# Canon
> The field of agentic engineering, distilled for agents.

An encyclopedia (Vol. I–X) plus an operating layer: job packs, playbooks, recipes, named failures, a skill library, and a reviewer.
Do not ingest the atlas. Load this file, pick a job or a skill, load that pack.

## How to use
1. Identify the job (coding-agent, research-agent, support-agent, document-agent, browser-agent, workflow-pipeline, multi-agent-crew, mcp-server, skill-pack, eval-platform, production-agent).
2. GET /api/canon/jobs/{jobId}?format=md — load only that pack. Or GET /api/canon/skills for the skill index (name+description), then GET /api/canon/skills/{id}?format=md.
3. Follow the playbook. Copy recipes. Refuse named failures.
4. Unsure of topology? GET /api/canon/decide?path=&work=&split=&gate=
5. Reviewing a design? POST /api/canon/review with {"text": "..."} .
6. Need one article? GET /api/canon/articles/{id}?format=md

## Always-on doctrine
The loop: context → structured next step → execute → compact-append. Termination, sandbox, context builder, eval set, pause API must be named.
- 1. Natural language to tool calls — Map user language onto structured intent. The model proposes; code dispatches.
- 2. Own your prompts — Prompts are source code. Diff them, test them, do not inherit a black box.
- 3. Own your context window — Build the working set explicitly. The window is a product, not a log.
- 4. Tools are structured outputs — A tool call is JSON. The ACI — names, schemas, errors — is the real prompt.
- 5. Unify execution and business state — One serializable blob. The ticket is the agent state.
- 6. Launch, pause, resume — Boring APIs for long-running work. Crashes must not lose the thread.
- 7. Contact humans with tool calls — Approval and missing info are tools named ask_human, not a side channel.
- 8. Own your control flow — The model picks among legal edges. Your code owns the graph.
- 9. Compact errors into context — Observations should be the smallest string that still enables the next correct action.
- 10. Small, focused agents — Few tools, narrow goal, short context. Generalists orchestrate; specialists act.
- 11. Trigger from anywhere — Meet users in mail, chat, tickets, cron. The loop does not live in one text box.
- 12. Stateless reducer — (state, event) → (newState, effects). The call is pure given the context you built.

Start with one prompt. Then a workflow. Then an agent. Multi-agent last.
A second agent is a context boundary, not a personality.
Skills: name+description always, body on trigger, files on demand. Library: GET /api/canon/skills
Enforce security at the sandbox/tool allowlist, never by asking the model to behave.

## Skills (progressive disclosure)
GET /api/canon/skills — index of name + description only.
GET /api/canon/skills/{id}?format=md — SKILL.md body.
- **skill-creator**: Write a skill — /api/canon/skills/skill-creator?format=md
- **agents-md**: Write AGENTS.md — /api/canon/skills/agents-md?format=md
- **distill-traces**: Distill a trace — /api/canon/skills/distill-traces?format=md
- **twelve-factor-agents**: Twelve-factor agents — /api/canon/skills/twelve-factor-agents?format=md
- **workflows-vs-agents**: Workflows versus agents — /api/canon/skills/workflows-vs-agents?format=md
- **agent-loop**: The agent loop — /api/canon/skills/agent-loop?format=md
- **framework-choice**: Pick a framework — /api/canon/skills/framework-choice?format=md
- **context-engineering**: Own the context window — /api/canon/skills/context-engineering?format=md
- **compaction**: Compact observations — /api/canon/skills/compaction?format=md
- **tool-design**: Design the ACI — /api/canon/skills/tool-design?format=md
- **permissions**: Allow / ask / deny — /api/canon/skills/permissions?format=md
- **mcp-server**: MCP server — /api/canon/skills/mcp-server?format=md
- **a2a-protocol**: Agent-to-agent (A2A) — /api/canon/skills/a2a-protocol?format=md
- **human-in-the-loop**: Humans as tools — /api/canon/skills/human-in-the-loop?format=md
- **sandbox-security**: Sandbox and injection — /api/canon/skills/sandbox-security?format=md
- **prompt-chaining**: Prompt chain — /api/canon/skills/prompt-chaining?format=md
- **routing**: Router / handoff — /api/canon/skills/routing?format=md
- **parallelization**: Fan-out / reduce — /api/canon/skills/parallelization?format=md
- **evaluator-optimizer**: Evaluator–optimizer — /api/canon/skills/evaluator-optimizer?format=md
- **code-act**: Code-act — /api/canon/skills/code-act?format=md
- **orchestrator-workers**: Orchestrator–workers — /api/canon/skills/orchestrator-workers?format=md
- **multi-agent**: Multi-agent topologies — /api/canon/skills/multi-agent?format=md
- **subagents**: Spawn subagents — /api/canon/skills/subagents?format=md
- **plan-and-act**: Plan / act — /api/canon/skills/plan-and-act?format=md
- **spec-driven**: Spec-driven work — /api/canon/skills/spec-driven?format=md
- **harness-design**: Design a harness — /api/canon/skills/harness-design?format=md
- **coding-agent**: Coding agent — /api/canon/skills/coding-agent?format=md
- **research-agent**: Research agent — /api/canon/skills/research-agent?format=md
- **browser-agent**: Browser agent — /api/canon/skills/browser-agent?format=md
- **document-agent**: Document / RAG agent — /api/canon/skills/document-agent?format=md
- **support-agent**: Support / ops agent — /api/canon/skills/support-agent?format=md
- **eval-harness**: Eval harness — /api/canon/skills/eval-harness?format=md
- **durable-execution**: Durable execution — /api/canon/skills/durable-execution?format=md
- **observability**: Trace the loop — /api/canon/skills/observability?format=md

