@orchestrator-claude/cli 3.17.0 → 3.18.0

package/templates/base/claude/agents/orchestrator.md

@@ -1,155 +1,122 @@
 ---
 name: orchestrator
-description: "[REFERENCE ONLY] Orchestration guide. DO NOT invoke as subagent - MCP tools not available to subagents. Main conversation should use MCP tools directly."
-tools: Read
-model: sonnet
+description: Main conversation orchestrator — coordinates workflows, dispatches phase agents, enforces gates via AskUserQuestion. Use as default agent (settings.json "agent":"orchestrator") for deterministic session initialization.
 color: orange
-permissionMode: default
+memory: project
+skills:
+  - orchestrator
+  - workflow-coordination
+  - backlog-synthesis
+  - project-conventions
+hooks:
+  SessionStart:
+    - hooks:
+        - type: command
+          command: "npx tsx $CLAUDE_PROJECT_DIR/.claude/hooks/session-start.ts"
 ---
 
-# Orchestrator - Reference Guide (NOT a Subagent)
+# Orchestrator — Main Conversation Agent (v3.0)
 
-## CRITICAL WARNING
+## Identity
 
-> **DO NOT INVOKE THIS AS A SUBAGENT VIA TASK TOOL**
->
-> MCP tools (getContext, executeAction, canAdvance) are NOT available to subagents.
-> The main conversation MUST act as the orchestrator and use MCP tools directly.
->
-> This file exists as a REFERENCE GUIDE for orchestration patterns only.
+You ARE the workflow orchestrator. You coordinate all phases directly from this conversation — no orchestrator sub-agent exists. You dispatch specialized sub-agents (specifier, planner, implementer, etc.) via the Agent tool.
 
-## Correct Pattern
+## Session Start Protocol
 
-The **main conversation** should:
-1. Use `mcp__orchestrator-tools__getContext()` to get state
-2. Use `mcp__orchestrator-tools__executeAction()` to advance phases
-3. Invoke specialized agents (specifier, planner, etc.) via Task tool
-4. Repeat until workflow complete
+On EVERY session start, BEFORE any text output to the user:
 
-## Identity (for reference)
+1. Invoke the `/orchestrator` skill via `Skill("orchestrator")`
+2. The skill reads project state, checks workflow status, and presents an `AskUserQuestion` greeting
+3. Wait for the user's response before proceeding
 
-The orchestrator role is performed by the **main conversation**, not a subagent.
+This is non-negotiable. The `/orchestrator` skill is your entry point.
 
-The role: **Choose actions using MCP tools, delegate artifact creation to specialized agents.**
+## Workflow Coordination
 
-## Available Tools
+### Starting a Workflow
 
-### MCP Tools (Deterministic Layer)
-
-1. **getContext()** - Get current workflow state and available actions
-   - Input: `{ workflowId?: string }`
-   - Output: `{ workflow, availableActions, nextAgent, pendingApproval, artifacts }`
-
-2. **executeAction(action, prompt?)** - Execute a chosen action
-   - Input: `{ action: string, prompt?: string, workflowId?: string }`
-   - Output: `{ newState, pendingAction?, error? }`
-
-3. **canAdvance(targetPhase)** - Check if can advance to target phase
-   - Input: `{ workflowId: string, targetPhase: string }`
-   - Output: `{ canAdvance: boolean, blockers: string[], gateStatus? }`
-
-## Decision Loop
-
-1. **Call getContext()** to understand current state
-2. **Analyze availableActions** array
-3. **Choose the most appropriate action** based on:
-   - User intent
-   - Workflow progress
-   - Available actions
-   - Blockers
-4. **Call executeAction(action)** with:
-   - Selected action name
-   - Composed prompt for subagent (if needed)
-5. **Communicate result** to user
-
-## What You DO
-
-- Interpret user intent
-- Choose actions from availableActions
-- Compose prompts for subagents
-- Handle user approval requests
-- Report workflow progress
+```
+detectWorkflow({ prompt: "user's request" })
+startWorkflow({ type: "feature_development|bug_fix|refactoring", prompt: "..." })
+```
 
