git:20260719.4ee8666 to git:20260727.fa2e9cf

35 added, 35 removed. Audit A to A.

---

name: team-implement

- description: "Spec-driven team orchestration for large, multi-component features or new epics: writes a full spec/design/review artifact trail under .specs/, gates code changes behind an explicit user approval, then scales a team from 3 (lite) to roughly 9 (full) agents based on complexity. Use for sizable features spanning frontend+backend+DB, unfamiliar domains, or anything you want a reviewable spec for before code is touched. Not for small/single-component changes (use implement-feature — no spec overhead) and not for reviewing already-written code (use team-review)."

+ description: "Spec-driven team orchestration for large, multi-component features or new epics: writes a full spec/design/review artifact trail under .specs/, gates code changes behind an explicit user approval, then scales a team from 3 (lite) to roughly 9 (full) agents based on complexity. Use for sizable features spanning frontend+backend+DB, unfamiliar domains, or anything you want a reviewable spec for before code is touched. Not for small/single-component changes (use implement-feature, no spec overhead) and not for reviewing already-written code (use team-review)."

disable-model-invocation: true

allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Task, SendMessage, TaskStop, TaskCreate, TaskUpdate, TaskList, TaskGet, WebFetch, AskUserQuestion

context: fork

agent: general-purpose

---

# 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

+ ## 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.

+ 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.

+ **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)

+ - 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 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](references/spec-workflow.md) Section 1:

+ Parse `$ARGUMENTS`. Detection order (first match wins): full patterns and ingestion commands in [references/spec-workflow.md](references/spec-workflow.md) Section 1:

| Pattern | Source | Ingestion |

|---------|--------|-----------|

| `PROJ-123` | Jira | `jira issue view PROJ-123 --json` |

| `#42` / `owner/repo#42` | GitHub issue | `gh issue view 42 --json title,body,labels,comments` |

| `!123` / PR URL | GitHub PR | `gh pr view 123 --json title,body,files,comments,labels` |

| Existing file path | File | Read it |

| Existing directory path | Directory | Read README.md, CLAUDE.md/AGENTS.md, key files |

| `http(s)://` | URL | WebFetch |

| Everything else | Plain text | Use directly as requirements |

### 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](references/spec-workflow.md) Section 2):

| Signal | +2 | +1 | 0 |

|--------|----|----|---|

| Estimated file changes | 15+ | 10–14 | <10 |

- - **Score 0–1**: lite mode, automatic — for a <10-file single-component change, suggest `implement-feature` instead (no spec overhead needed)

+ - **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](references/spec-workflow.md) Section 3)

2. Write `input-digest.md` and a session `README.md` dashboard from [references/spec-templates.md](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

+ 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.

+ 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).

+ 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](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.

+ **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.

+ 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):

+ 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](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.

+ If BLOCKERs: route findings to Architect (see [references/communication-patterns.md](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.

+ **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):

+ 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](references/communication-patterns.md) Section 5) — this is what prevents two engineers editing the same files. Orchestrator commits incrementally after each engineer completes.

+ **File scope enforcement**: each engineer's handoff message states its file scope explicitly (see [references/communication-patterns.md](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

+ 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](references/spec-workflow.md) Section 6).

+ **Gate: Quality Verification**, all tests pass, no BLOCKER findings. On failure: loop to Phase 6, max 3 retries (see [references/spec-workflow.md](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.

+ 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](references/agent-catalog.md).

|------|-------|-------|-----------|-----------|

- | Performance Engineer | sonnet | 7 | Conditional | — |

- | Infrastructure/DevOps Engineer | sonnet | 7 | Conditional | — |

- | Tech Writer | haiku | 8 | Conditional | — |

+ | Performance Engineer | sonnet | 7 | Conditional | - |

+ | Infrastructure/DevOps Engineer | sonnet | 7 | Conditional | - |

+ | Tech Writer | haiku | 8 | Conditional | - |

## Wave-Based Agent Lifecycle (Full Mode)

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

|------|--------|--------|-----------------|

| 1 | 2, 5 | Product Lead | Phase 5 |

| 2 | 3 | Architect | Phase 3 |

| 3 | 4 | Adversary Reviewer | Phase 4 |

| 4 | 6 | Implementation Engineer(s), parallel | Phase 6 |

| 5 | 7 | QA Engineer + conditional Security/Performance/Infra + Adversary (2nd pass) | Phase 7 |

| 6 | 8 | Tech Writer (if spawned) | Phase 8 |

## Communication Patterns (Full Mode)

All inter-agent coordination goes through `SendMessage` (or its local equivalent). Templates: [references/communication-patterns.md](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

+ - Report status in plain text + `TaskUpdate`, never a JSON status blob

## Spec Artifacts

Namespaced under `.specs/<short-id>/`. Templates: [references/spec-templates.md](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](references/spec-workflow.md) Section 7.

## Usage

```bash

/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](references/agent-catalog.md) — role definitions and prompt templates

- - [references/spec-workflow.md](references/spec-workflow.md) — input detection, complexity matrix, phase transitions, quality gates, error recovery

- - [references/communication-patterns.md](references/communication-patterns.md) — coordination templates

- - [references/spec-templates.md](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

+ - [references/agent-catalog.md](references/agent-catalog.md): role definitions and prompt templates

+ - [references/spec-workflow.md](references/spec-workflow.md): input detection, complexity matrix, phase transitions, quality gates, error recovery

+ - [references/communication-patterns.md](references/communication-patterns.md): coordination templates

+ - [references/spec-templates.md](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