aiwcli 0.11.1 → 0.12.1

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 { logDebug, logInfo, logWarn, logError } from "../../_shared/lib-ts/base/logger.js";
-import { getInternalSubprocessEnv, findExecutable, execFileAsync } from "../../_shared/lib-ts/base/subprocess-utils.js";
-import { parseCliOutput } from "./cli-output-parser.js";
-import type { AgentConfig, OrchestratorConfig, OrchestratorResult, ComplexityCategory } from "./types.js";
-import { ORCHESTRATOR_SCHEMA } from "./types.js";
+import { OrchestratorClaudeAgent } from "./reviewers/providers/orchestrator-claude-agent.js";
+import type { AgentConfig, OrchestratorConfig, OrchestratorResult } from "./types.js";
+import { logInfo, logWarn } from "../../_shared/lib-ts/base/logger.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,170 +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,
-    shell: process.platform === "win32",
-  });
-
-  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 (error) {
+    logWarn("orchestrator", `Unexpected error: ${error}`);
+    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: ${error}`,
+      error: String(error),
+    };
   }
-
-  // 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.selectedAgents;
-  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.`;
+}

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

@@ -0,0 +1,102 @@
+/**
+ * Plan question generation — runs a fresh-context agent to identify
+ * questions, assumptions, and ambiguities in a plan before review.
+ * See cc-native-plan-review.ts for integration point (questions gate).
+ */
+
+import * as path from "node:path";
+
+import { aggregateAgents } from "./aggregate-agents.js";
+import { runAgentReview } from "./reviewers/index.js";
+import { QUESTIONS_SCHEMA } from "./reviewers/schemas.js";
+import type { AgentConfig, ModelsConfig } from "./types.js";
+import { logInfo, logWarn, logError } from "../../_shared/lib-ts/base/logger.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface PlanQuestionsResult {
+  questions: string[];
+  assumptions: string[];
+  ambiguities: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Provider assignment (local copy — avoids circular import from hook)
+// ---------------------------------------------------------------------------
+
+import { findExecutable } from "../../_shared/lib-ts/base/subprocess-utils.js";
+
+function assignProvider(agent: AgentConfig): AgentConfig {
+  // Default to claude provider with the agent's configured model
+  const found = findExecutable("claude");
+  if (found) {
+    return { ...agent, provider: "claude" };
+  }
+  logWarn("plan-questions", "Claude CLI not found, using agent defaults");
+  return agent;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+const HOOK = "plan-questions";
+
+/**
+ * Run the plan-questions agent to generate questions about a plan.
+ * Returns structured questions/assumptions/ambiguities, or null on failure.
+ *
+ * The agent runs in a fresh context (no codebase, no session history)
+ * and uses QUESTIONS_SCHEMA instead of REVIEW_SCHEMA — the agent runner
+ * is schema-agnostic.
+ */
+export async function runPlanQuestions(
+  plan: string,
+  aiwcliDir: string,
+  timeout: number,
+  contextPath?: string,
+  sessionName?: string,
+): Promise<PlanQuestionsResult | null> {
+  // Load the plan-questions agent from agents/plan-questions/
+  const questionsAgentDir = path.join(aiwcliDir, "_cc-native", "agents", "plan-questions");
+  const agents = aggregateAgents(questionsAgentDir);
+
+  if (agents.length === 0) {
+    logWarn(HOOK, `No agents found in ${questionsAgentDir}`);
+    return null;
+  }
+
+  // Use the first agent (PLAN-QUESTIONER)
+  let agent = agents[0]!;
+  logInfo(HOOK, `Using plan-questions agent: ${agent.name}`);
+
+  // Assign provider
+  agent = assignProvider(agent);
+
+  // Run the agent with QUESTIONS_SCHEMA
+  const result = await runAgentReview(
+    plan,
+    agent,
+    QUESTIONS_SCHEMA,
+    timeout,
+    contextPath,
+    sessionName ?? "unknown",
+  );
+
+  if (!result.ok) {
+    logError(HOOK, `Plan-questions agent failed: ${result.err}`);
+    return null;
+  }
+
+  // Extract structured data
+  const data = result.data ?? {};
+  const questions = Array.isArray(data.questions) ? (data.questions as string[]) : [];
+  const assumptions = Array.isArray(data.assumptions) ? (data.assumptions as string[]) : [];
+  const ambiguities = Array.isArray(data.ambiguities) ? (data.ambiguities as string[]) : [];
+
+  logInfo(HOOK, `Plan-questions result: ${questions.length} questions, ${assumptions.length} assumptions, ${ambiguities.length} ambiguities`);
+
+  return { questions, assumptions, ambiguities };
+}