@orchestrator-claude/cli 3.17.1 → 3.19.0

package/templates/base/claude/hooks/lib/git-checkpoint.ts

@@ -0,0 +1,91 @@
+/**
+ * git-checkpoint.ts — Git checkpoint logic for Orchestrator hooks (RFC-022 Phase 2)
+ * Replaces post-phase-checkpoint.sh git logic.
+ */
+
+import { execSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { log, registerCheckpoint } from "./api-client.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PROJECT_ROOT = join(__dirname, "..", "..", "..");
+const STATE_DIR = join(PROJECT_ROOT, ".orchestrator", ".state");
+const LAST_PHASE_FILE = join(STATE_DIR, "last-checkpointed-phase");
+
+const PHASE_ORDER = ["research", "specify", "plan", "tasks", "implement", "validate"];
+
+/** Map from current phase to the phase that just completed */
+function getCompletedPhase(currentPhase: string): string | null {
+  const lower = currentPhase.toLowerCase();
+  const idx = PHASE_ORDER.indexOf(lower);
+  return idx > 0 ? PHASE_ORDER[idx - 1] : null;
+}
+
+function exec(cmd: string): string {
+  return execSync(cmd, { cwd: PROJECT_ROOT, encoding: "utf-8" }).trim();
+}
+
+/**
+ * Create a git checkpoint if the phase changed and there are staged changes.
+ * Returns the commit hash or null.
+ */
+export async function createCheckpointIfNeeded(
+  workflowId: string,
+  currentPhase: string
+): Promise<string | null> {
+  const completedPhase = getCompletedPhase(currentPhase);
+  if (!completedPhase) {
+    log("CHECKPOINT", `No completed phase from: ${currentPhase}`);
+    return null;
+  }
+
+  // Check if already checkpointed
+  let lastPhase = "";
+  try {
+    lastPhase = readFileSync(LAST_PHASE_FILE, "utf-8").trim();
+  } catch {
+    // no file
+  }
+  if (lastPhase === completedPhase) {
+    log("CHECKPOINT", `Already checkpointed: ${completedPhase}`);
+    return null;
+  }
+
+  try {
+    // Stage all changes
+    exec("git add -A");
+
+    // Check if there are staged changes
+    try {
+      exec("git diff --cached --quiet");
+      // No changes
+      log("CHECKPOINT", `No changes for phase: ${completedPhase}`);
+      writeFileSync(LAST_PHASE_FILE, completedPhase);
+      return null;
+    } catch {
+      // Has changes — good, proceed to commit
+    }
+
+    const commitMsg = `[orchestrator] ${completedPhase}: Auto-checkpoint after ${completedPhase} phase`;
+    exec(`git commit -m "${commitMsg}" --no-verify`);
+    const commitHash = exec("git rev-parse HEAD");
+
+    log("CHECKPOINT", `Created: phase=${completedPhase} commit=${commitHash}`);
+
+    // Register via API
+    await registerCheckpoint(
+      workflowId,
+      `Auto-checkpoint after ${completedPhase} phase`,
+      commitHash
+    );
+
+    writeFileSync(LAST_PHASE_FILE, completedPhase);
+    return commitHash;
+  } catch (err) {
+    log("CHECKPOINT", `Error: ${err}`);
+    return null;
+  }
+}

package/templates/base/claude/hooks/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@orchestrator/hooks",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Orchestrator TypeScript hooks (RFC-022 Phase 2)",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "tsx": "^4.21.0"
+  }
+}

package/templates/base/claude/hooks/post-compact.ts

@@ -0,0 +1,44 @@
+/**
+ * post-compact.ts — PostCompact hook (RFC-022 Phase 2)
+ * NEW hook: re-injects workflow state after context compaction
+ * so Claude doesn't lose track of active workflow.
+ */
+
+import {
+  log,
+  getActiveWorkflow,
+  getNextAction,
+  outputContext,
+} from "./lib/api-client.js";
+
+const HOOK = "POST-COMPACT";
+
+async function main(): Promise<void> {
+  log(HOOK, "PostCompact hook triggered");
+
+  const workflow = await getActiveWorkflow();
+  if (!workflow) {
+    log(HOOK, "No active workflow, nothing to re-inject");
+    return;
+  }
+
+  const parts: string[] = [
+    `[ORCHESTRATOR] Context was compacted. Active workflow state:`,
+    `Workflow: ${workflow.id}`,
+    `Type: ${workflow.type}`,
+    `Phase: ${workflow.currentPhase}`,
+    `Status: ${workflow.status}`,
+  ];
+
+  const action = await getNextAction(workflow.id);
+  if (action?.hasAction && action.pendingAction) {
+    parts.push(`Next: invoke '${action.pendingAction.agent}' (${action.pendingAction.status})`);
+  }
+
+  parts.push("", "Remember: YOU are the orchestrator (RFC-022). Dispatch sub-agents directly via Agent tool.");
+
+  log(HOOK, `Re-injecting workflow state (wf=${workflow.id})`);
+  outputContext("PostCompact", parts.join("\n"));
+}
+
+main().catch(() => process.exit(0));

