Appearance
SGE governance guide
For developers. SGE (Specification-Governed Development) is how this repo keeps code traceable to an approved spec. For setup, architecture and tests see the Developer guide.
The artefacts
| Artefact | Path | What it is |
|---|---|---|
| Vision | docs/vision.md | Why the product exists, non-goals, success measures (SM-n). |
| Capability model | .claude/product-context/capability-model.yaml | The capabilities (CAP-nn.n), each naming the spec that governs it. Versioned. |
| Feature specs | docs/features/SPEC-NNN-<slug>.md | One per slice. Front matter: ref, capability, status, questions, decisions. |
| ADRs | docs/decisions/NNNN-<slug>.md | One decision each, with context, decision and consequences. |
| Open questions | docs/sge/questions.md | The QD-NN registry of questions for the Product Owner. |
| Not doing | docs/not-doing.md | Out-of-scope items and why. |
| Change protocol | docs/sge/change-protocol.md | The 7 steps, spec status, trailers, migration rules, enforcement. |
Specs and scenarios
A spec states the business intent, scope and numbered scenarios in Given/When/Then form (S1, S2, ...). Tests carry the scenario in their name, for example SPEC-003 S38: ..., so a scenario can be found from the spec and a test from its spec. A spec's status is draft, approved (scope agreed, exit test not yet passed), implemented (the Product Owner ran the exit test on real data) or superseded. A slice is done only when the exit test passes on real data.
Check not-doing before adding scope. Adding something there to scope needs a Product Owner decision recorded as an ADR.
ADRs and questions
- An ADR records a decision and is not edited once accepted; a new one supersedes it. Numbers are never reused.
- An open question is a QD-NN entry with question, stakeholder, raised date and status (
Open, orClosed/Decidedwith the decision, who, and when). A closed entry is never edited; a new QD supersedes it. Specs list the QDs and ADRs they depend on in front matter. - Never assume an answer to an open question or an unfilled placeholder. Ask.
Change protocol
The 7 steps: LOCATE the spec and capability, READ the spec and its criteria, assess IMPACT, PROPOSE the plan in TDD slices, IMPLEMENT test first, TEST the full suite, UPDATE specs, ADRs and docs with the code.
Commit trailers
Every commit carries exactly one trailer, enforced by .githooks/commit-msg:
Spec: SPEC-NNNfor a commit that implements a spec.SGE-Override: <STEP>; <reason of at least 10 characters>for governance, infra or docs work that maps to no single spec.STEPis one of LOCATE, READ, IMPACT, PROPOSE, IMPLEMENT, TEST, UPDATE, ALL.
Merges, fixups, squashes and reverts are skipped. Never use --no-verify. Commit through /sge:commit and the right trailer is added. Run git config core.hooksPath .githooks once per clone.
From issue to deploy
- Issue. Raised on GitHub (
FEAW-Serv/getmy-books) and approved by the Product Owner. Usegh; the SGE plugin's GitHub flow runs natively (ADR 0046). - Spec. Governance trace decides whether it matches an existing spec, changes one, needs a new spec, or needs none (chore). New or changed scope is agreed with the Product Owner first and recorded in the spec.
- Failing test. Write the scenario's test and see it fail (
SGE_ENFORCE=tddblocks production edits until there is test evidence). - Minimum code. Make it pass, refactor, keep lint and typecheck clean.
- Commit and PR. One agent, one branch, one worktree. Commit with the trailer; open a PR on GitHub (
gh pr create). - Review. One reviewer per PR against the spec (
/sge:pr-review). - Merge. Merged one at a time, with the PR closed only after local main equals remote main.
- Deploy. The pipeline migrates and deploys main; check
/healthshows the commit. - Exit test. The Product Owner runs the spec's exit test on real data; only then does the spec become
implemented.
/sge:sge-align checks for governance drift. It is a check you run at the end of a slice and before a release, not a CI gate.