agent-team-execution

Agent Team Execution

Execute implementation plans using collaborative agent teams. Lead routes coordination through SendMessage, specialists work in parallel on file-disjoint groups, a reviewer gates every task.

Prerequisite: A plan at docs/plans/*.md with discrete tasks (see writing-plans skill).

Mode Selection

digraph mode_selection {
    "Read plan" -> "Count file-disjoint groups";
    "Count file-disjoint groups" -> "< 3 groups?" [label="analyze"];
    "< 3 groups?" -> "subagent-driven-development" [label="yes"];
    "< 3 groups?" -> "Heavy file overlap?" [label="no"];
    "Heavy file overlap?" -> "subagent-driven-development\n(dependency ordering)" [label="yes"];
    "Heavy file overlap?" -> "agent-team-execution" [label="no"];
}

Roles

Role	Count	Owns	Prompt
Lead	1	shared-contracts.md, TaskList	./lead-prompt.md
Specialist	1-N	Assigned files only	./specialist-prompt.md
Reviewer	1	Nothing (read-only)	./reviewer-prompt.md

Shared Contracts

A single markdown file at workspace root. Specialists read it; only Lead writes it.

Contains: Data models/types, API signatures, environment config. Template: ./shared-contracts-template.md

Communication

All coordination via SendMessage. No file-based polling or locking. No structured JSON.

• Contract change: Specialist requests -> Lead updates file -> Lead notifies affected specialists
• Completion: Specialist submits to Reviewer -> Reviewer approves/rejects -> Lead marks done
• Cross-boundary: Specialist A requests -> Lead routes to Specialist B -> B confirms -> Lead notifies A
• Heartbeat: Specialist signals activity before heavy operations. Lead does not reply.
• Stall: Lead pings silent specialist. No response -> reassign.

Workflow

Phase 1: Setup (Lead)

1. Read plan, extract tasks with file lists
2. Group tasks into file-disjoint sets
3. Apply mode selection (< 3 groups -> fall back to subagent-driven-development)
4. Create shared-contracts.md from ./shared-contracts-template.md
5. TeamCreate("{feature-name}-impl")
6. Spawn specialists with synthesized Mini-Specs (see lead-prompt.md)
7. Spawn one reviewer
8. Create TaskList entries, assign to owning specialists

Phase 2: Execution

Specialists work in parallel per their prompts. Reviewer processes review requests as they arrive. Lead routes messages and maintains shared state.

Phase 3: Completion

1. All tasks approved by Reviewer
2. Run full test suite (verification-before-completion)
3. Integration review
4. shutdown_request to all agents
5. TeamDelete
6. Invoke finishing-a-development-branch

Deadlock Prevention

Condition	Detection	Resolution
Specialist stall	No messages or heartbeats	Lead pings: "Status check?"
Repeated rejection	Same task rejected 3 times	Lead intervenes directly
Cross-boundary blocked	Specialist waiting on another	Lead routes and follows up
Crashed specialist	No response to Lead ping	Lead reassigns task

Red Flags

• File-based locking -- assignment is the only ownership mechanism
• Polling files for status -- all status flows through SendMessage
• Specialists self-marking tasks complete -- only Lead marks complete after Reviewer approval
• Skipping the Reviewer -- every task must be reviewed
• Lead editing specialist-owned files -- Lead routes requests only
• Structured JSON messages -- plain text via SendMessage only

Example: Contract Evolution and Cross-Boundary Routing

A plan has 3 file-disjoint groups: model-specialist (Group A), service-specialist (Group B), routes-specialist (Group C).

[Parallel start]

model-specialist -> Lead:
  "Requesting contract update: Task type needs dueDate: Date | null."

Lead: [validates against plan, edits shared-contracts.md]
Lead -> service-specialist: "Contract updated: Task.dueDate added. Re-read contracts."
Lead -> routes-specialist: "Contract updated: Task.dueDate added. Re-read contracts."

routes-specialist -> Lead:
  "Need TaskService.listByPriority() but it doesn't exist in contracts.
   service-specialist owns src/services/task.ts."

Lead: [adds listByPriority signature to shared-contracts.md]
Lead -> service-specialist:
  "Contract updated: TaskService.listByPriority added.
   routes-specialist needs this method. Implement and confirm."

service-specialist -> Lead: "Done. listByPriority implemented and tested."
Lead -> routes-specialist: "Change made. Proceed."

Integration

Skill	Relationship
writing-plans	Creates the plan this skill executes
subagent-driven-development	Sequential fallback for < 3 tasks or coupled tasks
test-driven-development	Specialists follow TDD discipline
finishing-a-development-branch	Invoked by Lead after completion
verification-before-completion	Lead runs full test suite before finalizing