develop-feature

Spec-Driven Feature

Runs the Specify → Plan → Tasks workflow described in this project's AGENTS.md, populating specs/<NNN-feature-slug>/{spec.md,plan.md,tasks.md} from the canonical templates in templates/. This skill is a thin orchestrator: it routes the work, scaffolds the folder, and owns every approval gate and decision-log.md entry, but the actual drafting of each document is delegated to a dedicated agent — specifier (spec.md), planner (plan.md), task-decomposer (tasks.md) — each invoked fresh, so none of them carries the other phases' revision back-and-forth into its own context, and each can be pinned to the model tier its phase actually needs (AGENTS.md Model Routing). Three gated phases — never skip a gate, and never merge two phases into one turn.

This file is intentionally short: it covers routing and the rules that apply throughout the whole session. Each phase's actual protocol lives in its own file under references/, read only when you reach that phase — see "Phases" below. A feature commonly spans days across many separate conversation turns; re-reading the phase file at the point of use, rather than relying on one big upfront read, is what keeps the protocol from decaying as the session grows.

Behavioral guardrails (apply throughout this skill session)

These rules are active from Step R through Phase 5 — routing, drafting, analysis, and implementation alike.

• No guessing. Where input leaves something unspecified, write [NEEDS CLARIFICATION: specific question] and surface it — never silently invent an assumption.
• Investigate before claiming. Never make statements about the codebase without first reading the relevant files. If a claim requires looking at code, look first.
• Conservative by default. Recommend before you write; stop and ask before anything irreversible (deleting files, force-pushing, dropping tables, external service calls).

• The human owns every approval gate — you never self-approve. Each drafting phase (1, 2, 3) and the Analyze gate (3.5) ends by stopping for explicit human approval; never flip a document's Status to Approved, merge two phases into one turn, or proceed on your own judgment because the draft "looks fine." This is the kit's core promise ("agent proposes, human approves") and it holds for the whole session, not just when a phase reference file happens to be freshly in context.
• Route fixes to the owning phase — never hand-apply a finding. When artifact-analyzer (or any check) reports an issue, loop it back to the agent that owns that artifact — specifier for spec.md, planner for plan.md, task-decomposer for tasks.md — and re-run the gate after the human approves the fix. The analyzer is read-only and reports; you are the orchestrator and route. Don't edit spec.md/plan.md/tasks.md yourself to clear a finding (small wording fixes aside) — the drafting agent stays responsible for its artifact's quality.
• No over-engineering. Only specify, plan, and build what is directly requested — no abstractions, extra projects, or flexibility for hypothetical future requirements unless the user explicitly asks.
• Template fidelity. spec.md, plan.md, tasks.md, and decision-log.md follow their canonical templates in templates/ exactly — no invented sections, fields, or status values beyond what the template defines. This binds the orchestrator's own edits (the Status header, decision-log.md rows) just as much as what specifier/planner/ task-decomposer draft into the body — a freelanced addition is a template deviation whether it's a paragraph or a single field. If a template genuinely seems to be missing something a feature needs, raise it as a question back to the human rather than freelancing a fix.
• Don't reprint drafted documents in chat. Every drafting phase (1, 2, 3) ends the same way: an agent already wrote the document to disk, so tell the human the file path and the agent's summary — retyping the content doubles output-token cost for no benefit. If the human asks to see it inline ("show me", "print it"), read the file and relay it then; otherwise let them review it in the file directly.
• Every prompt gets routed, not just the first one. No matching specs/<NNN>-<slug>/ folder → Step R fresh. Mid-session on a feature in progress → the resume diff-check ("Resuming an in-progress feature" below) before anything else. A feature that already finished — every document Approved, every story cleared Phase 5 — is not exempt: it goes through "Reopening a completed feature" below. Never skip straight to editing code because the request "sounds small," "sounds urgent," repeats something said earlier, or because every gate already shows Approved — routing and the diff-check determine that, not your own in-the-moment judgment.

Before starting

Confirm templates/spec.template.md, templates/plan.template.md, templates/tasks.template.md, templates/decision-log.template.md, and templates/learnings.template.md exist at the project root. If not, stop — tell the user to copy templates/ from this kit first. One source of truth: the project root, not this skill.

Resuming an in-progress feature

If specs/<NNN>-<slug>/ already exists: resume, don't start — Step 0 refuses to overwrite by design.

0. Diff the triggering prompt against what's already drafted, before anything else — including before touching any code. Check spec.md, plan.md, and tasks.md far enough to answer one question: does this prompt describe something already captured there (rephrasing aside), or is it introducing something new — a requirement, an acceptance criterion, a changed scope, a different approach than what was approved? If it's already covered, go to step 1. If it's new, don't hand-apply it: route it to whichever phase owns the affected artifact, per the "route fixes to the owning phase" guardrail above — a human's new instruction is a finding like any other; the source doesn't change who owns the fix. Two capture rules before invoking the owning agent, both for the same reason (agents run in fresh contexts — a file they can read is a durable input, a remark in this conversation is not):

   • Implementation-specific input (existing-system context, a candidate approach — not a WHAT/WHY change) goes into research.md first (create from templates/research.template.md if it doesn't exist), before invoking planner. Follow that file's own revision-discipline note: if the new input contradicts or corrects an entry already there, edit that entry in place rather than appending beside it.
   • A change to a currently-Approved document follows "Reopening a completed feature" steps 1-4 below for the exact mechanics — record the pending amendment, flip to the literal Draft string before the owning agent touches it, re-gate, cascade. Those mechanics govern amending any Approved document, whether or not the rest of the feature is done. Get the human's approval on the amended document (flipping its Status and logging the gate like any other approval) before resuming below.

1. Read each document's Status header (spec.md, plan.md, tasks.md): Draft = drafted but not yet approved; Approved = that gate is cleared. A document still full of placeholders hasn't been started.

2. Resume at the first phase whose document is not Approved; honour the approval gate before moving on. Any [NEEDS CLARIFICATION] markers still in the documents are the open questions left to settle. Read that phase's reference file (below) before acting — don't resume from memory of an earlier read. One special case: a document at Draft that already has an approval row for its gate in decision-log.md is a reopen in flight, not an unapproved first draft — a prior session flipped it and was interrupted before the amendment landed. Look for its entry under research.md → Pending Amendments and hand that to the owning agent as the amendment input. If there's no entry and the triggering prompt carries no detail, the reason for the flip is gone with the old conversation — ask the human what changed; never re-present the stale body for approval as if nothing was pending.

3. Cross-check decision-log.md — it carries one committed row per approved gate.

4. If learnings.md has entries, skim it before re-invoking implementor or debugger — it may already record why a prior attempt at this story went sideways. If it's grown large or repetitive across many prior stories and no compaction pass has run recently, this is also a good moment to offer one (see references/phase-5-review.md's compaction step) before it's handed, unread in full, into another fresh sub-agent context.

5. Re-read all three Status headers before relying on decision-log.md — don't carry step 1's conclusion forward. This step applies only if spec.md, plan.md, and tasks.md each read exactly Approved — <who>, <date>; if even one doesn't, go to step 2 instead. Only then is the resume point inside the per-story loop (3.7 → 4 → 5), not at a document gate.

   With the precondition actually confirmed, use decision-log.md's row history to find the story and its state, and act on it:

   • No rows at all for a story → it hasn't started. Invoke test-writer (Phase 3.7) — never jump straight to implementor before tests exist; that skips tests-first.
   • A Tests (red) row but no Implement row → mid-implementation. Invoke implementor for that story and let it find the exact task itself, via its own step 1 (run each task's test in order; the

Content truncated.