Ctx

ctx — a living, spec-centered single source of truth

ctx sets up and runs a knowledge base that stays a lean, living single source of truth across many agent sessions. Its own job is small and load-bearing — scaffold the folder, classify every finding by lifetime, route the domain work to a companion, and run the gate; the heavy domain work lives in the companions. This is the entry point: read the model (classify depends on it), then run the procedure and route.

The model — two ideas

1. Organize by LIFETIME, not stage

Three lifetime classes. The archive rule and the edit rule both follow the class — that is the whole model. This table is the single source for the lifetime classes; companions reference it, they do not redefine it.

Class	What	Iron law	Who belongs
LIVING	current truth	edited in place; always current; never carries a stale/deprecated section inline	spec/ (product truth, incl. spec/design/) + overview.md + progress/ (work truth) + services.md (infra topology, when present — see ctx-serve)
APPEND-ONLY	history	never edit or delete an accepted entry; supersede in place	decisions/ (why; ADRs)
DISPOSABLE	raw / process	non-authoritative; sink the confirmed, archive-aside the rest	scratch/ (ALL raw: notes, prompts, research dumps, comparisons) + reports/ (HTML a human reads for review)

2. The SOT is GENERATIVE

spec/ + decisions/ are the single source of truth, and they are generative. Any explanation, report, tutorial, or option-comparison is a short-term, on-demand derivation FROM the SOT — produced when you need to communicate with someone, then discarded. There is no long-term "explanation" document. If a spec states the constraint and an ADR records the choice + its real alternatives + consequences, then "why did we do X, not Y" is derivable on demand — so you do not store it. This is what keeps the base lean.

