c3-skill

C3: Architecture That Agents Can Read

C3 turns your codebase into something an LLM can navigate. A sealed .c3/ tree is the shared architectural truth for Git review and merges, while c3.db stays a local cache the CLI can rebuild at any time.

One Claude Code plugin. One /c3 command. The agent figures out the rest.

claude plugin install lagz0ne/c3-skill

Then: /c3 onboard this project

Why

Architecture docs rot because nobody enforces them. C3 fixes this by making the docs machine-writable and machine-verifiable:

• LLMs read them before touching code — c3x lookup src/auth/login.ts tells the agent which component owns the file, which refs govern it, what rules apply
• Writes are validated — every content update passes through schema enforcement. Missing a required section? Rejected with a hint
• Canonical text is reviewable — Git diffs and merges happen on sealed .c3/*.md files and code-map.yaml, not on an opaque cache
• The cache is disposable — c3.db accelerates queries and writes; c3x check rebuilds it from canonical text when needed
• Every element is trackable — headings, paragraphs, table rows, list items each have a unique ID and SHA256 hash; entity-level merkle for O(1) change detection

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 — topology traversal via list, 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 audit the docs	audit — structural → semantic → drift → compliance validation
/c3 what breaks if I change payments?	sweep — transitive impact across the entity graph

The c3x CLI

A Go binary bundled inside the plugin. No separate install — the skill carries its own binary for every platform (linux/darwin x amd64/arm64).

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

Read:

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

Write — two shapes, one rule: complex content goes through a file:

# Plain-text section edit
echo "Handle JWT authentication" | c3x write c3-101 --section Goal

# Rich content (mermaid, code fences, tables, mixed quotes) — use --file
c3x write c3-101 --section "Foundational Flow" --file flow.md
c3x write c3-101 --file full-body.md

# New entity
c3x add component auth --container c3-1 --file auth-component.md

Frontmatter fields (no body touched):

c3x set c3-101 goal "Handle JWT auth"
c3x set c3-101 codemap "src/auth/**,src/auth.go"
c3x set c3-101 codemap "src/new/**" --append

Navigate the architecture:

c3x list                                 # topology: goals, file coverage, ref usage
c3x lookup src/auth/login.ts             # file → component + refs + rules
c3x graph c3-1 --format mermaid          # forward subgraph as mermaid
c3x graph ref-jwt --direction reverse    # what breaks if this changes?
c3x schema adr                           # required sections + pre-draft workorder

Relationships and removal:

c3x wire c3-101 ref-jwt ref-error-handling   # cite one or more refs/rules
c3x wire c3-101 ref-jwt --remove             # unlink
c3x delete ref-obsolete --dry-run

Validate:

c3x check                                # canonical seal + schema + refs + coverage
c3x check --only-touched                 # scope to branch-touched entities
c3x check --only c3-101                  # scope to one entity
c3x check --include-adr                  # include ADR validation (skip by default)
c3x check --rule rule-xyz                # scope to citers of a rule
c3x check --fix                          # auto-fix title-matched references

Agent-mode compact c3x list keeps topology bounded while still exposing recipe description and sources, so cross-cutting shortcuts can be matched before a deeper read.

Full command list: c3x --help (12 user-facing commands)

Schema enforcement

Every entity type has required sections. The CLI enforces them on write: