@nlaprell/shipit 1.0.0

package/scripts/generate-system-state.sh

@@ -0,0 +1,95 @@
+#!/bin/bash
+
+# Generate SYSTEM_STATE.md Script
+# Creates a global summary for agents to maintain understanding
+
+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'
+NC='\033[0m'
+
+mkdir -p _system/artifacts
+STATE_FILE="_system/artifacts/SYSTEM_STATE.md"
+
+echo -e "${BLUE}Generating SYSTEM_STATE.md...${NC}"
+
+# Check prerequisites
+if [ -f "project.json" ]; then
+    PROJECT_NAME=$(jq -r '.name' project.json 2>/dev/null || echo "project")
+else
+    PROJECT_NAME=$(jq -r '.name' package.json 2>/dev/null || echo "shipit")
+fi
+
+# Collect state information
+INTENT_TOTAL=$(find intent -name "*.md" ! -name "_TEMPLATE.md" 2>/dev/null | wc -l | tr -d ' ')
+INTENT_ACTIVE=$(find intent -name "*.md" ! -name "_TEMPLATE.md" -print0 2>/dev/null | xargs -0 grep -l "Status.*active" 2>/dev/null | wc -l | tr -d ' ' || echo "0")
+INTENT_PLANNED=$(find intent -name "*.md" ! -name "_TEMPLATE.md" -print0 2>/dev/null | xargs -0 grep -l "Status.*planned" 2>/dev/null | wc -l | tr -d ' ' || echo "0")
+INTENT_SHIPPED=$(find intent -name "*.md" ! -name "_TEMPLATE.md" -print0 2>/dev/null | xargs -0 grep -l "Status.*shipped" 2>/dev/null | wc -l | tr -d ' ' || echo "0")
+
+# Get active intent
+ACTIVE_INTENT=$(grep -h "Intent ID:" work/workflow-state/active.md 2>/dev/null | grep -o "F-[0-9]*\|B-[0-9]*\|T-[0-9]*" | head -1 || echo "none")
+
+# Get recent intents
+RECENT_INTENTS=$(find intent -name "*.md" ! -name "_TEMPLATE.md" -type f -exec basename {} .md \; 2>/dev/null | head -10 | tr '\n' ',' | sed 's/,$//' || echo "none")
+
+# Generate system state
+cat > "$STATE_FILE" << EOF || error_exit "Failed to generate SYSTEM_STATE.md"
+# System State
+
+**Generated:** $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+**Project:** $PROJECT_NAME
+
+## Global Summary
+
+This file provides a global view of the system state for agents to maintain coherence.
+
+## Intent Status
+
+- **Total:** $INTENT_TOTAL
+- **Active:** $INTENT_ACTIVE
+- **Planned:** $INTENT_PLANNED
+- **Shipped:** $INTENT_SHIPPED
+
+## Current Work
+
+- **Active Intent:** $ACTIVE_INTENT
+- **Recent Intents:** $RECENT_INTENTS
+
+## System Health
+
+- **Workflow State:** [Check work/workflow-state/active.md]
+- **Drift Status:** [Check _system/drift/metrics.md]
+- **Test Coverage:** [Run: pnpm test:coverage]
+
+## Key Decisions
+
+[Recent architectural decisions]
+
+## Blockers
+
+[Current blockers and dependencies]
+
+## Next Actions
+
+[Planned next actions]
+
+---
+
+*This file is auto-generated. Run \`pnpm generate-system-state\` to update.*
+*Agents should read this file first to understand global state.*
+EOF
+
+echo -e "${GREEN}✓ Generated $STATE_FILE${NC}"
+echo ""
+echo -e "${YELLOW}System State Summary:${NC}"
+echo "  Total Intents: $INTENT_TOTAL"
+echo "  Active Intent: $ACTIVE_INTENT"
+echo ""

package/scripts/gh/create-intent-from-issue.sh

@@ -0,0 +1,82 @@
+#!/bin/bash
+# Create a new intent from a GitHub issue (fetch title/body, create intent file, set GitHub issue field).
+# Usage: create-intent-from-issue.sh <issue-number>
+# Requires: gh. Creates work/intent/features/F-XXX.md by default.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+# shellcheck source=../lib/common.sh
+[ -f "$SCRIPT_DIR/../lib/common.sh" ] && source "$SCRIPT_DIR/../lib/common.sh"
+
+require_cmd gh jq
+
+ISSUE_NUM="${1:-}"
+[ -n "$ISSUE_NUM" ] || error_exit "Usage: create-intent-from-issue.sh <issue-number>" 1
+[[ "$ISSUE_NUM" =~ ^[0-9]+$ ]] || error_exit "Issue number must be numeric" 1
+
+cd "$ROOT_DIR" || error_exit "Failed to cd to repo root" 1
+
+# Fetch issue
+JSON=$(gh issue view "$ISSUE_NUM" --json title,body,number 2>/dev/null) || error_exit "Failed to fetch issue #$ISSUE_NUM (gh issue view)" 1
+TITLE=$(echo "$JSON" | jq -r '.title')
+BODY=$(echo "$JSON" | jq -r '.body // ""')
+
+# Next intent ID (feature F-XXX)
+INTENT_BASE="work/intent"
+INTENT_DIR="$INTENT_BASE/features"
+mkdir -p "$INTENT_DIR"
+LAST=0
+while IFS= read -r f; do
+  [ -e "$f" ] || continue
+  base=$(basename "$f")
+  if [[ "$base" =~ ^F-([0-9]+)\.md$ ]]; then
+    num="${BASH_REMATCH[1]}"
+    ((10#$num > LAST)) && LAST=$((10#$num))
+  fi
+done < <(find "$INTENT_BASE" -type f -name 'F-*.md' 2>/dev/null)
+NEXT=$((LAST + 1))
+INTENT_ID="F-$(printf "%03d" "$NEXT")"
+INTENT_FILE="$INTENT_DIR/$INTENT_ID.md"
+
+# Minimal intent content: title, status, motivation from issue, GitHub issue link
+MOTIVATION=$(echo "$BODY" | head -15 | grep -v '^$' | sed 's/^/- /')
+[ -z "$MOTIVATION" ] && MOTIVATION="- (From issue #$ISSUE_NUM)"
+
+cat > "$INTENT_FILE" << EOF
+# $INTENT_ID: $TITLE
+
+## Type
+
+feature
+
+## Status
+
+planned
+
+## Motivation
+
+$MOTIVATION
+
+## Release Target
+
+R1
+
+## Dependencies
+
+-
+
+## GitHub issue
+
+#$ISSUE_NUM
+
+## Do Not Repeat Check
+
+- [ ] Checked _system/do-not-repeat/abandoned-designs.md
+- [ ] Checked _system/do-not-repeat/failed-experiments.md
+EOF
+
+echo -e "${GREEN}Created $INTENT_FILE from issue #${ISSUE_NUM}${NC}"
+echo "Intent ID: $INTENT_ID"
+echo "Title: $TITLE"

package/scripts/gh/create-issue-from-intent.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+# Create a GitHub issue from an intent and write the issue number back to the intent file.
+# Usage: create-issue-from-intent.sh <intent-id>
+# Requires: gh (repo from gh repo view)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+# shellcheck source=../lib/intent.sh
+[ -f "$SCRIPT_DIR/../lib/intent.sh" ] && source "$SCRIPT_DIR/../lib/intent.sh"
+# shellcheck source=../lib/common.sh
+[ -f "$SCRIPT_DIR/../lib/common.sh" ] && source "$SCRIPT_DIR/../lib/common.sh"
+
+require_cmd gh
+
+INTENT_ID="${1:-}"
+[ -n "$INTENT_ID" ] || error_exit "Usage: create-issue-from-intent.sh <intent-id>" 1
+
+cd "$ROOT_DIR" || error_exit "Failed to cd to repo root" 1
+INTENT_FILE="$(require_intent_file "$INTENT_ID")"
+
+# Title: first line of intent (e.g. "F-001: Add feature")
+TITLE=$(head -1 "$INTENT_FILE" | sed 's/^# *//')
+BODY_FILE=$(mktemp)
+trap 'rm -f "$BODY_FILE"' EXIT
+cat "$INTENT_FILE" > "$BODY_FILE"
+
+echo -e "${BLUE}Creating GitHub issue: $TITLE${NC}"
+OUTPUT=$(gh issue create --title "$TITLE" --body-file "$BODY_FILE" 2>&1) || error_exit "gh issue create failed: $OUTPUT" 1
+ISSUE_NUM=$(echo "$OUTPUT" | sed -n 's|.*/issues/\([0-9]*\)|\1|p')
+[ -n "$ISSUE_NUM" ] || ISSUE_NUM=$(echo "$OUTPUT" | grep -oE '[0-9]+' | head -1)
+[ -n "$ISSUE_NUM" ] || error_exit "Could not parse issue number from: $OUTPUT" 1
+
+# Write #ISSUE_NUM into intent file (add or update ## GitHub issue section)
+if grep -q '^## GitHub issue' "$INTENT_FILE"; then
+  # Replace value in existing section, or insert #num if section has only placeholder text
+  awk -v num="$ISSUE_NUM" '
+    /^## GitHub issue$/ { in_sec=1; printed=0; print; next }
+    in_sec && /^#?[0-9]+$/ { if (!printed) { print "#" num; printed=1 }; next }
+    in_sec && /^## / { in_sec=0; printed=0 }
+    in_sec && NF>0 && !printed { print "#" num; printed=1 }
+    { print }
+  ' "$INTENT_FILE" > "$INTENT_FILE.nw" && mv "$INTENT_FILE.nw" "$INTENT_FILE"
+else
+  # Insert section before ## Do Not Repeat Check
+  awk -v num="$ISSUE_NUM" '
+    /^## Do Not Repeat Check/ {
+      print "## GitHub issue"
+      print ""
+      print "#" num
+      print ""
+    }
+    { print }
+  ' "$INTENT_FILE" > "$INTENT_FILE.nw" && mv "$INTENT_FILE.nw" "$INTENT_FILE"
+fi
+
+echo -e "${GREEN}Created issue #${ISSUE_NUM} and updated $INTENT_FILE${NC}"
+echo "$OUTPUT"

package/scripts/gh/create-pr.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# Create a GitHub PR from work/workflow-state/pr.md for the given intent.
+# Resolves pr.md per workflow-state-layout: work/workflow-state/<intent-id>/pr.md or work/workflow-state/pr.md.
+# Usage: create-pr.sh <intent-id>
+# Requires: gh. Run /pr first if pr.md is missing.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+# shellcheck source=../lib/intent.sh
+[ -f "$SCRIPT_DIR/../lib/intent.sh" ] && source "$SCRIPT_DIR/../lib/intent.sh"
+# shellcheck source=../lib/common.sh
+[ -f "$SCRIPT_DIR/../lib/common.sh" ] && source "$SCRIPT_DIR/../lib/common.sh"
+
+require_cmd gh
+
+INTENT_ID="${1:-}"
+[ -n "$INTENT_ID" ] || error_exit "Usage: create-pr.sh <intent-id>" 1
+
+cd "$ROOT_DIR" || error_exit "Failed to cd to repo root" 1
+require_intent_file "$INTENT_ID" >/dev/null
+
+# Resolve pr.md per workflow-state-layout.md
+PR_PER_INTENT="work/workflow-state/${INTENT_ID}/pr.md"
+PR_FLAT="work/workflow-state/pr.md"
+if [ -f "$PR_PER_INTENT" ]; then
+  PR_FILE="$PR_PER_INTENT"
+elif [ -f "$PR_FLAT" ]; then
+  PR_FILE="$PR_FLAT"
+else
+  error_exit "pr.md not found. Run /pr $INTENT_ID first to generate work/workflow-state/pr.md (or work/workflow-state/$INTENT_ID/pr.md)." 1
+fi
+
+# PR title from first line of pr.md (e.g. "# PR: F-001 - Title")
+TITLE=$(head -1 "$PR_FILE" | sed 's/^# *PR: *//;s/^# *//')
+[ -n "$TITLE" ] || TITLE="Intent $INTENT_ID"
+
+echo -e "${BLUE}Creating PR: $TITLE${NC}"
+gh pr create --title "$TITLE" --body-file "$PR_FILE" || error_exit "gh pr create failed" 1
+echo -e "${GREEN}PR created from $PR_FILE${NC}"

package/scripts/gh/link-issue.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+# Link an existing GitHub issue to an intent (write issue number into intent file).
+# Usage: link-issue.sh <intent-id> <issue-number>
+# Requires: gh
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+# shellcheck source=../lib/intent.sh
+[ -f "$SCRIPT_DIR/../lib/intent.sh" ] && source "$SCRIPT_DIR/../lib/intent.sh"
+# shellcheck source=../lib/common.sh
+[ -f "$SCRIPT_DIR/../lib/common.sh" ] && source "$SCRIPT_DIR/../lib/common.sh"
+
+require_cmd gh
+
+INTENT_ID="${1:-}"
+ISSUE_NUM="${2:-}"
+[ -n "$INTENT_ID" ] && [ -n "$ISSUE_NUM" ] || error_exit "Usage: link-issue.sh <intent-id> <issue-number>" 1
+[[ "$ISSUE_NUM" =~ ^[0-9]+$ ]] || error_exit "Issue number must be numeric" 1
+
+cd "$ROOT_DIR" || error_exit "Failed to cd to repo root" 1
+INTENT_FILE="$(require_intent_file "$INTENT_ID")"
+
+if grep -q '^## GitHub issue' "$INTENT_FILE"; then
+  awk -v num="$ISSUE_NUM" '
+    /^## GitHub issue$/ { in_sec=1; print; next }
+    in_sec && /^#?[0-9]+$/ { print "#" num; in_sec=0; next }
+    in_sec && /^## / { in_sec=0 }
+    { print }
+  ' "$INTENT_FILE" > "$INTENT_FILE.nw" && mv "$INTENT_FILE.nw" "$INTENT_FILE"
+else
+  awk -v num="$ISSUE_NUM" '
+    /^## Do Not Repeat Check/ {
+      print "## GitHub issue"
+      print ""
+      print "#" num
+      print ""
+    }
+    { print }
+  ' "$INTENT_FILE" > "$INTENT_FILE.nw" && mv "$INTENT_FILE.nw" "$INTENT_FILE"
+fi
+
+echo -e "${GREEN}Linked issue #${ISSUE_NUM} to $INTENT_FILE${NC}"

package/scripts/gh/on-ship-update-issue.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+# When an intent is shipped, update or close the linked GitHub issue.
+# Usage: on-ship-update-issue.sh <intent-id> [--close]
+# Default: add a comment only. Use --close to close the issue.
+# Set SHIP_CLOSE_ISSUE=1 to close (same as --close).
+# Requires: gh
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+# shellcheck source=../lib/intent.sh
+[ -f "$SCRIPT_DIR/../lib/intent.sh" ] && source "$SCRIPT_DIR/../lib/intent.sh"
+# shellcheck source=../lib/common.sh
+[ -f "$SCRIPT_DIR/../lib/common.sh" ] && source "$SCRIPT_DIR/../lib/common.sh"
+
+require_cmd gh
+
+INTENT_ID="${1:-}"
+[ -n "$INTENT_ID" ] || error_exit "Usage: on-ship-update-issue.sh <intent-id> [--close]" 1
+CLOSE_ISSUE=false
+[ "${2:-}" = "--close" ] && CLOSE_ISSUE=true
+[ "${SHIP_CLOSE_ISSUE:-0}" = "1" ] && CLOSE_ISSUE=true
+
+cd "$ROOT_DIR" || error_exit "Failed to cd to repo root" 1
+INTENT_FILE="$(require_intent_file "$INTENT_ID")"
+
+# Extract GitHub issue number from intent (line under ## GitHub issue that looks like #N or N)
+ISSUE_NUM=$(awk '/^## GitHub issue$/,/^## /{if (/^#?[0-9]+$/) { gsub(/^#/,""); print; exit }}' "$INTENT_FILE" 2>/dev/null || true)
+
+[ -n "$ISSUE_NUM" ] || { echo -e "${YELLOW}No GitHub issue linked to intent $INTENT_ID; skipping.${NC}"; exit 0; }
+
+COMMENT="Shipped via intent $INTENT_ID."
+if [ "$CLOSE_ISSUE" = true ]; then
+  echo -e "${BLUE}Closing issue #${ISSUE_NUM} with comment.${NC}"
+  gh issue close "$ISSUE_NUM" --comment "$COMMENT" || error_exit "gh issue close failed" 1
+  echo -e "${GREEN}Closed issue #${ISSUE_NUM}${NC}"
+else
+  echo -e "${BLUE}Adding comment to issue #${ISSUE_NUM}.${NC}"
+  gh issue comment "$ISSUE_NUM" --body "$COMMENT" || error_exit "gh issue comment failed" 1
+  echo -e "${GREEN}Commented on issue #${ISSUE_NUM}${NC}"
+fi

package/scripts/headless/README.md

@@ -0,0 +1,8 @@
+# Headless mode scripts
+
+Run ShipIt phases from the CLI without Cursor. Uses the same `.cursor/commands` and `.cursor/rules` as Cursor; calls OpenAI or Anthropic API to generate phase output.
+
+- **run-phase.sh** — Run one phase (1–5) for an intent. Requires `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`.
+- **call-llm.js** — Helper that sends a prompt to the LLM and prints the response (used by run-phase.sh).
+
+See [docs/headless-mode.md](../../docs/headless-mode.md) for full documentation, human gates, and how to approve.

package/scripts/headless/call-llm.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+/**
+ * Call OpenAI or Anthropic API with a prompt; print the model response to stdout.
+ * Requires OPENAI_API_KEY or ANTHROPIC_API_KEY. Used by run-phase.sh.
+ * Usage: node scripts/headless/call-llm.js [--prompt "inline prompt"]
+ *   Or: echo "prompt" | node scripts/headless/call-llm.js
+ */
+
+import { readFileSync } from "node:fs";
+
+const OPENAI_API_KEY = process.env.OPENAI_API_KEY;
+const ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
+
+function getStdin() {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) resolve("");
+    else {
+      const chunks = [];
+      process.stdin.on("data", (chunk) => chunks.push(chunk));
+      process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    }
+  });
+}
+
+async function main() {
+  let prompt = "";
+  const arg = process.argv[2];
+  if (arg === "--prompt" && process.argv[3] != null) {
+    prompt = process.argv[3];
+  } else {
+    prompt = (await getStdin()).trim();
+  }
+  if (!prompt) {
+    console.error("Usage: echo 'prompt' | node call-llm.js   OR   node call-llm.js --prompt 'your prompt'");
+    process.exit(1);
+  }
+
+  if (OPENAI_API_KEY) {
+    const url = "https://api.openai.com/v1/chat/completions";
+    const body = {
+      model: process.env.OPENAI_MODEL || "gpt-4o-mini",
+      messages: [{ role: "user", content: prompt }],
+      max_tokens: 4096,
+    };
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${OPENAI_API_KEY}`,
+      },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+      const err = await res.text();
+      console.error("OpenAI API error:", res.status, err);
+      process.exit(1);
+    }
+    const data = await res.json();
+    const text = data.choices?.[0]?.message?.content ?? "";
+    if (!text) {
+      console.error("OpenAI returned no content:", JSON.stringify(data).slice(0, 200));
+      process.exit(1);
+    }
+    process.stdout.write(text);
+    return;
+  }
+
+  if (ANTHROPIC_API_KEY) {
+    const url = "https://api.anthropic.com/v1/messages";
+    const body = {
+      model: process.env.ANTHROPIC_MODEL || "claude-3-5-haiku-20241022",
+      max_tokens: 4096,
+      messages: [{ role: "user", content: prompt }],
+    };
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-api-key": ANTHROPIC_API_KEY,
+        "anthropic-version": "2023-06-01",
+      },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+      const err = await res.text();
+      console.error("Anthropic API error:", res.status, err);
+      process.exit(1);
+    }
+    const data = await res.json();
+    const block = data.content?.find((c) => c.type === "text");
+    const text = block?.text ?? "";
+    if (!text) {
+      console.error("Anthropic returned no text:", JSON.stringify(data).slice(0, 200));
+      process.exit(1);
+    }
+    process.stdout.write(text);
+    return;
+  }
+
+  console.error(
+    "Set OPENAI_API_KEY or ANTHROPIC_API_KEY to run headless. Never commit API keys."
+  );
+  process.exit(1);
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

