aiwcli 0.11.0 → 0.12.0

package/dist/templates/cc-native/_cc-native/lib-ts/cc-native-state.ts

@@ -1,18 +1,19 @@
 /**
  * CC-native state accessor for context state.json.
- * Deduplicates state access patterns for cc-native hooks.
+ * Deduplicates state access patterns from utils.py and suggest-fresh-perspective.py.
  * See cc-native-plan-review-spec.md §4.5
  */
 
+import { getContextBySessionId, saveState } from "../../_shared/lib-ts/context/context-store.js";
+import { logInfo, logWarn } from "../../_shared/lib-ts/base/logger.js";
+import { nowIso } from "../../_shared/lib-ts/base/utils.js";
 import type {
   CcNativeState,
-  IterationState,
   PlanReviewState,
-  QuestionsAskedState as _QuestionsAskedState,
+  QuestionsAskedState,
+  IterationState,
+  StuckDetectionState,
 } from "./types.js";
-import { logInfo, logWarn } from "../../_shared/lib-ts/base/logger.js";
-import { nowIso } from "../../_shared/lib-ts/base/utils.js";
-import { getContextBySessionId, saveState } from "../../_shared/lib-ts/context/context-store.js";
 import type { ContextState } from "../../_shared/lib-ts/types.js";
 
 /**
@@ -42,7 +43,6 @@ export function getCcNativeState(
   } catch {
     // Fail-safe: return null
   }
-
   return null;
 }
 
@@ -62,10 +62,9 @@ export function saveCcNativeState(
       saveState(state.id, state, projectRoot);
       return true;
     }
-  } catch (error: unknown) {
-    logWarn("utils", `Failed to save cc_native state: ${error}`);
+  } catch (e: unknown) {
+    logWarn("utils", `Failed to save cc_native state: ${e}`);
   }
-
   return false;
 }
 
@@ -104,6 +103,22 @@ export function wasPlanPreviouslyDenied(
   return decision === "deny" || decision.startsWith("hook_deny");
 }
 
+/**
+ * Get the last plan review state for this session.
+ * Returns null if no review state exists or plan hash doesn't match.
+ */
+export function getLastPlanReview(
+  sessionId: string,
+  planHash: string,
+  projectRoot: string,
+): PlanReviewState | null {
+  const ccNative = getCcNativeState(sessionId, projectRoot);
+  if (!ccNative) return null;
+  const reviewState = ccNative.plan_review;
+  if (reviewState?.plan_hash !== planHash) return null;
+  return reviewState;
+}
+
 /**
  * Mark this plan as reviewed (stores hash and decision in state.json).
  */
@@ -130,9 +145,9 @@ export function markPlanReviewed(
         max: iterationState.max ?? 1,
         complexity: iterationState.complexity ?? "unknown",
       };
-      const {history} = iterationState;
+      const history = iterationState.history;
       if (history && history.length > 0) {
-        const lastEntry = history.at(-1);
+        const lastEntry = history[history.length - 1];
         if (lastEntry) {
           reviewData.iteration.latest_verdict = lastEntry.verdict ?? "unknown";
         }
@@ -152,8 +167,8 @@ export function markPlanReviewed(
         `Failed to save plan review state for session ${sessionId}`,
       );
     }
-  } catch (error: unknown) {
-    logWarn(hookName, `Failed to mark plan reviewed: ${error}`);
+  } catch (e: unknown) {
+    logWarn(hookName, `Failed to mark plan reviewed: ${e}`);
   }
 }
 
@@ -191,8 +206,41 @@ export function markQuestionsAsked(
     };
 
     return saveCcNativeState(sessionId, projectRoot, ccNative);
