c3-skill

C3: Architecture That Agents Can Read

C3 turns your codebase's architecture into something an LLM can navigate, query, and safely change. A sealed .c3/ tree of markdown is the shared architectural truth — reviewable in Git, validated by machine — while c3.db stays a local cache the CLI rebuilds at any time.

Use it through the Claude Code plugin or the npx CLI. Both run the same c3x engine; only the install shape differs.

Install / Run

Claude Code plugin (fat, self-contained):

claude plugin install lagz0ne/c3-skill

Then: /c3 onboard this project

The plugin carries the c3x binary and the embedded semantic model — meaning-based search works offline, no downloads, no toolchain.

npx CLI (thin, fetched on demand):

npx @c3x/cli check
npx @c3x/cli search "how do users sign in and get permissions"

The npm package downloads the matching c3x binary and semantic model from the GitHub Release into a versioned local cache on first use.

Why

Architecture docs rot because nobody enforces them. C3 makes them machine-writable and machine-verifiable:

• Your entity model, not ours — every entity type is defined by a canvas, user-owned markdown your team edits; validation enforces your definition
• LLMs ask by meaning — c3x search "how do users sign in" surfaces authentication/RBAC/JWT docs even when the wording differs
• LLMs read before touching code — c3x lookup src/auth/login.ts returns the owning component, governing refs, and applicable rules
• Writes are validated — every content update passes canvas enforcement; a missing required section is rejected with a hint
• Canonical text is reviewable — Git diffs and merges happen on sealed .c3/*.md files, never on an opaque cache
• The cache is disposable — c3x check rebuilds c3.db from canonical text whenever needed
• Every element is trackable — headings, paragraphs, table rows, and list items carry stable IDs and hashes; entity-level merkle gives O(1) change detection

The canvas model

The core idea of C3: entity definitions are data, owned by your project.

Every entity type — container, component, ref, rule, adr, recipe, and document types like prd or user-story — is defined by a canvas: markdown declaring its sections, table columns, and reject rules. c3x ships built-in canvases as seeds; on onboard they materialize into .c3/canvases/<type>.md and your team owns them from there.

c3x canvas list             # every entity definition + domain + source
c3x canvas read component   # the canonical definition (yours to edit)
c3x schema component        # render its sections, columns, REJECT IF rules

Edit a canvas to shape docs around your architecture vocabulary — add a section, tighten a reject rule, define a new entity type — and c3x write / c3x check enforce your definition, not a baked-in one. Definitions travel with the repo and are reviewable in Git like everything else.

The built-in component canvas, for example, requires Goal, Parent Fit, Purpose, Foundational Flow, Business Flow, Governance, Contract, Change Safety, and Derived Materials — but that is a seed default, not a contract baked into the binary.

What You Get

Supported operations, one entry point

Say this	C3 does this
/c3 adopt this project	onboard — discovers your architecture through conversation, scaffolds .c3/
/c3 where is auth?	query — meaning-based discovery via search, then lookup, read, graph
/c3 add rate limiting	change — ADR-first: impact analysis → decision record → execute → validate
/c3 create a ref for error handling	ref — cross-cutting pattern with Choice/Why/How sections and cite wiring
/c3 add a rule for structured logging	rule — enforceable standard with golden example and anti-patterns
/c3 edit the canvas for ADRs	canvas — inspect or reshape the definitions that govern your docs
/c3 audit the docs	audit — structural → semantic → drift → compliance validation
/c3 what breaks if I change payments?	sweep — transitive impact across the entity graph, with a verification table

Query answers follow the skill's Answer Depth Contract: claims bound to reads actually run, causal chains over entity lists, failure boundaries stated, direct vs transitive dependents separated.

The c3x CLI

For agents: the /c3 skill invokes the CLI automatically via bash <skill-dir>/bin/c3x.sh. Never run bare c3x — always go through /c3. The examples below use c3x as shorthand.

Read:

c3x read c3-101                          # entity content
c3x read c3-101 --section Goal           # just one section
c3x read c3-101 --json                   # structured JSON