dsh-compound-engineering 0.0.0-stage → 0.1.0

package/skills/ce-optimize/scripts/experiment-worktree.sh

@@ -0,0 +1,330 @@
+#!/bin/bash
+
+# Experiment Worktree Manager
+# Creates, cleans up, and manages worktrees for optimization experiments.
+# Each experiment gets an isolated worktree with copied shared resources.
+#
+# Usage:
+#   experiment-worktree.sh create <spec_name> <exp_index> <base_branch> [shared_file ...]
+#   experiment-worktree.sh cleanup <spec_name> <exp_index>
+#   experiment-worktree.sh cleanup-all <spec_name>
+#   experiment-worktree.sh count
+#
+# Worktrees are created at: .worktrees/optimize-<spec>-exp-<NNN>/
+# Branches are named: optimize-exp/<spec>/exp-<NNN>
+
+set -euo pipefail
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+GIT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || {
+  echo -e "${RED}Error: Not in a git repository${NC}" >&2
+  exit 1
+}
+
+WORKTREE_DIR="$GIT_ROOT/.worktrees"
+
+# Every path this script deletes is built from these two inputs, so they are
+# checked before any path is composed: a name or shared path that can climb
+# out of its directory would turn a cleanup into a delete of something else.
+require_spec_name() {
+  if [[ ! "$1" =~ ^[a-z0-9][a-z0-9-]*$ ]]; then
+    echo -e "${RED}Error: spec name must be lowercase kebab-case: $1${NC}" >&2
+    exit 1
+  fi
+}
+
+require_relative_inside() {
+  case "/$1/" in
+    //*|*/../*|*/./*)
+      echo -e "${RED}Error: shared path must be relative and stay inside the repo: $1${NC}" >&2
+      exit 1
+      ;;
+  esac
+}
+
+# Last-resort removal when git cannot remove a worktree. Only ever a direct
+# child of .worktrees that this script named.
+remove_experiment_dir() {
+  local target="$1"
+  if [[ "$(dirname "$target")" != "$WORKTREE_DIR" ]] || [[ "$(basename "$target")" != optimize-*-exp-* ]] || [[ -L "$target" ]]; then
+    echo -e "${RED}Error: refusing to remove a path outside $WORKTREE_DIR: $target${NC}" >&2
+    return 1
+  fi
+  rm -rf "$target"
+}
+
+experiment_branch_name() {
+  local spec_name="${1:?Error: spec_name required}"
+  local padded_index="${2:?Error: padded_index required}"
+
+  # Keep experiment refs outside optimize/<spec> so they do not collide
+  # with the long-lived optimization branch namespace.
+  echo "optimize-exp/${spec_name}/exp-${padded_index}"
+}
+
+ensure_worktree_exclude() {
+  local exclude_file
+  exclude_file=$(git rev-parse --git-path info/exclude)
+
+  mkdir -p "$(dirname "$exclude_file")"
+
+  if ! grep -q "^\.worktrees$" "$exclude_file" 2>/dev/null; then
+    echo ".worktrees" >> "$exclude_file"
+  fi
+}
+
+is_registered_worktree() {
+  local worktree_path="${1:?Error: worktree_path required}"
+
+  git worktree list --porcelain | awk -v target="$worktree_path" '
+    $1 == "worktree" && $2 == target { found = 1 }
+    END { exit(found ? 0 : 1) }
+  '
+}
+
+is_branch_checked_out() {
+  local branch_name="${1:?Error: branch_name required}"
+  local branch_ref="refs/heads/$branch_name"
+
+  git worktree list --porcelain | awk -v target="$branch_ref" '
+    $1 == "branch" && $2 == target { found = 1 }
+    END { exit(found ? 0 : 1) }
+  '
+}
+
+reset_worktree_to_base() {
+  local worktree_path="${1:?Error: worktree_path required}"
+  local branch_name="${2:?Error: branch_name required}"
+  local base_branch="${3:?Error: base_branch required}"
+  local current_branch
+
+  current_branch=$(git -C "$worktree_path" symbolic-ref --quiet --short HEAD 2>/dev/null || true)
+  if [[ "$current_branch" != "$branch_name" ]]; then
+    echo -e "${RED}Error: Existing worktree is on unexpected branch: ${current_branch:-detached} (expected $branch_name)${NC}" >&2
+    echo -e "${RED}Clean up the stale worktree before rerunning this experiment.${NC}" >&2
+    return 1
+  fi
+
+  echo -e "${YELLOW}Resetting existing experiment worktree to base: $branch_name -> $base_branch${NC}" >&2
+  git -C "$worktree_path" reset --hard "$base_branch" >/dev/null
+  git -C "$worktree_path" clean -fdx >/dev/null
+}
+
+# Create an experiment worktree
+create_worktree() {
+  local spec_name="${1:?Error: spec_name required}"
+  local exp_index="${2:?Error: exp_index required}"
+  local base_branch="${3:?Error: base_branch required}"
+  shift 3
+  require_spec_name "$spec_name"
+  local shared_file
+  for shared_file in "$@"; do
+    require_relative_inside "$shared_file"
+  done
+
+  local padded_index
+  padded_index=$(printf "%03d" "$exp_index")
+  local worktree_name="optimize-${spec_name}-exp-${padded_index}"
+  local branch_name
+  branch_name=$(experiment_branch_name "$spec_name" "$padded_index")
+  local worktree_path="$WORKTREE_DIR/$worktree_name"
+
+  # Check if worktree already exists
+  if [[ -d "$worktree_path" ]]; then
+    if ! git -C "$worktree_path" rev-parse --is-inside-work-tree >/dev/null 2>&1 || \
+       ! is_registered_worktree "$worktree_path"; then
+      echo -e "${RED}Error: Existing path is not a valid registered git worktree: $worktree_path${NC}" >&2
+      echo -e "${RED}Remove or repair that directory before rerunning the experiment.${NC}" >&2
+      return 1
+    fi
+
+    echo -e "${YELLOW}Worktree already exists: $worktree_path${NC}" >&2
+    reset_worktree_to_base "$worktree_path" "$branch_name" "$base_branch"
+  else
+    mkdir -p "$WORKTREE_DIR"
+    ensure_worktree_exclude
+
+    # Create worktree from the base branch
+    if ! git worktree add -b "$branch_name" "$worktree_path" "$base_branch" --quiet 2>/dev/null; then
+      if git show-ref --verify --quiet "refs/heads/$branch_name"; then
+        if is_branch_checked_out "$branch_name"; then
+          echo -e "${RED}Error: Existing experiment branch is already checked out: $branch_name${NC}" >&2
+          echo -e "${RED}Clean up the stale worktree before rerunning this experiment.${NC}" >&2
+          return 1
+        fi
+
+        echo -e "${YELLOW}Resetting existing experiment branch to base: $branch_name -> $base_branch${NC}" >&2
+        git branch -f "$branch_name" "$base_branch" >/dev/null
+        git worktree add "$worktree_path" "$branch_name" --quiet
+      else
+        echo -e "${RED}Error: Failed to create worktree for $branch_name from $base_branch${NC}" >&2
+        return 1
+      fi
+    fi
+  fi
+
+  # Copy .env files from main repo
+  for f in "$GIT_ROOT"/.env*; do
+    if [[ -f "$f" ]]; then
+      local basename
+      basename=$(basename "$f")
+      if [[ "$basename" != ".env.example" ]]; then
+        cp "$f" "$worktree_path/$basename"
+      fi
+    fi
+  done
+
+  # Copy shared files
+  for shared_file in "$@"; do
+    if [[ -f "$GIT_ROOT/$shared_file" ]]; then
+      local dir
+      dir=$(dirname "$worktree_path/$shared_file")
+      mkdir -p "$dir"
+      cp "$GIT_ROOT/$shared_file" "$worktree_path/$shared_file"
+    elif [[ -d "$GIT_ROOT/$shared_file" ]]; then
+      local dir
+      dir=$(dirname "$worktree_path/$shared_file")
+      mkdir -p "$dir"
+      rm -rf "$worktree_path/$shared_file"
+      cp -R "$GIT_ROOT/$shared_file" "$worktree_path/$shared_file"
+    fi
+  done
+
+  echo "$worktree_path"
+}
+
+# Clean up a single experiment worktree
+cleanup_worktree() {
+  local spec_name="${1:?Error: spec_name required}"
+  local exp_index="${2:?Error: exp_index required}"
+  require_spec_name "$spec_name"
+
+  local padded_index
+  padded_index=$(printf "%03d" "$exp_index")
+  local worktree_name="optimize-${spec_name}-exp-${padded_index}"
+  local branch_name
+  branch_name=$(experiment_branch_name "$spec_name" "$padded_index")
+  local worktree_path="$WORKTREE_DIR/$worktree_name"
+
+  if [[ -d "$worktree_path" ]]; then
+    git worktree remove "$worktree_path" --force 2>/dev/null || {
+      # If worktree remove fails, try manual cleanup
+      remove_experiment_dir "$worktree_path" 2>/dev/null || true
+      git worktree prune 2>/dev/null || true
+    }
+  fi
+
+  # Delete the experiment branch
+  git branch -D "$branch_name" 2>/dev/null || true
+
+  echo -e "${GREEN}Cleaned up: $worktree_name${NC}" >&2
+}
+
+# Clean up all experiment worktrees for a spec
+cleanup_all() {
+  local spec_name="${1:?Error: spec_name required}"
+  require_spec_name "$spec_name"
+  local prefix="optimize-${spec_name}-exp-"
+  local count=0
+
+  if [[ ! -d "$WORKTREE_DIR" ]]; then
+    echo -e "${YELLOW}No worktrees directory found${NC}" >&2
+    return 0
+  fi
+
+  for worktree_path in "$WORKTREE_DIR"/${prefix}*; do
+    if [[ -d "$worktree_path" ]]; then
+      local worktree_name
+      worktree_name=$(basename "$worktree_path")
+      # Extract index from name
+      local index_str="${worktree_name#$prefix}"
+
+      git worktree remove "$worktree_path" --force 2>/dev/null || {
+        remove_experiment_dir "$worktree_path" 2>/dev/null || true
+      }
+
+      # Delete the branch
+      local branch_name
+      branch_name=$(experiment_branch_name "$spec_name" "$index_str")
+      git branch -D "$branch_name" 2>/dev/null || true
+
+      count=$((count + 1))
+    fi
+  done
+
+  git worktree prune 2>/dev/null || true
+
+  # Clean up empty worktree directory
+  if [[ -d "$WORKTREE_DIR" ]] && [[ -z "$(ls -A "$WORKTREE_DIR" 2>/dev/null)" ]]; then
+    rmdir "$WORKTREE_DIR" 2>/dev/null || true
+  fi
+
+  echo -e "${GREEN}Cleaned up $count experiment worktree(s) for $spec_name${NC}" >&2
+}
+
+# Count total worktrees (for budget check)
+count_worktrees() {
+  local count=0
+  if [[ -d "$WORKTREE_DIR" ]]; then
+    for worktree_path in "$WORKTREE_DIR"/*; do
+      if [[ -d "$worktree_path" ]] && [[ -e "$worktree_path/.git" ]]; then
+        count=$((count + 1))
+      fi
+    done
+  fi
+  echo "$count"
+}
+
+# Main
+main() {
+  local command="${1:-help}"
+
+  case "$command" in
+    create)
+      shift
+      create_worktree "$@"
+      ;;
+    cleanup)
+      shift
+      cleanup_worktree "$@"
+      ;;
+    cleanup-all)
+      shift
+      cleanup_all "$@"
+      ;;
+    count)
+      count_worktrees
+      ;;
+    help)
+      cat << 'EOF'
+Experiment Worktree Manager
+
+Usage:
+  experiment-worktree.sh create <spec_name> <exp_index> <base_branch> [shared_file ...]
+  experiment-worktree.sh cleanup <spec_name> <exp_index>
+  experiment-worktree.sh cleanup-all <spec_name>
+  experiment-worktree.sh count
+
+Commands:
+  create       Create an experiment worktree with copied shared files
+  cleanup      Remove a single experiment worktree and its branch
+  cleanup-all  Remove all experiment worktrees for a spec
+  count        Count total active worktrees (for budget checking)
+
+Worktrees:  .worktrees/optimize-<spec>-exp-<NNN>/
+Branches:   optimize-exp/<spec>/exp-<NNN>
+EOF
+      ;;
+    *)
+      echo -e "${RED}Unknown command: $command${NC}" >&2
+      exit 1
+      ;;
+  esac
+}
+
+main "$@"

package/skills/ce-optimize/scripts/measure.sh

@@ -0,0 +1,140 @@
+#!/bin/bash
+
+# Measurement Runner
+# Runs a measurement command, captures JSON output, and handles timeouts.
+# The orchestrating agent (not this script) evaluates gates and handles
+# stability repeats.
+#
+# Usage: measure.sh <command> <timeout_seconds> [working_directory] [KEY=VALUE ...]
+#
+# Arguments:
+#   command          - Shell command to run (e.g., "python evaluate.py")
+#   timeout_seconds  - Maximum seconds before killing the command
+#   working_directory - Directory to run the command in (default: .)
+#   KEY=VALUE        - Optional environment variables to set before running
+#
+# Output:
+#   stdout: Raw JSON output from the measurement command
+#   stderr: Passed through from the measurement command
+#   exit code: Same as the measurement command (124 for timeout, 125 when
+#              CE_OPTIMIZE_CENSOR_AFTER fires before timeout_seconds)
+
+set -euo pipefail
+
+# Parse arguments
+COMMAND="${1:?Error: command argument required}"
+TIMEOUT="${2:?Error: timeout_seconds argument required}"
+shift 2
+
+WORKDIR="."
+if [[ $# -gt 0 ]] && [[ "$1" != *=* ]]; then
+  WORKDIR="$1"
+  shift
+fi
+
+# Set any KEY=VALUE environment variables
+for arg in "$@"; do
+  if [[ "$arg" == *=* ]]; then
+    export "$arg"
+  fi
+done
+
+# Change to working directory
+cd "$WORKDIR" || {
+  echo "Error: cannot cd to $WORKDIR" >&2
+  exit 1
+}
+
+run_timed_command() {
+  local timeout_bin="$1"
+  if [[ -n "${CENSOR_STATUS_FILE:-}" ]]; then
+    "$timeout_bin" "$TIMEOUT" bash -c 'bash -c "$1"; printf "%s\n" "$?" > "$2"; exit 0' _ "$COMMAND" "$CENSOR_STATUS_FILE"
+    return
+  fi
+  "$timeout_bin" "$TIMEOUT" bash -c "$COMMAND"
+}
+
+run_with_timeout() {
+  if command -v timeout >/dev/null 2>&1; then
+    run_timed_command timeout
+    return
+  fi
+
+  if command -v gtimeout >/dev/null 2>&1; then
+    run_timed_command gtimeout
+    return
+  fi
+
+  PY=""
+  for c in python3 python py; do
+    if command -v "$c" >/dev/null 2>&1 && "$c" -c '' >/dev/null 2>&1; then
+      PY="$c"
+      break
+    fi
+  done
+  if [ -n "$PY" ]; then
+    "$PY" - "$TIMEOUT" "$COMMAND" "${CENSOR_STATUS_FILE:-}" <<'PY'
+import os
+import signal
+import subprocess
+import sys
+
+timeout_seconds = float(sys.argv[1])
+command = sys.argv[2]
+status_file = sys.argv[3] if len(sys.argv) > 3 and sys.argv[3] else ""
+proc = subprocess.Popen(["bash", "-c", command], start_new_session=True)
+
+try:
+    rc = proc.wait(timeout=timeout_seconds)
+    if status_file:
+        with open(status_file, "w", encoding="utf-8") as fh:
+            fh.write(f"{rc}\n")
+        sys.exit(0)
+    sys.exit(rc)
+except subprocess.TimeoutExpired:
+    os.killpg(proc.pid, signal.SIGTERM)
+    try:
+        proc.wait(timeout=5)
+    except subprocess.TimeoutExpired:
+        os.killpg(proc.pid, signal.SIGKILL)
+        proc.wait()
+    sys.exit(124)
+PY
+    return
+  fi
+
+  echo "Error: no timeout implementation available (tried timeout, gtimeout, and a working Python 3 interpreter)" >&2
+  exit 1
+}
+
+# Optional futility bound: CE_OPTIMIZE_CENSOR_AFTER=<seconds> kills a live
+# run that has already exceeded a predeclared noncompetitive bound. Distinct
+# from timeout_seconds (the spec's hard cap). Exit 125 means censored; 124
+# still means the configured timeout fired.
+CENSOR_AFTER="${CE_OPTIMIZE_CENSOR_AFTER:-}"
+CENSORING=0
+CENSOR_STATUS_FILE=""
+if [[ -n "$CENSOR_AFTER" ]] && awk -v a="$CENSOR_AFTER" -v t="$TIMEOUT" 'BEGIN { exit !(a ~ /^[0-9]+(\.[0-9]+)?$/ && t+0 == t && a+0 > 0 && a+0 < t+0) }'; then
+  TIMEOUT="$CENSOR_AFTER"
+  CENSORING=1
+  CENSOR_STATUS_FILE=$(mktemp "${TMPDIR:-/tmp}/ce-optimize-censor-XXXXXX")
+fi
+
+# Run the measurement command with timeout
+# timeout returns 124 if the command times out
+# We pass stdout and stderr through directly
+set +e
+run_with_timeout
+status=$?
+set -e
+if [[ $CENSORING -eq 1 ]]; then
+  if [[ -s "$CENSOR_STATUS_FILE" ]]; then
+    status=$(cat "$CENSOR_STATUS_FILE")
+  elif [[ $status -eq 124 ]]; then
+    echo "Error: measurement censored after ${CENSOR_AFTER}s (noncompetitive bound)" >&2
+    rm -f "$CENSOR_STATUS_FILE"
+    exit 125
+  fi
+  rm -f "$CENSOR_STATUS_FILE"
+fi
+exit "$status"

package/skills/ce-optimize/scripts/parallel-probe.sh

@@ -0,0 +1,134 @@
+#!/bin/bash
+
+# Parallelism Probe
+# Detects common parallelism blockers in the target project.
+# Output is advisory -- the skill presents results to the user for approval.
+#
+# Usage: parallel-probe.sh <project_directory> [measurement_command] [measurement_workdir] [shared_file ...]
+#
+# Arguments:
+#   project_directory   - Root directory of the project to probe
+#   measurement_command - The measurement command from the spec (optional, for port detection)
+#   measurement_workdir - Measurement working directory relative to project root (default: .)
+#   shared_file         - Explicitly declared shared files that parallel runs depend on
+#
+# Output:
+#   JSON to stdout with:
+#     mode: "parallel" | "serial" | "user-decision"
+#     blockers: [ { type, description, suggestion } ]
+
+set -euo pipefail
+
+PROJECT_DIR="${1:?Error: project_directory argument required}"
+MEASUREMENT_CMD="${2:-}"
+MEASUREMENT_WORKDIR="${3:-.}"
+
+shift 3 2>/dev/null || shift $# 2>/dev/null || true
+SHARED_FILES=()
+if [[ $# -gt 0 ]]; then
+  SHARED_FILES=("$@")
+fi
+
+cd "$PROJECT_DIR" || {
+  echo '{"mode":"serial","blockers":[{"type":"error","description":"Cannot access project directory","suggestion":"Check path"}]}'
+  exit 0
+}
+
+PY=""
+for c in python3 python py; do
+  if command -v "$c" >/dev/null 2>&1 && "$c" -c '' >/dev/null 2>&1; then
+    PY="$c"
+    break
+  fi
+done
+if [ -z "$PY" ]; then
+  echo '{"mode":"serial","blockers":[{"type":"missing_dependency","description":"A working Python 3 interpreter is required for structured probe output","suggestion":"Install Python 3 (python3, python, or py on PATH) or skip the probe and review parallel-readiness manually"}],"blocker_count":1}'
+  exit 0
+fi
+
+BLOCKERS="[]"
+SCAN_PATHS=()
+
+add_blocker() {
+  local type="$1"
+  local desc="$2"
+  local suggestion="$3"
+  BLOCKERS=$(echo "$BLOCKERS" | "$PY" -c "
+import json, sys
+b = json.load(sys.stdin)
+b.append({'type': '$type', 'description': '''$desc''', 'suggestion': '''$suggestion'''})
+print(json.dumps(b))
+" 2>/dev/null || echo "$BLOCKERS")
+}
+
+add_scan_path() {
+  local candidate="$1"
+
+  if [[ -z "$candidate" ]]; then
+    return
+  fi
+
+  if [[ -e "$candidate" ]]; then
+    SCAN_PATHS+=("$candidate")
+  fi
+}
+
+add_scan_path "$MEASUREMENT_WORKDIR"
+
+if [[ ${#SHARED_FILES[@]} -gt 0 ]]; then
+  for shared_file in "${SHARED_FILES[@]}"; do
+    add_scan_path "$shared_file"
+  done
+fi
+
+if [[ ${#SCAN_PATHS[@]} -eq 0 ]]; then
+  SCAN_PATHS=(".")
+fi
+
+# Check 1: Hardcoded ports in measurement command
+if [[ -n "$MEASUREMENT_CMD" ]]; then
+  # Look for common port patterns in the command itself
+  if echo "$MEASUREMENT_CMD" | grep -qE '(--port(?:\s+|=)[0-9]+|:\s*[0-9]{4,5}|PORT=[0-9]+|localhost:[0-9]+)'; then
+    add_blocker "port" "Measurement command contains hardcoded port reference" "Parameterize port via environment variable (e.g., PORT=\$EVAL_PORT)"
+  fi
+fi
+
+# Check 2: SQLite databases in the measurement workdir or declared shared files
+SQLITE_FILES=$(find "${SCAN_PATHS[@]}" -maxdepth 4 -type f \( -name '*.db' -o -name '*.sqlite' -o -name '*.sqlite3' \) ! -path '*/.git/*' ! -path '*/node_modules/*' ! -path '*/.claude/*' ! -path '*/.context/*' ! -path '*/.worktrees/*' 2>/dev/null | head -10 || true)
+if [[ -n "$SQLITE_FILES" ]]; then
+  FILE_COUNT=$(echo "$SQLITE_FILES" | wc -l | tr -d ' ')
+  add_blocker "shared_file" "Found $FILE_COUNT SQLite database file(s)" "Copy database files into each experiment worktree"
+fi
+
+# Check 3: Lock/PID files in the measurement workdir or declared shared files
+LOCK_FILES=$(find "${SCAN_PATHS[@]}" -maxdepth 4 -type f \( -name '*.lock' -o -name '*.pid' \) ! -path '*/.git/*' ! -path '*/node_modules/*' ! -path '*/.claude/*' ! -path '*/.context/*' ! -path '*/.worktrees/*' ! -name 'package-lock.json' ! -name 'yarn.lock' ! -name 'bun.lock' ! -name 'bun.lockb' ! -name 'Gemfile.lock' ! -name 'poetry.lock' ! -name 'Cargo.lock' 2>/dev/null | head -10 || true)
+if [[ -n "$LOCK_FILES" ]]; then
+  FILE_COUNT=$(echo "$LOCK_FILES" | wc -l | tr -d ' ')
+  add_blocker "lock_file" "Found $FILE_COUNT lock/PID file(s) that may cause contention" "Ensure measurement command cleans up lock files, or run in serial mode"
+fi
+
+# Check 4: Exclusive resource hints in the measurement command
+if [[ -n "$MEASUREMENT_CMD" ]] && echo "$MEASUREMENT_CMD" | grep -qiE '(cuda|gpu|tensorflow|torch|nvidia-smi|CUDA_VISIBLE_DEVICES)'; then
+  add_blocker "exclusive_resource" "Measurement command appears to use GPU or another exclusive accelerator" "GPU is typically an exclusive resource -- consider serial mode or device parameterization"
+fi
+
+# Determine mode
+BLOCKER_COUNT=$(echo "$BLOCKERS" | "$PY" -c "import json,sys; print(len(json.load(sys.stdin)))" 2>/dev/null || echo "0")
+
+if [[ "$BLOCKER_COUNT" == "0" ]]; then
+  MODE="parallel"
+elif echo "$BLOCKERS" | "$PY" -c "import json,sys; b=json.load(sys.stdin); exit(0 if any(x['type']=='exclusive_resource' for x in b) else 1)" 2>/dev/null; then
+  MODE="serial"
+else
+  MODE="user-decision"
+fi
+
+# Output JSON result
+"$PY" -c "
+import json
+print(json.dumps({
+    'mode': '$MODE',
+    'blockers': $BLOCKERS,
+    'blocker_count': $BLOCKER_COUNT
+}, indent=2))
+"

package/skills/ce-plan/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: ce-plan
+description: "Create structured plans for multi-step work, including software and non-software tasks. Use when asked to plan, break down implementation, plan from requirements, or deepen an existing plan; prefer ce-brainstorm for exploratory framing."
+argument-hint: "[optional: feature description, requirements doc path, plan path to deepen, or any task to plan] [output:html]"
+---
+
+# Create Technical Plan
+
+**The current year is 2026.**
+
+**Outcome:** a plan for carrying out and checking the agreed work while preserving its outcome and constraints. Resolve technical choices from evidence; leave adequate instructions unchanged. `ce-brainstorm` defines **WHAT**, `ce-plan` plans **HOW**, and `ce-work` executes. A prior brainstorm is optional.
+
+**An explicit invocation always produces a plan.** Never classify a direct invocation as "not a planning task" and route out. It may select any output contract below, and the smallest valid plan is a few sentences in chat.
+
+**Research, decide, and write the plan — never implement.** Do not write production code, run tests, or learn from execution-time results. Directional pseudo-code and grammar sketches may communicate design; changing code to see what happens belongs in `ce-work`.
+
+## Mandatory Completion Contract
+
+A run is complete when its output contract's done condition is met. Every normal interactive branch that produces a plan artifact or checkpoint is incomplete until the user has been asked what to do next. A request that already authorizes the next action is that answer. For a Durable software implementation-plan run that continues past the resume check, that means the Phase 5.4 menu has been presented and the selected action has actually fired. For Direct, the change stated and the handoff offered; for a Chat brief, the brief and its one-line save-or-`ce-work` offer in chat. Neither presents the Phase 5.4 menu. Non-software plans and approach-level plans end with the handoff their reference workflow defines. A run that only answers a question may end after the answer unless its reference requires a save or share step.
+
+Writing the file, checking confidence, and running or explicitly skipping `ce-doc-review` are intermediate milestones. In pipeline mode, the run is complete only when the plan, the confidence check, and the non-interactive document-review state have been returned to the caller, which decides what happens next.
+
+## Interaction Method
+
+Ask one question at a time through the host's blocking question tool already in the current tool list. Match by capability; never probe a user-facing tool to discover it. If none is listed or a real question call errors, render numbered choices in chat; never silently skip a required question. If no feature description was supplied, ask what to plan and wait.
+
+## Output Contract
+
+Decide which output contract applies at the start of scoping (Phase 0.6), before choosing depth and before the scoping synthesis. It applies only when no resume route (Phase 0.1) fired and the source check (Phase 0.2) found no upstream artifact. Ground it with bounded inline reads of what the request names, without dispatching a subagent. Select one:
+
+- **Direct** — the work can be stated, done, and verified in one pass with no decision the user would weigh. State the change in a few sentences and offer the handoff to `ce-work` or the user; execution starts only with implementation authority, as `references/output-contracts.md` defines.
+- **Chat brief** — bounded work with at most one decision the user would weigh and no risk surface. Deliver it in chat and stop.
+- **Durable** — everything else. Continue the workflow below.
+
+`references/output-contracts.md` defines Direct and Chat brief; read it when either is selected. When the tier is still uncertain after those reads, take the heavier one. If a read surfaces a decision the user would weigh, a risk surface, or multi-pass verification, move to the heavier tier before emitting anything. Durable regardless of size: a run with no synchronous user to act on chat this turn (pipeline, headless, goal- or scheduler-driven), a request whose wording asks for a plan, a plan file, or an output format, a request that continues an existing plan's item, and a risk surface — authentication, payments, migrations, external contracts.
+
+## Workflow
+
+Phases run in order unless a reference routes out or short-circuits. Read a phase's required reference in full when you enter that phase; a read made before that phase does not satisfy it, and a reference named for the final steps is read again at its step even when already in context. If a required reference cannot be read, stop before the action it governs and report the blocker and recovery path; never reconstruct the missing rules from memory. In pipeline mode, every required-reference failure returns `status: blocked`, `phase`, `blocker`, and `recovery_path`; include `artifact_path` and preserve the artifact when one exists. Report blocked even when an artifact exists.
+
+### Phase 0: Output, Resume, and Scope
+
+1. **Output first.** Read `references/output-mode.md` before interpreting any phase. It defines token parsing, output and confirmation precedence, renderer selection, artifact location, and when a repository may be resolved.
+2. **Resume, deepen, approach, and domain.** Read `references/resume.md` before acting. It defines resuming an existing plan, enriching a requirements-only plan, deepening, approach-level planning, and the software/non-software split. Follow any terminal route it selects; otherwise continue.
+3. **Source and scope.** Read `references/intake.md` before Phase 0.2 and follow it through Phase 0.7. It defines finding and preserving the upstream artifact, routing out to bootstrap work, blocking questions, depth, named resources, and the scoping synthesis; the Output Contract decision above happens inside it. Do not pass a decision point that has not resolved.
+
+### Phases 1-4: Research and Compose
+
+4. Read `references/research.md` before gathering context.
+5. Read `references/structure.md` before resolving questions or structuring the plan.
+6. Compose from `references/plan-sections.md` plus the format-rendering reference selected by `output-mode.md`.
+
+### Phase 5: Review, Write, Deepen, and Hand Off
+
+7. Read `references/final-review.md` before the pre-write review; it defines Phase 5.1 through 5.3.2. On an interactive run from a brainstorm, the user sees the Phase 5.1.5 scoping synthesis in chat before the write: a confirmation to wait on, or its one-line auto-proceed announcement.
+8. **Model elevation.** Immediately before authoring, read `references/reasoning-elevation.md`, resolve the choice at this boundary, and follow it. Do not author until activation resolution has completed and any selected dispatch or transparent fallback has settled.
+9. In pipeline mode, evidence that invalidates a decision settled earlier in the session stops the write. Return the exact token `settled-decision-invalidated`, the decision, and the reason; do not resolve it silently.
+10. Write the plan before presenting options, then complete the confidence path `final-review.md` defines.
+
+**STOP. Read `references/plan-handoff.md` immediately before Phase 5.3.8 and 5.4** (document review and the handoff menu). Document review is mandatory for a Durable plan and the default is non-interactive (`mode:non-interactive`). In interactive software runs, ask exactly: "Plan ready at `<absolute path to plan>`. What would you like to do next?" Present its menu and wait. If the selection arrives after a user turn, reload `references/plan-handoff.md` before acting. Rendering the menu, receiving a selection, or announcing a route is not completion; execute the selected action.