aiwcli 0.15.7 → 0.17.0

package/dist/templates/core/skills/devin/scripts/launch-devin.ts

@@ -12,7 +12,10 @@ import path from "node:path";
 
 import { findLatestPlan } from "../../../lib-ts/context/plan-manager.js";
 import {
+  cleanupSentinel,
+  eprint,
   findLatestPlanByMtime,
+  getWellKnownSummaryPath,
   resolveContextForLaunch,
   writeFileRefPromptFile,
   writeInlinePromptFile,
@@ -31,22 +34,6 @@ const DEVIN_ALIASES: Record<string, string> = {
   opus: DEVIN_MODELS.opus,
 };
 
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-function eprint(...args: unknown[]): void {
-  process.stderr.write(args.map(String).join(" ") + "\n");
-}
-
-function cleanupSentinel(sentinelPath: string | null | undefined): void {
-  if (!sentinelPath) return;
-  try {
-    const dir = path.dirname(sentinelPath);
-    fs.rmSync(dir, { recursive: true, force: true });
-  } catch { /* best-effort */ }
-}
-
 // ---------------------------------------------------------------------------
 // Arg parsing
 // ---------------------------------------------------------------------------
@@ -61,6 +48,7 @@ if (rawArgs.length === 0) {
 let modelFlag: string | undefined;
 let contextFlag: string | undefined;
 let extraPrompt: string | undefined;
+let taskId: string | undefined;
 let watch = true;
 const args: string[] = [];
 
@@ -71,6 +59,8 @@ for (let i = 0; i < rawArgs.length; i++) {
     contextFlag = rawArgs[++i];
   } else if (rawArgs[i] === "--prompt" && i + 1 < rawArgs.length) {
     extraPrompt = rawArgs[++i];
+  } else if (rawArgs[i] === "--task-id" && i + 1 < rawArgs.length) {
+    taskId = rawArgs[++i];
   } else if (rawArgs[i] === "--no-watch") {
     watch = false;
   } else if (rawArgs[i] === "--prompt") {
@@ -160,9 +150,18 @@ if (args[0] === "plan") {
 // ---------------------------------------------------------------------------
 
 const launchCwd = process.env.AIW_CALLER_CWD?.trim() || process.cwd();
+
+// Generate task ID if not provided by caller.
+if (!taskId) {
+  taskId = `${Date.now()}-${process.pid}`;
+}
+const wellKnownPath = getWellKnownSummaryPath("devin", taskId, projectRoot);
+console.log(`Task ID: ${taskId}`);
+console.log(`Summary will be at: ${wellKnownPath}`);
+
 if (resolvedModel) console.log(`Model: ${resolvedModel}${modelFlag !== resolvedModel ? ` (from "${modelFlag}")` : ""}`);
 
-logDebug("devin-skill", `Launching: model=${resolvedModel ?? "default"}, extraPrompt=${Boolean(extraPrompt)}, source=${args[0]}, bytes=${promptPath ? fs.statSync(promptPath).size : 0}`);
+logDebug("devin-skill", `Launching: model=${resolvedModel ?? "default"}, taskId=${taskId}, extraPrompt=${Boolean(extraPrompt)}, source=${args[0]}, bytes=${promptPath ? fs.statSync(promptPath).size : 0}`);
 
 const launchStartedAtMs = Date.now();
 
@@ -228,22 +227,24 @@ if (watch && (result.paneId || result.sentinelPath)) {
 
     const summary = (await summarizeDevinSession(projectRoot, launchStartedAtMs, result.paneId))
       ?? SUMMARY_UNAVAILABLE_MESSAGE;
-    const summaryPath = persistSummary(summary, "devin");
+    const summaryPath = persistSummary(summary, "devin", undefined, taskId, projectRoot);
 
     console.log("\n--- Devin Session Summary ---");
     console.log(summary);
+    console.log(`\n[well_known_summary:${wellKnownPath}]`);
     if (summaryPath) {
-      console.log(`\n[summary_file:${summaryPath}]`);
+      console.log(`[summary_file:${summaryPath}]`);
     }
   } catch (error) {
     logWarn("devin-skill", `Watch flow failed: ${String(error)}`);
     const { persistSummary: persistFallback } = await import("../lib/devin-watcher.js");
     const fallbackMsg = "Devin session completed. Summary unavailable (watch error).";
-    const fallbackPath = persistFallback(fallbackMsg, "devin");
+    const fallbackPath = persistFallback(fallbackMsg, "devin", undefined, taskId, projectRoot);
     console.log("\n--- Devin Session Summary ---");
     console.log(fallbackMsg);
+    console.log(`\n[well_known_summary:${wellKnownPath}]`);
     if (fallbackPath) {
-      console.log(`\n[summary_file:${fallbackPath}]`);
+      console.log(`[summary_file:${fallbackPath}]`);
     }
   } finally {
     cleanupSentinel(result.sentinelPath);

package/dist/templates/core/skills/handoff-system/CLAUDE.md

@@ -432,5 +432,5 @@ Both `.aiwcli/_core/skills/handoff-system/` (working copy) and `packages/cli/src
 **Windsurf and Codex workflows also reference scripts:**
 When updating script paths, check:
 - `packages/cli/src/templates/core/.windsurf/workflows/handoff.md`
-- `packages/cli/src/templates/core/.codex/workflows/handoff.md`
+- `packages/cli/src/templates/core/.codex/skills/handoff.md`
 

package/oclif.manifest.json

@@ -393,15 +393,15 @@
           "type": "option"
         },
         "split": {
-          "description": "Split direction when in tmux (auto|h|v, default: auto)",
+          "description": "Split direction when in multiplexer (auto|horizontal|vertical, default: auto)",
           "name": "split",
           "required": false,
           "hasDynamicHelp": false,
           "multiple": false,
           "options": [
             "auto",
-            "h",
-            "v"
+            "horizontal",
+            "vertical"
           ],
           "type": "option"
         },
@@ -510,5 +510,5 @@
       ]
     }
   },
-  "version": "0.15.7"
+  "version": "0.17.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "aiwcli",
   "description": "AI Workflow CLI - Command-line interface for AI-powered workflows",
-  "version": "0.15.7",
+  "version": "0.17.0",
   "author": "jofu-tofu",
   "bin": {
     "aiw": "bin/run.js"
@@ -27,6 +27,7 @@
     "@types/chai": "^4",
     "@types/node": "^18",
     "@types/sinon": "^21.0.0",
+    "@vitest/coverage-v8": "^3.2.4",
     "c8": "^10.1.3",
     "chai": "^4",
     "chokidar": "^5.0.0",
@@ -43,7 +44,7 @@
     "ts-node": "^10",
     "typescript": "^5",
     "vitest": "^3.2.4",
-    "@vitest/coverage-v8": "^3.2.4"
+    "zod": "^4.3.6"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -82,7 +83,7 @@
   },
   "scripts": {
     "build": "shx rm -rf dist && tsc -b && npm run build:templates",
-    "build:templates": "npm run sync:shared-lib && npm run sync:cc-native && shx mkdir -p dist/templates && shx cp -r src/templates/core dist/templates/ && shx cp -r src/templates/cc-native dist/templates/ && shx cp src/templates/CLAUDE.md dist/templates/",
+    "build:templates": "npm run sync:shared-lib && shx mkdir -p dist/templates && shx cp -r src/templates/core dist/templates/ && shx cp -r src/templates/cc-native dist/templates/ && shx cp src/templates/CLAUDE.md dist/templates/",
     "build:watch": "tsc -b --watch",
     "check": "npm run lint && npm run build",
     "clean": "shx rm -rf dist",
@@ -103,7 +104,6 @@
     "test:watch": "vitest",
     "version": "oclif readme && git add README.md",
     "watch": "run-p dev:watch test:watch",
-    "sync:cc-native": "node ./scripts/sync-cc-native.mjs",
     "sync:shared-lib": "node ./scripts/sync-shared-lib.mjs"
   },
   "types": "dist/index.d.ts"

package/dist/lib/base-command.d.ts

@@ -1 +0,0 @@
-export { default } from '../cli/base-command.js';

package/dist/lib/base-command.js

@@ -1 +0,0 @@
-export { default } from '../cli/base-command.js';

package/dist/lib/env-compat.d.ts

@@ -1,18 +0,0 @@
-/**
- * Environment Variable Layer
- *
- * Provides environment variable resolution for AIW CLI.
- *
- * Environment variables:
- * - AIW_DIR: Main installation directory
- * - AIW_CONFIG: Configuration file path
- */
-/**
- * Load environment variables.
- * Call this early in application bootstrap.
- */
-export declare function loadEnvWithCompatibility(): void;
-/**
- * Get AIW_DIR environment variable
- */
-export declare function getAiwDir(): string | undefined;

package/dist/lib/env-compat.js

@@ -1,23 +0,0 @@
-/**
- * Environment Variable Layer
- *
- * Provides environment variable resolution for AIW CLI.
- *
- * Environment variables:
- * - AIW_DIR: Main installation directory
- * - AIW_CONFIG: Configuration file path
- */
-/**
- * Load environment variables.
- * Call this early in application bootstrap.
- */
-export function loadEnvWithCompatibility() {
-    // DA (Assistant name) - Keep for backward compatibility, no warning
-    // This is commonly used and doesn't need migration
-}
-/**
- * Get AIW_DIR environment variable
- */
-export function getAiwDir() {
-    return process.env['AIW_DIR'];
-}

package/dist/lib/launch-options.d.ts

@@ -1 +0,0 @@
-export { buildSpawnedWindowArgs, type BuildSpawnedWindowArgsParams, buildUniqueSessionName, parseExtraEnv, resolvePromptText, sanitizeSessionName, } from '../capabilities/launch/runtime-core/launch-options.js';

package/dist/lib/launch-options.js

@@ -1 +0,0 @@
-export { buildSpawnedWindowArgs, buildUniqueSessionName, parseExtraEnv, resolvePromptText, sanitizeSessionName, } from '../capabilities/launch/runtime-core/launch-options.js';

package/dist/lib/stdin.d.ts

@@ -1,48 +0,0 @@
-/**
- * stdin Detection and Reading Utilities
- *
- * Provides utilities for detecting and reading piped input from stdin.
- * Used by commands that need to accept piped data from other commands.
- *
- * @example Basic stdin detection
- * ```typescript
- * if (hasStdin()) {
- *   const input = await readStdin()
- *   // Process piped input
- * } else {
- *   // Interactive mode - prompt user
- * }
- * ```
- */
-/**
- * Check if stdin has piped data available.
- * Returns true when data is piped into the command, false in interactive terminals.
- *
- * @returns True if stdin is piped (not a TTY), false if interactive terminal
- *
- * @example
- * ```typescript
- * // echo "data" | pai process
- * hasStdin() // Returns true
- *
- * // pai process (no pipe)
- * hasStdin() // Returns false
- * ```
- */
-export declare function hasStdin(): boolean;
-/**
- * Read all data from stdin.
- * Reads piped input data and returns as UTF-8 string.
- * Returns empty string if no stdin available.
- *
- * @returns Promise resolving to stdin content as string, or empty string if no stdin
- *
- * @example
- * ```typescript
- * const input = await readStdin()
- * if (input) {
- *   console.log(`Received: ${input}`)
- * }
- * ```
- */
-export declare function readStdin(): Promise<string>;

package/dist/lib/stdin.js

@@ -1,60 +0,0 @@
-/**
- * stdin Detection and Reading Utilities
- *
- * Provides utilities for detecting and reading piped input from stdin.
- * Used by commands that need to accept piped data from other commands.
- *
- * @example Basic stdin detection
- * ```typescript
- * if (hasStdin()) {
- *   const input = await readStdin()
- *   // Process piped input
- * } else {
- *   // Interactive mode - prompt user
- * }
- * ```
- */
-import { stdin } from 'node:process';
-/**
- * Check if stdin has piped data available.
- * Returns true when data is piped into the command, false in interactive terminals.
- *
- * @returns True if stdin is piped (not a TTY), false if interactive terminal
- *
- * @example
- * ```typescript
- * // echo "data" | pai process
- * hasStdin() // Returns true
- *
- * // pai process (no pipe)
- * hasStdin() // Returns false
- * ```
- */
-export function hasStdin() {
-    return stdin.isTTY !== true;
-}
-/**
- * Read all data from stdin.
- * Reads piped input data and returns as UTF-8 string.
- * Returns empty string if no stdin available.
- *
- * @returns Promise resolving to stdin content as string, or empty string if no stdin
- *
- * @example
- * ```typescript
- * const input = await readStdin()
- * if (input) {
- *   console.log(`Received: ${input}`)
- * }
- * ```
- */
-export async function readStdin() {
-    if (!hasStdin()) {
-        return '';
-    }
-    const chunks = [];
-    for await (const chunk of stdin) {
-        chunks.push(chunk);
-    }
-    return Buffer.concat(chunks).toString('utf8');
-}

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 (`_core/lib-ts/`)
-
-CC-native code depends heavily on shared infrastructure. Full API details: `_core/lib-ts/CLAUDE.md`.
-
-| Module | Capability | Use When |
-|--------|-----------|----------|
-| `hooks/hook-utils` | Hook lifecycle (load input, run, emit context) | Writing hooks |
-| `runtime/logger` | Structured logging (debug/info/warn/error) | Any hook or lib module |
-| `runtime/constants` | Project paths, context dirs, sanitization | Resolving file locations |
-| `runtime/subprocess-utils` | Find executables, exec with env, shell quoting | Spawning agent CLIs |
-| `runtime/cli-args` | CLI invocation builder, review spec construction | Launching review agents |
-| `runtime/atomic-write` | Crash-safe file writes | Writing state or artifacts |
-| `runtime/state-io` | State read/write helpers | Context state persistence |
-| `runtime/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/` → `_core/lib-ts/`. Never the reverse.
-
-```typescript
-// From hooks/ (2 levels up to _core):
-import { runHook, logInfo } from "../../_core/lib-ts/hooks/hook-utils.js";
-import { loadConfig } from "../lib-ts/config.js";
-
-// From lib-ts/ (2 levels up to _core):
-import { logDebug } from "../../_core/lib-ts/runtime/logger.js";
-import { atomicWrite } from "../../_core/lib-ts/runtime/atomic-write.js";
-
-// From plan-review/lib/ (3 levels up to _core):
-import { logInfo } from "../../../_core/lib-ts/runtime/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
-- `../../../_core/lib-ts/runtime/atomic-write.ts` — atomic file I/O
-- `../../../_core/lib-ts/runtime/constants.ts` — `sanitizeFilename`
-- `../../../_core/lib-ts/runtime/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/` → `_core/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 `_core/lib-ts` modules are used across cc-native lib-ts:
-
-| Shared Module | Used By |
-|--------------|---------|
-| `runtime/logger` | All modules (logging) |
-| `runtime/atomic-write` | `state.ts` (crash-safe writes) |
-| `runtime/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 _core/)
-  ↓
-lib-ts/                   (this directory — import from _core/ only)
-  ↓
-_core/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.