A framework for agent-driven development: design the system, not the agent.
Agents — like the humans they collaborate with — forget context, drift from conventions, infer requirements that were never agreed to, and declare work complete before it is verified. Armature treats these as properties to design around, not defects to correct. It structures the collaboration as a system: layered defense from agent direction out to CI, state carried in artifacts rather than memory, and automated mechanisms wherever a check could otherwise depend on someone remembering to run it.
This repo contains the method and a working reference implementation, extracted from the production system it was developed in and sanitized for public release.
| Path | What it is |
|---|---|
METHOD.md |
The Armature Method itself — tenets, the six-layer defense model, work-decomposition invariants, the delivery arc, catch economics, and how to measure the system. Start here. |
plugins/armature-plan/ |
Claude Code plugin: the /armature-plan command drives a phased planning-and-delivery workflow (constraints → decomposition → scaffold → parallel implementation → review → test → closeout) with typed agent personas, structured hand-off envelopes, and quality gates. |
plugins/epic-design/ |
Claude Code plugin: the /epic-design command drives four-phase epic-constraints authoring (Discovery → Reconnaissance → Constraints draft → Ratify) against a binding nine-section template. |
coordinatorlint/, armature/, cmd/ |
Go library + commands that mechanically verify workflow artifacts: hand-off envelope schema, agent-persona integrity, quality-gate configuration, permission profiles (generic / PHI / PCI), destructive-operation manifests. The workflow is prose; this is the part that makes the prose checkable. |
shim/knowledge-layer/ |
A minimal, file-backed reference implementation of the Knowledge Layer MCP interface the plugins expect (kl_* tools: knowledge entries, work ledger, FSM transitions). Enough to run the workflows end-to-end at demo scale. |
docs/audit-instrument.md |
A blank audit template for periodically verifying an Armature implementation — control inventory and measured adherence. The audit is itself a control. |
docs/kpis.md |
Catch-economics KPI definitions: production escape rate, catch-distribution profile, cost-weighted catch depth. |
hooks/ |
Reference git-hook templates (pre-commit, pre-push) and the hook-liveness check that tenet 2 demands. |
Read the method: METHOD.md. It is self-contained and tool-agnostic.
Install the plugins (Claude Code):
claude plugin marketplace add solventgrun/armature
claude plugin install armature-plan@armature
claude plugin install epic-design@armatureRun the Knowledge Layer shim so the plugins have a knowledge store and work ledger to talk to — see shim/knowledge-layer/README.md for the MCP registration snippet.
Build the verification tooling:
go build ./...
go test ./...The method names a "knowledge store" generically, and the plugins speak to it through a fixed MCP tool surface (kl_search, kl_blast_radius, kl_backlog_*, kl_story_*, …). The shim in this repo is a deliberately small reference implementation of that surface — single-user, file-backed, no auth. It exists so the workflows are runnable out of the box and so the interface contract is executable documentation. A production-grade knowledge-graph server implementing the same surface is a separate system and is not included here; anything that serves these tools works.
The method is v3.0 and in daily production use; every protocol in it traces to a real incident or a predictable class of error. The plugins and lint tooling are the same code that runs that production workflow, with project-specific references removed. The knowledge layer this method prescribes has been empirically tested: tenancy-bench is a with-KL vs. without-KL ablation across four models (4,000 runs) measuring when a knowledge layer helps, hurts, or does nothing for coding agents.
MIT — see LICENSE.