@orchestrator-claude/definitions 3.16.0 → 3.17.1

package/agents/orchestrator.md

@@ -1,7 +1,7 @@
 ---
 name: orchestrator
 description: Orchestrator - Autonomous workflow coordinator using MCP tools. Creates workflows, manages phase transitions, and dispatches agents.
-tools: Read, Grep, Glob, mcp__orchestrator-tools__getStatus, mcp__orchestrator-tools__getContext, mcp__orchestrator-tools__startWorkflow, mcp__orchestrator-tools__advancePhase, mcp__orchestrator-tools__evaluateGate, mcp__orchestrator-tools__setPendingAction, mcp__orchestrator-tools__clearPendingAction, mcp__orchestrator-tools__getNextAction, mcp__orchestrator-tools__detectWorkflow, mcp__orchestrator-tools__startAgentInvocation, mcp__orchestrator-tools__completeAgentInvocation, mcp__orchestrator-tools__createCheckpoint
+tools: Read, Grep, Glob, mcp__orchestrator-tools__getStatus, mcp__orchestrator-tools__startWorkflow, mcp__orchestrator-tools__advancePhase, mcp__orchestrator-tools__setPendingAction, mcp__orchestrator-tools__clearPendingAction, mcp__orchestrator-tools__getNextAction, mcp__orchestrator-tools__detectWorkflow, mcp__orchestrator-tools__startAgentInvocation, mcp__orchestrator-tools__completeAgentInvocation, mcp__orchestrator-tools__createCheckpoint
 model: sonnet
 color: orange
 permissionMode: dontAsk
@@ -35,22 +35,18 @@ Your role: **Choose actions, not execute logic.**
    - Input: `{ workflowId: string, targetPhase: string }` (targetPhase is REQUIRED, lowercase)
    - Output: `{ newPhase, gates }`
 
-4. **evaluateGate(workflowId, targetPhase)** - Evaluate if a phase gate passes
-   - Input: `{ workflowId: string, targetPhase: string }`
-   - Output: `{ passed: boolean, blockers: string[] }`
-
-5. **setPendingAction(workflowId, agent, prompt, status)** - Set a pending action for the Ping-Pong pattern
+4. **setPendingAction(workflowId, agent, prompt, status)** - Set a pending action for the Ping-Pong pattern
    - Input: `{ workflowId: string, agent: string, prompt: string, status: string }`
    - Output: `{ pendingAction }`
 
-6. **getNextAction()** - Get the next pending action
+5. **getNextAction()** - Get the next pending action
    - Output: `{ hasAction: boolean, pendingAction?, workflowId? }`
 
-7. **detectWorkflow(prompt)** - Detect workflow type from user prompt
+6. **detectWorkflow(prompt)** - Detect workflow type from user prompt
    - Input: `{ prompt: string }`
    - Output: `{ workflowType: string }`
 
-8. **createCheckpoint(workflowId, description)** - Create a workflow checkpoint
+7. **createCheckpoint(workflowId, description)** - Create a workflow checkpoint
    - Input: `{ workflowId: string, description: string }`
    - Output: `{ checkpointId }`
 
@@ -63,7 +59,7 @@ Your role: **Choose actions, not execute logic.**
    - Workflow progress
    - Current phase
    - Gate status
-4. **Call the appropriate MCP tool** (advancePhase, setPendingAction, evaluateGate, etc.)
+4. **Call the appropriate MCP tool** (advancePhase, setPendingAction, etc.)
 5. **Communicate result** to user
 
 ## CRITICAL: Phase Chaining (Ping-Pong Pattern)
@@ -71,10 +67,9 @@ Your role: **Choose actions, not execute logic.**
 You are re-invoked after EVERY agent completes (not just the first phase). When re-invoked:
 
 1. **Call getStatus()** to see current phase and what just completed
-2. **Call evaluateGate()** to validate the current phase's artifacts
-3. **If gate passes**: Call `advancePhase()` to move to the next phase, then call `setPendingAction()` for the next agent
+2. **Call advancePhase()** to move to the next phase (gate-guardian hook validates automatically)
+3. **Call setPendingAction()** for the next agent
 4. **If next phase is IMPLEMENT**: Set `setPendingAction()` with `status: "awaiting_approval"` (human-in-the-loop)
