@zalom/plastic 1.0.0-beta.8 → 1.0.0

package/skills/roadmap/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: plastic-roadmap
+description: Use when the user wants to plan a delivery batch, order waves of intents, ship a batch of tickets in one go, track a named collection of intents toward a goal, or asks for a "roadmap". Creates and maintains a roadmap file, a delivery-side collection of intents (the counterpart to a release), separate from INDEX.md status tracking.
+---
+
+# Roadmap
+
+A roadmap is a named, ordered, delivery-side collection of intents: the delivery-side counterpart
+to a release (completion-side, `CHANGELOG.md`). It lives at `roadmaps/{slug}.md`, a sibling of
+`INDEX.md` wherever `INDEX.md` lives: the global tier's `~/.plastic/roadmaps/` (beside
+`~/.plastic/INDEX.md`), or a project's root, `~/.plastic/projects/{slug}/roadmaps/` (beside that
+project's `INDEX.md` and `project.yml`). It never sits inside `store/`, which holds intent
+directories, not project artifacts.
+
+A roadmap file has four parts: a title/meta header, `## Goal` (prose), `## Waves` (ordered; entries
+inside a wave are parallel-safe, waves run sequentially), and an append-only dated `## Log`. Each
+wave entry mirrors that intent's status in `INDEX.md` (`queued`/`delivering`/`delivered`/
+`abandoned`/`blocked`).
+
+**`INDEX.md` is the single writer of intent status; on any conflict INDEX wins and the roadmap
+entry is corrected to match.**
+
+The skill operates on the file directly via Read/Edit; no helper script.
+
+## Verbs
+
+| Verb | When | Mechanics |
+|------|------|-----------|
+| Create | user wants to start a new roadmap / plan a delivery batch | `references/operations.md#create` |
+| Add / reorder entries | user wants to add intents to a wave or resequence waves | `references/operations.md#add--reorder-entries` |
+| Sync status mirror | an entry's status may be stale against INDEX | `references/operations.md#sync-status-mirror` |
+| Append log line | a roadmap event just happened (created, wave done, closed) | `references/operations.md#append-a-log-line` |
+| Read / consume | a human or a coordinator needs the roadmap's current state | `references/operations.md#read--consume` |
+| Close / archive | the roadmap's `## Goal` is reached | `references/operations.md#close--archive` |
+
+See `references/file-format.md` for the exact entry-line shape, status vocabulary, checkbox/log
+format, and a worked example. See `references/operations.md` for step-by-step mechanics of each
+verb above.
+
+## Notes
+
+- File location and the four-section shape are identical across tiers; do not invent a different
+  layout per project. The general rule: `roadmaps/` is a sibling of `INDEX.md`, wherever `INDEX.md`
+  lives.
+- `## Goal` is a checkable prose condition read by a human or agent, not an executable checker.
+- Wave entries render as checkboxes (`- [x] ... — delivered` / `- [ ] ... — <status>`); a human
+  reading cold should see shipped/running/next within a minute. `## Log` lines are one-sentence,
+  EM-to-CTO-voice, dated, and link each entry-intent's `outcome.md` (lossless-by-reference).
+- Additive: this skill introduces no gate, lock, or hook, and does not change `INDEX.md`'s section
+  list or the intent frontmatter schema.
+- Closing a roadmap moves it to `roadmaps/archived/{slug}.md` so `roadmaps/` lists only live ones.

package/skills/roadmap/references/file-format.md

