aiwcli 0.12.1 → 0.12.2

package/dist/templates/_shared/hooks-ts/session_start.ts

@@ -3,17 +3,18 @@
  * SessionStart hook: Restore context after /clear (plan/handoff) or compaction.
  * Routes by source field to appropriate handler.
  */
-import { getProjectRoot } from "../lib-ts/base/constants.js";
 import {
   loadHookInput, emitContext, runHook, runHookAsync,
   logDebug, logInfo, logError, logDiagnostic,
 } from "../lib-ts/base/hook-utils.js";
-import {
-  buildRestoreSections, formatHandoffContinuation, getModeDisplay,
-} from "../lib-ts/context/context-formatter.js";
+import { getProjectRoot } from "../lib-ts/base/constants.js";
 import {
   getContextBySessionId, getAllContexts, bindSession, updateMode,
 } from "../lib-ts/context/context-store.js";
+import {
+  buildRestoreSections, formatHandoffContinuation, getModeDisplay,
+  buildContextInventory,
+} from "../lib-ts/context/context-formatter.js";
 import type { ContextState } from "../lib-ts/types.js";
 
 /**
@@ -39,6 +40,9 @@ function handleCompactRestore(sessionId: string, projectRoot: string): void {
   const restore = buildRestoreSections(state, projectRoot, true);
   if (restore) sections.push(restore);
 
+  const inventory = buildContextInventory(state, projectRoot);
+  if (inventory) sections.push("", inventory);
+
   sections.push(
     "",
     "---",
@@ -79,6 +83,9 @@ async function handleClearRestore(sessionId: string, projectRoot: string): Promi
     const restore = buildRestoreSections(ctx, projectRoot, false);
     if (restore) sections.push(restore);
 
+    const inventory = buildContextInventory(ctx, projectRoot);
+    if (inventory) sections.push("", inventory);
+
     sections.push(
       "",
       "---",
@@ -100,7 +107,9 @@ async function handleClearRestore(sessionId: string, projectRoot: string): Promi
     logInfo("session_start", `Clear restore: ${ctx.id} has_handoff → active (handoff_consumed=true)`);
 
     const handoffContent = formatHandoffContinuation(ctx, projectRoot);
-    emitContext(handoffContent);
+    const handoffInventory = buildContextInventory(ctx, projectRoot);
+    const combined = handoffInventory ? handoffContent + "\n\n" + handoffInventory : handoffContent;
+    emitContext(combined);
     return;
   }
 
@@ -124,18 +133,15 @@ async function main(): Promise<void> {
   logDiagnostic("session_start", "entry", `source=${source}, session=${sessionId}`);
 
   switch (source) {
-    case "clear": {
-      await handleClearRestore(sessionId, projectRoot);
-      break;
-    }
-    case "compact": {
+    case "compact":
       handleCompactRestore(sessionId, projectRoot);
-      break;
-    }
-    default: {
+      break;
+    case "clear":
+      await handleClearRestore(sessionId, projectRoot);
+      break;
+    default:
       logDebug("session_start", `Unhandled source: ${source}`);
-      break;
-    }
+      break;
   }
 }
 

package/dist/templates/_shared/hooks-ts/user_prompt_submit.ts

@@ -6,14 +6,15 @@
  * Uses emitContext() for output — context text is passed via hookSpecificOutput JSON.
  * Catches BlockRequest and uses emitBlock() to block the prompt.
  */
-import { getProjectRoot } from "../lib-ts/base/constants.js";
 import {
   loadHookInput, runHookAsync, logDebug, logInfo, logWarn, logBlocking, logDiagnostic, hookLog, emitContext, emitBlock,
 } from "../lib-ts/base/hook-utils.js";
-import { determineContext, BlockRequest } from "../lib-ts/context/context-selector.js";
+import { getProjectRoot } from "../lib-ts/base/constants.js";
 import {
   getContextBySessionId, bindSession, maybeActivate, saveState,
 } from "../lib-ts/context/context-store.js";
