@dtlabs/ai-toolkit 0.1.2

package/bin/cli.js

@@ -0,0 +1,350 @@
+#!/usr/bin/env node
+const fs   = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const readline = require('readline');
+const packageRoot = path.join(__dirname, '..');
+
+// ── colors ────────────────────────────────────────────────────────────────────
+
+const c = {
+  reset:   '\x1b[0m',
+  bold:    '\x1b[1m',
+  dim:     '\x1b[2m',
+  green:   '\x1b[32m',
+  yellow:  '\x1b[33m',
+  blue:    '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan:    '\x1b[36m',
+  red:     '\x1b[31m',
+  gray:    '\x1b[90m',
+  white:   '\x1b[97m',
+};
+
+const clr = (color, text) => `${c[color]}${text}${c.reset}`;
+const bold = (text)        => `${c.bold}${text}${c.reset}`;
+const dim  = (text)        => `${c.dim}${text}${c.reset}`;
+
+function divider(char = '─', len = 60) {
+  return clr('gray', char.repeat(len));
+}
+
+function banner() {
+  console.log();
+  console.log(clr('cyan', '╔══════════════════════════════════════════════════════════╗'));
+  console.log(clr('cyan', '║') + bold(clr('white', '            AI Toolkit  —  Installer                      ')) + clr('cyan', '║'));
+  console.log(clr('cyan', '║') + clr('gray',  `         @dtlabs/ai-toolkit  v${require('../package.json').version.padEnd(22)}`) + clr('cyan', '║'));
+  console.log(clr('cyan', '╚══════════════════════════════════════════════════════════╝'));
+  console.log();
+}
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function fileHash(filePath) {
+  return crypto.createHash('md5').update(fs.readFileSync(filePath)).digest('hex');
+}
+
+function ensureDir(filePath) {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+function askConfirm(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(`${clr('cyan', '?')} ${question} ${dim('(y/N)')} `, (answer) => {
+      rl.close();
+      resolve(/^y(es)?$/i.test(answer.trim()));
+    });
+  });
+}
+
+// ── file enumeration ─────────────────────────────────────────────────────────
+
+function expandMappings(mappings) {
+  const files = [];
+  for (const { src, dest } of mappings) {
+    if (!fs.existsSync(src)) continue;
+    if (fs.statSync(src).isDirectory()) {
+      for (const entry of walkDir(src)) {
+        const rel = path.relative(src, entry);
+        files.push({ src: entry, dest: path.join(dest, rel) });
+      }
+    } else {
+      files.push({ src, dest });
+    }
+  }
+  return files;
+}
+
+function walkDir(dir) {
+  const results = [];
+  for (const item of fs.readdirSync(dir)) {
+    const full = path.join(dir, item);
+    if (fs.statSync(full).isDirectory()) results.push(...walkDir(full));
+    else results.push(full);
+  }
+  return results;
+}
+
+// ── categorize ───────────────────────────────────────────────────────────────
+
+function categorize(files) {
+  return files.map(({ src, dest }) => {
+    if (!fs.existsSync(dest)) return { src, dest, status: 'new' };
+    return fileHash(src) === fileHash(dest)
+      ? { src, dest, status: 'same' }
+      : { src, dest, status: 'modified' };
+  });
+}
+
+// ── version check ─────────────────────────────────────────────────────────────
+
+const TOOLKIT_VERSION = require('../package.json').version;
+const VERSION_FILE    = '.ai-toolkit-version';
+
+function readInstalledVersion(destRoot) {
+  const versionFile = path.join(destRoot, '.claude', VERSION_FILE);
+  if (!fs.existsSync(versionFile)) return null;
+  return fs.readFileSync(versionFile, 'utf8').trim();
+}
+
+function writeInstalledVersion(destRoot) {
+  const versionFile = path.join(destRoot, '.claude', VERSION_FILE);
+  ensureDir(versionFile);
+  fs.writeFileSync(versionFile, TOOLKIT_VERSION, 'utf8');
+}
+
+async function checkVersion(destRoot, force) {
+  const installed = readInstalledVersion(destRoot);
+  if (!installed) return true;
+
+  console.log(divider());
+  console.log(bold('  Version check'));
+  console.log(divider());
+
+  if (installed === TOOLKIT_VERSION) {
+    console.log(`  ${clr('green', '✔')}  Installed : ${clr('green', `v${installed}`)}`);
+    console.log(`  ${clr('blue',  '●')}  Available : ${clr('blue',  `v${TOOLKIT_VERSION}`)}`);
+    console.log(`\n  ${clr('yellow', 'Already up to date.')}`);
+    if (!force) {
+      const ok = await askConfirm('Re-install anyway?');
+      if (!ok) { console.log(`\n  ${clr('gray', 'Aborted. Nothing was changed.')}\n`); process.exit(0); }
+    }
+    return true;
+  }
+
+  console.log(`  ${clr('yellow', '◎')}  Installed : ${clr('yellow', `v${installed}`)}`);
+  console.log(`  ${clr('green',  '▲')}  Available : ${clr('green',  `v${TOOLKIT_VERSION}`)}`);
+  console.log();
+  const ok = await askConfirm(`Update toolkit from ${clr('yellow', `v${installed}`)} to ${clr('green', `v${TOOLKIT_VERSION}`)}?`);
+  if (!ok) {
+    console.log(`\n  ${clr('gray', 'Aborted. Your installation was not changed.')}\n`);
+    process.exit(0);
+  }
+  return true;
+}
+
+// ── install ───────────────────────────────────────────────────────────────────
+
+async function runInstall(label, mappings, force) {
+  const files    = expandMappings(mappings);
+  const entries  = categorize(files);
+
+  const newFiles = entries.filter(e => e.status === 'new');
+  const modified = entries.filter(e => e.status === 'modified');
+  const same     = entries.filter(e => e.status === 'same');
+
+  console.log();
+  console.log(`${bold('📦 Install plan')}  ${clr('gray', '→')}  ${clr('cyan', label)}`);
+  console.log(divider());
+  for (const e of newFiles)  console.log(`  ${clr('green',  '✚')} ${clr('green',  'NEW     ')}  ${dim(path.relative(process.cwd(), e.dest))}`);
+  for (const e of modified)  console.log(`  ${clr('yellow', '~')} ${clr('yellow', 'MODIFIED')}  ${path.relative(process.cwd(), e.dest)}`);
+  for (const e of same)      console.log(`  ${clr('gray',   '=')} ${clr('gray',   'SAME    ')}  ${dim(path.relative(process.cwd(), e.dest))}`);
+  console.log(divider());
+  console.log(
+    `  ${clr('green', `✚ New: ${newFiles.length}`)}` +
+    `  ${clr('yellow', `~ Modified: ${modified.length}`)}` +
+    `  ${clr('gray', `= Unchanged: ${same.length}`)}`
+  );
+  console.log();
+
+  for (const e of newFiles) {
+    ensureDir(e.dest);
+    fs.copyFileSync(e.src, e.dest);
+  }
+
+  if (modified.length === 0) {
+    console.log(`  ${clr('green', '✔')}  All new files copied. No conflicts.\n`);
+    return;
+  }
+
+  if (force) {
+    console.log(`  ${clr('yellow', '⚑')}  --force: overwriting all modified files.`);
+    for (const e of modified) {
+      ensureDir(e.dest);
+      fs.copyFileSync(e.src, e.dest);
+      console.log(`     ${clr('yellow', '↺')} ${dim(path.relative(process.cwd(), e.dest))}`);
+    }
+    return;
+  }
+
+  console.log(`  ${clr('yellow', 'These files differ from the toolkit version — decide for each:')}\n`);
+
+  let overwritten = 0;
+  let skipped = 0;
+
+  for (const e of modified) {
+    const rel = path.relative(process.cwd(), e.dest);
+    const ok = await askConfirm(`  Overwrite  ${clr('yellow', rel)}?`);
+    if (ok) {
+      ensureDir(e.dest);
+      fs.copyFileSync(e.src, e.dest);
+      console.log(`     ${clr('green', '✔')} Overwritten\n`);
+      overwritten++;
+    } else {
+      console.log(`     ${clr('gray', '✖')} Kept as-is\n`);
+      skipped++;
+    }
+  }
+
+  console.log(divider());
+  console.log(
+    `  ${clr('green', `✔ Overwritten: ${overwritten}`)}` +
+    `  ${clr('gray',  `✖ Kept as-is: ${skipped}`)}\n`
+  );
+}
+
+// ── Matt Pocock skills ───────────────────────────────────────────────────────
+
+function isMattPocockInstalled() {
+  const homedir = require('os').homedir();
+  // 'grilling' is a skill exclusive to Matt Pocock's package — not included in this toolkit
+  const pathsToCheck = [
+    path.join(homedir, '.claude', 'skills', 'grilling', 'SKILL.md'),
+    path.join(process.cwd(), '.claude', 'skills', 'grilling', 'SKILL.md'),
+  ];
+  return pathsToCheck.some(p => fs.existsSync(p));
+}
+
+async function installMattPocock() {
+  const { execSync } = require('child_process');
+  console.log(`\n  ${clr('cyan', '↓')}  Running: ${dim('npx skills@latest add mattpocock/skills')}\n`);
+  try {
+    execSync('npx skills@latest add mattpocock/skills', { stdio: 'inherit' });
+    console.log(`\n  ${clr('green', '✔')}  Matt Pocock skills installed successfully.\n`);
+  } catch (err) {
+    console.error(`\n  ${clr('red', '✖')}  Install failed: ${err.message}`);
+    console.error(`     Run manually: ${dim('npx skills@latest add mattpocock/skills')}\n`);
+  }
+}
+
+async function askMattPocock() {
+  const installed = isMattPocockInstalled();
+
+  console.log(divider());
+  console.log(bold('  Matt Pocock Skills'));
+  console.log(divider());
+  console.log(`  ${dim('Includes: define-feature, grilling, TDD, prototype, handoff, and more.')}`);
+  console.log();
+
+  if (!installed) {
+    console.log(`  ${clr('gray', '○')}  Status : ${clr('gray', 'not installed')}\n`);
+    const ok = await askConfirm('Install Matt Pocock\'s skills now?');
+    if (ok) await installMattPocock();
+    else console.log(`\n  ${clr('gray', 'Skipped. Install later with: npx skills@latest add mattpocock/skills')}\n`);
+    return;
+  }
+
+  console.log(`  ${clr('green', '✔')}  Status : ${clr('green', 'installed')}\n`);
+  const ok = await askConfirm('Re-install / update Matt Pocock skills?');
+  if (ok) await installMattPocock();
+  else console.log(`  ${clr('gray', 'Skipped.')}\n`);
+}
+
+// ── entry points ──────────────────────────────────────────────────────────────
+
+async function installLocal(targetDir, force) {
+  banner();
+  targetDir = path.resolve(process.cwd(), targetDir || '.');
+  console.log(`  ${clr('cyan', '▸')}  Target: ${bold(targetDir)}\n`);
+  await checkVersion(targetDir, force);
+  const mappings = [
+    { src: path.join(packageRoot, '.claude'),   dest: path.join(targetDir, '.claude') },
+    { src: path.join(packageRoot, 'docs'),      dest: path.join(targetDir, 'docs') },
+    { src: path.join(packageRoot, 'CLAUDE.md'), dest: path.join(targetDir, 'CLAUDE.md') },
+  ];
+  await runInstall(`local project`, mappings, force);
+  writeInstalledVersion(targetDir);
+  console.log(`  ${clr('green', '✔')}  ${bold('Install complete.')}\n`);
+  await askMattPocock();
+  console.log(divider());
+  console.log(`\n  ${bold('Next steps:')}`);
+  console.log(`  ${clr('cyan', '1.')} Run ${clr('cyan', '/init-agents')} to generate AGENTS.md`);
+  console.log(`  ${clr('cyan', '2.')} Create a feature doc and run ${clr('cyan', '/implement-feature')}`);
+  console.log();
+}
+
+async function installGlobal(force) {
+  banner();
+  try {
+    const homedir = require('os').homedir();
+    const target  = path.join(homedir, '.claude');
+    console.log(`  ${clr('cyan', '▸')}  Target: ${bold(target)}  ${clr('gray', '(global Claude folder)')}\n`);
+    await checkVersion(target, force);
+    const mappings = [
+      { src: path.join(packageRoot, '.claude', 'agents'),   dest: path.join(target, 'agents') },
+      { src: path.join(packageRoot, '.claude', 'skills'),   dest: path.join(target, 'skills') },
+      { src: path.join(packageRoot, '.claude', 'commands'), dest: path.join(target, 'commands') },
+      { src: path.join(packageRoot, 'docs'),                dest: path.join(target, 'docs') },
+      { src: path.join(packageRoot, 'CLAUDE.md'),           dest: path.join(target, 'CLAUDE.md') },
+    ];
+    await runInstall('global Claude folder', mappings, force);
+    writeInstalledVersion(target);
+    console.log(`  ${clr('green', '✔')}  ${bold('Global install complete.')}\n`);
+    await askMattPocock();
+    console.log(divider());
+    console.log(`\n  ${bold('Next steps:')}`);
+    console.log(`  ${clr('cyan', '1.')} The toolkit is now available in all your projects`);
+    console.log(`  ${clr('cyan', '2.')} Open any project and run ${clr('cyan', '/init-agents')}`);
+    console.log();
+  } catch (err) {
+    console.error(`\n  ${clr('red', '✖')}  Global install failed: ${err.message}\n`);
+    process.exit(1);
+  }
+}
+
+function help() {
+  banner();
+  console.log(`  ${bold('Usage:')}`);
+  console.log(`    ${clr('cyan', 'ai-toolkit')}                      Install into current directory`);
+  console.log(`    ${clr('cyan', 'ai-toolkit')} ${clr('yellow', '--local <dir>')}       Install into target directory`);
+  console.log(`    ${clr('cyan', 'ai-toolkit')} ${clr('yellow', '--global')}             Install into ~/.claude (global)`);
+  console.log(`    ${clr('gray',  '                     --force')}       Overwrite all files without prompting`);
+  console.log();
+}
+
+async function main() {
+  const argv  = process.argv.slice(2);
+  const force = argv.includes('--force');
+
+  if (argv.length === 0 || (argv.length === 1 && argv[0] === '--force')) {
+    await installLocal('.', force);
+    return;
+  }
+
+  if (argv[0] === '--local') {
+    await installLocal(argv[1] || '.', force);
+  } else if (argv[0] === '--global') {
+    await installGlobal(force);
+  } else if (argv[0] === 'help' || argv[0] === '--help') {
+    help();
+  } else if (fs.existsSync(argv[0]) && fs.statSync(argv[0]).isDirectory()) {
+    await installLocal(argv[0], force);
+  } else {
+    help();
+    process.exit(1);
+  }
+}
+
+main();