package/templates/base/claude/hooks/session-start.ts

@@ -0,0 +1,97 @@
+/**
+ * session-start.ts — SessionStart hook (RFC-022 Phase 2)
+ * Replaces session-orchestrator.sh
+ * Injects workflow status context on session start.
+ */
+
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  log,
+  getActiveWorkflow,
+  getNextAction,
+  outputContext,
+} from "./lib/api-client.js";
+
+const HOOK = "SESSION-START";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PROJECT_ROOT = join(__dirname, "..", "..");
+
+/**
+ * Read BACKLOG.md to extract version and next work item.
+ * Returns structured summary for the greeting.
+ */
+function getBacklogSummary(): { version: string; next: string; status: string } {
+  try {
+    const backlogPath = join(PROJECT_ROOT, "project-guidelines", "BACKLOG.md");
+    const content = readFileSync(backlogPath, "utf-8");
+    const lines = content.split("\n").slice(0, 40);
+
+    // Extract version from "**Release Atual:** vX.Y.Z" or "Current Release: vX.Y.Z"
+    const versionLine = lines.find((l) => /release atual|current release/i.test(l));
+    const versionMatch = versionLine?.match(/v(\d+\.\d+\.\d+)/);
+    const version = versionMatch ? `v${versionMatch[1]}` : "v?.?.?";
+
+    // Extract pending status from "**Pendente:**" line (colon may be inside or outside bold)
+    const pendenteLine = lines.find((l) => /\*\*pendente/i.test(l));
+    const status = pendenteLine
+      ?.replace(/.*\*\*pendente:?\*\*:?\s*/i, "")
+      .replace(/\s*$/, "")
+      .slice(0, 80) || "";
+
+    // Extract next step from "**Proximo passo:**" or "**Next:**" line
+    const nextLine = lines.find((l) => /\*\*proximo passo/i.test(l) || /\*\*next/i.test(l));
+    const next = nextLine
+      ?.replace(/.*\*\*(proximo passo|next):?\*\*:?\s*/i, "")
+      .replace(/\s*$/, "")
+      .slice(0, 120) || "see BACKLOG.md";
+
+    log(HOOK, `BACKLOG parsed: version=${version} next=${next.slice(0, 50)}`);
+    return { version, next, status };
+  } catch (err) {
+    log(HOOK, `BACKLOG read failed: ${err}`);
+    return { version: "v?.?.?", next: "see BACKLOG.md", status: "" };
+  }
+}
+
+async function main(): Promise<void> {
+  log(HOOK, "SessionStart hook triggered");
+
+  const backlog = getBacklogSummary();
+  const workflow = await getActiveWorkflow();
+
+  if (!workflow) {
+    log(HOOK, "No active workflow, injecting greeting data");
+    outputContext(
+      "SessionStart",
+      [
+        `[ORCHESTRATOR-DATA] version=${backlog.version} | workflow=none | next=${backlog.next}`,
+        `[ORCHESTRATOR] Greet the user via AskUserQuestion using the data above (CLAUDE.md Rule #1).`,
+        "Do NOT invoke /orchestrator skill for the greeting — use AskUserQuestion directly.",
+        "Invoke /orchestrator skill only when the user chooses to start a workflow.",
+      ].join("\n")
+    );
+    return;
+  }
+
+  // Active workflow — inject state + backlog
+  const action = await getNextAction(workflow.id);
+  const actionHint = action?.hasAction && action.pendingAction
+    ? ` | pending=${action.pendingAction.agent} (${action.pendingAction.status})`
+    : "";
+
+  log(HOOK, `Injecting workflow context (wf=${workflow.id} phase=${workflow.currentPhase})`);
+  outputContext(
+    "SessionStart",
+    [
+      `[ORCHESTRATOR-DATA] version=${backlog.version} | workflow=${workflow.id} | type=${workflow.type} | phase=${workflow.currentPhase} | status=${workflow.status}${actionHint}`,
+      `[ORCHESTRATOR] Active workflow detected. Greet the user via AskUserQuestion showing workflow state (CLAUDE.md Rule #1).`,
+      "Do NOT invoke /orchestrator skill for the greeting — use AskUserQuestion directly.",
+      "Invoke /orchestrator skill when the user chooses to continue the workflow.",
+    ].join("\n")
+  );
+}
+
+main().catch(() => process.exit(0));

