Spec Driven Development

Spec-Driven Development Skill

You ship software through GitHub's spec-kit (92K stars, MIT, baked into every osModa spawn). The workflow makes you a closed loop: humans declare WHAT and WHY; you generate plan, tasks, code; tests are the inner-loop signal of success; the human is the outer-loop reviewer.

When to invoke spec-kit

Use spec-kit when:

• The user asks for a feature implementation: "build me X", "add Y", "implement Z", "rewrite this so it does W"
• The work spans more than ~5 file edits
• Tests will exist that you can iterate against
• The user wants a reproducible artifact trail (specs, plans, tasks)

Skip spec-kit when:

• One-line fix or typo
• Operational task: use system-monitor, self-healing, app-deployer instead
• Exploratory hack: free-form chat
• The user explicitly says "just edit the file" / "don't write a spec"

The 8-step workflow

How to call from your tool box

The two MCP tools spec_kit_init + spec_kit_run wrap the spec-kit workflow. Use them — don't shell out to specify directly. Tool calls are audit-ledgered; raw shell isn't.

Step 1 — scaffold

spec_kit_init({
  project_name: "csv-exporter",
  integration: "claude",
  constitution_seed: "Python 3.12+, pytest for tests, no async, single binary"
})

Returns { project_path: "/workspace/csv-exporter", skills: [9 speckit-*], next_action }. The 9 skills become available as /speckit-* slash commands inside that project.

Step 2 — set governance

spec_kit_run({
  project_path: "/workspace/csv-exporter",
  command: "constitution",
  prompt: "Python 3.12+, pytest, no async runtime, all functions have docstrings, max 200 LOC per module"
})

Writes /workspace/csv-exporter/memory/constitution.md. Read the user's .specify/.constitution-seed.md first if it exists — they may have pre-staged principles.

Step 3 — capture WHAT and WHY

spec_kit_run({
  project_path: ".../csv-exporter",
  command: "specify",
  prompt: "<user's exact feature request, expanded with their goals>"
})

Resist the urge to declare a tech stack here — that's step 4. Specify is purely product-level.

Step 4 — clarify (only if specify left gaps)

spec_kit_run({ command: "clarify", prompt: "" })

This is interactive in the user-facing flow. From your loop: skip unless specify output mentions ambiguities.

Step 5 — declare the plan

spec_kit_run({
  command: "plan",
  prompt: "Python 3.12, click for CLI, pandas for parsing, pytest for tests, single-file binary via shiv"
})

Writes /specs/<feature>/plan.md.

Step 6 — break into tasks

spec_kit_run({ command: "tasks", prompt: "" })

Writes /specs/<feature>/tasks.md with numbered ordered tasks.

Step 7 — implement

spec_kit_run({
  command: "implement",
  prompt: "",
  timeout_seconds: 1800   // give it 30 min for non-trivial features
})

This is the long step. The agent reads tasks.md, generates code, runs tests, iterates. Do not interrupt unless the user explicitly aborts. Token usage will be high — that's by design (token-max philosophy).

Common pitfalls

• Don't run implement before plan — the implement step reads plan.md for the tech stack. Without it, the agent guesses (often wrong).
• Don't write the spec FOR the user. Capture their exact words for the WHAT/WHY. If their description is too vague to act on, run clarify instead of inventing requirements.
• Don't skip constitution for multi-feature projects. It's the cross-feature governance contract. Without it, feature 2 will violate decisions you implicitly made in feature 1.
• Don't run two spec_kit_runs in parallel for the same project. They contend for the same .specify/ state. Sequence them.
• Don't forget the audit trail. Every spec_kit_run is hash-chained in agentd's ledger. Querying agentctl events --type spec-kit shows the full project history. Show this to the user when they ask "what did you do?"