team-feature

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: Full Autonomy

Make ALL decisions autonomously. The user gives a task — possibly vague, one sentence — and Lead figures out everything else. NEVER go back to the user to ask clarifying questions. Instead:

• Ambiguous requirement? → Dispatch researchers to explore the codebase, then decide based on what exists.
• Multiple valid 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.

The ONLY reason to contact the user is if the task is so vague it's impossible to begin (e.g., just the word "improve" with no context). Even then, try sending researchers first.

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: 3)
• --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.

4a. Design options (when UX or architectural decisions exist) — scan tasks for decisions the user should weigh in on. Present 2-3 options with ASCII wireframes (UX) or flow diagrams (architecture) via AskUserQuestion. Max 3 decision points per feature. Update tasks with chosen approach. Skip for pure backend/refactoring work.

4b. Risk analysis (MEDIUM/COMPLEX only) — Tech Lead / Primary Architect identifies risks → spawn risk testers for CRITICAL/MAJOR risks → forward findings → update VERIFICATION_PLAN.md with mitigations.

5. Spawn team — reviewers (or switch architects to review mode) + coders with gold standard block + write state.md for compaction resilience.

Phase 2: Execution — Monitor Mode

Full details: references/phase2-monitoring.md

Lead's role is MINIMAL. Coders communicate directly with reviewers and tech-lead via SendMessage. Lead only:

• Tracks progress in state.md (task status updates)
• Spawns new coders when tasks complete and unassigned work remains
• Handles STUCK/QUESTION/REVIEW_LOOP escalations
• Transitions to Phase 3 when ALL coding tasks complete

Lead does NOT: read code, review code, run tests, notify reviewers, or forward messages between team members.

Compaction recovery: If context is lost, read .claude/teams/{team-name}/state.md — it contains the current phase, team roster, task statuses, and executable instructions for what to do next.

Phase 3: Completion & Verification

Full details: references/phase3-verification.md

Execute in order:

1. Conventions update — assign the conventions task to a coder. NOT optional — feature cannot be declared complete without .conventions/ being created or updated.

2. Cross-task consistency check — ask Tech Lead / Primary Architect.

3. Completion gate — verify .conventions/ exists and was modified this session.

4. Integrated verification (team still alive):

   • Parse VERIFICATION_PLAN.md sections
   • Pre-flight check (curl dev server)
   • Spawn ci-verifier + browser-verifier + spec-verifier in parallel
   • Collect results with integrity audit (manifest comparison)
   • Fix-verify loop: coders fix FAIL items, re-verify (max 3 iterations)
   • Compile progressive verification report → save to VERIFICATION_REPORT.md

5. Shutdown — print summary, shutdown team, TeamDelete, present Human Checks to user.

Key Rules

• Gold standards in every coder prompt — coders MUST receive canonical examples as few-shot context. This is the #1 lever for code quality.
• Escalation, not silent deviation — when a pattern doesn't fit, coders escalate to Tech Lead / Primary Architect. Every approved deviation is documented in DECISIONS.md.
• One file = one coder — never assign overlapping files to different coders.
• Definition of Done — defined in VERIFICATION_PLAN.md (the single "is it done?" document).
• Verify before shutdown — all auto-checks must pass (or be exhausted after 3 fix attempts) before declaring completion.

Reference Files

Detailed protocols for each phase:

• references/phase1-planning.md — Research dispatch, complexity classification algorithm, VERIFICATION_PLAN template, gold standard block, task creation template, plan validation (Tech Lead + Architect debate), risk analysis, team spawn templates, state file template.
• references/phase2-monitoring.md — Event handling table, state file updates, compaction recovery, spawning new coders, stuck protocol.
• references/phase3-verification.md — Conventions update, completion gate, integrated verification pipeline (5a-5f), verification report template, summary report, shutdown, human checks.