# AGENTS.md - Universal Agent Entrypoint
**This is a Decapod-managed repository.**
## Required Protocol
**⚠️ MANDATORY START SEQUENCE - Run these EVERY session before ANY work:**
```bash
decapod --version # 1. Check installed version
decapod update # 2. Update if repo version is newer (safe no-op if current)
decapod --help # 3. Verify available commands
decapod docs show core/DECAPOD.md # 4. Refresh constitution
decapod validate # 5. Check system state
decapod todo list # 6. See active work
```
**Why this is mandatory:** The decapod binary evolves. Commands change. Constitution updates. You MUST update on version mismatch, verify what's available, and refresh your understanding before acting. Skipping this causes errors.
**After the start sequence:**
1. **Use the control plane**: All shared state goes through `decapod` commands (never bypass)
2. **Proof gates matter**: Run `decapod validate` before claiming "verified" or "compliant"
3. **Interface abstraction boundary**: Preserve control-plane opacity. In operator-facing output, report intent, actions, and outcomes; keep Decapod command surfaces non-presentational unless diagnostics are explicitly requested.
If the router is missing or `decapod` command doesn't exist, **stop and ask the human for the entrypoint.**
## The Four Invariants
Every agent working in this repo MUST:
1. ✅ **Start at the router** - `decapod docs show core/DECAPOD.md` is your navigation charter
2. ✅ **Use the control plane** - `decapod` commands are the interface to shared state (TODOs, proofs, etc.)
3. ✅ **Pass validation** - `decapod validate` must pass before claiming completion
4. ✅ **Stop if router missing** - If Decapod doesn't exist, ask for guidance
**Contract breach**: If you cannot comply (missing router, missing commands, validation fails), you MUST stop, explain what's blocking, and ask for human direction.
## Why This Works
- **Single source of truth**: All authority lives in the embedded constitution (accessed via `decapod docs`)
- **Shared state**: Multiple agents can coordinate via the control plane
- **Proof gates**: `decapod validate` prevents unverified work from passing
- **Store purity**: The control plane enforces state boundaries
## Operating Guidance (Non-Binding)
Think of yourself as a **complete engineering organization**, not just a coder:
- Product Manager: clarify requirements, scope
- Architect: design, tradeoffs, boundaries
- Project Manager: break work into tasks (`decapod todo`)
- Principal Engineer: code quality, tests, patterns
- DevOps/SRE: deployment, reliability, validation
- Security: threat model, secure defaults
This is **guidance**, not **contract**. The binding requirements are the four invariants above.
See `decapod docs show plugins/WORKFLOW.md` for the full operating loop.
## Project-Specific Overrides
This repo may customize behavior via `.decapod/OVERRIDE.md`. Run `decapod docs show <path>` to see merged content.
## Links
- `core/DECAPOD.md` — **Router (start here)**
- `core/CONTROL_PLANE.md` — Sequencing patterns
- `specs/INTENT.md` — Authority contracts
- `specs/ARCHITECTURE.md` — System boundaries
- `core/PLUGINS.md` — Subsystem registry