@baldurpan/create-ai-workflow 0.2.0

package/dist/layout.js

@@ -0,0 +1,115 @@
+import path from 'node:path';
+import { readFileSync } from 'node:fs';
+import { templatesDir, toPosix, walk } from "./paths.js";
+/**
+ * Both trees ship. The hosts read disjoint directories — Codex finds `.agents/skills/` and never looks
+ * at `.claude/skills/` (§1.2) — so a repository worked on by more than one agent needs both, and a
+ * repository worked on by one pays a directory it never opens. Neither tree is ever hand-edited, which
+ * is what keeps the duplication structural rather than a drift risk (§5.1).
+ */
+export const DEFAULT_ADAPTERS = ['claude', 'agents'];
+/** Where each adapter's host looks for project-local skills. */
+export const ADAPTER_SKILL_DIRS = {
+    claude: '.claude/skills',
+    agents: '.agents/skills',
+};
+export function isAdapter(value) {
+    return value === 'claude' || value === 'agents';
+}
+/** The manifest key for the delimited block inside AGENTS.md. Not a file — a region of one. */
+export const AGENTS_BLOCK_KEY = 'AGENTS.md#ai-workflow';
+export const CONTEXT_DIR = 'context';
+export const MANIFEST_PATH = 'context/.state/manifest.json';
+export const STANDARDS_PREFIX = 'context/standards/';
+export const SKILL_NAMES = [
+    'roadmap',
+    'feature-plan',
+    'feature-implement',
+    'feature-status',
+    'feature-close',
+    'orchestrate',
+    'onboard',
+];
+/**
+ * A skill body is shared verbatim between adapter trees. `disable-model-invocation: true` is the only
+ * difference the Claude Code copy carries, and it is injected here rather than written into the template,
+ * so a second tree can reuse the same body untouched.
+ */
+export function claudeSkillTransform(text) {
+    const match = /^---\n([\s\S]*?)\n---\n/.exec(text);
+    if (!match)
+        throw new Error('skill template has no frontmatter block');
+    const frontmatter = match[1];
+    if (/^disable-model-invocation:/m.test(frontmatter))
+        return text;
+    const patched = `---\n${frontmatter}\ndisable-model-invocation: true\n---\n`;
+    return patched + text.slice(match[0].length);
+}
+/**
+ * npm refuses to publish a file named `.gitignore`, so the vendored standards carry theirs as
+ * `_dot_gitignore` and it is restored here. Without this the installed tree would quietly differ from the
+ * ref `standards/.source` claims it came from.
+ */
+export function undotted(posix) {
+    return posix.replace(/(^|\/)_dot_/, '$1.');
+}
+/** Every tool-owned file, in the order it should be written and reported. */
+export function managedFiles(adapters) {
+    const files = [
+        { source: 'context/README.md', dest: 'context/README.md' },
+        { source: 'context/workflow.md', dest: 'context/workflow.md' },
+        { source: 'context/plan-template.md', dest: 'context/plan-template.md' },
+        { source: 'context/plan-template.notes.md', dest: 'context/plan-template.notes.md' },
+        { source: 'context/roles/coder.md', dest: 'context/roles/coder.md' },
+    ];
+    for (const rel of walk(path.join(templatesDir, 'standards'))) {
+        const posix = toPosix(rel);
+        files.push({ source: `standards/${posix}`, dest: `${STANDARDS_PREFIX}${undotted(posix)}` });
+    }
+    if (adapters.includes('claude')) {
+        for (const name of SKILL_NAMES) {
+            files.push({
+                source: `skills/${name}/SKILL.md`,
+                dest: `${ADAPTER_SKILL_DIRS.claude}/${name}/SKILL.md`,
+                transform: claudeSkillTransform,
+            });
+        }
+        for (const rel of walk(path.join(templatesDir, 'claude', 'agents'))) {
+            const posix = toPosix(rel);
+            files.push({ source: `claude/agents/${posix}`, dest: `.claude/agents/${posix}` });
+        }
+    }
+    // The same seven bodies, verbatim. No transform: `disable-model-invocation` is Claude Code's key and
+    // means nothing here, and there is no subagent tree to go with it — the skills already write
+    // delegation as optional.
+    if (adapters.includes('agents')) {
+        for (const name of SKILL_NAMES) {
+            files.push({
+                source: `skills/${name}/SKILL.md`,
+                dest: `${ADAPTER_SKILL_DIRS.agents}/${name}/SKILL.md`,
+            });
+        }
+    }
+    return files;
+}
+/** Project-owned files. Written once, at install, and never reachable by `update`. */
+export const STUBS = [
+    { source: 'stubs/stack.md', dest: 'context/stack.md' },
+    { source: 'stubs/verify.md', dest: 'context/verify.md' },
+    { source: 'stubs/executors.md', dest: 'context/executors.md' },
+    { source: 'stubs/roadmap.md', dest: 'context/roadmap.md' },
+    { source: 'stubs/history.md', dest: 'context/history.md' },
+    { source: 'stubs/findings.md', dest: 'context/findings.md' },
+];
+export const STUB_DIRS = ['context/drafts', 'context/plans', 'context/archive'];
+export function readTemplate(source) {
+    return readFileSync(path.join(templatesDir, source), 'utf8');
+}
+/** The rendered content of a managed file — the template with its transform applied. */
+export function renderManaged(file) {
+    const text = readTemplate(file.source);
+    return file.transform ? file.transform(text) : text;
+}
+export function agentsBlockBody() {
+    return readTemplate('blocks/agents-block.md').trim();
+}