@@ -0,0 +1,91 @@
+# Roadmap File Format
+
+## Location
+
+`roadmaps/{slug}.md`, a sibling of `INDEX.md`, wherever `INDEX.md` lives. For the global tier
+that is `~/.plastic/roadmaps/{slug}.md` (beside `~/.plastic/INDEX.md`); for any project it is
+that project's root, `~/.plastic/projects/{slug}/roadmaps/{slug}.md` (beside that project's
+`INDEX.md` and `project.yml`). `roadmaps/` never sits inside `store/`: `store/` holds intent
+directories, not project artifacts. Create the `roadmaps/` directory the first time a tier gets a
+roadmap.
+
+`roadmaps/` lists only live (open or in-flight) roadmaps. Once a roadmap's `## Goal` is reached,
+its file moves to `roadmaps/archived/{slug}.md` (see Close/archive in `operations.md`); the
+`archived/` subdirectory is scaffolded once, alongside `roadmaps/`, with a `.gitkeep`.
+
+## The four sections (in order)
+
+1. **Title/meta header** — `# Roadmap: <name>` plus a one-line meta sentence naming what the
+   roadmap delivers and which tier (project or global) it lives in.
+2. **`## Goal`** — a checkable prose condition: one or a few sentences a human or coordinator reads
+   to decide the roadmap is done. Not an executable checker, not a list of tasks.
+3. **`## Waves`** — ordered waves (`### Wave 1`, `### Wave 2`, ...). Entries inside a wave are
+   parallel-safe (can be dispatched together); waves run top to bottom, sequentially (wave 2 does
+   not start until wave 1's entries are no longer `queued`/`delivering`).
+4. **`## Log`** — append-only, dated, one line per event. Newest entry at the bottom. Never edit or
+   remove an existing log line.
+
+## Entry line shape
+
+One line per intent, inside its wave, as a Markdown checkbox:
+
+```
+- [x] <intent-id> <title> — delivered
+- [ ] <intent-id> <title> — <status>
+```
+
+`<intent-id>` and `<title>` match the intent's `INDEX.md` entry (terse, not a summary). The
+checkbox is checked (`[x]`) once `<status>` is `delivered`, unchecked (`[ ]`) for every other
+status. The checkbox is a rendering of the mirrored status token, not a second piece of state: a
+human scanning the file sees at a glance what shipped (checked) and what has not (unchecked),
+while the trailing token still carries the precise state (`queued`/`delivering`/`blocked`/
+`abandoned`) when unchecked.
+
+## Status vocabulary
+
+`queued` | `delivering` | `delivered` | `abandoned` | `blocked`
+
+Status is a **mirror** of `INDEX.md`. `INDEX.md` is the single writer of intent status; on any
+conflict INDEX wins and the roadmap entry (both its token and its checkbox) is corrected to match
+it. The roadmap never sets a status that INDEX does not already reflect.
+
+## Log line shape
+
+One line per event, starting `YYYY-MM-DD HH:MM UTC` (human-readable, sortable, zone-explicit so
+same-day parallel deliveries can still be ordered), in plain-language EM-to-CTO voice: what shipped
+and why it matters to a non-expert reader, no jargon or internal codenames, ending with a link to
+that entry-intent's `outcome.md`:
+
+```
+- <YYYY-MM-DD HH:MM UTC> <one plain-language sentence: what shipped, its impact> — see store/<id>--<slug>/outcome.md
+```
+
+The log line never restates `outcome.md` detail; it points at it (lossless-by-reference). This
+complements, and does not replace, `INDEX.md`'s `## Completed` section or `CHANGELOG.md`.
+
+## Worked example
+
+```
+# Roadmap: Stable 1.0
+
+Delivery-side collection of intents that close out the pre-1.0 hardening pass, plastic project store.
+
+## Goal
+All intents below are delivered, the suite is green, and a 1.0.0 release is cut.
+
+## Waves
+Entries in a wave are parallel-safe; waves run top to bottom. The checkbox tracks delivered/not;
+the token after the em-dash carries the precise mirrored status (queued | delivering | delivered |
+abandoned | blocked); INDEX wins on any conflict.
+
+### Wave 1
+- [x] 121 Fix bash gate redirect parsing — delivered
+- [ ] 130 Proportional cycle tiers — delivering
+
+### Wave 2
+- [x] 124 Roadmap feature — delivered
+
+## Log
+- 2026-07-06 14:32 UTC Shipped the bash-gate redirect fix so quoted arrows and heredoc trailers
+  stop blocking legitimate commits — see store/121--fix-bash-gate-redirect-parsing/outcome.md.
+```

package/skills/roadmap/references/operations.md

@@ -0,0 +1,78 @@
+# Roadmap Operations
+
+All six verbs operate on the Markdown file directly (Read/Edit). No helper script exists or is
+needed; the file is small and the edits are mechanical.
+
+**Human-comprehension goal.** Every operation below should leave the file such that a cold reader
+(no INDEX.md, no intent directories open) can answer "what's shipped, what's running, what's
+next" in under a minute, just from this one file.
+
+## Create
+
+1. Pick a `slug` (kebab-case, descriptive) and a `title`.
+2. Resolve the tier root: the directory that holds `INDEX.md` (a project's root, beside
+   `project.yml`, or `~/.plastic/` for the global tier). `roadmaps/` is always a sibling of
+   `INDEX.md`, never inside `store/`. Create `roadmaps/` there if it does not exist yet.
+3. Copy `templates/roadmap.md` to `roadmaps/{slug}.md`.
+4. Fill the header (`# Roadmap: <title>` + the one-line meta) and write a real `## Goal` prose
+   condition.
+5. Add at least one `## Waves` wave with real entries (see Add / reorder below), each entry's
+   status mirroring that intent's current `INDEX.md` status.
+6. Append the first `## Log` line, a short `YYYY-MM-DD HH:MM UTC`-prefixed plain-language note
+   that the roadmap was created.
+
+## Add / reorder entries
+
+- **Add**: append an entry line (`- <intent-id> <title> — <status>`) to the target wave. Pick the
+  intent's title and status straight from `INDEX.md`.
+- **New wave**: add a new `### Wave N` heading after the last wave; entries in it are gated behind
+  every earlier wave's entries leaving `queued`/`delivering`.
+- **Reorder**: move an entry line to a different wave, or move a `### Wave` heading (with its
+  entries) earlier or later. Reordering never changes an entry's status; it only changes when the
+  entry is eligible to run.
+- After any add/reorder, append a `## Log` line describing the change (e.g.
+  `- <YYYY-MM-DD HH:MM UTC> added 132 to wave 2`).
+
+## Sync status mirror
+
+1. Read the intent's real status from `INDEX.md` (`## Active`, `## Future`, `## Completed`, or
+   `## Abandoned`).
+2. Compare to the roadmap entry's `<status>` token.
+3. If they differ, **INDEX wins**: rewrite the roadmap entry's status token to match INDEX, and
+   flip its checkbox in the same edit (`[x]` when the new status is `delivered`, `[ ]` otherwise).
+   Never edit INDEX.md from the roadmap skill; the roadmap is a mirror, not a second writer.
+4. Append a `## Log` line recording the change. When the new status is `delivered`, write the
+   one-line EM-to-CTO entry described in `file-format.md` (date, what shipped and its impact in
+   plain language, then a link to that intent's `outcome.md`). For other transitions, write a
+   short dated plain-language line (no codenames, no jargon).
+
+## Append a log line
+
+- One line per event, starting `YYYY-MM-DD HH:MM UTC`, appended at the bottom of `## Log`. Never
+  edit or delete an existing line (append-only).
+- Every line is plain language a non-expert can read, never a codename or a raw `field -> value`.
+  A delivery event follows the EM-to-CTO one-line shape with an `outcome.md` link (see
+  `file-format.md`); bookkeeping events (created, an intent added to a wave, a wave completed, a
+  roadmap closed) are short dated plain-language lines.
+
+## Read / consume
+
+- A human reading the file gets the current picture directly: `## Goal` for the target, `## Waves`
+  for what is queued/delivering/delivered per wave (checkboxes give the shipped/not-shipped view at
+  a glance), `## Log` for a one-line, plain-language history with a link into each intent's
+  `outcome.md` for detail.
+- A future coordinator (for example, an auto-mode dispatcher) reads `## Waves` top to bottom:
+  a wave is eligible to dispatch once every entry in the previous wave is no longer
+  `queued`/`delivering`; within an eligible wave, entries still `queued` are parallel-dispatchable.
+  Always re-sync against `INDEX.md` before dispatch decisions, since INDEX is the source of truth.
+
+## Close / archive
+
+1. Confirm the roadmap's `## Goal` prose condition is met (every entry `delivered` or explicitly
+   `abandoned` with a recorded reason, plus whatever else the goal states).
+2. Create `roadmaps/archived/` beside `roadmaps/` (both siblings of `INDEX.md`) if it does not
+   exist yet.
+3. Move the file: `roadmaps/{slug}.md` -> `roadmaps/archived/{slug}.md`. `roadmaps/` itself then
+   lists only live (open or in-flight) roadmaps.
+4. Append the final `## Log` line before or as part of the move:
+   `- <YYYY-MM-DD HH:MM UTC> roadmap closed`.