-  } catch (error: unknown) {
-    logWarn("utils", `Failed to mark questions asked: ${error}`);
+  } catch (e: unknown) {
+    logWarn("utils", `Failed to mark questions asked: ${e}`);
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Stuck Detection State
+// ---------------------------------------------------------------------------
+
+/**
+ * Get stuck detection state from cc_native.
+ */
+export function getStuckDetectionState(
+  sessionId: string,
+  projectRoot: string,
+): StuckDetectionState | null {
+  const ccNative = getCcNativeState(sessionId, projectRoot);
+  return ccNative?.stuck_detection ?? null;
+}
+
+/**
+ * Update stuck detection state.
+ */
+export function updateStuckDetectionState(
+  sessionId: string,
+  projectRoot: string,
+  stuckState: StuckDetectionState,
+): boolean {
+  try {
+    const ccNative = getCcNativeState(sessionId, projectRoot) ?? {};
+    ccNative.stuck_detection = stuckState;
+    return saveCcNativeState(sessionId, projectRoot, ccNative);
+  } catch (e: unknown) {
+    logWarn("utils", `Failed to update stuck detection state: ${e}`);
     return false;
   }
 }

package/dist/templates/cc-native/_cc-native/lib-ts/cli-output-parser.ts

@@ -1,6 +1,6 @@
 /**
  * Unified Claude CLI output parser.
- * Deduplicates identical logic from orchestrator.py and reviewers/agent.py.
+ * Deduplicates identical logic from orchestrator.ts and reviewers/agent.ts.
  * See cc-native-plan-review-spec.md §4.6
  */
 
@@ -36,6 +36,26 @@ export function parseCliOutput(
         return dict.structured_output as Record<string, unknown>;
       }
 
+      // Strategy 1.5: Session result envelope (type: "result")
+      // When the model fails to call StructuredOutput, the CLI returns a
+      // session metadata object with type/subtype/duration_ms/usage/etc.
+      // but no structured_output key. Check for the `result` text field
+      // (model may have written review as text) and for error states.
+      if (dict.type === "result" || ("duration_ms" in dict && "session_id" in dict)) {
+        if (dict.is_error === true || (Array.isArray(dict.errors) && (dict.errors as unknown[]).length > 0)) {
+          logWarn("cli_parser", `CLI returned error result: ${JSON.stringify(dict.errors ?? "is_error=true")}`);
+          return null;
+        }
+        if (typeof dict.result === "string" && dict.result) {
+          logDebug("cli_parser", "Found result text in session envelope, attempting JSON extraction");
+          const extracted = parseJsonMaybe(dict.result as string, requireFields);
+          if (extracted) return extracted;
+          logWarn("cli_parser", "Session envelope result text contained no extractable JSON");
+        }
+        logDebug("cli_parser", "Session result envelope with no structured_output or extractable result");
+        return null;
+      }
+
       // Strategy 2: Assistant message with StructuredOutput tool use
       if (dict.type === "assistant") {
         const message = dict.message as Record<string, unknown> | undefined;
@@ -57,7 +77,7 @@ export function parseCliOutput(
               >;
             }
           }
-        }
+        }
 
         logDebug(
           "cli_parser",
@@ -97,7 +117,7 @@ export function parseCliOutput(
             }
           }
         }
