doc-mirror
⭐ 0 stars • 🕑 Updated 2026-06-09
📦 Auto-published from the monorepo • CHANGELOG • sancovp/doc-mirror
A Claude Code plugin that turns your Claude Code into a documentation-and-development operating
system for any codebase.
doc-mirror is a claude system (an "AI operating system"): not a single command, but a folder the
agent lives in + a core loop it runs every turn + skills, hooks, rules, and CLIs on top. Installing
this plugin gives your Claude Code that operating system — it adds skills, hooks, rules, and CLI tools,
and changes nothing else about your setup.
What it does: it keeps a 1:1 documentation mirror of a codebase — one explanation file per source
module — and it develops the codebase through a small, fixed state machine so the documentation
never drifts from the code, and the agent never improvises a flow.
The one idea
Two agents running doc-mirror on the same codebase produce the same structure. That invariance is
the whole point. It comes from three rules:
- Every doc file is exactly one legal kind (see The Law below). No random session/fix/topic
documents, ever.
- The agent is a state machine, not a freestyler. It is always inside one state; it does that
state's work, advances a saved cursor, and loops. The flow is scripted, not invented each turn.
- Documentation is paired with code and committed together (fork-on-change), so the docs can
never silently fall behind the code.
How it runs — the core loop
Every session (and after every compaction), the first thing the agent does is use the doc-mirror-boot
skill. Boot primes the agent with the core loop, shows it the whole state machine, and routes it — via
the cursor (a persisted "you are here" pin) — into the one state it is currently in:
doc-mirror-boot → read the cursor → enter the state it names → do that state's leg
→ advance the cursor + journal the why → loop (back to boot, or exit)
The states are skills:
| state (skill) | what it is |
|---|
doc-mirror-init | first-time mirror an unmirrored codebase (enumerate modules → write a doc per module → synthesize the index files → closure test) |
doc-mirror-seework | the dispatcher: read the backlog, pick the next gap, route to the state that does it |
doc-mirror-change | a module changed → re-derive its doc → commit code+doc together → run the closure test |
doc-mirror-prompts | need an agent to do a task → search a reusable, reliability-scored prompt library, or author one |
Transitions are each state's reasoning chain plus the cursor; a hook keeps the moves sensical; the loop
prompt + an always-on rule keep the machine in front of the agent every turn, even after a compaction.
The Law (what every doc file must be)
For a codebase C, every file in its documentation layer is exactly one of:
doc(m) — the impl doc: a 1:1 explanation of what one module's code actually is, at
docs/mirror/<relpath>.md. Written first, always. Records only what exists.vision(m) — the vision doc: every idea/decision about a module not yet built, at
docs/vision/<relpath>.md. The gap between vision and impl is the backlog.- a named synthesis, one of the 6
context/ index files, a repo-local rule/skill, or the
dated journal (context/journal/).
Nothing else is legal. The closure test is the gate: the doc set must biject 1:1 with the module
set, and every file must classify under the kinds above. A run is "done" only when it passes.
What's in this plugin
