Brownfield entry: makes ctx take effect on an existing (usually messy) project without touching what the user has — it orchestrates; the domain skills do the real writing. Lifetime model:
../ctx.
The one principle: stable mount point, swappable backend
/ctx is a mount point at the project root — the fixed place any agent looks for context.
Its backend (where the bytes live) is swappable. The agent always reads <repo>/ctx;
whether that is a real folder or a symlink is a deployment detail.
Three rules — what "low-disruption" MEANS
- NEVER restructure the user's existing directories. Only ADD the
/ctxmount + one pointer line. - Default to the lightest backend (in-repo real dir). Upgrade only when separability is actually needed.
- Reorganize the user's tree only when the user asks, or when building ctx makes a change unavoidable — and even then guarantee one thing: ctx logic stays valid.
Execution Procedure
EP1 — pick the backend
if project is published (LICENSE + public remote + package-registry footprint):
backend = EXTERNAL SYMLINK # context must not ship with public code
<repo>/ctx -> ../<project>-ctx/ (symlink gitignored; real bytes live outside the code repo)
else:
backend = IN-REPO DIR # default, zero setup, minimal footprint
<repo>/ctx/ (real folder; commit if the repo is private, gitignore if not ready to share)
Naming: the mount is /ctx inside the project's own directory. When the project name must be
attached to a standalone ctx artifact (the external store, or loose files sharing a parent), use
the suffix form <project>-ctx — it reads as "the ctx of <project>" and keeps a
project and its ctx adjacent in a directory listing.
The external store's exact home (a sibling dir
../<project>-ctx/, a private repo, or a shared machine store) is a deployment detail — default to the sibling dir. Do NOT invent a central store unless the user has many repos AND asks for one.
EP2 — announce it (pointer: tool-agnostic, agent-aware)
The real interop contract is the /ctx folder (vendor-neutral, like .git). The pointer file is only a convenience:
if AGENTS.md exists: add the pointer line to AGENTS.md # respect the project's choice
# @AGENTS.md BRIDGE: if the running agent is Claude Code, ALSO ensure a
# CLAUDE.md exists that imports it — a single line `@AGENTS.md`. Claude Code
# does NOT read AGENTS.md, so without this import a CC session never sees the
# pointer (or any other AGENTS.md instruction). One line bridges both worlds.
elif CLAUDE.md exists: add the pointer line to CLAUDE.md
else (neither): the RUNNING AGENT writes its own native file
(Claude Code -> CLAUDE.md; Codex/Cursor/Windsurf/... -> AGENTS.md)
# never force the user to switch vendors
Fallback: the ctx skill's description is system-prompt-resident, so any agent with ctx installed
recognizes a ctx knowledge base is in play even with no pointer file — and once it loads the skill
body, /ctx is the mount point stated there.
Pointer line (one line): Project context & docs live in ./ctx — managed by the ctx skills; apply their consistency rules when editing ctx docs.
EP3 — sort the scattered docs (DELEGATE — do not re-implement)
Scan the existing tree for doc-shaped content, classify each by lifetime, and route each to the domain skill that owns writing it. ctx-adopt decides where a thing goes; the domain skill decides how it is written to standard:
| Found | Lifetime → ctx home | Delegate the WRITING to |
|---|---|---|
| scattered notes / dated research to converge | (varies) | ctx-merge (atomic conclusions + disposition ledger) |
| current-truth design / architecture | living → spec/ |
ctx-spec (normative spec + acceptance criteria) |
| a decided choice + why | append-only → decisions/ |
ctx-spec (ADR format + status lifecycle) |
| status / next-steps / TODO | living → progress/ |
ctx-progress (tree, frontmatter, handoff) |
| a doc written for a human to review | disposable → reports/ |
ctx-report |
| raw notes / experiments | disposable → scratch/ |
(no format contract; leave as-is) |
Produce a migration plan (found → ctx home → delegated skill → action), show it to the user, move nothing until approved. Never touch code files. This routing is what stops ctx-adopt from emitting shallow, standard-violating spec/decision stubs — the domain skills carry the format.
EP4 — code-topology check (last, subordinate, respectful)
After ctx is in place, assess whether the repo itself would benefit from a structural change (docs & code hopelessly interleaved; a monorepo that should split). Surface it as a recommendation with rationale. Act only if (a) the user asks, or (b) building ctx made a repo change unavoidable. Default: respect the repo as-is. (Absorbed repo-scaffold concern — code topology serves ctx, never drives it; greenfield code skeletons are a one-line starter note, not a system.)
Definition of done (stop condition = standard)
/ctxmount exists at the right place with the right backend.- pointer line added to the correct file (or skipped, with the description-fallback noted).
- confidentiality gate: backend holds secrets AND code repo is public →
/ctxis a gitignored symlink out, verified never committed. - migration plan produced (executed if approved) via the delegated domain skills; no code files moved.
- the ctx-folder DoD checklist (
../ctx/references/consistency.md § Rule 4 (the gate); skeleton model in../ctx/SKILL.md § The canonical folder) passes.
Routes to
ctx (model) · ctx-merge (converge) · ctx-spec (spec/ADR) · ctx-progress (progress) · ctx-report (reports). Absorbs the former repo-scaffold.