docs: sequence Spec Kit with the existing Ballast rules

[markcallen]

Phases 1, 3 and 5 — completing plans/plan-spec-kit-development-process.md.

The gap

Ballast ships a spec-kit agent, three Spec Kit skills, and rules for tasks, plan lifecycle, testing, docs and review. Each was documented on its own. The sequence between them was not — and without it the same decision gets recorded in spec.md, tasks.md, tasks/todo.md, a plan, an issue and a PR comment, then drifts in five of them.

docs/development-process.md

Placement is option (a) as agreed — a new doc, not folded into docs/agents/spec-kit.md. The per-guide docs already existed; what was missing was connective tissue, and that doesn't belong inside any one agent's guide.

It opens with which artifact owns which kind of truth, because that table is the part that actually prevents the duplication. Then the eight steps, the completion gates, and — deliberately — when to skip steps:

Change	Sequence
Single-file fix	Steps 6–8. No plan, no spec.
Bug fix with behaviour change	Steps 4, 6, 7, 8
Non-trivial feature	All eight
Architectural change	All eight, ending in an ADR

Running the full process on a one-line fix produces ceremony, not quality. The two rules that never relax are named explicitly: a behaviour change gets a test that failed first, and docs change with behaviour.

It links to the existing guides rather than restating them, per the plan's own constraint.

The two smaller decisions

Both recorded in the plan's resolved questions:

• speckit-taskstoissues — optional handoff, not default. It earns its place only when generated tasks need to be visible off-branch; otherwise it duplicates tasks.md.
• ADR graduation — only where the plan lifecycle rule already triggers. Not every feature makes an architectural decision, and an ADR per feature produces records nobody consults.

Phase 3

A one-line pointer at the top of nine guides — spec-kit, the three speckit-* skills, github-pr-copilot-cycle, tasks, plan-lifecycle, testing, docs — each naming the step it belongs to, so the sequence is reachable from any entry point rather than only from the index.

Honesty check

The doc states this repository has not bootstrapped Spec Kit itself. .specify/ is genuinely absent and #303 is genuinely open — both verified, not assumed. It would have been easy to write the process as though it were already in use.

Phase 5 verification

• 385/385 TypeScript tests, eslint and prettier clean
• docs-links.test.ts (added in Phase 4, fix: create the review policy AGENTS.md already promised #380) validates every link the new doc and the nine cross-links introduce — the check is now guarding the work that came after it
• tasks/todo.md has zero unchecked items; nothing outlived the branch, so nothing needed promoting

Next

The plan is complete and marked ready to graduate. Say the word and I'll take it to ADR-004 — I've left that as a separate step rather than assuming it.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!