flowhawk AGENTS.md

AGENTS.md — Universal Agent Contract

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

Mandatory Orientation

Before performing any Decapod operations beyond help/version checks, you MUST ingest the Agent API Orientation corpus from the Decapod binary:

decapod docs ingest

This command outputs the embedded agent documentation (api-index.md, command-contracts.md, payload-examples.md, error-recovery.md, state-model.md, config-schema.md, mcp.md) directly from the binary — no filesystem reads required.

Note on Constitution vs Docs: Agents use decapod constitution to discover technology, primitives in software engineering and delivery, and for scoping pre-inference context. Agents use decapod docs to access the embedded agent-facing methodology documentation (restricted to docs/agent/).

Mandatory Initialization

# Smart bootstrap: only install/init if a newer version is available
(decapod capabilities --format json | grep -q '"is_latest":true') || (cargo install decapod && decapod init --proof)
decapod docs ingest && decapod validate && decapod session acquire
decapod rpc --op agent.init
decapod workspace status
decapod todo add "<task>" && decapod todo claim --id <task-id>
decapod infer orientation --task-id <task-id>
decapod workspace ensure
cd .decapod/workspaces/<your-worktree>
decapod constitution get core/DECAPOD
decapod rpc --op context.resolve

Control-Plane First Loop

decapod capabilities --format json
decapod data schema --deterministic
decapod infer orientation --intent "<your-goal>" --task-id <id>
decapod govern capsule query --topic "<topic>" --scope interfaces --task-id <task-id>
decapod constitution search --query "<problem>"

Pre-Inference Governance

Decapod is pre-inference faculty, not post-hoc validation.

• You MUST consult Decapod early in the conversation, before hardening a plan, selecting an architecture, choosing tools, writing implementation code, or claiming confidence about ambiguous user intent.
• Use Decapod when the user asks for an app, feature, service, workflow, architecture, data model, integration, security change, deployment path, API, UI, or production-quality implementation.
• Start with core/DECAPOD for broad prompts. Use core/* nodes as secondary routers. Use non-core nodes as institutional doctrine.
• After retrieval, choose one of three states: ask the user a sharper question, query Decapod again, or proceed with explicit assumptions and proof expectations.
• Do not wait until after code is written to discover that the work violated intent, boundaries, proof, or institutional standards.