package/templates/base/claude/hooks/subagent-start.ts

@@ -0,0 +1,50 @@
+/**
+ * subagent-start.ts — SubagentStart hook (RFC-022 Phase 2)
+ * Replaces track-agent-invocation.sh start
+ * Registers agent invocation via REST API.
+ */
+
+import {
+  log,
+  readStdin,
+  getField,
+  getActiveWorkflow,
+  startInvocation,
+} from "./lib/api-client.js";
+
+const HOOK = "SUBAGENT-START";
+
+const PHASE_MAP: Record<string, string> = {
+  specifier: "specify",
+  planner: "plan",
+  "task-generator": "tasks",
+  implementer: "implement",
+  researcher: "research",
+  reviewer: "review",
+};
+
+async function main(): Promise<void> {
+  const stdin = await readStdin();
+  log(HOOK, `SubagentStart triggered`);
+
+  const agentType =
+    getField(stdin, "tool_input.subagent_type") ||
+    getField(stdin, "subagent_type") ||
+    getField(stdin, "tool_input.type") ||
+    "unknown";
+
+  const phase = PHASE_MAP[agentType] || agentType;
+
+  log(HOOK, `agent=${agentType} phase=${phase}`);
+
+  const workflow = await getActiveWorkflow();
+  if (!workflow) {
+    log(HOOK, "No active workflow, skipping");
+    return;
+  }
+
+  await startInvocation(agentType, workflow.id, phase);
+  log(HOOK, `START: agent=${agentType} phase=${phase} workflow=${workflow.id}`);
+}
+
+main().catch(() => process.exit(0));

package/templates/base/claude/hooks/subagent-stop.ts

@@ -0,0 +1,57 @@
+/**
+ * subagent-stop.ts — SubagentStop unified handler (RFC-022 Phase 2)
+ * Replaces 3 chained bash hooks:
+ *   1. track-agent-invocation.sh complete
+ *   2. ping-pong-enforcer.sh (ELIMINATED — main conversation is orchestrator)
+ *   3. post-phase-checkpoint.sh
+ *
+ * Single handler, single auth, sequential logic.
+ */
+
+import {
+  log,
+  readStdin,
+  getField,
+  getActiveWorkflow,
+  outputContext,
+} from "./lib/api-client.js";
+import { createCheckpointIfNeeded } from "./lib/git-checkpoint.js";
+
+const HOOK = "SUBAGENT-STOP";
+
+async function main(): Promise<void> {
+  const stdin = await readStdin();
+  log(HOOK, "SubagentStop triggered");
+
+  const agentType =
+    getField(stdin, "agent_type") ||
+    getField(stdin, "tool_input.subagent_type") ||
+    "unknown";
+
+  const workflow = await getActiveWorkflow();
+  if (!workflow) {
+    log(HOOK, "No active workflow, skipping");
+    return;
+  }
+
+  log(HOOK, `agent=${agentType} workflow=${workflow.id} phase=${workflow.currentPhase}`);
+
+  // 1. Invocation tracking — agent self-reports via MCP; this is safety net
+  log(HOOK, `COMPLETE: agent=${agentType} (safety net — agent self-reports via MCP)`);
+
+  // 2. Git checkpoint if phase changed
+  const commitHash = await createCheckpointIfNeeded(workflow.id, workflow.currentPhase);
+
+  // 3. Guide main conversation — NO ping-pong, main IS the orchestrator
+  const parts: string[] = [`[ORCHESTRATOR] Agent '${agentType}' completed for workflow ${workflow.id}.`];
+
+  if (commitHash) {
+    parts.push(`Checkpoint: ${commitHash}.`);
+  }
+
+  parts.push("Proceed to gate check via AskUserQuestion before advancing phase.");
+
+  outputContext("SubagentStop", parts.join(" "));
+}
+
+main().catch(() => process.exit(0));

