@orchestrator-claude/cli 3.10.2 → 3.12.0

package/templates/base/CLAUDE.md.hbs

@@ -2,330 +2,60 @@
 
 ## Overview
 
-This project uses the **Orchestrator System** for autonomous workflow management. When handling feature requests, bug fixes, or refactoring tasks, you MUST use the orchestrator workflow instead of implementing directly.
+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.
 
-## Critical Rule
+## Critical Rules
 
-**NEVER implement features directly.** Always use the orchestrator workflow:
-
-```
-User Request → Detect Workflow → Research (if needed) → SPECIFY → PLAN → TASKS → Implement
-```
+1. **NEVER implement features directly** — always use the orchestrator workflow
+2. **NEVER edit `.orchestrator/orchestrator-index.json`** — state is in PostgreSQL
+3. **Access artifacts via MCP tools** (`artifactStore`, `artifactRetrieve`), not filesystem paths
 
 ## How to Start a Workflow
 
-When a user requests a new feature, bug fix, or refactoring:
-
-### 1. Detect Workflow Type
-
-Use the MCP tool to detect the workflow type:
-
-```
-mcp__orchestrator-tools__detectWorkflow({ prompt: "user request here" })
-```
-
-Workflow types:
-- `feature_development` - New features, new functionality
-- `bug_fix` - Bug fixes, error corrections
-- `refactoring` - Code refactoring, improvements
-- `emergency_debug` - Urgent debugging
-
-### 2. Start Workflow and Get Next Step
-
-**MANDATORY:** After detecting workflow type, call `startWorkflow` to create the workflow:
-
-```
-mcp__orchestrator-tools__startWorkflow({ workflowType: "feature-development", prompt: "user request here" })
-```
-
-This returns a deterministic `nextStep` instruction:
-
-```json
-{
-  "success": true,
-  "workflowId": "wf-123",
-  "nextStep": {
-    "action": "invoke_agent",
-    "subagent_type": "orchestrator",
-    "prompt": "Start workflow feature-development (ID: wf-123) for user request: ..."
-  }
-}
-```
-
-### 3. Execute nextStep (Invoke Orchestrator Agent)
-
-**IMMEDIATELY** follow the `nextStep` instruction by invoking the orchestrator agent via Task tool:
-
-```
-Use the Task tool with subagent_type from nextStep.subagent_type
-Prompt: nextStep.prompt
-```
-
-The orchestrator agent will:
-1. Set pending actions for specialized agents
-2. Return control to CLI for Ping-Pong pattern
-3. CLI invokes agents via Task tool as directed by getNextAction()
-4. Process continues until workflow completes
-
-## Available MCP Tools
-
-### orchestrator-tools
-- `detectWorkflow` - Detect workflow type from user prompt
-- `startWorkflow` - **Create workflow and get deterministic nextStep instruction** (MANDATORY after detectWorkflow)
-- `advancePhase` - Advance to the next workflow phase
-- `evaluateGate` - Evaluate if a phase gate passes
-- `validateArtifact` - Validate artifact against schema
-- `createCheckpoint` - Create a git checkpoint
-- `getStatus` - Get current workflow status
-- `getWorkflows` - List workflows with phase configs (including `requiresApproval`)
-- `getNextAction` - Get the next pending action (Ping-Pong pattern)
-
-### knowledge-base
-- `search` - Search the knowledge base
-- `getDocument` - Get a specific document
-- `getConstitution` - Get the project constitution
-- `listByTier` - List documents by tier
-- `listByCategory` - List documents by category
-
-## Auto-Advance Behavior (requiresApproval)
-
-**CRITICAL**: Each workflow phase has a `requiresApproval` configuration.
-
-### How It Works
-
-1. **Load workflow config** at start using `getWorkflows`:
-   ```
-   mcp__orchestrator-tools__getWorkflows()
-   ```
-
-2. **Check each phase's `requiresApproval`**:
-   - `requiresApproval: false` → **AUTO-ADVANCE** after gate passes (no user interaction)
-   - `requiresApproval: true` → **PAUSE** and ask user for approval
-
-### Default Configuration (feature-development)
+For any feature request, bug fix, or refactoring:
 
 ```
-SPECIFY  → requiresApproval: false → auto-advance
-PLAN     → requiresApproval: false → auto-advance
-TASKS    → requiresApproval: false → auto-advance
-IMPLEMENT → requiresApproval: true  → PAUSE HERE
+1. mcp__orchestrator-tools__detectWorkflow({ prompt: "user request" })
+2. mcp__orchestrator-tools__startWorkflow({ workflowType: "...", prompt: "..." })
+3. Follow the nextStep returned — hooks handle the rest automatically
 ```
 
