team-implement

Team Implement

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

Prerequisites & fallback chain: read this first

Full mode needs multi-agent teams. In Claude Code that requires:

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

With the flag set, full mode spawns named teammates via the Task tool with a team_name (the team itself is created implicitly by the first such call, there's no separate "create team" step), coordinates via SendMessage, and stops a teammate with TaskStop. The exact tool signatures depend on the environment you're running in: treat any call shown below as illustrative and use whatever the local Task/SendMessage/TaskStop equivalents actually are. Do not invent a Teammate tool or similar if nothing like it exists here.

No flag, or a Task ... team_name call fails? Fall back to Lite mode: identical phase structure, but roles run as sequential Task subagents (no team_name, no cross-agent messaging) instead of a coordinated team.

No Task/subagent tool at all? Fall back further still: run every phase's steps yourself, inline, sequentially. The phase → gate → phase structure below is the workflow: teams and subagents are just two ways to parallelize it.

Delegate mode (Claude Code, full mode): Shift+Tab restricts the lead to coordination-only tools. Without it, wait for teammates to finish before touching their files yourself.

Input

$ARGUMENTS

Known Limitations

• No session resumption: an interrupted session loses spawned teammates (full mode)
• One team per session; teammates cannot spawn their own sub-teams
• Teammates sometimes forget to mark tasks complete: poll TaskList rather than trusting silence
• Teammates load project CLAUDE.md/AGENTS.md automatically (a benefit, not a limitation)

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. Detection order (first match wins): full patterns and ingestion commands in references/spec-workflow.md Section 1:

Step 0.2: Project Discovery

Spawn an Explore/haiku agent (with no subagent tool, do this yourself):

Task tool (Explore, haiku):
"Discover the project's stack and workflow: read CLAUDE.md/AGENTS.md and README.md,
find task-runner commands (test/lint/build/dev), map major components, note
frameworks/DB/auth patterns and existing conventions. Return a structured summary."

Step 0.3: Assess Complexity

Score against the signals below (full algorithm in references/spec-workflow.md Section 2):

• Score 0–1: lite mode, automatic, for a <10-file single-component change, suggest implement-feature instead (no spec overhead needed)
• Score 2–3: ask the user, default recommendation lite
• Score 4+: full mode, automatic

Steps 0.4–0.6: Namespace, Initial Artifacts, Git Handling

1. Generate .specs/<short-id>/ (<slugified-title>-<YYYYMMDD>; algorithm in references/spec-workflow.md Section 3)
2. Write input-digest.md and a session README.md dashboard from references/spec-templates.md
3. Update .specs/README.md (global index, create it if this is the first session)
4. If .specs/ isn't already tracked or gitignored, ask via AskUserQuestion whether to commit it or ignore it, first time only

Step 0.7: Propose Team Composition

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

Full-mode team creation is implicit: the first Task call in Phase 2 that uses team_name: "team-<short-id>" creates the team. There is no separate spawn step.

Phase 1: Clarifying Questions

Scan the input digest for ambiguity: vague requirements, missing acceptance criteria, unclear scope, technology decisions, conflicting asks. Resolve with AskUserQuestion, multiple rounds if needed. Skip or shorten this phase for a well-defined source (e.g. a detailed Jira ticket with acceptance criteria already attached).

Phase 2: Specification

Full Mode

Spawn Product Lead (prompt in references/agent-catalog.md):

Task tool (team_name: "team-<short-id>", name: "product-lead"):
  subagent_type: general-purpose, model: sonnet
  prompt: [Product Lead prompt, substituting SPEC_ID and project context]

Writes .specs/<short-id>/proposal/{brief,requirements,acceptance-criteria}.md.

Gate: Spec Review, orchestrator checks coherence, asks the user about remaining gaps.

Lite Mode

Spawn Product Analyst via Task (no team), see agent-catalog.md. Writes combined brief.md + task breakdown.

Phase 3: Architecture & Design

Full Mode

Spawn Architect (opus, complex system design benefits from the stronger model):

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

Writes design/architecture.md, design/api-contracts.md, design/data-model.md, design/diagrams/system-overview.md, and lightweight ADRs under decisions/. Defer to the cc-arsenal:docs-adr skill for ADR format and conventions (via the Skill tool where available, otherwise follow its documented ADR templates) rather than reinventing one here.

Lite Mode

Combined Architect/Developer subagent writes design.md.

Phase 4: Adversarial Review

Full Mode

Spawn Adversary Reviewer. Reviews all spec + design artifacts, writes review/adversary-report.md, rates findings BLOCKER | WARNING | SUGGESTION.

If BLOCKERs: route findings to Architect (see references/communication-patterns.md Section 3) → Architect revises → Adversary re-reviews. Max 2 revision cycles, proceed even if warnings remain after that, to avoid an infinite loop.

Lite Mode

QA/Reviewer subagent challenges the design, writes review.md. Same BLOCKER routing and 2-cycle cap.

Phase 5: Task Decomposition

Full Mode

Product Lead (still active) writes tasks/task-breakdown.md and a Mermaid tasks/task-graph.md. Orchestrator creates TaskCreate entries with dependencies. Target 5–6 tasks per teammate: smaller wastes coordination overhead, larger risks wasted effort between check-ins.

For decomposition technique beyond what's here (estimation, dependency-graph patterns), defer to the cc-arsenal:project-planner skill (via the Skill tool where available, otherwise apply its documented decomposition steps) instead of reinventing it.

Lite Mode

Orchestrator writes tasks.md with breakdown + Mermaid graph, initializes tasks via TaskCreate.

USER APPROVAL GATE

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"

No code changes happen before this gate passes. "Save spec only" skips straight to Phase 9 teardown. "Request changes" jumps back to the relevant phase.

Phase 6: Implementation

Only after approval.

Full Mode

Spawn one Implementation Engineer per affected component, in parallel (e.g. frontend-engineer, backend-engineer, same prompt template, scoped by component; see agent-catalog.md):

Task tool (team_name: "team-<short-id>", name: "frontend-engineer"):
  subagent_type: general-purpose, model: sonnet
  prompt: [Implementation Engineer prompt, component: frontend]

Each engineer claims tasks from the board (TaskList → TaskUpdate), reads spec files (API contracts, data model), implements per the architecture, writes tests, marks tasks completed, reports to the orchestrator.

File scope enforcement: each engineer's handoff message states its file scope explicitly (see references/communication-patterns.md Section 5): this is what prevents two engineers editing the same files. Orchestrator commits incrementally after each engineer completes.

Lite Mode

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

Phase 7: Quality Assurance

Full Mode

Spawn QA Engineer: validates each acceptance criterion, runs the test suite, checks coverage against a number it actually measured (target >80%, not an assumed figure), writes review/qa-plan.md.

Conditional specialists, spawn only if the spec flags the need:

• Security Engineer: security-sensitive features (auth, payments, PII)
• Performance Engineer: explicit performance/SLA requirements
• Infrastructure/DevOps Engineer: deployment or infra changes

Adversary Reviewer does a second pass on the implementation.

Gate: Quality Verification, all tests pass, no BLOCKER findings. On failure: loop to Phase 6, max 3 retries (see references/spec-workflow.md Section 6).

Lite Mode

QA/Reviewer subagent runs tests, lint, checks acceptance criteria. On failure: loop to Phase 6.

Phase 8: Documentation & Delivery

Spawn Tech Writer (haiku) only if the feature is user-facing or changes an API, otherwise the orchestrator handles the minimal doc updates itself. Updates README.md, CHANGELOG.md, and API docs as applicable, plus .specs/<short-id>/README.md with final status.

Phase 9: Teardown

Full Mode

1. Send a courtesy completion message to any still-active teammate via SendMessage
2. Stop each teammate (TaskStop on name@team-<short-id>, or the local equivalent)
3. Update .specs/<short-id>/README.md with final status
4. Present summary to user

Lite Mode

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

Quality Gates Summary

Agent Roles Quick Reference

Full prompts and activation criteria: references/agent-catalog.md.

Wave-Based Agent Lifecycle (Full Mode)

Agents spawn per phase and shut down when done to bound cost. Details: references/spec-workflow.md Section 5.

Communication Patterns (Full Mode)

All inter-agent coordination goes through SendMessage (or its local equivalent). Templates: references/communication-patterns.md.

• Default to a direct message; broadcast only for critical team-wide issues
• Always include exact file paths in handoff messages
• State each engineer's file scope explicitly to prevent write conflicts
• Report status in plain text + TaskUpdate, never a JSON status blob

Spec Artifacts

Namespaced under .specs/<short-id>/. Templates: references/spec-templates.md.

Full Mode Structure

.specs/<short-id>/
├── README.md
├── input-digest.md
├── proposal/{brief,requirements,acceptance-criteria}.md
├── design/{architecture,api-contracts,data-model}.md
│   └── diagrams/system-overview.md
├── review/{adversary-report,security-assessment,qa-plan}.md
├── tasks/{task-breakdown,task-graph}.md
└── decisions/NNNN-*.md

Lite Mode Structure

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

Error Recovery

Recovery strategies for unresponsive teammates, repeated test failures, post-implementation BLOCKERs, interrupted sessions, circular task dependencies, and invalid agent output: references/spec-workflow.md Section 7.

Usage

/team-implement Add user authentication with OAuth2 and JWT
/team-implement #42
/team-implement owner/repo#42
/team-implement PROJ-123
/team-implement !456
/team-implement ./docs/requirements.md
/team-implement https://example.com/feature-spec
/team-implement ./src/auth/

References

• references/agent-catalog.md: role definitions and prompt templates
• references/spec-workflow.md: input detection, complexity matrix, phase transitions, quality gates, error recovery
• references/communication-patterns.md: coordination templates
• references/spec-templates.md: representative .specs/ artifact templates
• cc-arsenal:docs-adr: ADR format for decisions/
• cc-arsenal:project-planner: deeper task-decomposition technique for Phase 5