package/skills/uninstall/SKILL.md

@@ -9,15 +9,21 @@ The installer tracks every file it writes in a manifest, so uninstall is exact a
 leaves no orphans. Prefer running it through the CLI; this skill wraps the same
 underlying uninstaller and adds reporting + verification.
 
+## Channel rule
+
+If Plastic is installed, derive `<channel>` from `~/.plastic/VERSION`: a version containing
+`-alpha` means `@alpha`, `-beta` means `@beta`, otherwise `@latest`. If not installed,
+default to `@beta`. The user can always override with `--alpha` / `--beta` / `--latest`.
+
 ## Procedure
 
 ### Step 1: Run the uninstaller
 
 ```bash
-npx @zalom/plastic@latest uninstall --claude
+npx -y @zalom/plastic@<channel> uninstall --claude
 ```
 
-(Use `--codex` / `--hermes` / `--all` to target other agents. `bunx` works too.)
+(Use `--codex` / `--hermes` / `--all` to target other agents. `bunx -y @zalom/plastic@<channel> uninstall --claude` works too.)
 
 This removes, for the targeted agent:
 - all `~/.claude/skills/plastic-*/` skills
@@ -29,8 +35,8 @@ This removes, for the targeted agent:
 
 ### Step 2: Report removed vs left
 