package/dist/log.js

@@ -0,0 +1,20 @@
+const useColour = process.stdout.isTTY && !process.env.NO_COLOR;
+const wrap = (code) => (s) => (useColour ? `\x1b[${code}m${s}\x1b[0m` : s);
+export const bold = wrap('1');
+export const dim = wrap('2');
+export const red = wrap('31');
+export const green = wrap('32');
+export const yellow = wrap('33');
+export const cyan = wrap('36');
+export function info(message = '') {
+    process.stdout.write(`${message}\n`);
+}
+export function warn(message) {
+    process.stdout.write(`${yellow('!')} ${message}\n`);
+}
+export function fail(message) {
+    process.stderr.write(`${red('error')} ${message}\n`);
+}
+/** An error whose message is meant for the user — printed without a stack trace. */
+export class UserError extends Error {
+}

package/dist/manifest.js

@@ -0,0 +1,53 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { MANIFEST_PATH, isAdapter } from "./layout.js";
+import { UserError } from "./log.js";
+import { exists } from "./paths.js";
+export const SCHEMA_VERSION = 1;
+export function manifestPath(root) {
+    return path.join(root, MANIFEST_PATH);
+}
+export function hasManifest(root) {
+    return exists(manifestPath(root));
+}
+export function readManifest(root) {
+    const file = manifestPath(root);
+    if (!exists(file)) {
+        throw new UserError(`no manifest at ${MANIFEST_PATH} — this repository has no ai-workflow install to update.\n` +
+            '  Run `npx @baldurpan/create-ai-workflow` to install one.');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        throw new UserError(`${MANIFEST_PATH} is not valid JSON: ${error.message}`);
+    }
+    const manifest = parsed;
+    if (manifest.schemaVersion !== SCHEMA_VERSION) {
+        throw new UserError(`${MANIFEST_PATH} has schemaVersion ${String(manifest.schemaVersion)}; this tool writes ${SCHEMA_VERSION}.`);
+    }
+    if (!manifest.managedFiles || typeof manifest.managedFiles !== 'object') {
+        throw new UserError(`${MANIFEST_PATH} has no managedFiles map.`);
+    }
+    // An adapter this version does not know is dropped rather than carried: `managedFiles` still lists
+    // whatever it wrote, so `update` reports those files as no longer shipped instead of losing them.
+    const adapters = (manifest.adapters ?? []).filter(isAdapter);
+    return {
+        schemaVersion: SCHEMA_VERSION,
+        version: manifest.version ?? '0.0.0',
+        adapters: adapters.length ? adapters : ['claude'],
+        managedFiles: manifest.managedFiles,
+    };
+}
+export function writeManifest(root, manifest) {
+    const file = manifestPath(root);
+    mkdirSync(path.dirname(file), { recursive: true });
+    const ordered = {
+        schemaVersion: manifest.schemaVersion,
+        version: manifest.version,
+        adapters: manifest.adapters,
+        managedFiles: Object.fromEntries(Object.entries(manifest.managedFiles).sort(([a], [b]) => (a < b ? -1 : 1))),
+    };
+    writeFileSync(file, `${JSON.stringify(ordered, null, 2)}\n`, 'utf8');
+}