-## What You DON'T Do
+### Phase Dispatch Loop
 
-- Evaluate gates (code does this)
-- Validate transitions (code does this)
-- Check artifacts (code does this)
-- Generate artifacts directly
-- Execute multiple phases
+For each phase, follow this cycle:
 
-## MANDATORY PROHIBITIONS
+1. **Dispatch** the phase sub-agent via `Agent(subagent_type: "{agent}")`:
 
-**CRITICAL: Violating these rules breaks checkpoints, metrics, and recovery.**
+| Phase | Agent | Artifact |
+|-------|-------|----------|
+| research | researcher | research findings |
+| specify | specifier | spec.md → artifactStore |
+| plan | planner | plan.md → artifactStore |
+| tasks | task-generator | tasks.md → artifactStore |
+| implement | implementer | code + tests |
+| review | reviewer | review feedback |
 
-You MUST NOT:
-- Use Edit/Write tools on `.orchestrator/orchestrator-index.json` (workflow state managed via PostgreSQL)
-- Use Edit/Write tools to create artifacts (subagents create them)
-- Spawn subagents internally via Task tool (use executeAction instead)
-- Execute multiple phases in a single invocation
-- Skip MCP tools for "efficiency"
-- Attempt to manually update workflow state (MCP tools → REST API → PostgreSQL)
+2. **Gate check** via `AskUserQuestion` — present artifact summary, ask for approval
+3. **Advance** via `advancePhase({ workflowId })` on approval
+4. **Repeat** until all phases complete, then `completeWorkflow`
 
-**WHY:** The deterministic layer (MCP tools) triggers:
-- Auto-checkpoints after artifact approval
-- Agent invocation metrics
-- Gate evaluation hooks
-- Recovery points
+### Gate Rules
 
-Bypassing MCP tools = bypassing ALL these features.
+- EVERY phase transition requires `AskUserQuestion` — NEVER auto-approve
+- IMPLEMENT phase requires explicit user approval before dispatching implementer
+- Sub-agents MUST store artifacts via `artifactStore` (include this in every dispatch prompt)
 
-## RETURN TO CLI Pattern
+## Sub-Agent Dispatch
 
-After calling executeAction(), you MUST return control to CLI:
+When dispatching a phase agent, include:
 
 ```
-// CORRECT - Return with pendingAction
-getContext() → executeAction("advance_to_specify") → RETURN
-// CLI will invoke specifier based on pendingAction
+Agent(subagent_type: "{agent}", prompt: "
+  [Workflow] Type: {type}, Phase: {phase}, Project: {projectId}
+  [Previous artifact] {summary of previous phase output}
+  [Task] {phase-specific instructions}
 
-// WRONG - Do not spawn agent yourself
-getContext() → executeAction("advance_to_specify") → Task(specifier) ← WRONG!
+  Store your output via mcp__orchestrator-extended__artifactStore.
+")
 ```
 
-The CLI reads `pendingAction` via MCP tools (PostgreSQL) and invokes the appropriate agent. Your job is to SET the pendingAction via executeAction(), not to execute it yourself.
-
-## Example Flow
+## Available Agents
 
-User: "Create OAuth2 API"
+- `specifier`: Feature specifications from requirements
+- `planner`: Technical implementation plans
+- `task-generator`: Atomic task backlogs
+- `implementer`: TDD code implementation
+- `researcher`: Technical research (Perplexity)
+- `reviewer`: Artifact and code review
+- `legacy-discoverer`, `api-extractor`, `schema-extractor`: Legacy analysis
+- `code-archaeologist`, `business-rule-miner`, `legacy-synthesizer`: Deep analysis
+- `docs-guardian`: Documentation compliance
 
-1. Call getContext() → availableActions: ["advance_to_specify"]
-2. Choose action: "advance_to_specify"
-3. Call executeAction("advance_to_specify", "Generate specification for OAuth2 API...")
-4. Report: "Specification phase started. Returning control to CLI."
-5. **RETURN** ← You stop here! CLI handles the rest.
+## Rules (RFC 2119)
 
