dot-plan

The idea in five lines

• One human. Everyone else is an agent.
• The plan is a list. Phases, and items small enough to finish in one sitting.
• One item, one fresh agent. It does the item, hands it over, and is gone. The next agent starts from what is written down.
• Nothing waits for you. What an agent cannot decide goes on a list, the agent picks the safest option, and the run continues.
• Unfinished work counts for nothing. An item is done when it is committed on a green gate.

Modes

Four modes run in order over the life of a plan. audit runs whenever you ask for it.

The run loop

The main session is the supervisor. It never writes code. Each item goes to a fresh worker, risky ones also to a reviewer on another model, and everything that matters lands in a file. Nothing lives in a context window.

1. Preflight. A lock stops a second run. Files already changed in the tree are listed as not ours, and no agent touches them. A heartbeat is armed.
2. Spawn a fresh worker with the item, the Rails, the gotchas and the sections the item names.
3. Check the proof. The supervisor recomputes the hash of the staged code and looks for a PASS line in the gate log. It never runs the gate again itself.
4. Review if risky. A fresh agent on another model reviews it with the checklist. A fresh fix agent fixes only the findings.
5. Commit, one per item, the item named in the body.
6. Failure. Discard only the worker's files, retry once with the diagnosis, then skip the item with a deferred row and move on. An API overload is retried with a backoff and not counted.
7. Staying alive. The heartbeat checks the worker's age and pushes you a status line. A worker is stopped only when it is past its time and the tree has stopped growing.

The worker's contract

A short reference file every worker gets, the same for every project.

1. Read only what you were given, and read the code, not only the notes. Line numbers drift.
2. Behaviour change: failing test first. Watch it fail, then make it pass.
3. Stage what you touched, by name. Never git add -A, never commit, reset or push.
4. Quick checks while working, the gate once at the end, after staging. Red: up to two fix tries, then say so and stop.
5. A correction is fixed twice, in the work and in the repo, in the same change.
6. Write it once. The item in full in the session log, one line on the tick, one gotcha at most.
7. Never ask. Take the safest reversible option and write it down, or mark the item for a human and stop.

Files

Everything lives in .plan/, committed, so a plan travels with the repo and any machine can resume it. Only logs/ stays local.

Config

Plain key and value lines. The skill runs exactly these commands and never guesses at a build system.

build   = npm run check            # the gate: green before every commit
quick   = npm run check:quick      # while working; never the gate
full    = npm run check:all        # at every phase gate
verify  = npm run e2e              # optional; per item only when verify_paths moved
verify_paths = src/routes/**

worker_model   = opus              # latest Opus; else the session's own model
reviewer_model = fable             # latest Fable; else latest Opus, fresh context, logged
risky = src/db/migrations/**, src/auth/**, src/payments/**
item_timeout   = 1800

lands  = local                     # local: commits on main, never pushes
                                   # branch: one branch per plan, rebased at each gate, PR at close

Rules

The skill's defaults. A project changes them only in ENGINE.md, and only by writing the difference.

1. One item, one fresh agent.

   It reads only its item, the Rails, the gotchas and the sections the item names. Never the whole plan. Small items in one phase may share an agent and a commit.

2. The gate.

   Every item passes the build command before it is committed, and the proof is a PASS line for the hash of the staged code. Green or it does not commit.

3. The reviewer did not write it.

   An item that touches a risky path is reviewed by an agent that did not make it, on another model. One review, then one fix round by a fresh fix agent. A finding that keeps coming back becomes a test.

4. Earlier phases stay green.

   Their tests run on every commit. A golden file that changes is explained in the commit, file by file.

5. A correction is fixed twice.

   Once in the work, once so it cannot happen again, in the same change: code that makes it impossible, then a test, then a checklist line, then a written line.

6. Defer, never wait.

   An agent that cannot decide picks the safest reversible option, writes a DEFERRED row, and continues. An unattended run has no way to ask you.

7. Write it once.

   An item's details go in the session log. The tick is one line. A gotcha is a line or two.

8. Leave what is not yours.

   Files already changed when the run started are never staged, edited or discarded. A discard reverts only the worker’s files. A project’s own hard stops are never removed.

9. Count between phases.

   Items per hour, process share and its trend, reviewer calls against catches, escaped defects, your interruptions, all computed from the logs.

10. One report at the end.

    What was done, what was skipped and why, every deferred row grouped by who acts, and the numbers.

The never-list

dot-plan ships no hard stops: no deny rules, no hooks, no guard scripts. In the build it came from, the guard only ever raised false alarms and cost a day. It also never removes a project's own. What it carries is a short written list every agent obeys.

• Never rewrite or discard committed history.
• Never touch real data, a production system, or a customer-facing channel.
• Never delete ignored files, secrets, or untracked files you did not create.
• Never edit Claude Code settings or the .git folder.
• Never lower a floor or an exit criterion without saying why.
• Never delete or rewrite the spec. Corrections go in DRIFT.
• Never ask during an unattended run, and never push to main.

The numbers

Five numbers, computed from the logs at every gate. They are what stops the process from growing, because from inside a process every check looks necessary.

From the old skills

Where it came from

One build of about 130 items, run unattended on the older skills, with a process that grew the way processes grow: a guard on every command, a judge on every commit, a coverage ratchet, an inbox of lessons, a reviewer on every risky item. By its second phase the process had nearly as many tests as the product. Then I counted.

The guard blocked a handful of commands, all false alarms. The judge and the ratchet caught nothing a plain run would have shipped. The reviewer, a fresh context on another model, caught something real on most of its calls. So the gate, the reviewer and the numbers stayed, and the rest went. Delivery went from about two items an hour to about four in the next phase, with no known defect escaping, and the human was never needed mid-run.

One lesson went straight into the skill. The process share in those phase reports was estimated by the agents, and the estimates were low. dot-plan computes it from the logs.