Imported from tae2089/agent-team (skills/agent-team-shared/SKILL.md). Install upstream with npx skills add tae2089/agent-team --skill agent-team-shared. Copyright stays with the author.

Agent Team Shared Runtime

Use agent-team for daemonless coordination between orchestrators and workers. The CLI stores state only; it does not run agents, watch files, or require a background daemon.

Installation

agent-team must be available on $PATH.

agent-team --help

Initialize state once per project or custom state directory:

agent-team init

State

Default state: .agent-team/agent-team.db
Override state directory: AGENT_TEAM_STATE_DIR=/path/to/state
Artifact convention: _workspace/{run_id}/
SQLite is the source of truth for runs, tasks, messages, inbox, sync status, and event history.
Do not use direct peer-to-peer agent communication. Send compact messages with agent-team message send; recipients check inboxes at checkpoints.

CLI Syntax

agent-team <resource> <command> [flags]

Examples:

agent-team run create --title "docs refactor"
agent-team task create --run run_docs --agent writer --title "draft docs"
agent-team inbox list --agent writer --run run_docs --unread
agent-team task complete --task task_docs --agent writer --evidence "Verified locally." --artifact "_workspace/run_docs/task_docs.md"

Global Flags

Flag	Default	Description
`--params`	`{}`	Strict JSON command arguments. Accepts inline JSON, `@file.json`, or `-` for stdin.
`--json`	`{}`	Strict JSON payload. Use for richer content such as task bodies, metadata, evidence, artifact paths, message body, and reasons.

Unknown JSON fields are rejected. If a value is supplied by both a named flag and JSON, the CLI returns input_conflict.

Shell Tips

Boolean flags are presence-based in shell usage: use --unread or --force.
Use JSON for explicit false values: --params '{"force":false}'.
Quote JSON with single quotes in POSIX shells.
Use @file.json for large JSON objects.
Use - to read a JSON object from stdin.
Do not pass positional arguments; use flags, --params, or --json.

Common Aliases

Flag	JSON key	Meaning
`--run`	`run_id`	Workflow scope.
`--task`	`task_id`	Task scope.
`--msg`	`msg_id`	Inbox message scope.
`--agent`	`agent`	Logical agent name.
`--id`	`id`	Optional caller-provided stable identifier.

Common Value Semantics

Value	Meaning
`metadata`	JSON object for compact machine-readable context. Put large content in artifacts.
`body`	Human-readable task or message content.
`reason`	Operational explanation persisted in state or event payloads.
`evidence`	Completion proof in text. State what was checked, changed, or verified.
`artifact`	Path to produced work, normally under `_workspace/{run_id}/`.

JSON Output

Success:

{ "ok": true, "state_version": 12, "data": {}, "warnings": [] }

Failure:

{
  "ok": false,
  "state_version": 12,
  "error": {
    "code": "sync_conflict",
    "message": "...",
    "details": {},
    "recovery": {
      "summary": "...",
      "actions": [],
      "commands": [],
      "docs": [],
      "skills": []
    }
  }
}

Agents should branch on ok and error.code. Use error.recovery for operator-facing next steps and related helper skills. Human-readable messages are not stable interfaces.

Error Codes

Code	Meaning	Typical action
`validation_error`	Required or invalid input.	Fix flags or JSON.
`input_conflict`	Same field supplied by flag and JSON.	Provide the value once.
`invalid_json`	JSON payload is malformed or has unknown fields.	Fix JSON shape.
`invalid_json_source`	`@file` or stdin JSON source is invalid.	Fix the source argument.
`not_found`	Run, task, or message does not exist.	Check IDs.
`agent_mismatch`	Agent does not own the task/message.	Reassign or use the correct agent.
`sync_conflict`	Unread messages or incomplete dependencies.	Run sync check, resolve, retry.
`run_not_ready`	Run has unfinished tasks.	Finish or terminally resolve tasks before closing.
`invalid_run_state`	Run status does not allow operation.	Inspect run status.
`invalid_task_state`	Task status does not allow operation.	Inspect task and choose an allowed transition.
`internal_error`	Local filesystem, SQLite, state, install, or sandbox failure.	Check state dir permissions, run init, or inspect install/sandbox docs.

Full recovery guidance lives in docs/errors.md. agent-team schema export exposes the same error_recovery catalog for agents and CI drift checks.

Skill Routing

Need	Load
Run lifecycle	`agent-team-run`
Task lifecycle	`agent-team-task`
Messages and inbox	`agent-team-inbox`
Drift checks before completion	`agent-team-sync`
Audit, logs, schema, operational cleanup	`agent-team-ops`

Use agent-team schema export to inspect the current machine-readable command contract.

agent-team-shared

About