-### Expected Behavior
-
-- **DO NOT ask user** between SPECIFY → PLAN → TASKS phases
-- **Run these phases sequentially** invoking each agent automatically
-- **ONLY pause** before IMPLEMENT phase (or phases with `requiresApproval: true`)
-- This reduces unnecessary interactions and speeds up the workflow
-
-### Example Flow
-
-```
-User: "Create a calculator function"
-
-Claude:
-1. detectWorkflow({ prompt: "Create a calculator function" }) → feature-development
-2. startWorkflow({ workflowType: "feature-development", prompt: "..." }) → { nextStep: {...} }
-3. Execute nextStep → Invoke orchestrator agent via Task tool
-4. getNextAction() → { agent: "specifier", status: "awaiting_agent" }
-5. Invoke specifier via Task tool → spec.md created
-6. getNextAction() → { agent: "planner", status: "awaiting_agent" }
-7. Invoke planner via Task tool → plan.md created
-8. getNextAction() → { agent: "task-generator", status: "awaiting_agent" }
-9. Invoke task-generator via Task tool → tasks.md created
-10. getNextAction() → { status: "awaiting_approval" }
-11. Ask user: "Artifacts ready. Approve implementation?"
-```
-
-## Workflow Phases
-
-```
-RESEARCH (optional)
-    ↓
-  SPECIFY
-    ↓
-   PLAN
-    ↓
-  TASKS
-    ↓
-  [HUMAN APPROVAL REQUIRED]
-    ↓
-IMPLEMENT
-```
-
-Each phase produces artifacts stored in MinIO (object storage) and tracked in PostgreSQL:
-- `research` - Research context documents
-- `specify` - Specifications (spec.md)
-- `plan` - Technical plans (plan.md)
-- `tasks` - Task backlogs (tasks.md)
-- `implement` - Implementation reports
-
-**CRITICAL**: Artifacts are accessed via MCP tools (`artifactStore`, `artifactRetrieve`), NOT via filesystem paths. The `.orchestrator/artifacts/` directory does NOT exist on the filesystem.
-
----
+Workflow types: `feature_development`, `bug_fix`, `refactoring`, `emergency_debug`
 
-## Workflow Execution Pattern (Ping-Pong Híbrido)
+## What Hooks Enforce Automatically
 
-### Critical Rule: Always Check for Pending Actions
+| 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 |
+| `dangling-workflow-guard` | On session Stop | Warns and completes dangling workflows |
+| `workflow-guard` | Before Write/Edit on src/ | Blocks code writes without an active workflow |
 
-**MANDATORY:** After EVERY Task tool invocation that involves workflow orchestration, you MUST:
+You do NOT need to manually call `getNextAction` after agents or `evaluateGate` before advancing — hooks do this deterministically.
 
-1. **Call `mcp__orchestrator-tools__getNextAction()`**
-2. **Analyze the response and take appropriate action**
+## Skills (On-Demand Context)
 
-### Status → Action Mapping
+Use skills for phase-specific guidance:
 
-| Status | Your Action |
-|--------|-------------|
-| `awaiting_agent` | **Immediately** invoke the specified agent via Task tool |
-| `awaiting_approval` | **Ask user** for approval, then call `approveAction()` |
-| `running` | Agent is currently executing, do nothing |
-| No pending action | Workflow is complete or paused |
+| Skill | When to use |
+|-------|------------|
+| `/workflow-status` | Check current workflow state |
+| `/artifact-production` | Phase-specific artifact formats |
+| `/tdd-discipline` | TDD protocol during IMPLEMENT |
+| `/project-conventions` | Project patterns and gotchas |
+| `/checkpoint-protocol` | When to create checkpoints |
+| `/kb-lookup` | Search project knowledge base |
 
