@phuc1403/musketeer 0.8.0 → 0.10.0

package/template/.claude/skills/architecture-characteristic-writer/scripts/ranking-table.cjs

@@ -1,171 +1,171 @@
-#!/usr/bin/env node
-// Scaffolds and repairs the architecture-characteristics ranking table.
-//
-//   scaffold  write a blank ranking holding every catalog characteristic
-//   fix       renumber the Order column and rebuild every "Above X:" prefix
-//             from the row order as it now stands, keeping the justifications
-//
-// Ranking ORDER and justification prose are the architect's work. Everything
-// this script touches — which characteristics appear, the numbering, which row
-// each reason compares against — is mechanical, so no one has to transcribe it.
-//
-// Run `fix` after moving rows. A prefix left naming the wrong row is the usual
-// defect after a reorder, and regenerating them makes it impossible.
-
-const fs = require('fs');
-const path = require('path');
-
-const {
-  loadCatalog,
-  normalise,
-  locateTable,
-  splitCells,
-  isSeparator,
-  RANKING_HEADER,
-} = require('../../../hooks/lib/characteristics/checker.cjs');
-
-const DEFAULT_FILE = 'docs/architecture-characteristics-ranking.md';
-
-// The validation hook resolves the ranking against CLAUDE_PROJECT_DIR. Resolve
-// against the same root, or running this from a subdirectory would quietly
-// write a second ranking somewhere the hook never looks at.
-const projectRoot = () => process.env.CLAUDE_PROJECT_DIR || process.cwd();
-const PLACEHOLDER = '{why}';
-const HEADING = '# Architecture Characteristics Ranking';
-
-const PREAMBLE = [
-  HEADING,
-  '',
-  'All characteristics in priority order. The top 7 feed the worksheet in',
-  '`architecture-characteristics.md`.',
-  '',
-  '<!-- Reason = why this row outranks the row directly BELOW it. Comparative, never a description.',
-  '     Keep the "Above {next characteristic}:" prefix and replace {why} with the justification.',
-  '     Both sides must appear: what this row protects, and what the row below gives up.',
-  '     State WHY the system needs it, meaning the business driver or risk.',
-  '     Never name the mechanism: no patterns, libraries, components, or tactics.',
-  '',
-  '     Move rows freely, then run scripts/ranking-table.cjs fix to renumber and',
-  '     rebuild every prefix. Do not hand-maintain the numbering or the prefixes. -->',
-  '',
-];
-
-const die = (msg) => {
-  process.stderr.write(`${msg}\n`);
-  process.exit(1);
-};
-
-// Builds the three table lines plus data rows for the given ordered names,
-// pairing each row with the justification supplied for it.
-function render(order, justifications) {
-  const rows = order.map((name, i) => {
-    const last = i === order.length - 1;
-    const reason = last ? '—' : `Above ${order[i + 1]}: ${justifications[i] || PLACEHOLDER}`;
-    return `| ${i + 1} | ${name} | ${reason} |`;
-  });
-  return ['| Order | Characteristic | Reason |', '|---|---|---|', ...rows];
-}
-
-// Drops an "Above X:" prefix and a lone em dash, leaving the justification the
-// author actually wrote.
-function justificationOf(reason) {
-  const text = String(reason).trim();
-  if (/^[—-]$/.test(text)) return '';
-  const m = text.match(/^above\s+[^:]+:\s*(.*)$/i);
-  return (m ? m[1] : text).trim();
-}
-
-function scaffold(argv) {
-  const out = argv.out || DEFAULT_FILE;
-  const target = path.resolve(projectRoot(), out);
-
-  if (fs.existsSync(target) && !argv.force) {
-    die(`${out} already exists. Run fix to repair it, or pass --force to start over.`);
-  }
-
-  const { catalog } = loadCatalog(argv.catalog);
-  fs.mkdirSync(path.dirname(target), { recursive: true });
-  fs.writeFileSync(target, [...PREAMBLE, ...render(catalog, []), ''].join('\n'), 'utf8');
-
-  process.stdout.write(
-    `Wrote ${out} with ${catalog.length} characteristics in catalog order.\n` +
-      'Reorder the rows, replace every {why}, then run fix.\n'
-  );
-}
-
-function fix(argv) {
-  const file = argv.file || DEFAULT_FILE;
-  const target = path.resolve(projectRoot(), file);
-
-  if (!fs.existsSync(target)) die(`${file} does not exist. Run scaffold first.`);
-
-  const original = fs.readFileSync(target, 'utf8');
-  const eol = original.includes('\r\n') ? '\r\n' : '\n';
-  const lines = original.split(/\r?\n/);
-
-  const bounds = locateTable(lines, RANKING_HEADER);
-  if (!bounds) die(`${file} holds no table with a "| Order | Characteristic | Reason |" header row.`);
-
-  const table = lines.slice(bounds.start, bounds.end);
-  const data = table.filter((l) => {
-    const c = splitCells(l);
-    return c.length >= 3 && !isSeparator(c) && !/^order$/i.test(c[0]);
-  });
-
-  if (!data.length) die(`${file} holds no ranking rows to fix.`);
-
-  const order = data.map((l) => normalise(splitCells(l)[1]));
-  const justifications = data.map((l) => justificationOf(splitCells(l)[2]));
-
-  const { catalog } = loadCatalog(argv.catalog);
-  const unknown = order.filter((n) => !catalog.includes(n));
-  if (unknown.length) die(`${file} names characteristics absent from the catalog: ${unknown.join(', ')}`);
-
-  const rebuilt = render(order, justifications);
-  const next = [...lines.slice(0, bounds.start), ...rebuilt, ...lines.slice(bounds.end)];
-  const updated = next.join(eol);
-
-  // Reported whether or not anything moved: a scaffold is already correct and
-  // still has every justification left to write.
-  const blank = justifications.filter((j, i) => i < justifications.length - 1 && (!j || j === PLACEHOLDER)).length;
-  const outstanding = blank ? `${blank} row(s) still need a justification in place of ${PLACEHOLDER}.\n` : '';
-
-  if (updated === original) {
-    process.stdout.write(`${file} is already correct.\n${outstanding}`);
-    return;
-  }
-
-  fs.writeFileSync(target, updated, 'utf8');
-
-  const repaired = data.filter((l, i) => splitCells(l)[2] !== splitCells(rebuilt[i + 2])[2]).length;
-  const renumbered = data.filter((l, i) => splitCells(l)[0] !== String(i + 1)).length;
-
-  process.stdout.write(
-    `Fixed ${file}: renumbered ${renumbered} row(s), rebuilt ${repaired} reason(s).\n${outstanding}`
-  );
-}
-
-function main() {
-  const [command, ...rest] = process.argv.slice(2);
-  const argv = { force: false };
-
-  for (let i = 0; i < rest.length; i += 1) {
-    const flag = rest[i];
-    if (flag === '--force') argv.force = true;
-    else if (flag === '--out') argv.out = rest[(i += 1)];
-    else if (flag === '--file') argv.file = rest[(i += 1)];
-    else if (flag === '--catalog') argv.catalog = rest[(i += 1)];
-    else die(`unknown argument: ${flag}`);
-  }
-
-  try {
-    if (command === 'scaffold') return scaffold(argv);
-    if (command === 'fix') return fix(argv);
-  } catch (err) {
-    die(err.message);
-  }
-
-  die('usage: ranking-table.cjs scaffold [--out <path>] [--force] | fix [--file <path>]');
-}
-
-main();
+#!/usr/bin/env node
+// Scaffolds and repairs the architecture-characteristics ranking table.
+//
+//   scaffold  write a blank ranking holding every catalog characteristic
+//   fix       renumber the Order column and rebuild every "Above X:" prefix
+//             from the row order as it now stands, keeping the justifications
+//
+// Ranking ORDER and justification prose are the architect's work. Everything
+// this script touches — which characteristics appear, the numbering, which row
+// each reason compares against — is mechanical, so no one has to transcribe it.
+//
+// Run `fix` after moving rows. A prefix left naming the wrong row is the usual
+// defect after a reorder, and regenerating them makes it impossible.
+
+const fs = require('fs');
+const path = require('path');
+
+const {
+  loadCatalog,
+  normalise,
+  locateTable,
+  splitCells,
+  isSeparator,
+  RANKING_HEADER,
+} = require('../../../hooks/lib/characteristics/checker.cjs');
+
+const DEFAULT_FILE = 'docs/architecture-characteristics-ranking.md';
+
+// The validation hook resolves the ranking against CLAUDE_PROJECT_DIR. Resolve
+// against the same root, or running this from a subdirectory would quietly
+// write a second ranking somewhere the hook never looks at.
+const projectRoot = () => process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const PLACEHOLDER = '{why}';
+const HEADING = '# Architecture Characteristics Ranking';
+
+const PREAMBLE = [
+  HEADING,
+  '',
+  'All characteristics in priority order. The top 7 feed the worksheet in',
+  '`architecture-characteristics.md`.',
+  '',
+  '<!-- Reason = why this row outranks the row directly BELOW it. Comparative, never a description.',
+  '     Keep the "Above {next characteristic}:" prefix and replace {why} with the justification.',
+  '     Both sides must appear: what this row protects, and what the row below gives up.',
+  '     State WHY the system needs it, meaning the business driver or risk.',
+  '     Never name the mechanism: no patterns, libraries, components, or tactics.',
+  '',
+  '     Move rows freely, then run scripts/ranking-table.cjs fix to renumber and',
+  '     rebuild every prefix. Do not hand-maintain the numbering or the prefixes. -->',
+  '',
+];
+
+const die = (msg) => {
+  process.stderr.write(`${msg}\n`);
+  process.exit(1);
+};
+
+// Builds the three table lines plus data rows for the given ordered names,
+// pairing each row with the justification supplied for it.
+function render(order, justifications) {
+  const rows = order.map((name, i) => {
+    const last = i === order.length - 1;
+    const reason = last ? '—' : `Above ${order[i + 1]}: ${justifications[i] || PLACEHOLDER}`;
+    return `| ${i + 1} | ${name} | ${reason} |`;
+  });
+  return ['| Order | Characteristic | Reason |', '|---|---|---|', ...rows];
+}
+
+// Drops an "Above X:" prefix and a lone em dash, leaving the justification the
+// author actually wrote.
+function justificationOf(reason) {
+  const text = String(reason).trim();
+  if (/^[—-]$/.test(text)) return '';
+  const m = text.match(/^above\s+[^:]+:\s*(.*)$/i);
+  return (m ? m[1] : text).trim();
+}
+
+function scaffold(argv) {
+  const out = argv.out || DEFAULT_FILE;
+  const target = path.resolve(projectRoot(), out);
+
+  if (fs.existsSync(target) && !argv.force) {
+    die(`${out} already exists. Run fix to repair it, or pass --force to start over.`);
+  }
+
+  const { catalog } = loadCatalog(argv.catalog);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, [...PREAMBLE, ...render(catalog, []), ''].join('\n'), 'utf8');
+
+  process.stdout.write(
+    `Wrote ${out} with ${catalog.length} characteristics in catalog order.\n` +
+      'Reorder the rows, replace every {why}, then run fix.\n'
+  );
+}
+
+function fix(argv) {
+  const file = argv.file || DEFAULT_FILE;
+  const target = path.resolve(projectRoot(), file);
+
+  if (!fs.existsSync(target)) die(`${file} does not exist. Run scaffold first.`);
+
+  const original = fs.readFileSync(target, 'utf8');
+  const eol = original.includes('\r\n') ? '\r\n' : '\n';
+  const lines = original.split(/\r?\n/);
+
+  const bounds = locateTable(lines, RANKING_HEADER);
+  if (!bounds) die(`${file} holds no table with a "| Order | Characteristic | Reason |" header row.`);
+
+  const table = lines.slice(bounds.start, bounds.end);
+  const data = table.filter((l) => {
+    const c = splitCells(l);
+    return c.length >= 3 && !isSeparator(c) && !/^order$/i.test(c[0]);
+  });
+
+  if (!data.length) die(`${file} holds no ranking rows to fix.`);
+
+  const order = data.map((l) => normalise(splitCells(l)[1]));
+  const justifications = data.map((l) => justificationOf(splitCells(l)[2]));
+
+  const { catalog } = loadCatalog(argv.catalog);
+  const unknown = order.filter((n) => !catalog.includes(n));
+  if (unknown.length) die(`${file} names characteristics absent from the catalog: ${unknown.join(', ')}`);
+
+  const rebuilt = render(order, justifications);
+  const next = [...lines.slice(0, bounds.start), ...rebuilt, ...lines.slice(bounds.end)];
+  const updated = next.join(eol);
+
+  // Reported whether or not anything moved: a scaffold is already correct and
+  // still has every justification left to write.
+  const blank = justifications.filter((j, i) => i < justifications.length - 1 && (!j || j === PLACEHOLDER)).length;
+  const outstanding = blank ? `${blank} row(s) still need a justification in place of ${PLACEHOLDER}.\n` : '';
+
+  if (updated === original) {
+    process.stdout.write(`${file} is already correct.\n${outstanding}`);
+    return;
+  }
+
+  fs.writeFileSync(target, updated, 'utf8');
+
+  const repaired = data.filter((l, i) => splitCells(l)[2] !== splitCells(rebuilt[i + 2])[2]).length;
+  const renumbered = data.filter((l, i) => splitCells(l)[0] !== String(i + 1)).length;
+
+  process.stdout.write(
+    `Fixed ${file}: renumbered ${renumbered} row(s), rebuilt ${repaired} reason(s).\n${outstanding}`
+  );
+}
+
+function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  const argv = { force: false };
+
+  for (let i = 0; i < rest.length; i += 1) {
+    const flag = rest[i];
+    if (flag === '--force') argv.force = true;
+    else if (flag === '--out') argv.out = rest[(i += 1)];
+    else if (flag === '--file') argv.file = rest[(i += 1)];
+    else if (flag === '--catalog') argv.catalog = rest[(i += 1)];
+    else die(`unknown argument: ${flag}`);
+  }
+
+  try {
+    if (command === 'scaffold') return scaffold(argv);
+    if (command === 'fix') return fix(argv);
+  } catch (err) {
+    die(err.message);
+  }
+
+  die('usage: ranking-table.cjs scaffold [--out <path>] [--force] | fix [--file <path>]');
+}
+
+main();

