Skip to content

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 ​

ArtefactPathWhat it is
Visiondocs/vision.mdWhy the product exists, non-goals, success measures (SM-n).
Capability model.claude/product-context/capability-model.yamlThe capabilities (CAP-nn.n), each naming the spec that governs it. Versioned.
Feature specsdocs/features/SPEC-NNN-<slug>.mdOne per slice. Front matter: ref, capability, status, questions, decisions.
ADRsdocs/decisions/NNNN-<slug>.mdOne decision each, with context, decision and consequences.
Open questionsdocs/sge/questions.mdThe QD-NN registry of questions for the Product Owner.
Not doingdocs/not-doing.mdOut-of-scope items and why.
Change protocoldocs/sge/change-protocol.mdThe 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, or Closed / Decided with 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-NNN for 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. STEP is 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 ​

  1. Issue. Raised on GitHub (FEAW-Serv/getmy-books) and approved by the Product Owner. Use gh; the SGE plugin's GitHub flow runs natively (ADR 0046).
  2. 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.
  3. Failing test. Write the scenario's test and see it fail (SGE_ENFORCE=tdd blocks production edits until there is test evidence).
  4. Minimum code. Make it pass, refactor, keep lint and typecheck clean.
  5. Commit and PR. One agent, one branch, one worktree. Commit with the trailer; open a PR on GitHub (gh pr create).
  6. Review. One reviewer per PR against the spec (/sge:pr-review).
  7. Merge. Merged one at a time, with the PR closed only after local main equals remote main.
  8. Deploy. The pipeline migrates and deploys main; check /health shows the commit.
  9. 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.