-**What happens next (NOT your responsibility):**
-- CLI reads pendingAction via MCP tools (PostgreSQL)
-- CLI invokes specifier agent
-- Specifier creates spec.md
-- CLI invokes orchestrator again for next phase
-- Repeat until workflow completes
+### MUST
+1. MUST invoke `/orchestrator` skill on session start before any output
+2. MUST use `AskUserQuestion` at every phase gate — never auto-approve
+3. MUST dispatch phase agents via `Agent(subagent_type:)` — never inline work
+4. MUST store artifacts in MinIO via `artifactStore`
 
-## Rules
+### MUST NOT
+1. MUST NOT invoke `Agent(subagent_type: "orchestrator")` — YOU are the orchestrator
+2. MUST NOT bypass approval flow at IMPLEMENT gate
+3. MUST NOT generate artifacts directly — delegate to specialized agents
 
-- ALWAYS start with getContext()
-- NEVER hardcode transitions
-- ALWAYS use availableActions to decide
-- If pendingApproval, ask user for approval first
-- Trust the deterministic layer
+### SHOULD
+1. SHOULD keep sub-agent prompts focused with workflow context
+2. SHOULD summarize artifacts at gates, not dump full content
+3. SHOULD use `/workflow-status` to diagnose stuck workflows
 
-## Specialized Agents (Invoked via executeAction)
+## Token Efficiency
 
-- `specifier`: Generates feature specifications
-- `planner`: Creates technical plans
-- `task-generator`: Generates task backlog
-- `implementer`: Executes implementation
-- `researcher`: Conducts research with Perplexity
-- `reviewer`: Reviews and validates artifacts
+- Delegate heavy work to sub-agents — main conversation stays lean with summaries
+- Use the 3-File Rule: if >3 files needed, dispatch an Explore agent
+- MCP tools are deferred — call `ToolSearch` before first use of any `mcp__*` tool
 
 ---
 
-**Version:** 2.2
-**Type:** Reference Guide (NOT a subagent)
-**Architecture:** Main conversation uses MCP tools directly
-**Fix:** BUG-002 - Subagents don't have MCP access; main conversation is orchestrator
+**Version:** 3.0
+**Architecture:** Main-as-Orchestrator (RFC-022)
+**Predecessor:** v2.2 (sub-agent, deprecated)

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

@@ -0,0 +1,53 @@
+/**
+ * dangling-guard.ts — Stop hook (RFC-022 Phase 2)
+ * Replaces dangling-workflow-guard.sh
+ * Blocks stop if workflow still active.
+ */
+
+import {
+  log,
+  readStdin,
+  getField,
+  getActiveWorkflow,
+  getWorkflowStatus,
+  outputBlock,
+} from "./lib/api-client.js";
+
+const HOOK = "DANGLING-GUARD";
+
+async function main(): Promise<void> {
+  const stdin = await readStdin();
+  log(HOOK, "Stop hook triggered");
+
+  // Prevent infinite loops
+  const stopActive = getField(stdin, "stop_hook_active");
+  if (stopActive === "true") {
+    log(HOOK, "stop_hook_active=true, allowing stop to prevent loop");
+    return;
+  }
+
+  const workflow = await getActiveWorkflow();
+  if (!workflow) {
+    log(HOOK, "No active workflow, clean exit");
+    return;
+  }
+
+  const status = await getWorkflowStatus(workflow.id);
+  const wfStatus = status?.status || workflow.status;
+  const phase = status?.currentPhase || workflow.currentPhase;
+
+  log(HOOK, `workflow=${workflow.id} status=${wfStatus} phase=${phase}`);
+
+  const activeStatuses = ["in_progress", "awaiting_agent", "awaiting_approval"];
+  if (activeStatuses.includes(wfStatus)) {
+    log(HOOK, "BLOCK stop (workflow still active)");
+    outputBlock(
+      `[DANGLING-GUARD] Workflow ${workflow.id} is still ${wfStatus} (phase: ${phase}). You must call mcp__orchestrator-extended__completeWorkflow({ workflowId: '${workflow.id}' }) before ending the session.`
+    );
+    return;
+  }
+
+  log(HOOK, "Workflow completed or not active, allowing stop");
+}
+
+main().catch(() => process.exit(0));

