Get running
That's it. decapod init asks about your project (name, intent, language, architecture direction) and scaffolds industry-grade specs.
Your workflow doesn't change. Your agent calls Decapod before:
- Acting — intent
- Calling the model — context
- Committing — proof
- Touching protected code — boundaries
Decapod is designed to stay out of the human workflow. The agent checks in. You keep talking to your agent like normal. See the canonical router in constitution/core/DECAPOD.md.
AI agents do not fail because they lack tools. They fail because they lose intent, skip dependencies, mutate context unsafely, and return vibes instead of proof.
The loop
User
│
▼
Agent ───────┐
│ │
│ ┌────▼────┐
│ │ Decapod │
│ │ (check) │
│ └────┬────┘
│ │
├─────────┤
│ │
Model Agent
│ │
└────┬────┘
▼
User
What Decapod does
- Clarifies intent — What's the goal?
- Bounds context — Only what's needed. Not the whole repo.
- Enforces proof — VERIFIED means gates passed.
- Protects boundaries — No direct writes to master.
Decapod resolves only what's relevant to the user's intent — no context poisoning. Your agent gets surgical context, not the entire constitution.
Agent workbenches improve the session. Decapod improves the shared substrate.
- Agents act in private context; Decapod makes their work public to the repo.
- A task started by one agent provider should be understandable, auditable, or resumable by another. The source of truth lives in
.decapod/, not in chat history, IDE state, or provider memory. - The durable parts of agentic work—intent, resolved context, boundaries, todos, specs, validation, proof artifacts—become repo-native operational knowledge.
Decapod absorbs agent deficiencies: ambiguity, context waste, boundary drift, forgotten dependencies, unsafe mutation, and unverifiable "done."
The shared substrate
decapod/
generated/
specs/ # INTENT.md, ARCHITECTURE.md, etc.
context/ # deterministic context capsules
artifacts/ # proof artifacts, provenance
governance/ # todos, claims, workunits
data/ # durable state
This is what persists. Not the chat transcript.
The constitution
Decapod ships with an embedded engineering constitution.
Over 100 industry-grade declarative documents covering architecture, security, performance, testing, knowledge graphs, claims, proof surfaces, interfaces, evaluation criteria, and workflows. Everything an engineering org usually keeps in scattered docs, tribal memory, and review culture becomes executable guidance your agent can consult.
Recent research has confirmed what Decapod was built around from the start: AI coding agents waste significant context on irrelevant files. — arXiv:2602.11988
Your agent doesn't guess. It reads the constitution. It cites claim IDs. It follows gates. It asks for clarification. It produces proof.
Your interface
Override the embedded constitution with .decapod/OVERRIDE.md. Plain English rules that take precedence:
.decapod/
OVERRIDE.md # your rules, overrides embedded defaults
Your overrides augment the constitution automatically.
Project config
.decapod/config.toml is your project's control plane configuration. Think of it like an ansible.cfg or pyproject.toml — it captures the high-level scope and details of your project:
- Project name and summary
- Primary language(s)
- Architecture type (webapp, microservice, library, etc.)
- Entrypoints for different agents (CLAUDE.md, GEMINI.md, etc.)
You can edit this file directly or let the agent update it as your project evolves. The generated agent entrypoints tell agents to read it before planning and keep it aligned when user intent or project direction changes.
For rules that override the embedded Decapod constitution, use .decapod/OVERRIDE.md. Keep .decapod/config.toml focused on project context and setup preferences.
Proof lives in the repo
Every run leaves its operational evidence in .decapod/:
- captured intent →
generated/specs/INTENT.md - resolved context →
generated/context/ - todos and dependencies →
governance/todos.jsonl - verification results →
generated/artifacts/ - proof artifacts →
generated/artifacts/provenance/
That directory is the proof surface. It can be inspected locally, reviewed in pull requests, archived with the codebase, and used by the next agent invocation to re-establish state.
The repo remembers. Chat history doesn't.
Agent Workbench Gaps
| What workbenches optimize | What Decapod preserves |
|---|---|
| The current session | Reusable repo-native knowledge |
| Worker throughput | Shared substrate quality |
| Provider-specific context | Explicit intent, boundaries, proof |
| Session-scoped memory | .decapod/ durable state |
Multi-provider continuity: A task started by Claude Code should be auditable by Codex, resumable by Gemini CLI, and verifiable by Kilo. The source of truth is .decapod/, not chat history, IDE state, or provider memory.
Use whatever agent you already use: Claude, Codex, Gemini, Cursor, Kilo.
What you get
- No daemon.
- No SaaS control plane.
- No hidden agent memory.
- Full operational state stored locally in
.decapod/. - Proof your team can inspect, diff, review, and commit.
Before / After
Before
User: "build auth"
Agent: [full repo in prompt]
→ generates
→ commits
After
User: "build auth"
Agent: [Decapod]
→ intent: auth system
→ context: src/auth/
→ generates
→ [Decapod]
→ proof: verified
→ commits
Running
Use whatever agent you already use: Claude, Codex, Gemini, Cursor.
Guarantees
- Daemonless — runs on-demand
- Repo-native — state in
.decapod/ - Proof-gated — VERIFIED means gates pass
- Boundaries enforced — protected branches locked
Contributing
&&