# AGENTS.md - Universal Agent Entrypoint

**This is a Decapod-managed repository.**

## Required Protocol

**⚠️ MANDATORY START SEQUENCE - Run these EVERY session before ANY work:**

```bash
cargo install decapod              # 1. Install/update to latest release
decapod --version                   # 2. Check installed version
decapod update                      # 3. Update if repo version is newer (safe no-op if current)
decapod --help                      # 4. Verify available commands
decapod docs show core/DECAPOD.md  # 5. Refresh constitution
decapod validate                    # 6. Check system state
decapod todo list                   # 7. See active work
```

**Why this is mandatory:** The decapod binary evolves. Commands change. Constitution updates. Always install the latest release first, then 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 Router (Start Here)
- `core/DECAPOD.md` — **Router and navigation charter**

### Authority (Constitution Layer)
- `specs/INTENT.md` — **Methodology contract (READ FIRST)**
- `specs/SYSTEM.md` — System definition and authority doctrine
- `specs/SECURITY.md` — Security contract
- `specs/GIT.md` — Git etiquette contract
- `specs/AMENDMENTS.md` — Change control

### Registry (Core Indices)
- `core/PLUGINS.md` — Subsystem registry
- `core/INTERFACES.md` — Interface contracts index
- `core/METHODOLOGY.md` — Methodology guides index

### Contracts (Interfaces Layer)
- `interfaces/CONTROL_PLANE.md` — Sequencing patterns
- `interfaces/DOC_RULES.md` — Doc compilation rules
- `interfaces/STORE_MODEL.md` — Store semantics
- `interfaces/CLAIMS.md` — Promises ledger
- `interfaces/GLOSSARY.md` — Term definitions

### Practice (Methodology Layer)
- `methodology/SOUL.md` — Agent identity
- `methodology/ARCHITECTURE.md` — Architecture practice
- `methodology/KNOWLEDGE.md` — Knowledge curation
- `methodology/MEMORY.md` — Memory and learning

### Operations (Plugins Layer)
- `plugins/TODO.md` — **Work tracking (PRIMARY)**
- `plugins/VERIFY.md` — Validation subsystem
- `plugins/MANIFEST.md` — Canonical vs derived vs state
- `plugins/EMERGENCY_PROTOCOL.md` — Emergency protocols
