v3.2.0 — add execute-plan, closing the scaffold → plan → build chain

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "code-idea",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Turn a plan or idea into an AI-coding-agent-ready docs set, then plan and build the modules it defines.",
   "author": { "name": "Melconcoast Inc" },
   "homepage": "https://github.com/melconcoast/code-idea#readme",

AGENTS.md

@@ -1,6 +1,6 @@
 # code-idea
 
-"Code this idea" — a Claude Code plugin that turns a plan into an AI-coding-agent-ready docs set, then plans and builds the modules it defines. There's no application code, only markdown. Two skills exist today, and they run in sequence: `scaffold` (`skills/scaffold/SKILL.md`) writes the docs set including `docs/development-roadmap.md`, and `plan-module` (`skills/plan-module/SKILL.md`) turns one module of that roadmap into `docs/guides/feature_<module>_plan.md`. One more is planned and deliberately unbuilt — `execute-plan` — and it ships no directory until it is written.
+"Code this idea" — a Claude Code plugin that turns a plan into an AI-coding-agent-ready docs set, then plans and builds the modules it defines. There's no application code in this repo, only markdown. Three skills run in sequence: `scaffold` (`skills/scaffold/SKILL.md`) writes the docs set including `docs/development-roadmap.md`; `plan-module` (`skills/plan-module/SKILL.md`) turns one module of that roadmap into `docs/guides/feature_<module>_plan.md`; and `execute-plan` (`skills/execute-plan/SKILL.md`) builds that plan file task by task, writing real code and tests into the user's project. The chain is complete — no skill name is reserved-but-unbuilt any more.
 
 ## Critical rules (read first)
 - **Confirmation must be explicit, never assumed from silence.** A fact that appears in a planning conversation because the assistant proposed it, or because it showed up in a prototype/demo (especially one shaped by the demo environment's own constraints), is NOT the same as something the user explicitly stated or confirmed. Step 2 of `skills/scaffold/SKILL.md` must apply the recommend-and-confirm pattern to both cases the same way — don't let "it's already in the conversation" substitute for a real confirmation.
@@ -10,11 +10,14 @@
 - **`skills/scaffold/references/recommendation-heuristics.md` is expected to age.** Verify a specific tool/version recommendation against a current search before trusting it, and treat outdated entries there as a normal, welcome PR rather than a bug.
 - **The container is per-agent; the content is not.** Which files the skill generates depends on the target agent (Claude Code reads `CLAUDE.md` and never `AGENTS.md`; Codex and Antigravity read `AGENTS.md` natively). What those files *say* is identical in every mode. When changing a `SKILL.md`, check you haven't let a layout assumption leak into content guidance or vice versa — `examples/test-scenarios.md` S12 is the check for this.
 - **The version lives in two places — the git tag and `.claude-plugin/plugin.json`.** Bump both together; CI blocks a tag whose `plugin.json` version doesn't match. `.claude-plugin/marketplace.json` deliberately carries no version, so the plugin's own manifest stays the single answer to "what version is this?" — don't add one there.
-- **A skill directory without a `SKILL.md` is not a placeholder for a future skill.** Git can't track an empty directory, and a `.gitkeep` stub registers a broken skill for every user. Reserve an unbuilt skill's name in `README.md` and `CHANGELOG.md`; create the directory when you write it.
+- **A skill directory without a `SKILL.md` is not a placeholder for a future skill.** Git can't track an empty directory, and a `.gitkeep` stub registers a broken skill for every user. Reserve a future skill's name in `README.md` and `CHANGELOG.md`; create the directory when you write it.
 - **`scaffold` stops at sub-modules.** `docs/development-roadmap.md` records modules and sub-modules only — never task tables. Task detail is `plan-module`'s output, and inventing it at scaffold time means guessing implementation detail nobody has decided. `examples/test-scenarios.md` S37 is the check.
 - **The roadmap is the contract between the two skills, and `scaffold` owns it.** The `Status` vocabulary, the `Depends on:` rules, and the `Tasks:` field are specified once, in `skills/scaffold/references/templates.md`. `plan-module` reads that spec and must never restate it — changing the format in one skill without the other silently breaks the handoff, and nothing errors when it does. `examples/test-scenarios.md` S45 is the check.
 - **`plan-module` never overwrites a plan in flight.** A re-plan preserves every `[x]`, `[~]`, and `[-]` item with its annotation, plus the whole `## Progress Log`. A re-cut task becomes `[~]` with a reason; it never reverts to `[ ]`, which would silently un-do finished work. S48 is the check.
 - **No implementation or test code in a plan file.** *Details* names endpoints, tables, and data shapes; scenarios describe observable behavior in plain English. Writing the code or the assertions decides at plan time what `execute-plan` exists to decide. S47 is the check.
+- **Three skills write to the docs set, and their fields are disjoint.** `scaffold` owns the roadmap's *format*, `plan-module` owns each sub-module's `**Tasks:**` pointer, and `execute-plan` owns `Status:` write-back as phases close. Nothing else updates a roadmap status, so an `execute-plan` that skips it sends the next `plan-module` run at a module that is already built. Never let one skill start writing another's field. S67 is the check.
+- **`skills/execute-plan/references/progress-updates.md` is subordinate to the two specs it applies.** The checkbox vocabulary and counting rules live in `plan-module`'s `plan-template.md`; the roadmap `Status` vocabulary lives in `scaffold`'s `templates.md`. That file says only how to *apply* them during execution and must never become a third source of truth — if it disagrees with either, it is the bug. S66 is the check.
+- **`[x]` means verified, never merely written.** `execute-plan` may not close an item on inspection, on intent, or on a passing type-check — a test covering that scenario has to have actually run and been read. Behavior that genuinely can't be checked in the environment is `[~]` with what would verify it, never `[x]` on faith. S68 is the check.
 - **A deferred decision is not a placeholder.** "Undecided as of [date], do X meanwhile" is required output when the user defers; `[Project name]` and `TODO` are not. Don't let the no-placeholder rule suppress the pending-decision feature.
 
 ## Commands
@@ -33,4 +36,6 @@
 - `skills/scaffold/references/agent-profiles.md` — per-agent container facts, with sources and dates; expected to age
 - `skills/plan-module/references/plan-template.md` — the plan file's format, checkbox vocabulary, and counting rules
 - `skills/plan-module/references/scenario-writing.md` — what makes a plain-English test scenario checkable
+- `skills/execute-plan/references/verification.md` — finding or bootstrapping a test runner, and what counts as verified
+- `skills/execute-plan/references/progress-updates.md` — the plan-file and roadmap writes execution makes
 - `examples/test-scenarios.md` — the scenarios a change must be checked against

CHANGELOG.md

@@ -1,5 +1,75 @@
 # Changelog
 
+## [3.2.0] — 2026-08-22
+
+Adds the plugin's third and final skill, `execute-plan`, and with it the chain closes: `scaffold`
+writes the docs set, `plan-module` cuts a module into a plan file, and `execute-plan` builds that plan
+file into working, tested code. No skill name is reserved-but-unbuilt any more.
+
+Additive for anyone already on 3.1.0 — nothing `scaffold` or `plan-module` generates changes shape,
+and an existing plan file is exactly what the new skill expects to find.
+
+### Added
+- **`execute-plan`** (`skills/execute-plan/SKILL.md`) — works a plan file in a strict **micro-loop**:
+  select the first open task, implement only what its *Details* names, write the test code its
+  plain-English scenarios describe, run it until green, then update the plan file — before looking at
+  the next task. Never a whole phase in one pass. At each `Task X.V` gate it runs the *whole* module's
+  suite rather than just that phase's tests, closes the phase, and **stops to ask** before continuing.
+  Invoked as `/code-idea:execute-plan`, or triggered by "execute the plan", "build task 2.1",
+  "start phase 2", "continue building this module", "implement the next task".
+- **Test-runner bootstrap.** In this chain a project starts with no code, so the first module usually
+  has nothing to run and `scaffold` has left `## Commands` reading "not yet established". `execute-plan`
+  sets up the runner that fits the stack the project's docs already chose — never introducing a
+  language or framework those docs didn't pick — and writes the real commands back into the root
+  context file. That closes a loop `scaffold` could not close on its own.
+- **Roadmap status write-back.** Sub-modules move to `in progress` as their phase starts and `done` as
+  it closes; the module becomes `done` once every phase is. Phases match sub-modules through the
+  `**Tasks:**` pointer `plan-module` wrote. Nothing else updated these statuses, so before this a
+  finished module still read `planned` and the next `plan-module` run would be pointed at work that
+  was already built.
+- `skills/execute-plan/references/verification.md` — where to look for a test runner, how to bootstrap
+  one without adding tooling nobody asked for, what counts as green, and what to do with a scenario
+  that is wrong or that can't be checked in the environment at hand.
+- `skills/execute-plan/references/progress-updates.md` — every write execution makes to a plan file or
+  the roadmap. **Deliberately subordinate**: it applies the vocabularies specified in `plan-module`'s
+  `plan-template.md` and `scaffold`'s `templates.md` and never restates them, so the plugin keeps one
+  source of truth per contract rather than three.
+- **A stop-and-report rule for a plan that disagrees with the repository** — a task marked closed whose
+  code isn't there, a `## Files Modified` path that doesn't exist. `execute-plan` neither builds on the
+  false closure nor quietly repairs it: reopening a phase the file calls done is the user's decision,
+  and rewriting the record to match reality would erase the evidence that it was wrong.
+- `examples/test-scenarios.md` — Fixture G (a plan file in a repo that has code and a working runner)
+  and S65–S84, covering the micro-loop, phase-dependency enforcement, runner bootstrap, reframe-not-
+  delete, scope containment, the gate-and-stop, resume-don't-restart, roadmap write-back, the
+  verified-not-written rule, bare status values, and the three-way trigger boundary.
+
+### Changed
+- **`[x]` is now enforced as *verified*, not *written*.** The distinction was always in
+  `plan-template.md`; `execute-plan` is what acts on it. A task whose code exists but whose tests never
+  ran stays `[ ]`, and behavior that genuinely can't be checked here becomes `[~]` with what would
+  verify it — never `[x]` on faith.
+- **Status values are bare, and both vocabularies now say so.** `scaffold`'s `templates.md` already
+  called the roadmap `Status` a closed vocabulary, but not that the value is the word *alone* — so
+  `done (server-side only — see Sub-Module 2.2)` looked permissible while breaking the same parse a
+  new status word would. Both `templates.md` and `plan-template.md` now state it, and a caveat worth
+  recording goes in the Progress Log instead. Caught by running S67 against the real skill.
+- `skills/plan-module/references/plan-template.md` now specifies a **phase's** `Status:` line, not just
+  the header's. It reads `[ ] Open` while anything in the phase is open and `[x] Done` once every item
+  including the `X.V` gate is closed. Only the open form was written down before, so the closed form
+  was being improvised.
+- `examples/test-scenarios.md` — S43 and S64 changed meaning. Both previously accepted silence or a
+  hand-off *naming* `execute-plan`, because it didn't exist; now the sibling skill is expected to fire.
+- `examples/sample-output/docs/development-roadmap.md` — Sub-Module 3.1 corrected to `done`. The sample
+  plan file closes Phase 1, so under the new write-back rule its sub-module can't still read
+  `in progress`. The sample was internally inconsistent before there was a rule to catch it.
+- `README.md`, `AGENTS.md`, and `CONTRIBUTING.md` updated for a three-skill plugin.
+
+### Upgrading
+Nothing to do. `execute-plan` appears once the plugin updates. Existing plan files work unchanged —
+it reads the format `plan-module` has always written. If you have a roadmap whose statuses drifted
+while there was no skill maintaining them, the first `execute-plan` pass over a module will bring that
+module's own entries back in line; it won't touch any other module's.
+
 ## [3.1.0] — 2026-08-22
 
 Adds the plugin's second skill, `plan-module`. `scaffold` has always written a

CONTRIBUTING.md

@@ -5,9 +5,10 @@ Thanks for considering a contribution. This plugin is small on purpose — most
 ## Where things live
 
 The repo is a Claude Code plugin. Each skill owns a directory under `skills/`, holding its own
-`SKILL.md` and its own `references/`. Two skills exist today — `scaffold` and `plan-module`. One more
-is planned and deliberately unbuilt, `execute-plan`; it gets no directory until it is written, because
-git can't track an empty directory and a stub `SKILL.md` registers a broken skill for everyone.
+`SKILL.md` and its own `references/`. Three skills ship — `scaffold`, `plan-module`, and
+`execute-plan` — and they run in that order. No skill name is reserved-but-unbuilt any more; if you
+propose a fourth, it gets no directory until it is written, because git can't track an empty directory
+and a stub `SKILL.md` registers a broken skill for everyone.
 
 - **`.claude-plugin/plugin.json`** and **`marketplace.json`** — the plugin manifest, and the entry that makes this repo its own marketplace (named `melconcoast`, after the owner, so installs read `code-idea@melconcoast`). The version lives in `plugin.json` only and must match the release tag; CI enforces it.
 - **`skills/scaffold/SKILL.md`** — the workflow itself: when the skill triggers, how the interview works, how structure is decided, how content gets drafted and written. Changes here affect behavior directly, so keep edits scoped and explain the reasoning in the PR description.
@@ -16,8 +17,11 @@ git can't track an empty directory and a stub `SKILL.md` registers a broken skil
 - **`skills/scaffold/references/agent-profiles.md`** — what each coding agent reads and how it loads it. **This file is expected to age**, like the heuristics file, and every claim carries a source URL and verified-on date. A stale entry is a welcome PR. Never add a row you can't cite from that agent's own docs.
 - **`skills/scaffold/references/templates.md`** — the skeleton structure for each generated doc type. The `docs/development-roadmap.md` section here is the contract `plan-module` reads; a change to that block is a change to both skills.
 - **`skills/plan-module/SKILL.md`** — how a roadmap module is located, cut into phases, and written out as a plan file. It reads the roadmap contract rather than restating it, so a scope or vocabulary change belongs in `scaffold`'s `templates.md` first.
-- **`skills/plan-module/references/plan-template.md`** — the plan file's exact format, its four-state checkbox vocabulary, and how progress is counted. `execute-plan` will parse this, so treat the headings and glyphs as a contract, not styling.
+- **`skills/plan-module/references/plan-template.md`** — the plan file's exact format, its four-state checkbox vocabulary, and how progress is counted. `execute-plan` parses this, so treat the headings and glyphs as a contract, not styling.
 - **`skills/plan-module/references/scenario-writing.md`** — what makes a plain-English test scenario checkable, with weak/strong pairs. New guidance on scenario quality belongs here, not in the SKILL.md.
+- **`skills/execute-plan/SKILL.md`** — the micro-loop: how one task is selected, implemented, verified, and written back. It reads the plan file `plan-module` produced rather than restating that file's format, so a vocabulary or counting change belongs in `plan-module`'s `plan-template.md` first.
+- **`skills/execute-plan/references/verification.md`** — finding or bootstrapping a test runner, what counts as green, and what to do with a scenario that's wrong or can't be checked. Guidance on proving a task is done belongs here, not in the SKILL.md.
+- **`skills/execute-plan/references/progress-updates.md`** — every write execution makes to a plan file or the roadmap. **This file is deliberately subordinate**: the checkbox vocabulary and counting rules are specified in `plan-module`'s `plan-template.md`, and the roadmap `Status` vocabulary in `scaffold`'s `templates.md`. It may say how to apply them and nothing more — if it ever disagrees with either, it's the file that's wrong.
 - **`examples/`** — shared across every skill in the plugin, which is why it stays at the repo root rather than moving under `skills/scaffold/`.
 
 ## Reporting an outdated recommendation