aiwcli 0.15.5 → 0.17.0

package/dist/templates/_shared/scripts/resolve-run.ts

@@ -1,62 +0,0 @@
-#!/usr/bin/env bun
-/* global Bun */
-/**
- * Cross-platform project root resolver for hook and status line commands.
- *
- * Finds the project root (via git or .aiwcli/ anchor walk-up), then spawns
- * the target script with cwd set to the root. stdin/stdout/stderr pass through.
- *
- * Install:  ~/.aiwcli/bin/resolve-run.ts  (global, always findable via ~)
- * Usage:    bun ~/.aiwcli/bin/resolve-run.ts .aiwcli/_shared/scripts/status_line.ts
- *
- * Works on: bash, zsh, PowerShell, cmd (anywhere bun + ~ expansion works)
- */
-import { execSync } from "node:child_process";
-import * as fs from "node:fs";
-import * as path from "node:path";
-
-function findProjectRoot(): string {
-  // 1. git (works from any subdirectory of a repo)
-  try {
-    const root = execSync("git rev-parse --show-toplevel", {
-      encoding: "utf-8",
-      stdio: ["pipe", "pipe", "pipe"],
-      timeout: 2000,
-    }).trim();
-    if (root && fs.existsSync(path.join(root, ".aiwcli"))) return root;
-  } catch { /* not a git repo or git not available */ }
-
-  // 2. Walk up from cwd to find .aiwcli/ anchor
-  let dir = process.cwd();
-  while (true) {
-    if (fs.existsSync(path.join(dir, ".aiwcli"))) return dir;
-    const parent = path.dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-
-  return process.cwd(); // last resort
-}
-
-const target = process.argv[2];
-if (!target) {
-  process.stderr.write("resolve-run: missing script path argument\n");
-  process.exit(1);
-}
-
-const root = findProjectRoot();
-const fullPath = path.resolve(root, target);
-
-if (!fs.existsSync(fullPath)) {
-  process.stderr.write(`resolve-run: script not found: ${fullPath}\n`);
-  process.exit(1);
-}
-
-const result = Bun.spawnSync(["bun", fullPath, ...process.argv.slice(3)], {
-  stdin: "inherit",
-  stdout: "inherit",
-  stderr: "inherit",
-  cwd: root,
-});
-
-process.exit(result.exitCode);

package/dist/templates/_shared/skills/codex/CLAUDE.md

@@ -1,70 +0,0 @@
-# Codex Skill
-
-Launch Codex CLI in a visible pane (tmux on Unix, Windows Terminal/window fallback on native Windows) and pass the prompt at process start.
-
-## Directory Structure
-
-```
-codex/
-├── CLAUDE.md       ← This file
-├── lib/
-│   └── codex-watcher.ts  ← Reusable watch/summarize library
-└── scripts/
-    └── launch-codex.ts   ← Single entry point (launch + optional watch)
-```
-
-## Script: launch-codex.ts
-
-**Usage:**
-```bash
-bun ~/.aiwcli/bin/resolve-run.ts .aiwcli/_shared/skills/codex/scripts/launch-codex.ts [--model <tier|id>] [--sandbox <sandbox-mode>] [--prompt <text>] [--no-yolo] [--no-watch] [--context <id>] plan
-bun ~/.aiwcli/bin/resolve-run.ts .aiwcli/_shared/skills/codex/scripts/launch-codex.ts [--model <tier|id>] [--sandbox <sandbox-mode>] [--prompt <text>] [--no-yolo] [--no-watch] [--context <id>] --file <path>
-bun ~/.aiwcli/bin/resolve-run.ts .aiwcli/_shared/skills/codex/scripts/launch-codex.ts [--model <tier|id>] [--sandbox <sandbox-mode>] [--prompt <text>] [--no-yolo] [--no-watch] [--context <id>] <inline text...>
-```
-
-**Args:**
-- `plan` — discover active plan via context system, send it as startup prompt to Codex
-- `--file <path>` — read file contents and send as startup prompt
-- `<text...>` — join remaining args as inline prompt
-- `--model <alias|tier|id>` — Aliases: `spark` → `gpt-5.3-codex-spark`, `codex` → `gpt-5.3-codex`, `gpt` → `gpt-5.2`. Tiers: `fast`/`standard`/`smart` (resolved via `resolveModelForProvider()`). Or any full model ID.
-- `--sandbox <mode>` — `read-only`, `workspace-write`, or `danger-full-access`. Default is `danger-full-access`.
-- `--prompt <text>` — append extra instructions under `## Additional Instructions`.
-- `--no-yolo` — Disable YOLO mode (`--dangerously-bypass-approvals-and-sandbox`).
-- `--no-watch` — Disable watch/summarize mode.
-
-**Plan discovery order:**
-1. `CLAUDE_SESSION_ID` env → `getContextBySessionId()` → `findLatestPlan(contextId)`
-2. Fallback: scan `_output/contexts/*/plans/*.md` by mtime
-
-**Dependencies (all from `_shared/lib-ts/`):**
-- `base/tmux-driver.ts` — pane launcher orchestration with cross-platform fallback
-- `base/pane-launcher.ts` + `base/launchers/*` — tmux / wt / window launchers
-- `base/cli-args.ts` — model/sandbox/yolo CLI arg generation
-- `base/sentinel-ipc.ts` — completion sentinel file lifecycle
-- `context/*` — context lookup, formatting, plan discovery
-
-**Watch behavior (single entry point):**
-- Watch is enabled by default.
-- `launch-codex.ts` launches Codex, waits for completion (pane close or sentinel), and prints a summary.
-- Summary cascade:
-  1. Spark transcript summary from session file
-  2. `codex exec resume <session_id>` summary
-  3. Transcript-line fallback
-  4. Static `Summary unavailable` message
-
-**Design decisions:**
-- Prompt is delivered at launch time (no tmux buffer paste/capture workflow)
-- Pane backend detection order: tmux (in-session) → Windows Terminal split pane → Windows new window → non-interactive exec fallback
-- `_shared` only — never imports from `_cc-native`
-- Watch path is best-effort and does not change launch success semantics
-
-## Library: lib/codex-watcher.ts
-
-Reusable side-effect-free watch/summarize functions used by launch flow:
-- `waitForPaneClose(target, timeoutMs?)` where `target` can be tmux pane id or `{ backend, paneId, sentinelPath }`
-- `summarizeViaSessionFileSpark(sessionFile)`
-- `summarizeViaResume(sessionId)`
-- `summarizeFromSessionFileFallback(sessionFile)`
-- `collectTranscriptLines(sessionFile)`
-
-Constants and helper utilities are exported for reuse and testing (`POLL_INTERVAL_MS`, `SUMMARY_UNAVAILABLE_MESSAGE`, `normalizeText`, `looksLikeBadSummary`, etc.).

package/dist/templates/cc-native/_cc-native/CLAUDE.md

@@ -1,73 +0,0 @@
-# CC-Native Method
-
-**Location:** `.aiwcli/_cc-native/` — Claude Code-specific plan review, artifacts, and agent orchestration.
-
----
-
-## Subsystems
-
-| Directory | Purpose | CLAUDE.md |
-|-----------|---------|-----------|
-| `agents/` | Plan review agent roster and specs | `agents/CLAUDE.md` |
-| `artifacts/` | Review artifact generation and tracking | `artifacts/CLAUDE.md` |
-| `hooks/` | CC-native hook entry points (plan review triggers) | `hooks/CLAUDE.md` |
-| `lib-ts/` | Shared TypeScript library for cc-native subsystems | `lib-ts/CLAUDE.md` |
-| `lib-ts/rlm/` | Retrieval-augmented learning memory | `lib-ts/rlm/CLAUDE.md` |
-| `plan-review/` | Multi-agent plan review pipeline | `plan-review/CLAUDE.md` |
-
----
-
-## Shared Infrastructure (`_shared/lib-ts/`)
-
-CC-native code depends heavily on shared infrastructure. Full API details: `_shared/lib-ts/CLAUDE.md`.
-
-| Module | Capability | Use When |
-|--------|-----------|----------|
-| `base/hook-utils` | Hook lifecycle (load input, run, emit context) | Writing hooks |
-| `base/logger` | Structured logging (debug/info/warn/error) | Any hook or lib module |
-| `base/constants` | Project paths, context dirs, sanitization | Resolving file locations |
-| `base/subprocess-utils` | Find executables, exec with env, shell quoting | Spawning agent CLIs |
-| `base/cli-args` | CLI invocation builder, review spec construction | Launching review agents |
-| `base/atomic-write` | Crash-safe file writes | Writing state or artifacts |
-| `base/state-io` | State read/write helpers | Context state persistence |
-| `base/inference` | Claude CLI subprocess calls | AI inference from hooks |
-| `context/context-store` | Context CRUD (get by session, list all) | Session/context binding |
-| `context/plan-manager` | Plan lifecycle (archive, hash, sign) | Plan discovery and hashing |
-| `types` | Shared type definitions (`ContextState`, etc.) | Type imports |
-
----
-
-## Import Patterns
-
-**Import direction:** `hooks/` → `lib-ts/` → `_shared/lib-ts/`. Never the reverse.
-
-```typescript
-// From hooks/ (2 levels up to _shared):
-import { runHook, logInfo } from "../../_shared/lib-ts/base/hook-utils.js";
-import { loadConfig } from "../lib-ts/config.js";
-
-// From lib-ts/ (2 levels up to _shared):
-import { logDebug } from "../../_shared/lib-ts/base/logger.js";
-import { atomicWrite } from "../../_shared/lib-ts/base/atomic-write.js";
-
-// From plan-review/lib/ (3 levels up to _shared):
-import { logInfo } from "../../../_shared/lib-ts/base/logger.js";
-```
-
----
-
-## Context Maintenance
-
-**After modifying files in this directory:** scan the entries above — if any claim is now
-false or incomplete, update this file before ending the task. Do not defer.
-
-**Add** an entry only if an agent would fail without knowing it, it is not obvious from
-the code, and it belongs at this scope.
-
-**Remove** any entry that fails the falsifiability test: if removing it would not change
-how an agent acts here, remove it.
-
-**Staleness anchor:** This file assumes `lib-ts/index.ts` exists. If it doesn't, this file
-is stale — update or regenerate before relying on it.
-
-<!-- context-layer: generated=2026-03-01 | last-audited=2026-03-01 | version=1 | dir-commits-at-audit=15 -->

package/dist/templates/cc-native/_cc-native/artifacts/CLAUDE.md

@@ -1,64 +0,0 @@
-# Artifacts System
-
-Review artifact generation, formatting, and file I/O for the plan review pipeline.
-
-## Overview
-
-The artifacts system handles all output files produced by plan review runs: combined markdown reports, JSON results, inline summaries, corroboration reports, and the review tracker. It is a pure library — no hooks or scripts.
-
-## File Structure
-
-```
-artifacts/
-├── CLAUDE.md        ← This file
-└── lib/
-    ├── index.ts     ← Barrel re-export of all public API
-    ├── format.ts    ← Pure formatting functions (markdown, JSON, summaries)
-    ├── write.ts     ← File I/O: atomic writes to context reviews dir
-    └── tracker.ts   ← Review tracker: read/write/hash extraction
-```
-
-## Public API (`lib/index.ts`)
-
-| Function | Source | Purpose |
-|----------|--------|---------|
-| `formatReviewMarkdown` | format.ts | Format single agent review as markdown |
-| `formatCombinedMarkdown` | format.ts | Format all agent reviews into combined markdown |
-| `buildInlineReviewSummary` | format.ts | Short inline summary for context injection |
-| `extractTopIssuesText` | format.ts | Extract top issues as text block |
-| `buildHighIssuesDocument` | format.ts | Full high-issues document for context |
-| `buildCorroborationReport` | format.ts | Corroboration analysis markdown report |
-| `generateReviewIndex` | format.ts | Index markdown linking all review files |
-| `buildCombinedJson` | format.ts | Combined JSON artifact for all reviews |
-| `writeCombinedArtifacts` | write.ts | Write all artifacts to context reviews dir |
-| `writeFile` | write.ts | Atomic file write |
-| `writeFileNonCritical` | write.ts | Non-atomic file write (non-critical paths) |
-| `writeReviewTracker` | tracker.ts | Write review tracker JSON to disk |
-| `extractPreviousHashes` | tracker.ts | Read previous plan hashes from tracker |
-| `ReviewTrackerEntry` | tracker.ts | Type: single tracker entry |
-
-## Dependencies
-
-- `../../lib-ts/types.ts` — `CombinedReviewResult`, `CorroborationResult` types
-- `../../lib-ts/constants.ts` — `ENABLE_ROBUST_PLAN_WRITES` feature flag
-- `../../../_shared/lib-ts/base/atomic-write.ts` — atomic file I/O
-- `../../../_shared/lib-ts/base/constants.ts` — `sanitizeFilename`
-- `../../../_shared/lib-ts/base/logger.ts` — logging
-
-## Hooks
-
-Hooks for this system are NOT co-located here. Hooks are path-referenced in `.claude/settings.json` at install time. Moving a hook file requires settings.json updates in both `.aiwcli/` and `packages/cli/src/templates/`, which is high blast-radius and fragile.
-
-The artifacts system is invoked indirectly through the plan review pipeline — it has no dedicated hooks. See `../_cc-native/hooks/` for the plan review hooks that drive this system.
-
-## Callers
-
-- `../plan-review/lib/review-pipeline.ts` — primary caller, writes all review artifacts
-- `../../lib-ts/index.ts` — re-exports public API surface
-
-## Design Decisions
-
-- **Pure library:** No global state, no side effects except file I/O in write.ts/tracker.ts
-- **Atomic writes:** `write.ts` uses atomic writes (write to temp + rename) for critical review files when `ENABLE_ROBUST_PLAN_WRITES` is set, preventing partial writes on crash
-- **format.ts is pure:** All formatting is pure functions — takes data, returns strings. No file I/O.
-- **Co-location:** Moved from `lib-ts/artifacts/` to `artifacts/lib/` to give the system peer-level status alongside `plan-review/` and `rlm/`

package/dist/templates/cc-native/_cc-native/lib-ts/CLAUDE.md

@@ -1,70 +0,0 @@
-# CC-Native Library
-
-**Location:** `_cc-native/lib-ts/` — TypeScript modules for plan review, state, and agent orchestration.
-
-**Import direction:** `hooks/` → `lib-ts/` → `_shared/lib-ts/`. Never the reverse.
-
----
-
-## Module Reference
-
-The barrel `index.ts` re-exports most modules. Three files are **not** re-exported and must be imported directly: `plan-discovery.ts`, `plan-enhancement.ts`, `settings.ts`.
-
-| File | Purpose | Key Exports |
-|------|---------|-------------|
-| `aggregate-agents.ts` | Agent frontmatter parser — loads agent configs from markdown | `aggregateAgents`, `extractBody`, `extractFrontmatter` |
-| `cc-native-state.ts` | CC-native state accessor for context `state.json` | `getCcNativeState`, `saveCcNativeState`, `isPlanAlreadyReviewed`, `markPlanReviewed`, `markQuestionsAsked` |
-| `cli-output-parser.ts` | Unified Claude CLI JSON output parser | `parseCliOutput` |
-| `config.ts` | Configuration loading from `cc-native.config.json` | `loadConfig`, `getDisplaySettings` |
-| `constants.ts` | Feature flags, security limits, path validation | `ENABLE_ROBUST_PLAN_WRITES`, `PLANS_DIR`, `validatePlanPath`, `MAX_RETRY_ATTEMPTS` |
-| `debug.ts` | Per-context debug logging (thin layer over shared logger) | `debugLog`, `debugRaw`, `getDebugDir`, `cleanupDebugFolder` |
-| `index.ts` | Barrel — re-exports public API from all modules | (see individual modules) |
-| `json-parser.ts` | JSON parsing with recovery for LLM responses | `parseJsonMaybe`, `coerceToReview` |
-| `plan-discovery.ts` | Plan file discovery, reading, and hashing | *(not re-exported)* — import directly |
-| `plan-enhancement.ts` | Plan quality guidance prompt for context emission | *(not re-exported)* — import directly |
-| `settings.ts` | Settings loading, defaults, agent library management | *(not re-exported)* — import directly |
-| `state.ts` | Iteration state management for plan review cycles | `loadState`, `saveStateToPlan`, `getIterationState`, `shouldContinueIterating` |
-| `types.ts` | All cc-native type definitions and prompt constants | `Verdict`, `ReviewData`, `AgentConfig`, `PlanReviewConfig`, `REVIEW_SCHEMA` |
-
-**Subfolder:** `rlm/` — retrieval-augmented learning memory. Has its own `rlm/CLAUDE.md`.
-
----
-
-## Shared Dependencies
-
-These `_shared/lib-ts` modules are used across cc-native lib-ts:
-
-| Shared Module | Used By |
-|--------------|---------|
-| `base/logger` | All modules (logging) |
-| `base/atomic-write` | `state.ts` (crash-safe writes) |
-| `base/utils` | `cc-native-state.ts` (`nowIso`) |
-| `context/context-store` | `cc-native-state.ts` (state access) |
-| `context/plan-manager` | `plan-discovery.ts` (plan path lookup) |
-| `types` | `types.ts` (re-exports `ContextState`, `HookInput`, `HookOutput`) |
-
----
-
-## Import Direction
-
-```
-hooks/                    (entry points — import from lib-ts/ and _shared/)
-  ↓
-lib-ts/                   (this directory — import from _shared/ only)
-  ↓
-_shared/lib-ts/           (cross-method infrastructure — no reverse imports)
-```
-
-Never import from `hooks/` or `plan-review/` into `lib-ts/`. The one exception noted in `aggregate-agents.ts`: it stays in `lib-ts/` because both `settings.ts` and `plan-review/` depend on it.
-
----
-
-## Context Maintenance
-
-**After modifying files in this directory:** scan the entries above — if any claim is now
-false or incomplete, update this file before ending the task. Do not defer.
-
-**Staleness anchor:** This file assumes `index.ts` exists with 13 sibling `.ts` files. If the
-count changes, update the Module Reference table.
-
-<!-- context-layer: generated=2026-03-01 | last-audited=2026-03-01 | version=1 | dir-commits-at-audit=15 -->

package/dist/templates/cc-native/_cc-native/plan-review/CODING-STANDARDS-CHECKLIST.md

@@ -1,75 +0,0 @@
-# Coding Standards Checklist
-
-Standards that address the most common plan review failure modes. Reference this
-when planning code changes in established codebases.
-
----
-
-## 1. Test-First Design Thinking
-
-Tests are an architectural constraint, not an afterthought. Design from the test
-perspective first.
-
-- **Interface-first:** Before describing implementation, ask: "Can I write the test
-  for this before the implementation exists?" If the answer is unclear, the interface
-  needs more thought.
-- **Structure tests before code:** Plans that describe "implement then test" consistently
-  fail review. Restructure: define what the tests assert, then describe the implementation
-  that satisfies them.
-- **Testability as architecture:** Design for dependency injection, interface seams, and
-  fakes. If a component can't be tested in isolation, the coupling is too tight.
-- **Test categories:** Consider which test types apply — unit (isolated logic), integration
-  (module boundaries), contract (API surfaces), and characterization (existing behavior
-  preservation during refactoring).
-- **Verification clarity:** Each planned change should have a corresponding verification
-  step that is binary-testable (pass/fail in one check, no subjective judgment).
-
----
-
-## 2. File Structure & Codebase Convention Fit
-
-Don't pick a "plausible" location — pick the location that matches the project's
-established patterns.
-
-- **Discover before proposing:** Before suggesting new files or directories, verify where
-  similar things already live in this project. Use Glob/Grep to find existing patterns.
-- **Naming conventions:** Match existing module and file naming patterns. If the project
-  uses `kebab-case.ts`, don't introduce `camelCase.ts`. If hooks live in `hooks/`, don't
-  create a `hook-handlers/` directory.
-- **Co-location patterns:** Check if the project follows co-location (tests next to source,
-  types with implementation) or separation (dedicated `__tests__/`, `types/` directories).
-  Follow what exists.
-- **Import depth:** Verify that new files fit the existing import hierarchy. Adding a file
-  that requires imports to cross architectural boundaries (e.g., shared lib importing from
-  feature code) signals a structural problem.
-- **Existing system boundaries:** Check if the project has documented system boundaries
-  (CLAUDE.md, architecture docs). New files should respect these boundaries rather than
-  create cross-cutting dependencies.
-
----
-
-## 3. Extensibility & Future-Proofing Analysis
-
-Balance: don't over-engineer (YAGNI), but don't create designs that actively resist
-extension.
-
-- **Adjacent features:** What features are most commonly built after this one? Does the
-  design accommodate those extensions without major restructuring?
-- **Extension points:** Where would future developers need to hook in? Are those seams
-  accessible, or does the design require forking/copying to extend?
-- **Configuration vs. code changes:** Will common customizations require code changes, or
-  can they be handled through configuration? Prefer the latter when the variation space
-  is predictable.
-- **Data model flexibility:** Are data structures designed to accommodate likely additions
-  (new fields, new types) without breaking existing consumers?
-- **Inversion of control:** Does the design allow callers to inject behavior, or does it
-  hardcode decisions that callers will need to override? Prefer interfaces and callbacks
-  over concrete implementations when variation is expected.
-
----
-
-## Applicability
-
-These standards apply to production code in established codebases with existing conventions.
-For prototypes, scripts, spike explorations, or greenfield projects without established
-patterns, use judgment on which standards apply — not all will be relevant.

package/dist/templates/cc-native/_cc-native/plan-review/agents/CLAUDE.md

@@ -1,143 +0,0 @@
-# CC-Native Plan Review Agents
-
-Agent persona definitions for single-turn plan review. 31 review agents + 1 question agent.
-
-## Directory Structure
-
-```
-agents/
-├── CLAUDE.md              # This file
-├── PLAN-ORCHESTRATOR.md   # Complexity/agent selection orchestrator
-├── plan-review/           # Review agents (31 files)
-│   ├── HANDOFF-READINESS.md
-│   ├── CLARITY-AUDITOR.md
-│   ├── SKEPTIC.md
-│   ├── ...                # All review agent .md files
-│   └── TESTDRIVEN-CHARACTERIZATION.md
-└── plan-questions/        # Question generation agents
-    └── PLAN-QUESTIONER.md # Fresh-context question generator
-```
-
-**Important:** Review agents MUST be in `plan-review/`. The hook loads from `agents/plan-review/` — files in the root `agents/` directory (other than CLAUDE.md and PLAN-ORCHESTRATOR.md) are ignored.
-
-## Review Agents (31 total)
-
-4 mandatory + 27 selectable (organized into 7 variation families + 7 standalone).
-
-## Agent Roster (31 agents)
-
-### Mandatory (4) — always run
-| Agent | Focus |
-|-------|-------|
-| `handoff-readiness` | Fresh context execution test |
-| `clarity-auditor` | Communication clarity |
-| `skeptic` | Problem-solution alignment, first-principles |
-| `documentation-philosophy` | Knowledge capture (medium+ only) |
-
-### Risk Family (4 variations)
-| Agent | Framework | Categories |
-|-------|-----------|------------|
-| `risk-premortem` | Pre-mortem (Klein 2007) — assumes failure, generates narratives | all |
-| `risk-fmea` | FMEA — per-step severity×likelihood×detectability | code, infra, design |
-| `risk-dependency` | Blast radius / dependency graph — maps cascading chains | code, infra |
-| `risk-reversibility` | One-way doors / optionality — classifies decision reversibility | all |
-
-### Completeness Family (3 variations)
-| Agent | Framework | Categories |
-|-------|-----------|------------|
-| `completeness-gaps` | Structural gap analysis — missing steps, error paths, pre/post-conditions | all |
-| `completeness-feasibility` | Feasibility — resource gaps, expertise, timeline realism | all |
-| `completeness-ordering` | Critical path / topological sort — step ordering, parallelization | code, infra, design |
-
-### Architecture Family (3 variations)
-| Agent | Framework | Categories |
-|-------|-----------|------------|
-| `arch-structure` | Coupling/cohesion — boundary placement, dependency direction | code, infra, design |
-| `arch-evolution` | Evolutionary architecture — change amplification, extension points | code, infra, design |
-| `arch-patterns` | Pattern selection — technology fit, pattern-forcing detection | code, infra |
-
-### Verification Family (2 variations)
-| Agent | Framework | Categories |
-|-------|-----------|------------|
-| `verify-coverage` | Coverage mapping — 1:1 implementation-to-verification | all |
-| `verify-strength` | Mutation testing — would tests catch subtle bugs? | code, infra |
-
-### Trade-off Family (2 variations)
-| Agent | Framework | Categories |
-|-------|-----------|------------|
-| `tradeoff-costs` | Opportunity cost — hidden costs, capability sacrifice | all |
-| `tradeoff-stakeholders` | Stakeholder impact — who wins, who loses, asymmetry | all |
-
-### Design Family (2 variations)
-| Agent | Framework | Categories |
-|-------|-----------|------------|
-| `design-adr-validator` | ADR structure — Context, Decision, Consequences, alternatives analysis | design, code, infra |
-| `design-scale-matcher` | Scale matching — design depth proportional to blast radius | design, code, infra |
-
-### TestDriven Family (4 variations)
-| Agent | Framework | Categories |
-|-------|-----------|------------|
-| `testdriven-first-validator` | FIRST principles — Fast, Independent, Repeatable, Self-validating, Thorough | code, infra |
-| `testdriven-behavior-auditor` | Behavior contracts — tests verify WHAT not HOW | code, infra |
-| `testdriven-pyramid-analyzer` | Test pyramid — balanced distribution, fast feedback at base | code, infra |
-| `testdriven-characterization` | Characterization tests — safety nets before code modification | code, infra |
-
-### Standalone Agents (7)
-| Agent | Focus | Categories |
-|-------|-------|------------|
-| `scope-boundary` | Scope drift detection | all |
-| `hidden-complexity` | Understated difficulty, "just" statements | all |
-| `simplicity-guardian` | Over-engineering, YAGNI | all |
-| `devils-advocate` | Contrarian, reductio ad absurdum | all |
-| `assumption-tracer` | Stacked assumption chains | all |
-| `incremental-delivery` | Vertical slicing, smaller increments | all |
-| `constraint-validator` | Constraint satisfaction | all |
-
-## Design: Variation Families
-
-Each family covers the same topic area but through different analytical lenses. Same output format, different analytical identity. This follows the RedTeam pattern (32 agents with unique personalities on the same concern). The orchestrator selects the most relevant variation(s) per family based on plan context.
-
-## System Prompt vs Agent Flag
-
-**Decision:** Use `--system-prompt` with markdown body content instead of `--agent <name>`
-
-**Rationale:**
-- Claude Code's `--agent` flag invokes built-in agents designed for multi-turn agentic workflows with tool access
-- Plan review needs single-turn text analysis: read plan, output structured JSON
-- The `--agent` flag ignores our custom markdown content entirely - it loads Claude Code's built-in agent definitions
-- Using `--system-prompt` lets us inject the full persona (expertise, review approach, output requirements) directly
-- Result: faster execution, no tool overhead, and our rich agent descriptions actually get used
-
-**Constraint:** If you switch back to `--agent`, the elaborate persona content in these markdown files will be ignored. The reviews will use Claude Code's generic agent behavior instead of our specialized reviewers.
-
-## File Structure
-
-Each agent file has:
-- **Frontmatter (YAML):** name, model, focus, categories
-- **Body (Markdown):** Full persona content → becomes `system_prompt` for `--system-prompt` flag
-
-## --setting-sources "" Requirement
-
-**Decision:** Use `--setting-sources ""` to disable user/project settings loading
-
-**Rationale:**
-- Without this flag, Claude Code loads user settings (~43k cached tokens of PAI context)
-- The PAI Algorithm instructions override the agent's system prompt behavior
-- Model tries to follow PAI format instead of calling StructuredOutput directly
-- Result: 6+ turns, 30+ seconds, often no structured output
-
-**Constraint:** If you remove `--setting-sources ""`, agent reviews will be slow and unreliable due to PAI context interference.
-
-## --max-turns 3 Requirement
-
-**Decision:** Use `--max-turns 3` with agent invocations
-
-**Rationale:**
-- `--max-turns 1` is too restrictive - the model needs turn 1 to call StructuredOutput, turn 2 for the tool result
-- `--max-turns 2` works but leaves no buffer for edge cases
-- `--max-turns 3` gives safety margin while still preventing runaway multi-turn behavior
-- With these settings, reviews complete in ~5-10 seconds
-
-**Constraint:** The agent markdown files MUST contain clear instructions to "call StructuredOutput IMMEDIATELY" and "do NOT use any other tools". Without these instructions, the model will try to use its turns for file operations instead of outputting the review.
-
-