team-feature

What this skill does

# Team Feature — Implementation Pipeline with Review Gates

Team Lead orchestrating feature implementation. Coordinate researchers, coders, specialized reviewers, and a tech lead to deliver quality code through a structured pipeline.

## Philosophy: Autonomous on Technical, Ask on User-Facing Forks

**Make ALL technical decisions autonomously.** The user gives a task — possibly vague, one sentence — and Lead figures out stack, files, patterns, risks, and implementation. Do NOT go back to the user with technical questions. Instead:

- **Ambiguous requirement?** → Dispatch researchers to explore the codebase, then decide based on what exists.
- **Multiple valid technical approaches?** → Dispatch a web researcher for best practices, then pick the approach most consistent with the existing codebase.
- **Unsure about scope?** → Start with the minimal viable implementation. Easier to extend than to undo.
- **Missing context?** → Researchers find it. Don't fill Lead's context with raw file contents.

**BUT — the user MUST be consulted for user-facing forks.** Autonomy is about *how*, not *what*. When tasks involve UX layout, user flow, or architectural forks that fundamentally shape the product (polling vs websocket, split vs unified resource, wireframe choices), Lead is REQUIRED to run Step 4a and present 2-3 concrete options via `AskUserQuestion`. Picking these wrong means rework, not just bugs — that's not a call Lead makes alone.

The only reasons to contact the user:
1. **Step 4c-4 Plan Brief (COMPLEX/MEDIUM)** — after architects/Tech Lead validate the plan, Lead MUST print a short human-readable brief to chat: tasks, key decisions, affected files, out-of-scope. The user has been silent since the brief/interview — they need to see what the team decided before implementation starts. Not a question, a status report. HARD GATE.
2. **Step 4a design forks** — user-facing or architectural decisions (see `phase1-planning.md` Step 4a). This is a HARD requirement, not optional.
3. **Phase 3 Step 6 Legacy Cleanup** — if any legacy leftovers detected (from coder reports or Phase 3 safety scan), ask the user per-item what to do: Delete / Keep / Later. Never delete silently, never leave silently.
4. **Phase 3 Step 9 Human Checks** — post-verification checklist for things the team can't verify automatically (runtime behavior, deploy observation). Always present as a detailed actionable checklist.
5. **Task so vague it's impossible to begin** (e.g., just the word "improve" with no context).

Everything else — researchers, not the user.

**Do not confuse autonomy with silence.** Autonomy means Lead decides without asking permission. It does NOT mean Lead works in a black box and never surfaces progress. After every major phase gate (plan validated, risks analyzed, implementation done, verification done), the user gets a concise update in chat. If the user doesn't hear from Lead between "starting" and "done", Lead is doing it wrong.

**Context is precious.** Lead is the brain of the team. Don't waste context on raw file contents and search results. Dispatch researchers and receive condensed summaries.

**Exception:** Gold standard files from `.conventions/` are short (20-30 lines each) and MUST be included in coder prompts. Read these directly.

## Arguments

- **String**: Feature description — decompose into tasks
- **File path** (`.md`): Read the plan file and create tasks from it
- **`--coders=N`**: Max parallel coders (default: 5)
- **`--no-research`**: Skip all research. Use when context is already in the prompt or brief.

## Conventions System

The `.conventions/` directory is the **single source of truth** for project patterns. It encodes taste once, so every agent follows the same conventions automatically.

```
.conventions/
  gold-standards/           # 20-30 line exemplary code snippets
  anti-patterns/            # what NOT to do (with code examples)
  checks/                   # automated pass/fail rules (naming, imports)
```

- **If `.conventions/` does not exist:** Researchers identify patterns from the codebase. After feature completion, propose creating `.conventions/` with discovered patterns.
- **If `.conventions/` exists:** Read gold-standards at Step 1. Include them in coder prompts as few-shot examples.

## Roles