-Relay the uninstaller's output to the user — what was **removed** and what was
-**left in place**:
+Relay the uninstaller's output to the user: what was **removed** and what was
+**left in place**.
 - **Left:** `~/.plastic/` (intent store, history, projects) and any non-Plastic
   settings.json entries.
 
@@ -39,21 +45,33 @@ Relay the uninstaller's output to the user — what was **removed** and what was
 Tell the user to confirm:
 
 ```bash
-ls ~/.claude/skills | grep '^plastic-'    # → no output
-ls ~/.claude/hooks  | grep '^plastic-'    # → no output
-grep -n plastic ~/.claude/settings.json   # → no plastic hook/plugin refs
+ls ~/.claude/skills | grep '^plastic-'    # -> no output
+ls ~/.claude/hooks  | grep '^plastic-'    # -> no output
+grep -n plastic ~/.claude/settings.json   # -> no plastic hook/plugin refs
+```
+
+### Step 4: Report + offer the data decision
+
+Emit the reporting block, using the Step 3 checks for the verification line:
+
+```
+Plastic uninstall (<channel>)
+Command:  npx -y @zalom/plastic@<channel> uninstall --claude <flags>
+Version:  removed
+Verification: <Step 3 results, or "clean">
 ```
 
-### Step 4: Offer the data decision
+Then:
 
 ```
 Plastic is uninstalled from [agent].
 Your intent store at ~/.plastic/ is untouched.
 
 Delete it too?
-  a) Keep everything (recommended) — re-install anytime with npx
-  b) Delete everything now — removes ~/.plastic/ entirely (irreversible)
+  a) Keep everything (recommended): re-install anytime with npx
+  b) Delete everything now: removes ~/.plastic/ entirely (irreversible)
 ```
 
