@zalom/plastic 1.0.0-beta.35 → 1.0.0-beta.37

package/skills/brainstorming/references/design-principles.md

@@ -0,0 +1,49 @@
+# Design Principles: Unit Boundaries and Existing Codebases
+
+General good-developer guidance behind two parts of the Process: how to design for
+isolation and clarity, and how to behave in an existing codebase. Also holds the
+Process Flow diagram (the same ordered flow the Checklist already states as numbered
+steps).
+
+## Design for isolation and clarity
+
+- Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently
+- For each unit, you should be able to answer: what does it do, how do you use it, and what does it depend on?
+- Can someone understand what a unit does without reading its internals? Can you change the internals without breaking consumers? If not, the boundaries need work.
+- Smaller, well-bounded units are also easier for you to work with - you reason better about code you can hold in context at once, and your edits are more reliable when files are focused. When a file grows large, that's often a signal that it's doing too much.
+
+## Working in existing codebases
+
+- Explore the current structure before proposing changes. Follow existing patterns.
+- Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design - the way a good developer improves code they're working in.
+- Don't propose unrelated refactoring. Stay focused on what serves the current goal.
+
+## Process Flow (diagram)
+
+The Checklist above already states this ordered flow as numbered steps 1-8; this
+diagram is the same flow in a visual form.
+
+```dot
+digraph brainstorming {
+    "Explore project context" [shape=box];
+    "Ask clarifying questions" [shape=box];
+    "Propose 2-3 approaches" [shape=box];
+    "Present design sections" [shape=box];
+    "User approves design?" [shape=diamond];
+    "Write spec" [shape=box];
+    "Spec self-review\n(fix inline)" [shape=box];
+    "User reviews spec?" [shape=diamond];
+    "Invoke plastic-writing-plans" [shape=doublecircle];
+
+    "Explore project context" -> "Ask clarifying questions";
+    "Ask clarifying questions" -> "Propose 2-3 approaches";
+    "Propose 2-3 approaches" -> "Present design sections";
+    "Present design sections" -> "User approves design?";
+    "User approves design?" -> "Present design sections" [label="no, revise"];
+    "User approves design?" -> "Write spec" [label="yes"];
+    "Write spec" -> "Spec self-review\n(fix inline)";
+    "Spec self-review\n(fix inline)" -> "User reviews spec?";
+    "User reviews spec?" -> "Write spec" [label="changes requested"];
+    "User reviews spec?" -> "Invoke plastic-writing-plans" [label="approved"];
+}
+```

package/skills/creating-intent/SKILL.md

@@ -124,32 +124,11 @@ cleanly, and do not work around the failure by hand-writing the files.
 
 ### 6. If Implementation Intent Spawns a Project
 
-When the user says "start building" or the plan calls for a new project:
-
-1. Determine project slug from intent name
-2. Create project directory in first `project_roots` path (from `~/.plastic/config.yml`):
-   ```bash
-   mkdir -p <project_root>/<slug>
-   cd <project_root>/<slug>
-   git init
-   ```
-3. Copy `AGENTS.md` template from `${CLAUDE_PLUGIN_ROOT}/templates/agents.md`
-4. Register in `~/.plastic/projects.yml`:
-   ```yaml
-   <slug>:
-     path: <full-path>
-     parent: "ID"
-     registered: <today>
-     status: active
-   ```
-5. Provision the project store (the single source of truth for store creation;
-   runs after step 4 because the provisioner requires the project to be
-   registered):
-   ```bash
-   ruby ~/.plastic/scripts/provision-project-store <slug>
-   ```
-6. Add `project-<slug>` to the intent's `tags` array
-7. Auto-commit in both `~/.plastic/` and the new project
+When the user says "start building" or the plan calls for a new project, invoke the
+`plastic-creating-project` skill; it owns project directory creation, AGENTS.md
+population, projects.yml registration, store provisioning, and the auto-commit of
+both stores. Add `project-<slug>` to this intent's `tags` array either before
+invoking it or as part of that skill's handoff.
 
 ### 7. Update INDEX.md
 

package/skills/creating-project/SKILL.md

@@ -43,89 +43,25 @@ Invoke `plastic-install --local` in the project directory. This creates:
 
 ### 4. Populate AGENTS.md
 
