markcallen · Sep 29, 2026 · Sep 29, 2026
@@ -92,6 +92,13 @@ See [installation.md](installation.md) for package-specific commands, skill inst
 - go install/go run (`ballast-go`)
 - installed skills under target-specific skill locations such as `.claude/skills/` and `.opencode/skills/`
 
+## Development Process
+
+See [development-process.md](development-process.md) for how Spec Kit and Ballast's rules
+fit together end to end: which artifact owns which kind of truth, the eight-step sequence
+from product intent to merged code, the completion gates, and which steps to skip for
+smaller changes.
+
 ## Code Review
 
 See [code_review.md](code_review.md) for the review policy this repository follows: what

@@ -1,5 +1,7 @@
 # Documentation Agent
 
+> Step 7 of the [development process](../development-process.md).
+
 The **docs** agent keeps repository documentation aligned with the shipped application, CLI, configuration, and operating model.
 
 ## What It Sets Up

@@ -1,5 +1,7 @@
 # Plan Lifecycle Agent
 
+> Step 5 of the [development process](../development-process.md).
+
 The **plan-lifecycle** agent defines when agents should create implementation plans and how completed plans graduate into ADRs.
 
 ## What It Sets Up

@@ -1,5 +1,7 @@
 # Spec Kit Agent
 
+> Part of the [development process](../development-process.md) — Spec Kit owns product intent and the feature lifecycle; that doc sequences it with the task, plan, testing, docs, and review rules.
+
 The **spec-kit** agent adds common GitHub Spec Kit guidance for repositories that use `.specify/` and `specs/`.
 
 ## What It Sets Up

@@ -1,5 +1,7 @@
 # Tasks Agent
 
+> Step 4 of the [development process](../development-process.md). `tasks/todo.md` is branch-local; durable work belongs in the configured task system.
+
 The **tasks** agent keeps branch-local work tracking and durable task-system handoff consistent.
 
 ## What It Sets Up

@@ -1,5 +1,7 @@
 # Testing Agent
 
+> Step 6 of the [development process](../development-process.md) — tests start from the Spec Kit acceptance criteria.
+
 The **testing** agent sets up and maintains test workflows for TypeScript, Python, Go, Ansible, Terraform, Dart, and Docker projects with sensible defaults and CI integration.
 
 ## What It Sets Up by Language

