---
name: feature-developer
description: "Executes the full feature development lifecycle (phases 3-9): generates proposal documents from discussion, iteratively reviews and refines proposal/plan documents from a strict architect's perspective, then implements the plan using TDD with parallel Task agents in worktrees, and validates with self-analysis. Use when given a feature discussion or existing proposal/plan documents to generate, review, refine, and implement."
argument-hint: [feature-topic-or-slug]
allowed-tools: Read, Glob, Grep, Bash, Agent
contracts:
  - grep: "TDD"
  - grep: "FeatureDiscussion"
  - grep: "proposal-round"
---

## Spec

λ(input: FeatureDiscussion | ProposalDoc | PlanDoc) → ImplementedFeature

## Role: Orchestrator Only

This skill is an **orchestrator**. It coordinates phases and evaluates outputs.

This skill MUST NOT:
- Write implementation code directly
- Write or edit any file directly (no Write or Edit tools — use Task agents)
- Perform proposal or plan review inline (without spawning a Task agent)
- Skip any phase, even if the caller provides detailed implementation specs

If the caller provides detailed design specs (class names, method signatures, rules, etc.),
treat that as **discussion input** — NOT as a replacement for proposal/plan documents.
You MUST still execute all phases in order.

---

## Phase 3: Generate Proposal

**Trigger**: No `docs/proposals/proposal-<slug>.md` exists yet.

**If proposal already exists**: skip to Phase 4.

**Steps**:

1. Derive `<slug>` from the feature topic (lowercase, hyphenated).
2. Spawn a Task agent (subagent_type: `general-purpose`) to read relevant source files and produce a grounded proposal draft:
   - Task agent reads all source files related to the feature area
   - Task agent writes `docs/proposals/proposal-<slug>.md` with this structure:
     - Problem Statement, Goals, Non-Goals, Design, Alternatives, Open Questions
   - Every design decision must reference actual file paths, class names, and interfaces
   - MUST NOT invent APIs, types, or paths that don't exist in the codebase
3. **Gate verification** — run this command and STOP if it fails:
   ```bash
   test -f docs/proposals/proposal-<slug>.md || { echo "GATE FAILED: proposal missing"; exit 1; }
   ```

**Gate**: `docs/proposals/proposal-<slug>.md` MUST exist on disk before Phase 4 begins.

---

## Phase 4+5: Proposal Review Loop

**Prerequisite**: Run gate verification:
```bash
test -f docs/proposals/proposal-<slug>.md || { echo "STOP: proposal missing, return to Phase 3"; exit 1; }
```

**Minimum rounds: 2** (even if Round 1 finds no issues, Round 2 must still verify).

**Round tracking**: Before starting each round N, create a round marker:
```bash
mkdir -p .claude/review && touch .claude/review/proposal-round-N.pending
```
After the Task agent completes and findings are applied, rename to `.done`:
```bash
mv .claude/review/proposal-round-N.pending .claude/review/proposal-round-N.done
```
**Exit condition check** (run before exiting the loop):
```bash
ls .claude/review/proposal-round-1.done .claude/review/proposal-round-2.done 2>/dev/null | wc -l
# Must output 2 before proceeding to Phase 6
```

**Each round**:

1. Spawn a Task agent (subagent_type: `general-purpose`) for review with this purpose:
   - Read the proposal file
   - Read every source file, interface, and type referenced in the proposal
   - For each claim in the proposal, verify it against actual code
   - Check: API surface correctness, interface contracts, dependency accuracy, implementation feasibility
   - Check: naming consistency with existing codebase conventions
   - Check: no phantom types, methods, or paths that don't exist
   - Check: edge cases, error handling, missing constraints
   - Return a prioritized issue list: **critical** / **warning** / **suggestion**

2. Evaluate the Task agent's findings:
   - If critical or warning issues exist: spawn another Task agent to apply confirmed fixes to the proposal (confirmed issues only — do NOT rewrite correct sections), then mark round done and start next round
   - If only suggestions remain: mark round done, note them, then proceed