-- **Keep:** "Your data is at ~/.plastic/. Re-install anytime with `npx @zalom/plastic@latest install --claude`."
+- **Keep:** "Your data is at ~/.plastic/. Re-install anytime with
+  `npx -y @zalom/plastic@beta install --claude` (or your channel)."
 - **Delete:** run `rm -rf ~/.plastic/` and confirm.

package/skills/update/SKILL.md

@@ -13,58 +13,69 @@ description: Use when updating Plastic. Runs the `update` verb, which reads the
 ## What it does
 
 `update` is a single deterministic command. It reads `~/.plastic/VERSION`, derives the
-channel from the version string (`-alpha`/`-beta`/none → stable), queries `npm` dist-tags,
+channel from the version string (`-alpha`/`-beta`/none -> stable), queries `npm` dist-tags,
 and advances to the **next version on the current channel**. "Already up to date" is a
-clean no-op. You do not compute the target yourself — the script does.
+clean no-op. You do not compute the target yourself, the script does.
+
+## Channel rule
+
+If Plastic is installed, derive `<channel>` from `~/.plastic/VERSION`: a version containing
+`-alpha` means `@alpha`, `-beta` means `@beta`, otherwise `@latest`. If not installed
+(first install), default to `@beta`. The user can always override with
+`--alpha` / `--beta` / `--latest`.
 
 ## Flags
 
 | Flag | Behaviour |
 |------|-----------|
 | (none) | Advance to the next version on the **current** channel |
-| `--latest` | Switch to / advance the **stable** channel (toward stability — frictionless) |
+| `--latest` | Switch to / advance the **stable** channel (toward stability, frictionless) |
 | `--beta` | Switch to / advance the **beta** channel |
-| `--alpha` | Switch to / advance the **alpha** channel (bleeding edge — confirmed if moving down in stability) |
+| `--alpha` | Switch to / advance the **alpha** channel (bleeding edge, confirmed if moving down in stability) |
 
 Switching toward a more stable channel is frictionless; switching toward bleeding edge is
 confirmed. To roll **back** to a previously-installed version, use `plastic-versions`.
 
 ## Prerequisites
 
-Plastic must be installed (`~/.plastic/VERSION` present). If not, run
-`npx @zalom/plastic install --claude` first.
+Plastic must be installed (`~/.plastic/VERSION` present). If not, run `plastic-install`
+first (or `npx -y @zalom/plastic@beta install --claude` directly).
 
 ## Procedure
 
 ### Step 1: Run the update
 
 ```bash
-npx @zalom/plastic update            # next version on the current channel
-# or: npx @zalom/plastic update --beta   /   --latest   /   --alpha
+npx -y @zalom/plastic@<channel> update --claude
+# channel switch: append --beta / --latest / --alpha
+# other agents: append --codex / --hermes / --all
 ```
 
-Append the agent flag(s) if not just Claude (`--codex`, `--hermes`, `--all`).
-The command prints the transition (`vX → vY`) or "already up to date", and records the
-move in the append-only `~/.plastic/versions.json` ledger.
+`bunx -y @zalom/plastic@<channel> update --claude` works as a fallback if `npx` is
+unavailable. The command prints the transition (`vX -> vY`) or "already up to date", runs
+a post-update doctor summary, and records the move in the append-only
+`~/.plastic/versions.json` ledger.
 
-### Step 2: Announce key changes
+### Step 2: Relay the result, announce convention changes
 
