Codex Machinae

Codex Machinae

A process playbook for building, testing, and maintaining software with AI agents as collaborators. It prescribes how to work — requirements, structure, quality, testing, remediation — never what to build.

Everything activates by trigger. This file carries the steps and the routing; the deep rules live in reference/ and are loaded only when their condition fires. Loading reference that no trigger asked for is a violation of the playbook's own first principle (Emergent Expansion).

Section references like §5.3 resolve inside reference/core.md; D1…D7, M1…M4, and Appendix A…D name files under reference/domains/, reference/modules/, and reference/appendices/.

Loading reference/core.md is always legitimate — it is the Core, and a § pointer narrows where to read inside it, not whether to load it. Emergent Expansion's no-untriggered-loading rule governs the domain, module, and appendix files.

Operating rules — always apply

1. Read the repo's agent-configuration file before any action. Update PROJECT_STATUS.md at session end — four sections: Objective, Modified Files, Logical State, Next Action (§2.3).
2. A project-size profile — Solo, Small, or Large — must be declared in the agent config; it modulates every checklist obligation (§2.5). The profile, the issue-tracker binding (where §1.9 maps and §10 tracking issues publish), and the autonomy posture are seeded by the sibling setup-codex-machinae skill — when one is missing where needed, point the human to it rather than inventing a value.
3. Emergent Expansion (§2.2): no folder, file, or process exists until a trigger fires. Propose expansions as "I suggest adding <path> to cover <concern> because <trigger>. Cost of omission: <what breaks>" — and wait for acceptance. Propose removal when a trigger lapses.
4. Autonomy is bounded (§12.1–§12.5): touch only the client/adapter layer and tests unless directed otherwise; ship a regression test with every fix; for complex features propose the approach in writing and await approval before code; never claim an action you did not perform.
5. An item is done only when the Core Definition of Done passes and every contextual check is satisfied or recorded n/a — never silently skipped (§1.8).
6. More than one agent on the repo → load the coordination protocol first (§12.7): lead designation, scope partitioning, single-writer artefacts.

Route by situation

When more than one row matches, the causal trigger wins — route on the event that started the situation, not its symptoms. Red tests caused by a dependency bump take the break route, not Phase 2.

Lifecycle

Phase 0 — Ideation and requirements (§11.1, checklist A.1)

0. If the effort exceeds one agent session and open decisions block the PRD: run decision mapping (§1.9) — chart the decisions as a map of typed tickets (research / prototype / grilling / task), resolve one per session, collapse the cleared map into the artefacts below. Plan, don't do: no production code while a map is open.
1. Write the PRD — what and why, never how (§1.2).
2. User stories with binary acceptance criteria, each falsifiable at the starting commit; stories cut as vertical slices sized to one agent session (§1.3–§1.4).
3. ADRs for decisions passing the three-test bar: hard to reverse, surprising without context, real trade-off (§1.5).
4. State-of-the-art research when a §1.7 trigger fires; findings land in the research register.
5. Backlog ordered by priority (§1.6); Definition of Done agreed (§1.8); critical dependencies in DEPENDENCIES.md.

Done when: checklist A.1 passes for the declared profile. The checklist is a gate artefact — consult it here, not at entry; while a §1.9 map is open, Phase 0 has not begun and A.1 has nothing to grade yet.

Phase 1 — Technical bootstrap (§11.2, checklist A.2)

Minimum Core of Existence only — README.md, PROJECT_STATUS.md, agent config (§2.1) — then: linting/formatting hooks (§3.4), base CI (§7), initial Boundary Contract Map (§8), .env.example where secrets exist (§4.3).

Done when: checklist A.2 passes; CI is green on an empty-but-real build.

Phase 2 — Active development (§11.3, checklists A.3–A.4)

The loop, per user story: respect the DoD; tests at every appropriate tier of the pyramid (§5); coverage ratchet never loosens (§5.3); Conventional Commits (§3.3); CHANGELOG on user-visible change (§6.3); contract map updated after significant refactors (§8).

Phase 3 — Maturity (§11.4) · Phase 4 — Major upgrade (§11.5)

Phase 3: fixes ride the autonomy ladder (below); quarterly threshold review. Phase 4: a major dependency upgrade disables L1 — everything is human-led until the contract map is regenerated and the harness re-verified.

Phase R — Retrofit (§11.6, template B.9)

For codebases that predate the playbook. One-time convergence, not a phase sequence: debt-scoping audit → retroactive contract map → adoption in tiers (T1 safety net, then T2 structure, then T3 process; T1 is non-negotiable and first). Enter the lifecycle at Phase 2 or 3 when T1+T2 are complete.

Done when: checklist A.8 passes; T1 and T2 tiers complete.

When something changes or breaks

1. Classify the change (§9): bucket + severity (safe / additive / breaking / p0), checked against the never-auto-merge list (§9.3).
2. Remediate on the autonomy ladder (§10.1): L0 auto-merge (safe, green tests) · L1 agent PR with fix-claim behind the correctness gate (§10.2) · L2 human-led (breaking, p0, or missing machinery). Circuit breaker: 3 open L1 PRs or 5 attempts in 14 days pauses automation and produces a handover dossier (§10.3–§10.4).
3. Wide mechanical refactors that defeat vertical slicing are sequenced as expand–contract (§10.7).

Domain appendices — load on trigger

Cross-cutting modules — load on trigger

Reference index

• reference/core.md — the full Core: §1 requirements (incl. §1.9 decision mapping), §2 structure and profiles, §3 quality, §4 security, §5 testing, §6 documentation, §7 CI/CD, §8 boundary contracts, §9 classification, §10 remediation, §11 lifecycle, §12 agent conventions.
• reference/appendices/A-checklists.md — per-phase checklists, profile-aware. Consult at every phase gate.
• reference/appendices/B-templates.md — PRD, story, ADR, dependencies, contract map, retrofit audit, decision map templates. Copy, never retype.
• reference/appendices/C-glossary.md — the vocabulary; consult when a term in this file is unfamiliar.
• reference/appendices/D-tooling.md — specifications for the AST Walker, Coverage Ratchet, and Surveillance Agent scaffolds.
• reference/limitations.md — what the playbook deliberately does not cover.

Codex Machinae is licensed CC BY 4.0. Attribution: "Codex Machinae — https://github.com/SOsintOps/codex-machinae". The reference tree is generated from the repository's playbook/ sources by tools/build.py; edit the sources, not the copies.