From c3-skill
Manages architecture documentation via canvas definitions: validates docs, scaffolds entities, checks topology, and enforces user-owned schemas for every type.
How this skill is triggered — by the user, by Claude, or both
Slash command
/c3-skill:c3The summary Claude sees in its skill listing — used to decide when to auto-load this skill
CLI binary: packaged with this skill at `<skill-dir>/bin/c3x.sh`.
CLI binary: packaged with this skill at <skill-dir>/bin/c3x.sh.
c3() { C3X_MODE=agent bash <skill-dir>/bin/c3x.sh "$@"; }
c3x.sh = single source. Skill = router: classify -> run c3 -> follow output. No duplicate CLI checklists.C3X_MODE=agent -> TOON output (~40% fewer tokens). Commands append help[] hints.c3 list for topology + coverage, c3 check for validation. --help for help.Every entity TYPE — context, container, component, ref, rule, adr, and
document types (prd, user-story, atomic-design-change, pm-requirement, and
any project-defined type) — has a canvas definition: the sections and typed
columns its docs must carry. Definitions are user-owned markdown materialized
at .c3/canvases/<type>.md; c3 canvas manages them and the user may edit them.
c3 schema <type>
renders it; c3 canvas read <type> is the owned source). Required sections, table
columns, and reject rules come from there, never from a fixed list in this file.c3 check validates against the definition, so a user's edit to a definition
changes what is enforced. c3x facilitates the wiring (scaffold / validate /
check); it does not dictate shape.adr canvas. Read c3 schema adr for its shape.| Command | Purpose |
|---|---|
list | Topology with counts + coverage (--flat, --compact) |
check | Validate docs against their canvas definitions (--fix, --only, --include-adr, --only-touched). Also verifies an accepted unit's declared code bindings resolve (WARN; --strict-codemap to gate) |
canvas <list|read|add|write> | Manage canvas definitions (the shape of each entity type); user-owned at .c3/canvases/ |
schema <type> | Render the canvas definition for <type> (sections, columns, REJECT IF). Source of truth = c3 canvas read <type> |
add <type> <slug> | Create entity; body via stdin or --file <path> (--container, --feature). Unguarded — the create path. Valid types = c3 canvas list |
write <id> | Rewrite body or a section (--section <name>, --file <path>, stdin). Refused on a frozen fact → use the change-unit flow. Direct only for change-docs (adr/prd) + canvas bodies |
set <id> <field> <val> | Update a frontmatter field (goal, status, boundary, category, title, date). Refused on a frozen fact → change-unit flow. Exception: set <id> codemap '<glob>' — the external code binding is verified, not frozen, so this one field is editable on a frozen fact (live code-map maintenance) |
wire <src> <tgt> | Link entities (--remove unlinks). Refused when <src> is a frozen fact → change-unit flow (frontmatter patch) |
read <id> | Entity content; agent truncates 1500 chars (--full bypasses). --section <name> --cite emits the patch base anchor |
search <query> | Natural-language or conceptual query -> candidate entities by semantic + keyword + graph signals |
lookup <file-or-glob> | File/glob -> component + refs |
delete <id> | Remove entity + clean refs (--dry-run). Refused on a frozen fact → change-unit flow (retire patch) |
change <new|view|status|accept|apply|rebase|scaffold> | The change-unit flow — the only way to edit a frozen fact. Author patches (and optional .codemap.md carriers for code re-bindings) in .c3/changes/<unit-id>/, then change apply lands them atomically. view/status show both arms — internal patches + external code bindings (see references/change.md) |
change scaffold <unit-id> | Stage a rung-climb: scans every fact, finds those below their canvas's current required bar, and writes one insert patch per fact with an empty required-section template (heading + column headers, no rows). The emptiness gates the climb — change apply refuses an empty required section, so each template must be filled first (see references/change.md §Climbing a rung) |
graph <id> | Relationship graph (--depth, `--direction forward |
Don't assume a fixed type set — confirm any type's shape with c3 schema <type> (works for every entity type); c3 canvas list shows the document/definition canvases.
Authoring — two surfaces, one boundary. Read the type's definition first (c3 schema <type>), author to it. Body with mermaid, code fences, or tables -> use --file <path>, not inline strings.
system, container, component, ref, rule, recipe, pm-requirement, user-story (every type whose canvas declares no status: set). You cannot write/set/wire/delete an existing one. Editing a fact happens ONLY through the change-unit flow: c3 read <id> --section <name> --cite -> c3 change new <unit-id> -> author <seq>-<slug>.patch.md -> c3 change apply <unit-id>. See references/change.md. (Creating a new fact is exempt — c3 add <type> <slug> is unguarded.)adr, prd, atomic-design-change) and CANVAS bodies — these declare status: / are user-owned, so they edit directly: single-sentence text -> echo "..." | c3 write <id> --section <name>; whole-body rewrite -> c3 write <id> --file body.md; frontmatter -> c3 set <id> <field> <value>.The guard keys on the FIRST arg only, and an unknown/typo'd type is treated as frozen. The exact refusal names the fix: " is a fact — facts are frozen and change only through a change-unit."
| Keywords | Op | Ref |
|---|---|---|
| adopt, init, scaffold, bootstrap, onboard, "create .c3" | onboard | references/onboard.md |
| where, explain, how, diagram, trace, "show me", "what is", "what handles" | query | references/query.md |
| audit, validate, "check docs", drift | audit | references/audit.md |
| add, change, fix, implement, refactor, remove, provision, design | change (the change-unit flow: ADR = unit; fact-edits ride as patches, land via change apply) | references/change.md |
| pattern, convention, "create ref", "update ref", standardize | ref | references/ref.md |
| "coding rule", "coding standard", "coding convention", "split ref into rule" | rule | references/rule.md |
| marketplace, "browse rules", "adopt rule", "install rule from" | rule (Adopt) | references/rule.md |
| "edit the canvas", "change the shape", "what sections does X have", "add a doc type", "customize the ADR/component definition", "add prd/user-story" | canvas | references/canvas.md |
| impact, "what breaks", assess, sweep, "is this safe" | sweep | references/sweep.md |
| recipe, "trace end-to-end", "cross-cutting flow" | query(read) / change(create) | references/query.md / references/change.md |
AskUserQuestion with options)references/<op>.mdRead-only fast path: for conceptual or natural-language discovery ("where is X", "what handles Y", paraphrases), start with c3 search "<question>", then read the best candidates. For known files/globs, use c3 lookup <file>. For known IDs/sections, use c3 read <id> --section <name>. Do not run c3 list or c3 check before the first conceptual c3 search; use them only after search/lookup misses, drift is suspected, topology-wide inventory is required, mutation verification is needed, or the user explicitly asks for validation/audit. Prefer section reads. Skip graph unless relationship/dependent impact is part of the answer.
Missing .c3/ -> onboard. Follow help[] hints in output.
C3 context loaded. Before touching anything, ask C3 first:
c3 lookup <file-or-glob> -> component docs, refs, constraints. They supersede assumptions.
Context shifts mid-task -> look up again. Topology = source of truth.
First AskUserQuestion denial -> ASSUMPTION_MODE = true for session.
AskUserQuestion again[ASSUMED]HARD RULE -- entity instances are CLI-only. NEVER Read/Glob/Edit/Write entity docs under .c3/ (containers, components, refs, rules, adrs, recipes, document instances). Mutate them only through the c3 command handle below.
HARD RULE -- FACTS ARE FROZEN. A fact = any entity whose canvas declares no status: set (system, container, component, ref, rule, recipe, pm-requirement, user-story). c3 write/set/wire/delete on an existing fact is refused — edit it ONLY by authoring patches in a change-unit and running c3 change apply. Exempt (still direct): c3 add (create), c3 canvas write (canvas bodies are user-owned), editing a change-doc (adr/prd/atomic-design-change — they declare status:), and c3 set <id> codemap (the external code binding is verified, not frozen — code churns, so the map is live-maintenance; deliberate re-bindings ride a change-unit as a .codemap.md carrier, see references/change.md). The guard checks the FIRST arg only; unknown types are treated as frozen.
HARD RULE -- A FACT IS ALWAYS COMPLETE TO ITS RUNG. The canvas is a rung: a complete contract for one complexity level, not a target to fill in over time. A fresh init's canvas is deliberately lean (rung-1) — every required section is present, but the deeper sections a complex project needs are a higher rung, not a hole. Completeness is never relaxed: a fact is always complete to its current rung, never thin or partial. What grows is the complexity level, and you grow it by climbing a rung — raise the canvas (make an optional section required, or author a richer one via c3 canvas write), then migrate every affected fact up to the new contract, completely. Migration is the mechanism of climbing: integrity forbids facts straddling two rungs. Each rung stands on its own and is not responsible for future rungs — solve now completely, do not over-engineer rung-1 with sections a later rung would carry; climb when the architecture earns it. The climb flow (change scaffold → fill → gated change apply) is in references/change.md §Climbing a rung.
Canvas DEFINITIONS at .c3/canvases/<type>.md are the exception — they are user-owned markdown. Read them (c3 canvas read <type> / directly) and edit them (c3 canvas write or by hand); they are meant to be customized. c3 check validates instances against them.
.c3/c3.db = disposable cache, not submitted state. Raw access to instance files bypasses the CLI contract -> stale/misleading. Instance access via the c3 command handle:
| Op | Commands |
|---|---|
| Create (unguarded) | add |
| Read | read <id> (--cite for a patch base), list, lookup, graph |
| Edit a FROZEN FACT | change new → author patch → change apply (the ONLY path; write/set/wire/delete are refused on facts) |
| Edit a change-doc / retire a fact | write <id>, set, wire (--remove) on adr/prd only; fact frontmatter/retire ride as patches via change apply |
| Validate | check |
| Definitions (user-owned) | canvas <list|read|add|write>, schema <type> |
Missing packaged CLI operation -> STOP, tell user. No file-tool workarounds.
Search strategy: concept->entity via c3 search "<question>"; code->entity via c3 lookup <file-or-glob>; topology via c3 list; doc bodies via targeted c3 read <id> --section <name> or c3 read <id> --full.
Embeddings self-heal — no manual re-index after a change. change apply does not touch embeddings; the next c3 search reconciles the changed fact incrementally. c3 index = full rebuild (maintenance only), never a correctness step.
c3 check after every mutation — after change apply (the landing for any fact edit), after add (create), and after canvas write. Errors = blockers. (change apply runs drift + canvas gates first, but check is still the post-land confirmation.)
Read the definition before authoring or validating any entity. Required sections / columns / reject rules come from c3 schema <type> (the project's canvas definition), never from memory or this skill's prose. If a user edited the definition, that edit is the contract.
ADR-first — the ADR is the change-unit:
Every change starts c3 add adr <slug> before implementation.
(Exception: ref-add creates ADR at completion -- references/ref.md.)
ADR = work order, and the ADR is the change-unit: same id, folder .c3/changes/<adr-id>/. You author the ADR freely (add adr / write / set — it is a change-doc, not a frozen fact); any edit it makes to a frozen fact rides as a <seq>-<slug>.patch.md in that folder and lands when you run c3 change apply <adr-id>. Author the reasoning, carry the fact-edits as patches, land them together.
Two distinct freezes — do not blur them:
c3 check — its prose is a frozen record of a past decision.ADR schema discipline is unchanged: start with c3 schema adr (or c3 canvas read adr) BEFORE drafting any ADR body. The schema output leads with a REJECT IF block — read it first; the bullets ARE the rejection contract. Per-section fill: and rejected when: lines apply the same gate at section level. Same shape for any c3 schema <type> — REJECT IF first, fill the body to the contract, never draft freehand and reconcile later. Use c3 read <adr> --full and help[] to verify the body still matches the contract. ADR creation is all-or-nothing; thin sections fail at creation, N.A - <reason> for inapplicable rows. list/check exclude ADRs by default; --include-adr only when working on a specific ADR. Change-doc status set is [open, accepted, done, superseded] (c3 add adr stamps proposed at creation — the unmigrated synonym for open); accepted auto-latches to done when its After-cites resolve fresh. Terminal-state change-docs (status: done, status: superseded) are exempt from c3 check — historical, content-frozen. ADR content is historical — verify against current docs.
Stop if:
c3 add adr <slug> NOW (the ADR is the change-unit; fact-edits ride in .c3/changes/<adr-id>/)AskUserQuestion (skip if ASSUMPTION_MODE)c3 schema <type>1. Lookup:
c3 lookup <file-path>
c3 lookup 'src/auth/**'
Run when any file path surfaces. No match = uncharted.
2. Load rules: For every rule-* from lookup:
c3 read <rule-id>
Read its ## Rule / ## Golden Example / ## Not This (or whatever sections its definition declares). Code MUST match golden pattern. Deviations need Override or new ADR.
3. Parent context: Read upward first:
c3 read <parent-container-id>
c3 read <component-id>
Parent responsibilities + membership = integration contract.
4. Graph context:
c3 graph <parent-container-id> --depth 1
c3 graph <component-id> --depth 1
Change affects interface -> check consumers first.
Result: Refs + rules + parent + graph = full constraint set. All honored.
New component: Top-down. Container Components + Responsibilities first, then component. Not done until parent has Parent Delta decision.
Navigation: Context -> Container -> Component
Include mermaid when relationships matter:
c3 graph <entity-id> --format mermaid
Root selection > depth:
--depth 1 default. --depth 2 for cross-container only--direction forward = impact. --direction reverse = dependentsc3-0 -- one node, no signal.c3/
├── README.md # Context (c3-0)
├── canvases/<type>.md # Canvas definitions (user-owned shape of each type)
├── adr/adr-YYYYMMDD-slug.md
├── refs/ref-slug.md
├── rules/rule-slug.md
├── recipes/recipe-slug.md
└── c3-N-name/
├── README.md # Container
└── c3-NNN-component.md
No .c3/ or re-onboard. Scaffold (incl. materialize canvas definitions) -> discovery -> inject CLAUDE.md -> show capabilities.
references/onboard.md
c3 search <question> first for fuzzy/conceptual discovery, c3 lookup <file-or-glob> for code->entity, c3 graph <id> --direction reverse for dependents. For body text, use targeted c3 read output. Deliver to the Answer Depth Contract in the reference — claims bound to reads, causal chain over entity lists, failure boundary stated.
references/query.md
c3 check -> c3 list -> semantic phases (each entity validated against its canvas definition) -> PASS/WARN/FAIL table.
references/audit.md
ADR first (= the change-unit) -> c3 list -> affected entities -> c3 lookup files -> fill ADR to the adr canvas. Editing a frozen fact: c3 read <id> --section <name> --cite -> c3 change new <adr-id> -> author patches -> c3 change view/status/accept -> c3 change apply (the only mutation) -> c3 check. Creating a fact stays direct (c3 add). Provision gate: implement or design-only.
references/change.md
Modes: Add / Update / List / Usage. Author to the ref canvas (c3 schema ref).
references/ref.md
Modes: Add / Update / List / Usage. Author to the rule canvas (c3 schema rule).
references/rule.md
Inspect or edit the definitions that shape entities: c3 canvas list/read, c3 canvas write to customize a project's shape, c3 canvas add for a new project-defined type. Definitions are user-owned at .c3/canvases/; editing one changes what c3 check enforces.
references/canvas.md
c3 graph <id> --direction reverse -> transitive deps -> parallel assessment -> synthesize. Advisory only.
references/sweep.md
npx claudepluginhub lagz0ne/c3-skill --plugin c3-skillDesigns, reviews, and documents complex software architectures using C4 Mermaid diagrams, ADRs, and patterns like Clean, Hexagonal, and DDD for system design reviews.
Generates C4 architecture documentation (Context, Container, Component, Code levels) for existing repositories using bottom-up analysis from code subdirectories. Outputs to C4-Documentation/ directory.
Guides architecture design via Socratic questioning, generates technical docs like overview.md, domain-model.md, and ADR for new features, systems, or project structuring.