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:
2026-08-07 20:34:05 +02:00
parent 076bc66ebe
commit a5f0aa95d2
3 changed files with 47 additions and 2 deletions

View File

@@ -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"
]
}
}

View File

@@ -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

View 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`.