**Exit condition**: `.claude/review/proposal-round-1.done` AND `.claude/review/proposal-round-2.done` both exist AND no critical or warning issues remain.

---

## Phase 6: Generate Plan

**Prerequisite**: Run gate verification:
```bash
test -f docs/proposals/proposal-<slug>.md || { echo "STOP: proposal missing, return to Phase 3"; exit 1; }
```

**If plan already exists**: skip to Phase 7.

**Steps**:

1. Check existing plan files to determine the next plan number NN:
   ```bash
   ls docs/plans/plan-*.md 2>/dev/null | sed 's/.*plan-//' | sed 's/-.*//' | sort -n | tail -1
   ```
2. Spawn a Task agent (subagent_type: `general-purpose`) to read the proposal and write `docs/plans/plan-NN-<slug>.md`:
   - Structure: Overview → Phases → per Phase: objectives, stages, acceptance criteria, dependencies
   - Each stage must be independently testable (TDD-first)
   - Immediate phase: full detail. Future phases: objectives only.
   - File paths, class names, and interface names must match the actual codebase.
3. **Gate verification** — run this command and STOP if it fails:
   ```bash
   test -f docs/plans/plan-NN-<slug>.md || { echo "GATE FAILED: plan missing"; exit 1; }
   ```

**Gate**: `docs/plans/plan-NN-<slug>.md` MUST exist on disk before Phase 7 begins.

---

## Phase 7+8: Plan Review Loop

**Prerequisite**: Run gate verification:
```bash
test -f docs/proposals/proposal-<slug>.md && test -f docs/plans/plan-NN-<slug>.md || { echo "STOP: missing files, return to appropriate phase"; exit 1; }
```

**Minimum rounds: 2**.

**Round tracking**: Before starting each round N, create a round marker:
```bash
mkdir -p .claude/review && touch .claude/review/plan-round-N.pending
```
After findings are applied:
```bash
mv .claude/review/plan-round-N.pending .claude/review/plan-round-N.done
```
**Exit condition check**:
```bash
ls .claude/review/plan-round-1.done .claude/review/plan-round-2.done 2>/dev/null | wc -l
# Must output 2 before proceeding to Phase 9
```

**Each round**:

1. Spawn a Task agent (subagent_type: `general-purpose`) for review with this purpose:
   - Read both the proposal and plan files
   - Read all source files, interfaces, and types referenced in the plan
   - Check: phases are complete, non-overlapping, and correctly sequenced
   - Check: each stage has clear acceptance criteria and a concrete test approach
   - Check: no implementation detail contradicts the proposal
   - Check: all file paths, class names, and interface names exist in the codebase
   - Return a prioritized issue list: **critical** / **warning** / **suggestion**

2. Evaluate findings:
   - Fix the plan by spawning a Task agent for confirmed issues. If plan changes affect proposal intent, sync the proposal too.
   - Mark round done and start next round.

**Exit condition**: `.claude/review/plan-round-1.done` AND `.claude/review/plan-round-2.done` both exist AND no critical or warning issues remain.

---

## Phase 9: Implementation

**Prerequisite**: Run gate verification:
```bash
test -f docs/plans/plan-NN-<slug>.md || { echo "STOP: plan missing, return to Phase 6"; exit 1; }
```

**Execution rules**:

- Execute phases **sequentially**: Phase N+1 starts only after Phase N's tests pass.
- Within a phase, execute independent stages **in parallel**: spawn multiple Task agents with `isolation: worktree`.
- Each Task agent follows TDD: write failing tests first, then implementation to make them pass.
- This skill does NOT write code directly — it only spawns Task agents and evaluates their results.

**Validation** (after all phases complete):

1. Run `npm run build` (or project-equivalent) via Bash.
2. Spawn a Task agent to verify the implementation against the plan and proposal:
   - Check every stage's acceptance criteria is met
   - Check no unintended side effects on existing tests
   - Return a gap list if anything is missing
3. If gaps exist: fix and re-validate.
4. Iterate until convergence.