package/docs/installation.md

@@ -0,0 +1,80 @@
+# Installation
+
+The toolkit is published to the **public npm registry** under the `@dtlabs` organization.
+
+- **Package**: `@dtlabs/ai-toolkit`
+- **Registry**: `https://registry.npmjs.org/`
+
+No authentication setup required — it is a public package.
+
+---
+
+## Usage
+
+### Local installation (default)
+
+Copies `.claude/`, `docs/`, and `CLAUDE.md` into the current directory:
+
+```bash
+npx @dtlabs/ai-toolkit
+```
+
+Target a different directory:
+
+```bash
+npx @dtlabs/ai-toolkit --local /path/to/project
+```
+
+Overwrite existing files without confirmation:
+
+```bash
+npx @dtlabs/ai-toolkit --local . --force
+```
+
+### Global installation
+
+Merges `.claude/agents`, `.claude/skills`, `docs/`, and `CLAUDE.md` into `~/.claude/`:
+
+```bash
+npm install -g @dtlabs/ai-toolkit
+ai-toolkit --global
+```
+
+Force overwrite:
+
+```bash
+ai-toolkit --global --force
+```
+
+### What gets copied where
+
+| Mode | Source (in package) | Destination |
+|---|---|---|
+| Local | `.claude/` | `<target>/.claude/` |
+| Local | `docs/` | `<target>/docs/` |
+| Local | `CLAUDE.md` | `<target>/CLAUDE.md` |
+| Global | `.claude/agents/` | `~/.claude/agents/` |
+| Global | `.claude/skills/` | `~/.claude/skills/` |
+| Global | `.claude/commands/` | `~/.claude/commands/` |
+| Global | `docs/` | `~/.claude/docs/` |
+| Global | `CLAUDE.md` | `~/.claude/CLAUDE.md` |
+
+> The asymmetry is intentional: locally you mirror the package layout, globally you merge into Claude Code's standard folder structure.
+
+---
+
+## Verify installation
+
+```bash
+npm view @dtlabs/ai-toolkit version
+```
+
+---
+
+## Publishing a new version
+
+```bash
+npm login                        # authenticate with your npmjs.com account
+npm version patch                # bump version (patch / minor / major)
+npm publish --access public      # --access public is required for scoped packages
+```

