# Decapod
**Decapod is an assurance interface agents talk to: ADVISORY + INTERLOCK + ATTESTATION.**
The human interfaces ONLY with the agent as the UX. The agent calls Decapod.
## What Decapod Really Is
Decapod helps agents:
1. **Build what the human intends** - Through interview-driven spec generation
2. **Follow the rules the human intends** - Through resolved standards and guardrails
3. **Produce the quality the human intends** - Through validation gates and receipts
## Agents Are the Buyer
Agents don't browse. They query. Decapod provides a structured JSON-RPC interface that agents route to for:
- **Next-best question** for the human (spec/architecture interview)
- **Resolved repo standards** (industry defaults + override.md)
- **Drift detection** (prevent contradictions to declared decisions)
- **Proofed "done"** (validate gates + receipts)
- **Safe workspace behavior** (agents cannot touch main)
## Quick Start
```bash
# Install Decapod
cargo install decapod
# Initialize in a repo
decapod init
# Agent workflow
decapod rpc --op agent.init # Required: get session receipt
decapod workspace status # Check if safe to work
decapod workspace ensure # Create isolated branch if needed
decapod validate # Validate before claiming done
```
## Architecture
```
repo/
├── AGENTS.md # Agent entrypoint (thin shim)
├── CLAUDE.md # Claude entrypoint (thin shim)
├── .decapod/
│ ├── data/ # State: SQLite + event logs
│ │ ├── todo.db
│ │ ├── federation.db
│ │ └── *.events.jsonl
│ ├── OVERRIDE.md # Project-specific overrides
│ └── README.md
└── docs/ # Generated by interview engine
├── spec.md
├── architecture.md
├── security.md
├── ops.md
└── decisions/
└── ADR-*.md
```
## Key Capabilities
### Workspace Enforcement (Non-Negotiable)
Agents **cannot** work on main/master. Decapod enforces this programmatically:
```bash
$ decapod validate
❌ VALIDATION FAILED: Workspace Protection Gate
Error: You are on protected branch 'main'
Hint: Run 'decapod workspace ensure' to create an isolated workspace
```
### RPC Interface
Agents query Decapod programmatically:
```bash
$ decapod rpc --op agent.init
{
"success": true,
"receipt": { "op": "agent.init", "hash": "...", "timestamp": "..." },
"allowed_next_ops": [
{ "op": "workspace.ensure", "reason": "Create isolated workspace" }
],
"blocked_by": []
}
```
### Interview Engine
Generate industry-grade docs through structured Q&A:
```bash
decapod rpc --op scaffold.next_question # Get next question
decapod rpc --op scaffold.apply_answer # Provide answer
decapod rpc --op scaffold.generate_artifacts # Generate docs
```
### Standards Resolution
Decapod resolves standards from industry defaults + project overrides:
```bash
decapod rpc --op standards.resolve
```
### Capabilities Discovery
Agents discover what's available:
```bash
decapod capabilities --json
```
## Response Envelope
Every RPC response includes:
- **receipt**: What happened, hashes, touched paths, governing anchors
- **context_capsule**: Minimal relevant spec/arch/security/standards slices
- **allowed_next_ops**: Contract for what to do next
- **blocked_by**: Missing answers/proofs preventing progress
- **interlock**: Binding enforcement with stable code + unblock path
- **advisory**: Non-binding reconciliations + deterministic verification plan
- **attestation**: Structured evidence record suitable for local trace export
## Subsystems
- **todo**: Task tracking with event sourcing (preserved from v0.25)
- **workspace**: Branch protection and isolation (new)
- **interview**: Spec/architecture generation (new)
- **federation**: Knowledge graph with provenance (preserved)
- **container**: Docker + git workspaces (preserved, enhanced)
- **validate**: Authoritative completion gates (enhanced)
## Hard Constraints
- **Single Rust binary/library** - No daemon requirement
- **Local-first, repo-native** - Everything auditable on disk
- **Deterministic > vibes** - Summarizes canon text, never decides what is binding
## License
MIT