@orchestrator-claude/cli 3.17.1 → 3.19.0

package/dist/index.d.ts

@@ -12,5 +12,5 @@
 /**
  * CLI version
  */
-export declare const CLI_VERSION = "3.17.1";
+export declare const CLI_VERSION = "3.19.0";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -24,7 +24,7 @@ import { OutputFormatter } from './formatters/OutputFormatter.js';
 /**
  * CLI version
  */
-export const CLI_VERSION = '3.17.1';
+export const CLI_VERSION = '3.19.0';
 /**
  * Main CLI function
  */

package/dist/templates/base/CLAUDE.md.hbs

@@ -3,52 +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 |
-| `approval-guardian` | Before `approveAction`/`completeWorkflow` | Blocks auto-approve when workflow awaiting_approval |
-| `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 |
@@ -67,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.*

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