-### Workflow Execution Loop
+## Creating Custom Definitions
 
-```typescript
-// MANDATORY PATTERN for workflow execution
+When creating agents, skills, or hooks, write to BOTH filesystem and PostgreSQL:
 
-// 1. Detect workflow type
-const detection = await detectWorkflow({ prompt: "Create authentication API" });
+- **Agent**: Write `.claude/agents/{slug}.md` + `createAgentDefinition` MCP tool
+- **Skill**: Write `.claude/skills/{slug}/SKILL.md` + `createSkillDefinition` MCP tool
+- **Hook**: Write `.claude/hooks/{slug}.sh` + `createHook` MCP tool
 
-// 2. Start workflow and get nextStep (DETERMINISTIC)
-const startResult = await startWorkflow({
-  workflowType: detection.workflowType,
-  prompt: "Create authentication API"
-});
-
-// 3. Execute nextStep - invoke orchestrator agent
-await invokeTool("Task", {
-  subagent_type: startResult.nextStep.subagent_type, // "orchestrator"
-  prompt: startResult.nextStep.prompt
-});
-
-// 4. Check for pending actions (Ping-Pong loop)
-const action = await getNextAction();
-
-// 5. Handle the action
-if (action.hasAction && action.pendingAction.status === "awaiting_agent") {
-  // Immediately invoke the specified agent
-  await invokeTool("Task", {
-    subagent_type: action.pendingAction.agent,
-    prompt: action.pendingAction.prompt
-  });
-
-  // 6. REPEAT: Check for next action after agent completes
-  const nextAction = await getNextAction();
-  // ... continue loop
-}
-
-if (action.hasAction && action.pendingAction.status === "awaiting_approval") {
-  // Inform user and wait for approval
-  console.log("⚠️ Workflow requires approval before continuing to IMPLEMENT phase.");
-  console.log("Review artifacts and type 'yes' to proceed.");
-
-  // After user approves:
-  await approveAction({ workflowId: action.workflowId });
-
-  // Then check for next action again
-  const nextAction = await getNextAction();
-  // ...
-}
-```
-
-### What NOT to Do
-
-- ❌ **NEVER** skip `startWorkflow` after `detectWorkflow` - it creates the workflow and returns deterministic `nextStep`
-- ❌ **NEVER** ignore `nextStep` from `startWorkflow` - it tells you exactly which agent to invoke
-- ❌ **NEVER** ignore `getNextAction()` after Task tool invocation
-- ❌ **NEVER** decide which agent to invoke without checking `pendingAction`
-- ❌ **NEVER** skip to IMPLEMENT phase without user approval
-- ❌ **NEVER** execute multiple phases in a single agent invocation
-- ❌ **NEVER** use Write/Edit tools to create artifacts during orchestration (let specialized agents do it)
-- ❌ **NEVER** invoke agents out of order defined by `pendingAction`
-
-### Why This Pattern?
-
-**Problem (LIM-001):** Context window bloat when orchestrator executes all phases internally in one invocation.
-
-**Solution (Ping-Pong Híbrido):** Orchestrator acts as **dispatcher**, creating `pendingActions` that guide the CLI to invoke specialized agents in separate, isolated invocations.
-
-**Benefits:**
-- Each agent invocation has isolated context (< 12k tokens)
-- Total token usage reduced by 40%+
-- No hallucination from massive context
-- Real agent metrics (not simulated)
-- Workflow resumable after crashes (pendingAction persists)
-
----
-
-## MANDATORY: IMPLEMENT Phase Delegation
-
-> **WARNING**
->
-> The IMPLEMENT phase REQUIRES delegation to the implementer subagent.
-> Direct implementation is FORBIDDEN and will break workflow governance.
-
-### Trigger Phrases
-
-When user approves implementation with ANY of these phrases:
-
-**English:**
-- "yes", "yes, implement", "proceed", "go ahead", "continue"
-- "start implementation", "implement it", "do it"
-
-**Portuguese:**
-- "sim", "prossiga", "continue", "pode implementar"
-- "manda ver", "vai la", "implementa"
-
-### Required Actions (IN ORDER)
-
-1. **ANNOUNCE DELEGATION:**
-   ```
-   I will now delegate to the implementer agent to execute the tasks.
-   ```
-
-2. **ADVANCE PHASE:**
-   ```
-   mcp__orchestrator-tools__advancePhase({ workflowId: "current-workflow-id" })
-   ```
-
-3. **INVOKE IMPLEMENTER (REQUIRED):**
-   ```
-   Use the Task tool with subagent_type="implementer"
-
-   Prompt:
-   Execute all tasks from .orchestrator/artifacts/tasks/tasks.md
-
-   Context:
-   - Specification: .orchestrator/artifacts/specify/spec.md
-   - Plan: .orchestrator/artifacts/plan/plan.md
-   - Tasks: .orchestrator/artifacts/tasks/tasks.md
-
-   Requirements:
-   - Follow TDD (write tests BEFORE implementation)
-   - Maintain {{coverageThreshold}}% minimum coverage
-   - Create checkpoint after every 3-5 tasks
-   - Generate implementation-report.md at the end
-   ```
-
-### FORBIDDEN Actions
-
-- Using Edit/Write tools directly for code implementation
-- Skipping Task tool invocation
-- Writing production code without implementer agent
-- Editing `.orchestrator/orchestrator-index.json` directly (state is in PostgreSQL)
-
-### Self-Verification Checklist
-
-Before proceeding, verify:
-- [ ] Did I announce delegation to the user?
-- [ ] Did I call advancePhase via MCP?
-- [ ] Did I use Task tool with subagent_type="implementer"?
-- [ ] Is the implementer prompt complete with all context?
-
-If ANY answer is NO -> STOP and correct before continuing.
-
----
+Built-in definitions are seeded on `orchestrator init` (idempotent).
 
 ## Quality Rules
 