package/templates/base/claude/hooks/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": ".",
+    "declaration": false,
+    "sourceMap": false,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true
+  },
+  "include": ["*.ts", "lib/*.ts"]
+}

package/templates/base/claude/hooks/user-prompt.ts

@@ -0,0 +1,95 @@
+/**
+ * user-prompt.ts — UserPromptSubmit hook (RFC-022 Phase 2)
+ * Replaces prompt-orchestrator.sh
+ * Detects workflow type and injects hints by confidence tiers.
+ */
+
+import {
+  log,
+  readStdin,
+  getField,
+  getActiveWorkflow,
+  getNextAction,
+  detectWorkflow,
+  outputContext,
+} from "./lib/api-client.js";
+
+const HOOK = "USER-PROMPT";
+
+async function main(): Promise<void> {
+  log(HOOK, "UserPromptSubmit triggered");
+
+  const stdin = await readStdin();
+  const workflow = await getActiveWorkflow();
+
+  if (!workflow) {
+    // No active workflow — detect and suggest
+    const prompt = getField(stdin, "prompt");
+    if (!prompt) {
+      log(HOOK, "empty prompt, silence");
+      return;
+    }
+
+    const detection = await detectWorkflow(prompt);
+    if (!detection) {
+      log(HOOK, "detect API failed/timeout, silence (fail-open)");
+      return;
+    }
+
+    const { workflowType, confidence, suggestedMode } = detection;
+    log(HOOK, `detected type=${workflowType} confidence=${confidence} mode=${suggestedMode}`);
+
+    // Tier 1: interactive_analysis
+    if (workflowType === "interactive_analysis") {
+      outputContext(
+        "UserPromptSubmit",
+        [
+          "[ORCHESTRATOR] This looks like an analytical/design request. How would you like to proceed?",
+          '(a) Continue as a free conversation (no workflow)',
+          '(b) Start an interactive_analysis workflow for structured exploration (cyclic phases: research → discuss → analyze)',
+          "",
+          'If you choose (b), I will call: mcp__orchestrator-tools__startWorkflow({ type: "interactive_analysis", prompt: "..." })',
+        ].join("\n")
+      );
+      return;
+    }
+
+    // Tier 2: high confidence (>= 0.7)
+    if (confidence >= 0.7) {
+      const mode = suggestedMode || "standard";
+      outputContext(
+        "UserPromptSubmit",
+        `[ORCHESTRATOR] Detected: ${workflowType} workflow (confidence: ${confidence}, suggested mode: ${mode}).\nTo start: mcp__orchestrator-tools__startWorkflow({ type: "${workflowType}", prompt: "...", mode: "${mode}" })\nOr continue without a workflow if this is exploratory.`
+      );
+      return;
+    }
+
+    // Tier 3: medium confidence (0.5-0.69)
+    if (confidence >= 0.5) {
+      outputContext(
+        "UserPromptSubmit",
+        `[ORCHESTRATOR] Hint: this might be a ${workflowType} task. Consider starting a workflow if you plan to write code.`
+      );
+      return;
+    }
+
+    // Tier 4: low confidence — silence
+    log(HOOK, `Tier 4 silence (confidence=${confidence} < 0.5)`);
+    return;
+  }
+
+  // Active workflow — inject state
+  const action = await getNextAction(workflow.id);
+  let context: string;
+
+  if (action?.hasAction && action.pendingAction) {
+    context = `[ORCHESTRATOR] Active workflow: ${workflow.id}. Next: invoke '${action.pendingAction.agent}' (${action.pendingAction.status}).`;
+  } else {
+    context = `[ORCHESTRATOR] Active workflow: ${workflow.id}. No pending actions.`;
+  }
+
+  log(HOOK, `workflow=${workflow.id} hasAction=${action?.hasAction}`);
+  outputContext("UserPromptSubmit", context);
+}
+
+main().catch(() => process.exit(0));

package/templates/base/claude/hooks/workflow-guard.ts

