Spec-Anchored Agentic Development

One durable contract per capability, and the code answers to it — evidence before "done".
A methodology, and a ready-to-install bundle, for building software with AI coding agents:
from the first capability spec to supervised autonomy.

This repository is my agentic development workflow. It is both a guideline (how to work) and an installable bundle (the shared protocol, the workflow skills, two internal authoring agents, engineering rules, authorization policies, executable contracts and templates that make a coding agent actually work this way). The canonical core lives in open, runtime-neutral formats — AGENTS.md, .agents/skills/, .agents/protocols/, .agents/rules/ — so Claude Code, Codex and Cursor read the same source; adaptations/ covers what each harness does differently, and Kiro.

It is maintained as a living reference — when practice conflicts with what's written here, the document is updated, not silently worked around.

The core idea

Spec-anchored: the business decision comes before the code, and the spec stays. It is the permanent source of truth the code answers to — drift is treated as a bug, conformance is checked value by value — not scaffolding discarded once a feature ships.

Where this sits in the field (per the consolidating taxonomy in "Spec-Driven Development: From Code to Contract", 2026, echoed by martinfowler.com's exploring-gen-ai series):

• spec-first — the spec precedes the code but may drift or be discarded (Kiro, Spec Kit).
• spec-anchored — the spec is permanent and the code answers to it continuously. ← this is where this methodology sits.
• spec-as-source — code is generated from the spec. For normative rules, the spec's reference values generate the golden tests that act as the oracle, moving toward this.

The unit of organization is the capability — a cohesive slice of what the system does for the business (payments, orders, notifications), never a technical layer (controllers, repositories) or a bare entity (Product, Customer). Each capability has one durable contract — a stable entrypoint file, with companion files when the capability needs them — you develop from it, and progress in autonomy.

Five fundamental principles

1. Simplest possible change. Delete before you add. No unrequested refactors, no speculative helpers.
2. Root cause, not band-aid. Find why a bug happens; don't hide the symptom.
3. Verification is part of the work, not optional. Every change needs a way to verify it. If you can't verify it, don't merge it.
4. Determinism where you can, agent where you must. Every predictable task becomes a deterministic script the agent calls — the agent is expensive and non-deterministic; a script is cheap and auditable.
5. Machine-produced "no" before human review. Every gate the machine can run (failing test, type error, lint rule, a surviving mutant, a hardener's finding) fires before a human is asked to look. This is backpressure — the check confronts the agent at the boundary.

The trajectory

Identify capabilities → Specification → Development
                                            ↓
                          Operational maturity → Autonomy (narrow start → widening)

The minimum entry point is the first capability spec. You do not need the constitution, the hardeners, the milestones or the rituals to begin — write specs/<capability>/<capability>.md and start. Everything else is how the system scales; each piece enters when its pain shows up.

Autonomy is a gradient, not a switch

The narrow start needs no formal eval suite: issues → an allowlist of trivial classes → CI green mandatory → PR → a human approving every PR — over a safety baseline that cannot wait (branch protection, scoped credentials, no direct push, one issue → one PR, named blockers, human merge). Widening — more classes, more volume, any step toward auto-merge — requires a regression suite with a track record. Normative calculations never enter autonomy before golden/conformance verification exists. The widening path lives in AUTONOMY-PLAYBOOK.md, which splits the last step honestly: M4a is machine approval eligibility (the human still merges); M4b is platform auto-merge, a much higher bar.

What's in this repository

Documents (the methodology)

The entrypoint, the protocol and its three adapters

One state machine, three modes. .agents/protocols/implementation-protocol.md holds phases 0–10, the terminal taxonomy, the invariants and the logging; each implementation skill is a mode adapter that declares only who satisfies each gate.

The two internal authoring agents

Both agents inherit the Owner's model and run at effort=max; no contract pins a model, and the Markdown and TOML forms are validated for parity. Every handoff is a local commit the Owner inspects and explicitly accepts or rejects before integration — agent output is never self-validating. Spec/conformance, constitution, security, performance and systemic-architecture reviews are external to the implementation harness: the review tool or API the repository configures, CI, the orchestrator, a periodic audit, or a human.

Workflow skills

Skills are invoked directly with the runtime's own syntax (/shape in Claude Code, $shape in Codex); the canonical files carry no launcher syntax. Ordinary prose that merely names a skill is not a launch.

Rules, authorization, contracts and the gate

The three modes

All three run the same protocol. They differ only in who answers.

• implement-feature — local and interactive. You resolve ambiguity, you approve the plan (and its APPROVAL-FINGERPRINT), you approve any scope change; a semantic amendment to a spec is possible here, behind an explicit in-session gate, and the PR ratifies it.

• implement-orchestrated — one worker per ticket, dispatched by orchestrate into its own worktree. Its gates live on GitHub: the plan is posted as an issue comment and the run stops until a human replies approved <fingerprint>; ambiguity is a comment plus a label, never a guess.

• implement-backlog — headless. No one is there to answer, so every gate has a mechanical provider or aborts with a named blocker (AMBIGUITY, MISSING_ORACLE, TRUTH_CONFLICT, SCOPE_VIOLATION, SPEC_CHANGE_REQUIRED, SPEC_STALE, GRAPH_DECISION_REQUIRED, ENVIRONMENT, REPEATED_FAILURE). Scope is increments only; new capabilities and large features stay human-led.

Two things hold across all three. After the Owner has implemented and verified, the same internal pipeline runs — General Code Reviewer, Owner disposition, Mutation Hardener, Owner disposition, final deterministic verification — and any later Owner edit invalidates both passes. And no run ever merges: every mode ends at PR_READY_AWAITING_HUMAN, and a human decides.

Installation

See INSTALL.md. In short: copy AGENTS.md, .agents/, agents/, policy/, scripts/ and tests/ into your repository root, keep specs/ and docs/ where the whole team can read them, and put an AGENTS.md/CLAUDE.md next to each capability's code pointing at its spec. Then:

1. Read GUIDELINE.md. The floor is the first capability spec — start there.
2. Run prep once so the repository has the verification interface, the metric-class gates and the ratchet baseline. Verification is what everything else stands on.
3. Shape the first capability spec with shape, write it with to-spec, and let a human ratify it by merging its own PR. Add the constitution when invariant rules demand it.
4. spec-to-tickets breaks the ratified spec into tracer-bullet issues with explicit blocking edges.
5. Run the first slice locally with implement-feature, then explain afterward.
6. Turn on autonomous mode narrow (allowlist + green CI + a human approving every PR); widen only as your eval suite earns trust.

Portability

The methodology has two layers that travel differently:

• Specs and context (Parts 1–2 of the guideline) — capabilities, specs, the AGENTS.md/CLAUDE.md files, the constitution. Tool-portable: any coding agent reads them.
• Automation (Parts 3–5) — the shared protocol and its adapters, the two internal agents, the launchers, the autonomy trajectory. The canonical core is runtime-neutral: Claude Code and Cursor read it as it is; scripts/install-codex-port.sh materializes the disposable .codex/agents/ adapters for Codex and --check catches drift; adaptations/kiro.md documents what does not survive the trip.

The executable contracts under scripts/ are deliberately tool-neutral: dependency-free Python over plain JSON, so any harness can compute the same fingerprint and any CI can recompute the same verdict.

License

MIT.

This document exists to serve the work, not to govern it. When a rule here causes more friction than value, change it — consciously, with a commit and a reason. Silent erosion of discipline is what kills systems like this.