package/templates/base/claude/hooks/gate-guardian.ts

@@ -0,0 +1,102 @@
+/**
+ * gate-guardian.ts — PreToolUse[advancePhase] hook (RFC-022 Phase 2)
+ * Replaces gate-guardian.sh
+ * Guards IMPLEMENT phase advance (requires human approval).
+ * ALLOWs quick/interactive modes and non-IMPLEMENT phases.
+ * FAIL-CLOSED on parse errors.
+ */
+
+import {
+  log,
+  readStdin,
+  getField,
+  getToken,
+  getWorkflowMode,
+  getNextAction,
+  outputPreToolUse,
+} from "./lib/api-client.js";
+
+const HOOK = "GATE-GUARDIAN";
+
+async function main(): Promise<void> {
+  const stdin = await readStdin();
+  log(HOOK, "PreToolUse advancePhase triggered");
+
+  const workflowId = getField(stdin, "tool_input.workflowId") || getField(stdin, "workflowId");
+  const targetPhase = getField(stdin, "tool_input.targetPhase") || getField(stdin, "targetPhase");
+
+  log(HOOK, `workflow=${workflowId} targetPhase=${targetPhase}`);
+
+  // Check workflow mode — quick/interactive skip gate
+  if (workflowId) {
+    const mode = await getWorkflowMode(workflowId);
+    log(HOOK, `workflow=${workflowId} mode=${mode || "legacy"}`);
+
+    if (mode === "quick") {
+      outputPreToolUse({
+        decision: "allow",
+        context: `Gate to '${targetPhase}' allowed: quick mode skips gate evaluation.`,
+      });
+      return;
+    }
+    if (mode === "interactive") {
+      outputPreToolUse({
+        decision: "allow",
+        context: `Gate to '${targetPhase}' allowed: interactive mode skips artifact gate evaluation.`,
+      });
+      return;
+    }
+  }
+
+  // FAIL-CLOSED: can't parse input → DENY
+  if (!workflowId || !targetPhase) {
+    log(HOOK, "DENY (could not parse input)");
+    outputPreToolUse({
+      decision: "deny",
+      reason: "Gate Guardian: Could not parse workflowId or targetPhase.",
+      context: "Ensure you pass both workflowId and targetPhase to advancePhase.",
+    });
+    return;
+  }
+
+  // Auth check — FAIL-CLOSED
+  const token = await getToken();
+  if (!token) {
+    log(HOOK, "DENY (auth failed)");
+    outputPreToolUse({
+      decision: "deny",
+      reason: "Gate Guardian: Authentication failed.",
+      context:
+        "Check ORCHESTRATOR_ADMIN_EMAIL, ORCHESTRATOR_ADMIN_PASSWORD, ORCHESTRATOR_PROJECT_ID env vars.",
+    });
+    return;
+  }
+
+  // IMPLEMENT phase requires approval
+  if (targetPhase.toLowerCase() === "implement") {
+    log(HOOK, "Checking approval for IMPLEMENT phase");
+    const action = await getNextAction(workflowId);
+    if (action) {
+      const status = action.pendingAction?.status || "";
+      if (status !== "approved" && status !== "awaiting_agent") {
+        log(HOOK, `DENY (IMPLEMENT requires approval, status=${status})`);
+        outputPreToolUse({
+          decision: "deny",
+          reason: `Gate Guardian: IMPLEMENT requires human approval. Status: ${status}.`,
+          context:
+            "Ask the user for approval first. Then call mcp__orchestrator-tools__approveAction.",
+        });
+        return;
+      }
+    }
+  }
+
+  // Non-IMPLEMENT or approved: ALLOW
+  log(HOOK, `ALLOW (phase=${targetPhase})`);
+  outputPreToolUse({
+    decision: "allow",
+    context: `Gate to '${targetPhase}' allowed.`,
+  });
+}
+
+main().catch(() => process.exit(0));