package/template/.claude/skills/code-review/SKILL.md

@@ -1,54 +1,201 @@
----
-name: code-review
-description: "Review code quality with adversarial rigor. Supports input modes: pending changes, PR number, commit hash, codebase scan. Always-on red-team analysis finds security holes, false assumptions, and failure modes."
-argument-hint: "[#PR | COMMIT | --pending | codebase [parallel]]"
-metadata:
-  author: claudekit
-  version: "3.0.0"
----
-
-# Code Review
-
-Adversarial, evidence-based code review. Two stages: **Quality** then **Adversarial** (red-team). Be honest, brutal, concise. **YAGNI / KISS / DRY.** Verify before claiming; evidence before assertions.
-
-## 1. Resolve the input
-
-Parse arguments, first match wins, then get the diff:
-
-| Argument | Mode | Diff command |
-|----------|------|--------------|
-| `#123` / PR URL | PR | `gh pr diff <n>` (+ `gh pr view <n> --json title,body,baseRefName` for intent) |
-| `[0-9a-f]{7,40}` | Commit | `git show <sha>` |
-| `--pending` | Pending | `git diff HEAD` (staged + unstaged) — ask user for intent |
-| *(none, changes in context)* | Default | recent changes already in context |
-| `codebase` / `codebase parallel` | Codebase | full-codebase scan (see below) |
-| *(none, no context)* | Prompt | `AskUserQuestion`: pending / PR / commit / codebase |
-
-Errors: PR not found → "PR #N not found"; bad SHA → "commit not found — is it pushed?"; empty `git diff HEAD` → "no pending changes". Ambiguous PR-vs-commit → prefer PR, note the assumption.
-
-Always review **added/modified lines** (`+` in diff). Pre-existing code is out of scope unless the change makes it newly broken.
-
-## 2. Stage 1 — Quality review
-
-If the work implemented a plan/spec, first confirm compliance: list each requirement, mark PASS / MISSING / EXTRA. Missing requirements fail the review before quality matters — well-written code that doesn't match the spec is still wrong.
-
-Then review the diff for: correctness, standards, edge cases (null/empty/boundary/error paths), performance, and reuse/simplification. Dispatch a `code-reviewer` subagent for non-trivial diffs; review inline for small ones. Each finding: `file:line`, problem, fix.
-
-**Checklists (optional, for pre-landing / security audits):** detect project type — `package.json` with react/vue/next/etc → load `references/checklists/web-app.md`; `src/routes|api|controllers` → `references/checklists/api.md`; always load `references/checklists/base.md`. Run critical categories first (blocking), informational second. Honor the suppressions list at the bottom of `base.md`.
-
-## 3. Stage 2 — Adversarial review (always-on)
-
-**Skip only when ALL true:** ≤2 files changed, ≤30 lines, no security-sensitive files (auth/crypto/input-parsing/SQL/env), no new dependencies. When skipped, note `Adversarial: skipped (below threshold)`.
-
-**Never skip** when auth/middleware/security/crypto, a lockfile, env vars, DB schema, or an API route changed.
-
-Run the red-team pass per **`references/adversarial-review.md`** — spawn an adversarial `code-reviewer` whose only job is to break the code (security holes, false assumptions, failure modes, races, data corruption, supply chain, observability gaps). Then adjudicate each finding **Accept / Reject / Defer** with a reason — no silent dismissals; benefit of the doubt goes to the adversary. Critical accepted findings block merge. On re-review, pass only the fix diff.
-
-## Codebase modes
-
-- **`codebase`** — explore relevant files, dispatch parallel `code-reviewer` subagents by area, then run the always-on adversarial pass over the full scope. Report combined findings.
-- **`codebase parallel`** — first enumerate edge cases exhaustively (null, boundary, error, race, validation, security, leaks, untested paths), group into ≤6 categories, dispatch one `code-reviewer` per category to **verify** them, aggregate handled/unhandled, then run the adversarial pass.
-
-## Bottom line
-
-Resolve what you're reviewing → quality pass → adversarial pass (scope-gated) → adjudicate → fix Critical, then claim only with verification evidence.
+---
+name: code-review
+description: "Review code quality with evidence-based rigor. Supports input modes: pending changes, PR number, commit hash, and codebase scan. Focuses on bugs, regressions, maintainability, reliability, and verification gaps."
+user-invocable: true
+when_to_use: "Invoke to review diffs, PRs, commits, or full codebases."
+category: utilities
+keywords: [review, quality, verification, reliability]
+argument-hint: "[#PR | COMMIT | --pending | codebase [parallel]]"
+metadata:
+  author: claudekit
+  version: "4.0.0"
+---
+
+# Code Review
+
+Production-readiness code review with technical rigor, evidence-based claims, and verification over performative responses. Reviews focus on production risks, regression paths, and whether the implementation matches the requested change.
+
+## Input Modes
+
+Auto-detect from arguments. If ambiguous or no arguments, prompt via `AskUserQuestion`.
+
+| Input | Mode | What Gets Reviewed |
+|-------|------|--------------------|
+| `#123` or PR URL | **PR** | Full PR diff fetched via `gh pr diff` |
+| `abc1234` (7+ hex chars) | **Commit** | Single commit diff via `git show` |
+| `--pending` | **Pending** | Staged + unstaged changes via `git diff` |
+| *(no args, recent changes)* | **Default** | Recent changes in context |
+| `codebase` | **Codebase** | Full codebase scan |
+| `codebase parallel` | **Codebase+** | Parallel multi-reviewer audit |
+
+**Resolution details:** `references/input-mode-resolution.md`
+
+### No Arguments
+
+If invoked WITHOUT arguments and no recent changes in context, use `AskUserQuestion` with header "Review Target", question "What would you like to review?":
+
+| Option | Description |
+|--------|-------------|
+| Pending changes | Review staged/unstaged git diff |
+| Enter PR number | Fetch and review a specific PR |
+| Enter commit hash | Review a specific commit |
+| Full codebase scan | Deep codebase analysis |
+| Parallel codebase audit | Multi-reviewer codebase scan |
+
+## Core Principle
+
+**YAGNI**, **KISS**, **DRY** always. Technical correctness over social comfort.
+**Be honest, be brutal, straight to the point, and be concise.**
+
+Default assumption: reviewed code may be AI-assisted. Do not trust polished shape, confident comments, or happy-path tests. Verify behavior, project-rule compliance, and scope discipline from evidence.
+
+No rubber-stamp reviews. The reviewer is not trying to please the author or preserve momentum; the reviewer enforces the rulebook and blocks defects, regressions, hidden scope drift, and AI-slop patterns.
+
+Verify before implementing. Ask before assuming. Evidence before claims.
+
+## Practices
+
+| Practice | When | Reference |
+|----------|------|-----------|
+| **Spec compliance** | After implementing from plan/spec, BEFORE quality review | `references/spec-compliance-review.md` |
+| Receiving feedback | Unclear feedback, external reviewers, needs prioritization | `references/code-review-reception.md` |
+| Requesting review | After tasks, before merge, stuck on problem | `references/requesting-code-review.md` |
+| Verification gates | Before any completion claim, commit, PR | `references/verification-before-completion.md` |
+| Edge case scouting | After implementation, before review | `references/edge-case-scouting.md` |
+| **Checklist review** | Pre-landing, pre-merge, security audit | `references/checklist-workflow.md` |
+| **Task-managed reviews** | Multi-file features (3+ files), parallel reviewers, fix cycles | `references/task-management-reviews.md` |
+
+## Quick Decision Tree
+
+```
+SITUATION?
+│
+├─ Input mode? → Resolve diff (references/input-mode-resolution.md)
+│   ├─ #PR / URL → fetch PR diff
+│   ├─ commit hash → git show
+│   ├─ --pending → git diff (staged + unstaged)
+│   ├─ codebase → full scan (references/codebase-scan-workflow.md)
+│   ├─ codebase parallel → parallel audit (references/parallel-review-workflow.md)
+│   └─ default → recent changes in context
+│
+├─ Received feedback → STOP if unclear, verify if external, implement if human partner
+├─ Completed work from plan/spec:
+│   ├─ Stage 1: Spec compliance review (references/spec-compliance-review.md)
+│   │   └─ PASS? → Stage 2 │ FAIL? → Fix → Re-review Stage 1
+│   ├─ Stage 2: Code quality review (code-reviewer subagent)
+│   │   └─ Scout edge cases → Review standards, performance
+│   └─ Verification gate → Run required tests/builds before claims
+├─ Completed work (no plan) → Scout → Code quality → Verification
+├─ Pre-landing / ship → Load checklists → Two-pass review → Verification
+├─ Multi-file feature (3+ files) → Create review pipeline tasks (scout→review→fix→verify)
+└─ About to claim status → RUN verification command FIRST
+```
+
+### Review Protocol
+
+**Stage 1 — Spec Compliance** (load `references/spec-compliance-review.md`)
+- Does code match what was requested?
+- Any missing requirements? Any unjustified extras?
+- MUST pass before Stage 2
+
+**Stage 2 — Code Quality** (code-reviewer subagent)
+- Only runs AFTER spec compliance passes
+- Standards, security, performance, edge cases
+
+**Final Verification**
+- Runs AFTER Stage 2 passes
+- Re-run the relevant tests, build, lint, or manual reproduction
+- Verify accepted findings are fixed and no new regression is introduced
+- Critical findings block merge until fixed and re-verified
+
+## Receiving Feedback
+
+**Pattern:** READ → UNDERSTAND → VERIFY → EVALUATE → RESPOND → IMPLEMENT
+No performative agreement. Verify before implementing. Push back if wrong.
+
+**Full protocol:** `references/code-review-reception.md`
+
+## Requesting Review
+
+**When:** After each task, major features, before merge
+
+**Process:**
+1. **Scout edge cases first** (see below)
+2. Get SHAs: `BASE_SHA=$(git rev-parse HEAD~1)` and `HEAD_SHA=$(git rev-parse HEAD)`
+3. Dispatch code-reviewer subagent with: WHAT, PLAN, BASE_SHA, HEAD_SHA, DESCRIPTION
+4. Fix Critical immediately, Important before proceeding
+
+**Full protocol:** `references/requesting-code-review.md`
+
+## Edge Case Scouting
+
+**When:** After implementation, before requesting code-reviewer
+
+**Process:**
+1. Dispatch an `Explore` subagent with an edge-case-focused prompt
+2. It analyzes: affected files, data flows, error paths, boundary conditions
+3. Review the returned findings for potential issues
+4. Address critical gaps before code review
+
+**Full protocol:** `references/edge-case-scouting.md`
+
+## Task-Managed Review Pipeline
+
+**When:** Multi-file features (3+ changed files), parallel code-reviewer scopes, review cycles with Critical fix iterations.
+
+**Fallback:** Task tools (`TaskCreate`/`TaskUpdate`/`TaskGet`/`TaskList`) are CLI-only — unavailable in VSCode extension. If they error, use `TodoWrite` for tracking and run pipeline sequentially. Review quality is identical.
+
+**Pipeline:** scout → review → fix → verify (each a Task with dependency chain)
+
+```
+TaskCreate: "Scout edge cases"         → pending
+TaskCreate: "Review implementation"    → pending, blockedBy: [scout]
+TaskCreate: "Fix critical issues"      → pending, blockedBy: [review]
+TaskCreate: "Verify fixes pass"        → pending, blockedBy: [fix]
+```
+
+**Parallel reviews:** Spawn scoped code-reviewer subagents for independent file groups (e.g., backend + frontend). Fix task blocks on all reviewers completing.
+
+**Re-review cycles:** If fixes introduce new issues, create cycle-2 review task. Limit 3 cycles, escalate to user after.
+
+**Full protocol:** `references/task-management-reviews.md`
+
+## Verification Gates
+
+**Iron Law:** NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+
+**Gate:** IDENTIFY command → RUN full → READ output → VERIFY confirms → THEN claim
+
+**Requirements:**
+- Tests pass: Output shows 0 failures
+- Build succeeds: Exit 0
+- Bug fixed: Original symptom passes
+- Requirements met: Checklist verified
+
+**Red Flags:** "should"/"probably"/"seems to", satisfaction before verification, trusting agent reports
+
+**Full protocol:** `references/verification-before-completion.md`
+
+## Integration with Workflows
+
+- **Subagent-Driven:** Scout → Review → Verify before next task
+- **Pull Requests:** Scout → Code quality → Verify → Merge
+- **Task Pipeline:** Create review tasks with dependencies → auto-unblock through chain
+- **PR Review:** `/code-review #123` → fetch diff → full review pipeline on PR changes
+- **Commit Review:** `/code-review abc1234` → review specific commit with full pipeline
+
+## Codebase Analysis Subcommands
+
+| Subcommand | Reference | Purpose |
+|------------|-----------|---------|
+| `/code-review codebase` | `references/codebase-scan-workflow.md` | Scan & analyze the codebase |
+| `/code-review codebase parallel` | `references/parallel-review-workflow.md` | Ultrathink edge cases, then parallel verify |
+
+## Bottom Line
+
+1. Resolve input mode first — know WHAT you're reviewing
+2. Technical rigor over social performance
+3. Scout edge cases before review
+4. Evidence before claims
+
+Verify. Scout. Question. Then implement. Evidence. Then claim.