@orchestrator-claude/cli 3.17.0 → 3.18.0

package/dist/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/dist/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));

package/dist/templates/base/claude/settings.json

@@ -39,11 +39,11 @@
   "hooks": {
     "SessionStart": [
       {
-        "matcher": "startup",
+        "matcher": "startup|resume",
         "hooks": [
           {
             "type": "command",
-            "command": ".claude/hooks/session-orchestrator.sh",
+            "command": "npx tsx .claude/hooks/session-start.ts",
             "timeout": 10000,
             "on_failure": "ignore"
           }
@@ -56,7 +56,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": ".claude/hooks/prompt-orchestrator.sh",
+            "command": "npx tsx .claude/hooks/user-prompt.ts",
             "timeout": 10000,
             "on_failure": "ignore"
           }
@@ -69,7 +69,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": ".claude/hooks/gate-guardian.sh",
+            "command": "npx tsx .claude/hooks/gate-guardian.ts",
             "timeout": 15000,
             "on_failure": "warn"
           }
@@ -80,7 +80,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": ".claude/hooks/workflow-guard.sh",
+            "command": "npx tsx .claude/hooks/workflow-guard.ts",
             "timeout": 10000,
             "on_failure": "warn"
           }
@@ -89,12 +89,12 @@
     ],
     "SubagentStart": [
       {
-        "matcher": "implementer|specifier|planner|task-generator|reviewer|researcher|orchestrator",
+        "matcher": "implementer|specifier|planner|task-generator|reviewer|researcher",
         "hooks": [
           {
             "type": "command",
-            "command": ".claude/hooks/track-agent-invocation.sh start",
-            "timeout": 5000,
+            "command": "npx tsx .claude/hooks/subagent-start.ts",
+            "timeout": 10000,
             "on_failure": "ignore"
           }
         ]
@@ -102,37 +102,38 @@
     ],
     "SubagentStop": [
       {
-        "matcher": "implementer|specifier|planner|task-generator|reviewer|researcher|orchestrator",
+        "matcher": "implementer|specifier|planner|task-generator|reviewer|researcher",
         "hooks": [
           {
             "type": "command",
-            "command": ".claude/hooks/track-agent-invocation.sh complete",
-            "timeout": 5000,
+            "command": "npx tsx .claude/hooks/subagent-stop.ts",
+            "timeout": 30000,
             "on_failure": "ignore"
-          },
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
           {
             "type": "command",
-            "command": ".claude/hooks/ping-pong-enforcer.sh",
+            "command": "npx tsx .claude/hooks/dangling-guard.ts",
             "timeout": 15000,
-            "on_failure": "warn"
-          },
-          {
-            "type": "command",
-            "command": ".claude/hooks/post-phase-checkpoint.sh",
-            "timeout": 30000,
             "on_failure": "ignore"
           }
         ]
       }
     ],
-    "Stop": [
+    "PostCompact": [
       {
         "matcher": "",
         "hooks": [
           {
             "type": "command",
-            "command": ".claude/hooks/dangling-workflow-guard.sh",
-            "timeout": 15000,
+            "command": "npx tsx .claude/hooks/post-compact.ts",
+            "timeout": 5000,
             "on_failure": "ignore"
           }
         ]

package/dist/templates/base/claude/skills/orchestrator/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: orchestrator
+description: Workflow coordination — phase dispatch, sub-agent management, gate checks. Use when starting features/bugs/refactoring, or when the user invokes /orchestrator. The session greeting is handled by CLAUDE.md Rule #1 + hook data, NOT by this skill.
+---
+
+# Skill: /orchestrator
+
+You are the **workflow orchestrator**. The main conversation coordinates all phases directly — no orchestrator sub-agent needed. Sub-agents (specifier, planner, implementer, etc.) are dispatched via the Agent tool from this conversation.
+
+**Note:** The session greeting (AskUserQuestion on start) is handled by CLAUDE.md Rule #1 using hook-injected data. This skill is loaded only when the user chooses to start or continue a workflow.
+
+## Step 1: Start Workflow
+
+```
+mcp__orchestrator-tools__detectWorkflow({ prompt: "user's request" })
+mcp__orchestrator-tools__startWorkflow({ type: "feature_development|bug_fix|refactoring", prompt: "..." })
+```
+
+Workflow types: `feature_development`, `bug_fix`, `refactoring`, `emergency_debug`
+
+## Step 4: Phase Dispatch Loop
+
+For each phase in the workflow, follow this cycle:
+
+### 4a. Dispatch Phase Sub-Agent
+
+| Phase | Agent | What it produces |
+|-------|-------|-----------------|
+| 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 |
+
+Dispatch the appropriate sub-agent:
+
+```
+Agent(subagent_type: "{phase_agent}", prompt: "
+  [Workflow] Type: {type}, Phase: {phase}, Project: {projectId}
+  [Previous artifact] {summary of previous phase artifact, if any}
+  [Task] {phase-specific instructions from user's original request}
+")
+```
+
+**Critical:** Sub-agents MUST use `artifactStore` to persist artifacts to MinIO. Include this instruction in every sub-agent prompt:
+> Store your output artifact via mcp__orchestrator-extended__artifactStore with workflowId, type (spec|plan|tasks), and content.
+
+### 4b. Gate Check via AskUserQuestion
+
+After each sub-agent completes, present the artifact summary and ask for approval:
+
+```
+AskUserQuestion({
+  question: "Phase '{phase}' complete.\n\n{artifact_summary}\n\nApprove to proceed to next phase?",
+  options: ["Approve", "Request changes", "Abort workflow"]
+})
+```
+
+- **Approve**: Call `advancePhase` and dispatch next phase agent
+- **Request changes**: Re-dispatch the same sub-agent with feedback
+- **Abort**: Call `completeWorkflow` with cancelled status
+
+### 4c. Advance Phase
+
+```
+mcp__orchestrator-tools__advancePhase({ workflowId: "..." })
+```
+
+Then loop back to 4a for the next phase.
+
+## Step 5: Complete Workflow
+
+After all phases are done:
+
+```
+ToolSearch("select:mcp__orchestrator-extended__completeWorkflow")
+mcp__orchestrator-extended__completeWorkflow({ workflowId: "..." })
+```
+
+Summarize what was accomplished and any follow-up items.
+
+## Rules
+
+1. **YOU are the orchestrator** — dispatch sub-agents via Agent tool, do NOT invoke Agent(subagent_type: "orchestrator")
+2. **Every gate uses AskUserQuestion** — NEVER auto-approve phase transitions
+3. **Artifacts go to MinIO** — sub-agents MUST call artifactStore
+4. **MCP tools are deferred** — call ToolSearch before first use of any mcp__* tool
+5. **Keep sub-agent prompts focused** — include workflow context + previous artifact summary + task description
+6. **Summarize, don't dump** — when presenting gate checks, show a concise summary of the artifact, not the full content
+
+## Phase-Specific Skills
+
+Load these skills for phase-specific guidance when needed:
+
+| Skill | When |
+|-------|------|
+| `/artifact-production` | Before dispatching specify/plan/tasks agents |
+| `/tdd-discipline` | Before dispatching implementer |
+| `/project-conventions` | Before any implementation work |
+| `/checkpoint-protocol` | After completing task groups |
+
+## Error Recovery
+
+- **Sub-agent fails**: Read the error, fix the issue, re-dispatch
+- **MCP tool not found**: Call ToolSearch to load the schema, then retry
+- **Workflow stuck**: Call `getStatus` to diagnose, present options to user via AskUserQuestion
+- **Context getting large**: Sub-agents handle heavy work; main conversation stays lean with summaries

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orchestrator-claude/cli",
-  "version": "3.17.0",
+  "version": "3.18.0",
   "description": "Orchestrator CLI - Project scaffolding, migration and management",
   "type": "module",
   "main": "dist/index.js",

package/templates/base/CLAUDE.md.hbs

@@ -3,51 +3,64 @@
 ## Overview
 
 This project uses the **Orchestrator System** for autonomous workflow management.
-Orchestration is enforced by **deterministic hooks** — you do not need to memorize the workflow protocol.
+The main conversation IS the orchestrator — it coordinates all phases directly, dispatching sub-agents as needed.
 
 ## Critical Rules
 
-1. **NEVER implement features directly** — always use the orchestrator workflow
-2. **NEVER bump versions manually** — always use `/release patch|minor|major`
-3. **NEVER edit `.orchestrator/orchestrator-index.json`** — state is in PostgreSQL
-4. **Access artifacts via MCP tools** (`artifactStore`, `artifactRetrieve`), not filesystem paths
-
-## How to Start a Workflow
-
-For any feature request, bug fix, or refactoring:
+1. **On session start, greet via AskUserQuestion** — use `[ORCHESTRATOR-DATA]` from the SessionStart hook context (already injected). Do NOT load any skill for the greeting. Format:
+   ```
+   AskUserQuestion({
+     question: "━━ Orchestrator {version} ━━\n{status_summary}\nNext: {next_item}\n\nWhat would you like to do?",
+     options: ["Start workflow for next item", "Start workflow for something else", "Free conversation"]
+   })
+   ```
+   If `[ORCHESTRATOR-DATA]` is missing (API down), fallback: invoke `/orchestrator` skill.
+   If there is an active workflow, adapt greeting to show workflow state and offer "Continue workflow".
+2. **To start or manage workflows, invoke `/orchestrator`** — it coordinates phases, dispatches sub-agents, and enforces gates via AskUserQuestion.
+3. **NEVER implement features directly** — start a workflow first
+4. **NEVER bump versions manually** — always use `/release patch|minor|major`
+5. **NEVER edit `.orchestrator/orchestrator-index.json`** — state is in PostgreSQL
+6. **Access artifacts via MCP tools** (`artifactStore`, `artifactRetrieve`), not filesystem paths
+7. **NEVER invoke `Agent(subagent_type: "orchestrator")`** — YOU are the orchestrator (RFC-022)
+
+## How Workflows Work
+
+The main conversation is the orchestrator. Sub-agents (specifier, planner, implementer, etc.) are dispatched via the Agent tool directly.
 
 ```
-1. mcp__orchestrator-tools__detectWorkflow({ prompt: "user request" })
-2. mcp__orchestrator-tools__startWorkflow({ type: "...", prompt: "..." })
-3. MUST invoke orchestrator agent: Agent(subagent_type: "orchestrator")
-4. After EVERY phase agent completes, MUST invoke orchestrator agent again
+1. AskUserQuestion (greeting)                 ← immediate, uses hook data
+2. User chooses to start workflow
+3. /orchestrator skill + detectWorkflow       ← loads coordination context
+4. Agent(subagent_type: "specifier")          ← dispatched from main conversation
+5. AskUserQuestion → gate check              ← human approval
+6. advancePhase                               ← MCP tool
+7. Agent(subagent_type: "planner")            ← next phase
+8. ...repeat until complete...
+9. completeWorkflow                           ← MCP tool
 ```
 
-**MANDATORY:** The orchestrator agent coordinates ALL phase transitions. It calls `evaluateGate`, `advancePhase`, and `setPendingAction`. Do NOT call these tools directly from the main conversation. The ping-pong-enforcer hook will remind you after each sub-agent completes.
-
-**Exceptions** (may be called directly): `detectWorkflow`, `startWorkflow`, `approveAction`, `completeWorkflow`, `getStatus`.
+**Key principle:** Every phase gate uses `AskUserQuestion` — never auto-approve transitions.
 
 Workflow types: `feature_development`, `bug_fix`, `refactoring`, `emergency_debug`
 
-## What Hooks Enforce Automatically
+## What Hooks Enforce Automatically (TypeScript, RFC-022)
 
 | Hook | Trigger | What it does |
 |------|---------|-------------|
-| `ping-pong-enforcer` | After every Agent call | Calls `getNextAction` and injects result |
-| `gate-guardian` | Before `advancePhase` | Evaluates gate, blocks if it fails |
-| `workflow-guard` | Before Write/Edit on src/ | Blocks code writes without an active workflow |
-| `dangling-workflow-guard` | On session Stop | Warns and completes dangling workflows |
-| `session-orchestrator` | On session Start | Injects workflow status context |
-| `prompt-orchestrator` | On user prompt Submit | Injects workflow status context |
-
-You do NOT need to manually call `getNextAction` after agents or `evaluateGate` before advancing — hooks do this deterministically.
+| `session-start.ts` | SessionStart | Injects `[ORCHESTRATOR-DATA]` (version, workflow, next item) for greeting |
+| `user-prompt.ts` | UserPromptSubmit | Detects workflow type, injects hints |
+| `gate-guardian.ts` | Before `advancePhase` | Blocks unless IMPLEMENT phase has approval |
+| `workflow-guard.ts` | Before Write/Edit on src/ | Blocks code writes without active workflow |
+| `subagent-start.ts` | SubagentStart | Registers agent invocation via API |
+| `subagent-stop.ts` | SubagentStop | Completes invocation + git checkpoint + next step guidance |
+| `dangling-guard.ts` | Stop | Warns about dangling workflows |
+| `post-compact.ts` | PostCompact | Re-injects workflow state after context compaction |
 
 ## Skills (On-Demand Context)
 
-Use skills for phase-specific guidance:
-
 | Skill | When to use |
 |-------|------------|
+| `/orchestrator` | **Workflow coordination** — phase dispatch, sub-agent management, gate checks |
 | `/workflow-status` | Check current workflow state |
 | `/artifact-production` | Phase-specific artifact formats |
 | `/tdd-discipline` | TDD protocol during IMPLEMENT |
@@ -66,6 +79,11 @@ Use skills for phase-specific guidance:
 - **Clean Architecture**: Dependencies point inward
 - **TypeScript Strict**: `strict: true` required
 
+## MCP Tool Notes
+
+Extended MCP tools (`artifactStore`, `completeWorkflow`, KB graph tools) are deferred-loaded.
+On the first call in a session you may get `No such tool available` — retry once and it will succeed.
+
 ---
 
 *This project was initialized with the Orchestrator CLI.*