@@ -335,33 +65,6 @@ If ANY answer is NO -> STOP and correct before continuing.
 - **Clean Architecture**: Dependencies point inward
 - **TypeScript Strict**: `strict: true` required
 
-## State Management
-
-```
-PostgreSQL (Single Source of Truth):
-├── workflows          # Workflow state, pending actions, phases
-├── artifacts          # Artifact metadata
-├── checkpoints        # Checkpoint metadata
-└── agent_invocations  # Agent invocation history
-
-MinIO (Object Storage):
-└── artifacts/         # Generated artifact content by phase
-
-.orchestrator/ (DEPRECATED - do NOT read or write directly):
-└── orchestrator-index.json  # DEPRECATED: state is in PostgreSQL
-```
-
-**CRITICAL**: All workflow state is in PostgreSQL. All artifact content is in MinIO. Access everything through MCP tools. NEVER edit `.orchestrator/orchestrator-index.json` directly.
-
-## Important Notes
-
-1. **Always start with workflow detection** - Don't skip this step
-2. **Let agents do their work** - Don't bypass the workflow
-3. **Validate artifacts** - Use the artifact-validator skill
-4. **Check gates** - Use phase-gate-evaluator before advancing
-5. **Create checkpoints** - After each validated artifact
-6. **Consult CONSTITUTION** - For project rules and constraints
-
 ---
 
 *This project was initialized with the Orchestrator CLI.*

