@nlaprell/shipit 1.0.0

package/scripts/usage.sh

@@ -0,0 +1,58 @@
+#!/bin/bash
+
+# Record token-usage (or cost) for a phase/intent.
+# Values are estimates unless source is "api" (e.g. from provider response).
+# Usage: usage.sh <intent_id> <phase> <tokens_in> <tokens_out> [estimated_cost_usd] [source]
+# Example: ./scripts/usage.sh F-001 analysis 1500 800
+# Example: ./scripts/usage.sh F-001 plan 2000 1200 0.02 cursor_estimate
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+cd "$REPO_ROOT"
+
+# shellcheck source=scripts/lib/common.sh
+. "$SCRIPT_DIR/lib/common.sh"
+
+require_cmd jq
+
+USAGE_FILE="_system/artifacts/usage.json"
+
+if [ $# -lt 4 ]; then
+    echo "Usage: $0 <intent_id> <phase> <tokens_in> <tokens_out> [estimated_cost_usd] [source]" >&2
+    echo "  source: cursor_estimate (default) | api" >&2
+    exit 1
+fi
+
+INTENT_ID="$1"
+PHASE="$2"
+TOKENS_IN="$3"
+TOKENS_OUT="$4"
+COST="${5:-null}"
+SOURCE="${6:-cursor_estimate}"
+
+if ! [[ "$TOKENS_IN" =~ ^[0-9]+$ ]] || ! [[ "$TOKENS_OUT" =~ ^[0-9]+$ ]]; then
+    error_exit "tokens_in and tokens_out must be non-negative integers" 1
+fi
+
+mkdir -p _system/artifacts
+
+if [ ! -f "$USAGE_FILE" ]; then
+    echo '{"entries":[]}' > "$USAGE_FILE"
+fi
+
+TIMESTAMP_ISO="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+NEW_ENTRY=$(jq -n \
+    --arg intent_id "$INTENT_ID" \
+    --arg phase "$PHASE" \
+    --argjson tokens_in "$TOKENS_IN" \
+    --argjson tokens_out "$TOKENS_OUT" \
+    --argjson cost "$COST" \
+    --arg ts "$TIMESTAMP_ISO" \
+    --arg source "$SOURCE" \
+    '{ intent_id: $intent_id, phase: $phase, tokens_in: $tokens_in, tokens_out: $tokens_out, estimated_cost_usd: $cost, timestamp_iso: $ts, source: $source }')
+
+jq --argjson entry "$NEW_ENTRY" '.entries += [$entry]' "$USAGE_FILE" > "$USAGE_FILE.nw" && mv "$USAGE_FILE.nw" "$USAGE_FILE"
+
+echo "Recorded: $INTENT_ID $PHASE (in=$TOKENS_IN out=$TOKENS_OUT) source=$SOURCE"

package/scripts/validate-cursor.sh

@@ -0,0 +1,151 @@
+#!/bin/bash
+
+# Cursor Integration Validation Script
+# Checks if Cursor recognizes .mdc files and slash commands
+
+set -euo pipefail
+
+error_exit() {
+    echo "ERROR: $1" >&2
+    exit "${2:-1}"
+}
+
+# Colors
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+RED='\033[0;31m'
+NC='\033[0m'
+
+echo -e "${BLUE}Validating Cursor Integration...${NC}"
+echo ""
+
+PASSED=0
+FAILED=0
+WARNINGS=0
+
+# Check 1: .mdc files exist
+echo -e "${YELLOW}[1/6] Checking .mdc rule files...${NC}"
+MDC_COUNT=$(find .cursor/rules -name "*.mdc" 2>/dev/null | wc -l | tr -d ' ')
+if [ "$MDC_COUNT" -gt 0 ]; then
+    echo -e "${GREEN}✓ Found $MDC_COUNT .mdc rule files${NC}"
+    PASSED=$((PASSED + 1))
+    find .cursor/rules -name "*.mdc" | sed 's/^/  - /'
+else
+    echo -e "${RED}✗ No .mdc rule files found${NC}"
+    FAILED=$((FAILED + 1))
+fi
+echo ""
+
+# Check 2: Slash commands exist
+echo -e "${YELLOW}[2/6] Checking slash command files...${NC}"
+CMD_COUNT=$(find .cursor/commands -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
+if [ "$CMD_COUNT" -gt 0 ]; then
+    echo -e "${GREEN}✓ Found $CMD_COUNT slash command files${NC}"
+    PASSED=$((PASSED + 1))
+    find .cursor/commands -name "*.md" | sed 's/^/  - /'
+else
+    echo -e "${RED}✗ No slash command files found${NC}"
+    FAILED=$((FAILED + 1))
+fi
+echo ""
+
+# Check 3: Required commands exist
+echo -e "${YELLOW}[3/6] Checking required commands...${NC}"
+REQUIRED_CMDS=("ship.md" "new_intent.md" "init_project.md" "scope_project.md" "deploy.md" "verify.md" "kill.md" "drift_check.md")
+MISSING=0
+for cmd in "${REQUIRED_CMDS[@]}"; do
+    if [ -f ".cursor/commands/$cmd" ]; then
+        echo -e "  ${GREEN}✓${NC} $cmd"
+    else
+        echo -e "  ${RED}✗${NC} $cmd (missing)"
+        MISSING=$((MISSING + 1))
+    fi
+done
+if [ $MISSING -eq 0 ]; then
+    PASSED=$((PASSED + 1))
+else
+    FAILED=$((FAILED + 1))
+fi
+echo ""
+
+# Check 4: Required rules exist
+echo -e "${YELLOW}[4/6] Checking required rule files...${NC}"
+REQUIRED_RULES=("steward.mdc" "pm.mdc" "architect.mdc" "implementer.mdc" "qa.mdc" "security.mdc" "docs.mdc")
+MISSING=0
+for rule in "${REQUIRED_RULES[@]}"; do
+    if [ -f ".cursor/rules/$rule" ]; then
+        echo -e "  ${GREEN}✓${NC} $rule"
+    else
+        echo -e "  ${RED}✗${NC} $rule (missing)"
+        MISSING=$((MISSING + 1))
+    fi
+done
+if [ $MISSING -eq 0 ]; then
+    PASSED=$((PASSED + 1))
+else
+    FAILED=$((FAILED + 1))
+fi
+echo ""
+
+# Check 5: Scripts are executable
+echo -e "${YELLOW}[5/6] Checking script executability...${NC}"
+SCRIPTS=("init-project.sh" "scope-project.sh" "deploy.sh" "workflow-orchestrator.sh")
+MISSING=0
+for script in "${SCRIPTS[@]}"; do
+    if [ -f "scripts/$script" ] && [ -x "scripts/$script" ]; then
+        echo -e "  ${GREEN}✓${NC} $script"
+    else
+        echo -e "  ${YELLOW}⚠${NC} $script (not executable or missing)"
+        MISSING=$((MISSING + 1))
+        WARNINGS=$((WARNINGS + 1))
+    fi
+done
+if [ $MISSING -eq 0 ]; then
+    PASSED=$((PASSED + 1))
+else
+    WARNINGS=$((WARNINGS + 1))
+fi
+echo ""
+
+# Check 6: Project structure
+echo -e "${YELLOW}[6/6] Checking project structure...${NC}"
+REQUIRED_DIRS=("intent" "workflow-state" "architecture" "scripts" ".cursor/rules" ".cursor/commands")
+MISSING=0
+for dir in "${REQUIRED_DIRS[@]}"; do
+    if [ -d "$dir" ]; then
+        echo -e "  ${GREEN}✓${NC} $dir/"
+    else
+        echo -e "  ${RED}✗${NC} $dir/ (missing)"
+        MISSING=$((MISSING + 1))
+    fi
+done
+if [ $MISSING -eq 0 ]; then
+    PASSED=$((PASSED + 1))
+else
+    FAILED=$((FAILED + 1))
+fi
+echo ""
+
+# Summary
+echo -e "${BLUE}════════════════════════════════════════${NC}"
+echo -e "${BLUE}Validation Summary${NC}"
+echo -e "${BLUE}════════════════════════════════════════${NC}"
+echo -e "${GREEN}Passed: $PASSED${NC}"
+echo -e "${RED}Failed: $FAILED${NC}"
+echo -e "${YELLOW}Warnings: $WARNINGS${NC}"
+echo ""
+
+if [ $FAILED -eq 0 ]; then
+    echo -e "${GREEN}✓ All checks passed!${NC}"
+    echo ""
+    echo -e "${YELLOW}Manual Validation Required:${NC}"
+    echo "1. Open Cursor and type '/' - verify commands appear"
+    echo "2. Try /ship F-001 - verify command works"
+    echo "3. Check if .mdc rules are recognized (Cursor may show them in settings)"
+    echo ""
+    exit 0
+else
+    echo -e "${RED}✗ Some checks failed. Fix issues above.${NC}"
+    exit 1
+fi

package/scripts/validate-project.sh

@@ -0,0 +1,71 @@
+#!/bin/bash
+
+# Validate project.json against schema
+
+set -euo pipefail
+
+error_exit() {
+    echo "ERROR: $1" >&2
+    exit "${2:-1}"
+}
+
+PROJECT_FILE="${1:-project.json}"
+
+if [ ! -f "$PROJECT_FILE" ]; then
+    error_exit "Project file not found: $PROJECT_FILE" 1
+fi
+
+# Basic validation (check required fields)
+echo "Validating $PROJECT_FILE..."
+
+# Check if jq is available
+if ! command -v jq >/dev/null 2>&1; then
+    echo "WARNING: jq not found, performing basic validation only"
+    
+    # Basic checks
+    if ! grep -q '"name"' "$PROJECT_FILE"; then
+        error_exit "Missing required field: name" 1
+    fi
+    
+    if ! grep -q '"version"' "$PROJECT_FILE"; then
+        error_exit "Missing required field: version" 1
+    fi
+    
+    if ! grep -q '"techStack"' "$PROJECT_FILE"; then
+        error_exit "Missing required field: techStack" 1
+    fi
+    
+    echo "✓ Basic validation passed"
+    exit 0
+fi
+
+# Advanced validation with jq
+REQUIRED_FIELDS=("name" "version" "techStack" "created")
+
+for field in "${REQUIRED_FIELDS[@]}"; do
+    if ! jq -e ".$field" "$PROJECT_FILE" >/dev/null 2>&1; then
+        error_exit "Missing required field: $field" 1
+    fi
+done
+
+# Validate techStack enum
+TECH_STACK=$(jq -r '.techStack' "$PROJECT_FILE")
+if [[ ! "$TECH_STACK" =~ ^(typescript-nodejs|python|other)$ ]]; then
+    error_exit "Invalid techStack: $TECH_STACK (must be typescript-nodejs, python, or other)" 1
+fi
+
+# Validate version format
+VERSION=$(jq -r '.version' "$PROJECT_FILE")
+if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+    error_exit "Invalid version format: $VERSION (must be semantic version like 0.1.0)" 1
+fi
+
+# Validate settings if present
+if jq -e '.settings' "$PROJECT_FILE" >/dev/null 2>&1; then
+    CONFIDENCE=$(jq -r '.settings.confidenceThreshold // 0.7' "$PROJECT_FILE")
+    if (( $(echo "$CONFIDENCE < 0 || $CONFIDENCE > 1" | bc -l) )); then
+        error_exit "Invalid confidenceThreshold: $CONFIDENCE (must be 0.0-1.0)" 1
+    fi
+fi
+
+echo "✓ Validation passed: $PROJECT_FILE"

package/scripts/validate-vscode.sh

@@ -0,0 +1,146 @@
+#!/bin/bash
+
+# VS Code + ShipIt Extension Validation Script
+# Checks .cursor layout and project structure (same as Cursor). Run from repo root in VS Code.
+
+set -euo pipefail
+
+# Colors
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+RED='\033[0;31m'
+NC='\033[0m'
+
+echo -e "${BLUE}Validating VS Code / ShipIt integration...${NC}"
+echo ""
+
+PASSED=0
+FAILED=0
+WARNINGS=0
+
+# Check 1: .mdc files exist
+echo -e "${YELLOW}[1/6] Checking .mdc rule files...${NC}"
+MDC_COUNT=$(find .cursor/rules -name "*.mdc" 2>/dev/null | wc -l | tr -d ' ')
+if [ "$MDC_COUNT" -gt 0 ]; then
+    echo -e "${GREEN}✓ Found $MDC_COUNT .mdc rule files${NC}"
+    PASSED=$((PASSED + 1))
+    find .cursor/rules -name "*.mdc" | sed 's/^/  - /'
+else
+    echo -e "${RED}✗ No .mdc rule files found${NC}"
+    FAILED=$((FAILED + 1))
+fi
+echo ""
+
+# Check 2: Slash command files exist (extension reads these)
+echo -e "${YELLOW}[2/6] Checking command files...${NC}"
+CMD_COUNT=$(find .cursor/commands -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
+if [ "$CMD_COUNT" -gt 0 ]; then
+    echo -e "${GREEN}✓ Found $CMD_COUNT command files${NC}"
+    PASSED=$((PASSED + 1))
+    find .cursor/commands -name "*.md" | sed 's/^/  - /'
+else
+    echo -e "${RED}✗ No command files found${NC}"
+    FAILED=$((FAILED + 1))
+fi
+echo ""
+
+# Check 3: Required commands exist
+echo -e "${YELLOW}[3/6] Checking required commands...${NC}"
+REQUIRED_CMDS=("ship.md" "new_intent.md" "init_project.md" "scope_project.md" "deploy.md" "verify.md" "kill.md" "drift_check.md")
+MISSING=0
+for cmd in "${REQUIRED_CMDS[@]}"; do
+    if [ -f ".cursor/commands/$cmd" ]; then
+        echo -e "  ${GREEN}✓${NC} $cmd"
+    else
+        echo -e "  ${RED}✗${NC} $cmd (missing)"
+        MISSING=$((MISSING + 1))
+    fi
+done
+if [ $MISSING -eq 0 ]; then
+    PASSED=$((PASSED + 1))
+else
+    FAILED=$((FAILED + 1))
+fi
+echo ""
+
+# Check 4: Required rules exist
+echo -e "${YELLOW}[4/6] Checking required rule files...${NC}"
+REQUIRED_RULES=("steward.mdc" "pm.mdc" "architect.mdc" "implementer.mdc" "qa.mdc" "security.mdc" "docs.mdc")
+MISSING=0
+for rule in "${REQUIRED_RULES[@]}"; do
+    if [ -f ".cursor/rules/$rule" ]; then
+        echo -e "  ${GREEN}✓${NC} $rule"
+    else
+        echo -e "  ${RED}✗${NC} $rule (missing)"
+        MISSING=$((MISSING + 1))
+    fi
+done
+if [ $MISSING -eq 0 ]; then
+    PASSED=$((PASSED + 1))
+else
+    FAILED=$((FAILED + 1))
+fi
+echo ""
+
+# Check 5: Scripts are executable
+echo -e "${YELLOW}[5/6] Checking script executability...${NC}"
+SCRIPTS=("init-project.sh" "scope-project.sh" "deploy.sh" "workflow-orchestrator.sh")
+MISSING=0
+for script in "${SCRIPTS[@]}"; do
+    if [ -f "scripts/$script" ] && [ -x "scripts/$script" ]; then
+        echo -e "  ${GREEN}✓${NC} $script"
+    else
+        echo -e "  ${YELLOW}⚠${NC} $script (not executable or missing)"
+        MISSING=$((MISSING + 1))
+        WARNINGS=$((WARNINGS + 1))
+    fi
+done
+if [ $MISSING -eq 0 ]; then
+    PASSED=$((PASSED + 1))
+else
+    WARNINGS=$((WARNINGS + 1))
+fi
+echo ""
+
+# Check 6: Project structure (work/ layout for ShipIt)
+echo -e "${YELLOW}[6/6] Checking project structure...${NC}"
+REQUIRED_DIRS=("work/intent" "work/workflow-state" "_system/architecture" "scripts" ".cursor/rules" ".cursor/commands")
+MISSING=0
+for dir in "${REQUIRED_DIRS[@]}"; do
+    if [ -d "$dir" ]; then
+        echo -e "  ${GREEN}✓${NC} $dir/"
+    else
+        echo -e "  ${RED}✗${NC} $dir/ (missing)"
+        MISSING=$((MISSING + 1))
+    fi
+done
+if [ $MISSING -eq 0 ]; then
+    PASSED=$((PASSED + 1))
+else
+    FAILED=$((FAILED + 1))
+fi
+echo ""
+
+# Summary
+echo -e "${BLUE}════════════════════════════════════════${NC}"
+echo -e "${BLUE}Validation Summary${NC}"
+echo -e "${BLUE}════════════════════════════════════════${NC}"
+echo -e "${GREEN}Passed: $PASSED${NC}"
+echo -e "${RED}Failed: $FAILED${NC}"
+echo -e "${YELLOW}Warnings: $WARNINGS${NC}"
+echo ""
+
+if [ $FAILED -eq 0 ]; then
+    echo -e "${GREEN}✓ All checks passed!${NC}"
+    echo ""
+    echo -e "${YELLOW}Manual validation (in VS Code):${NC}"
+    echo "1. Install the ShipIt extension (from vscode-extension/ or VSIX)."
+    echo "2. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and run e.g. \"ShipIt: Ship\"."
+    echo "3. Enter intent id when prompted; Copilot Chat should open with the same context as Cursor /ship."
+    echo ""
+    exit 0
+else
+    echo -e "${RED}✗ Some checks failed. Fix issues above.${NC}"
+    exit 1
+fi

package/scripts/verify.sh

@@ -0,0 +1,153 @@
+#!/bin/bash
+
+# Verification Script
+# Runs verification checks and writes 04_verification.md (flat or per-intent per workflow-state-layout.md).
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+error_exit() {
+    echo "ERROR: $1" >&2
+    exit "${2:-1}"
+}
+# shellcheck source=lib/workflow_state.sh
+[ -f "$SCRIPT_DIR/lib/workflow_state.sh" ] && source "$SCRIPT_DIR/lib/workflow_state.sh"
+
+INTENT_ID="${1:-}"
+if [ -z "$INTENT_ID" ]; then
+    error_exit "Usage: ./scripts/verify.sh <intent-id>" 1
+fi
+
+WORKFLOW_DIR="$(get_workflow_state_dir "$INTENT_ID")"
+[ -n "$WORKFLOW_DIR" ] || error_exit "No workflow state dir for intent $INTENT_ID. Run /ship $INTENT_ID first." 1
+mkdir -p "$WORKFLOW_DIR"
+
+FAILED=0
+TEST_STATUS="not run"
+MUTATE_STATUS="not run"
+AUDIT_STATUS="not run"
+
+if command -v pnpm >/dev/null 2>&1; then
+    if pnpm test; then
+        TEST_STATUS="pass"
+    else
+        TEST_STATUS="fail"
+        FAILED=1
+    fi
+
+    if pnpm -s run test:mutate >/dev/null 2>&1; then
+        if pnpm test:mutate; then
+            MUTATE_STATUS="pass"
+        else
+            MUTATE_STATUS="fail"
+            FAILED=1
+        fi
+    else
+        MUTATE_STATUS="skipped (test:mutate not defined)"
+    fi
+
+    # Always run audit (no script gate). Use audit-level=high per verification requirements.
+    if [ -f "scripts/audit-check.sh" ]; then
+        if ./scripts/audit-check.sh high; then
+            AUDIT_STATUS="pass"
+        else
+            AUDIT_STATUS="fail (unlisted or expired advisories)"
+            FAILED=1
+        fi
+    else
+        if pnpm audit --audit-level=high; then
+            AUDIT_STATUS="pass"
+        else
+            AUDIT_STATUS="fail (high+ vulnerabilities)"
+            FAILED=1
+        fi
+    fi
+else
+    error_exit "pnpm is required to run verification checks" 1
+fi
+
+cat > "$WORKFLOW_DIR/04_verification.md" << EOF
+# Verification: $INTENT_ID
+
+**Generated:** $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+**Intent:** $INTENT_ID
+
+## Test Results
+
+- pnpm test: $TEST_STATUS
+- pnpm test:mutate: $MUTATE_STATUS
+
+## Security Review
+
+- pnpm audit --audit-level=high: $AUDIT_STATUS
+
+## Verification Status
+
+$(if [ "$FAILED" -eq 0 ]; then echo "- [x] All checks pass"; else echo "- [ ] All checks pass"; fi)
+- [ ] Ready for release
+EOF
+
+# Append to confidence-calibration.json if it exists
+mkdir -p _system/artifacts
+CALIBRATION_FILE="_system/artifacts/confidence-calibration.json"
+if [ -f "$CALIBRATION_FILE" ] && command -v jq >/dev/null 2>&1; then
+    # Determine outcome
+    if [ "$FAILED" -eq 0 ]; then
+        OUTCOME="success"
+    else
+        OUTCOME="failure"
+    fi
+    
+    # Generate next decision ID
+    LAST_ID=$(jq -r '.decisions[-1].id // "D-000"' "$CALIBRATION_FILE" 2>/dev/null || echo "D-000")
+    LAST_NUM=$(echo "$LAST_ID" | sed 's/D-//' | awk '{print int($1)}')
+    NEXT_NUM=$((LAST_NUM + 1))
+    NEXT_ID=$(printf "D-%03d" "$NEXT_NUM")
+    
+    # Try to read stated_confidence from analysis file if available
+    STATED_CONFIDENCE="null"
+    ANALYSIS_FILE="$WORKFLOW_DIR/01_analysis.md"
+    if [ -f "$ANALYSIS_FILE" ]; then
+        # Try to extract confidence from analysis file (look for "Requirements clarity: X.XX" pattern)
+        CONF_LINE=$(grep -i "requirements clarity:" "$ANALYSIS_FILE" 2>/dev/null | head -1)
+        if [ -n "$CONF_LINE" ]; then
+            EXTRACTED_CONF=$(echo "$CONF_LINE" | grep -oE '[0-9]+\.[0-9]+' | head -1)
+            if [ -n "$EXTRACTED_CONF" ]; then
+                STATED_CONFIDENCE="$EXTRACTED_CONF"
+            fi
+        fi
+    fi
+    
+    # Build notes
+    NOTES="Intent: $INTENT_ID. Tests: $TEST_STATUS, Mutation: $MUTATE_STATUS, Audit: $AUDIT_STATUS"
+    
+    # Append new decision
+    if [ "$STATED_CONFIDENCE" != "null" ]; then
+        # Use --argjson when we have a numeric value
+        jq --arg id "$NEXT_ID" \
+           --argjson confidence "$STATED_CONFIDENCE" \
+           --arg outcome "$OUTCOME" \
+           --arg notes "$NOTES" \
+           '.decisions += [{
+             "id": $id,
+             "stated_confidence": $confidence,
+             "actual_outcome": $outcome,
+             "notes": $notes
+           }]' "$CALIBRATION_FILE" > "${CALIBRATION_FILE}.tmp" && \
+        mv "${CALIBRATION_FILE}.tmp" "$CALIBRATION_FILE" || true
+    else
+        # Use null explicitly when confidence is not available
+        jq --arg id "$NEXT_ID" \
+           --arg outcome "$OUTCOME" \
+           --arg notes "$NOTES" \
+           '.decisions += [{
+             "id": $id,
+             "stated_confidence": null,
+             "actual_outcome": $outcome,
+             "notes": $notes
+           }]' "$CALIBRATION_FILE" > "${CALIBRATION_FILE}.tmp" && \
+        mv "${CALIBRATION_FILE}.tmp" "$CALIBRATION_FILE" || true
+    fi
+fi
+
+exit "$FAILED"

