@rasensio/aidlc-content 1.37.1 → 1.39.0

package/dist/howto.d.ts

@@ -0,0 +1,17 @@
+import type { HowTo } from './types.js';
+/**
+ * The only headings a how-to body may contain at level 1 or 2, in this order
+ * (docs-how-to-recipes/AC-3). Holding the list exact — no `#` heading, no extra
+ * `##` — is also what keeps the page to a single `h1` (AC-7): the title comes
+ * from frontmatter, so a `# Title` in the body would be a second one.
+ */
+export declare const HOWTO_SECTIONS: readonly ["What you'll do", "Steps", "Check it worked"];
+/** Parse one how-to. `filename` only labels errors. */
+export declare function parseHowToSource(raw: string, filename?: string): HowTo;
+/**
+ * Every how-to, sorted by `order` (AC-5). Throws on the first bad file — this
+ * runs inside `next build`, so a bad recipe fails the build rather than shipping.
+ */
+export declare function loadHowTos(dir?: string): HowTo[];
+export declare function getHowTo(slug: string): HowTo | undefined;
+//# sourceMappingURL=howto.d.ts.map

package/dist/howto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"howto.d.ts","sourceRoot":"","sources":["../src/howto.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAOxC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,yDAA0D,CAAC;AA0FtF,uDAAuD;AACvD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,CAGtE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,GAAE,MAAkB,GAAG,KAAK,EAAE,CAwB3D;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAExD"}

package/dist/howto.js

@@ -0,0 +1,121 @@
+import { fileURLToPath } from 'node:url';
+import { resolve, dirname } from 'node:path';
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import { parse as parseYaml } from 'yaml';
+const CONTENT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const HOWTO_DIR = resolve(CONTENT_ROOT, 'howto');
+const SLUG_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+/**
+ * The only headings a how-to body may contain at level 1 or 2, in this order
+ * (docs-how-to-recipes/AC-3). Holding the list exact — no `#` heading, no extra
+ * `##` — is also what keeps the page to a single `h1` (AC-7): the title comes
+ * from frontmatter, so a `# Title` in the body would be a second one.
+ */
+export const HOWTO_SECTIONS = ["What you'll do", 'Steps', 'Check it worked'];
+function fail(filename, message) {
+    throw new Error(filename ? `How-to "${filename}": ${message}` : message);
+}
+function parseFrontmatter(raw, filename) {
+    const match = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+    if (!match)
+        fail(filename, 'missing YAML frontmatter');
+    const parsed = (parseYaml(match[1]) ?? {});
+    const { title, description, order, slug } = parsed;
+    // Same four rules as tutorials, so one mental model covers both (AC-2).
+    if (typeof title !== 'string' || title.length === 0 || title.length > 100) {
+        fail(filename, 'invalid title: must be a string of 1-100 characters');
+    }
+    if (typeof description !== 'string' || description.length === 0 || description.length > 300) {
+        fail(filename, 'invalid description: must be a string of 1-300 characters');
+    }
+    if (typeof order !== 'number' || !Number.isInteger(order) || order < 1 || order > 999) {
+        fail(filename, 'invalid order: must be an integer between 1 and 999');
+    }
+    if (typeof slug !== 'string' || slug.length === 0 || slug.length > 80 || !SLUG_PATTERN.test(slug)) {
+        fail(filename, 'invalid slug: must be lowercase alphanumeric with hyphens, max 80 characters');
+    }
+    return { meta: { title, description, order, slug }, body: match[2] };
+}
+/**
+ * Level-1 and level-2 headings outside code fences. A recipe may well show a
+ * Markdown file in a fence, and a `## ` inside it is content, not structure.
+ */
+function topHeadings(lines) {
+    const headings = [];
+    let fence = null;
+    lines.forEach((line, index) => {
+        const marker = line.match(/^\s*(```|~~~)/)?.[1];
+        if (marker) {
+            if (fence === null)
+                fence = marker;
+            else if (fence === marker)
+                fence = null;
+            return;
+        }
+        if (fence !== null)
+            return;
+        const m = line.match(/^(#{1,2})\s+(.+?)\s*#*\s*$/);
+        if (m)
+            headings.push({ level: m[1].length, text: m[2], line: index });
+    });
+    return headings;
+}
+function splitSections(body, filename) {
+    const lines = body.split('\n');
+    const headings = topHeadings(lines);
+    const stray = headings.find((h) => h.level === 1);
+    if (stray) {
+        fail(filename, `level-1 heading "# ${stray.text}" is not allowed — the title comes from frontmatter`);
+    }
+    HOWTO_SECTIONS.forEach((expected, i) => {
+        const found = headings[i];
+        if (!found)
+            fail(filename, `missing heading "## ${expected}"`);
+        if (found.text !== expected) {
+            fail(filename, `expected heading "## ${expected}" but found "## ${found.text}"`);
+        }
+    });
+    if (headings.length > HOWTO_SECTIONS.length) {
+        fail(filename, `unexpected heading "## ${headings[HOWTO_SECTIONS.length].text}"`);
+    }
+    const text = (i) => {
+        const start = headings[i].line + 1;
+        const end = i + 1 < headings.length ? headings[i + 1].line : lines.length;
+        return lines.slice(start, end).join('\n').trim();
+    };
+    return { whatYoullDo: text(0), steps: text(1), checkItWorked: text(2) };
+}
+/** Parse one how-to. `filename` only labels errors. */
+export function parseHowToSource(raw, filename) {
+    const { meta, body } = parseFrontmatter(raw, filename);
+    return { ...meta, body, sections: splitSections(body, filename) };
+}
+/**
+ * Every how-to, sorted by `order` (AC-5). Throws on the first bad file — this
+ * runs inside `next build`, so a bad recipe fails the build rather than shipping.
+ */
+export function loadHowTos(dir = HOWTO_DIR) {
+    if (!existsSync(dir))
+        return [];
+    const entries = readdirSync(dir)
+        .filter((f) => f.endsWith('.md'))
+        .sort()
+        .map((filename) => ({
+        filename,
+        howTo: parseHowToSource(readFileSync(resolve(dir, filename), 'utf8'), filename),
+    }));
+    // A property of the set, not of one file, so it lives here (AC-4).
+    const owners = new Map();
+    for (const { filename, howTo } of entries) {
+        const first = owners.get(howTo.slug);
+        if (first !== undefined) {
+            throw new Error(`How-to slug "${howTo.slug}" is used by both "${first}" and "${filename}" — two pages would share one URL`);
+        }
+        owners.set(howTo.slug, filename);
+    }
+    return entries.map((e) => e.howTo).sort((a, b) => a.order - b.order);
+}
+export function getHowTo(slug) {
+    return loadHowTos().find((h) => h.slug === slug);
+}
+//# sourceMappingURL=howto.js.map

package/dist/howto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"howto.js","sourceRoot":"","sources":["../src/howto.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -7,5 +7,6 @@ export { loadPhases, getPhase } from './phases.js';
 export { loadRules } from './rules.js';
 export { loadBoardWorkflow, BOARD_WORKFLOW_PATH } from './recipes.js';
 export { loadTutorials, getTutorial, getSeries, parseTutorialSource } from './tutorials.js';
-export type { Skill, WorkflowTemplate, GuidanceLayer, GlossaryTerm, CapabilityMap, QuestionRendering, PhaseDefinition, Rule, CodeSample, ContentReference, TutorialStep, Tutorial, WidgetKind, WidgetReference } from './types.js';
+export { loadHowTos, getHowTo, parseHowToSource, HOWTO_SECTIONS } from './howto.js';
+export type { Skill, WorkflowTemplate, GuidanceLayer, GlossaryTerm, CapabilityMap, QuestionRendering, PhaseDefinition, Rule, CodeSample, ContentReference, TutorialStep, Tutorial, WidgetKind, WidgetReference, HowTo } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC5F,YAAY,EAAE,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,eAAe,EAAE,IAAI,EAAE,UAAU,EAAE,gBAAgB,EAAE,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC5F,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACpF,YAAY,EAAE,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,eAAe,EAAE,IAAI,EAAE,UAAU,EAAE,gBAAgB,EAAE,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -7,4 +7,5 @@ export { loadPhases, getPhase } from './phases.js';
 export { loadRules } from './rules.js';
 export { loadBoardWorkflow, BOARD_WORKFLOW_PATH } from './recipes.js';
 export { loadTutorials, getTutorial, getSeries, parseTutorialSource } from './tutorials.js';
+export { loadHowTos, getHowTo, parseHowToSource, HOWTO_SECTIONS } from './howto.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC5F,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/types.d.ts

@@ -133,4 +133,22 @@ export interface Tutorial {
     /** Position within `series`. Falls back to `order` when absent (AC-9). */
     seriesOrder?: number;
 }
+/**
+ * One task-shaped page: the steps to do one thing, and how to check it worked
+ * (docs-how-to-recipes). Unlike a tutorial it teaches nothing, so its shape is
+ * fixed to exactly three sections, in order.
+ */
+export interface HowTo {
+    title: string;
+    description: string;
+    order: number;
+    slug: string;
+    /** The full body after the frontmatter. */
+    body: string;
+    sections: {
+        whatYoullDo: string;
+        steps: string;
+        checkItWorked: string;
+    };
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/howto/add-to-existing-project.md

@@ -0,0 +1,55 @@
+---
+title: Add AIDLC to a project you already have
+description: Install AIDLC into an existing repository so your AI assistant starts with real knowledge of the code.
+order: 10
+slug: add-to-existing-project
+---
+
+## What you'll do
+
+Install the CLI and run `init` in your repository. It adds the AIDLC files and writes a
+first description of your code for your AI assistant to read. None of your code is changed.
+
+## Steps
+
+1. Install the CLI once, so `aidlc` is on your path:
+
+   ```bash
+   npm install -g @rasensio/aidlc
+   ```
+
+2. Go to the root of your repository and run `init`. It asks which AI tools you use:
+
+   ```bash
+   cd path/to/your-repo
+   aidlc init
+   ```
+
+   To skip the questions and set up one tool, name it instead:
+
+   ```bash
+   aidlc init --platform claude-code
+   ```
+
+   The other names are `codex`, `copilot`, `cursor`, `kiro` and `windsurf`. To see what
+   `init` would write before it writes anything, add `--dry-run`.
+
+3. Read the two files `init` wrote in `.aidlc/context/`: `architecture.md` and
+   `style-guide.md`. They describe your code, and your assistant reads them before every
+   phase, so fix anything they get wrong now. A mistake here repeats in every piece of work.
+
+4. See the new files, then commit them:
+
+   ```bash
+   git status
+   git add .aidlc .claude CLAUDE.md .gitattributes
+   git commit -m "chore: add AIDLC"
+   ```
+
+   The tool folder and instructions file depend on the tool you chose — for example
+   `.cursor/` for Cursor or `.kiro/` for Kiro. Add whatever `git status` lists as new.
+
+## Check it worked
+
+Run `aidlc status`. You should see `No active lifecycle instances.` That means AIDLC is set
+up and waiting for your first piece of work.

package/howto/change-a-finished-requirement.md

@@ -0,0 +1,60 @@
+---
+title: Change a requirement after its phase is finished
+description: Record a change to finished requirements as an amendment, so the gates, the tasks and the code stay in step.
+order: 30
+slug: change-a-finished-requirement
+---
+
+## What you'll do
+
+Add an amendment to `requirements.md` that says which criteria are retired, which are new,
+and which phase to reopen. Then run `aidlc amend`. Editing the finished file directly leaves
+every gate passing while the requirements and the code disagree.
+
+## Steps
+
+1. Open `.aidlc/state/<instance>/requirements.md`. Change each criterion you are dropping
+   into its retired form, in place — never delete it or reuse its number:
+
+   ```markdown
+   - AC-4 (retired 2026-09-07, superseded by AC-31): export as CSV only
+   ```
+
+   Add each new criterion with the next free number, for example `AC-31`. Then add an
+   amendment section at the end of the file:
+
+   ```markdown
+   ## Amendment 1 — 2026-09-07
+   - **Retires:** AC-4
+   - **Issues:** AC-31
+   - **Reopens:** design
+   - **Reason:** the customer needs JSON as well as CSV
+   ```
+
+   List each criterion by its full name. `AC-4..AC-6` is not read as a range.
+
+2. See what still depends on the criteria you are retiring. This writes nothing:
+
+   ```bash
+   aidlc amend <instance> --impact
+   ```
+
+   It prints a line starting `Reopens:` that names the earliest phase the change must
+   reopen, or `none`. If your `Reopens:` is later than that, move it earlier.
+
+3. Apply the amendment:
+
+   ```bash
+   aidlc amend <instance>
+   ```
+
+   If the work is already in testing or later, add `--confirm`. Reopening that far is
+   costly, and the flag makes you say so.
+
+4. Ask your assistant to continue. It resumes in the reopened phase.
+
+The full rules for amendments are on the {{ref:phase/requirements}} phase page.
+
+## Check it worked
+
+Run `aidlc status`. The instance's phase should now be the one you named in `Reopens:`.

package/howto/keep-aidlc-up-to-date.md

@@ -0,0 +1,56 @@
+---
+title: Keep AIDLC up to date
+description: Update the CLI and your project's AIDLC files, then let doctor tidy what older versions left behind.
+order: 60
+slug: keep-aidlc-up-to-date
+---
+
+## What you'll do
+
+Update the CLI and refresh the AIDLC files in your project with one command, then run
+`doctor` to fix anything older versions left behind. Your own context documents in
+`.aidlc/context/` are not overwritten.
+
+## Steps
+
+1. See what an update would change. This writes nothing:
+
+   ```bash
+   aidlc update --dry-run
+   ```
+
+2. Update:
+
+   ```bash
+   aidlc update
+   ```
+
+   It updates the CLI if a newer version exists, then refreshes the skills and instruction
+   files for each tool you set up. Text you wrote outside the AIDLC markers in files like
+   `CLAUDE.md` is kept.
+
+3. Tidy up. `doctor` applies safe fixes on its own and asks before it changes what git
+   tracks:
+
+   ```bash
+   aidlc doctor
+   ```
+
+   To preview first, run `aidlc doctor --dry-run`. In CI, where nothing can answer a
+   question, use `aidlc doctor --yes`.
+
+4. See what changed, then commit it:
+
+   ```bash
+   git status
+   git add .aidlc
+   git commit -m "chore: update AIDLC"
+   ```
+
+   Also add any tool folder or instructions file `git status` lists, such as `.claude/` or
+   `CLAUDE.md`.
+
+## Check it worked
+
+Run `aidlc update --dry-run` again. You should see `CLI: <version> (already up to date)`, and
+every project file listed under `Unchanged:`.

package/howto/run-two-pieces-of-work.md

@@ -0,0 +1,49 @@
+---
+title: Run two pieces of work at the same time
+description: Give each piece of work its own folder and branch, so two sessions never overwrite each other's files.
+order: 20
+slug: run-two-pieces-of-work
+---
+
+## What you'll do
+
+Start the second piece of work in a separate folder with its own branch. Two AI sessions in
+one folder share every file on disk, so one session's `git add -A` picks up the other's
+half-finished work. A separate folder removes that problem.
+
+## Steps
+
+1. From your main folder, start the new work with `--worktree`:
+
+   ```bash
+   aidlc start bugfix --name login-500 --worktree
+   ```
+
+   AIDLC creates a new branch from `main` and a new folder next to your repository, named
+   after the repository and the work — for example `../your-repo-login-500`. It prints both.
+
+2. Open a new terminal and AI session in that folder:
+
+   ```bash
+   cd ../your-repo-login-500
+   ```
+
+   Do all the work for this piece there. Your first session keeps working in the main folder.
+
+3. If the second piece of work needs no code yet — say, only requirements — you can skip
+   the folder and start it with `--no-code` instead. It stays in your main folder and
+   cannot reach implementation until it has a branch.
+
+4. When the work is merged, remove the folder:
+
+   ```bash
+   git worktree remove ../your-repo-login-500
+   ```
+
+   Git refuses if the folder still has changes that are not committed. That protects work
+   you have not saved.
+
+## Check it worked
+
+Run `aidlc status` from either folder. You should see both pieces of work. The one that
+lives in the other folder shows `(remote worktree)` in the Template column.

package/howto/see-what-work-cost.md

@@ -0,0 +1,52 @@
+---
+title: See what a piece of work cost
+description: Read the AI spend for one piece of work, split by phase, and the cost across all your work.
+order: 50
+slug: see-what-work-cost
+---
+
+## What you'll do
+
+Check that cost capture is on, then read the spend for one piece of work, phase by phase.
+Cost is read from your AI tool's own session records on your machine. Nothing is sent
+anywhere.
+
+## Steps
+
+1. Check that capture is on for your tool:
+
+   ```bash
+   aidlc cost hooks status
+   ```
+
+   `init` turns it on. If your tool shows `not installed`, turn it on:
+
+   ```bash
+   aidlc cost hooks install --platform claude-code
+   ```
+
+   Use the name of your tool in place of `claude-code`.
+
+2. Read the cost of one piece of work:
+
+   ```bash
+   aidlc cost <instance>
+   ```
+
+   You get one line per phase with its cost and time, then a total.
+
+3. See every piece of work at once, or the average per template:
+
+   ```bash
+   aidlc cost
+   aidlc cost --by-template
+   ```
+
+4. To see what a piece of work cost including the bugfixes it later caused, run
+   `aidlc metrics`. Its true-cost figure adds those fixes to the work's own cost.
+
+## Check it worked
+
+Run `aidlc cost <instance>` on a piece of work you have spent time on. You should see a
+dollar amount on its `total:` line. `no data` means capture was off while you worked — turn
+it on as in step 1, and the next session is counted.

package/howto/send-roadmap-to-github.md

@@ -0,0 +1,62 @@
+---
+title: Send your roadmap to GitHub Issues and a Project board
+description: Turn roadmap items into GitHub issues, and optionally keep a Project board's Status column in step with them.
+order: 40
+slug: send-roadmap-to-github
+---
+
+## What you'll do
+
+Copy your roadmap items to GitHub Issues with one command. Items in `backlog/`,
+`in-progress/` and `done/` become issues; `inbox/` and `hold/` stay private. The copy is one
+way: the files in `.aidlc/roadmap/` stay the source, and GitHub follows them. Moving cards
+on a Project board is an optional second part.
+
+## Steps
+
+1. Install the GitHub CLI and sign in. AIDLC uses its login and never asks for a token:
+
+   ```bash
+   gh auth login
+   ```
+
+2. Preview what would change. This writes nothing:
+
+   ```bash
+   aidlc roadmap sync --dry-run
+   ```
+
+   It uses the repository your folder points at. To target another one, add
+   `--repo <owner/name>`.
+
+3. Apply it:
+
+   ```bash
+   aidlc roadmap sync
+   ```
+
+   It shows the plan and asks before it writes. Run it again whenever items move — it
+   updates labels, and closes an issue when its item reaches `done/`.
+
+4. Optional — move a Project board too. Save the workflow AIDLC ships into your repository:
+
+   ```bash
+   aidlc roadmap board-workflow > .github/workflows/aidlc-project-status.yml
+   ```
+
+   Then, in your repository's settings on GitHub:
+
+   - Create a classic token with the `project` and `read:org` scopes (add `repo` if the
+     repository is private). Store it as the repository secret `AIDLC_PROJECT_TOKEN`, with
+     `<your-github-token>` as the value. Never paste it into a file you commit.
+   - Set the repository variable `AIDLC_PROJECT_NUMBER` to your project's number — the
+     digits in its URL.
+
+   The top of the workflow file lists the Status columns it expects and how to rename them.
+
+## Check it worked
+
+Open your repository's Issues tab on GitHub. You should see one issue per roadmap item in
+`backlog/`, `in-progress/` and `done/`, each labelled `aidlc`. If you set up the board, move
+an item and run `aidlc roadmap sync` again: once the workflow run shows in your Actions tab,
+its card should be in the new column.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rasensio/aidlc-content",
-  "version": "1.37.1",
+  "version": "1.39.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,6 +20,7 @@
     "capabilities/",
     "phases/",
     "tutorials/",
+    "howto/",
     "resources/",
     "glossary.yaml"
   ],

package/resources/rules/next-steps.md

@@ -0,0 +1,38 @@
+# The next-steps rule
+
+This file is the only statement of the rule. The phase skills and the review skill point here instead of restating it.
+
+**Never end a phase or a review on a state.** "26 findings", "gate failed" and "phase in progress" tell the user where things are and leave them to work out the path. End instead with what they must decide, what you can fix, and one command.
+
+## When it applies
+
+- At the end of a phase, once its exit criteria are met or it cannot go further without the user.
+- At the end of a review, after the findings file is written.
+- After an `aidlc gate` or `aidlc transition` failure you are reporting.
+
+## Sort what is still open
+
+Put every open item — finding, gap, failed criterion — into exactly one of two groups:
+
+1. **Needs your decision.** Different answers would change an artifact, the scope, or the product: which principal is refused, whether production behaviour changes, what an edge case should return. Ask these through the **Question Protocol** (`.aidlc/resources/rules/question-protocol.md`) — in place when the options fit one line, in `.aidlc/state/<instance>/<phase>-questions.md` when they need context. Name the item each question came from.
+2. **I can fix these.** One correct answer exists and you can apply it: a wrong rule id, a stale sentence, an over-broad permission, a missing test, a task out of order. List them, one line each, and offer to apply them all in one step. Do not ask about each one separately.
+
+An item you cannot place is a decision. Do not quietly fix something that was the user's to choose.
+
+When both groups are empty, say so in one line.
+
+## End with one next command
+
+Close the turn with exactly one next step. It names a command the user can run as written — the real instance name, the real phase or artifact — or, when decisions are open, says to answer them first.
+
+- Decisions are open → answer them first; no command yet.
+- Fixes are offered and not yet applied → the fixes, then the command below.
+- The phase's exit criteria are met → `aidlc transition <instance>`. That is the step that marks the phase complete; `aidlc gate` only checks, and fails on an open phase until it runs.
+- A review finished with no open critical finding → `aidlc transition <instance>` for the phase the artifact belongs to.
+- The instance's last phase is done → the retrospective (**aidlc-retrospective**).
+
+If the CLI printed a `Next steps:` block, use it — it names the fix for each failure it reported.
+
+## What this rule does not do
+
+It changes what you report, not what you write. It adds no writer of `phase-<name>.yaml` or `transitions.log`: the Completion section of each skill still says how the phase is closed.

package/skills/00-overview.md

@@ -92,6 +92,10 @@ On each lifecycle event — `on-instance-start`, `on-phase-enter`, `on-phase-exi
 
 When to ask the user something, how the question is written, and where it is recorded. The rule is in `.aidlc/resources/rules/question-protocol.md`.
 
+## Ending a Phase or a Review
+
+How to end a turn: decisions asked, fixes offered together, and one next command. The rule is in `.aidlc/resources/rules/next-steps.md`.
+
 ## Roadmap Capture
 
 When the user shares an idea tangential to the current work, offer to record it in `.aidlc/roadmap/inbox/` (see **aidlc-roadmap**) and continue the current phase — do not derail into ideation. Capture touches no instance state, so it is safe at any point in any phase.

package/skills/10-ideation.md

@@ -66,3 +66,5 @@ If any ideation option involves sensitive operations (new credentials, infrastru
 ## Completion
 
 When exit criteria are met, update `phase-ideation.yaml` status to `complete` and append a transition record to `transitions.log`.
+
+Then end the turn as **The next-steps rule** (`.aidlc/resources/rules/next-steps.md`) says.

package/skills/20-requirements.md

@@ -85,6 +85,8 @@ If requirements reference sensitive data handling, authentication flows, or acce
 
 When exit criteria are met, update `phase-requirements.yaml` status to `complete` and append a transition record to `transitions.log`.
 
+Then end the turn as **The next-steps rule** (`.aidlc/resources/rules/next-steps.md`) says.
+
 ## Amending a Completed Phase
 
 A completed phase's artifact is changed **only through an amendment**. Editing

package/skills/30-design.md

@@ -89,6 +89,8 @@ You MUST flag these explicitly in the design document and note that implementati
 
 When exit criteria are met, update `phase-design.yaml` status to `complete` and append a transition record to `transitions.log`.
 
+Then end the turn as **The next-steps rule** (`.aidlc/resources/rules/next-steps.md`) says.
+
 **Changing a completed phase's artifact.** Do it only through an amendment — append an
 `## Amendment <n> — YYYY-MM-DD` section to `requirements.md` with `Retires:`, `Issues:`,
 `Reopens:` and `Reason:` bullets, then run `aidlc amend <instance>` (start with `--impact`

package/skills/40-implementation.md

@@ -82,6 +82,8 @@ Never store credentials, API keys, tokens, or passwords in source code or state
 
 When exit criteria are met, update `phase-implementation.yaml` status to `complete` and append a transition record to `transitions.log`.
 
+Then end the turn as **The next-steps rule** (`.aidlc/resources/rules/next-steps.md`) says.
+
 **Changing a completed phase's artifact.** Do it only through an amendment — append an
 `## Amendment <n> — YYYY-MM-DD` section to `requirements.md` with `Retires:`, `Issues:`,
 `Reopens:` and `Reason:` bullets, then run `aidlc amend <instance>` (start with `--impact`

package/skills/50-testing.md

@@ -100,6 +100,8 @@ You MUST describe the action, confirm it targets a safe environment, and wait fo
 
 When exit criteria are met, update `phase-testing.yaml` status to `complete` and append a transition record to `transitions.log`.
 
+Then end the turn as **The next-steps rule** (`.aidlc/resources/rules/next-steps.md`) says.
+
 **Changing a completed phase's artifact.** Do it only through an amendment — append an
 `## Amendment <n> — YYYY-MM-DD` section to `requirements.md` with `Retires:`, `Issues:`,
 `Reopens:` and `Reason:` bullets, then run `aidlc amend <instance>` (start with `--impact`

package/skills/60-deployment.md

@@ -100,3 +100,5 @@ Never deploy without explicit user confirmation. If the user cancels, halt and l
 When exit criteria are met, update `phase-deployment.yaml` status to `complete` and append a transition record to `transitions.log`.
 
 Then check for the **completion moment**: derive the instance's applicable phases (template × scope). If deployment is the last applicable phase, or the next phase is maintenance (maintenance-terminal templates complete on maintenance *entry*, since maintenance is open-ended), this transition completes the instance — run the **aidlc-retrospective** skill now, before any completion cleanup (worktree removal, claim release), and fire the `on-instance-complete` event.
+
+End the turn as **The next-steps rule** (`.aidlc/resources/rules/next-steps.md`) says.

package/skills/70-maintenance.md

@@ -78,3 +78,5 @@ You MUST describe the change, confirm the target environment, and wait for expli
 For maintenance-terminal instances the completion moment already fired on maintenance *entry* (see **aidlc-deployment**) — entering this phase means the instance is complete and its retrospective has run or is pending. Do not fire `on-instance-complete` again when closing the phase.
 
 When exit criteria are met, update `phase-maintenance.yaml` status to `complete` and append a transition record to `transitions.log`. If no retrospective exists for the instance (legacy completion paths), offer to run the **aidlc-retrospective** skill.
+
+Then end the turn as **The next-steps rule** (`.aidlc/resources/rules/next-steps.md`) says.

package/skills/80-review.md

@@ -150,4 +150,11 @@ If the review identifies security vulnerabilities:
 
 ## Completion
 
-After writing the findings file, report the review summary: total findings count by severity, and whether any critical findings block phase transition.
+After writing the findings file, report the review summary in two lines: total findings count by severity, and whether any critical findings block phase transition.
+
+The summary is not the end of the turn. A review's output is mostly decisions, and a count leaves the user to dig them out. Follow **The next-steps rule** (`.aidlc/resources/rules/next-steps.md`):
+
+1. Split the open findings into **needs your decision** and **I can fix these**. A finding whose fix changes what the product does, who it refuses, or what it returns is a decision, whatever its severity.
+2. Ask the decisions through the **Question Protocol** (`.aidlc/resources/rules/question-protocol.md`), each naming its finding id. When the reviewed artifact belongs to a phase, the question file is that phase's `<phase>-questions.md`.
+3. List the fixes one line each, by finding id, and offer to apply them together. When the user accepts, apply them and mark each finding `resolved` in the findings file.
+4. End with one next command — usually `aidlc transition <instance>` once no critical finding is open.