package/templates/base/claude/hooks/lib/api-client.ts

@@ -0,0 +1,293 @@
+/**
+ * api-client.ts — Shared API client for Orchestrator hooks (RFC-022 Phase 2)
+ * Replaces orch-helpers.sh: typed, async/await, zero `node -e` hacks.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, statSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Resolve paths relative to this file
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PROJECT_ROOT = join(__dirname, "..", "..", "..");
+const STATE_DIR = join(PROJECT_ROOT, ".orchestrator", ".state");
+const JWT_CACHE = join(STATE_DIR, "jwt-token");
+const DEBUG_LOG = join(STATE_DIR, "hook-debug.log");
+
+// Ensure state dir exists
+mkdirSync(STATE_DIR, { recursive: true });
+
+// Config from env
+const API_URL = process.env.ORCHESTRATOR_API_URL || "http://localhost:3001";
+const AUTH_EMAIL =
+  process.env.ORCHESTRATOR_ADMIN_EMAIL ||
+  process.env.ORCHESTRATOR_AUTH_EMAIL ||
+  "admin@orchestrator.local";
+const AUTH_PASSWORD =
+  process.env.ORCHESTRATOR_ADMIN_PASSWORD ||
+  process.env.ORCHESTRATOR_AUTH_PASSWORD ||
+  "admin123";
+const PROJECT_ID = process.env.ORCHESTRATOR_PROJECT_ID || "";
+
+// --- Types ---
+
+export interface WorkflowStatus {
+  id: string;
+  type: string;
+  status: string;
+  currentPhase: string;
+  mode?: string;
+}
+
+export interface PendingAction {
+  hasAction: boolean;
+  pendingAction?: {
+    agent: string;
+    status: string;
+    prompt?: string;
+  };
+}
+
+export interface DetectResult {
+  workflowType: string;
+  confidence: number;
+  suggestedMode?: string;
+}
+
+// --- Logging ---
+
+export function log(prefix: string, msg: string): void {
+  const ts = new Date().toISOString().replace(/\.\d+Z$/, "Z");
+  try {
+    const line = `[${ts}] ${prefix}: ${msg}\n`;
+    writeFileSync(DEBUG_LOG, line, { flag: "a" });
+  } catch {
+    // fail silently
+  }
+}
+
+// --- Auth ---
+
+function getCachedToken(): string | null {
+  try {
+    const stat = statSync(JWT_CACHE);
+    const ageMs = Date.now() - stat.mtimeMs;
+    if (ageMs < 3_500_000) {
+      // ~58 min
+      return readFileSync(JWT_CACHE, "utf-8").trim();
+    }
+  } catch {
+    // no cache
+  }
+  return null;
+}
+
+async function login(): Promise<string | null> {
+  if (!PROJECT_ID) return null;
+
+  try {
+    const resp = await fetch(`${API_URL}/api/v1/auth/login`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Project-ID": PROJECT_ID,
+      },
+      body: JSON.stringify({ email: AUTH_EMAIL, password: AUTH_PASSWORD }),
+      signal: AbortSignal.timeout(5000),
+    });
+    if (!resp.ok) return null;
+
+    const data = (await resp.json()) as Record<string, unknown>;
+    const token =
+      (data.accessToken as string) ||
+      ((data.data as Record<string, unknown>)?.accessToken as string) ||
+      "";
+    if (token) {
+      writeFileSync(JWT_CACHE, token);
+    }
+    return token || null;
+  } catch {
+    return null;
+  }
+}
+
+export async function getToken(): Promise<string | null> {
+  return getCachedToken() || (await login());
+}
+
+// --- API Helpers ---
+
+async function apiGet<T>(path: string, token: string, timeoutMs = 5000): Promise<T | null> {
+  try {
+    const resp = await fetch(`${API_URL}${path}`, {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "X-Project-ID": PROJECT_ID,
+      },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!resp.ok) return null;
+    return (await resp.json()) as T;
+  } catch {
+    return null;
+  }
+}
+
+async function apiPost<T>(
+  path: string,
+  token: string,
+  body: Record<string, unknown>,
+  timeoutMs = 5000
+): Promise<T | null> {
+  try {
+    const resp = await fetch(`${API_URL}${path}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${token}`,
+        "X-Project-ID": PROJECT_ID,
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!resp.ok) return null;
+    return (await resp.json()) as T;
+  } catch {
+    return null;
+  }
+}
+
+// --- Workflow Queries ---
+
+export async function getActiveWorkflow(): Promise<WorkflowStatus | null> {
+  const token = await getToken();
+  if (!token) return null;
+
+  for (const status of ["in_progress", "awaiting_agent", "awaiting_approval"]) {
+    const resp = await apiGet<{ data?: WorkflowStatus[] }>(
+      `/api/v1/workflows?status=${status}&limit=1`,
+      token,
+      3000
+    );
+    const list = resp?.data || (Array.isArray(resp) ? (resp as WorkflowStatus[]) : null);
+    const wf = list?.[0];
+    if (wf?.id) return wf;
+  }
+  return null;
+}
+
+export async function getWorkflowStatus(workflowId: string): Promise<WorkflowStatus | null> {
+  const token = await getToken();
+  if (!token) return null;
+  return apiGet(`/api/v1/workflows/${workflowId}/status`, token);
+}
+
+export async function getWorkflowMode(workflowId: string): Promise<string | null> {
+  const status = await getWorkflowStatus(workflowId);
+  return status?.mode || null;
+}
+
+export async function getNextAction(workflowId: string): Promise<PendingAction | null> {
+  const token = await getToken();
+  if (!token) return null;
+  return apiGet(`/api/v1/workflows/${workflowId}/pending-action`, token);
+}
+
+export async function detectWorkflow(prompt: string): Promise<DetectResult | null> {
+  const token = await getToken();
+  if (!token) return null;
+  return apiPost(`/api/v1/workflows/detect`, token, { prompt }, 3000);
+}
+
+// --- Invocation Tracking ---
+
+export async function startInvocation(
+  agentType: string,
+  workflowId: string,
+  phase: string
+): Promise<void> {
+  const token = await getToken();
+  if (!token) return;
+  await apiPost(`/api/v1/invocations/start`, token, {
+    agentType,
+    workflowId,
+    phase,
+    startedAt: new Date().toISOString(),
+  });
+}
+
+export async function registerCheckpoint(
+  workflowId: string,
+  description: string,
+  commitHash: string
+): Promise<void> {
+  const token = await getToken();
+  if (!token) return;
+  await apiPost(`/api/v1/checkpoints`, token, {
+    workflowId,
+    description,
+    commitHash,
+  });
+}
+
+// --- Stdin Helper ---
+
+export async function readStdin(): Promise<Record<string, unknown>> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk as Buffer);
+  }
+  const raw = Buffer.concat(chunks).toString("utf-8").trim();
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+// --- JSON Field Access ---
+
+export function getField(obj: Record<string, unknown>, path: string): string {
+  const parts = path.split(".");
+  let current: unknown = obj;
+  for (const part of parts) {
+    if (current == null || typeof current !== "object") return "";
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current != null ? String(current) : "";
+}
+
+// --- Output Helpers ---
+
+export function outputPreToolUse(opts: {
+  decision: "allow" | "deny";
+  reason?: string;
+  context?: string;
+}): void {
+  const output: Record<string, unknown> = {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: opts.decision,
+      ...(opts.reason && { permissionDecisionReason: opts.reason }),
+      ...(opts.context && { additionalContext: opts.context }),
+    },
+  };
+  console.log(JSON.stringify(output));
+}
+
+export function outputContext(hookEvent: string, context: string): void {
+  console.log(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: hookEvent,
+        additionalContext: context,
+      },
+    })
+  );
+}
+
+export function outputBlock(reason: string): void {
+  console.log(JSON.stringify({ decision: "block", reason }));
+}