-      }
+      }
 
       logDebug(
         "cli_parser",

package/dist/templates/cc-native/_cc-native/lib-ts/corroboration.ts

@@ -0,0 +1,119 @@
+/**
+ * Corroboration-based verdict computation for plan review.
+ *
+ * Replaces the old per-verdict aggregation with proportional thresholding:
+ * high-severity issues in a dimension only block when the total count
+ * exceeds 2× the number of distinct agents contributing to that dimension.
+ *
+ * **Why proportional thresholding:**
+ * The agent pool has dimensional imbalance (e.g., 10 completeness agents vs
+ * 1 maintainability agent). A fixed "2+ agents agree = block" would mean
+ * any 2 completeness agents always block. Proportional scaling (issues > 2×agents)
+ * sets a fair bar regardless of how many agents focus on each dimension.
+ *
+ * **Convergence problem this solves:**
+ * Agents with opposing philosophies (simplicity-guardian vs completeness-gaps)
+ * produce contradictory high-severity issues. Because the old system treated
+ * every agent's finding as independently authoritative, plans oscillated —
+ * addressing one agent's feedback triggered the opposing agent.
+ *
+ * **Revert path:** Change one line in cc-native-plan-review.ts back to
+ * `computeReviewDecision(allVerdicts)`. Old function kept in verdict.ts.
+ */
+
+import type {
+  ReviewerResult,
+  ReviewIssue,
+  IssueDimension,
+  CorroborationResult,
+  CorroboratedGroup,
+  SoloFinding,
+} from "./types.js";
+
+/**
+ * Compute a corroboration-based review decision from all reviewer results.
+ *
+ * Algorithm:
+ * 1. Collect all high-severity issues with a `dimension` field
+ * 2. Group by dimension, tracking distinct agent names per group
+ * 3. For each dimension: block if `issues.length > 2 × agentCount`
+ * 4. Issues without `dimension` are unclassified (never block)
+ * 5. Non-high issues are ignored (informational only)
+ *
+ * @param allResults - Map of reviewer name → ReviewerResult (CLI + agent)
+ * @returns CorroborationResult with blocking groups, solo findings, and verdict
+ */
+export function computeCorroboratedDecision(
+  allResults: Record<string, ReviewerResult>,
+): CorroborationResult {
+  // Accumulator: dimension → { issues, agentNames }
+  const dimMap = new Map<
+    IssueDimension,
+    {
+      issues: Array<{ agent: string; issue: ReviewIssue }>;
+      agentNames: Set<string>;
+    }
+  >();
+
+  const unclassified: Array<{ agent: string; issue: ReviewIssue }> = [];
+
+  for (const [agentName, result] of Object.entries(allResults)) {
+    if (!result.data) continue;
+    const issues = result.data.issues as ReviewIssue[] | undefined;
+    if (!Array.isArray(issues)) continue;
+
+    for (const issue of issues) {
+      // Only high-severity issues participate in corroboration
+      if (issue.severity !== "high") continue;
+
+      // Issues without dimension are unclassified — cannot block
+      if (!issue.dimension) {
+        unclassified.push({ agent: agentName, issue });
+        continue;
+      }
+
+      let group = dimMap.get(issue.dimension);
+      if (!group) {
+        group = { issues: [], agentNames: new Set() };
+        dimMap.set(issue.dimension, group);
+      }
+      group.issues.push({ agent: agentName, issue });
+      group.agentNames.add(agentName);
+    }
+  }
+
+  const blocking: CorroboratedGroup[] = [];
+  const solo: SoloFinding[] = [];
+
+  for (const [dimension, group] of dimMap) {
+    const agentCount = group.agentNames.size;
+    const threshold = 2 * agentCount;
+
+    if (group.issues.length >= threshold) {
+      blocking.push({
+        dimension,
+        issues: group.issues,
+        agentCount,
+        threshold,
+      });
+    } else {
+      solo.push({
+        dimension,
+        issues: group.issues,
+        agentCount,
+        threshold,
+      });
+    }
+  }
+
+  return {
+    blocking,
+    solo,
+    unclassified,
+    verdict: blocking.length > 0
+      ? "fail"
+      : solo.length > 0
+        ? "warn"
+        : "pass",
+  };
+}

package/dist/templates/cc-native/_cc-native/lib-ts/index.ts

@@ -64,15 +64,12 @@ export { buildOrchestratorSchema, runOrchestrator } from "./orchestrator.js";
 // Reviewers
 export {
   AgentReviewer,
-  CodexReviewer,
-  GeminiReviewer,
   runAgentReview,
-  runCodexReview,
-  runGeminiReview,
 } from "./reviewers/index.js";
 
 // Iteration state
 export {
+  DEFAULT_REVIEW_ITERATIONS,
   deleteState,
   getIterationState,
   getStateFilePath,

package/dist/templates/cc-native/_cc-native/lib-ts/json-parser.ts

@@ -73,6 +73,12 @@ export function parseJsonMaybe(
         `Parsed JSON (${parseMethod}) missing/empty fields: ${JSON.stringify(missing)}`,
       );
       logDebug("parse", `Keys present: ${JSON.stringify(Object.keys(obj))}`);
+      // Heuristic extraction grabbed the wrong object — reject it.
+      // Strict parse still returns partial objects (caller handles defaults).
+      if (parseMethod === "heuristic") {
+        logWarn("parse", "Rejecting heuristic result due to missing required fields");
+        return null;
+      }
     }
   }
 
@@ -137,7 +143,7 @@ export function coerceToReview(
       "coerce",
       `verdict=${obj.verdict}, issues_count=${Array.isArray(obj.issues) ? (obj.issues as unknown[]).length : 0}`,
     );