-After it completes, read `~/.plastic/PLASTIC.md` and announce convention changes that
-affect the current session:
+Relay what `update` printed, do not recompute the version transition or the doctor
+summary:
 
 ```
-Plastic updated to vX.Y.Z (channel).
-
-Key changes:
-- [notable convention changes, if any]
-
-Recommendation: run /clear for a clean session with all new conventions loaded.
+Plastic update (<channel>)
+Command:  npx -y @zalom/plastic@<channel> update --claude <flags>
+Version:  <before> -> <after>
+Doctor:   <relayed summary, or "all clear">
 ```
 
-### Step 3: Health check
+Then read `~/.plastic/PLASTIC.md` and announce convention changes that affect the
+current session, and recommend `/clear` for a clean session with all new conventions
+loaded.
+
+### Step 3: Health check only on a relayed failure
 
-Invoke `plastic-doctor`. If all checks pass: **"Health check: all clear."** Otherwise show
-the report and offer to fix.
+If the relayed doctor summary shows a failure, invoke `plastic-doctor` for the full
+report and offer to fix. If it already reads clean, do not re-run doctor.
 
 ### Step 4: Commit + clear update cache
 

package/skills/versions/SKILL.md

@@ -3,7 +3,7 @@ name: plastic-versions
 description: Use when the user wants to see their Plastic version history or roll back to a previously-installed version after a bad release. Manages the local, append-only versions.json ledger and steps between versions the user has actually run. For moving to a brand-new release, use plastic-update instead.
 ---
 
-# Plastic Versions — local version time-machine
+# Plastic Versions: local version time-machine
 
 ## When to Use
 - "show plastic versions", "version history", "what versions have I run"
@@ -11,11 +11,18 @@ description: Use when the user wants to see their Plastic version history or rol
 - A new version broke something and the user wants their last known-good build
 
 For upgrading to a **new** release, use `plastic-update`. This skill only navigates
-versions you have **already installed** — the ones recorded in the ledger.
+versions you have **already installed**, the ones recorded in the ledger.
+
+## Channel rule
+
+`versions` restores whichever build you pick from the ledger, it does not take a channel
+flag for the target. The pinned `<channel>` below is only the npx invocation itself:
+derive it from `~/.plastic/VERSION` the same way as the other lifecycle skills,
+`-alpha` -> `@alpha`, `-beta` -> `@beta`, otherwise `@latest`.
 
 ## The ledger
 
-`~/.plastic/versions.json` is an **append-only JSONL** ledger — one line per version
+`~/.plastic/versions.json` is an **append-only JSONL** ledger, one line per version
 change, never modified or deleted:
 
 ```json
@@ -23,15 +30,16 @@ change, never modified or deleted:
 {"version":"1.0.0-alpha.18","action":"update","at":"..."}
 ```
 
-`action` ∈ `install | reinstall | update | downgrade` (derived from version direction; the
-channel is derived from the version string, never stored). It is a troubleshooting record.
+`action` is one of `install`, `reinstall`, `update`, `downgrade` (derived from version
+direction; the channel is derived from the version string, never stored). It is a
+troubleshooting record.
 
 ## Procedure
 
 ### Show history
 
 ```bash
-npx @zalom/plastic versions
+npx -y @zalom/plastic@<channel> versions
 ```
 
 Prints the table with the currently-installed version marked. If the most recent action was
