git:20260930.f6c6d99 to git:20260930.a8a7956

+ │ │ ├── skills/ # workflow skills (user-invocable) + internal spec/implement skills

+ The specification describes **WHY** and **WHAT** (the target state and what "done" looks like); the implementation is a set of **tasks** in the spec's tracker. **HOW** to build each task is decided by the code agent inside the implementation loop. The two concerns are split across a clean line.

+ - `plan.mdx` — **WHAT (narrative)**: the high-level approach — phases and achievable outcomes, plus a link to the tracker. Read for orientation, not parsed for work.

+ - `.tracker/` — the operational **tasks** (managed by `task.js`): a root **phase** task, one **slice** task per vertical deliverable (its body is the code brief — features + EARS behavior + quality gates), and under each slice its **scenario** child tasks (the holdout acceptance evidence). `--depends-on` edges between slices are the parallelization contract.

+ The specification carries **no task-by-task instructions** — a slice says what it delivers and how it is proven, never the steps to build it. `/start:specify` runs Requirements → Solution → Plan (a 5-step flow: init → requirements → solution → plan → finalize); `specify-plan` writes the narrative `plan.mdx` and creates the tracker tasks.

+ #### One implementation loop (the dynamic-workflow runtime)

+ There is a single `/start:implement`, and it always runs on Claude Code's **dynamic-workflow runtime**. It reads the spec's tasks from the tracker and launches the reusable workflow script that ships beside it — `implement/reference/implement.js`, whose `meta.name` is `run-implement` — via `Workflow({ scriptPath, args })`, with the slice tasks as input. There is no install step: the script runs where it ships.

+ The workflow drives each slice through a **barriered code→eval retry loop**:

+ - a **code agent** builds the slice via TDD — it reads the slice task (features + EARS + gates), never its scenario child tasks;

+ - an **eval agent** proves the slice against its scenario child tasks through external interfaces — it reads the scenarios + service config, never the slice or the source;

+ - failures are filtered to one-line summaries and fed back until the slice's scenarios pass the `threshold`, or `max_iterations` is reached; each failed scenario becomes a `type: bug` child task.

+ The information barrier is *which task each agent reads* — the code agent the slice, the eval agent its scenario children. Independent slices (no unmet dependency) run concurrently via the runtime's `parallel()`; dependent slices run in order. Scale is emergent — a 1-slice plan is a short loop, a 40-slice plan fans out. Specs created before this model (legacy `### BEAN-N` plans, `plan/` / `manifest.md`) are not run; `/start:implement` offers to re-run `/start:specify` to regenerate the tasks. Users invoke `/start:specify` and `/start:implement`; everything else is internal.

+ | Workflow scripts | `plugins/*/skills/*/reference/*.js` | file matches the skill; `meta.name` is **`run-<script>`** (see below) |

+

+ ### Skill vs workflow naming

+

+ A workflow's `meta.name` is always **`run-<script>`** — the script's filename with a `run-` prefix.

+

+ | | Skill | Workflow (`meta.name`) |

+ |---|---|---|

+ | Shape | short noun or verb — the thing you type | `run-` + the script filename |

+ | Example | `implement` | `run-implement` |

+

+ | Skill | Script | Workflow |

+ |---|---|---|

+ | `implement` | `implement/reference/implement.js` | `run-implement` |

+ | `analyze` | `analyze/reference/analyze.js` | `run-analyze` |

+ | `review` | `review/reference/review.js` | `run-review` |

+ | `specify-solution` | `specify-solution/reference/solution-review.js` | `run-solution-review` |

+ | `daydream` | `daydream/reference/daydream.js` | `run-daydream` |

+

+ The prefix is the whole convention: it is mechanically derivable (no naming judgment, so no drift), it

+ sorts every workflow together, and `run-` is instantly recognizable in the `/workflows` progress view and

+ the run-approval dialog. The name only has to *identify* the run — the view shows `meta.description` and

+ the phase list beside it, so the name carries no burden to describe.

+

+ **Never give a workflow the same `meta.name` as a skill.** Skills and workflows share one `/[plugin]:`

+ namespace, so identical names collide and the workflow shadows the skill — replacing a working entry

+ point with a script that cannot run standalone. The `run-` prefix makes that impossible by construction:

+ no skill is named `run-*`.

+

+ ### Where workflow scripts live — and why not `workflows/`

+

+ A plugin *can* ship workflows from a `workflows/` directory at the plugin root (or the `workflows`

+ manifest field), which registers each as `/[plugin]:[meta.name]`. **Ours deliberately do not.** A script

+ in `workflows/` becomes a command a user can type, and per the Claude Code docs a workflow script has

+ "no direct filesystem or shell access" and cannot take mid-run user input — so none of ours can resolve

+ its own `args`. They are engines their skill feeds via `Workflow({ scriptPath, args })`, not commands.

+

+ Each script therefore sits beside the one skill that launches it, in that skill's `reference/`. There is

+ no install step and no version marker: the script runs where it ships, and the plugin version governs.