@@ -0,0 +1,120 @@
+/**
+ * workflow-guard.ts — PreToolUse[Write|Edit] hook (RFC-022 Phase 2)
+ * Replaces workflow-guard.sh
+ * Blocks writes to src/ and tests/ without active workflow.
+ * Respects SKIP_WORKFLOW_GUARD, quick/interactive modes, sub-agent writes.
+ */
+
+import {
+  log,
+  readStdin,
+  getField,
+  getActiveWorkflow,
+  getWorkflowMode,
+  outputPreToolUse,
+} from "./lib/api-client.js";
+
+const HOOK = "WORKFLOW-GUARD";
+
+async function main(): Promise<void> {
+  const stdin = await readStdin();
+  const filePath = getField(stdin, "tool_input.file_path") || getField(stdin, "file_path") || getField(stdin, "input.file_path");
+
+  log(HOOK, `file_path=${filePath}`);
+
+  // Explicit bypass
+  if (process.env.SKIP_WORKFLOW_GUARD === "true") {
+    log(HOOK, "ALLOW (SKIP_WORKFLOW_GUARD=true)");
+    outputPreToolUse({
+      decision: "allow",
+      context: "Workflow guard bypassed via SKIP_WORKFLOW_GUARD=true.",
+    });
+    return;
+  }
+
+  // Only guard src/ and tests/ paths
+  if (!filePath.includes("/src/") && !filePath.includes("/tests/")) {
+    log(HOOK, "ALLOW (non-guarded path)");
+    return;
+  }
+
+  // Allow config/doc files
+  if (/\.(json|ya?ml|md|env(\..*)?)$/.test(filePath)) {
+    log(HOOK, "ALLOW (config/doc file)");
+    return;
+  }
+
+  // Check for active workflow
+  const workflow = await getActiveWorkflow();
+
+  if (workflow) {
+    const mode = await getWorkflowMode(workflow.id);
+    log(HOOK, `workflow=${workflow.id} mode=${mode || "legacy"}`);
+
+    if (mode === "quick") {
+      outputPreToolUse({
+        decision: "allow",
+        context: `Active workflow: ${workflow.id} (mode: quick). Direct writes allowed in quick mode.`,
+      });
+      return;
+    }
+
+    if (mode === "interactive") {
+      outputPreToolUse({
+        decision: "allow",
+        context: `Active workflow: ${workflow.id} (mode: interactive). Note: code writes are unexpected in interactive/analysis workflows.`,
+      });
+      return;
+    }
+
+    // Check if running inside a sub-agent
+    const agentId = getField(stdin, "agent_id");
+    if (agentId) {
+      const agentType = getField(stdin, "agent_type");
+      log(HOOK, `ALLOW (sub-agent: ${agentType || "unknown"}, workflow: ${workflow.id})`);
+      outputPreToolUse({
+        decision: "allow",
+        context: `Active workflow: ${workflow.id}. Sub-agent ${agentType || "unknown"} write allowed.`,
+      });
+      return;
+    }
+
+    // Main agent writing directly — check SKIP_SUBAGENT_GUARD
+    if (process.env.SKIP_SUBAGENT_GUARD === "true") {
+      log(HOOK, `ALLOW (SKIP_SUBAGENT_GUARD=true, workflow: ${workflow.id})`);
+      outputPreToolUse({
+        decision: "allow",
+        context: `Active workflow: ${workflow.id}. Direct write allowed via SKIP_SUBAGENT_GUARD.`,
+      });
+      return;
+    }
+
+    // Main agent direct write — DENY
+    log(HOOK, `DENY (main agent direct write, mode=${mode || "legacy"})`);
+    outputPreToolUse({
+      decision: "deny",
+      reason:
+        "Workflow Guard: Direct code writes are blocked. You must invoke a sub-agent (e.g. implementer) to write code. The sub-agent will have write access.",
+      context:
+        "Use the Agent tool to spawn an implementer sub-agent for code changes. The workflow-guard allows writes only from sub-agents (identified by agent_id in hook input).",
+    });
+    return;
+  }
+
+  // No active workflow — DENY
+  log(HOOK, "DENY (no active workflow)");
+  outputPreToolUse({
+    decision: "deny",
+    reason: "Workflow Guard: No active workflow. Direct implementation is not allowed.",
+    context: [
+      "You MUST start a workflow before writing code:",
+      '1. mcp__orchestrator-tools__detectWorkflow({ prompt: "..." })',
+      '2. mcp__orchestrator-tools__startWorkflow({ workflowType: "...", prompt: "..." })',
+      "3. Follow the nextStep returned by startWorkflow",
+      "",
+      "The workflow-guard hook blocks all writes to src/ and tests/ without an active workflow.",
+    ].join("\n"),
+  });
+}
+
+main().catch(() => process.exit(0));