Reference
The formal Canopy specification. For the narrative explanation of why things are shaped the way they are, see Concepts. For one-page lookup, see Cheatsheet.
What’s here
| Page | What it covers |
|---|---|
| Framework Spec | Skill anatomy, frontmatter rules, tree execution model, op-lookup order, category-resource subdirectories, skills-root resolution, the Compatibility field, runtime activation, debug mode. |
| Primitives | Framework primitives (IF, SWITCH, FOR_EACH, ASK, SHOW_PLAN, VERIFY_EXPECTED, etc.) — signatures, semantics, examples. Mirrored from canopy-runtime’s sliced spec (index ops.md + per-feature files under references/ops/) so the spec the runtime executes and the spec the docs site shows are the same content. |
| Runtimes | Per-platform execution rules — Claude Code (native subagents) and GitHub Copilot (inline subagent fallback). Mirrored from canopy-runtime’s runtime-claude.md and runtime-copilot.md. |
Single source of truth
Primitives and Runtimes are generated from canopy-runtime’s reference files (skills/canopy-runtime/references/*.md) — those are the canonical source the runtime actually loads at execution time. The mirror is regenerated by scripts/sync-runtime-docs.py; CI fails if the runtime files change without the mirror being regenerated, so the docs site can never silently drift from what the runtime executes.
To edit primitive or runtime content, edit the canonical file under skills/canopy-runtime/references/ and run the sync script. Don’t edit docs/reference/PRIMITIVES.md or docs/reference/RUNTIMES.md directly — your changes will be overwritten on next sync.