package/templates/base/claude/hooks/dangling-workflow-guard.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+# dangling-workflow-guard.sh — ADR-013 Phase 5 Hook (JSON Structured Output)
+# Trigger: Stop
+# Purpose: Before conversation ends, check for workflows in in_progress state.
+#          Blocks stop and instructs LLM to call completeWorkflow.
+#
+# Output: JSON with decision: "block" + reason (forces LLM to continue)
+# Exit 0 with block JSON = prevent stop
+# Check stop_hook_active to prevent infinite loops
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/orch-helpers.sh"
+
+STDIN_DATA=$(orch_read_stdin)
+orch_log "DANGLING-GUARD: Stop hook triggered"
+
+# Prevent infinite loops
+STOP_ACTIVE=$(orch_json_field "$STDIN_DATA" "stop_hook_active")
+if [ "$STOP_ACTIVE" = "true" ]; then
+  orch_log "DANGLING-GUARD: stop_hook_active=true, allowing stop to prevent loop"
+  exit 0
+fi
+
+# Find active workflow
+WORKFLOW_ID=$(orch_get_active_workflow 2>/dev/null) || WORKFLOW_ID=""
+
+if [ -z "$WORKFLOW_ID" ]; then
+  orch_log "DANGLING-GUARD: No active workflow, clean exit"
+  exit 0
+fi
+
+# Get workflow status
+TOKEN=$(orch_get_token 2>/dev/null) || TOKEN=""
+if [ -z "$TOKEN" ]; then
+  orch_log "DANGLING-GUARD: Auth failed, allowing stop"
+  exit 0
+fi
+
+STATUS_RESP=$(curl -sf --max-time 5 "${API_URL}/api/v1/workflows/${WORKFLOW_ID}/status" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "X-Project-ID: $PROJECT_ID" 2>/dev/null) || STATUS_RESP=""
+
+PHASE=$(orch_json_field "$STATUS_RESP" "currentPhase")
+STATUS=$(orch_json_field "$STATUS_RESP" "status")
+
+orch_log "DANGLING-GUARD: workflow=$WORKFLOW_ID status=$STATUS phase=$PHASE"
+
+if [ "$STATUS" = "in_progress" ] || [ "$STATUS" = "awaiting_agent" ] || [ "$STATUS" = "awaiting_approval" ]; then
+  orch_log "DANGLING-GUARD: BLOCK stop (workflow still active)"
+  echo "{\"decision\":\"block\",\"reason\":\"[DANGLING-GUARD] Workflow ${WORKFLOW_ID} is still ${STATUS} (phase: ${PHASE}). You must call mcp__orchestrator-extended__completeWorkflow({ workflowId: '${WORKFLOW_ID}' }) before ending the session.\"}"
+  exit 0
+fi
+
+orch_log "DANGLING-GUARD: Workflow completed or not active, allowing stop"
+exit 0

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