-Create `AGENTS.md` in the project root with:
-
-```markdown
-# <Project Name> — Agent Instructions
-
-Read `PLASTIC.md` in `~/.plastic/`. It contains all Plastic conventions.
-Follow it exactly.
-
-This file is the operating contract for this project. Any agent entering
-this project reads this file first.
-
-## Global Store
-
-Location: `~/.plastic/`
-Governing intent(s): <list of founding intent IDs with descriptions>
-
-## Decisions
-
-<Copy ALL decisions from founding intent(s)' `## Context > ### Decisions`>
-
-Each decision should include:
-- The decision itself
-- The rationale (why this choice)
-- Date decided
-
-## Project-Specific Rules
-
-<Any rules derived from the decisions — e.g., "Use Minitest, not RSpec",
-"37signals methodology", "sqlite-vec for vector storage">
-```
+Create `AGENTS.md` in the project root from the skeleton in
+`references/project-scaffolding.md` ("AGENTS.md skeleton"): read it now and fill in
+the project name, governing intent IDs, decisions, and project-specific rules.
 
 ### 5. Create Tactical Mirror
 
-Create the first intent in the project's store at `~/.plastic/projects/{slug}/store/`:
+Create the first intent in the project's store at `~/.plastic/projects/{slug}/store/`
+using the frontmatter, sections, and INDEX.md line in `references/project-scaffolding.md`
+("Tactical mirror intent"), including the Hub multi-intent variant if there is more
+than one founding intent.
 
 **Directory:** `~/.plastic/projects/{slug}/store/1--{slug}/`
 **File:** `~/.plastic/projects/{slug}/store/1--{slug}/1--{slug}.md`
 
-```yaml
----
-id: '1'
-intent: "<same description as founding intent>"
-sources: ["global:<founding_intent_ID>"]
-chain: []
-created: <today>
-author: <same as founding intent author>
-tags: [<relevant tags>]
----
-```
-
-Sections:
-- `## Intent` — same as founding intent
-- `## Context` — carry forward relevant Context and Decisions
-- `## Outcome` — (pending)
-- `## Insights` — empty
-- `## Links` — `[[global:<founding_intent_ID>|<founding intent name>]]`
-
-Update the project's `~/.plastic/projects/{slug}/INDEX.md`:
-```markdown
-# Index
-
-## Active
-- [1 — <intent name>](store/1--<slug>/1.md) — implementation, from: global:<ID>
-```
-
-**For multi-intent spawning (Hub):**
-- `sources`: `["global:<id1>", "global:<id2>", ...]` — all founding intents
-- All founding intents' decisions merge into AGENTS.md
-- Context carries forward from all founding intents
-
 ### 6. Register in projects.yml
 
-Read `~/.plastic/projects.yml` and add:
-
-```yaml
-<slug>:
-  path: <full-path>
-  parent: "<founding_intent_ID>"
-  registered: <today>
-  status: active
-```
-
-For Hub-spawned projects, `parent` references the primary founding intent.
+Read `~/.plastic/projects.yml` and add the entry shown in
+`references/project-scaffolding.md` ("projects.yml registration block"). For
+Hub-spawned projects, `parent` references the primary founding intent.
 
 ### 7. Provision the Project Store
 
@@ -195,4 +131,5 @@ Announce to user:
 
 ## References
 
+- Read `references/project-scaffolding.md` before steps 4-6, for the AGENTS.md skeleton, the tactical mirror intent format, and the projects.yml registration block
 - Read `references/hubs-projects.md` for the full hub/project relationship model, project creation flow, and cross-linking conventions

package/skills/creating-project/references/project-scaffolding.md