package/docs/pricing.md

@@ -0,0 +1,99 @@
+# AI Model Pricing Reference
+
+> This file contains LLM pricing data used for cost estimation in feature delivery and assessment pipelines.
+> Update manually when provider pricing changes.
+>
+> **Last updated:** 2026-07-10
+> **Source:** https://platform.claude.com/docs/about-claude/pricing
+
+---
+
+## Cost estimation parameters
+
+| Parameter | Value | Notes |
+|-----------|-------|-------|
+| Input token share | 80% | Assumed proportion of total tokens used as input |
+| Output token share | 20% | Assumed proportion of total tokens used as output |
+
+These two parameters drive the blended cost formula used by all pipeline agents:
+
+```
+blended_cost = tokens × (0.80 × input_price_per_token + 0.20 × output_price_per_token)
+```
+
+Adjust the percentages here if empirical data suggests a different ratio.
+
+---
+
+## Anthropic — Claude models
+
+Prices are in **USD per million tokens ($/MTok)**.
+
+### Standard API
+
+| Model | Input ($/MTok) | Output ($/MTok) | Notes |
+|-------|---------------|----------------|-------|
+| Claude Fable 5 | $10.00 | $50.00 | |
+| Claude Mythos 5 | $10.00 | $50.00 | |
+| Claude Opus 4.8 | $5.00 | $25.00 | |
+| Claude Opus 4.7 | $5.00 | $25.00 | |
+| Claude Opus 4.6 | $5.00 | $25.00 | |
+| Claude Opus 4.5 | $5.00 | $25.00 | |
+| Claude Sonnet 5 | $2.00 | $10.00 | Promotional until 2026-08-31 |
+| Claude Sonnet 5 | $3.00 | $15.00 | From 2026-09-01 |
+| Claude Sonnet 4.6 | $3.00 | $15.00 | |
+| Claude Sonnet 4.5 | $3.00 | $15.00 | |
+| Claude Haiku 4.5 | $1.00 | $5.00 | |
+
+### Prompt caching add-on ($/MTok on top of input price)
+
+| Cache type | Write surcharge |
+|------------|----------------|
+| 5-minute cache write | +25% of input price |
+| 1-hour cache write | +100% of input price |
+| Cache read (hit) | −80% of input price |
+
+### Batch API
+
+50% discount on both input and output prices for all models.
+
+### Tool use
+
+| Tool | Cost |
+|------|------|
+| Web search | $10.00 / 1,000 searches |
+| Code execution | Free (first 1,550 hours/month), then $0.05/hour |
+
+---
+
+## Blended unit cost reference
+
+Pre-computed blended cost per 1,000 tokens using the 80/20 split above.
+Use these values for quick estimates without recalculating.
+
+| Model | Input ($/MTok) | Output ($/MTok) | Blended ($/1k tokens) |
+|-------|---------------|----------------|-----------------------|
+| Claude Fable 5 | $10.00 | $50.00 | $0.018000 |
+| Claude Opus 4.8 | $5.00 | $25.00 | $0.009000 |
+| Claude Sonnet 5 (promo) | $2.00 | $10.00 | $0.003600 |
+| Claude Sonnet 5 | $3.00 | $15.00 | $0.005400 |
+| Claude Sonnet 4.5/4.6 | $3.00 | $15.00 | $0.005400 |
+| Claude Haiku 4.5 | $1.00 | $5.00 | $0.001800 |
+
+> Formula: `blended = (input × 0.80 + output × 0.20) / 1,000`
+
+---
+
+## Adding other providers
+
+To add pricing for another provider (OpenAI, Google, Azure, etc.), append a new section following the same structure:
+
+```markdown
+## {Provider name} — {Model family}
+
+| Model | Input ($/MTok) | Output ($/MTok) | Notes |
+|-------|---------------|----------------|-------|
+| ...   | ...            | ...             | ...   |
+```
+
+Update the **Blended unit cost reference** table accordingly.