@@ -40,8 +48,8 @@ a `downgrade`, it asks whether to keep rolling back.
 ### Roll back
 
 ```bash
-npx @zalom/plastic versions --downgrade                    # one step back
-npx @zalom/plastic versions --downgrade --version 1.0.0-alpha.15   # to a specific run
+npx -y @zalom/plastic@<channel> versions --downgrade                    # one step back
+npx -y @zalom/plastic@<channel> versions --downgrade --version 1.0.0-alpha.15   # to a specific run
 ```
 
 Rollback targets are restricted to versions in the ledger (only builds you have actually
@@ -51,15 +59,22 @@ re-fetched from npm and re-synced; your intent store, config, and the ledger are
 ### Step forward (after a rollback)
 
 ```bash
-npx @zalom/plastic versions --upgrade                      # one step forward in your history
+npx -y @zalom/plastic@<channel> versions --upgrade                      # one step forward in your history
 ```
 
 ### After any change
 
-Run `plastic-doctor` to confirm health, and suggest `/clear` so the session picks up the
-swapped conventions.
+Run `plastic-doctor` to confirm health, then emit the reporting block and suggest
+`/clear` so the session picks up the swapped conventions:
+
+```
+Plastic versions (<channel>)
+Command:  npx -y @zalom/plastic@<channel> versions <flags>
+Version:  <before> -> <after>
+Doctor:   <summary or "all clear">
+```
 
 ## Notes
-- The ledger is **never** edited or pruned — it is the audit trail.
+- The ledger is **never** edited or pruned, it is the audit trail.
 - Downgrades cannot un-migrate a store-format change; if a warning appears, surface it to
   the user rather than forcing the rollback.

package/skills/writing-plans/SKILL.md

@@ -48,70 +48,13 @@ This structure informs the task decomposition. Each task should produce self-con
 - "Run the tests and make sure they pass" - step
 - "Commit" - step
 
-## Plan Document Header
+## Plan Format
 
-**Every plan MUST start with this header:**
-
-```markdown
-# [Feature Name] Implementation Plan
-
-> **For agentic workers:** Use `plastic-executing-plan` to implement this plan task-by-task.
-
-**Goal:** [One sentence describing what this builds]
-
-**Architecture:** [2-3 sentences about approach]
-
-**Tech Stack:** [Key technologies/libraries]
-
-**Intent:** {id} — {name}
-
----
-```
-
-## Task Structure
-
-````markdown
-### Task N: [Component Name]
-
-**Files:**
-- Create: `exact/path/to/file.rb`
-- Modify: `exact/path/to/existing.rb:123-145`
-- Test: `test/exact/path/to/test.rb`
-
-- [ ] **Step 1: Write the failing test**
-
-```ruby
-def test_specific_behavior
-  result = function(input)
-  assert_equal expected, result
-end
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `ruby -Itest test/path/test.rb --name test_specific_behavior`
-Expected: FAIL with "undefined method"
-
-- [ ] **Step 3: Write minimal implementation**
-
-```ruby
-def function(input)
-  expected
-end
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `ruby -Itest test/path/test.rb --name test_specific_behavior`
-Expected: PASS
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add test/path/test.rb lib/path/file.rb
-git commit -m "feat: add specific feature"
-```
-````
+For the exact plan/task/checklist/action format (the Plan Document Header
+template, the full Task Structure worked example, and the checklist.md /
+actions/ACTION_N.md templates), read `references/plan-format.md` before
+writing plan.md. Every plan starts with the header template and decomposes
+into tasks matching the Task Structure shape.
 
 ## No Placeholders
 
@@ -144,31 +87,10 @@ If you find issues, fix them inline. No need to re-review — just fix and move
 ## Plastic Artifacts
 
 After writing `plan.md`, create two additional artifacts in the intent directory:
-
-### checklist.md
-
-Execution registry with one checkbox per task. Format:
-
-```markdown
-# Checklist — Intent {id}: {name}
-
-- [ ] Task 1: {task title}
-- [ ] Task 2: {task title}
-- [ ] Task 3: {task title}
-...
-```
-
-### actions/ACTION_N.md
-
-One file per task. Each action is self-contained — a subagent can execute it without reading the plan.
-
-```markdown
-# Action {N}: {task title}
-
-{Full task text copied from plan.md — all steps, all code, all commands. Nothing omitted.}
-```
-
-Create the `actions/` directory inside the intent directory: `{intent_dir}/actions/`
+`checklist.md` (execution registry with one checkbox per task) and
+`actions/ACTION_N.md` (one self-contained file per task, in an `actions/`
+directory inside the intent directory). For the exact format of both, read
+`references/plan-format.md`.
 
 ## Git Commit