@@ -0,0 +1,97 @@
+# Project Scaffolding Templates
+
+Full templates for the artifacts created while spawning a project: the AGENTS.md
+skeleton (Workflow step 4), the tactical mirror intent (step 5), and the
+projects.yml registration block (step 6).
+
+## Table of Contents
+
+- [AGENTS.md skeleton (step 4)](#agentsmd-skeleton-step-4)
+- [Tactical mirror intent (step 5)](#tactical-mirror-intent-step-5)
+- [projects.yml registration block (step 6)](#projectsyml-registration-block-step-6)
+
+## AGENTS.md skeleton (step 4)
+
+Create `AGENTS.md` in the project root with:
+
+```markdown
+# <Project Name> — Agent Instructions
+
+Read `PLASTIC.md` in `~/.plastic/`. It contains all Plastic conventions.
+Follow it exactly.
+
+This file is the operating contract for this project. Any agent entering
+this project reads this file first.
+
+## Global Store
+
+Location: `~/.plastic/`
+Governing intent(s): <list of founding intent IDs with descriptions>
+
+## Decisions
+
+<Copy ALL decisions from founding intent(s)' `## Context > ### Decisions`>
+
+Each decision should include:
+- The decision itself
+- The rationale (why this choice)
+- Date decided
+
+## Project-Specific Rules
+
+<Any rules derived from the decisions — e.g., "Use Minitest, not RSpec",
+"37signals methodology", "sqlite-vec for vector storage">
+```
+
+## Tactical mirror intent (step 5)
+
+Create the first intent in the project's store at `~/.plastic/projects/{slug}/store/`:
+
+**Directory:** `~/.plastic/projects/{slug}/store/1--{slug}/`
+**File:** `~/.plastic/projects/{slug}/store/1--{slug}/1--{slug}.md`
+
+```yaml
+---
+id: '1'
+intent: "<same description as founding intent>"
+sources: ["global:<founding_intent_ID>"]
+chain: []
+created: <today>
+author: <same as founding intent author>
+tags: [<relevant tags>]
+---
+```
+
+Sections:
+- `## Intent` — same as founding intent
+- `## Context` — carry forward relevant Context and Decisions
+- `## Outcome` — (pending)
+- `## Insights` — empty
+- `## Links` — `[[global:<founding_intent_ID>|<founding intent name>]]`
+
+Update the project's `~/.plastic/projects/{slug}/INDEX.md`:
+```markdown
+# Index
+
+## Active
+- [1 — <intent name>](store/1--<slug>/1.md) — implementation, from: global:<ID>
+```
+
+**For multi-intent spawning (Hub):**
+- `sources`: `["global:<id1>", "global:<id2>", ...]` — all founding intents
+- All founding intents' decisions merge into AGENTS.md
+- Context carries forward from all founding intents
+
+## projects.yml registration block (step 6)
+
+Read `~/.plastic/projects.yml` and add:
+
+```yaml
+<slug>:
+  path: <full-path>
+  parent: "<founding_intent_ID>"
+  registered: <today>
+  status: active
+```
+
+For Hub-spawned projects, `parent` references the primary founding intent.

package/skills/dashboard/SKILL.md

@@ -110,23 +110,8 @@ a raw terminal. The Markdown board (`--data` + template) is the surface for the
 
 ## How classification works (deterministic)
 
-- **Effort** — small for `research`/`exploration`/`bugfix`, for already-scoped intents
-  (plan/checklist exists), or a **branch id** (folgezettel depth ≥ 2, e.g. `4a`, `12b3`); big
-  otherwise. A root id (a bare number) is always depth 1, so it is never demoted by this rule.
-- **Value → high** when any of: explicit `value: high`; a human-authored **root** intent; or
-  an intent that is a `source` of ≥1 other intent (it has spawned follow-on work). A purely
-  relational `chain` entry alone is **not** a value signal (intent 68) — else low.
-- **Flags** — `unblocked` only when a **future** intent has **all** its `sources` done AND at
-  least one source's completion date is strictly later than the intent's own `created` date (a
-  genuine wait, not a birth-time default); `in-progress` only when the savepoint ledger shows
-  real post-birth activity, not just the creation stamp; `stale` only on future intents past
-  the staleness threshold. All three kept low-noise by design.
-- **Override** — a `value: high|low` frontmatter field always wins (pre-stamped data, never
-  model judgment at render time).
-- **Caps** — quadrant lists and the project board's `active`/`future` lists are capped at 8
-  entries plus a trailing "+N more" line; each entry's text is truncated to 120 characters
-  with a trailing ellipsis. Applies to the Markdown board only (the ASCII renderer has its own
-  separate `CELL_CAP`).
+The script computes Effort/Value/Flags/Override/Caps; the agent never re-derives them.
+To explain or debug a quadrant assignment, read `references/classification.md`.
 
 ## Eval
 

package/skills/dashboard/references/classification.md

@@ -0,0 +1,22 @@
+# How Classification Works (Deterministic)
+
+The script (`dashboard.rb`) computes Effort/Value/Flags/Override/Caps deterministically;
+the agent never re-derives them. Read this to explain or debug a quadrant assignment.
+
+- **Effort** — small for `research`/`exploration`/`bugfix`, for already-scoped intents
+  (plan/checklist exists), or a **branch id** (folgezettel depth ≥ 2, e.g. `4a`, `12b3`); big
+  otherwise. A root id (a bare number) is always depth 1, so it is never demoted by this rule.
+- **Value → high** when any of: explicit `value: high`; a human-authored **root** intent; or
+  an intent that is a `source` of ≥1 other intent (it has spawned follow-on work). A purely
+  relational `chain` entry alone is **not** a value signal (intent 68) — else low.
+- **Flags** — `unblocked` only when a **future** intent has **all** its `sources` done AND at
+  least one source's completion date is strictly later than the intent's own `created` date (a
+  genuine wait, not a birth-time default); `in-progress` only when the savepoint ledger shows
+  real post-birth activity, not just the creation stamp; `stale` only on future intents past
+  the staleness threshold. All three kept low-noise by design.
+- **Override** — a `value: high|low` frontmatter field always wins (pre-stamped data, never
+  model judgment at render time).
+- **Caps** — quadrant lists and the project board's `active`/`future` lists are capped at 8
+  entries plus a trailing "+N more" line; each entry's text is truncated to 120 characters
+  with a trailing ellipsis. Applies to the Markdown board only (the ASCII renderer has its own
+  separate `CELL_CAP`).

package/skills/install/SKILL.md

@@ -158,7 +158,7 @@ Version:  none -> <installed>
 Doctor:   <summary or "all clear">
 ```
 
-Then: "Create your first intent with `/plastic-creating-intent`."
+Then: "Read `docs/guides/your-first-intent-in-10-minutes.md` for your first intent, start to finish."
 
 ### Local Install (testing/legacy)
 

package/skills/releasing/SKILL.md

@@ -85,14 +85,11 @@ git merge <branch-name> --no-ff -m "feat: merge intent [ID] - [description]"
 
 Always `--no-ff` to preserve branch history in the merge commit.
 
-**Worktree-isolated intents (intent 73c3).** When the intent was delivered in a Plastic
-worktree (the bridge has a provisioned `worktree` block), its code lives on the branch
-`plastic/{id}--{slug}` inside `<repo>/.claude/worktrees/{id}--{slug}`, not on a hand-made
-feature branch. The merge-then-remove of that worktree is handled together with cleanup in
-step 9, which merges `plastic/{id}--{slug}` into the default branch BEFORE removing the
-worktree. If you already merged here by hand, step 9 is a clean no-op merge ("Already up to
-date") and proceeds straight to removal. Do not delete the worktree before its branch is
-merged, or the work is lost.
+**Worktree-isolated intents (intent 73c3).** A worktree-delivered intent's code lives on
+`plastic/{id}--{slug}`, merged together with cleanup in step 9, not on a hand-made feature
+branch. Do not delete the worktree before its branch is merged, or the work is lost. For
+the full rationale and the already-merged-by-hand no-op case, read
+`references/promotion-and-tagging.md`.
 
 ### 4. Bump Version
 
@@ -231,12 +228,8 @@ A release IS a delivery. The active intent that drove this work must be complete
 
 ### 9. Clean Up the Intent's Worktrees (merge-then-remove)
 
-A release is the merge-then-remove path for the intent's worktrees (intent 73c3). This is the
-one place the merge-vs-remove policy lands on "merge": the intent's code branch
-(`plastic/{id}--{slug}`) is merged back into the repo's default branch BEFORE the worktree is
-removed, so the integrated work is never lost. (The disarm path in `plastic-auto`, by contrast,
-is a plain remove because no release is merging the branch.)
-
+A release is the merge-then-remove path for the intent's worktrees (intent 73c3): the
+intent's code branch is merged back into the default branch BEFORE the worktree is removed.
 Drive it through `Worktree.finish` with `merge: true`, which merges the code branch, then
 removes both worktrees (code + paired store), prunes both repos, and clears the worktree block
 from the bridge:
@@ -249,10 +242,10 @@ ruby -r ~/.plastic/scripts/lib/worktree -r ~/.plastic/scripts/lib/bridge -e \
 (Uses `discover_bridge`, not a bare session-keyed `Bridge.read`, because a session can own more
 than one live bridge now — intent 131 — and `discover_bridge` resolves the right one for this cwd.)
 
-`finish` is fail-open and idempotent: a conflicting merge is aborted and logged (the worktree
-is still removed rather than stranded), and a second call with the block already cleared is a
-no-op. Honor the worktree-cleanup rule: never leave an orphaned worktree, and run `git worktree
-prune` in the affected repo if you hit a stale reference.
+Honor the worktree-cleanup rule: never leave an orphaned worktree, and run `git worktree
+prune` in the affected repo if you hit a stale reference. For why this is the one place the
+merge-vs-remove policy lands on merge, and the fail-open/idempotent guarantees of `finish`,
+read `references/promotion-and-tagging.md`.
 
 ## Conventions
 
@@ -266,34 +259,9 @@ prune` in the affected repo if you hit a stale reference.
 - **Verify sync** - after pushing, confirm npm dist-tag, GitHub "Latest", and the git tag all show the new version
 - **Branch cleanup** - delete merged feature branches: `git branch -d <branch>`
 
-## Promotion
-
-To promote a release across channels, use `--promote`:
-
-```bash
-plastic-releasing --promote beta    # promotes current alpha → beta
-plastic-releasing --promote stable  # promotes current beta → stable
-```
-
-**Promotion rules:**
-- Linear only: alpha → beta → stable. Cannot skip channels.
-- `--promote beta`: reads version from `package.json`, changes `-alpha.N` suffix
-  to `-beta.1`, publishes with `--tag beta`.
-- `--promote stable`: reads version from `package.json`, strips pre-release suffix
-  entirely (e.g., `1.0.0-beta.3` → `1.0.0`), publishes to `latest`.
-- Version files are bumped and committed as in a normal release.
-- An annotated tag is created for the promoted version.
-
-## Retroactive Tagging
-
-For repos without prior tags, tag historical releases:
-
-```bash
-git tag -a v0.1.0 <commit-sha> -m "v0.1.0 - [description]"
-```
-
-Use `git log --oneline` to find the right commits (look for version bump commits or major feature merges).
-
 ## References
 
+- When promoting a pre-release across channels (`--promote beta`/`--promote stable`) or
+  tagging a historical release retroactively, read `references/promotion-and-tagging.md`
+  for the exact commands and rules first
 - Read `references/deprecations.md` for the full deprecation process, severity levels, deprecations.yml schema, and dismissal rules when adding or managing deprecations

package/skills/releasing/references/promotion-and-tagging.md

@@ -0,0 +1,60 @@
+# Promotion, Retroactive Tagging, and Worktree Merge Rationale
+
+Occasional variant paths off the main release workflow: promoting a pre-release
+across channels, tagging historical releases retroactively, and the deep rationale
+for why the intent's worktree is merged before removal.
+
+## Table of Contents
+
+- [Worktree merge-then-remove rationale](#worktree-merge-then-remove-rationale)
+- [Promotion](#promotion)
+- [Retroactive Tagging](#retroactive-tagging)
+
+## Worktree merge-then-remove rationale
+
+**Worktree-isolated intents (intent 73c3).** When the intent was delivered in a Plastic
+worktree (the bridge has a provisioned `worktree` block), its code lives on the branch
+`plastic/{id}--{slug}` inside `<repo>/.claude/worktrees/{id}--{slug}`, not on a hand-made
+feature branch. The merge-then-remove of that worktree is handled together with cleanup in
+Workflow step 9, which merges `plastic/{id}--{slug}` into the default branch BEFORE removing the
+worktree. If you already merged here by hand, step 9 is a clean no-op merge ("Already up to
+date") and proceeds straight to removal. Do not delete the worktree before its branch is
+merged, or the work is lost.
+
+A release is the merge-then-remove path for the intent's worktrees. This is the one place
+the merge-vs-remove policy lands on "merge": the intent's code branch (`plastic/{id}--{slug}`)
+is merged back into the repo's default branch BEFORE the worktree is removed, so the
+integrated work is never lost. (The disarm path in `plastic-auto`, by contrast, is a plain
+remove because no release is merging the branch.)
+
+`Worktree.finish` is fail-open and idempotent: a conflicting merge is aborted and logged (the
+worktree is still removed rather than stranded), and a second call with the block already
+cleared is a no-op.
+
+## Promotion
+
+To promote a release across channels, use `--promote`:
+
+```bash
+plastic-releasing --promote beta    # promotes current alpha → beta
+plastic-releasing --promote stable  # promotes current beta → stable
+```
+
+**Promotion rules:**
+- Linear only: alpha → beta → stable. Cannot skip channels.
+- `--promote beta`: reads version from `package.json`, changes `-alpha.N` suffix
+  to `-beta.1`, publishes with `--tag beta`.
+- `--promote stable`: reads version from `package.json`, strips pre-release suffix
+  entirely (e.g., `1.0.0-beta.3` → `1.0.0`), publishes to `latest`.
+- Version files are bumped and committed as in a normal release.
+- An annotated tag is created for the promoted version.
+
+## Retroactive Tagging
+
+For repos without prior tags, tag historical releases:
+
+```bash
+git tag -a v0.1.0 <commit-sha> -m "v0.1.0 - [description]"
+```
+
+Use `git log --oneline` to find the right commits (look for version bump commits or major feature merges).

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