From a5f0aa95d2943742f4609d8b4807a1d2ae702d30 Mon Sep 17 00:00:00 2001 From: Jan Novak Date: Fri, 7 Aug 2026 20:34:05 +0200 Subject: [PATCH] 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 --- .claude/settings.json | 6 +++-- CLAUDE.md | 24 +++++++++++++++++++ .../2026-08-07-1747-proxy-operator.md | 19 +++++++++++++++ 3 files changed, 47 insertions(+), 2 deletions(-) create mode 100644 docs/plans-executions/2026-08-07-1747-proxy-operator.md diff --git a/.claude/settings.json b/.claude/settings.json index e3415b4..cdc16e7 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -39,11 +39,13 @@ "Bash(mkdir -p docs/plans && date \"+%Y-%m-%d-%H%M\")", "Bash(go install *)", "Bash(go env *)", - "Bash(git rm *)" + "Bash(git rm *)", + "Bash(mkdir -p /Users/jan.novak/srv/go/egress-proxies-operator/docs/plans-executions)" ], "additionalDirectories": [ "/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" ] } } diff --git a/CLAUDE.md b/CLAUDE.md index 099cd93..3900081 100644 --- a/CLAUDE.md +++ b/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-.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 diff --git a/docs/plans-executions/2026-08-07-1747-proxy-operator.md b/docs/plans-executions/2026-08-07-1747-proxy-operator.md new file mode 100644 index 0000000..b0b81d6 --- /dev/null +++ b/docs/plans-executions/2026-08-07-1747-proxy-operator.md @@ -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`.