+import { determineContext, BlockRequest } from "../lib-ts/context/context-selector.js";
+import { buildContextInventory } from "../lib-ts/context/context-formatter.js";
 
 async function asyncMain(): Promise<void> {
   const payload = loadHookInput();
@@ -38,8 +39,8 @@ async function asyncMain(): Promise<void> {
     // Returning user — context already bound (stderr: false to avoid "hook error" display)
     try {
       maybeActivate(existingCtx.id, permissionMode, projectRoot, "user_prompt_submit");
-    } catch (error) {
-      hookLog("warn", "user_prompt_submit", `maybeActivate failed (non-critical): ${error}`, { stderr: false });
+    } catch (e) {
+      hookLog("warn", "user_prompt_submit", `maybeActivate failed (non-critical): ${e}`, { stderr: false });
     }
     hookLog("debug", "user_prompt_submit", `Session bound to ${existingCtx.id}`, { stderr: false });
   } else if (prompt) {
@@ -64,12 +65,23 @@ async function asyncMain(): Promise<void> {
       if (outputText) {
         outputs.push(outputText);
       }
-    } catch (error) {
-      if (error instanceof BlockRequest) {
-        emitBlock((error as Error).message);
+
+      // Append context folder inventory
+      try {
+        const boundState = getContextBySessionId(sessionId, projectRoot);
+        if (boundState) {
+          const inventory = buildContextInventory(boundState, projectRoot);
+          if (inventory) outputs.push(inventory);
+        }
+      } catch (e) {
+        logWarn("user_prompt_submit", `Inventory failed (non-critical): ${e}`);
+      }
+    } catch (e) {
+      if (e instanceof BlockRequest) {
+        emitBlock((e as Error).message);
         return;
       }
-      throw error; // Re-throw unexpected errors
+      throw e; // Re-throw unexpected errors
     }
   }
 

package/dist/templates/_shared/lib-ts/context/context-formatter.ts

@@ -8,9 +8,9 @@
  */
 
 import * as fs from "node:fs";
-import * as _path from "node:path";
-
+import * as path from "node:path";
 import { parseIsoTimestamp } from "../base/utils.js";
+import { getContextDir } from "../base/constants.js";
 import type { ContextState, Task } from "../types.js";
 
 const MAX_PLAN_INLINE_CHARS = 30_000;
@@ -42,10 +42,10 @@ export function getModeDisplay(mode: string): string {
  * Format ISO timestamp as '2 hours ago', 'yesterday', etc.
  * See SPEC.md §11.3
  */
-export function formatRelativeTime(isoTimestamp: null | string): string {
+export function formatRelativeTime(isoTimestamp: string | null): string {
   if (!isoTimestamp) return "unknown";
 
-  const dt = parseIsoTimestamp(isoTimestamp);
+  let dt = parseIsoTimestamp(isoTimestamp);
   if (!dt) return isoTimestamp.slice(0, 16);
 
   const now = new Date();
@@ -62,10 +62,8 @@ export function formatRelativeTime(isoTimestamp: null | string): string {
       if (diffMin === 0) return "just now";
       return diffMin === 1 ? "1 minute ago" : `${diffMin} minutes ago`;
     }
-
     return diffHours === 1 ? "1 hour ago" : `${diffHours} hours ago`;
   }
-
   if (diffDays === 1) return "yesterday";
   if (diffDays < 7) return `${diffDays} days ago`;
 
@@ -80,23 +78,21 @@ export function formatRelativeTime(isoTimestamp: null | string): string {
 // Internal helpers
 // ---------------------------------------------------------------------------
 
-function taskAttr(task: Record<string, any> | Task, key: string, defaultVal = ""): string {
+function taskAttr(task: Task | Record<string, any>, key: string, defaultVal = ""): string {
   if (typeof task === "object" && task !== null) {
     return (task as any)[key] ?? defaultVal;
   }
-
   return defaultVal;
 }
 
-function readPlanContent(planPath: string): [null | string, boolean, number] {
+function readPlanContent(planPath: string): [string | null, boolean, number] {
   try {
     if (!fs.existsSync(planPath)) return [null, false, 0];
-    const content = fs.readFileSync(planPath, "utf8");
+    const content = fs.readFileSync(planPath, "utf-8");
     const total = content.length;
     if (total > MAX_PLAN_INLINE_CHARS) {
       return [content.slice(0, MAX_PLAN_INLINE_CHARS), true, total];
     }
-
     return [content, false, total];
   } catch {
     return [null, false, 0];
@@ -105,7 +101,7 @@ function readPlanContent(planPath: string): [null | string, boolean, number] {
 
 function modeLabel(ctx: ContextState): string {
   const d = getModeDisplay(ctx.mode ?? "idle");
-  return d ? d.replaceAll(/^\[|\]$/g, "") : "Active";
+  return d ? d.replace(/^\[|\]$/g, "") : "Active";
 }
 
 /**
@@ -124,7 +120,7 @@ export function buildRestoreSections(
     const savedAt = lastSession.saved_at ?? "";
     if (savedAt) {
       const reason = lastSession.save_reason ?? "";
-      const reasonDisplay = reason ? reason.replaceAll('_', " ") : "unknown";
+      const reasonDisplay = reason ? reason.replace(/_/g, " ") : "unknown";
       sections.push(`**Last session ended:** ${formatRelativeTime(savedAt)} (${reasonDisplay})`);
     }
   }
@@ -143,7 +139,6 @@ export function buildRestoreSections(
         buckets[s]!.push(taskAttr(t, "subject"));
       }
     }
-
     if (Object.values(buckets).some(b => b.length > 0)) {
       sections.push("", `### Previous Work (${tasks.length} tasks)`, "");
       const marks: Record<string, string> = {
@@ -201,7 +196,8 @@ function resumeBlock(ctx: ContextState, projectRoot: string | undefined, modeTex
   ];
   const restore = buildRestoreSections(ctx, projectRoot, true);
   if (restore) lines.push(restore);
-  lines.push("", "---", "", "**Instructions:**", ...instructions);
+  lines.push("", "---", "", "**Instructions:**");
+  lines.push(...instructions);
   return lines.join("\n");
 }
 
@@ -223,12 +219,12 @@ export function formatHandoffContinuation(ctx: ContextState, projectRoot?: strin
 
   try {
     if (handoffPath && fs.existsSync(handoffPath)) {
-      lines.push("### Previous Session Handoff", "", fs.readFileSync(handoffPath, "utf8"), "");
+      lines.push("### Previous Session Handoff", "", fs.readFileSync(handoffPath, "utf-8"), "");
     } else {
       lines.push(`*Handoff document not found at \`${handoffPath}\`*`, "");
     }
-  } catch (error: any) {
-    lines.push(`*Handoff document at \`${handoffPath}\` could not be read: ${error}*`, "");
+  } catch (e: any) {
+    lines.push(`*Handoff document at \`${handoffPath}\` could not be read: ${e}*`, "");
   }
 
   const restore = buildRestoreSections(ctx, projectRoot, true);
@@ -271,21 +267,20 @@ export function formatContextList(contexts: ContextState[]): string {
   if (contexts.length === 0) return "No active contexts found.";
 
   const lines = ["## Active Contexts\n"];
-  for (const [i, context_] of contexts.entries()) {
-    const ctx = context_!;
+  for (let i = 0; i < contexts.length; i++) {
+    const ctx = contexts[i]!;
     const timeStr = formatRelativeTime(ctx.last_active);
     const md = getModeDisplay(ctx.mode ?? "idle");
     const si = md ? ` ${md}` : "";
-    lines.push(`**${i + 1}. ${ctx.id}**${si}`, `   ${ctx.summary}`);
+    lines.push(`**${i + 1}. ${ctx.id}**${si}`);
+    lines.push(`   ${ctx.summary}`);
     if (ctx.method) {
       lines.push(`   Method: ${ctx.method} | Last active: ${timeStr}`);
     } else {
       lines.push(`   Last active: ${timeStr}`);
     }
-
     lines.push("");
   }
-
   return lines.join("\n");
 }
 
@@ -355,11 +350,11 @@ export function formatContextPickerStderr(contexts: ContextState[]): string {
   ];
 
   let selectableCount = 0;
-  for (const [i, context_] of contexts.entries()) {
-    const ctx = context_!;
+  for (let i = 0; i < contexts.length; i++) {
+    const ctx = contexts[i]!;
     const timeStr = formatRelativeTime(ctx.last_active);
     const mode = ctx.mode ?? "idle";
-    const isSelectable = mode === "active" || Boolean(ctx.handoff_path);
+    const isSelectable = mode === "active" || !!ctx.handoff_path;
     if (isSelectable) selectableCount++;
 
     let status = "";
@@ -372,7 +367,10 @@ export function formatContextPickerStderr(contexts: ContextState[]): string {
     const summary = ctx.summary.length > 48 ? ctx.summary.slice(0, 45) + "..." : ctx.summary;
     const selTag = isSelectable ? " [selectable]" : " [end only]";
 
-    lines.push(`|  ^${i + 1}  ${ctx.id}${status}${selTag}`, `|       ${summary}`, `|       [${timeStr}]`, "|");
+    lines.push(`|  ^${i + 1}  ${ctx.id}${status}${selTag}`);
+    lines.push(`|       ${summary}`);
+    lines.push(`|       [${timeStr}]`);
+    lines.push("|");
   }
 
   lines.push(
@@ -397,7 +395,6 @@ export function formatContextPickerStderr(contexts: ContextState[]): string {
       "+----------------------------------------------------------------+",
     );
   }
-
   lines.push("");
   return lines.join("\n");
 }
@@ -417,7 +414,6 @@ export function formatCommandFeedback(
       const s = ctx.summary.length > 50 ? ctx.summary.slice(0, 50) + "..." : ctx.summary;
       lines.push(`- **${ctx.id}**: ${s}`);
     }
-
     lines.push("");
   }
 
@@ -433,6 +429,132 @@ export function formatCommandFeedback(
       "Tasks created with TaskCreate will be persisted to this context.",
     );
   }
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Context Inventory
+// ---------------------------------------------------------------------------
+
+/** Collector function: scans one aspect of the context folder, returns markdown or null. */
+type InventoryCollector = (
+  contextId: string,
+  contextDir: string,
+  state: ContextState,
+) => string | null;
+
+/** Descriptions for known context subfolders. */
+const KNOWN_FOLDERS: Record<string, string> = {
+  "plans": "Archived implementation plans from plan mode",
+  "session-transcripts": "JSONL records of previous agent sessions — read these to understand prior work",
+  "handoffs": "Structured briefing documents for session continuity",
+  "reviews": "Plan review artifacts (reviewer verdicts, corroboration reports)",
+};
+
+function collectFolderPath(contextId: string, contextDir: string, state: ContextState): string | null {
+  if (!fs.existsSync(contextDir)) return null;
+  return `**Context folder:** \`${contextDir}\`\n**State file:** \`${path.join(contextDir, "state.json")}\` — contains session history, task records, plan/handoff metadata`;
+}
 
+function collectStatePointers(contextId: string, contextDir: string, state: ContextState): string | null {
+  const pointers: string[] = [];
+  if (state.plan_path) {
+    const exists = fs.existsSync(state.plan_path);
+    pointers.push(`- **Active plan:** \`${state.plan_path}\`${exists ? "" : " (not found)"}`);
+  }
+  if (state.handoff_path) {
+    const exists = fs.existsSync(state.handoff_path);
+    pointers.push(`- **Active handoff:** \`${state.handoff_path}\`${exists ? "" : " (not found)"}`);
+  }
+  if (pointers.length === 0) return null;
+  return "**Key artifacts:**\n" + pointers.join("\n");
+}
+
+function countFilesRecursive(dirPath: string): number {
+  let count = 0;
+  try {
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isFile()) {
+        count++;
+      } else if (entry.isDirectory()) {
+        count += countFilesRecursive(path.join(dirPath, entry.name));
+      }
+    }
+  } catch { /* permission errors, etc. */ }
+  return count;
+}
+
+function collectFolderInventory(contextId: string, contextDir: string, state: ContextState): string | null {
+  if (!fs.existsSync(contextDir)) return null;
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(contextDir, { withFileTypes: true });
+  } catch { return null; }
+
+  const dirs = entries.filter(e => e.isDirectory()).sort((a, b) => a.name.localeCompare(b.name));
+  if (dirs.length === 0) return null;
+
+  const lines: string[] = ["**Available folders:**"];
+  for (const dir of dirs) {
+    const dirPath = path.join(contextDir, dir.name);
+    const desc = KNOWN_FOLDERS[dir.name] ?? "Project-specific artifacts";
+    const fileCount = countFilesRecursive(dirPath);
+    lines.push(`- \`${dir.name}/\` — ${desc} (${fileCount} file${fileCount !== 1 ? "s" : ""})`);
+  }
   return lines.join("\n");
 }
+
+function collectSessionStats(contextId: string, contextDir: string, state: ContextState): string | null {
+  const sessionCount = (state.session_ids ?? []).length;
+  if (sessionCount === 0) return null;
+
+  const transcriptsDir = path.join(contextDir, "session-transcripts");
+  let transcriptCount = 0;
+  let timeRange = "";
+
+  if (fs.existsSync(transcriptsDir)) {
+    try {
+      const files = fs.readdirSync(transcriptsDir).filter(f => f.endsWith(".jsonl")).sort();
+      transcriptCount = files.length;
+      if (files.length > 1) {
+        const oldest = files[0]!.slice(0, 10);
+        const newest = files[files.length - 1]!.slice(0, 10);
+        if (oldest !== newest) timeRange = ` (${oldest} to ${newest})`;
+      }
+    } catch { /* ignore */ }
+  }
+
+  let line = `**Sessions:** ${sessionCount} total`;
+  if (transcriptCount > 0) {
+    line += `, ${transcriptCount} transcript${transcriptCount !== 1 ? "s" : ""} archived${timeRange}`;
+  }
+  return line;
+}
+
+/** Ordered list of inventory collectors. Append new collectors here. */
+const INVENTORY_COLLECTORS: InventoryCollector[] = [
+  collectFolderPath,
+  collectStatePointers,
+  collectFolderInventory,
+  collectSessionStats,
+];
+
+/**
+ * Build a markdown inventory of resources available in the context folder.
+ * Returns null if the context folder doesn't exist yet (brand new context).
+ */
+export function buildContextInventory(
+  state: ContextState,
+  projectRoot: string,
+): string | null {
+  const contextDir = getContextDir(state.id, projectRoot);
+  if (!fs.existsSync(contextDir)) return null;
+
+  const sections = INVENTORY_COLLECTORS
+    .map(c => c(state.id, contextDir, state))
+    .filter((s): s is string => s !== null);
+
+  if (sections.length === 0) return null;
+  return "### Context Resources\n\n" + sections.join("\n\n");
+}

package/dist/templates/_shared/scripts/resume_handoff.ts

@@ -315,6 +315,31 @@ function main(): void {
   out.push("---");
   out.push("");
   out.push("**Create ISC tasks** from the pending items and remaining plan items above using TaskCreate. Each task should be ~8 words, state a desired end-state (not an action), and be binary testable.");
+  out.push("");
+
+  // Appendix: Full Plan
+  let fullPlanContent: string | null = sections.plan ?? null;
+  if (!fullPlanContent && resolvedContextId) {
+    const planRef = getHandoffPlanReference(handoffFolder, resolvedContextId, projectRoot);
+    if (planRef) {
+      try {
+        fullPlanContent = fs.readFileSync(planRef, "utf-8");
+      } catch {
+        // ignore — no plan to append
+      }
+    }
+  }
+  if (fullPlanContent) {
+    const planBody = stripTitle(fullPlanContent);
+    if (planBody && planBody !== "(No content for this section)") {
+      out.push("---");
+      out.push("");
+      out.push("### Appendix: Full Plan");
+      out.push("");
+      out.push(planBody);
+      out.push("");
+    }
+  }
 
   console.log(out.join("\n"));
 }

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

@@ -113,7 +113,7 @@ Each family covers the same topic area but through different analytical lenses.
 ## File Structure
 
 Each agent file has:
-- **Frontmatter (YAML):** name, model, focus, categories, enabled
+- **Frontmatter (YAML):** name, model, focus, categories
 - **Body (Markdown):** Full persona content → becomes `system_prompt` for `--system-prompt` flag
 
 ## --setting-sources "" Requirement
@@ -140,10 +140,4 @@ Each agent file has:
 
 **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.
 
-## enabled: false Convention
 
-**Decision:** Set `enabled: false` in frontmatter for all plan review agents
-
-**Rationale:** The `enabled` field controls Claude Code's auto-suggestion feature (showing agents in command palette). For plan review agents, we don't want them appearing as general-purpose agents - they're invoked programmatically by the hook. Setting `enabled: false` hides them from auto-suggestion while still allowing the hook to use them.
-
-**Constraint:** Don't set `enabled: true` unless you want the agent to appear in Claude Code's agent picker for general use.

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

@@ -1,63 +1,62 @@
----
-name: arch-evolution
-description: Evolutionary architecture analyst who evaluates how well planned architecture accommodates future change. Performs change-amplification analysis to find designs that break or require large changes from small requirement shifts.
-model: sonnet
-focus: evolutionary architecture and change amplification
-enabled: false
-categories:
-  - code
-  - infrastructure
-  - design
----
-
-# Architecture Evolution - Plan Review Agent
-
-You evaluate how well planned architecture handles future change. Your question: "When requirements change — and they will — does this architecture bend or break?"
-
-## Your Core Principle
-
-Evolutionary architecture (Ford, Parsons & Kua 2017) designs for guided, incremental change across multiple dimensions. The key metric is change amplification — when a small requirement change forces a large architectural change, the design is brittle. Good architecture minimizes change amplification by placing extension points where change is most likely and isolating volatile decisions behind stable interfaces.
-
-## Your Expertise
-
-- **Change amplification analysis**: Would a small requirement change force large structural changes?
-- **Extension point evaluation**: Are extension points placed where change is most likely to occur?
-- **Volatility isolation**: Are the most likely-to-change decisions isolated behind stable interfaces?
-- **Future adaptability**: Does this architecture support the probable evolution paths?
-- **Fitness function identification**: What measurable properties should guide this architecture's evolution?
-
-## Review Approach
-
-Evaluate the plan's evolutionary fitness:
-
-1. **Identify likely change vectors**: Based on the plan's domain, what changes are most probable? (New features, scaling needs, integration requirements, technology updates)
-2. **Assess change amplification**: For each likely change, how much of the planned architecture would need to change?
-3. **Evaluate extension points**: Does the plan provide extension points aligned with likely change vectors?
-4. **Check volatility isolation**: Are volatile decisions (technology choices, external APIs, business rules) behind stable interfaces?
-5. **Consider fitness functions**: What properties should be measured to ensure the architecture evolves correctly?
-
-## Key Distinction
-
-| Agent | Asks |
-|-------|------|
-| arch-structure | "Are boundaries at natural seams?" |
-| arch-patterns | "Is the chosen pattern appropriate?" |
-| **arch-evolution** | **"When requirements change, does this bend or break?"** |
-
-## CRITICAL: Single-Turn Review
-
-When reviewing a plan:
-1. Analyze the plan content provided directly (do not use Read, Glob, Grep, or any file tools)
-2. Call StructuredOutput immediately with your assessment
-3. Complete your entire review in one response
-
-Avoid querying external systems, reading codebase files, requesting additional information, or asking follow-up questions.
-
-## Required Output
-
-Call StructuredOutput with exactly these fields:
-- **verdict**: "pass" (architecture supports evolution), "warn" (some rigidity concerns), or "fail" (brittle architecture that resists change)
-- **summary**: 2-3 sentences explaining evolutionary fitness assessment (minimum 20 characters)
-- **issues**: Array of evolution concerns, each with: severity (high/medium/low), category (e.g., "change-amplification", "missing-extension-point", "volatility-exposure", "brittle-coupling", "fitness-gap"), issue description, suggested_fix (add extension point, isolate volatile decision, reduce change amplification)
-- **missing_sections**: Evolution considerations the plan should address (likely change vectors, extension points, volatility isolation)
-- **questions**: Evolution aspects that need investigation
+---
+name: arch-evolution
+description: Evolutionary architecture analyst who evaluates how well planned architecture accommodates future change. Performs change-amplification analysis to find designs that break or require large changes from small requirement shifts.
+model: sonnet
+focus: evolutionary architecture and change amplification
+categories:
+  - code
+  - infrastructure
+  - design
+---
+
+# Architecture Evolution - Plan Review Agent
+
+You evaluate how well planned architecture handles future change. Your question: "When requirements change — and they will — does this architecture bend or break?"
+
+## Your Core Principle
+
+Evolutionary architecture (Ford, Parsons & Kua 2017) designs for guided, incremental change across multiple dimensions. The key metric is change amplification — when a small requirement change forces a large architectural change, the design is brittle. Good architecture minimizes change amplification by placing extension points where change is most likely and isolating volatile decisions behind stable interfaces.
+
+## Your Expertise
+
+- **Change amplification analysis**: Would a small requirement change force large structural changes?
+- **Extension point evaluation**: Are extension points placed where change is most likely to occur?
+- **Volatility isolation**: Are the most likely-to-change decisions isolated behind stable interfaces?
+- **Future adaptability**: Does this architecture support the probable evolution paths?
+- **Fitness function identification**: What measurable properties should guide this architecture's evolution?
+
+## Review Approach
+
+Evaluate the plan's evolutionary fitness:
+
+1. **Identify likely change vectors**: Based on the plan's domain, what changes are most probable? (New features, scaling needs, integration requirements, technology updates)
+2. **Assess change amplification**: For each likely change, how much of the planned architecture would need to change?
+3. **Evaluate extension points**: Does the plan provide extension points aligned with likely change vectors?
+4. **Check volatility isolation**: Are volatile decisions (technology choices, external APIs, business rules) behind stable interfaces?
+5. **Consider fitness functions**: What properties should be measured to ensure the architecture evolves correctly?
+
+## Key Distinction
+
+| Agent | Asks |
+|-------|------|
+| arch-structure | "Are boundaries at natural seams?" |
+| arch-patterns | "Is the chosen pattern appropriate?" |
+| **arch-evolution** | **"When requirements change, does this bend or break?"** |
+
+## CRITICAL: Single-Turn Review
+
+When reviewing a plan:
+1. Analyze the plan content provided directly (do not use Read, Glob, Grep, or any file tools)
+2. Call StructuredOutput immediately with your assessment
+3. Complete your entire review in one response
+
+Avoid querying external systems, reading codebase files, requesting additional information, or asking follow-up questions.
+
+## Required Output
+
+Call StructuredOutput with exactly these fields:
+- **verdict**: "pass" (architecture supports evolution), "warn" (some rigidity concerns), or "fail" (brittle architecture that resists change)
+- **summary**: 2-3 sentences explaining evolutionary fitness assessment (minimum 20 characters)
+- **issues**: Array of evolution concerns, each with: severity (high/medium/low), category (e.g., "change-amplification", "missing-extension-point", "volatility-exposure", "brittle-coupling", "fitness-gap"), issue description, suggested_fix (add extension point, isolate volatile decision, reduce change amplification)
+- **missing_sections**: Evolution considerations the plan should address (likely change vectors, extension points, volatility isolation)
+- **questions**: Evolution aspects that need investigation