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:
@@ -39,11 +39,13 @@
|
|||||||
"Bash(mkdir -p docs/plans && date \"+%Y-%m-%d-%H%M\")",
|
"Bash(mkdir -p docs/plans && date \"+%Y-%m-%d-%H%M\")",
|
||||||
"Bash(go install *)",
|
"Bash(go install *)",
|
||||||
"Bash(go env *)",
|
"Bash(go env *)",
|
||||||
"Bash(git rm *)"
|
"Bash(git rm *)",
|
||||||
|
"Bash(mkdir -p /Users/jan.novak/srv/go/egress-proxies-operator/docs/plans-executions)"
|
||||||
],
|
],
|
||||||
"additionalDirectories": [
|
"additionalDirectories": [
|
||||||
"/Users/jan.novak/srv/go/egress-proxies-operator/.claude",
|
"/Users/jan.novak/srv/go/egress-proxies-operator/.claude",
|
||||||
"/Users/jan.novak/srv/go/egress-proxies-operator/docs/plans"
|
"/Users/jan.novak/srv/go/egress-proxies-operator/docs/plans",
|
||||||
|
"/Users/jan.novak/srv/go/egress-proxies-operator/docs"
|
||||||
]
|
]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
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
|
Create `docs/plans/` on first use. Plan files are committed to the repo so other
|
||||||
contributors can review historical decisions.
|
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
|
### Changelog
|
||||||
|
|
||||||
Maintain a running changelog in `CHANGELOG.md` at the repo root. After every
|
Maintain a running changelog in `CHANGELOG.md` at the repo root. After every
|
||||||
|
|||||||
19
docs/plans-executions/2026-08-07-1747-proxy-operator.md
Normal file
19
docs/plans-executions/2026-08-07-1747-proxy-operator.md
Normal file
@@ -0,0 +1,19 @@
|
|||||||
|
# Execution log: proxy-operator
|
||||||
|
|
||||||
|
Pairs with [docs/plans/2026-08-07-1747-proxy-operator.md](../plans/2026-08-07-1747-proxy-operator.md).
|
||||||
|
|
||||||
|
## Step 0 — Branch and scaffold
|
||||||
|
|
||||||
|
Branched `feat/proxy-operator` off the unborn `main`, installed kubebuilder v4.15.0
|
||||||
|
via `go install`, and ran `kubebuilder init` + `kubebuilder create api` in place.
|
||||||
|
|
||||||
|
Worth noting: `--domain example.com --group crawl` landed on the correct CRD group
|
||||||
|
(`crawl.example.com`) on the first try — the doubling trap the plan called out
|
||||||
|
(`--domain crawl.example.com --group crawl` → `crawl.crawl.example.com`) was avoided
|
||||||
|
by using the right flags from the start. `CONTROLLER_TOOLS_VERSION` came out at
|
||||||
|
`v0.21.0` by default in this kubebuilder release, so no Makefile edit was needed there.
|
||||||
|
Dropped the scaffolded `.github/workflows/` since the remote is Gitea. Pre-existing
|
||||||
|
`CLAUDE.md`/`CHANGELOG.md` content survived untouched; kubebuilder added its own
|
||||||
|
`README.md`, `AGENTS.md`, `.golangci.yml`, `.devcontainer/`, `Dockerfile` on top —
|
||||||
|
those get edited or left as-is in later steps. `go build ./...`, `go vet ./...`, and
|
||||||
|
`make manifests generate` all ran clean. Committed as `076bc66`.
|
||||||
Reference in New Issue
Block a user