Codify plan-save ordering and add plan execution summaries
The plan for this build was written to docs/plans/ only after Step 0's implementation had already started, instead of as its own first action right after ExitPlanMode. CLAUDE.md said *where* to save plans but not *when* relative to other work, so that ordering wasn't actually enforced. Makes it explicit: copying the plan into docs/plans/ and committing it is its own checkpoint that blocks starting Step 0. Also adds a docs/plans-executions/ convention: one running, chronological summary file per plan, appended to after each completed step, for a human-readable narrative of how the plan actually went (judgment calls, spec gaps, surprises) without duplicating the plan or the diff. Backfills the Step 0 entry for the proxy-operator plan retroactively. Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
24
CLAUDE.md
24
CLAUDE.md
@@ -86,6 +86,30 @@ Include the same timestamp in the plan's header, e.g.:
|
||||
Create `docs/plans/` on first use. Plan files are committed to the repo so other
|
||||
contributors can review historical decisions.
|
||||
|
||||
**Ordering matters:** plan mode itself restricts writes to the default
|
||||
`~/.claude/plans/` location — that's a hard tool restriction during plan mode, not a
|
||||
choice. So the copy into `docs/plans/` cannot happen until *after* `ExitPlanMode`.
|
||||
When it happens, it must be the very first action taken post-exit, committed on its
|
||||
own, *before* any implementation work starts (branching, scaffolding, editing code).
|
||||
Do not fold the plan-file commit into the first implementation commit, and do not
|
||||
defer it until "later" in the same turn — treat "save and commit the plan" as its own
|
||||
checkpoint that blocks starting Step 0.
|
||||
|
||||
### Plan execution summaries
|
||||
|
||||
After finishing each step of an approved plan, append a short, human-readable summary
|
||||
to `docs/plans-executions/YYYY-MM-DD-HHMM-<slug>.md` — same timestamp and slug as the
|
||||
originating plan in `docs/plans/`, so the two files pair up 1:1. Create the file (and
|
||||
`docs/plans-executions/` on first use) after the first step completes; append a new
|
||||
section per step after that, in chronological order (bottom of the file), not
|
||||
newest-first like `CHANGELOG.md`.
|
||||
|
||||
Keep each entry light — a few sentences on what was done, plus anything genuinely
|
||||
interesting or non-obvious about how it went (a judgment call made, a spec gap found,
|
||||
something that didn't work as expected). This is not a duplicate of the plan or the
|
||||
diff; skip steps that went exactly as planned with nothing worth flagging. Commit the
|
||||
summary update together with that step's implementation commit.
|
||||
|
||||
### Changelog
|
||||
|
||||
Maintain a running changelog in `CHANGELOG.md` at the repo root. After every
|
||||
|
||||
Reference in New Issue
Block a user