Documentation

Context Canvas Docs

Context Canvas checks whether a Claude Code configuration applies as written, and designs the lifecycle your agents follow: stages, gates and approvals compiled to Claude Code and AGENTS.md files. These docs cover the check, the model, the build gate, releases, governance and the export map.

Check your setup Take the tour API Reference

Quick Start

Check a setup

Open /check and drop the folder you start Claude Code in, or try the sample. The check runs in your browser; nothing is uploaded.
Read each finding: what won't apply, why, the fix, and a link to Claude Code's documentation.
Fix the files, or copy the fix prompt into your coding agent: it lists each fix, with the exact edit where the change is mechanical. Then check again. The map shows which agents, skills and MCP servers load.

Keep it checked

CLI: npx context-canvas-check, with --json for CI and --prompt for a fix prompt.
Claude Code plugin: /plugin marketplace add UnicornGraveyard/context-canvas-check, then /plugin install context-canvas-check@context-canvas. It checks at session start and after each config edit.
MCP server, for any agent: npx -y context-canvas-check mcp. Tools: check_config, get_fix_instructions and explain_check. They only read files.

Design a lifecycle

Create a blueprint at /blueprints/new from a template, or import an existing project at /blueprints/import.
Open it on the canvas. Use the Lifecycle view to assign agents to stages and add gates.
Run the build gate. Fix issues in the Inspector, or run Auto Fix.
Publish a version, move it to staging, then to production.
Export a zip or open a GitHub pull request, pinned to the version or channel you choose.

FAQ (Ask an Agent)

Use these question patterns when you want an assistant to guide setup, modeling, and export decisions.

What problem does Context Canvas solve?

Agent setups drift: prompts get copied, permissions widen, and nobody can say which version shipped. Context Canvas models the setup as a blueprint, checks it with a build gate, versions it, and exports deterministic `.claude` files you can review, diff and audit.

What is the fastest way to start?

Create a blueprint from a template (the AI-driven development lifecycle, AI-DLC, and the spec-driven lifecycle are good defaults), or import an existing `.claude` directory. Edit it on the canvas, run the build gate, publish a version, and export it as a zip or a GitHub pull request.

Can I bring in an existing Claude Code setup?

Yes. Import a folder or zip from Blueprints > Import. Agents, skills, rules, settings, `.mcp.json`, CLAUDE.md, AGENTS.md and plugins become nodes. Imports skip existing hooks; the preview lists them with anything else that can't be modeled. Exports generate their own hooks to enforce lifecycle gates, and a Context Canvas export imports with its lifecycle and gates.

How do versions and releases work?

Publishing freezes the compiled blueprint as an immutable, content-hashed version. Move a version to staging, then to production; production only takes the version in staging, and your organization can require a second person to approve it. Exports and the API can pin a number or follow a channel.

How does a team govern its blueprints?

Roles control who edits, publishes, releases and administers. An organization policy (for example, no bypassPermissions, a verification stage in every lifecycle) is enforced by the build gate. Every change and export is in the audit log, which you can export as JSONL or pull through the API.

How do I reduce prompt size without losing capability?

Move repeated instructions into shared SKILL and POLICY nodes, keep agent prompts short, and compose behavior with typed relationships instead of copying sections between agents.

How do I apply an export to a repository?

Open a GitHub pull request from the export dialog, or download the zip and commit the files. Treat generated files like source: review the diff, and pin the version in the PR description.

Data Model

A blueprint is a graph: nodes of the types below, joined by typed relationships. The API calls a blueprint a pack in older paths, and a node an atom; the stored type names are shown in code.

Structure node types

Agents, their skills and their settings: what Claude Code runs.

Agent AGENT_CLASSSkill SKILLSetting SETTING

Lifecycle node types

Stages in order, the gates at their exits, and the artifacts they hand over.

Stage STAGEGate GATE

Knowledge node types

These nodes provide contextual guidance, policy references, and traceability.

Fact FACTDecision DECISIONTask TASKArtifact ARTIFACTPolicy POLICYSnippet SNIPPET

Relationship Schema