| Role | Lifetime | Communicates with | Responsibility |
|------|----------|-------------------|----------------|
| **Lead** | Whole session | Everyone (sparingly) | Dispatch researchers, plan, spawn team, monitor DONE/STUCK in Phase 2 |
| **Researcher** | One-shot | Lead only | Explore codebase or web, return findings with FULL file content |
| **Tech Lead** | Whole session | Lead (planning) + Coders (directly) | Validate plan, architectural review, DECISIONS.md |
| **Coder** | Per task | Reviewers + Tech Lead (directly), Lead (DONE/STUCK) | Implement, self-check, request review directly, fix feedback, commit |
| **Security Reviewer** | Whole session | Coder only | Injection, XSS, auth bypasses, IDOR, secrets |
| **Logic Reviewer** | Whole session | Coder only | Race conditions, edge cases, null handling, async |
| **Quality Reviewer** | Whole session | Coder only | DRY, naming, abstractions, CLAUDE.md + conventions compliance |
| **Architect** (COMPLEX) | Whole session | Other Architects + Coders + Lead | Debate spec (Phase 1), review code in domain (Phase 2+). Replaces Tech Lead + 3 Reviewers. |

## Complexity Classification

Classify after researchers return. Follow the detailed algorithm in `references/phase1-planning.md` (Step 3).

**Quick reference — what each level means:**

| Complexity | Team Composition | Total Agents |
|-----------|------------------|--------------|
| **SIMPLE** (0-1 MEDIUM triggers) | Lead + Coder + Unified Reviewer | 3 |
| **MEDIUM** (2-3 MEDIUM triggers, 0 COMPLEX) | Lead + Coder + 3 Reviewers + Tech Lead | 6 |
| **COMPLEX** (4+ MEDIUM or 1+ COMPLEX trigger) | Lead + 3 Architects (debate → review) + Coder(s) + Researchers + Risk Testers | 5-8+ |

**SIMPLE** differences: Skip Tech Lead, skip risk analysis, unified reviewer only, faster flow.
**MEDIUM** differences: Full flow, Tech Lead validates plan, 3 separate reviewers, risk analysis.
**COMPLEX** differences: 3 Architects debate specification before coding, one becomes Primary Architect, architects become reviewers.

## Protocol Overview

### Phase 1: Discovery, Planning & Setup

> **Full details:** `references/phase1-planning.md`

Execute these steps in order:

1. **Quick orientation** (Lead alone) — read CLAUDE.md, check `.conventions/`, glob top-level layout. Do NOT read source files.

2. **Dispatch researchers** (conditional) — adaptive: skip what's already known. Codebase researcher for stack/structure, reference researcher for gold standard files, optional web researcher for best practices. Skip all if `--no-research` or brief provides everything.

3. **Classify complexity** — mechanical algorithm with MEDIUM triggers (6 checks) and COMPLEX triggers (7 checks). Not overridable. Create team, write VERIFICATION_PLAN.md (SIMPLE/MEDIUM) or defer to architects (COMPLEX). Compile gold standard block for coders. Create tasks with acceptance criteria + convention checks.

4. **Validate plan** — SIMPLE: skip. MEDIUM: Tech Lead validates. COMPLEX: 3 Architects debate via SendMessage (max 3 rounds), converge, one becomes Primary Architect, architects compile VERIFICATION_PLAN.md.

4c-4. **Plan Brief to User — HARD GATE (COMPLEX/MEDIUM)**. After plan validation, Lead MUST print a short status brief to chat: task list, key decisions from the architect debate (or Tech Lead review), files/modules affected, out-of-scope, open questions. This is NOT a question — it's a status report so the user knows what the team decided before implementation begins. The user has been silent since the brief/interview — break the silence here. SIMPLE skips this. See `phase1-planning.md` Step 4c-4.

4a. **Design options — REQUIRED SCAN** (skip only for pure refactoring/bug fixes)