Agent Teams and Task Graphs

When a team is the right abstraction

A team adds coordination state. The lead manages registered teammates and a shared task list; each teammate runs as a separate headless process with its own agent definition, model context, and tool boundary.

Situation	Use	Reason
Four independent reviews that return once	`delegate_parallel`	No persistent status or dependencies are needed
Several compatible workers processing a dependency graph	Agent Team	Later tasks remain blocked until prerequisites complete
Exact specialist must receive exact work	`delegate_task` or `delegate_parallel`	Team tasks do not select an agent; the first idle teammate claims the next available task
One specialist question	`delegate_task`	A persistent teammate would add coordination overhead

Lead-managed architecture

Lead process: owns the user goal, creates the team, launches teammates, creates tasks, routes messages, and verifies the integrated result.
Teammate process: starts in teammate mode using a registered agent definition and receives assignments over JSON-RPC on standard I/O.
Task manager: stores pending, in-progress, and completed tasks with optional blocked_by task IDs.
Auto-assignment: the first idle teammate receives the first pending task whose dependencies are complete. create_task has no owner or agent selector.
Message routing: teammates do not form an uncontrolled peer network; the lead routes task messages and direct follow-ups.
Recovery: if a teammate exits, its in-progress work can return to pending so another worker can take it.

Know the current runtime boundary

One active team: creating a differently named team shuts down the old team before creating the replacement.
In-memory coordination: team membership and tasks live in the lead process. Shut down the team before ending the session and do not treat it as a durable queue.
Headless children: every teammate is a separate Autohand process connected to the lead over JSON-RPC on standard input and output.
Shared workspace: teammate processes run against the same workspace path. The runtime does not create one worktree per teammate.
Persistent definitions: teammate children reload user, configured external, and bundled definitions. Prefer file-based definitions for team members; inline --agents definitions belong only to the lead session.
Tool approval: teammate mode auto-confirms its local tool prompts. The agent definition's narrow tool allowlist is the main safety boundary.

Start from a clean branch or dedicated worktree. Use read-only definitions whenever possible. For write-capable teammates, grant only the required tools and ensure every available task is safe for every idle teammate that could claim it.

Create a team from an outcome

/team create <name> creates an empty team. A natural-language instruction can ask the lead to create or reuse a team, profile the project, list available definitions, launch teammates, and create dependency-aware tasks. It does not create a project-derived plan automatically.

First use direct, read-only delegation to map the authorization gaps and decide
the exact regression cases. Then create a team named auth-regression-tests with
two teammates that both use the registered tester definition.

Outcome: add the agreed authorization regression tests without changing
production code or public request and response contracts.

Create independent tasks for these disjoint files:
- tests/auth/projects.test.ts
- tests/auth/organizations.test.ts

Create a final verification task blocked by both file tasks. Either teammate may
claim either file task, so put the complete case list, mutation boundary, command,
and expected evidence in each description. The lead reviews the combined diff and
runs the focused auth suite before reporting completion.

If a catalog role is missing, ask the lead to show the exact catalog result and wait for installation approval before adding that teammate.

Understand the coordination tools

The lead calls these model-facing tools. They are documented so you can specify the workflow precisely; you normally do not type them directly.

Tool	Contract	Operational note
`create_team`	Create or reuse a named team, profile the project, and list available definitions	It does not add teammates or tasks; call those tools next
`add_teammate`	Launch a named teammate from a registered `agent_name`; optional model override	The agent definition controls tools and behavior
`create_task`	Create a subject and detailed description with optional `blocked_by` IDs	There is no agent selector; the first idle teammate claims the first available task
`task_get` / `task_list`	Inspect one task or filter the queue by status or owner	Use this before declaring the team stuck
`task_update`	Change task details, dependencies, or status	Update the graph when evidence changes the plan
`task_stop`	Stop active or queued work and return it to pending	Use before reassigning overlapping or misguided work
`task_output`	Store the latest progress note or result against a task	Preserve evidence, commands, and artifact paths
`team_status`	Return teammates, states, and task progress	Status is coordination data, not validation proof
`send_team_message`	Send a correction or question from the lead to one teammate	Do not silently change another worker's ownership

Design a task graph

Dependencies should encode information flow, not only chronology. A task is available when it is pending and every ID in blocked_by is complete.

task-1  Add project authorization regression cases       [any tester teammate]
task-2  Add organization authorization regression cases  [any tester teammate]
task-3  Run focused suite and summarize failures          [any tester teammate]
         blocked_by: task-1, task-2
task-4  Review combined diff and repository checks        [lead]
         blocked_by: task-3

Keep tasks large enough to produce a coherent artifact and small enough to have one owner. “Fix authentication” is too broad; “add regression tests for cross-tenant project reads in tests/auth/projects.test.ts” is assignable and verifiable. If only one named specialist can do a task, use direct delegation or stage a separate homogeneous team for that phase.

Prevent write collisions

Give every write-capable teammate an exclusive directory or explicit file list.
Make design, research, and review agents read-only where possible.
Use dependency edges when two roles must touch the same surface at different phases.
Create isolated worktrees outside the team runtime when parallel branches are intentional, then run a separate Autohand session in each worktree.
Stop and re-plan a task as soon as its scope crosses another owner's boundary.

Shared working directory means shared risk. A team task queue prevents duplicate assignment, but it does not isolate files, route tasks by specialist, or make concurrent edits merge cleanly. File ownership and tool access are part of every task contract.

Monitor and control the team

# Summarize team, teammates, and task progress
/team status

# Show task IDs, owners, dependencies, and state
/tasks

# Correct or extend one teammate's assignment
/message tester-a Do not touch production code; add the failing command and output to the task result.

# Gracefully stop all teammate processes after integration
/team shutdown

A teammate that reports completion should include changed files, commands run, results, open risks, and any assumptions the lead must verify. If a task fails or the teammate exits, inspect its latest output before returning the task to pending or assigning it elsewhere.

Use phase gates for risky work

For migrations, security changes, or cross-service work, use several small teams or shut down and re-form the team between phases:

Discovery gate: repository map, current contracts, risks, and proposed ownership are reviewed by the lead.
Test gate: failures reproduce the problem and baseline validation is recorded.
Implementation gate: one owner per surface, focused checks green, and no unauthorized contract drift.
Integration gate: the lead reviews the combined diff and runs repository-level build, lint, type, and test commands.
Release gate: documentation, migration notes, rollout, rollback, and monitoring are complete.

Define team completion

A team is complete only when the integrated workspace satisfies the user-facing acceptance criteria. Require:

all required tasks completed and no dependency left unresolved;
every worker's output inspected, with contradictory assumptions resolved;
the combined diff reviewed for cross-task regressions;
focused and repository-level validation commands recorded with results;
temporary teammates shut down and their artifacts either retained intentionally or cleaned up safely.

See the broader Agent Teams reference for hooks and additional operational examples.