@@ -0,0 +1,163 @@
+# Development Process
+
+How Spec Kit and Ballast's existing rules fit together, from product intent to merged code.
+
+Ballast ships a `spec-kit` agent and three Spec Kit skills alongside rules for tasks, plan
+lifecycle, testing, documentation, and PR review. Each is documented on its own. What was
+missing is the sequence — which artifact owns which kind of truth, and in what order they
+come into play.
+
+This is a recommended workflow, not a replacement for those rules. It sequences the
+existing guides rather than restating them; each step links to the guide that owns the
+detail.
+
+## Which artifact owns what
+
+The main failure mode this process prevents is the same decision being recorded in five
+places and drifting in four of them. Each artifact owns exactly one kind of truth:
+
+| Artifact | Owns | Does not own |
+| --- | --- | --- |
+| Spec Kit `spec.md` | Product intent and acceptance scenarios | Technical design, implementation detail |
+| Spec Kit `plan.md` | Technical design for one feature | Product intent, branch bookkeeping |
+| Spec Kit `tasks.md` | Generated implementation work for that feature | Evidence, rollback notes, durable follow-up |
+| `plans/plan-<name>.md` | Branch and session continuity for non-trivial work | Anything a single-file fix would need |
+| `tasks/todo.md` | Branch-local execution tracking, test evidence, rollback notes | Durable backlog — it is deleted when the branch is done |
+| GitHub Issues | Durable follow-up, bugs, cross-branch work | Branch-local checklists |
+| `adr/NNN-*.md` | Decisions that outlive the change that made them | Work in progress |
+
+Two rules keep it that way:
+
+- **Intent is written before implementation, not reconstructed after it.** When existing
+  behaviour changes, update `spec.md` first. Old requirements are preserved through git
+  history rather than rewritten to match whatever the code now does.
+- **Work that will not be finished on this branch leaves the branch.** It goes to a GitHub
+  Issue with the link recorded, not into a widened plan or a todo that outlives its branch.
+
+## The sequence
+
+### 1. Set up the repository
+
+Use [`speckit-bootstrap`](skills/speckit-bootstrap.md) when `.specify/` is missing,
+incomplete, or questionable.
+
+Done when `.specify/` is valid, the native `speckit-*` skills are installed for the active
+target, a project constitution exists if cross-cutting constraints are needed, and the
+Ballast managed outputs list the `spec-kit` rule and the `speckit-*` skills.
+
+> This repository has not bootstrapped Spec Kit yet — there is no `.specify/` directory.
+> That work is tracked as [#303](https://github.com/everydaydevopsio/ballast/issues/303).
+
+### 2. Establish a baseline, if the product already exists
+
+Use [`speckit-reverse-engineer`](skills/speckit-reverse-engineer.md) before any forward
+work when the product exists but reliable specs do not.
+
+Evidence is weighted, strongest first: intentional specs and explicit product decisions,
+then observable runtime behaviour, E2E and smoke tests, integration tests, unit tests,
+source and configuration, and only then structural inference.
+
+The discipline that matters here: **low-confidence behaviour stays an assumption or an
+open question — it does not get promoted to a requirement** because it was easier to
+write it as one. Capabilities are grouped by what the product does, not by route or file.
+
+### 3. Run the feature
+
+Use [`speckit-delivery`](skills/speckit-delivery.md) for bounded forward work. It
+orchestrates the native skills in order:
+
+```text
+speckit-specify → speckit-clarify → speckit-checklist → speckit-plan
+   → speckit-tasks → speckit-analyze → speckit-implement → speckit-converge
+```
+
+`speckit-taskstoissues` is an optional handoff for larger features where the generated
+tasks need to be visible to people who are not on the branch. It is not part of the
+default path — for most changes it duplicates tracking that `tasks.md` already does.
+
+### 4. Track the branch
+
+Create or update `tasks/todo.md` per the [tasks guide](agents/tasks.md): scope and
+constraints, acceptance criteria, execution checklist, test strategy with
+requirement-to-test mapping, rollback strategy, and outcome with command evidence.
+
+It is branch-local. Before opening a PR, every unchecked item is resolved, promoted to a
+GitHub Issue with the link recorded, or removed as no longer relevant.
+
+### 5. Plan the implementation, and graduate decisions
+
+Create a plan under `plans/` per the [plan lifecycle guide](agents/plan-lifecycle.md) when
+the change touches more than two files, spans multiple sessions, carries real uncertainty,
+or makes an architectural decision. Skip it for single-file fixes.
+
+Keep it current: when the approach changes, the plan and its change log change with it. Do
+not widen a plan to absorb out-of-scope work — that goes to `tasks/todo.md` or an issue.
+
+Graduate to an ADR when the plan lifecycle rule calls for it — that is, when the decision
+outlives the change. Not every Spec Kit feature produces an architectural decision, and
+routine features should not generate ADRs for their own sake.
+
+### 6. Test against the acceptance criteria
+
+Start from the acceptance criteria in the Spec Kit spec, per the
+[testing guide](agents/testing.md):
+
+- Write the failing test first, and confirm it fails **for the expected reason**.
+- Implement the smallest coherent change that makes it pass.
+- Cover the failure paths — errors, edge cases, misuse — not only the happy one.
+- Link tests back to requirement or issue IDs through names, comments, or PR evidence.
+- Run targeted tests locally; rely on CI for the full matrix.
+
+### 7. Update the documentation in the same change
+
+Per the [docs guide](agents/docs.md), documentation changes alongside behaviour, CLI
+commands, configuration, architecture, workflows, or operating assumptions — not after.
+
+Docs should answer: what changed, why a user would care, how a new user gets started, how
+an advanced user configures or operates it, and which commands, flags, config fields,
+files, or APIs are affected.
+
+### 8. Close the PR
+
+Use [`github-pr-copilot-cycle`](skills/github-pr-copilot-cycle.md): push, request
+`@copilot`, wait for review to settle, score every unresolved comment, fix the actionable
+ones, reply and resolve each handled thread, and re-check CI after each push. Up to three
+cycles, or until nothing actionable is unresolved.
+
+Review standards — severity, what blocks a merge, and the evidence bar — are in
+[code_review.md](code_review.md). Agent review findings are claims to verify, not verified
+findings.
+
+## Completion gates
+
+A change is done when all of these hold:
+
+- [ ] Spec and plan artifacts reflect the intended product change.
+- [ ] Spec Kit tasks are implemented, or explicitly deferred with a reason.
+- [ ] `speckit-converge` reports no actionable gaps.
+- [ ] `tasks/todo.md` is complete, or its remainder is linked to GitHub Issues.
+- [ ] Tests pass locally for the relevant scope, and CI passes for the PR.
+- [ ] User-facing and operator-facing documentation is current.
+- [ ] Copilot review has no unresolved actionable comments.
+- [ ] Architectural decisions are captured in ADRs where the plan lifecycle rule requires it.
+
+## When to skip steps
+
+The full sequence is for a bounded product change. Most work is smaller:
+
+| Change | Sequence |
+| --- | --- |
+| Single-file fix, obvious and contained | Steps 6–8. No plan, no spec. |
+| Bug fix with a behaviour change | Steps 4, 6, 7, 8. Spec only if intent was wrong. |
+| Non-trivial feature | All eight. |
+| Architectural change | All eight, and step 5 ends in an ADR. |
+
+Running the full process on a one-line fix produces ceremony, not quality. The rules that
+never relax are the ones in steps 6 and 7: a behaviour change gets a test that failed
+first, and docs change with behaviour.
+
+## Related
+
+- [`spec-kit` agent guide](agents/spec-kit.md) — when Spec Kit applies and how Ballast treats it
+- [Code review policy](code_review.md)
+- [Architecture decision records](../adr/README.md)
@@ -1,5 +1,7 @@
 # GitHub PR Copilot Cycle
 
+> Step 8 of the [development process](../development-process.md). Review standards live in [code_review.md](../code_review.md).
+
 Use `github-pr-copilot-cycle` to run a pull request feedback loop with GitHub Copilot review.
 
 ## Install

@@ -1,5 +1,7 @@
 # Spec Kit Bootstrap
 
+> Step 1 of the [development process](../development-process.md).
+
 Use `speckit-bootstrap` when adopting or repairing GitHub Spec Kit in a repository.
 
 ## Install

@@ -1,5 +1,7 @@
 # Spec Kit Delivery
 
+> Step 3 of the [development process](../development-process.md).
+
 Use `speckit-delivery` after a Spec Kit baseline exists to coordinate a bounded product change.
 
 ## Install

@@ -1,5 +1,7 @@
 # Spec Kit Reverse Engineer
 
+> Step 2 of the [development process](../development-process.md), for products that exist before their specs do.
+
 Use `speckit-reverse-engineer` to create a GitHub Spec Kit baseline for an existing application before normal forward development begins.
 
 ## Install

@@ -1,6 +1,6 @@
 # Plan: Spec Kit Development Process
 
-**Status:** In progress (Phases 2 and 4 complete; Phase 1 blocked on the placement question)
+**Status:** Complete — all five phases landed; ready to graduate to an ADR
 **Branch:** docs/spec-kit-development-process
 **Created:** 2026-08-29
 **Related ADRs:** _(none yet)_
@@ -227,11 +227,11 @@ A change is complete only when:
 
 Per-agent and per-skill guides (`docs/agents/spec-kit.md`, `docs/skills/speckit-*.md`, `docs/skills/github-pr-copilot-cycle.md`) already exist from the Spec Kit merge, so the remaining work is the connective tissue between them, not new per-artifact docs.
 
-- [ ] Phase 1: Resolve the placement question, then write the end-to-end process doc that sequences the existing guides.
+- [x] Phase 1: Placement resolved as option (a) — a new `docs/development-process.md`. The per-agent and per-skill guides already existed, so what was missing was the connective tissue between them; burying that inside one agent's guide would make it hard to find. Written and indexed in `docs/README.md`.
 - [x] Phase 2 (#340): Created `docs/code_review.md` rather than repointing. The reference is written into `AGENTS.md` by an external Codex reviewer installer (an orphaned `END CODEX REVIEWER INSTALLER` marker sits below it), so providing the target is durable where editing the pointer would be overwritten. Indexed in `docs/README.md`.
-- [ ] Phase 3: Add cross-links from the existing Spec Kit guides to task, plan lifecycle, testing, docs, and PR review guidance.
+- [x] Phase 3: Added a one-line pointer to the top of nine guides — `spec-kit`, the three `speckit-*` skills, `github-pr-copilot-cycle`, `tasks`, `plan-lifecycle`, `testing` and `docs` — each naming the step it belongs to, so the sequence is discoverable from any entry point.
 - [x] Phase 4: Added `packages/ballast-typescript/src/docs-links.test.ts`. Checks that every relative markdown link resolves, and that every `docs/*.md` path named in backticks exists. Verified it reproduces #340 by deleting the doc. `plans/` is excluded from the second check, since a plan naming a file it intends to create describes intent, not current state.
-- [ ] Phase 5: Run focused validation and update this plan with evidence.
+- [x] Phase 5: Validated. 385/385 TypeScript tests, eslint and prettier clean; `docs-links.test.ts` confirms every link in the new doc and the nine cross-links resolve. Claims spot-checked against the repository: `.specify/` is genuinely absent and #303 is genuinely open, as the doc states.
 
 ## Verification
 
@@ -257,12 +257,27 @@ Future implementation should verify:
 | Keep process guidance only in agent rules         | Rules guide agents, but users need GitHub-readable docs that explain the workflow without inspecting generated `.codex/` or `.claude/` files. |
 | Skip `tasks/todo.md` when Spec Kit has `tasks.md` | Spec Kit tasks describe implementation work; `tasks/todo.md` records branch evidence, rollback notes, and final triage.                       |
 
+## Resolved Questions
+
+All four answered; the phases above carry the decisions.
+
+- **Placement — option (a)**, a new `docs/development-process.md`. The per-guide docs
+  already existed; the gap was the sequence between them, which does not belong inside any
+  one agent's guide.
+- **`docs/code_review.md` — created**, not repointed. The reference is written into
+  `AGENTS.md` by an external Codex reviewer installer, so supplying the target is durable
+  where editing the pointer would be overwritten. Closed #340, which was the same question
+  asked in a second place.
+- **`speckit-taskstoissues` — optional handoff**, not part of the default path. It earns
+  its place only when generated tasks need to be visible to people off the branch;
+  otherwise it duplicates what `tasks.md` already tracks.
+- **ADR graduation — only when the plan lifecycle rule already triggers.** Not every Spec
+  Kit feature makes an architectural decision, and requiring an ADR per feature would
+  produce records that no one consults.
+
 ## Open Questions
 
-- Should the final process live in a new `docs/development-process.md`, under `docs/agents/spec-kit.md`, or both?
-- Should `docs/code_review.md` be created as a standalone review policy, or should `AGENTS.md` point to an existing review document?
-- Should `speckit-taskstoissues` be part of the default process, or only an optional handoff for larger features?
-- Should ADR graduation be required for all Spec Kit plans or only when the Ballast plan lifecycle rule is triggered?
+- None outstanding.
 
 ## Change Log
 
@@ -271,3 +286,4 @@ Future implementation should verify:
 | 2026-08-29 | Plan created with Spec Kit process model and target `.rulesrc.json` configuration.                                                                                                                        |
 | 2026-09-16 | Merged main; corrected Files Affected (Spec Kit agent/skill docs already exist) and rescoped phases to the remaining connective work; confirmed the `.rulesrc.json` example still matches the repository. |
 | 2026-09-29 | Phases 2 and 4 landed. Phase 1 still needs the placement question answered. |
+| 2026-09-29 | Phases 1, 3 and 5 landed; all four open questions resolved. Plan complete. |
@@ -51,16 +51,17 @@ A stale plan is worse than no plan — it is read as current intent.
       via #339/#342/#325, leaving only #128 and #94, which are tracked as issues. The
       Phase 2 and Phase 3 design notes, and the unanswered parity open question, were
       posted to #128 and #94 before deletion so nothing was lost.
-- [ ] **`plans/plan-spec-kit-development-process.md` — kept and in progress.** Phases 2
-      and 4 are done; Phase 1 is blocked on its placement question (does the end-to-end
-      process doc live at `docs/development-process.md`, under `docs/agents/spec-kit.md`,
-      or both?). Phases 3 and 5 follow Phase 1.
+- [x] **`plans/plan-spec-kit-development-process.md` — complete.** All five phases landed
+      and all four open questions are resolved. `docs/development-process.md` is the
+      sequence; nine guides cross-link into it. Ready to graduate to an ADR.
 - [x] **#340 answered and closed.** The spec-kit plan's open question and #340 were the
       same question. Resolved by creating `docs/code_review.md` rather than repointing
       `AGENTS.md`: that line is written by an external Codex reviewer installer, so
       supplying the target is durable where editing the pointer is not.
-- [ ] Promote whichever of these outlive this branch into GitHub issues and record the links
-      here, per the task-system rule. `tasks/todo.md` is not durable tracking.
+- [x] **Nothing outlived the branch.** All three plans are resolved — two retired with
+      their substance moved to the issues that own it (#128, #94), one completed — so no
+      promotion was needed. #340 was closed rather than promoted. The one genuinely new
+      item found along the way, #376, was filed when it was found.
 
 ## Test Strategy
 
@@ -71,5 +72,5 @@ Documentation-only; no test changes expected. Verification is by inspection:
 
 ## Outcome
 
-- Result: _pending_
-- Evidence links/commands: _pending_
+- Result: all three plans resolved — `issue-priority-plan.md` retired to ADR-003, `plan-setup-toolchain.md` retired to #128/#94, `plan-spec-kit-development-process.md` completed across five phases.
+- Evidence: PRs #379 (retirements, ADR-003), #380 (#340 + docs-link check), and this branch (process doc + cross-links). 385/385 TypeScript tests, eslint and prettier clean, `docs-links.test.ts` green.