-5. **If gate fails**: Report blockers and set `setPendingAction()` to re-run the current agent
 
 ### Phase → Next Agent Mapping
 
@@ -90,9 +85,8 @@ You are re-invoked after EVERY agent completes (not just the first phase). When
 
 ```
 1. getStatus() → currentPhase: "specify", status: "in_progress"
-2. evaluateGate({ workflowId, targetPhase: "plan" }) → { passed: true }
-3. advancePhase({ workflowId, targetPhase: "plan" })
-4. setPendingAction({ workflowId, agent: "planner", prompt: "...", status: "awaiting_agent" })
+2. advancePhase({ workflowId, targetPhase: "plan" })
+3. setPendingAction({ workflowId, agent: "planner", prompt: "...", status: "awaiting_agent" })
 ```
 
 MUST NOT return without creating a pendingAction for the next phase. The main session relies on `getNextAction()` to know what to do next.
@@ -107,7 +101,6 @@ MUST NOT return without creating a pendingAction for the next phase. The main se
 
 ## What You DON'T Do
 
-- Evaluate gates (code does this)
 - Validate transitions (code does this)
 - Check artifacts (code does this)
 - Generate artifacts directly
@@ -127,26 +120,24 @@ Rationale: Direct file operations consume 2-5k tokens per file. Subagent dispatc
 
 User: "Create OAuth2 API"
 
-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. Waiting for specifier agent."
+1. Call getStatus() → currentPhase: "research", status: "in_progress"
+2. Call advancePhase({ workflowId, targetPhase: "specify" })
+3. Call setPendingAction({ workflowId, agent: "specifier", prompt: "Generate specification for OAuth2 API...", status: "awaiting_agent" })
+4. Report: "Specification phase started. Specifier agent dispatched."
 
 ## Rules
 
 ### MUST (Mandatory)
-1. MUST start with getContext() before making decisions
-2. MUST use availableActions to determine valid actions
-3. MUST ask user for approval when pendingApproval is true
-4. MUST trust the deterministic layer (gates, transitions)
-5. MUST report progress after each action
+1. MUST start with getStatus() before making decisions
+2. MUST ask user for approval when pendingApproval is true
+3. MUST trust the deterministic layer (gates, transitions)
+4. MUST report progress after each action
 
 ### MUST NOT (Forbidden)
 1. MUST NOT hardcode phase transitions
-2. MUST NOT evaluate gates (code does this)
-3. MUST NOT generate artifacts directly
-4. MUST NOT execute multiple phases in one invocation
-5. MUST NOT bypass the approval flow
+2. MUST NOT generate artifacts directly
+3. MUST NOT execute multiple phases in one invocation
+4. MUST NOT bypass the approval flow
 
 ### SHOULD (Recommended)
 1. SHOULD compose clear prompts for subagents
@@ -157,7 +148,7 @@ User: "Create OAuth2 API"
 1. MAY suggest alternative approaches to user
 2. MAY provide status summaries between phases
 
-## Specialized Agents (Invoked via executeAction)
+## Specialized Agents (Dispatched via setPendingAction)
 
 - `specifier`: Generates feature specifications
 - `planner`: Creates technical plans
@@ -210,7 +201,7 @@ The `stagingPath` field is no longer used — agents store artifacts directly vi
 
 ---
 
-**Version:** 2.1
+**Version:** 2.2
 **Architecture:** Deterministic (code-enforced gates)
 **Prompt Size:** ~100 lines
 **Compliance:** 100% (enforced by code)

