team-implement

Team Implement

Adaptive spec-driven development team that scales from 3 agents (lite) to 11 agents (full) based on project complexity. All planning completes before any code changes, with explicit user approval between planning and implementation.

Prerequisites

Full mode requires the experimental agent teams flag. Add to your environment or settings.json:

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Lite mode works without this flag (uses Task subagents instead of Teammate API).

Delegate mode (recommended for full mode): Press Shift+Tab to enable delegate mode, which restricts the lead to coordination-only tools and prevents it from implementing tasks itself. Without delegate mode, always wait for teammates to complete their tasks before proceeding — do not implement tasks yourself.

Input

$ARGUMENTS

Known Limitations

• No session resumption: /resume does not restore teammates. If a session is interrupted mid-team, teammates are lost
• One team per session: Cannot run multiple team-implement invocations simultaneously
• No nested teams: Teammates cannot spawn their own teams
• Task status can lag: Teammates sometimes forget to mark tasks complete; orchestrator should monitor
• Teammates load CLAUDE.md: Project-specific guidance applies automatically to all agents (this is a benefit)

Workflow Overview

MACRO PHASE A: PLANNING (no code changes)
  Phase 0: Input Ingestion & Discovery
  Phase 1: Clarifying Questions
  Phase 2: Specification
  Phase 3: Architecture & Design
  Phase 4: Adversarial Review
  Phase 5: Task Decomposition

  ══════════════════════════════════════
  USER APPROVAL GATE
  ══════════════════════════════════════

MACRO PHASE B: IMPLEMENTATION (code changes)
  Phase 6: Implementation
  Phase 7: Quality Assurance
  Phase 8: Documentation & Delivery
  Phase 9: Teardown

---

Phase 0: Input Ingestion & Discovery

Step 0.1: Detect Input Source

Parse $ARGUMENTS to determine the input type. For detection patterns and ingestion commands, see references/spec-workflow.md Section 1.

Detection order (first match wins):

Pattern	Source Type	Ingestion
PROJ-123	Jira ticket	jira issue view PROJ-123 --json
#42 or owner/repo#42	GitHub issue	gh issue view 42 --json title,body,labels,comments
!123 or PR URL	GitHub PR	gh pr view 123 --json title,body,files,comments,labels
Existing file path	File	Read file content
Existing directory path	Directory	Read README.md, CLAUDE.md, key files
http:// or https://	URL	WebFetch to extract content
Everything else	Plain text	Use directly as requirements

Step 0.2: Project Discovery

Spawn an Explore/haiku agent to understand the project:

Task tool (Explore, haiku):
"Discover the project's technology stack and development workflow:
  1. Read CLAUDE.md and README.md for project context
  2. Check for task runners: Makefile, package.json, pyproject.toml
  3. Identify test, lint, build, dev server commands
  4. Map major components and modules
  5. Note frameworks, databases, authentication patterns
  6. Find existing patterns and conventions
  Return: structured summary of project architecture and available commands."

Step 0.3: Assess Complexity

Evaluate complexity signals to determine team mode. See references/spec-workflow.md Section 2 for the full scoring matrix.

Signal	+2 (Full)	+1 (Medium)	0 (Lite)
Components affected	3+ (frontend + backend + DB + infra)	2 components	Single component
Security sensitivity	Auth, payments, PII	Permission checks	No sensitive data
Performance requirements	Real-time, SLAs	Caching, optimization	Standard CRUD
External integrations	2+ APIs/services	1 external API	Self-contained
Estimated file changes	15+ files	10-14 files	<10 files
Domain familiarity	Unfamiliar tech	Partially familiar	Well-understood

Thresholds:

• Score 0-1: Use lite mode automatically
• Score 2-3: Ask user (recommend lite)
• Score 4+: Use full mode automatically

Step 0.4: Generate Spec Namespace

Create .specs/<short-id>/ directory. Format: <slugified-title>-<YYYYMMDD> (e.g., auth-oauth2-20260205). See references/spec-workflow.md Section 3 for the generation algorithm.

Step 0.5: Create Initial Artifacts

1. Create .specs/<short-id>/ directory
2. Write .specs/<short-id>/input-digest.md using template from references/spec-templates.md
3. Write .specs/<short-id>/README.md (session dashboard)
4. Update .specs/README.md (global index) — create if first spec session