## Jobs
- [Coding agent](/api/canon/jobs/coding-agent?format=md): Load this pack, then the coding-agent playbook. Do not ingest the atlas. Start from a harness, not a blank graph.
- [Research agent](/api/canon/jobs/research-agent?format=md): Parent synthesizes. Researchers write notes.md and return 30 lines. Never dump 40 hits into the parent window.
- [Support / ops agent](/api/canon/jobs/support-agent?format=md): Ticket is the blob. Handoff rewrites the brief. Refunds are ask_human. Do not start a crew.
- [Document / RAG agent](/api/canon/jobs/document-agent?format=md): Prefer LlamaIndex (or equivalent) for the corpus. Retrieved text is untrusted data. Citations are part of the schema.
- [Browser agent](/api/canon/jobs/browser-agent?format=md): API first. Browser last. Sandbox always. Action space is the product; keep it small and eval it.
- [Named workflow](/api/canon/jobs/workflow-pipeline?format=md): Do not build an agent. Build a workflow. Put code gates between hops. Add a loop only where the eval fails without one.
- [Multi-agent team](/api/canon/jobs/multi-agent-crew?format=md): Roles must change tools or schema. Fresh windows. Structured returns. Bound the talk. Prefer supervisor or handoff over group chat.
- [MCP server](/api/canon/jobs/mcp-server?format=md): One job per tool. No secrets in descriptions. Clients pin this server. Do not instruct the model from a tool description.
- [Skill pack](/api/canon/jobs/skill-pack?format=md): Description first (what + when). Body as a playbook. references/ on demand. Trigger-test five phrasings.
- [Eval harness](/api/canon/jobs/eval-platform?format=md): 20–50 real tasks, structured asserts, CI on change, at least one injection/refusal case. Architecture waits on this.
- [Production agent product](/api/canon/jobs/production-agent?format=md): Name the five: termination, sandbox, context builder, eval set, pause API. One blob. One orchestrator. Gateway not a text box.

## Playbooks
- [Design an agent](/api/canon/playbooks/design-an-agent?format=md): Evals first. Raw loop second. Framework last, and only for a missing primitive.
- [Choose a topology](/api/canon/playbooks/choose-topology?format=md): Walk the decision tree. Do not start from a crew because the demo looked collaborative.
- [Write a skill](/api/canon/playbooks/write-a-skill?format=md): Frontmatter that triggers, a body that runs, files on demand. Distill from traces if you have them.
- [Write AGENTS.md](/api/canon/playbooks/write-agents-md?format=md): The constitution of the repo. Commands, boundaries, done. Point at skills for depth.
- [Design the ACI](/api/canon/playbooks/design-tools?format=md): Names, schemas, errors, caps, idempotency, the permission gate. This is the real prompt.
- [Add a human gate](/api/canon/playbooks/add-hitl?format=md): Approval and missing info are tools. Pause is an API. The blob survives the wait.
- [Spawn subagents](/api/canon/playbooks/spawn-subagents?format=md): A nested loop to protect the parent window, to parallelize, or to apply a different skill set.
- [Own the window](/api/canon/playbooks/compact-context?format=md): Build the working set every turn. Pin the goal. File the bulk. Compact the errors.
- [Write evals first](/api/canon/playbooks/write-evals?format=md): The golden set is the product specification. Architecture waits on it.
- [Review a design](/api/canon/playbooks/review-a-design?format=md): Paste the design. Score it against named failures and the five readiness questions.
- [Sandbox a coding agent](/api/canon/playbooks/sandbox-coding-agent?format=md): Workspace, permissions, git as ledger, verifier in the loop. Do not start from a blank graph.
- [Defend injection](/api/canon/playbooks/defend-injection?format=md): Untrusted speakers everywhere: pages, PDFs, MCP descriptions, other agents. Executor enforces.
- [Distill a trace](/api/canon/playbooks/distill-a-trace?format=md): Compile a paid-for lesson into a skill, a rubric, or a golden case. Do not hoard transcripts.
- [Pick a framework](/api/canon/playbooks/pick-a-framework?format=md): Pick for the constraint you have. Steal modular concepts. Do not rewrite the company around a README.
- [Ship durable](/api/canon/playbooks/ship-durable?format=md): The reducer over a blob, with pause, resume, traces, and evals. This is production.

## Endpoints
- GET /llms.txt — this index
- GET /llms-full.txt — full dump (only if you must; prefer a job pack)
- GET /api/canon — JSON index
- GET /api/canon/jobs/{id}  (?format=md)
- GET /api/canon/playbooks/{id}  (?format=md)
- GET /api/canon/articles/{id}  (?format=md)
- GET /api/canon/recipes/{id}  (?format=md)
- GET /api/canon/failures
- GET /api/canon/skills — skill index (name+description)
- GET /api/canon/skills/{id}  (?format=md) — SKILL.md
- GET /api/canon/search?q=
- GET /api/canon/decide?path=&work=&split=&gate=
- POST /api/canon/review  {"text":"..."}

Human UI: /field  /skills  /choose  /review  /playbooks  /recipes  /failures