package/docs/procedures/approval-gates.md

@@ -0,0 +1,142 @@
+# Procedure: Approval Gates
+
+Two mandatory approval gates block the pipeline. **No phase after a gate may start without a
+verified, written approval record.** This is a hard stop — not a suggestion.
+
+---
+
+## Gate 1 — Docs Approval (after validation passes)
+
+### Step 1 — Present documents
+
+Show the user a summary of the generated documents:
+- `{PREFIX}-Requirements.md` — N use cases, N business rules, N acceptance criteria
+- `{PREFIX}-Tech-Spec.md` — N endpoints, N entities, N new files
+- `{PREFIX}-Validation-Report.md` — N gaps found / 0 gaps
+
+### Step 2 — Request explicit sign-off
+
+Use `AskUserQuestion` with this exact phrasing:
+
+> **"Please review the documents above and choose one of the options below.
+> The pipeline CANNOT continue until you make a selection."**
+
+Options:
+- **"Approve — proceed to Work Breakdown"**
+- **"Request changes"** — describe what to change; the pipeline re-runs affected agents, re-validates, and returns here (max 2 revision cycles)
+- **"Approve with notes"** — accepted with comments recorded in the approval file
+
+### Step 3 — Write approval record BEFORE continuing
+
+Immediately after the user approves, write `{PREFIX}-Approvals.md`:
+
+```markdown
+# Approval Record — {PREFIX}
+
+## Gate 1 — Document Approvals
+
+| Document | Status | Date | Notes |
+|----------|--------|------|-------|
+| {PREFIX}-Requirements.md | ✅ Approved | {date} | {notes or —} |
+| {PREFIX}-Tech-Spec.md | ✅ Approved | {date} | {notes or —} |
+| {PREFIX}-Validation-Report.md | ✅ Approved | {date} | {notes or —} |
+
+## Approval History
+
+| Cycle | Action | Date | Details |
+|-------|--------|------|---------|
+| 1 | {action} | {date} | {details} |
+```
+
+### Step 4 — Verify the file was written
+
+Read back `{PREFIX}-Approvals.md` and confirm it contains the Gate 1 section with ✅ status.
+If the file is missing or incomplete, **do not proceed** — write it again.
+
+---
+
+## Gate 2 — Work Breakdown Approval (after WB generation)
+
+### Step 1 — Pre-condition check (MANDATORY)
+
+**Before doing anything in this gate**, read `{PREFIX}-Approvals.md` and verify it contains
+"Gate 1 — Document Approvals" with ✅ status on all three documents.
+
+If Gate 1 approval is missing:
+```
+⛔ HARD STOP — Gate 1 approval not found in {PREFIX}-Approvals.md.
+   Work Breakdown Approval cannot proceed without prior document approval.
+   Returning to Gate 1.
+```
+Go back and execute Gate 1 before continuing.
+
+### Step 2 — Present Work Breakdown
+
+Show key metrics:
+- User Stories: N (US-01 ÷ US-NN)
+- Total tasks: N (DB:N, BE:N, FE:N, INFRA:N, TEST:N)
+- Implementation phases: N
+- Human estimate: ~Nh | Agent estimate: ~Nh Nmin
+- Reference: `{PREFIX}-Effort-Estimate.md` for full detail
+
+### Step 3 — Request explicit sign-off
+
+Use `AskUserQuestion`:
+
+> **"Please review the Work Breakdown above and choose one of the options below.
+> Implementation CANNOT start until you approve."**
+
+Options:
+- **"Approve — start implementation"**
+- **"Request changes"** — re-run `generate-work-breakdown` with feedback (max 2 cycles)
+- **"Approve with notes"** — accepted with comments recorded
+
+### Step 4 — Update approval record BEFORE starting implementation
+
+Append to `{PREFIX}-Approvals.md`:
+
+```markdown
+## Gate 2 — Work Breakdown Approval
+
+| Document | Status | Date | Notes |
+|----------|--------|------|-------|
+| {PREFIX}-Work-Breakdown.md | ✅ Approved | {date} | {N} tasks, {N} phases |
+```
+
+### Step 5 — Verify before proceeding
+
+Read back `{PREFIX}-Approvals.md` and confirm Gate 2 section is present with ✅ status.
+If missing, **do not start implementation** — write it again.
+
+---
+
+## Pre-condition check for implementation (Phase 6)
+
+**At the very start of Phase 6 (before creating the branch or writing any code)**,
+read `{PREFIX}-Approvals.md` and verify BOTH gates are present and approved:
+
+```
+✅ Gate 1 — Document Approvals: Requirements ✅ | Tech-Spec ✅ | Validation ✅
+✅ Gate 2 — Work Breakdown Approval: Work-Breakdown ✅
+```
+
+If either gate is missing or shows a non-✅ status:
+```
+⛔ HARD STOP — Required approval missing in {PREFIX}-Approvals.md.
+   Gate {N} approval is required before implementation can start.
+   Returning to Gate {N}.
+```
+
+This check is the last line of defence. Even if the PM believes it ran the gates, it must
+verify the file on disk before touching the codebase.
+
+---
+
+## Rules
+
+- **Gates are hard stops, not suggestions** — the PM must use `AskUserQuestion` and wait for a response; it cannot auto-approve or assume approval
+- **Write the approval file before continuing** — the file is the contract; if it doesn't exist, the gate did not happen
+- **Verify the file after writing** — read it back to confirm
+- **Pre-condition check at Phase 6** — always verify both gates on disk before any code change
+- **Max 2 revision cycles** per gate — if still not approved after 2 cycles, stop and escalate to user
+- **Log every gate event** in the process log (gate opened, user response, file written, pre-condition check result)