🌐 English · 中文
docs-discipline
Give your AI-coded project a memory that survives across sessions.
Every new AI coding session starts cold. The decisions, the dead-ends, the "where were we?" from last time — gone. Meanwhile your docs quietly drift away from the code. On long, exploratory work this is brutal: you burn the first twenty minutes of every session re-explaining context your agent already figured out once.
docs-discipline turns the end of each session into a 60-second ritual. One command — /docs-discipline:codify — files what this session learned into durable docs, checks them for drift, and (optionally) writes a handoff so the next session picks up exactly where you left off.
Why you'll want it
- 🧠 Cross-session memory. Findings and decisions land in your repo as real files — so a fresh session continues the last one instead of restarting it. This is the whole point.
- 🔔 It reminds you. Setup installs a one-line habit anchor in your
CLAUDE.md, so your coding agent offers the ritual on its own at session end. Nothing to wire up, nothing to remember.
- ⏱️ One command closes the session. codify → automatic doc-health review → optional handoff plan, all in a single pass.
- 🛰️ Drift radar. Catches broken links, stale timestamps, orphaned docs, the same "fact" restated in five places, and B-layer "current state" docs that quietly bloat with per-session narrative — the root causes of docs that lie.
- 🪶 Zero lock-in. No templates. No enforced folder layout. It never silently rewrites your docs — it proposes, you approve. Every write is yours.
- 🎯 Built for the work that needs it most. Multi-week spikes, research, architecture — the big, exploratory tasks where losing the thread between sessions costs you the most.
The magic moment: you close a session, open a brand-new one a week later, and your agent already knows what was decided, what's half-done, and what's next — because it's written down, not held in a context window that's long gone.
Quickstart (30 seconds)
Claude Code installs plugins through marketplaces. This repo is its own single-plugin marketplace, so two commands set it up:
/plugin marketplace add circlecrystal/docs-discipline
/plugin install docs-discipline@docs-discipline
(<plugin-name>@<marketplace-name> — both happen to be docs-discipline here.)
Heads up: docs-discipline is also being submitted to Anthropic's community marketplace. Once it lands there you can instead /plugin marketplace add anthropics/claude-plugins-community and /plugin install docs-discipline@claude-community. Until then, the direct install above is the way.
Then, at the end of each session, run:
/docs-discipline:codify
That's it. The first run sets your project up automatically (see Phase 0 below) — there's no separate init step.
To update later:
/plugin marketplace update docs-discipline
What's in the box
Two slash commands and one script — nothing that runs on its own:
| Component | What it is |
|---|
/docs-discipline:codify | The end-of-session ritual: self-bootstrap → codify → review → optional handoff |
/docs-discipline:review | Standalone doc-health checkup (drift + SSOT) |
scripts/drift-check.sh | A read-only Bash scanner, copied into your repo on first run, that powers the drift heuristics (also callable from CI/cron) |
CLAUDE.md stub | A minimal habit anchor + A/B scaffold, created or appended on first run |
No agents, no hooks, no MCP servers, no LSP servers. Nothing wires itself into your session loop, so the per-turn context cost is effectively zero — the commands run only when you invoke them.
Requirements
- Claude Code with plugin support (the
/plugin command).
- Bash for
drift-check.sh (macOS/Linux; it handles both BSD and GNU date). The agent-driven phases work without it — only the scriptable drift scan needs a shell.
- Git is optional:
drift-check.sh uses it when present (to respect .gitignore and read commit dates) and falls back to a plain file walk when absent.
Safety & permissions — what it touches
docs-discipline is deliberately low-trust. Exactly what it does, and does not, do:
