@rasensio/aidlc-content 1.38.0 → 1.40.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.38.0",
+  "version": "1.40.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,6 +20,7 @@
     "capabilities/",
     "phases/",
     "tutorials/",
+    "howto/",
     "resources/",
     "glossary.yaml"
   ],

package/skills/03-entry-point.md

@@ -65,6 +65,7 @@ If `.aidlc/state/` is empty or missing, offer just three options: start somethin
 | Answer pending questions | Open the question file, re-render its open questions per the **Question Protocol** (`.aidlc/resources/rules/question-protocol.md`), record each answer in the file, then fold them into the artifact they were gathered for |
 | Triage the inbox | Follow the **aidlc-roadmap** skill (triage flow) |
 | Browse / promote the roadmap | Follow the **aidlc-roadmap** skill (browse/promote flow) |
+| Start a roadmap item in a new worktree | Follow the **aidlc-roadmap** skill (**Promote into a new worktree**). It ends by handing off to a new session; do not start the phase here |
 | Show status | Summarize each instance from its state files — name, template, current phase, completion %, and whether it looks stalled. When the roadmap is non-empty, append the per-status counts (e.g. "roadmap: 3 inbox, 5 backlog, 12 done") |
 | Review an artifact | Follow the **aidlc-review** skill |
 | Help / getting started | Follow the **aidlc-getting-started** skill |

package/skills/04-roadmap.md

@@ -3,7 +3,7 @@ name: aidlc-roadmap
 description: Captures roadmap items into .aidlc/roadmap/inbox/ at any moment — no instance, claim, or phase required — and browses, triages, promotes, or drops them
 phase: ideation
 priority: 90
-trigger: When the user says "idea:", asks to capture/record an idea or roadmap item, wants to browse the roadmap, or wants to triage, promote, or drop an item
+trigger: When the user says "idea:", asks to capture/record an idea or roadmap item, wants to browse the roadmap, or wants to triage, promote, or drop an item, or asks to start a roadmap item in a new worktree
 native_mode_hint:
   claude-code: >-
     This skill is an interactive inbox, not a phase artifact. Do not enter
@@ -170,6 +170,20 @@ Promotion is where the roadmap meets the lifecycle:
 5. Seed the instance with the item: Full scope → the item is raw material the Ideation phase refines into that phase's required artifact (`idea.md` for the feature templates, `research-question.md` for `spike`); Standard scope → the item is input context for Requirements.
 6. Set `promoted_to: <instance-name>`, move the file to `in-progress/`, and append the `history` entry.
 
+### Promote into a new worktree
+
+When the user asks for a worktree ("create a new worktree for roadmap `<file>`"), they want to work on the item in a separate session — for example one per pane of a session manager. Run the promote steps above with these changes, and do not stop to ask anything the item and config already answer:
+
+1. **Find the item** by file name, `id`, or title, in `backlog/` or `inbox/`. Asking for a worktree counts as choosing to skip triage. When more than one item matches, list them and ask which one.
+2. **Instance name**: the item's file name without its date prefix and extension (the item filed as `20260929-say-what-to-do-next` becomes `say-what-to-do-next`). Template and scope come from the config defaults, unless the item or the user names them.
+3. **Create the instance with** `aidlc start <template> --name <name> --scope <scope> --worktree --non-interactive`. Take the worktree path from the `Worktree:` line it prints. That command creates the branch and the worktree and fires `on-instance-start`; do not repeat any of it by hand.
+4. **Seed the instance inside the worktree** (`<worktree>/.aidlc/state/<name>/`), not the primary checkout. Copy the item into it per step 5 above. Keep the roadmap move (step 6) in the primary checkout, as always.
+5. **Hand off. Do not start the phase in this session.** The work belongs to the new session. End with the exact command that opens it:
+   ```
+   cd <worktree> && claude "/aidlc-continue <name>"
+   ```
+   For Codex, swap `claude` for `codex`. If the user names a session manager, give them the worktree path to point it at.
+
 When the instance completes, the `roadmap-done` lifecycle action moves the item to `done/` on its own — do not do it by hand, and do not remove that action to do it manually.
 
 ## Drop