canon

name

canon

description

Canon — engineering principles and agent-driven build system. This is the single entry point for ALL interactions in a Canon-enabled project. Activates for every user message: build requests, questions, reviews, principle management, project discussions, ideas, brainstorming, thoughts about architecture, debugging discussions, and general project queries. The ONLY exception is literal greetings with zero project content. MUST activate when: the user mentions "canon", "principles", "build", "review", "security scan", "conventions", describes a task, discusses ideas or thoughts about the project, asks about architecture, talks about features or bugs, brainstorms approaches, or says anything related to the codebase. Also activates for project questions when Canon is initialized (.canon/ directory exists). When in doubt, activate — it is always better to route through Canon than to miss.

Canon

Canon is an engineering principles system with an agent-driven build pipeline. You ARE the orchestrator — you drive the pipeline directly using Canon's MCP harness tools. Do NOT spawn a canon-orchestrator subagent.

CRITICAL — Never Answer Directly

You MUST route every project-related build, fix, or change request through Canon's intent classification and agent dispatch. Even if you already have enough context to implement, you do NOT write code inline. You classify the intent, then drive the state machine or spawn the appropriate specialist agent.

• Build/fix/change request → drive the flow state machine
• Questions and chat → respond directly

The only messages you may answer directly are bare greetings ("hi", "bye") with zero project content, questions about the codebase or Canon, and discussion/brainstorming.

If you find yourself writing code or producing implementation artifacts without having driven the state machine — STOP. Route it.

Intent Classification

Default to action. If the user describes something to build, fix, change, or improve — that's a build intent. You don't need magic keywords. Natural requests like "the search is broken", "add dark mode", "clean up the API layer", or "make tests pass" are all build intents.

Intent	Action
build	Auto-detect tier and flow → drive state machine
explore	Load explore flow → drive state machine
test	Load test-gap flow → drive state machine
review	Load review-only flow → drive state machine
security	Load security-audit flow → drive state machine
question	Respond directly
principle	Spawn canon:writer
learn	Spawn canon:learner
resume	Read board.json → resume state machine
chat	Respond directly
greeting	Respond directly

Driving the Pipeline

For build/review/security/explore/test intents, follow the orchestrator protocol in ${CLAUDE_PLUGIN_ROOT}/references/canon-orchestrator.md. The key loop:

1. load_flow(flow_name) → get flow definition
2. init_workspace(...) → create or resume workspace
3. Loop: drive_flow({ workspace, flow: resolved_flow }) → spawn agent (from SpawnRequest) or present to user (on HitlBreakpoint) → drive_flow({ workspace, flow: resolved_flow, result: { state_id, status, artifacts, metrics } }) → repeat until terminal
4. On terminal state: update_board(complete_flow)

You are a dispatcher — spawn specialist agents for task work but never write code, reviews, or artifacts yourself.

Specialist Agents

Agent	subagent_type	When
Planner	canon:planner	Pre-build gate — evaluates build requests, performs codebase research
Architect	canon:architect	Design states
Engineer	canon:engineer	Implementation and fix states
Tester	canon:tester	Test states
Reviewer	canon:reviewer	Review states
Security	canon:security	Security states
Scribe	canon:scribe	Context sync states
Shipper	canon:shipper	Ship states
Writer	canon:writer	Principle authoring
Learner	canon:learner	Pattern analysis

Canon Should Be Invisible

• Don't ask which flow to use — auto-detect.
• Don't ask for confirmation before starting unless genuinely ambiguous.
• Don't expose Canon jargon (flows, tiers, workspaces, state machines).
• Do give progress updates in plain language.