package/dist/paths.js

@@ -0,0 +1,41 @@
+import { createHash } from 'node:crypto';
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Root of the published package — the directory holding `templates/`. */
+export const packageRoot = path.resolve(fileURLToPath(import.meta.url), '..', '..');
+export const templatesDir = path.join(packageRoot, 'templates');
+export function packageVersion() {
+    const pkg = JSON.parse(readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+    return pkg.version;
+}
+/** sha256 of a buffer or string, hex. Line endings are normalised so a CRLF checkout is not a conflict. */
+export function hash(content) {
+    const text = typeof content === 'string' ? content : content.toString('utf8');
+    return createHash('sha256').update(text.replace(/\r\n/g, '\n'), 'utf8').digest('hex');
+}
+/** Every file under `dir`, as paths relative to `dir`, sorted. Follows no symlinks. */
+export function walk(dir, base = dir) {
+    const out = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...walk(full, base));
+        else if (entry.isFile())
+            out.push(path.relative(base, full));
+    }
+    return out.sort();
+}
+export function exists(p) {
+    try {
+        statSync(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Always forward slashes — manifest keys are portable across platforms. */
+export function toPosix(p) {
+    return p.split(path.sep).join('/');
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@baldurpan/create-ai-workflow",
+  "version": "0.2.0",
+  "description": "Overlay a tiered planning workflow — roadmap, plans, phase ledgers, verification gates — onto an existing repository, for coding agents.",
+  "keywords": ["ai", "agents", "claude-code", "workflow", "planning", "AGENTS.md"],
+  "license": "MIT",
+  "author": "Baldur Páll Hólmgeirsson",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/baldurpan/ai-workflow.git"
+  },
+  "homepage": "https://github.com/baldurpan/ai-workflow#readme",
+  "bugs": {
+    "url": "https://github.com/baldurpan/ai-workflow/issues"
+  },
+  "type": "module",
+  "bin": {
+    "create-ai-workflow": "dist/bin.js"
+  },
+  "files": ["dist", "templates", "README.md", "LICENSE"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.10.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build && npm test",
+    "test": "node --test \"test/*.test.ts\"",
+    "check": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.9.2"
+  }
+}

package/templates/blocks/agents-block.md

@@ -0,0 +1,30 @@
+## Planning workflow
+
+Planning artifacts live in [`context/`](context/README.md). Read
+[`context/workflow.md`](context/workflow.md) before using any command below — it holds the tier model and
+the standing rules, and every command cites it rather than restating it.
+
+| Command | Does |
+|---|---|
+| `/roadmap` | prints the Tier-1 backlog, or appends one `pending` entry to it |
+| `/feature-plan` | turns a backlog entry into `context/plans/<NAME>-PLAN.md` and **stops** — it never implements |
+| `/feature-implement` | activates a planned feature and runs its phases, through both gates |
+| `/feature-status` | read-only "where do things stand". **Never a prerequisite** for anything |
+| `/feature-close` | retires a finished or abandoned feature into `context/archive/` |
+| `/orchestrate` | one ad-hoc, gated, commit-sized change — no roadmap entry, no ledger |
+| `/onboard` | fills in this project's own stubs: `verify.md`, `executors.md`, `stack.md` |
+
+| Read | For |
+|---|---|
+| [`context/stack.md`](context/stack.md) | runtime, layout, conventions |
+| [`context/standards/README.md`](context/standards/README.md) | engineering standards — load per its conditional table |
+| [`context/verify.md`](context/verify.md) | the real lint / typecheck / build / test commands — the only file that names one |
+
+**Phase status lives in the active plan's status ledger and nowhere else.** Work the lowest-numbered phase
+that is not `done` and whose `Depends on` are all `done`; state which you picked before starting; update
+the row in the same commit as the work. **If the ledger disagrees with the repo, stop and say so.**
+
+**An open `P0` or `P1` in [`context/findings.md`](context/findings.md) blocks its phase from being `done`.**
+
+**Require evidence, not assertion.** A claim about what a file contains needs the file read, not recalled —
+yours as much as a subagent's.

package/templates/claude/agents/planner.agent.md

@@ -0,0 +1,60 @@
+---
+name: planner
+description: Researches the codebase and the relevant documentation and drafts a plan. Use when a plan is needed before implementing a feature or fixing a complex issue. Does not write code.
+model: inherit
+tools: Read, Grep, Glob, Bash, WebFetch, WebSearch
+---
+
+# Planner
+
+You research and draft. You do **not** write code, and you do not edit files.
+
+## Research
+
+You do your own research — a subagent cannot dispatch further subagents. Use `Read`, `Grep` and `Glob` for
+the codebase, a documentation MCP server if one is configured, and `WebFetch` / `WebSearch` for anything it
+does not cover. `Bash` is for read-only inspection (`git log`, `ls`, `--version`) — never for writing.
+
+Do not assume a library's current API from memory. Verify it, and cite what you confirmed.
+
+## The output contract comes from the brief
+
+**Your brief names the required output shape. It overrides everything below.** When it names a template's
+section list, that section list *is* your output — in that order, with the ledger's exact column set. A
+plan document and a per-phase work item are different artifacts, and producing the wrong one wastes the
+run.
+
+The default shape below applies only when the brief names none.
+
+## Workflow
+
+1. **Load the standards.** Read `context/standards/README.md` and load the files its conditional-loading
+   table points at for this task. Your checklist items must reference specific rules from those files, not
+   generic principles.
+2. **Read the project.** `context/stack.md` for what this repo is; `context/verify.md` for how it proves
+   itself. Search the codebase and find the patterns that already exist.
+3. **Verify externals.** Check documentation for every library and API involved. Cite what you confirmed.
+4. **Consider.** Edge cases, error states, and implicit requirements the request did not mention.
+5. **Draft.** Say *what* needs to happen, not *how* to code it.
+
+## Default output shape
+
+**Summary** — one paragraph on the change and its intent.
+
+**Steps** — ordered. Each one: what needs to happen, the explicit file paths it creates or modifies, the
+testable acceptance criteria, and the review checklist items (naming the specific standards that apply).
+
+**Edge cases** — the cross-cutting ones not tied to a single step.
+
+**Open questions** — anything you could not resolve. Mark them clearly.
+
+## Rules
+
+- **Cite a file path or command output for every claim about the current codebase.** An assertion about
+  what a file contains needs the file read, not recalled.
+- **Anything you could not verify is an open question, not an assertion.** An honest gap is worth more than
+  an invented decision.
+- Acceptance criteria must be **testable** — say what passes and what fails, not "should work well".
+- Review checklist items must name **specific standards**, not "follow best practices".
+- **Name no verification command.** `context/verify.md` is the only file in this project that does. Point
+  at it.

package/templates/claude/agents/reviewer.agent.md

@@ -0,0 +1,77 @@
+---
+name: reviewer
+description: Reviews a completed implementation against the plan's review checklist and the project's engineering standards, returning a verdict with severities and cited evidence. Use as the review gate after verification passes.
+model: inherit
+tools: Read, Grep, Glob, Bash
+---
+
+# Reviewer
+
+You review a completed implementation. You are an **evidence-gatherer first and a judge second**.
+
+You are called after verification has passed. You receive the implementation output, the plan's review
+checklist, and the verification result — for context, not for re-running.
+
+Your verdict gates completion:
+
+- **PASS**, or **PASS WITH NOTES** the caller accepts → the work is complete.
+- **FAIL** → the caller writes a finding and loops back. Cap: two loops.
+
+## Do these in order
+
+### 1. Gather evidence, before forming any opinion
+
+- For every file in the brief's file list: if its content is inlined in the prompt, treat that as the
+  source of truth. Otherwise `Read` it. Do this **before** writing a summary, before forming a verdict.
+- For every "missing X" claim you are considering: run `grep -n "<pattern>" <file>`. The empty output is
+  your evidence. Cite the search you ran.
+- For every standards rule you cite: open the file and quote the rule verbatim. Load them per the
+  conditional table in `context/standards/README.md`.
+- Read the diff: `git diff` for uncommitted work, `git diff <base>...HEAD` against a base branch.
+
+**You may not cite a line, quote code, or reference a file you have not opened.** If you find yourself
+writing "line 42 says X", verify that line 42 says X. If you cannot, write
+`NOT VERIFIED: I do not have access to <file>:42`.
+
+### 2. Walk the checklist
+
+For every item in the plan's review checklist, write a verdict, using only the evidence from step 1.
+
+### 3. Form blocking findings
+
+A finding is **blocking** only if all three hold:
+
+1. It corresponds to a specific review checklist item, or violates a standard the plan referenced.
+2. You have a verbatim quote from the actual file as evidence — line number and content.
+3. The fix is specific and actionable in one targeted edit.
+
+If you cannot satisfy all three, it is a **non-blocking note**, not a blocking finding.
+
+### 4. Write the verdict
+
+```
+Verdict: PASS | PASS WITH NOTES | FAIL   (severity: P0 | P1 | P2 | P3)
+
+Evidence gathered
+- <file>:<line> — <verbatim quote>
+- <the grep you ran, and its output>
+
+Checklist
+- <item> — <verdict, with the evidence that supports it>
+
+Blocking findings   (each with a severity, the file, and the specific fix)
+Non-blocking notes
+```
+
+Every blocking finding carries a `P0`–`P3` severity, and the verdict carries the highest of them.
+`P0` breaks production or data. `P1` blocks a phase or a gate. `P2` is a real defect that does not block.
+`P3` is a note worth not losing.
+
+## Rules
+
+- **Never invent evidence.** These rules exist because past reviews have.
+- **Do not re-run verification.** It already ran; you are reading the code.
+- **Do not fix anything.** You review; the coder fixes.
+- **Name no verification command.** `context/verify.md` is the only file in this project that does.
+- Scope is the change, not the repository. You are judging what landed, not everything that was already
+  there.

package/templates/context/README.md

@@ -0,0 +1,81 @@
+# context/
+
+Everything an agent needs to work on this project, in one agent-neutral place. Nothing here is specific to
+any one coding agent — `AGENTS.md` at the repo root is the entry point that points here.
+
+## The one rule that outranks the others
+
+**No document states its own status.** There is no `**Status:**` header anywhere under `context/`. Every
+status has exactly one home:
+
+| To know | Read |
+|---|---|
+| whether a feature is being worked | the `pending` / `active` marker in its [`roadmap.md`](roadmap.md) heading |
+| whether a feature has a plan | whether its **Doc** field points into [`plans/`](plans/) |
+| where a phase stands | that plan's own status ledger |
+| what a retired feature's outcome was | its [`history.md`](history.md) row |
+
+A header that claims a status is a copy nobody remembers to update. The two facts "is it being worked" and
+"does it have a plan" are orthogonal, which is why they live in two different places and neither can go
+stale against the other.
+
+Nothing here is cached, parsed by a script, or generated. There is no build step in the planning loop and no
+generated "current state" file — hand-editing a ledger row changes every command's answer immediately.
+
+## What the tool installs
+
+| File | Holds | Owner |
+|---|---|---|
+| `README.md` | this file | tool |
+| [`workflow.md`](workflow.md) | the tier model, the commands, the standing invariants | tool |
+| [`plan-template.md`](plan-template.md) | the bare skeleton every Tier-2 plan is copied from | tool |
+| [`plan-template.notes.md`](plan-template.notes.md) | what goes in each section of that skeleton | tool |
+| [`roles/coder.md`](roles/coder.md) | the coder system prompt — names no commands | tool |
+| [`standards/`](standards/README.md) | engineering standards, loaded per that README's conditional table | tool* |
+| [`stack.md`](stack.md) | this project's runtime, layout, conventions, and an index of your own files | project |
+| [`verify.md`](verify.md) | this project's real lint / typecheck / build / test commands | project |
+| [`executors.md`](executors.md) | how this project dispatches a coder and a reviewer | project |
+| [`roadmap.md`](roadmap.md) | Tier 1 — the backlog. `pending` and `active` entries only | project |
+| [`history.md`](history.md) | index of retired features, newest last | project |
+| [`findings.md`](findings.md) | open findings that gate a phase from being marked `done` | project |
+| [`drafts/`](drafts/) | notes and source material for ideas not yet planned — no ledger | project |
+| [`plans/`](plans/) | Tier 2 — documents with an executable phase ledger | project |
+| [`archive/`](archive/) | retired plans, moved here by `/feature-close` | project |
+
+`*` `standards/` is tool-owned only while it is the bundled default and unmodified. Swap it with
+`standards add <git-url>`, or edit it, and it becomes yours — it drops out of the manifest and updates
+stop reaching it.
+
+A document moves once per tier transition, and **which directory it sits in tells you what it is**:
+
+```
+drafts/  ──/feature-plan──▶  plans/  ──/feature-close──▶  archive/
+notes                        a phase ledger              retired
+```
+
+`plans/` means "has an executable ledger" and nothing more — it does not imply the feature is being worked.
+If a document is ever misfiled, the roadmap's link to it breaks loudly rather than lying quietly.
+
+## Ownership
+
+This directory mixes tool-supplied content with project state. The boundary is enforced by a data structure,
+not by a rule someone has to remember: `context/.state/manifest.json` lists every tool-owned file with its
+hash, `update` walks that manifest, and a project-owned file is not in it — so no code path reaches it.
+
+| Tool-owned — replaced on `update` | Project-owned — unreachable by the updater |
+|---|---|
+| `README.md`, `workflow.md`, `plan-template*.md`, `roles/` | `stack.md`, `verify.md`, `executors.md` |
+| the skill and agent trees, the `AGENTS.md` block | `roadmap.md`, `history.md`, `findings.md` |
+| `standards/` while it is ours and unmodified | `drafts/`, `plans/`, `archive/`, `CLAUDE.md` |
+
+`update` prints both columns when it runs. A visible boundary beats a documented one.
+
+**Anything else you add under `context/` is yours forever**, by the same property — `context/decisions.md`,
+`context/glossary.md`, `context/ops-notes.md` all survive by default, with no feature required to protect
+them. Index your own additions in [`stack.md`](stack.md), not here: this file is replaced on every update,
+so a line you add to it is a line you lose.
+
+## What does not belong here
+
+Planning artifacts live in `context/`, wherever else your docs live. Product specs, API references and
+anything else written for humans or library consumers stay where this project already keeps them.

package/templates/context/plan-template.md

@@ -0,0 +1,69 @@
+# <Feature> Plan
+
+Written <YYYY-MM-DD>. <One line on what this is.> The `<name>` entry in
+[`../roadmap.md`](../roadmap.md) is where this feature's status lives.
+
+**Phase status lives in §6.1 of this document, and nowhere else.**
+
+---
+
+## 1. Why
+
+<The problem, with evidence.>
+
+## 2. Constraints
+
+<What the solution may not do.>
+
+## 3. Decisions
+
+**D1.** <Decision.> Rejected: <alternative>, because <why>.
+
+## 4. Design
+
+<How it works.>
+
+## 5. Risks
+
+<What could go wrong, how it would show up, and the response.>
+
+## 6. Phases
+
+### 6.1 Status ledger
+
+| # | Phase | Status | Depends on | Note |
+|---|---|---|---|---|
+| 1 | <name> | not started | — | |
+| 2 | <name> | not started | 1 | |
+
+Status is one of `not started`, `in progress`, `blocked`, `done`. `done` only when committed and verified,
+and whoever finishes a phase updates the row in the same commit.
+
+**Exactly one table in this document has these columns.** Do not add a second phase table — a
+differently-shaped one nearby is a decoy that gets read by mistake.
+
+### 6.2 The phases
+
+#### Phase 1 — <name>
+
+**Files:** <every path this phase creates or modifies>
+
+**Scope:** <what it does>
+
+**Done when:** <a condition checkable against the repo>
+
+#### Phase 2 — <name>
+
+**Files:** <every path this phase creates or modifies>
+
+**Scope:** <what it does>
+
+**Done when:** <a condition checkable against the repo>
+
+## 7. Verification
+
+<How to prove the feature works, beyond `context/verify.md` passing.>
+
+## 8. Open questions
+
+- <Anything the plan could not settle. An honest gap is worth more than an invented decision.>

package/templates/context/plan-template.notes.md

@@ -0,0 +1,55 @@
+# Filling in a Tier-2 plan
+
+[`plan-template.md`](plan-template.md) is the skeleton. `/feature-plan` copies it **verbatim** into
+`context/plans/<NAME>-PLAN.md` and then fills it in — there is no fenced block to extract and no italic
+guidance to strip, because all of that is here instead.
+
+Sections may be added. The ones in the template may not be dropped or reordered, and the ledger's column
+set is fixed — `check` compares every plan's ledger against the template's.
+
+## What goes in each section
+
+**§1 Why** — the problem, with evidence. Measurements, failing cases, user-visible symptoms; not "it would
+be nice if". A reader who disagrees with this section should not read further, and a reader who agrees
+should not need convincing again later.
+
+**§2 Constraints** — what the solution may not do. Runtime limits, compatibility promises, things already
+decided elsewhere that this must respect. Link to [`stack.md`](stack.md) rather than restating it.
+
+**§3 Decisions** — numbered `D1`, `D2`, … so later sections and source comments can cite them by number.
+Each one: the decision, the alternative rejected, and why. This is the section that stops a question being
+re-litigated in three months.
+
+**§4 Design** — how it works. Sub-sections as the shape of the work demands. Cite file paths for anything
+that already exists.
+
+**§5 Risks** — what could go wrong, how it would show up, and what the response is. "Unknown" is an
+acceptable response; silence is not.
+
+**§6.1 Status ledger** — one row per phase, `not started` in a newly written plan. Every row needs a real
+`Depends on` value (`—` for none): the phase-selection rule *is* "lowest-numbered phase that is not `done`
+and whose `Depends on` are all `done`", so a missing column silently degrades it.
+
+**§6.2 The phases** — one sub-section per ledger row. **The `Files:` line is required, not advisory.** It
+is what turns `/feature-status`'s reconciliation from a judgement call into a check: without it, "does the
+repo match the ledger" has no answer. A phase is a **commit-sized unit of work with a checkable outcome**,
+not a category of activity — "grammar plus container support for the new token" is a phase; "testing" is
+not.
+
+**§7 Verification** — how to prove the feature works, beyond [`verify.md`](verify.md) passing. Commands to
+run by hand, files to eyeball, numbers to compare against §1's measurements. Anything that belongs to the
+project's standing verification stack goes in `verify.md` instead, not here.
+
+**§8 Open questions** — what the plan could not settle. Do not paper over them.
+
+## Standing rules
+
+- **The document never states its own status.** No `**Status:**` header, ever. Feature status lives in
+  [`roadmap.md`](roadmap.md), phase status in §6.1, retired outcomes in [`history.md`](history.md) — one
+  place each. `check` fails a plan that grows one.
+- **`/feature-plan` produces a reviewable skeleton plus open questions**, not a finished plan of record.
+  §1, §3 and §6.1 are the sections research can usefully draft. §4 and §5 usually arrive as open questions.
+- **Cite by §-number, not by line number.** Source comments cite plan sections; line numbers rot on the
+  first edit, and a §-number survives the move into `archive/`.
+- **Never mark a phase `done` in a plan that has not been executed.** Every phase in a new plan is
+  `not started`.