C3
CLI: bash <skill-dir>/bin/c3x.sh <command> [args]
| Command | Purpose |
|---|---|
init | Scaffold .c3/ |
list | Topology (--json, --flat, --compact) |
check | Structural validation (--json) |
add <type> <slug> | Create entity (--container, --feature) |
codemap | Scaffold .c3/code-map.yaml with stubs for all components + refs |
lookup <file-or-glob> | File or glob → component + refs (--json) |
coverage | Code-map coverage stats (JSON default) |
Types for add: container, component, ref, adr, recipe
Intent Classification
| Keywords | Op | Reference |
|---|---|---|
| adopt, init, scaffold, bootstrap, onboard, "create .c3", "set up architecture" | onboard | references/onboard.md |
| where, explain, how, diagram, trace, "show me", "what is", "list components" | query | references/query.md |
| audit, validate, "check docs", drift, "docs up to date", "verify docs" | audit | references/audit.md |
| add, change, fix, implement, refactor, remove, migrate, provision, design | change | references/change.md |
| pattern, convention, "create ref", "update ref", "list refs", standardize | ref | references/ref.md |
| impact, "what breaks", assess, sweep, "is this safe" | sweep | references/sweep.md |
| recipe, "trace end-to-end", "cross-cutting flow", "how does X flow" | query (read) / change (create) | references/query.md / references/change.md |
Dispatch
- Classify op (ambiguous →
AskUserQuestionwith 6 options) - Load
references/<op>.md - Execute (use Task tool for parallelism)
Precondition
Before every op except onboard:
bash <skill-dir>/bin/c3x.sh list --json
Fails/empty → route to onboard
CoT Harness
C3 context is already loaded. Every file, every directory has a place in the topology. Before touching anything, let C3 tell you what it knows — then follow its lead.
c3x lookup <file-or-glob> → component docs, refs, constraints. Read them. They supersede assumptions.
When context shifts to a new component mid-task, look it up again. The topology is the source of truth — just follow it.
ASSUMPTION_MODE
First AskUserQuestion denial → ASSUMPTION_MODE = true for session.
- Never call
AskUserQuestionagain - High-impact: state assumption, mark
[ASSUMED] - Low-impact: auto-proceed
Shared Rules
Run c3x check frequently — after creating/editing any .c3/ doc. It catches broken YAML frontmatter, missing required sections, bad entity references, and codemap issues. Treat errors (✗) as blockers.
HARD RULE — ADR is the unit of change:
Every change operation MUST start with c3x add adr <slug> as its FIRST action.
No code reads, no file edits, no exploration before the ADR exists.
(Exception: ref-add creates its adoption ADR at completion — see references/ref.md.)
The ADR is an ephemeral work order — it drives what to update, then gets hidden.
c3x list and c3x check exclude ADRs by default; use --include-adr to see them.
Stop immediately if:
- No ADR exists for current change →
c3x add adr <slug>NOW - Guessing intent →
AskUserQuestion(skip if ASSUMPTION_MODE) - Jumping to component → start Context down
- Updating docs without code check
File Context — MANDATORY before reading or altering any file:
bash <skill-dir>/bin/c3x.sh lookup <file-path>
bash <skill-dir>/bin/c3x.sh lookup 'src/auth/**' # glob for directory-level context
Returned refs = hard constraints, every one MUST be honored. Run the moment any file path surfaces. Use glob when working across a directory. No match = uncharted, proceed with caution.
Layer Navigation: Context → Container → Component
File Structure:
.c3/
├── README.md # Context (c3-0)
├── adr/adr-YYYYMMDD-slug.md
├── refs/ref-slug.md
├── recipes/recipe-slug.md
└── c3-N-name/
├── README.md # Container
└── c3-NNN-component.md
Operations
onboard
No .c3/ or re-onboard. c3x init → discovery → inject CLAUDE.md → show capabilities.
Details: references/onboard.md
query
c3x list → match entity → Read doc → explore code.
Details: references/query.md
audit
c3x check → c3x list --json → semantic phases. Output: PASS/WARN/FAIL table.
Details: references/audit.md
change
ADR first (c3x add adr) → c3x list --json → c3x lookup each file → fill ADR (impact, work breakdown) → approve → execute → c3x check.
Provision gate: implement now or status: provisioned.
Details: references/change.md
ref
Modes: Add / Update / List / Usage.
Details: references/ref.md
sweep
c3x list --json → affected entities → parallel assessment → synthesize. Advisory only.
Details: references/sweep.md