@@ -0,0 +1,79 @@
+#!/bin/bash
+# gate-guardian.sh — ADR-013 Phase 5 Hook (JSON Structured Output)
+# Trigger: PreToolUse on mcp__orchestrator-tools__advancePhase
+# Purpose: Evaluate gate before phase advance. FAIL-CLOSED: blocks when uncertain.
+#
+# Output: JSON with permissionDecision (deny/allow) + additionalContext
+# Exit 0 with JSON = structured decision
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/orch-helpers.sh"
+
+STDIN_DATA=$(orch_read_stdin)
+orch_log "GATE-GUARDIAN: PreToolUse advancePhase triggered"
+
+# Extract parameters
+WORKFLOW_ID=$(orch_json_field "$STDIN_DATA" "tool_input.workflowId")
+TARGET_PHASE=$(orch_json_field "$STDIN_DATA" "tool_input.targetPhase")
+[ -z "$WORKFLOW_ID" ] && WORKFLOW_ID=$(orch_json_field "$STDIN_DATA" "workflowId")
+[ -z "$TARGET_PHASE" ] && TARGET_PHASE=$(orch_json_field "$STDIN_DATA" "targetPhase")
+
+orch_log "GATE-GUARDIAN: workflow=$WORKFLOW_ID targetPhase=$TARGET_PHASE"
+
+# FAIL-CLOSED: if we can't parse input, DENY
+if [ -z "$WORKFLOW_ID" ] || [ -z "$TARGET_PHASE" ]; then
+  orch_log "GATE-GUARDIAN: DENY (could not parse input)"
+  echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"Gate Guardian: Could not parse workflowId or targetPhase.","additionalContext":"Ensure you pass both workflowId and targetPhase to advancePhase."}}'
+  exit 0
+fi
+
+# Get auth token — FAIL-CLOSED on auth failure
+TOKEN=$(orch_get_token 2>/dev/null) || TOKEN=""
+if [ -z "$TOKEN" ]; then
+  orch_log "GATE-GUARDIAN: DENY (auth failed)"
+  echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"Gate Guardian: Authentication failed.","additionalContext":"Check ORCHESTRATOR_ADMIN_EMAIL, ORCHESTRATOR_ADMIN_PASSWORD, ORCHESTRATOR_PROJECT_ID env vars."}}'
+  exit 0
+fi
+
+# Special handling for IMPLEMENT phase: require approval
+TARGET_LOWER=$(echo "$TARGET_PHASE" | tr '[:upper:]' '[:lower:]')
+if [ "$TARGET_LOWER" = "implement" ]; then
+  orch_log "GATE-GUARDIAN: Checking approval for IMPLEMENT phase"
+
+  PENDING=$(curl -sf --max-time 5 "${API_URL}/api/v1/workflows/${WORKFLOW_ID}/pending-action" \
+    -H "Authorization: Bearer $TOKEN" \
+    -H "X-Project-ID: $PROJECT_ID" 2>/dev/null) || PENDING=""
+
+  if [ -n "$PENDING" ]; then
+    PENDING_STATUS=$(orch_json_field "$PENDING" "status")
+    if [ "$PENDING_STATUS" != "approved" ] && [ "$PENDING_STATUS" != "awaiting_agent" ]; then
+      orch_log "GATE-GUARDIAN: DENY (IMPLEMENT requires approval, status=$PENDING_STATUS)"
+      echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"Gate Guardian: IMPLEMENT requires human approval. Status: ${PENDING_STATUS}.\",\"additionalContext\":\"Ask the user for approval first. Then call mcp__orchestrator-tools__approveAction.\"}}"
+      exit 0
+    fi
+  fi
+fi
+
+# Evaluate gate via API — FAIL-CLOSED on failure
+GATE_RESULT=$(orch_evaluate_gate "$WORKFLOW_ID" "$TARGET_PHASE" 2>/dev/null) || GATE_RESULT=""
+if [ -z "$GATE_RESULT" ]; then
+  orch_log "GATE-GUARDIAN: DENY (gate evaluation failed)"
+  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"Gate Guardian: Gate evaluation failed for phase '${TARGET_PHASE}'.\",\"additionalContext\":\"Required artifacts may be missing. Complete the current phase before advancing.\"}}"
+  exit 0
+fi
+
+PASSED=$(orch_json_field "$GATE_RESULT" "passed")
+
+if [ "$PASSED" = "true" ]; then
+  orch_log "GATE-GUARDIAN: ALLOW (gate passed for $TARGET_PHASE)"
+  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"additionalContext\":\"Gate to '${TARGET_PHASE}' passed.\"}}"
+  exit 0
+fi
+
+# Gate failed
+REASONS=$(orch_json_field "$GATE_RESULT" "reasons")
+orch_log "GATE-GUARDIAN: DENY (gate failed: $REASONS)"
+echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"Gate Guardian: Gate to '${TARGET_PHASE}' did not pass.\",\"additionalContext\":\"Reasons: ${REASONS}. Complete current phase requirements before advancing.\"}}"
+exit 0

package/templates/base/claude/hooks/orch-helpers.sh

