Merge remote-tracking branch 'origin/staging' into develop

.agents/README.md

@@ -344,6 +344,39 @@ delegating when it helps), review it when the task is complex
 (`/review-plan`), implement it (`/implement-plan`), and mark progress
 on the roadmap as you land each piece.
 
+### Plan file naming (base + derivatives)
+
+Base plans live in `.agents/plans/` as `YYYY-MM-DD-<slug>.md`.
+Derived plans reuse the parent basename verbatim and append one
+suffix per level with `--`, with no new date — the parent prefix
+keeps everything adjacent in `ls`:
+
+- Review followup on implemented work:
+  `2026-09-14-paste-before-init-crash.md` →
+  `2026-09-14-paste-before-init-crash--review-01.md`
+- Roadmap sub-plan (task number from the roadmap):
+  `2026-09-20-upload-pipeline-roadmap.md` →
+  `2026-09-20-upload-pipeline-roadmap--task-01-chunk-upload.md`
+- Chained: `...--task-02-gc--review-01.md`
+
+While a plan is still unimplemented, `/make-a-plan` revises it in
+place. Once implemented and reviewed, it writes a new followup file.
+Full rules live in the `planner` skill.
+
+### Plan status lifecycle
+
+Every plan carries `Status: draft | reviewed | done` plus an
+append-only `Review Log` (UTC ISO 8601, one line per entry):
+
+- `draft` — fresh from `/make-a-plan`.
+- `reviewed` — review feedback incorporated. `/review-plan` stays
+  read-only; only your explicit "apply" makes `/make-a-plan` apply
+  the changes, flip the status, and log one line.
+- `done` — `/implement-plan` closes it on completion, logging the
+  issue URL when one exists (never commit hashes).
+
+A plan approved with no changes goes `draft` → `done` directly.
+
 ## 7. Connecting `gh` CLI with a token
 
 The `create-issue` and `create-pr` flows need an authenticated `gh`

.agents/skills/implement-plan/SKILL.md

@@ -102,8 +102,14 @@ Implement every task in one go. Work methodically, keeping changes
 focused on what the issue requires. Respect the plan's proposed
 parallelization when it applies.
 
-When the implementation is complete, load the **`create-commit`** skill
-and follow its workflow to commit the changes. Provide a brief summary
+When the implementation is complete, close the plan file first: flip its
+`Status` to `done` and append one UTC ISO 8601 line to its `Review Log`
+with the issue URL when one exists (standalone mode, e.g.
+`https://github.com/penpot/penpot/issues/NNNN`); in continue/direct
+mode with no issue, just `done` with no invented identifier. Never
+record commit hashes. Then load the **`create-commit`** skill
+and follow its workflow to commit the changes together with the
+closed plan file, so plan and code land in the same commit. Provide a brief summary
 of what was implemented and why, the issue reference (`issue-NNNN`) when
 there is one, and the model name you are running as so the
 `AI-assisted-by` trailer is set correctly.
@@ -117,6 +123,9 @@ per task" — loop one task at a time:
 - Commit it now: load the **`create-commit`** skill and follow it —
   one commit per task, never two tasks in one commit. Same inputs as
   always: what and why, the issue reference, your model name.
+- After the final task, close the plan file (`Status: done`, one
+  `Review Log` line with the issue URL when one exists) and include
+  it in that last commit.
 - Show the user the result (what changed, files touched, how it was
   verified).
 - WAIT for the user's confirmation before starting the next task.

.agents/skills/make-a-plan/SKILL.md

@@ -16,8 +16,18 @@ stop — this skill needs the build agent to save the plan.
 - The user asks to plan, design, or break down a task, in any phrasing:
   "make a plan", "how would we build X", "design an approach for Y" —
   or runs `/make-a-plan`.
-- The user asks to rework or extend an existing plan (for example, after
-  review findings) — revise the saved plan file in place.
+- The user asks to rework or extend an existing plan. While the plan is
+  still unimplemented (pre-`implement-plan` iteration, e.g. after
+  `/review-plan` findings or user feedback), revise the saved plan file
+  in place. Once the plan has been implemented and reviewed (post
+  `/review-code` findings on committed work), write a new derived plan
+  file instead — never rewrite the executed plan. The `planner` skill
+  defines the derived naming (`--review-NN`, `--task-NN`).
+- The user says to apply `review-plan` findings to a still-unimplemented
+  plan: apply the agreed changes, flip `Status` to `reviewed`, and
+  append one UTC ISO 8601 line to `Review Log` describing what changed.
+  This apply step is the only pre-implementation write to those fields —
+  `review-plan` itself stays read-only and never writes.
 
 Do not use it to execute a plan — that is the `implement-plan` flow.
 
@@ -34,8 +44,12 @@ Do not use it to execute a plan — that is the `implement-plan` flow.
 3. Once all decisions are answered and the plan is final, save it verbatim to the
    announced path under `.agents/plans/` (create the directory if it does not
    exist). This step is the flow's explicit authorization to write the plan
