Opt-in plugin access keeps runtime/skills in the host bundle and process archives
in .coderail/workspace/, inside the same Git repository. Product source, formal
documents, and autonomous project rules stay in place. See workspace access
for previewable migration, detachment, recovery, and explicit product exports.
Existing projects are not migrated automatically. Full Git history remains visible.
Spec is the output, not the input.
Vibe coding explores; CodeRail converges. As you build, discover, and change your mind, the tool quietly turns what you learned into guardrails — so exploration compounds instead of unravelling. Your AI assistant stops drifting, stops declaring victory too early, and always leaves a state the next session can pick up.
No server. No accounts. No new methodology to learn. Just three commands and a docs/ folder that stays honest.
If you are new to programming and want to understand what CodeRail solves, what it does during development, and how it works with Spec Kit, grill-me, and Superpowers, read What CodeRail is: project governance for vibe coders (Simplified Chinese).
flowchart LR
User["Human or AI agent"]
Shim["Repo-local launcher<br/>.coderail/coderail.py"]
Facade["CodeRail facade<br/>scripts/coderail.py"]
Lifecycle["Lifecycle<br/>start / check / done / switch"]
Gates["Gates and state model<br/>scope / TDD / Doctor / repository state"]
Truth["Repository truth<br/>TASKS / PROGRESS / TRACE"]
Git["Verification and local Git<br/>tests / exact scoped commit"]
Views["Navigation and continuity<br/>Inspect / graph / HANDOFF"]
User --> Shim
Shim --> Facade
Facade --> Lifecycle
Lifecycle --> Gates
Lifecycle --> Truth
Gates -. reads .-> Truth
Lifecycle --> Git
Git --> Truth
Truth --> Views
Views --> User
The launcher connects a project to the CodeRail home. The lifecycle facade checks scope and evidence, updates plain-text repository truth, and commits only the exact safe task files. Detailed system, lifecycle, closeout, and state authority diagrams are in docs/CODERAIL_DIAGRAMS.md.
# 1. Get CodeRail and link its checkout into your project
git clone https://github.com/HaipingShi/coderail
python3 coderail/scripts/init_project.py --target /path/to/your/project
# 2. In your project, work with three commands
python .coderail/coderail.py start "add a login page" # begin a task
python .coderail/coderail.py check # am I on track?
python .coderail/coderail.py done # finish safelyThat is the whole interface. Your AI assistant reads the installed AGENTS.md and follows the same three commands automatically.
The source-linked setup above is convenient for development. CodeRail also has
a Phase 2 independently installed mode: one verified candidate is stored in an
immutable versions/<version> directory, while each project commits an exact
version pin and keeps machine paths ignored. Missing, mismatched, or stale
runtimes fail before project writes; upgrades install side by side and rollback
retains the old version. See INSTALL.md for candidate install,
migration, upgrade, and rollback commands. This verifies the minimum
installable bundle only—not host loading, publication, or downstream rollout.
start "..." — records what you are about to do, which files it may touch, and how you will know it is finished. This one step is what prevents scope creep and "wait, what was I doing?" later.
check — answers "am I on track?" in plain language: what is active, what is missing, whether you could finish right now.
done — the safety net. It verifies tests/checks pass (or you explicitly recorded a manual check), confirms changes stayed inside the promised files, syncs the docs, commits only the safe task-related files, and tells you the next step. If something is off, it refuses and says exactly what to fix. An AI assistant cannot talk its way past it.
inspect and check are read-only. They report structured diagnostics with a
severity, category, blocking stage, evidence, and recommended action. Stale
handwritten lifecycle prose is projection_staleness: it may be cleaned up in
a maintenance batch, but it does not block product formulation or create a new
governance task. Exact machine-marker conflicts, scope violations, and failed
verification still block the relevant lifecycle stage.
Generated snapshots are synchronized explicitly:
python .coderail/coderail.py sync-projections # preview, zero writes
python .coderail/coderail.py sync-projections --apply # write listed projectionsinspect is the Agent Blackboard: it leads with control-plane state,
diagnostics, exact evidence references, and recovery actions. It never presents
NORTH_STAR goals as verified product capability. Read the separate owner view
without changing repository state:
python .coderail/coderail.py owner-summary --locale zh-CNNo extra commit-approval question is needed after those gates pass: successful done is already permission for one exact local task commit. Use --no-commit only when you explicitly want to review the diff first. Push, tag, and release always remain separate user decisions.
For owner delivery, a task may add an explicit structured Delivery Contract.
done emits only a localized three-to-six-sentence Owner Receipt; pass
--owner-locale zh-CN or en to override the saved or explicit host
preference. Necessary English must be annotated (the exact proper names Codex,
Claude, CodeRail and OpenGCUI are allowed), while task IDs, paths, lifecycle
jargon, commits, and safe-file lists remain in the Agent Blackboard and
Technical Report. The same normalized facts are appended to tracked
docs/DELIVERIES.jsonl, so product evidence survives hot-TASKS compaction and a
fresh clone without becoming lifecycle authority. The owner language is now
resolved deterministically: explicit flag, saved preference, explicit host
locale, then English. Unknown-but-valid locales or renderer failures emit a
diagnostic fallback without repeating tests, commits, or completion writes.
They never weaken failed verification, unsafe scope, required delivery facts,
or transaction completion. Task finalization never implies milestone or product completion. See
references/DELIVERY_CONTRACT.md.
start adds a fenced Delivery Draft authoring template at the resolved task
path. Fill it in, then rename the heading to Delivery Contract.
check --owner-locale zh-CN catches invalid explicit syntax before closeout and
reports copy warnings without running registered verification. An untouched
draft preserves legacy not_assessed behavior; it makes no completion claim.
For wording-only corrections, owner-summary --presentation-template prints
fact-bound JSON. Save/edit that input and use owner-summary --presentation <file> --locale zh-CN;
add --delivery-id <id> for a historical delivery. The input may include
project-relative evidence paths and SHA-256 hashes, but cannot replace assessment
status, command results or task authority. Rendering does not save the input,
rewrite facts, run tests or commit. Keep the reusable input with your handoff
if needed; supplemental hashes are not test passes. Idle manual guidance
leaves paused tasks paused until explicitly selected.
Refresh the evidence view or query only relevant dynamic documentation:
python .coderail/coderail.py progress-view
python .coderail/coderail.py knowledge query "delivery"The first command maintains an offline Markdown checklist and self-contained
HTML execution view under .coderail/reports/. Active tasks are expanded; other
tasks remain in a searchable index, without a default full-history graph.
progress-view --task T-ID returns one task's evidence and direct dependency
blockers in separate progress-T-ID.md / .html files. Dependency explanations
never replace scope, authorization or execution gates. Checkboxes distinguish implementation,
machine verification, and human acceptance, and become stale when related code
changes. knowledge query returns an index and relevant snippets classified as
source facts, confirmed decisions, drafts, stale regions, or missing sources.
Task scope is fail-closed. If one path matches both an Allowed rule and a Forbidden rule, start, switch, or closeout reports SCOPE_CONTRADICTION with the exact path and both rules. Allowed never silently overrides Forbidden; narrow the forbidden glob before continuing.
If verification passes but the exact Git commit cannot run, CodeRail preserves the complete safe-file snapshot as verified-commit-pending. Restore Git permission and run coderail done --resume (optionally overriding --owner-locale), or manually commit only the exact files printed by CodeRail and then run the same resume command. Use coderail done --no-commit to choose this manual mode from the beginning. Resume never reruns verification or duplicates PROGRESS/TRACE entries.
done --resume accepts and completes the exact snapshot commit. It cannot be
combined with --no-commit; that option applies only to the initial closeout.
If the owner rejects the snapshot instead, hash the original bytes of
.coderail/pending_close.json and use the explicit, fully attributed recovery
command:
python .coderail/coderail.py recover --abandon-pending \
--task T-044 --snapshot-sha256 <sha256> \
--reason "<reason>" --authorized-by "<owner>" \
--authorization-ref "<reference>"Abandon records the full snapshot and authorization in the append-only
docs/CODERAIL_RECOVERY.jsonl before clearing recovery state. It rejects that
snapshot and does not complete the task, create a commit, or invent verification,
acceptance, finalization, or delivery facts. Repeating the exact command is
idempotent, including after an interruption between the ledger append and
pending-file cleanup.
Internal task IDs are permanent retirement identifiers, distinct from optional
display IDs. CodeRail reserves each new internal ID in the versioned append-only
docs/TASK_ID_LEDGER.jsonl, scans current authority plus complete reachable Git
history, pending snapshots, and recovery tombstones before allocation, and fails
closed when history cannot be proven complete (including a shallow clone).
Git revert never releases an internal task ID; a manually supplied display ID cannot
replace or reopen one.
start and next --go refuse to create ambiguous ownership. Use the explicit switch gate when work must branch:
python .coderail/coderail.py switch "new task" --owner-locale en # close and commit the accepted source first
python .coderail/coderail.py switch "new task" --checkpoint --owner-locale en # commit a verified checkpoint, then pause it
python .coderail/coderail.py switch "new task" --dirty-fork # explicit waiver: carry a fingerprinted dirty baseline
python .coderail/coderail.py switch --to T-012 --owner-locale en # close any active source, then resume the destinationIf current work is not safely committable, CodeRail writes an H3 handoff and requires switch --continue-current or an explicit --dirty-fork. Pre-existing dirty files are recorded by path, Git state, and SHA-256 fingerprint so unchanged work is not attributed to the new task. Auto-commit never means auto-push.
Vibe coding is fast and creative — until the project grows. Then docs rot, the assistant drifts from the goal, sessions forget each other, and "done" stops meaning done. The usual fix is spec-driven development: write the spec first, then build. But that assumes you already know what you want — and vibe coders discover what they want by building. Spec-first is not too hard for them; it points the wrong way.
Convergent Coding inverts the arrow. You explore freely; each time something proves true — a task verified, a decision made, a boundary learned — the tool records it as a constraint the next round of exploration must respect. The spec accumulates behind you instead of blocking the road ahead. Exploration stays free; the project stops oscillating and starts converging. When repeated fixing fails to converge, the tool says so and points one level up: rethink the design, or rethink the goal.
In short: discipline runs automatically behind three plain commands. You never write a spec; the tool quietly maintains one for you (goal, task list, decision log, change history) and refuses to let anyone — human or AI — skip verification.
your-project/
├── AGENTS.md # plain-language rules your AI assistant follows
├── .coderail/ # the single entry command
└── docs/
├── NORTH_STAR.md # what you are building, one page
├── TASKS.md # every task: goal, files, how it was verified
├── DECISIONS.md # why things are the way they are
├── HANDOFF.md # how the next session picks up
└── TRACELOG.jsonl # append-only history linking changes to reasons
Plain text, all in git, nothing hidden. Delete the folder and CodeRail is gone.
Pure Python 3 standard library. Works with Codex, Claude Code, and any agent that reads AGENTS.md / CLAUDE.md.
The three commands are a facade over a deeper kernel: verification gates, TDD evidence, drift detection, deterministic drive decisions for long-running autonomous sessions, architecture blueprints, and trace graphs. Power users can call these directly:
python .coderail/coderail.py --help # lists advanced commands
python .coderail/coderail.py why T-046
python .coderail/coderail.py impact docs/BLUEPRINTS.md
python .coderail/coderail.py graph T-046
python .coderail/coderail.py candidate listThe idea behind the tool — Convergent Coding — is written up in references/CONVERGENT_CODING.md. Deep documentation lives in references/. Install details in INSTALL.md. Skills for Claude Code / Codex live in skills/.
MIT