@@ -0,0 +1,133 @@
+#!/bin/bash
+# orch-helpers.sh — Shared helper functions for Orchestrator hooks
+# ADR-013: Deterministic Orchestration
+# Sourced by all hooks. NOT called directly.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+STATE_DIR="$PROJECT_ROOT/.orchestrator/.state"
+DEBUG_LOG="$STATE_DIR/hook-debug.log"
+
+# API Configuration (from .env or defaults)
+API_URL="${ORCHESTRATOR_API_URL:-http://localhost:3001}"
+AUTH_EMAIL="${ORCHESTRATOR_ADMIN_EMAIL:-${ORCHESTRATOR_AUTH_EMAIL:-admin@orchestrator.local}}"
+AUTH_PASSWORD="${ORCHESTRATOR_ADMIN_PASSWORD:-${ORCHESTRATOR_AUTH_PASSWORD:-admin123}}"
+PROJECT_ID="${ORCHESTRATOR_PROJECT_ID}"
+
+mkdir -p "$STATE_DIR"
+
+orch_log() {
+  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] $*" >> "$DEBUG_LOG" 2>/dev/null || true
+}
+
+# Read stdin (Claude Code passes JSON via stdin)
+orch_read_stdin() {
+  if [ ! -t 0 ]; then
+    cat
+  else
+    echo ""
+  fi
+}
+
+# Get cached JWT token (login if expired)
+orch_get_token() {
+  local cached="$STATE_DIR/jwt-token"
+  if [ -f "$cached" ]; then
+    local age
+    age=$(( $(date +%s) - $(stat -c%Y "$cached" 2>/dev/null || stat -f%m "$cached" 2>/dev/null || echo 0) ))
+    if [ "$age" -lt 3500 ]; then
+      cat "$cached"
+      return
+    fi
+  fi
+
+  [ -z "$PROJECT_ID" ] && return 1
+
+  local resp
+  resp=$(curl -sf --max-time 5 -X POST "${API_URL}/api/v1/auth/login" \
+    -H "Content-Type: application/json" \
+    -H "X-Project-ID: $PROJECT_ID" \
+    -d "{\"email\":\"${AUTH_EMAIL}\",\"password\":\"${AUTH_PASSWORD}\"}" 2>/dev/null) || return 1
+
+  local token
+  token=$(echo "$resp" | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{const j=JSON.parse(d);console.log(j.accessToken||j.data?.accessToken||'')}catch{console.log('')}})" 2>/dev/null)
+
+  if [ -n "$token" ] && [ "$token" != "" ]; then
+    echo "$token" > "$cached"
+    echo "$token"
+  else
+    return 1
+  fi
+}
+
+# Get the active (non-terminal) workflow ID
+# Checks in_progress, awaiting_agent, and awaiting_approval statuses
+orch_get_active_workflow() {
+  local token
+  token=$(orch_get_token) || return 1
+
+  local status id
+  for status in in_progress awaiting_agent awaiting_approval; do
+    local resp
+    resp=$(curl -sf --max-time 3 "${API_URL}/api/v1/workflows?status=${status}&limit=1" \
+      -H "Authorization: Bearer $token" \
+      -H "X-Project-ID: $PROJECT_ID" 2>/dev/null) || continue
+
+    id=$(echo "$resp" | node -e "
+      let d='';
+      process.stdin.on('data',c=>d+=c);
+      process.stdin.on('end',()=>{
+        try {
+          const j=JSON.parse(d);
+          const wfs=j.data||j;
+          const wf=Array.isArray(wfs)?wfs[0]:wfs;
+          const id=wf?.id||'';
+          if(id) console.log(id); else process.exit(1);
+        } catch { process.exit(1); }
+      });" 2>/dev/null) && [ -n "$id" ] && echo "$id" && return 0
+  done
+  return 1
+}
+
+# Call getNextAction for a workflow
+orch_get_next_action() {
+  local workflow_id="$1"
+  local token
+  token=$(orch_get_token) || return 1
+
+  curl -sf --max-time 5 "${API_URL}/api/v1/workflows/${workflow_id}/pending-action" \
+    -H "Authorization: Bearer $token" \
+    -H "X-Project-ID: $PROJECT_ID" 2>/dev/null
+}
+
+# Call evaluateGate for a workflow
+orch_evaluate_gate() {
+  local workflow_id="$1"
+  local target_phase="$2"
+  local token
+  token=$(orch_get_token) || return 1
+
+  curl -sf --max-time 10 -X POST "${API_URL}/api/v1/workflows/${workflow_id}/gate/evaluate" \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $token" \
+    -H "X-Project-ID: $PROJECT_ID" \
+    -d "{\"targetPhase\":\"${target_phase}\"}" 2>/dev/null
+}
+
+# Extract a field from JSON string using node
+orch_json_field() {
+  local json="$1"
+  local field="$2"
+  echo "$json" | node -e "
+    let d='';
+    process.stdin.on('data',c=>d+=c);
+    process.stdin.on('end',()=>{
+      try {
+        const j=JSON.parse(d);
+        const parts='${field}'.split('.');
+        let v=j;
+        for(const p of parts) v=v?.[p];
+        console.log(v||'');
+      } catch { console.log(''); }
+    });" 2>/dev/null
+}