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

# 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:

$ 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:

$ 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:

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:

decapod rpc --op standards.resolve

Capabilities Discovery

Agents discover what's available:

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