Relationship	Allowed Pair	Rationale	Constraints
Extends `EXTENDS`	`AGENT_CLASS -> AGENT_CLASS`	Inheritance specializes one agent from another, so both endpoints must be agent classes.	Multiple parent classes are allowed. EXTENDS graph must remain acyclic.
Uses skill `COMPOSES`	`AGENT_CLASS -> SKILL`	Composition models an agent owning reusable capabilities, so it points from agent to skill.	Composition is directional (owner -> capability).
Requires `REQUIRES`	`SKILL -> SKILL`	Skill dependencies describe capability prerequisites, so dependencies are only between skills.	REQUIRES graph must remain acyclic.
Configures `CONFIGURES`	`SETTING -> AGENT_CLASS\|SKILL`	Settings provide runtime configuration and can only configure executable nodes (agents/skills).	Settings are attached, not inherited.
Related to `RELATED`	`ANY -> ANY`	RELATED is a contextual linkage for knowledge traceability and should not replace OO structural edges.	At least one endpoint must be a knowledge atom. Use only for context/policy linkage, not OO structure.
Assigned to `ASSIGNED_TO`	`AGENT_CLASS -> STAGE`	Assigns an agent to a lifecycle stage, as the stage's lead or as a contributor.	Edge metadata role is LEAD or CONTRIBUTOR (default CONTRIBUTOR). Each stage needs exactly one LEAD.
Then `NEXT`	`STAGE -> STAGE`	Orders lifecycle stages; work hands off from a stage to its NEXT stage.	Stages form one linear chain. NEXT graph must remain acyclic; revision loops belong in gate outcomes.
Gated by `GATED_BY`	`STAGE -> GATE`	A gate decides whether a stage's output may hand off to the next stage.	Each gate belongs to exactly one stage.
Produces `PRODUCES`	`STAGE -> ARTIFACT`	Declares an artifact a stage writes, such as requirements.md or a pull request.	Name artifacts after the file or deliverable (design.md, Pull request) so later stages can consume them.
Consumes `CONSUMES`	`STAGE -> ARTIFACT`	Declares an artifact a stage reads as input.	Artifacts should be produced by an earlier stage, or come from outside the lifecycle.
Requires context `REQUIRES_CONTEXT`	`AGENT_CLASS\|STAGE -> CONTEXT_CONTRACT`	Attaches a context contract to an agent or stage, declaring what context it needs before starting.	An agent or stage may have multiple contracts.
Provides context `PROVIDES_CONTEXT`	`CONTEXT_SOURCE -> CONTEXT_CONTRACT`	Binds a context source to a contract, declaring it can satisfy one or more of the contract's requirements.	A source may provide context to multiple contracts.

Build Gate

Relationship labels match their source and target node types.
EXTENDS, REQUIRES and NEXT graphs have no cycles; no self-edges.
Claude Code export compliance: names, path collisions, required frontmatter, transitive skill dependencies.
Lifecycle: stages form one NEXT chain, each stage has one lead, each gate belongs to one stage.
Organization policy: permission modes, models, tools, required stages and approvals, literal secrets, agent count.

Versions and Releases

Publishing a version freezes the compiled blueprint. Versions are immutable and content-hashed; unchanged content reuses the last version.
Each blueprint has a staging and a production channel. Production only takes the version in staging.
With the policy rule for production approval, a second person approves each production release. Requesters cannot approve their own.
Exports and the API accept ?version= with a number, latest, staging or production.

Governance

Blueprints belong to an organization. Create a team organization in Settings and invite people with a role.

Role	Can
Owner	Everything, including deleting the organization and managing owners.
Admin	Everything except deleting the organization or changing owners.
Editor	Edit blueprints, publish and release versions, and export.
Approver	Read blueprints, approve lifecycle gates and production releases.
Viewer	Read blueprints.

Organization policy: rules the build gate enforces on every blueprint, as blocking errors or warnings. Preview the impact before saving.
Audit log: every change, release and export with actor, time and IP. Export JSONL or CSV, or pull it with an API key.
API keys: read-only, scoped to the organization, shown once and stored as a hash.
OAuth tokens are encrypted at rest.

Export Map

Node	Export Target	Notes
`AGENT_CLASS`	`.claude/agents/<slug>.md`	Frontmatter (tools, model, permission mode, skills, scoped MCP servers) plus the merged prompt.
`SKILL`	`.claude/skills/<slug>/SKILL.md`	Instructions plus frontmatter: allowed-tools, invocation, paths.
`POLICY`	`.claude/rules/<slug>.md`	When exportAsRule is on. Other policies go to CLAUDE.md.
`SETTING`	`.claude/settings.json, .mcp.json`	Permissions, environment, MCP servers. Settings attached to one agent land in its frontmatter.
`STAGE, GATE`	`.context-canvas/lifecycle.json, .claude/hooks/context-canvas/gate.mjs`	Stage order, leads and gates. Check and rubric gates run as Stop hooks; rubric gates can be graded by Jev (TypeSafe AI) with TYPESAFE_API_KEY set. Human approvals run as /approve-gate-* skills.
`Knowledge nodes`	`CLAUDE.md`	Facts, decisions, tasks and snippets as sections of the project guide.
`Every export`	`.context-canvas/manifest.json`	Version, content hash, compiler and adapter versions. No timestamps, so the output is deterministic.
`AGENTS.md target`	`AGENTS.md`	Optional portable instructions for other agent runtimes.

For machine-readable references and endpoint examples, use the API page at /apis.