-   file — the only write allowed here. If I later ask for changes, update the
-   saved file directly.
+   file — the only write allowed here. A fresh plan uses
+   `.agents/plans/YYYY-MM-DD-<slug>.md` with `Status: draft` and an
+   empty `Review Log`; a derived plan uses the parent
+   basename plus the `planner` suffix (`--review-NN`, `--task-NN`) in its
+   own new file, also starting as `draft`. If I later ask for changes to a still-unimplemented plan,
+   update the saved file directly.
 4. Present me with a clear, self-contained summary of the plan's most relevant points
    only after all required decisions have been answered. Write it for someone who knows
    only the project's high-level goal and may not know the plan's low-level context.

.agents/skills/planner/SKILL.md

@@ -70,7 +70,7 @@ Skipping this step is the #1 cause of incorrect or incomplete plans.
 Each task follows this structure:
 
 ```markdown
-## Task [N]: [Short descriptive title]
+### Task [N]: [Short descriptive title]
 
 **Description:** One or two paragraphs explaining what this task accomplishes.
 Should be clear and concise.
@@ -153,6 +153,45 @@ Announce the save path `.agents/plans/YYYY-MM-DD-<slug>.md` (today's date,
 lowercase hyphen-separated slug, e.g. `2026-09-10-add-batch-get-profiles`;
 an explicit user path wins).
 
+### Derived plans
+
+Never invent a fresh slug when the plan derives from an existing one.
+The derived name is `<parent-basename>` plus one suffix per level,
+joined with `--` (double hyphen; single hyphens already separate
+slug words, so `--` marks where the derivation starts). The parent
+name is never edited, and no new date is added — the parent prefix
+already carries its date, which keeps parent and derivatives adjacent
+in `ls`. Record the real creation date inside the plan (`Created:`).
+
+Valid names match:
+
+```
+^\d{4}-\d{2}-\d{2}-[a-z0-9-]+(--(review-\d{2}|task-\d{2})(-[a-z0-9-]+)?)*\.md$
+```
+
+- `review-NN` — a new plan addressing findings of a `review-code` or
+  `review-plan` on already-implemented work. `NN` counts reviews of
+  that parent from `01`. Example: parent
+  `2026-09-14-paste-before-init-crash.md` →
+  `2026-09-14-paste-before-init-crash--review-01.md`,
+  then `--review-02.md`.
+- `task-NN-<short-slug>` — sub-plan for task `NN` of a high-level
+  roadmap plan. `NN` is the roadmap task number. Example: parent
+  `2026-09-20-upload-pipeline-roadmap.md` →
+  `2026-09-20-upload-pipeline-roadmap--task-01-chunk-upload.md`.
+  Levels chain: `...--task-02-gc--review-01.md`.
+
+Never use `v2`, `final`, `new`, or `fix2` as suffixes. Keep the
+optional short slug to 3-4 lowercase hyphen-separated words.
+
+Every derived plan opens its `Context` with:
+
+```markdown
+Parent: `<parent-basename>.md`
+Source: review-code over `<commit>` (branch `<branch>`) | task `NN` of roadmap `<parent-basename>.md`
+Created: YYYY-MM-DD
+```
+
 End the response by suggesting the next steps: `/review-plan` to get a second
 opinion on the plan and `/implement-plan` to execute it.
 
@@ -163,6 +202,10 @@ Use this document shape:
 ```markdown
 # Plan: Title
 
+Status: draft | reviewed | done
+Review Log:
+- YYYY-MM-DDTHH:MM:SSZ — <what changed and why, one line per entry>
+
 ## Context
 ## Affected Modules
 ## Architecture Decisions
@@ -174,6 +217,23 @@ Use this document shape:
 ## Open Questions
 ```
 
+`Status` and `Review Log` are write-restricted metadata, not free text:
+
+- `make-a-plan` creates every plan with `Status: draft` and an empty
+  log. `reviewed` never means "a review was emitted" — it means
+  "review feedback was incorporated". A plan approved with no changes
+  goes `draft` → `done` without passing through `reviewed`.
+- Only a user-triggered apply step writes them before implementation:
+  when the user says to apply `review-plan` findings, `make-a-plan`
+  applies the changes, flips to `reviewed`, and appends one UTC
+  ISO 8601 line describing what changed.
+- `implement-plan` flips to `done` on completion and appends one line
+  with the issue URL when one exists (standalone mode); otherwise
+  just `done`. Never record commit hashes — they rot on amend/rebase
+  and git already links the commit.
+- The log is append-only: never rewrite or delete lines.
+- `review-plan` and `review-code` never write these fields.
+
 Omit empty sections only when they do not apply. Every implementation task
 still requires acceptance criteria, verification, dependencies, likely files,
 and scope.