package/scripts/workflow-orchestrator.sh

@@ -0,0 +1,97 @@
+#!/bin/bash
+
+# Workflow Orchestrator Script
+# Automates workflow state file generation from phase spec and templates.
+# Phase list: scripts/workflow-templates/phases.yml. Add a phase there and a .tpl file.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ORCHESTRATOR_DIR="$SCRIPT_DIR"
+TEMPLATES_DIR="$SCRIPT_DIR/workflow-templates"
+# shellcheck source=lib/intent.sh
+[ -f "$SCRIPT_DIR/lib/intent.sh" ] && source "$SCRIPT_DIR/lib/intent.sh"
+# shellcheck source=lib/workflow_state.sh (use ORCHESTRATOR_DIR so intent.sh doesn't overwrite SCRIPT_DIR)
+[ -f "$ORCHESTRATOR_DIR/lib/workflow_state.sh" ] && source "$ORCHESTRATOR_DIR/lib/workflow_state.sh"
+
+INTENT_ID="${1:-}"
+if [ -z "$INTENT_ID" ]; then
+    error_exit "Usage: $0 <intent-id>" 1
+fi
+
+INTENT_FILE="$(require_intent_file "$INTENT_ID")"
+
+# Resolve workflow dir: flat for single intent, per-intent for multiple (see workflow-state-layout.md).
+WORKFLOW_DIR="$(ensure_workflow_state_dir "$INTENT_ID")"
+[ -n "$WORKFLOW_DIR" ] || error_exit "Failed to resolve workflow state dir for $INTENT_ID" 1
+mkdir -p "$WORKFLOW_DIR"
+
+# Source progress library
+if [ -f "$SCRIPT_DIR/lib/progress.sh" ]; then
+    source "$SCRIPT_DIR/lib/progress.sh"
+fi
+
+DATE_UTC="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+PHASE_COUNT=$(node -e "
+const yaml = require('yaml');
+const fs = require('fs');
+const spec = yaml.parse(fs.readFileSync('$TEMPLATES_DIR/phases.yml', 'utf8'));
+console.log(spec.phases.length);
+")
+
+echo -e "${BLUE}Orchestrating workflow for $INTENT_ID...${NC}"
+echo -e "${BLUE}Using intent file: ${INTENT_FILE}${NC}"
+echo ""
+
+phase_num=0
+while IFS='|' read -r output_file template_file phase_name; do
+    [ -z "$output_file" ] && continue
+    phase_num=$((phase_num + 1))
+    if command -v show_phase_progress >/dev/null 2>&1; then
+        show_phase_progress "$phase_num" "$PHASE_COUNT" "$phase_name" "running"
+    else
+        echo -e "${YELLOW}[Phase $phase_num/$PHASE_COUNT] $phase_name... ⏳${NC}"
+    fi
+
+    template_path="$TEMPLATES_DIR/$template_file"
+    if [ ! -f "$template_path" ]; then
+        error_exit "Template not found: $template_path" 1
+    fi
+
+    # active.md lives at top level only; update it for this intent (multi-intent list).
+    if [ "$output_file" = "active.md" ]; then
+        append_or_set_active_intent "$INTENT_ID" "$phase_name" || true
+        if command -v show_phase_progress >/dev/null 2>&1; then
+            show_phase_progress "$phase_num" "$PHASE_COUNT" "$phase_name" "complete"
+        else
+            echo -e "${GREEN}✓ Updated $WS_BASE/active.md${NC}"
+        fi
+    else
+        sed -e "s/{{INTENT_ID}}/$INTENT_ID/g" -e "s/{{DATE_UTC}}/$DATE_UTC/g" "$template_path" > "$WORKFLOW_DIR/$output_file" \
+            || error_exit "Failed to create $WORKFLOW_DIR/$output_file" 1
+
+        if command -v show_phase_progress >/dev/null 2>&1; then
+            show_phase_progress "$phase_num" "$PHASE_COUNT" "$phase_name" "complete"
+        else
+            echo -e "${GREEN}✓ Created $WORKFLOW_DIR/$output_file${NC}"
+        fi
+    fi
+done < <(node -e "
+const yaml = require('yaml');
+const fs = require('fs');
+const spec = yaml.parse(fs.readFileSync('$TEMPLATES_DIR/phases.yml', 'utf8'));
+spec.phases.forEach(p => console.log(p.output + '|' + p.template + '|' + (p.name || '')));
+")
+
+echo ""
+echo -e "${GREEN}════════════════════════════════════════${NC}"
+echo -e "${GREEN}✓ Workflow state files created${NC}"
+echo -e "${GREEN}════════════════════════════════════════${NC}"
+echo ""
+echo -e "${YELLOW}Next steps:${NC}"
+echo "1. Fill in $WORKFLOW_DIR/01_analysis.md (PM role)"
+echo "2. Fill in $WORKFLOW_DIR/02_plan.md (Architect role)"
+echo "3. Fill in $WORKFLOW_DIR/03_implementation.md (Implementer role)"
+echo "4. Fill in $WORKFLOW_DIR/04_verification.md (QA + Security roles)"
+echo "5. Fill in $WORKFLOW_DIR/05_release_notes.md (Docs + Steward roles)"
+echo ""