feature-developer

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:

   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:

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:

mkdir -p .claude/review && touch .claude/review/proposal-round-N.pending

After the Task agent completes and findings are applied, rename to .done:

mv .claude/review/proposal-round-N.pending .claude/review/proposal-round-N.done

Exit condition check (run before exiting the loop):

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:

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:

   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:

   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:

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:

mkdir -p .claude/review && touch .claude/review/plan-round-N.pending

After findings are applied:

mv .claude/review/plan-round-N.pending .claude/review/plan-round-N.done

Exit condition check:

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:

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.