package/scripts/headless/run-phase.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# Run one ShipIt phase headless (no Cursor). Reads same .cursor/ content, calls LLM, writes state.
+# Usage: ./scripts/headless/run-phase.sh <intent-id> <phase-number>
+# Phase: 1=Analysis, 2=Planning, 3=Implementation, 4=Verification, 5=Release.
+# Requires OPENAI_API_KEY or ANTHROPIC_API_KEY. See docs/headless-mode.md.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+cd "$REPO_ROOT"
+
+# Source libs (use absolute paths so we find them from repo root)
+HELPER_DIR="$SCRIPT_DIR/../lib"
+[ -f "$HELPER_DIR/common.sh" ] && source "$HELPER_DIR/common.sh"
+[ -f "$HELPER_DIR/intent.sh" ] && source "$HELPER_DIR/intent.sh"
+[ -f "$HELPER_DIR/workflow_state.sh" ] && source "$HELPER_DIR/workflow_state.sh"
+
+INTENT_ID="${1:-}"
+PHASE_NUM="${2:-}"
+if [ -z "$INTENT_ID" ] || [ -z "$PHASE_NUM" ]; then
+  echo "Usage: $0 <intent-id> <phase-number>" >&2
+  echo "  Phase: 1=Analysis, 2=Planning, 3=Implementation, 4=Verification, 5=Release" >&2
+  exit 1
+fi
+
+# Require intent file
+require_intent_file "$INTENT_ID" >/dev/null || error_exit "Intent file not found for $INTENT_ID" 1
+
+# Resolve workflow state dir (flat or per-intent)
+WORKFLOW_DIR="$(get_workflow_state_dir "$INTENT_ID")"
+[ -n "$WORKFLOW_DIR" ] || error_exit "No workflow state dir for $INTENT_ID. Run pnpm workflow-orchestrator $INTENT_ID first." 1
+mkdir -p "$WORKFLOW_DIR"
+
+# Phase config: output file, role rule name, phase name
+case "$PHASE_NUM" in
+  1) OUT_FILE="01_analysis.md";   ROLE_RULE="pm";         PHASE_NAME="Analysis (PM)" ;;
+  2) OUT_FILE="02_plan.md";       ROLE_RULE="architect";  PHASE_NAME="Planning (Architect)" ;;
+  3) OUT_FILE="03_implementation.md"; ROLE_RULE="implementer"; PHASE_NAME="Implementation (Implementer)" ;;
+  4) OUT_FILE="04_verification.md"; ROLE_RULE="qa";       PHASE_NAME="Verification (QA)" ;;
+  5) OUT_FILE="05_release_notes.md"; ROLE_RULE="docs";    PHASE_NAME="Release (Docs)" ;;
+  *) error_exit "Phase must be 1-5, got: $PHASE_NUM" 1 ;;
+esac
+
+# Check API key
+if [ -z "${OPENAI_API_KEY:-}" ] && [ -z "${ANTHROPIC_API_KEY:-}" ]; then
+  echo "Set OPENAI_API_KEY or ANTHROPIC_API_KEY to run headless. Never commit API keys." >&2
+  echo "See docs/headless-mode.md for details." >&2
+  exit 1
+fi
+
+# Read role rule and ship command content (same source as Cursor)
+ROLE_FILE=".cursor/rules/${ROLE_RULE}.mdc"
+SHIP_FILE=".cursor/commands/ship.md"
+[ -f "$ROLE_FILE" ] || error_exit "Role rule not found: $ROLE_FILE" 1
+[ -f "$SHIP_FILE" ] || error_exit "Command file not found: $SHIP_FILE" 1
+
+ROLE_CONTENT="$(cat "$ROLE_FILE")"
+SHIP_CONTENT="$(cat "$SHIP_FILE")"
+
+# Build prompt: single source of instructions
+PROMPT="You are running ShipIt Phase $PHASE_NUM: $PHASE_NAME. Intent ID: $INTENT_ID.
+Write the content for the output file: $OUT_FILE (path under work/workflow-state).
+Do not include the filename or markdown fence in your response; output only the file body.
+
+=== Role and constraints (follow these) ===
+$ROLE_CONTENT
+
+=== Workflow instructions (ship command) ===
+$SHIP_CONTENT
+
+=== Task ===
+Produce the complete content for $OUT_FILE for intent $INTENT_ID. Output only the file body, no preamble."
+
+# Call LLM and write output
+echo "Running Phase $PHASE_NUM ($PHASE_NAME) for $INTENT_ID..." >&2
+node "$SCRIPT_DIR/call-llm.js" --prompt "$PROMPT" > "$WORKFLOW_DIR/$OUT_FILE" || exit 1
+echo "Wrote $WORKFLOW_DIR/$OUT_FILE" >&2
+
+# Human gates: after phase 2 (plan) and phase 5 (release)
+if [ "$PHASE_NUM" = "2" ]; then
+  echo "" >&2
+  echo "*** Waiting for human approval ***" >&2
+  echo "Review $WORKFLOW_DIR/02_plan.md and add APPROVED (or check the approval box)." >&2
+  echo "Then run: $0 $INTENT_ID 3" >&2
+  exit 0
+fi
+if [ "$PHASE_NUM" = "5" ]; then
+  echo "" >&2
+  echo "*** Release phase complete. Steward/human approval may be required. ***" >&2
+  echo "Review $WORKFLOW_DIR/05_release_notes.md. Then run verify or ship as needed." >&2
+  exit 0
+fi
+
+# Next phase hint
+NEXT=$((PHASE_NUM + 1))
+if [ "$NEXT" -le 5 ]; then
+  echo "Next: $0 $INTENT_ID $NEXT" >&2
+fi