diff --git a/docs/README.md b/docs/README.md index 8c822048..5dd6d18c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 diff --git a/docs/agents/docs.md b/docs/agents/docs.md index f5ad6680..51b88b93 100644 --- a/docs/agents/docs.md +++ b/docs/agents/docs.md @@ -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 diff --git a/docs/agents/plan-lifecycle.md b/docs/agents/plan-lifecycle.md index f921767a..31bb7bd0 100644 --- a/docs/agents/plan-lifecycle.md +++ b/docs/agents/plan-lifecycle.md @@ -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 diff --git a/docs/agents/spec-kit.md b/docs/agents/spec-kit.md index 3477d87d..d00898be 100644 --- a/docs/agents/spec-kit.md +++ b/docs/agents/spec-kit.md @@ -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 diff --git a/docs/agents/tasks.md b/docs/agents/tasks.md index 66b29757..4605f73f 100644 --- a/docs/agents/tasks.md +++ b/docs/agents/tasks.md @@ -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 diff --git a/docs/agents/testing.md b/docs/agents/testing.md index ef8febb8..9998d595 100644 --- a/docs/agents/testing.md +++ b/docs/agents/testing.md @@ -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 diff --git a/docs/development-process.md b/docs/development-process.md new file mode 100644 index 00000000..dd79ac04 --- /dev/null +++ b/docs/development-process.md @@ -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-.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) diff --git a/docs/skills/github-pr-copilot-cycle.md b/docs/skills/github-pr-copilot-cycle.md index 90834afb..eeb40d40 100644 --- a/docs/skills/github-pr-copilot-cycle.md +++ b/docs/skills/github-pr-copilot-cycle.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 diff --git a/docs/skills/speckit-bootstrap.md b/docs/skills/speckit-bootstrap.md index 32686d63..c1f337c1 100644 --- a/docs/skills/speckit-bootstrap.md +++ b/docs/skills/speckit-bootstrap.md @@ -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 diff --git a/docs/skills/speckit-delivery.md b/docs/skills/speckit-delivery.md index c0b19124..431b7413 100644 --- a/docs/skills/speckit-delivery.md +++ b/docs/skills/speckit-delivery.md @@ -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 diff --git a/docs/skills/speckit-reverse-engineer.md b/docs/skills/speckit-reverse-engineer.md index 527e0fc3..868cd615 100644 --- a/docs/skills/speckit-reverse-engineer.md +++ b/docs/skills/speckit-reverse-engineer.md @@ -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 diff --git a/plans/plan-spec-kit-development-process.md b/plans/plan-spec-kit-development-process.md index 6dab73da..5984560f 100644 --- a/plans/plan-spec-kit-development-process.md +++ b/plans/plan-spec-kit-development-process.md @@ -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. | diff --git a/tasks/todo.md b/tasks/todo.md index f0506d10..04989919 100644 --- a/tasks/todo.md +++ b/tasks/todo.md @@ -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.