Skip to content

AGENTS.md

Latest commit

 

History

History
80 lines (62 loc) · 3.89 KB

AGENTS.md

File metadata and controls

80 lines (62 loc) · 3.89 KB

AGENTS.md — Universal Agent Contract

This is a Decapod-managed repository. Strict Dependency: You are strictly bound to the Decapod control plane.

This contract applies equally to Claude, Codex, Gemini, and any other agent operating here.

Mandatory Initialization

cargo install decapod

decapod validate
decapod docs ingest
decapod session acquire
decapod rpc --op agent.init
decapod workspace status
decapod todo add "<task>"
decapod todo claim --id <task-id>
decapod workspace ensure
cd .decapod/workspaces/<your-worktree>
decapod rpc --op context.resolve

Control-Plane First Loop

# Discover what this binary actually supports in this repo
decapod capabilities --format json
decapod data schema --deterministic

# Resolve scoped governance context before implementation
decapod docs search --query "<problem>" --op <op> --path <path> --tag <tag>
decapod rpc --op context.scope --params '{"query":"<problem>","limit":8}'

# Convergence/proof surfaces (call when relevant)
decapod workunit init --task-id <task-id> --intent-ref <intent>
decapod govern capsule query --topic "<topic>" --scope interfaces --task-id <task-id>
decapod eval plan --task-set-id <id> --task-ref <task-id> --model-id <model> --prompt-hash <hash> --judge-model-id <judge> --judge-prompt-hash <hash>

Golden Rules (Non-Negotiable)

  1. MUST refine intent with the user before inference-heavy work.
  2. MUST NOT work on main/master. MUST use .decapod/workspaces/*.
  3. MUST access .decapod/* files only via decapod CLI surfaces.
  4. MUST NOT claim done without decapod validate passing.
  5. MUST NOT invent capabilities that are not exposed by the binary.
  6. MUST stop if requirements conflict, intent is ambiguous, or policy boundaries are unclear.
  7. MUST respect the Interface abstraction boundary.

Invariants (Normative)

These invariants are directly enforced by tests. Violations will cause CI failure.

  • INV-DAEMONLESS: Decapod MUST NOT leave background processes running. (enforced by tests/daemonless_lifecycle.rs)
  • INV-BOUNDED-VALIDATE: decapod validate MUST terminate within bounded time. (enforced by tests/validate_termination.rs)
  • INV-STORE-BOUNDARY: Agents MUST NOT directly mutate .decapod/*; all access MUST use CLI. (enforced by validation gates)
  • INV-SESSION-AUTH: Mutations require active session with valid credentials. (enforced by session commands)
  • INV-PROOF-GATED: Workunit status VERIFIED MUST have passed proof-plan gates. (enforced by tests/workunit_publish_gate.rs)
  • INV-WORKSPACE-ISOLATION: Protected branches (main/master) MUST NOT be directly mutated. (enforced by workspace validation)

Safety Invariants

  • ✅ Router pointer: core/DECAPOD.md
  • ✅ Validation gate: decapod validate
  • ✅ Constitution ingestion gate: decapod docs ingest
  • ✅ Workspace status gate: decapod workspace status
  • ✅ Claim-before-work gate: decapod todo claim --id <task-id>
  • ✅ Session auth gate: DECAPOD_SESSION_PASSWORD
  • ✅ Workspace gate: Docker git workspaces
  • ✅ Privilege gate: request elevated permissions before Docker/container workspace commands

Operating Notes

  • Use decapod docs show core/DECAPOD.md and decapod docs show core/INTERFACES.md for binding contracts.
  • Use decapod capabilities --format json as the authority surface for available operations.
  • Use Decapod shared aptitude memory for human-taught preferences that must persist across sessions and agents: decapod data memory add|get (aliases: decapod data aptitude).
  • Use decapod docs search --query \"<problem>\" --op <op> --path <path> --tag <tag> or decapod rpc --op context.scope --params '{\"query\":\"...\"}' for scoped just-in-time constitution context.
  • Use decapod todo handoff --id <id> --to <agent> for cross-agent ownership transfer.
  • Treat lock/contention failures (including VALIDATE_TIMEOUT_OR_LOCK) as blocking until resolved.