spec/ — the canonical language-agnostic process

Generated from the repo

This page is spec/README.md, copied in at build time.

This is the source of truth for everything a conforming repo carries, independent of its implementation language. A repo consumes these files by vendoring a read-only copy into its own docs/process/ via the sync mechanism (sync/SYNC.md); it never edits a vendored copy. Edit the spec here.

The rule: this repo owns the SPEC (these files); each consuming repo owns its language’s IMPLEMENTATION. Nothing here is normatively language-specific.

File	What it governs
lifecycle.md	The factory’s path from a one-line idea to a monitored service: each stage’s artifact, gate and decider, and how autonomy is granted by risk class. Start here.
session-types.md	The typed sessions that run the lifecycle, each a contract: trigger, inputs, outputs, gate, scope, who is in the loop, home.
process-guide.md	The engineering lifecycle: the phases and the Definition of Done a service moves through, with tools per phase. Informative; the other files are normative.
service-conventions.md	The §1–10 operational + HTTP contract surface: API description, health, telemetry, logging, trace propagation, container interface, event envelope, purity, variation behind a contract with every flag defaulted, the problem document.
deployment-conventions.md	The deployment contract: runtime reproducible from files, migrations as a release step, secrets and fail-fast, health wiring, the smoke gate, CD from main.
gate-discipline.md	What makes a gate script’s verdict trustworthy: one script, the gate order, declared inputs, committed failing fixtures, exit codes, coverage ratchets, nothing without a caller.
adr-discipline.md	How decisions are recorded (Context → Decision → Consequences), numbered, superseded; process-level vs repo-level ADRs.
adr-template.md	The single-ADR template to copy.
concept-note-structure.md	The learning curriculum: the fixed concept-note form and the onboarding-path discipline.
session-ritual.md	The begin/wrap work-session ritual, the handoff format, and the ephemeral-briefs lifecycle.

Changing any file here is a spec change: bump the repo VERSION per the policy in CLAUDE.md (patch = clarification, minor = additive obligation, major = breaking), so consumers see the drift and re-sync deliberately.