• No standalone log. "What happened" = git history. "Why we abandoned X" = a decision. Don't keep a separate event log.
• Two living docs is fine (no SSOT violation): spec/ = the PRODUCT (what it is / how it works), progress/ = the WORK (where we are / what's next). Different domains. Guard: progress/ references spec/decisions by pointer, never restates a product fact.
• Archive follows lifetime class (mechanics AND the canonical archive filename in references/consistency.md): LIVING → fix in place, or on a foundational rewrite move the whole old doc to <folder>/archive/ under the canonical archive filename and write ONE clean new doc; APPEND-ONLY decisions → never archived, supersede in place (the trail is the value); DISPOSABLE → archive-aside.

What goes where (classify by lifetime — write from any direction, NOT a waterfall)

Order does not matter. Whatever you produce, classify it:

1. Current product truth → spec/ or overview.md, edit in place.
2. A made choice + why + the real alternatives → append decisions/NNNN, supersede-don't-rewrite. (Only decided things — see ctx-spec for the ADR content boundary. Undecided deliberations do NOT go here.)
3. Where we are / what's next → progress/, edit in place, pointers only (see ctx-progress).
4. Raw / uncertain: notes, prompts, research dumps, comparisons → scratch/, non-authoritative.
5. Thinking laid out for a human to review → reports/ (disposable HTML; see the ctx-report skill).

Execution Procedure

build_or_maintain_kb(project_or_pile) → living_kb

# STEP 0 — Load the cross-cutting constraints (four rules + format conventions)
read("references/consistency.md")        # single-source · same-change · verify-canonical · gate + numbering/archive-by-class
ensure ctx/ skeleton exists — scaffold from assets/ctx-skeleton/ (progress/ · spec/ · decisions/ · reports/ · scratch/ · README.md)

# STEP 1 — Classify by LIFETIME, not stage (write from any direction; NOT a waterfall)
for each finding / note / doc:
    cls = classify(finding)
        # current product truth         → spec/ or overview.md   (edit in place)
        # a MADE choice + why + rejected → decisions/NNNN         (append; supersede, never rewrite)
        # where we are / what next       → progress/              (edit in place; pointers only)
        # raw / uncertain / research      → scratch/               (non-authoritative; not a scan entry)
        # normative extract of a theory   → spec/ + decisions/     (concept can be normative)

# STEP 2 — Converge scattered sources into the KB (any consolidation of ≥2 sources)
if consolidating notes / reports / subagent outputs:
    merged = Skill("ctx-merge", sources)     # disposition ledger; a drop is a recorded decision, never silent
    assert merged.delivered                  # GATE — do not proceed believing a merge happened if it didn't

# STEP 3 — Write build-grade docs
if writing / restructuring a spec, ADR, or design doc:
    spec_result = Skill("ctx-spec", target)  # formats, granularity, ADR boundary + numbering, spec/design/, the writing standard
    assert spec_result.delivered             # GATE

# STEP 4 — Track progress / hand off between sessions
if updating work state, opening a subtree, or handing off to a new session:
    progress_result = Skill("ctx-progress", ctx/progress/)  # single-file-or-tree, frontmatter, handoff, archive-when-long
    assert progress_result.delivered         # GATE

# STEP 5 — Producing / distilling / merging a report for human review?
if writing or distilling an HTML report for the human:
    report_result = Skill("ctx-report", ctx/reports/)       # report format · distillation · rolling-merge · archive
    assert report_result.delivered           # GATE

# STEP 6 — Apply the cross-cutting constraints (mandatory before finishing any multi-doc edit or behavior-changing commit)
apply("references/consistency.md")       # verify single-source · same-change (incl. code↔doc) · verify-against-canonical · the gate — fix any violation before committing

# STEP 7 — Stop (JBGE): smallest living-doc set that lets an agent build correctly. Do not over-document.

Each read() and Skill() above is a decision-layer entry — enter the module when the step runs; do not paraphrase it here.

When to call the companions

You (the agent) classify and route; the user never hand-picks a companion. The user describes their work in plain language ("nail down the design for X, then build it" / "merge these notes" / "where does this finding go?"). Read the intent and route by what it needs. When one ask spans both a durable contract and transient work — the common "settle the docs, then execute" case — produce BOTH: the durable "what must be true" → spec/ (via ctx-spec) and the doing/tracking → progress/ (via ctx-progress), linked by REQ-### ↔ T###. Never ask the user to choose "spec or progress" — that classification is this skill's job. Signals: should/must/design/architecture/requirements → durable → spec; let's do/plan/next/where are we → transient → progress; a pile of notes to settle → ctx-merge.

• Converging scattered notes / many reports / subagent outputs into the KB → ctx-merge (merge discipline + human-adjudicated routing). Use it for any consolidation of ≥2 sources — a silent merge drops content.
• Writing or restructuring a spec, ADR, architecture doc, or design/design-system doc → ctx-spec (formats, templates, granularity, ADR content boundary; spec/design/ and the writing standard live here).
• Updating work state, opening a progress subtree, or handing off to a new session → ctx-progress (single-file-or-tree progress, frontmatter, handoff protocol, archive-when-long).
• Writing an HTML report for the human to review, distilling their comments, or merging a pile of reports → ctx-report (report format, keep/drop/unsure distillation, rolling-merge, archive-aside).
• Bringing an existing (brownfield) repo under ctx — where /ctx mounts, in-repo vs external symlink, onboarding a messy tree → ctx-adopt (minimal-disruption onboarding; routes the actual doc-writing to the domain skills).

The two companions below are not document skills — one is operational, one is meta (a cross-SOT checkpoint over progress + spec/decisions):

• Hosting a dev server / watcher / build daemon that must survive a reset or be shared across parallel sessions → ctx-serve (tmux-hosted processes, a committed services.md topology manifest, live status detected-not-stored).
• Preparing to /compact or reset the session — sweeping everything decided into its SOT home first → ctx-compact (a thin cross-SOT checkpoint over ctx-progress + decisions/spec + the folder indexes; introduces no new rule).

The cross-cutting hard constraints — single-source · same-change (incl. code↔doc) · verify-against-canonical · the gate — are not a companion you route to; they live in references/consistency.md, which every skill (and STEP 0/6 above) loads before it commits.

---

The rest of this file is orientation — the problem ctx solves, the finer classification calls, the folder shape, and honest limits. The procedure above is the operative part; read on when you need the why.

The problem this solves

Long, multi-session AI-agent research/design produces documents that rot into a pile that is redundant, contradictory, and stale. Symptoms: docs multiply endlessly; changing one thing forces chasing a chain of edits across many docs; old docs go 50%-true/50%-false so you can't tell what's current; the process order feels chaotic ("research first or design first?"); dozens of review reports pile up and merging their conclusions becomes its own unsolved problem.

Root cause: organizing docs by pipeline stage (requirements→research→design→decisions→progress) leaves a persistent, editable, go-stale doc at every stage.

Theory & evidence — not a separate class

Psychology, research evidence, a chosen theoretical framework: conceptual content can absolutely be normative (normative = "is this binding on what we build", not "is it concrete vs abstract"). So split it:

• The normative extract — which paradigm, how it's applied, and (in decisions/) why this one not others — is BINDING → goes to spec/ (a design principle) + decisions/ (the framework choice).
• The raw literature / evidence body → scratch/ (disposable), cited by the spec/decision.
• Classic theory → just name it (the model already knows it). New (2026) theory → cite the URL + a one-line summary in the spec. A theory you designed yourself IS a spec (you authored it).

Reliability flows from the SOT's reference: a disposable file earns trust only where a SOT doc links to it.

Disposable is NOT a scan entry (false-positive guard)

scratch/ and reports/ are non-SOT: they are not a scan / entry point. A disposable file is opened only where a SOT doc (spec / decision / progress) explicitly links to it — deep-scanning scratch/ to "understand the project" surfaces rejected and obsolete ideas as false positives, as if they were current truth. (This is a model characterization; its binding MUST/NEVER form is references/consistency.md Rule 1.)

Normative vs informative — spec vs report

The split above is a status distinction: a spec states conclusions and constraints (normative, build-grade); a report is discursive and disposable (informative). A spec that teaches, compares options, or narrates what happened has let informative content leak in — move it to a report (for review) or an ADR (the why). The one "why" that stays in a spec is its INTENT (a one-clause so-that that scopes a rule). The full writing standard — the four axes (normative/informative · RFC-2119 · IRB why-discipline · granularity) — lives in ctx-spec.

The canonical folder

The knowledge root is ctx/ — a single folder at the project root. This is the stable mount point; its backend is an in-repo directory by default, or a gitignored symlink to an external store when the context must not ship (see ctx-adopt).

ctx/                       # knowledge root — the single SOT for product + work truth
├─ progress/               # LIVING · work truth: current focus + next + "read first"
│                          #   (single file progress.md when small; a tree when it grows — see ctx-progress)
├─ overview.md             # LIVING · product truth, system level (C4 Context + Container)
├─ services.md             # LIVING · infra topology: long-running processes this project hosts (optional; see ctx-serve)
├─ spec/                   # LIVING · product truth (see ctx-spec)
│  ├─ <subsystem>.md       #   one clean current-truth doc per subsystem
│  ├─ design/              #   design is a spec SUBTYPE; token .json = diffable contract, .html = reference-grade intent (ctx-spec → design-system.md)
│  └─ archive/             #   whole old specs on a foundational rewrite (versioned name)
├─ decisions/NNNN-*.md     # APPEND-ONLY · why (ADR; see ctx-spec). Superseded → status flip in place, never deleted
├─ reports/                # DISPOSABLE · HTML a human reads for review (NON-SOT; see the ctx-report skill)
│  └─ archive/
├─ scratch/                # DISPOSABLE · ALL raw: notes, prompts, research dumps, comparisons (NON-SOT, not a scan entry)
│  └─ archive/
└─ README.md               # index (esp. reports/) + the project's chosen formats

(No separate CONVENTIONS.md file — the project's chosen formats live in ctx/README.md, so it can't be confused with this skill's references/consistency.md.)

Definition of Done for a ctx folder

The skeleton above is the model — what a correct ctx folder looks like. Whether a given setup actually is done (skeleton present, each folder indexed, SOT seeded, indexes in sync, no orphan docs, backend + confidentiality boundary decided) is checked against the ctx-folder Definition-of-Done checklist, which lives with the other standing gates in references/consistency.md § Rule 4 (the gate). Model here; the DoD gate that verifies it there.

The external store — how a shippable artifact records its own making

When the deliverable is a shippable artifact (a skill, an app, a video) whose docs must NOT ship with it, keep the docs in a sibling <name>-ctx/ (external, never shipped), managed by this methodology. That <name>-ctx/ folder itself IS the knowledge root — it plays the role of ctx/, so its children are spec/ decisions/ progress/ reports/ scratch/ directly (no nested ctx/). The published artifact = the output; the external store = why it is the way it is (its spec + its ADRs). This is where a design decision like "we supersede old ADRs in place (never archive them), because a superseded decision is live knowledge" is recorded — so the reasoning is never lost. This collection dogfoods it exactly: this skill ships as ctx/, its own making lives in the sibling ctx-ctx/.

Cross-cutting rules & the read-side habit (pointers, not mechanics)

The prescriptive cross-cutting MUSTs — single-source · same-change (incl. code↔doc) · verify-against-canonical · the gate — plus the shared format conventions live in references/consistency.md, which every skill loads before it commits. In particular the gate (author the acceptance checklist before you execute; validate before you claim "done") is consistency.md Rule 4 — ctx names the pattern behind spec acceptance-criteria / progress task-completion / report self-verification / the ctx-folder DoD; consistency.md holds the mechanics.

Read-side habit (why the append-only trail earns its keep): before an architecturally-significant choice, the decisions/ trail + reject log get scanned so a settled question isn't re-litigated and a rejected concept isn't reintroduced — a decision nobody consults is just history. Its binding form is ctx-spec § Hard constraints (ADR discipline); the reject log feeds from ctx-merge.

The loop

CHAOS (notes/conflicts) → debate/converge → scattered good questions + local answers
   → [ctx-merge] sink into the KB → spec/decisions (current truth + why)
   → [ctx-spec] write build-grade specs → agent builds → tests are the arbiter of behavior
   → new conclusions fold back into the KB (edit spec in place / append decision). Repeat.

Stop condition (don't over-build docs)

The goal is the SMALLEST set of living docs that lets an agent build correctly. Apply JBGE (Just Barely Good Enough): stop documenting when the next sentence costs more than its value. Anything derivable from code/tests (API refs, generated docs) is generated, never hand-maintained. Anything derivable from spec + decisions (explanations, comparisons) is derived on demand, never stored. Scratch and reports are disposable by default.

Honest limits

Every mechanism trades discipline for cleanliness: append-only decisions accumulate (but appending is cheap and the index gates the token cost); living specs rot without a freshness check; scratch/reports pile up if never swept; confidence labels become theater without periodic re-verification. The model removes the structural causes of rot — it does not remove the need to actually maintain.

References

• references/consistency.md — the cross-cutting constraints every edit must satisfy: the four rules (single-source · same-change incl. code↔doc · verify-against-canonical · the gate) + the shared format conventions (numbering, archive-by-lifetime-class, file-or-folder units, README-per-folder). Every skill loads it before committing.
• (The reports/ workspace method moved to the ctx-report companion skill — no longer a reference here.)

Note on restatement (DRY carve-out): independently-loaded skills and references MAY restate a load-bearing rule in one line and link back here for the full version. Within this skill (SKILL.md + its own references/), each fact has exactly one home.