Each file here describes one functional area of the product — what it does, where it lives in the code, the contract it must honour, and its known gaps. They are modelled on the way a game's specs describe its battle, magic, and inventory systems: a faithful description of the intended behaviour that the build loop reconciles the code against.
Filenames are topics, not ordered identifiers — there are no number
prefixes, because numbering implies a priority the specs don't have.
Priority lives in ../IMPLEMENTATION_PLAN.md.
These specs are not RFCs. The RFCs in
../../../docs/rfcs/ are the normative governance
layer ("the constitution"); the loop respects them as constraints but
never reads or edits them. Specs are the functional description of the
actual codebase. A spec may cite a principle as a constraint; it never
restates one and never lives in docs/rfcs/.
Start with overview.md, then:
- Modes:
triage-mode.md,mentoring-mode.md,drafting-mode.md,pairing-mode.md. - Cross-cutting:
security-issue-lifecycle.md,release-management-lifecycle.md,privacy-llm-gate.md,agent-isolation-sandbox.md,cve-tooling.md,adoption-and-setup.md,adapters.md,project-agnosticism.md,meta-and-quality-tooling.md,spec-loop-runner.md,security-reporting.md,reviewer-routing.md,skill-reconciler.md,security-model-preparation.md,marketplace-distribution.md,organization-adapters.md,issue-management-family.md,pr-management-family.md,repo-health-family.md,contributor-growth.md,contributor-offboarding.md,good-first-issue-sweep.md,codex-runtime.md,copilot-runtime.md,maintainer-education.md,spec-gap-staleness.md,batch-write-lock.md,batch-failure-budget.md,vetted-command-surface.md,adversarial-review.md,sandbox-diagnostics.md,container-gateway.md,sbom-pipeline.md.
(Agentic Autonomous, the fifth MISSION mode, is deliberately off and has no
spec — see the note in overview.md.)
Frontmatter:
---
title: <functional area>
status: experimental # stable | experimental | proposed | off
kind: feature # feature | fix | docs | chore
mode: Triage # Triage | Mentoring | Drafting | Pairing | infra
source: <MISSION.md clause / code paths this area is grounded in>
acceptance:
- <verifiable criterion>
---Body sections: What it does, Where it lives, Behaviour & contract, Out of scope, Acceptance criteria, Validation, and (optional) Known gaps — the gaps are what the loop's plan pass turns into work items.
Status mirrors docs/modes.md: stable,
experimental, proposed (designed in MISSION, no code yet), off
(deliberately not built).
- Name the file for its topic (no number prefix).
- Fill in the frontmatter and the body sections above.
- Keep Acceptance criteria and Validation objective — they are the loop's backpressure.