Step 0.6: Git Handling (first time only)

If .specs/ does not already exist in git or .gitignore, ask the user:

AskUserQuestion:
  question: "How should .specs/ be handled in git?"
  options:
    - "Commit to git (specs are part of the project)"
    - "Add to .gitignore (specs are local-only)"

Step 0.7: Propose Team Composition

Present the mode decision and team composition to the user for confirmation:

AskUserQuestion:
  question: "Complexity assessment complete. Proceed with this team?"
  options:
    - "[MODE] mode with [ROLES] (Recommended)"
    - "Switch to [OTHER_MODE] mode"
    - "Customize team composition"

Full mode team spawn:

Teammate({ operation: "spawnTeam", team_name: "team-<short-id>" })

---

Phase 1: Clarifying Questions

CRITICAL: Before any planning begins, analyze the input digest for ambiguities.

Look for:

• Vague requirements ("should support authentication" — which kind?)
• Missing acceptance criteria
• Unclear scope boundaries (what's in/out)
• Technology decisions needing user input
• Conflicting requirements

Use AskUserQuestion to resolve ambiguities. Multiple rounds are fine. Only proceed when requirements are clear enough to specify.

If the input is already well-defined (e.g., detailed Jira ticket with acceptance criteria), this phase can be brief or skipped.

---

Phase 2: Specification

Full Mode

Spawn Product Manager and Scrum Master (Wave 1). See references/agent-catalog.md for complete prompt templates.

Task tool (team_name: "team-<short-id>", name: "product-manager"):
  subagent_type: general-purpose
  model: sonnet
  prompt: [Product Manager prompt from agent-catalog.md, substituting SPEC_ID and project context]

Product Manager writes:

• .specs/<short-id>/proposal/brief.md
• .specs/<short-id>/proposal/requirements.md
• .specs/<short-id>/proposal/acceptance-criteria.md

Scrum Master reviews for completeness.

Gate: Spec Review — Orchestrator validates coherence, asks user about remaining gaps.

Lite Mode

Spawn Product Analyst subagent (via Task, not Teammate). See references/agent-catalog.md Combined Agent 12.

Product Analyst writes:

• .specs/<short-id>/brief.md
• .specs/<short-id>/design.md (combined)

---

Phase 3: Architecture & Design

Full Mode

Spawn Architect (Wave 2, opus model). See references/agent-catalog.md Agent 3.

Task tool (team_name: "team-<short-id>", name: "architect"):
  subagent_type: general-purpose
  model: sonnet
  prompt: [Architect prompt from agent-catalog.md]

Architect writes:

• .specs/<short-id>/design/architecture.md
• .specs/<short-id>/design/api-contracts.md
• .specs/<short-id>/design/data-model.md
• .specs/<short-id>/design/diagrams/system-overview.md
• .specs/<short-id>/decisions/NNNN-*.md (lightweight ADRs)

Lite Mode

Architect/Developer subagent writes .specs/<short-id>/design.md (combined). See references/agent-catalog.md Combined Agent 13.

---

Phase 4: Adversarial Review

Full Mode

Spawn Adversary Reviewer (Wave 3). See references/agent-catalog.md Agent 11.

Adversary reviews ALL spec + design artifacts and writes:

• .specs/<short-id>/review/adversary-report.md

Findings rated as: BLOCKER | WARNING | SUGGESTION

If BLOCKERs found:

1. Route findings back to Architect via orchestrator (see references/communication-patterns.md Section 3)
2. Architect revises design
3. Adversary re-reviews
4. Maximum 2 revision cycles — after that, approve even if warnings remain

Lite Mode

QA/Reviewer subagent challenges design and writes .specs/<short-id>/review.md. If BLOCKERs: orchestrator feeds back, spawns revision subagent.

---

Phase 5: Task Decomposition

Full Mode

Scrum Master (from Wave 1, still active) creates:

• .specs/<short-id>/tasks/task-breakdown.md
• .specs/<short-id>/tasks/task-graph.md (Mermaid dependency graph)

Orchestrator creates TaskCreate entries with dependencies via the Task Management System. Target 5-6 tasks per teammate — too small wastes coordination overhead, too large risks wasted effort without check-ins.

Lite Mode

Orchestrator creates .specs/<short-id>/tasks.md with breakdown and Mermaid graph, then initializes tasks via TaskCreate.

---

USER APPROVAL GATE

Present the complete plan to the user via AskUserQuestion:

AskUserQuestion:
  question: "Planning complete for [TITLE]. Specs at .specs/<short-id>/. [N] requirements, [M] tasks, [K] parallelizable. Ready to proceed?"
  options:
    - "Approve and begin implementation"
    - "Request changes (I'll describe what to modify)"
    - "Save spec only — do not implement"
    - "Cancel"

Option 3 (spec-only): Users may want just the planning artifacts without code changes. Skip to Phase 9 (teardown).

If changes requested: Jump back to the relevant phase (spec, architecture, or tasks) based on user feedback.

---

Phase 6: Implementation

Only after user approval.

Full Mode

Spawn implementation agents in parallel (Wave 5). See references/agent-catalog.md Agents 4-5.

# Spawn in parallel
Task tool (team_name: "team-<short-id>", name: "frontend-dev"):
  subagent_type: general-purpose, model: sonnet
  prompt: [Frontend Developer prompt from agent-catalog.md]

Task tool (team_name: "team-<short-id>", name: "backend-dev"):
  subagent_type: general-purpose, model: sonnet
  prompt: [Backend Developer prompt from agent-catalog.md]

Each agent:

1. Claims tasks from the shared task board (TaskList → TaskUpdate)
2. Reads spec files for guidance (API contracts, data model)
3. Implements following architecture
4. Writes tests
5. Marks tasks completed (TaskUpdate)
6. Sends completion message to orchestrator

File scope enforcement: Frontend and backend agents have strict boundaries. See references/communication-patterns.md Section 5 for conflict prevention.

Orchestrator commits incrementally after each agent completes.

Lite Mode

Architect/Developer subagent implements sequentially per spec. Writes tests, runs quality checks.

---

Phase 7: Quality Assurance

Full Mode

Spawn QA Engineer (Wave 6) + optional specialized agents. See references/agent-catalog.md Agent 6.

QA Engineer:

1. Validates each acceptance criterion
2. Runs test suite
3. Checks code coverage (target: >80%)
4. Writes .specs/<short-id>/review/qa-plan.md

Optional agents (spawn based on spec):

• Security Engineer (Agent 7): If security-sensitive features
• Performance Engineer (Agent 8): If performance requirements
• Infrastructure/DevOps (Agent 9): If deployment changes

Adversary Reviewer (2nd pass) challenges the implementation.

Gate: Quality Verification — All tests pass, no critical findings. If failures: loop to Phase 6 (max 3 retries). See references/spec-workflow.md Section 6.

Lite Mode

QA/Reviewer subagent validates: run tests, lint, check acceptance criteria. If failures: loop to Phase 6.

---

Phase 8: Documentation & Delivery

Full Mode

Spawn Tech Writer (Wave 7, haiku model). See references/agent-catalog.md Agent 10.

Tech Writer updates:

• README.md (if feature-facing)
• CHANGELOG.md
• API documentation (if API changes)
• .specs/<short-id>/README.md (final status)

Lite Mode

Orchestrator handles minimal doc updates.

---

Phase 9: Teardown

Full Mode

1. Send shutdown_request to all remaining agents (see references/communication-patterns.md Section 6)
2. Wait for shutdown_response from each
3. Run Teammate({ operation: "cleanup" })
4. Update .specs/<short-id>/README.md with final status
5. Present summary to user

Lite Mode

1. Update .specs/<short-id>/README.md with final status
2. Present summary to user

---

Quality Gates Summary

Gate	Between Phases	Pass Criteria	On Failure	Max Retries
Clarifying Questions	0 → 2	All ambiguities resolved	More questions	Unlimited
Spec Review	2 → 3	Requirements complete, criteria clear	Revise specs	2
Adversarial Review	3 → 5	Zero BLOCKER findings	Architect revises	2
User Approval	5 → 6	User approves full plan	Revise or cancel	Unlimited
Quality Verification	6 → 8	Tests pass, no critical findings	Loop to Phase 6	3
Final Delivery	8 → done	Spec artifacts exist, all tasks done	Block completion	1

Agent Roles Quick Reference

For complete prompt templates and activation criteria, see references/agent-catalog.md.

Role	Model	Phase	Full Mode	Lite Mode
Product Manager	sonnet	2	Dedicated	Combined as Product Analyst
Scrum Master	sonnet	2, 5	Dedicated	Combined as Product Analyst
Architect	sonnet	3	Dedicated	Combined as Architect/Developer
Frontend Developer	sonnet	6	Dedicated	Combined as Architect/Developer
Backend Developer	sonnet	6	Dedicated	Combined as Architect/Developer
QA Engineer	sonnet	7	Dedicated	Combined as QA/Reviewer
Security Engineer	sonnet	7	Conditional	Combined as QA/Reviewer
Performance Engineer	sonnet	7	Conditional	—
Infrastructure/DevOps	sonnet	7	Conditional	—
Tech Writer	sonnet	8	Dedicated	—
Adversary Reviewer	sonnet	4, 7	Dedicated	Combined as QA/Reviewer

Wave-Based Agent Lifecycle (Full Mode)

Agents spawn per phase and shut down when done to minimize cost:

Wave	Phases	Agents	Shutdown After
1	1-2, 5	Product Manager, Scrum Master	Phase 5
2	3	Architect	Phase 3
3	4	Adversary Reviewer	Phase 4
5	6	Frontend Dev, Backend Dev (conditional)	Phase 6
6	7	QA Engineer + optional Security/Perf/Infra	Phase 7
7	8	Tech Writer	Phase 8

See references/spec-workflow.md Section 5 for details.

Communication Patterns (Full Mode)

All inter-agent communication uses SendMessage. See references/communication-patterns.md for templates covering:

1. Phase handoff messages (orchestrator → next agent)
2. Adversarial review routing (findings → architect → re-review)
3. Blocker escalation (agent → orchestrator → user)
4. Parallel coordination (frontend + backend contract sharing)
5. Shutdown sequences

Key rules:

• Default to type: "message" (direct). Only use type: "broadcast" for critical team-wide issues.
• Always include exact file paths in handoff messages
• Enforce file scope boundaries for implementation agents
• Never send JSON status messages — use plain text + TaskUpdate

Spec Artifacts

All artifacts are namespaced under .specs/<short-id>/. See references/spec-templates.md for all templates.

Full Mode Structure

.specs/<short-id>/
├── README.md                    # Session dashboard
├── input-digest.md              # Normalized input
├── proposal/
│   ├── brief.md
│   ├── requirements.md
│   └── acceptance-criteria.md
├── design/
│   ├── architecture.md
│   ├── api-contracts.md
│   ├── data-model.md
│   └── diagrams/
│       └── system-overview.md
├── review/
│   ├── adversary-report.md
│   ├── security-assessment.md
│   └── qa-plan.md
├── tasks/
│   ├── task-breakdown.md
│   └── task-graph.md
└── decisions/
    └── 0001-decision-title.md

Lite Mode Structure

.specs/<short-id>/
├── README.md
├── input-digest.md
├── brief.md
├── design.md
├── review.md
└── tasks.md

Error Recovery

See references/spec-workflow.md Section 7 for recovery strategies covering:

• Teammate fails to respond (re-send → re-spawn → subagent fallback)
• Tests fail repeatedly (detailed feedback → code review → user escalation)
• Critical issue found post-implementation (hotfix task or architecture revision)
• Session interrupted (check for existing .specs/, offer resume)
• Circular task dependencies (detect via DFS, request revision)
• Invalid agent output (validation error → retry → subagent fallback)

Usage

# Plain text description
/team-implement Add user authentication with OAuth2 and JWT

# GitHub issue
/team-implement #42
/team-implement owner/repo#42

# Jira ticket
/team-implement PROJ-123

# GitHub PR (spec for changes needed)
/team-implement !456

# File with requirements
/team-implement ./docs/requirements.md

# URL with spec
/team-implement https://example.com/feature-spec

# Directory to analyze
/team-implement ./src/auth/

References

• references/agent-catalog.md — All 11 agent role definitions with complete prompt templates
• references/spec-workflow.md — Input detection, complexity matrix, phase transitions, quality gates
• references/communication-patterns.md — SendMessage templates for team coordination
• references/spec-templates.md — File templates for all .specs/ artifacts