-  }
+  }
 
   if (!obj.issues) {
     logDebug("coerce", "issues array empty or missing");

package/dist/templates/cc-native/_cc-native/lib-ts/orchestrator.ts

@@ -1,67 +1,15 @@
 /**
  * Plan orchestrator — analyzes complexity and selects reviewer agents.
+ * Uses OrchestratorClaudeAgent (BaseCliAgent framework) for subprocess execution.
  * See cc-native-plan-review-spec.md §4.8
  */
 
-import { parseCliOutput } from "./cli-output-parser.js";
-import type { AgentConfig, ComplexityCategory, OrchestratorConfig, OrchestratorResult } from "./types.js";
-import { ORCHESTRATOR_SCHEMA } from "./types.js";
-import { logDebug, logError, logInfo, logWarn } from "../../_shared/lib-ts/base/logger.js";
-import { execFileAsync, findExecutable, getInternalSubprocessEnv } from "../../_shared/lib-ts/base/subprocess-utils.js";
+import { logInfo, logWarn } from "../../_shared/lib-ts/base/logger.js";
+import type { AgentConfig, OrchestratorConfig, OrchestratorResult } from "./types.js";
+import { OrchestratorClaudeAgent } from "./reviewers/providers/orchestrator-claude-agent.js";
 
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-const DEFAULT_AGENT_SELECTION: Record<string, unknown> = {
-  simple: { min: 3, max: 3 },
-  medium: { min: 8, max: 8 },
-  high: { min: 12, max: 12 },
-  fallbackCount: 3,
-};
-
-const DEFAULT_COMPLEXITY_CATEGORIES = [
-  "code",
-  "infrastructure",
-  "documentation",
-  "life",
-  "business",
-  "design",
-  "research",
-];
-
-// ---------------------------------------------------------------------------
-// Schema Builder
-// ---------------------------------------------------------------------------
-
-/**
- * Build orchestrator JSON schema with enum-constrained agent names.
- */
-export function buildOrchestratorSchema(
-  validAgentNames: string[],
-  categories: string[],
-): Record<string, unknown> {
-  const itemsSchema: Record<string, unknown> = { type: "string" };
-  if (validAgentNames.length > 0) {
-    itemsSchema.enum = validAgentNames;
-  }
-
-  return {
-    type: "object",
-    properties: {
-      complexity: { type: "string", enum: ["simple", "medium", "high"] },
-      category: { type: "string", enum: categories },
-      selectedAgents: {
-        type: "array",
-        items: itemsSchema,
-      },
-      reasoning: { type: "string" },
-      skipReason: { type: "string" },
-    },
-    required: ["complexity", "category", "selectedAgents", "reasoning"],
-    additionalProperties: false,
-  };
-}
+// Re-export for backward compatibility (moved to reviewers/schemas.ts)
+export { buildOrchestratorSchema } from "./reviewers/schemas.js";
 
 // ---------------------------------------------------------------------------
 // Orchestrator
@@ -81,169 +29,43 @@ export async function runOrchestrator(
   logInfo("orchestrator", "Starting plan analysis...");
 
   const mandatory = mandatoryNames ?? new Set<string>();
-  const selection = (settings.agentSelection as Record<string, unknown>) ?? DEFAULT_AGENT_SELECTION;
-  const categories = (settings.complexityCategories as string[]) ?? DEFAULT_COMPLEXITY_CATEGORIES;
-  const fallbackCount = (selection.fallbackCount as number) ?? 2;
 
-  // Filter out mandatory agents — they always run
-  const nonMandatory = agentLibrary.filter(
-    (a) => a.enabled && !mandatory.has(a.name),
-  );
-  const validNames = nonMandatory.map((a) => a.name);
-
-  logDebug("orchestrator", `Mandatory agents (always run): ${[...mandatory].sort().join(", ")}`);
-  logDebug("orchestrator", `Non-mandatory agents for selection: ${validNames.join(", ")}`);
+  // Create a synthetic AgentConfig for the orchestrator
+  const orchestratorAgent: AgentConfig = {
+    name: "orchestrator",
+    model: config.model,
+    provider: "claude",
+    focus: "plan analysis and agent selection",
+    enabled: config.enabled,
+    categories: [],
+    description: "Plan orchestrator",
+    system_prompt: "",
+  };
 
-  const claudePath = findExecutable("claude");
-  if (!claudePath) {
-    logWarn(
-      "orchestrator",
-      "Claude CLI not found on PATH, falling back to medium complexity",
+  try {
+    const agent = new OrchestratorClaudeAgent(
+      orchestratorAgent,
+      agentLibrary,
+      mandatory,
+      settings,
+      config.timeout,
     );
-    return makeFallback(nonMandatory, fallbackCount, "Orchestrator skipped - Claude CLI not found", "claude CLI not found on PATH");
-  }
-
-  logDebug("orchestrator", `Found Claude CLI at: ${claudePath}`);
-
-  // Build agent list from non-mandatory agents
-  const agentList = nonMandatory
-    .map(
-      (a) =>
-        `- ${a.name} [${a.categories.join(", ")}]\n  Focus: ${a.focus}\n  Expertise: ${a.description}`,
-    )
-    .join("\n");
-  const categoryList = categories.join("/");
-
-  // Compute additional agent counts
-  const mandatoryCount = agentLibrary.filter((a) => mandatory.has(a.name)).length;
-  const simpleAdditional = Math.max(0, ((selection.simple as Record<string, number> | undefined)?.max ?? 3) - mandatoryCount);
-  const mediumAdditional = Math.max(0, ((selection.medium as Record<string, number> | undefined)?.max ?? 8) - mandatoryCount);
-  const highAdditional = Math.max(0, ((selection.high as Record<string, number> | undefined)?.max ?? 12) - mandatoryCount);
-
-  const systemPrompt = `You are a plan orchestrator for code review. Your job is to analyze plans and select appropriate reviewer agents.
-
-You MUST call StructuredOutput immediately with your analysis. Do NOT ask questions or use any other tools.
-
-When selecting agents:
-- Match agent expertise to plan requirements
-- Consider what each agent specializes in
-- Only select agents whose categories match the plan category
-- Fewer agents for simple plans, more for complex plans`;
-
-  const prompt = `Analyze this plan and select appropriate reviewer agents.
-
-Available agents (select ONLY from this list):
-${agentList}
-
-Selection rules (number of ADDITIONAL agents to select from the list above):
-- simple complexity = ${simpleAdditional} agents
-- medium complexity = ${mediumAdditional} agents
-- high complexity = ${highAdditional} agents
-- Only select agents whose categories match the plan category (${categoryList})
-- Non-technical plans (life, business) typically need 0 code-focused agents
-- Note: mandatory agents run separately and are NOT listed above
-
-PLAN:
-<<<
-${plan}
->>>
 
-Call StructuredOutput now with: complexity, category, selectedAgents, reasoning`;
-
-  const schema =
-    validNames.length > 0
-      ? buildOrchestratorSchema(validNames, categories)
-      : ORCHESTRATOR_SCHEMA;
-  const schemaJson = JSON.stringify(schema);
-
-  const cmdArgs = [
-    "--model", config.model,
-    "--output-format", "json",
-    "--json-schema", schemaJson,
-    "--max-turns", "3",
-    "--setting-sources", "",
-    "--system-prompt", systemPrompt,
-    "-p",
-  ];
-
-  logInfo("orchestrator", `Running with model: ${config.model}, timeout: ${config.timeout}s`);
-
-  const env = getInternalSubprocessEnv();
-
-  const result = await execFileAsync(claudePath, cmdArgs, {
-    input: prompt,
-    timeout: config.timeout * 1000,
-    env: env as Record<string, string>,
-    maxBuffer: 10 * 1024 * 1024,
-  });
-
-  if (result.killed || result.signal === "SIGTERM") {
-    logWarn("orchestrator", `TIMEOUT after ${config.timeout}s, falling back to medium complexity`);
-    return makeFallback(nonMandatory, fallbackCount, "Orchestrator timed out - defaulting to medium complexity", `Orchestrator timed out after ${config.timeout}s`);
-  }
-
-  const raw = result.stdout.trim();
-  if (result.stderr) logDebug("orchestrator", `stderr: ${result.stderr.slice(0, 300)}`);
-
-  if (!raw && !result.stderr && result.exitCode !== 0) {
-    logError("orchestrator", `Process exited with code ${result.exitCode}, falling back to medium complexity`);
-    return makeFallback(nonMandatory, fallbackCount, `Orchestrator failed (exit ${result.exitCode})`, `Exit code ${result.exitCode}`);
-  }
-
-  const obj = parseCliOutput(raw);
-
-  logDebug("orchestrator", `Raw output length: ${raw.length} chars`);
-  if (raw) logDebug("orchestrator", `Raw output (first 500 chars): ${raw.slice(0, 500)}`);
-  logDebug("orchestrator", `Parsed obj: ${JSON.stringify(obj)}`);
-
-  if (!obj) {
-    logWarn("orchestrator", "Failed to parse output, falling back to medium complexity");
-    return makeFallback(nonMandatory, fallbackCount, "Orchestrator output could not be parsed", "Failed to parse orchestrator output");
+    const result = await agent.review(plan);
+
+    logInfo("orchestrator", `Result: complexity=${result.complexity}, category=${result.category}, agents=${JSON.stringify(result.selected_agents)}`);
+
+    return result;
+  } catch (e) {
+    logWarn("orchestrator", `Unexpected error: ${e}`);
+    const nonMandatory = agentLibrary.filter((a) => a.enabled && !mandatory.has(a.name));
+    const fallbackCount = ((settings.agentSelection as Record<string, unknown>)?.fallbackCount as number) ?? 2;
+    return {
+      complexity: "medium",
+      category: "code",
+      selected_agents: nonMandatory.slice(0, fallbackCount).map((a) => a.name),
+      reasoning: `Orchestrator failed: ${e}`,
+      error: String(e),
+    };
   }
-
-  // Extract and validate fields
-  const rawComplexity = String(obj.complexity ?? "medium");
-  const complexity: ComplexityCategory =
-    rawComplexity === "simple" || rawComplexity === "medium" || rawComplexity === "high"
-      ? rawComplexity
-      : "medium";
-
-  let category = (obj.category as string) ?? "code";
-  if (!categories.includes(category)) category = "code";
-
-  let {selectedAgents} = obj;
-  if (!Array.isArray(selectedAgents)) selectedAgents = [];
-
-  const reasoning = String(obj.reasoning ?? "").trim() || "No reasoning provided";
-  const skipReason = obj.skipReason as string | undefined;
-
-  logInfo("orchestrator", `Result: complexity=${complexity}, category=${category}, agents=${JSON.stringify(selectedAgents)}`);
-  logDebug("orchestrator", `Reasoning: ${reasoning}`);
-
-  return {
-    complexity,
-    category,
-    selected_agents: selectedAgents as string[],
-    reasoning,
-    skip_reason: skipReason || undefined,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-function makeFallback(
-  nonMandatory: AgentConfig[],
-  fallbackCount: number,
-  reasoning: string,
-  error: string,
-): OrchestratorResult {
-  return {
-    complexity: "medium",
-    category: "code",
-    selected_agents: nonMandatory.slice(0, fallbackCount).map((a) => a.name),
-    reasoning,
-    error,
-  };
 }

package/dist/templates/cc-native/_cc-native/lib-ts/plan-enhancement.ts

@@ -0,0 +1,41 @@
+/**
+ * Plan quality guidance for context emission.
+ *
+ * Provides prompt text that guides the main agent to review plans before
+ * presenting them to the user. Emitted via emitContext() — NOT appended to plan files.
+ *
+ * Used by both SubagentStop hook (Plan agents) and PostToolUse:Write hook (direct writes).
+ */
+
+/**
+ * Returns the plan quality review prompt to emit as context after a plan is written.
+ * This guides the main agent to review the plan before calling ExitPlanMode.
+ *
+ * Design principles:
+ * - No hardcoded skill names — agent discovers relevant skills from system-reminders
+ * - Documentation focuses on WHY (preserve decisions) not WHERE (file paths)
+ * - Concise — every token in emitted context costs attention budget
+ * - Trusts the agent's judgment — guidance, not mandate
+ */
+export function getPlanQualityReviewContext(): string {
+  return `## Plan Quality Review
+
+Before presenting this plan, review it from the perspective of an agent with zero conversation history.
+
+### Self-Check
+- File paths are absolute and verified (not "the auth file" or "as discussed")
+- Function and class names are exact references (not "the handler" or "it")
+- Each step is specific enough to execute without this conversation's context
+- Verification steps are binary-testable (pass/fail in one check)
+
+### Skills Integration
+Review the skills listed in your system-reminder messages. Where a step would benefit from a specific skill, reference it inline (e.g., "Use \`SkillName\` skill for [specific purpose]"). Only reference skills relevant to this plan's domain.
+
+### Documentation Reasoning
+Evaluate whether the plan captures decisions that would be lost when this session ends. The implementation agent should understand:
+- What was decided and why alternatives were rejected
+- What constraints exist that aren't obvious from the code
+- What would break if assumptions change
+
+If the plan has gaps, address them before presenting to the user.`;
+}