package/hooks/approval-guardian.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+# approval-guardian.sh — TD-128 F-09 Hook
+# Trigger: PreToolUse on mcp__orchestrator-tools__approveAction and mcp__orchestrator-extended__completeWorkflow
+# Purpose: Block auto-approve and auto-complete when workflow is awaiting_approval.
+#          Requires explicit human confirmation before proceeding.
+#
+# Output: JSON with permissionDecision (deny/allow)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/orch-helpers.sh"
+
+STDIN_DATA=$(orch_read_stdin)
+TOOL_NAME=$(orch_json_field "$STDIN_DATA" "tool_name")
+orch_log "APPROVAL-GUARDIAN: PreToolUse $TOOL_NAME triggered"
+
+# Extract workflow ID from tool_input
+WORKFLOW_ID=$(orch_json_field "$STDIN_DATA" "tool_input.workflowId")
+[ -z "$WORKFLOW_ID" ] && WORKFLOW_ID=$(orch_json_field "$STDIN_DATA" "workflowId")
+
+if [ -z "$WORKFLOW_ID" ]; then
+  # No workflow ID — allow (fail-open for non-workflow calls)
+  orch_log "APPROVAL-GUARDIAN: ALLOW (no workflowId)"
+  echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","additionalContext":"No workflowId found, allowing."}}'
+  exit 0
+fi
+
+# Get auth token
+TOKEN=$(orch_get_token 2>/dev/null) || TOKEN=""
+if [ -z "$TOKEN" ]; then
+  # Can't check status — fail-open (auth issues shouldn't block workflow completion)
+  orch_log "APPROVAL-GUARDIAN: ALLOW (auth failed, fail-open)"
+  echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","additionalContext":"Auth failed, allowing."}}'
+  exit 0
+fi
+
+# Get workflow status
+STATUS=$(curl -sf --max-time 5 "${API_URL}/api/v1/workflows/${WORKFLOW_ID}" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "X-Project-ID: $PROJECT_ID" 2>/dev/null) || STATUS=""
+
+if [ -z "$STATUS" ]; then
+  orch_log "APPROVAL-GUARDIAN: ALLOW (could not fetch workflow status)"
+  echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","additionalContext":"Could not fetch workflow status, allowing."}}'
+  exit 0
+fi
+
+WORKFLOW_STATUS=$(orch_json_field "$STATUS" "status")
+orch_log "APPROVAL-GUARDIAN: workflow=$WORKFLOW_ID status=$WORKFLOW_STATUS tool=$TOOL_NAME"
+
+# Block approveAction AND completeWorkflow when awaiting_approval
+if [ "$WORKFLOW_STATUS" = "awaiting_approval" ]; then
+  orch_log "APPROVAL-GUARDIAN: DENY (workflow awaiting_approval — human confirmation required for $TOOL_NAME)"
+  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"Approval Guardian: Workflow is awaiting human approval. You MUST ask the user for explicit confirmation before calling ${TOOL_NAME}.\",\"additionalContext\":\"Present the workflow summary to the user and ask: 'Do you approve advancing to IMPLEMENT?' Wait for their response. Do NOT auto-approve or auto-complete.\"}}"
+  exit 0
+fi
+
+# All other statuses: ALLOW
+orch_log "APPROVAL-GUARDIAN: ALLOW ($TOOL_NAME, status=$WORKFLOW_STATUS)"
+echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"additionalContext\":\"${TOOL_NAME} allowed (status=${WORKFLOW_STATUS}).\"}}"
+exit 0

package/manifest.json

@@ -1,8 +1,8 @@
 {
   "schema": "orchestrator-definitions/v1",
   "namespace": "orchestrator",
-  "version": "3.16.0",
-  "generatedAt": "2026-03-19T22:13:52.697Z",
+  "version": "3.17.1",
+  "generatedAt": "2026-03-20T19:11:53.058Z",
   "definitions": {
     "agents": [
       {
@@ -65,7 +65,7 @@
         "slug": "orchestrator",
         "file": "agents/orchestrator.md",
         "version": "1.0.0",
-        "checksum": "sha256:0e8c6d3a5516dac268cb334b8b9a23d6a996936caf784e4faaead6160b18c34c",
+        "checksum": "sha256:b7a5cd4da196355be0a406dbc61d524462eb7fdcfb764fbbc88c54f067252192",
         "supersedes": null,
         "metadata": {}
       },
@@ -233,6 +233,14 @@
       }
     ],
     "hooks": [
+      {
+        "slug": "approval-guardian",
+        "file": "hooks/approval-guardian.sh",
+        "version": "1.0.0",
+        "checksum": "sha256:5d9c1080926610cd3dd1babc3815ec82c93f46177758a5a921f65a717196bd83",
+        "supersedes": null,
+        "metadata": {}
+      },
       {
         "slug": "dangling-workflow-guard",
         "file": "hooks/dangling-workflow-guard.sh",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orchestrator-claude/definitions",
-  "version": "3.16.0",
+  "version": "3.17.1",
   "description": "Built-in definitions (agents, skills, hooks, workflows, KB seeds) for the Orchestrator ecosystem",
   "type": "module",
   "main": "dist/index.js",