create-merlin-brain 3.7.2 → 3.8.0-beta.0

package/files/loop/lib/workflow.sh

@@ -0,0 +1,367 @@
+#!/usr/bin/env bash
+#
+# ╔═══════════════════════════════════════════════════════════════════════════╗
+# ║  MERLIN WORKFLOW ENGINE - Core Engine                                    ║
+# ║  Load, validate, execute steps, manage state                            ║
+# ╚═══════════════════════════════════════════════════════════════════════════╝
+#
+# A thin orchestration layer on top of existing primitives:
+# - Agent selection → blend_for_task() (blend.sh)
+# - Context passing → handoff_append() (blend-handoff.sh)
+# - Verification   → blend_and_verify() (blend-verify.sh)
+# - Parallel steps  → execute_wave_teams() (teams.sh)
+# - Learning       → learn_record() (blend-learn.sh)
+#
+# This file: core engine (load, template, step execution, state)
+# See workflow-run.sh: orchestration (run, resume, status, CLI dispatch)
+#
+# Requires: blend.sh, blend-handoff.sh loaded first
+
+# Colors
+: "${RESET:=\033[0m}"
+: "${BOLD:=\033[1m}"
+: "${DIM:=\033[2m}"
+: "${RED:=\033[31m}"
+: "${GREEN:=\033[32m}"
+: "${YELLOW:=\033[33m}"
+: "${BLUE:=\033[34m}"
+: "${MAGENTA:=\033[35m}"
+: "${CYAN:=\033[36m}"
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Configuration
+# ═══════════════════════════════════════════════════════════════════════════════
+
+WORKFLOW_DIR="${HOME}/.claude/loop/workflows"
+WORKFLOW_BUNDLED_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/workflows"
+WORKFLOW_RUN_FILE="${MERLIN_LOOP_DIR:-.merlin-loop}/workflow-run.json"
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Load & Validate
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Load a workflow definition by ID
+# Returns the JSON content on stdout, errors to stderr
+workflow_load() {
+  local id="$1"
+  local wf_file=""
+
+  # Search order: user dir → bundled dir
+  if [ -f "${WORKFLOW_DIR}/${id}.json" ]; then
+    wf_file="${WORKFLOW_DIR}/${id}.json"
+  elif [ -f "${WORKFLOW_BUNDLED_DIR}/${id}.json" ]; then
+    wf_file="${WORKFLOW_BUNDLED_DIR}/${id}.json"
+  else
+    echo -e "${RED}Workflow '${id}' not found.${RESET}" >&2
+    echo -e "${DIM}Searched: ${WORKFLOW_DIR}/ and ${WORKFLOW_BUNDLED_DIR}/${RESET}" >&2
+    return 1
+  fi
+
+  # Validate: valid JSON with required fields
+  if ! python3 -c "
+import json, sys
+with open('$wf_file') as f:
+    wf = json.load(f)
+assert 'id' in wf, 'Missing id'
+assert 'steps' in wf, 'Missing steps'
+assert len(wf['steps']) > 0, 'No steps defined'
+print(json.dumps(wf))
+" 2>/dev/null; then
+    echo -e "${RED}Invalid workflow definition: ${wf_file}${RESET}" >&2
+    return 1
+  fi
+}
+
+# List all available workflows
+workflow_list() {
+  echo -e "${MAGENTA}${BOLD}  Available Workflows${RESET}"
+  echo -e "${MAGENTA}  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
+
+  local found=0
+  for dir in "$WORKFLOW_BUNDLED_DIR" "$WORKFLOW_DIR"; do
+    [ ! -d "$dir" ] && continue
+    for wf_file in "$dir"/*.json; do
+      [ ! -f "$wf_file" ] && continue
+      found=1
+
+      local id name desc step_count
+      id=$(python3 -c "import json; wf=json.load(open('$wf_file')); print(wf.get('id','?'))" 2>/dev/null)
+      name=$(python3 -c "import json; wf=json.load(open('$wf_file')); print(wf.get('name','?'))" 2>/dev/null)
+      desc=$(python3 -c "import json; wf=json.load(open('$wf_file')); print(wf.get('description',''))" 2>/dev/null)
+      step_count=$(python3 -c "import json; wf=json.load(open('$wf_file')); print(len(wf.get('steps',[])))" 2>/dev/null)
+
+      local source_tag=""
+      [[ "$dir" == "$WORKFLOW_DIR" ]] && source_tag="${CYAN}[user]${RESET}" || source_tag="${DIM}[bundled]${RESET}"
+
+      echo -e "  ${GREEN}${BOLD}${id}${RESET}  ${source_tag}  ${step_count} steps"
+      echo -e "    ${name} — ${DIM}${desc}${RESET}"
+      echo ""
+    done
+  done
+
+  [ "$found" -eq 0 ] && echo -e "  ${DIM}No workflows found. Place .json files in: ${WORKFLOW_DIR}/${RESET}"
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Run Initialization
+# ═══════════════════════════════════════════════════════════════════════════════
+
+workflow_run_init() {
+  local workflow_json="$1"
+  local task="$2"
+
+  local wf_id run_id
+  wf_id=$(echo "$workflow_json" | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])")
+  run_id="${wf_id}-$(date +%s | tail -c 7)"
+
+  mkdir -p "$(dirname "$WORKFLOW_RUN_FILE")"
+
+  python3 << PYEOF
+import json, sys
+from datetime import datetime, timezone
+
+wf = json.loads('''$workflow_json''')
+task = """$task"""
+
+run = {
+    "run_id": "$run_id",
+    "workflow": wf["id"],
+    "workflow_name": wf.get("name", wf["id"]),
+    "task": task,
+    "started": datetime.now(timezone.utc).isoformat(),
+    "status": "running",
+    "current_step": wf["steps"][0]["id"],
+    "steps": {}
+}
+
+for step in wf["steps"]:
+    run["steps"][step["id"]] = {"status": "pending"}
+
+with open("$WORKFLOW_RUN_FILE", 'w') as f:
+    json.dump(run, f, indent=2)
+
+print("$run_id")
+PYEOF
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Template Substitution
+# ═══════════════════════════════════════════════════════════════════════════════
+
+workflow_apply_template() {
+  local template="$1"
+  local task="$2"
+  local handoff_context="$3"
+  local session_dir="$4"
+
+  python3 << PYEOF
+import re, os
+
+template = """$template"""
+task = """$task"""
+handoff = """$handoff_context"""
+session_dir = "$session_dir"
+
+result = template.replace("{{task}}", task).replace("{{handoff}}", handoff)
+
+def replace_file_ref(match):
+    filename = match.group(1)
+    filepath = os.path.join(session_dir, filename)
+    if os.path.isfile(filepath):
+        with open(filepath, 'r') as f:
+            return f.read()
+    return f"[File not found: {filename}]"
+
+result = re.sub(r'\{\{([a-zA-Z0-9_.-]+)\}\}', replace_file_ref, result)
+print(result)
+PYEOF
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Step Execution
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Execute a single workflow step with retry, blend engine, and handoff support
+workflow_step_run() {
+  local step_json="$1"
+  local task="$2"
+  local handoff_context="$3"
+  local session_dir="$4"
+
+  # Parse step fields via single python call for efficiency
+  local step_fields
+  step_fields=$(echo "$step_json" | python3 -c "
+import json, sys
+s = json.load(sys.stdin)
+print(s['id'])
+print(s.get('label', s['id']))
+print(s.get('agent_hint', 'impl'))
+print(s.get('agent_override', ''))
+print(s.get('input_template', '{{task}}\n\n{{handoff}}'))
+print('---FIELD_SEP---')
+print(s.get('expects', ''))
+print(s.get('retry', 1))
+print(s.get('blend', False))
+print(s.get('independent', False))
+print(s.get('parallel', False))
+print(s.get('output_file', ''))
+print(s.get('action', ''))
+")
+
+  local step_id step_label agent_hint agent_override input_template
+  local expects_signal retry_max use_blend is_independent is_parallel output_file action
+
+  step_id=$(echo "$step_fields" | sed -n '1p')
+  step_label=$(echo "$step_fields" | sed -n '2p')
+  agent_hint=$(echo "$step_fields" | sed -n '3p')
+  agent_override=$(echo "$step_fields" | sed -n '4p')
+  # input_template spans lines 5 to the separator
+  input_template=$(echo "$step_fields" | sed -n '5,/---FIELD_SEP---/p' | sed '$d')
+  expects_signal=$(echo "$step_fields" | sed -n '/---FIELD_SEP---/,$ p' | sed -n '2p')
+  retry_max=$(echo "$step_fields" | sed -n '/---FIELD_SEP---/,$ p' | sed -n '3p')
+  use_blend=$(echo "$step_fields" | sed -n '/---FIELD_SEP---/,$ p' | sed -n '4p')
+  is_independent=$(echo "$step_fields" | sed -n '/---FIELD_SEP---/,$ p' | sed -n '5p')
+  is_parallel=$(echo "$step_fields" | sed -n '/---FIELD_SEP---/,$ p' | sed -n '6p')
+  output_file=$(echo "$step_fields" | sed -n '/---FIELD_SEP---/,$ p' | sed -n '7p')
+  action=$(echo "$step_fields" | sed -n '/---FIELD_SEP---/,$ p' | sed -n '8p')
+
+  local prompt
+  prompt=$(workflow_apply_template "$input_template" "$task" "$handoff_context" "$session_dir")
+
+  _workflow_update_step "$step_id" "running"
+
+  local attempt=0 output="" exit_code=1
+
+  while [ "$attempt" -lt "$retry_max" ]; do
+    attempt=$((attempt + 1))
+    echo -e "  ${CYAN}[attempt ${attempt}/${retry_max}]${RESET}" >&2
+
+    # Choose execution method based on step flags
+    if [ "$is_independent" = "True" ] && type blend_and_verify &>/dev/null; then
+      output=$(blend_and_verify "$prompt" "" "$session_dir/step-${step_id}")
+      exit_code=$?
+    elif [ "$is_parallel" = "True" ] && type execute_wave_teams &>/dev/null && teams_enabled 2>/dev/null; then
+      output=$(blend_and_spawn "$prompt" "" "$session_dir/step-${step_id}")
+      exit_code=$?
+    elif [ -n "$agent_override" ] && [ "$use_blend" != "True" ]; then
+      local agent_path="${HOME}/.claude/agents/${agent_override}.md"
+      if [ -f "$agent_path" ]; then
+        output=$(echo "$prompt" | claude --agent "$agent_override" -p --permission-mode acceptEdits --output-format text 2>&1)
+        exit_code=$?
+      else
+        output=$(blend_and_spawn "$prompt" "" "$session_dir/step-${step_id}" 2>/dev/null || echo "$prompt" | claude -p --output-format text 2>&1)
+        exit_code=$?
+      fi
+    elif type blend_and_spawn &>/dev/null; then
+      output=$(blend_and_spawn "$prompt" "" "$session_dir/step-${step_id}")
+      exit_code=$?
+    else
+      output=$(echo "$prompt" | claude -p --output-format text 2>&1)
+      exit_code=$?
+    fi
+
+    # Check expects signal
+    if [ $exit_code -eq 0 ]; then
+      if [ -z "$expects_signal" ] || echo "$output" | grep -qi "$expects_signal"; then
+        break
+      else
+        echo -e "  ${YELLOW}Expected signal '${expects_signal}' not found, retrying...${RESET}" >&2
+        exit_code=1
+      fi
+    fi
+  done
+
+  # Save output file if specified
+  [ -n "$output_file" ] && [ $exit_code -eq 0 ] && echo "$output" > "$session_dir/$output_file"
+
+  # Update handoff chain
+  if type handoff_append &>/dev/null && [ -f "$session_dir/handoff.json" ]; then
+    handoff_append "$session_dir/handoff.json" "$step_id" "$output"
+  fi
+
+  # Run post-step action
+  [ $exit_code -eq 0 ] && [ -n "$action" ] && _workflow_run_action "$action" "$output" "$session_dir"
+
+  # Update run state
+  [ $exit_code -eq 0 ] && _workflow_update_step "$step_id" "done" "$attempt" || _workflow_update_step "$step_id" "failed" "$attempt"
+
+  echo "$output"
+  return $exit_code
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# State Management
+# ═══════════════════════════════════════════════════════════════════════════════
+
+_workflow_update_step() {
+  local step_id="$1"
+  local status="$2"
+  local attempts="${3:-1}"
+
+  [ ! -f "$WORKFLOW_RUN_FILE" ] && return
+
+  python3 << PYEOF
+import json
+from datetime import datetime, timezone
+
+with open("$WORKFLOW_RUN_FILE", 'r') as f:
+    run = json.load(f)
+
+step = run["steps"].get("$step_id", {})
+step["status"] = "$status"
+step["attempts"] = $attempts
+
+if "$status" == "running":
+    step["started"] = datetime.now(timezone.utc).isoformat()
+elif "$status" in ("done", "failed", "skipped"):
+    step["completed"] = datetime.now(timezone.utc).isoformat()
+
+run["steps"]["$step_id"] = step
+
+if "$status" == "done":
+    wf_steps = list(run["steps"].keys())
+    idx = wf_steps.index("$step_id") if "$step_id" in wf_steps else -1
+    if idx >= 0 and idx + 1 < len(wf_steps):
+        run["current_step"] = wf_steps[idx + 1]
+    else:
+        run["current_step"] = None
+        run["status"] = "completed"
+elif "$status" == "failed":
+    run["status"] = "failed"
+
+with open("$WORKFLOW_RUN_FILE", 'w') as f:
+    json.dump(run, f, indent=2)
+PYEOF
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Post-Step Actions
+# ═══════════════════════════════════════════════════════════════════════════════
+
+_workflow_run_action() {
+  local action="$1"
+  local output="$2"
+  local session_dir="$3"
+
+  case "$action" in
+    gh_pr_create)
+      echo -e "${CYAN}  Action: Create PR${RESET}" >&2
+      echo "$output" | grep -qi "pull request\|PR created\|pr/" || \
+        echo -e "${YELLOW}  PR may not have been created. Check manually.${RESET}" >&2
+      ;;
+    git_commit)
+      echo -e "${CYAN}  Action: Git commit${RESET}" >&2
+      git add -A && git commit -m "workflow: auto-commit from step" 2>/dev/null || true
+      ;;
+    notify)
+      type send_notification &>/dev/null && send_notification "Workflow Step Complete" "Step finished"
+      ;;
+  esac
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Load orchestration module
+# ═══════════════════════════════════════════════════════════════════════════════
+
+_WORKFLOW_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${_WORKFLOW_LIB_DIR}/workflow-run.sh" 2>/dev/null || true

package/files/loop/merlin-loop.sh

@@ -47,6 +47,7 @@ source "$SCRIPT_DIR/lib/teams.sh" 2>/dev/null || true      # Agent Teams integra
 # Stage 2: blend-parallel.sh — Parallel Agent Execution
 # Stage 3: blend-handoff.sh  — Structured Handoffs
 # Stage 4: blend-learn.sh    — Blend Learning
+source "$SCRIPT_DIR/lib/workflow.sh" 2>/dev/null || true    # Workflow engine (multi-agent pipelines)
 source "$SCRIPT_DIR/lib/boot.sh" 2>/dev/null || true        # Boot sequence
 source "$SCRIPT_DIR/lib/session-end.sh" 2>/dev/null || true # Session end protocol
 source "$SCRIPT_DIR/lib/tui.sh" 2>/dev/null || true         # Interactive TUI
@@ -769,6 +770,13 @@ usage() {
   echo "  status     Show current loop status"
   echo "  reset      Reset loop state (keeps history)"
   echo ""
+  echo "  workflow list                         List available workflows"
+  echo "  workflow run <id> \"<task>\"             Run a named workflow"
+  echo "  workflow status                       Show workflow run progress"
+  echo "  workflow resume                       Resume interrupted workflow"
+  echo "  workflow skip                         Skip current step and advance"
+  echo "  workflow install <url|file>           Install community workflow"
+  echo ""
   echo "Options:"
   echo "  --mode MODE     Loop mode: auto, interactive, hybrid (default: hybrid)"
   echo "                    auto        - Only pause on explicit checkpoints"
@@ -792,6 +800,11 @@ usage() {
   echo "  merlin-loop --max 100 build         # Allow up to 100 iterations"
   echo "  merlin-loop --teams build           # Parallel wave execution (experimental)"
   echo "  merlin-loop --afk auto              # Run unattended (auto mode)"
+  echo ""
+  echo "  merlin-loop workflow list            # See available workflows"
+  echo "  merlin-loop workflow run feature-dev \"Add OAuth\" # Run a workflow"
+  echo "  merlin-loop workflow status          # Check progress"
+  echo "  merlin-loop workflow resume          # Resume after failure"
 }
 
 parse_args() {
@@ -854,6 +867,13 @@ parse_args() {
         COMMAND="$1"
         shift
         ;;
+      workflow)
+        COMMAND="workflow"
+        shift
+        # Capture remaining args for workflow subcommand
+        WORKFLOW_ARGS=("$@")
+        break
+        ;;
       -h|--help)
         usage
         exit 0
@@ -869,6 +889,7 @@ parse_args() {
 
 main() {
   COMMAND="${COMMAND:-auto}"
+  WORKFLOW_ARGS=()
 
   parse_args "$@"
 
@@ -904,6 +925,15 @@ main() {
       reset_state
       echo -e "${GREEN}Loop state reset${RESET}"
       ;;
+    workflow)
+      merlin_banner
+      if type workflow_dispatch &>/dev/null; then
+        workflow_dispatch "${WORKFLOW_ARGS[@]}"
+      else
+        echo -e "${RED}Workflow engine not available. Check lib/workflow.sh${RESET}"
+        exit 1
+      fi
+      ;;
     *)
       usage
       exit 1

package/files/loop/workflows/bug-fix.json

@@ -0,0 +1,64 @@
+{
+  "id": "bug-fix",
+  "name": "Bug Fix",
+  "description": "Report a bug. Get back a fix with regression test and PR.",
+  "version": "1.0",
+  "steps": [
+    {
+      "id": "triage",
+      "label": "Triage & Reproduce",
+      "agent_hint": "debug",
+      "input_template": "Triage this bug report and reproduce it:\n\n{{task}}\n\nSteps:\n1. Understand the reported behavior\n2. Find the relevant code\n3. Reproduce the issue (or confirm from code analysis)\n4. Identify root cause vs symptoms\n5. Assess severity and blast radius\n\nOutput TRIAGE_COMPLETE with root cause analysis.",
+      "expects": "TRIAGE_COMPLETE",
+      "output_file": "triage.md",
+      "retry": 2
+    },
+    {
+      "id": "investigate",
+      "label": "Deep Investigation",
+      "agent_hint": "debug",
+      "input_template": "Deep-dive into the root cause identified in triage:\n\n{{triage.md}}\n\nPrevious context:\n{{handoff}}\n\nTrace the exact code path. Identify all affected branches. Find related bugs that might share the same root cause.\n\nOutput INVESTIGATION_COMPLETE with fix strategy.",
+      "expects": "INVESTIGATION_COMPLETE",
+      "output_file": "investigation.md",
+      "retry": 1
+    },
+    {
+      "id": "fix",
+      "label": "Apply Fix",
+      "agent_hint": "impl",
+      "input_template": "Apply the fix based on investigation:\n\n{{investigation.md}}\n\nPrevious context:\n{{handoff}}\n\nFix the root cause, not just the symptom. Keep changes minimal and focused. Commit atomically.\n\nOutput FIX_COMPLETE when the fix is applied.",
+      "expects": "FIX_COMPLETE",
+      "retry": 2,
+      "blend": true
+    },
+    {
+      "id": "regression-test",
+      "label": "Regression Test",
+      "agent_hint": "test",
+      "input_template": "Write a regression test that:\n1. Fails WITHOUT the fix (proves the bug existed)\n2. Passes WITH the fix (proves the fix works)\n3. Covers edge cases identified in investigation\n\nContext:\n{{handoff}}\n\nOutput TESTS_PASS when regression test passes.",
+      "expects": "TESTS_PASS",
+      "retry": 2
+    },
+    {
+      "id": "verify",
+      "label": "Independent Verification",
+      "agent_hint": "architect",
+      "agent_override": "merlin-verifier",
+      "input_template": "Verify this bug fix cold. Check:\n- Fix addresses root cause (not just symptom)\n- No regressions introduced\n- Edge cases handled\n- Test coverage adequate\n\nContext:\n{{handoff}}\n\nOutput VERIFIED when review passes.",
+      "expects": "VERIFIED",
+      "independent": true,
+      "retry": 1
+    },
+    {
+      "id": "pr",
+      "label": "Pull Request",
+      "agent_hint": "impl",
+      "input_template": "Create a PR for this bug fix.\n\nContext:\n{{handoff}}\n\nPR should reference the bug, explain root cause, and describe the fix. Include before/after behavior.\n\nOutput PR_CREATED when done.",
+      "expects": "PR_CREATED",
+      "action": "gh_pr_create",
+      "retry": 1
+    }
+  ],
+  "on_failure": "pause",
+  "on_complete": "notify"
+}

package/files/loop/workflows/feature-dev.json

@@ -0,0 +1,73 @@
+{
+  "id": "feature-dev",
+  "name": "Feature Development",
+  "description": "Drop in a feature request. Get back a tested PR.",
+  "version": "1.0",
+  "steps": [
+    {
+      "id": "plan",
+      "label": "Planning",
+      "agent_hint": "spec",
+      "agent_override": "merlin-planner",
+      "input_template": "Create a detailed implementation plan for: {{task}}\n\nInclude: file changes, acceptance criteria, edge cases, and testing strategy.\n\nOutput PLAN_COMPLETE when done.",
+      "expects": "PLAN_COMPLETE",
+      "output_file": "plan.md",
+      "retry": 2
+    },
+    {
+      "id": "setup",
+      "label": "Environment Setup",
+      "agent_hint": "architect",
+      "input_template": "Set up environment and scaffolding for this plan:\n\n{{plan.md}}\n\nCreate any new files, install dependencies, set up config.\nHandoff context:\n{{handoff}}\n\nOutput SETUP_COMPLETE when done.",
+      "expects": "SETUP_COMPLETE",
+      "retry": 1
+    },
+    {
+      "id": "implement",
+      "label": "Implementation",
+      "agent_hint": "impl",
+      "input_template": "Implement according to this plan:\n\n{{plan.md}}\n\nPrevious context:\n{{handoff}}\n\nFollow existing patterns. Keep files under 400 lines. Commit after each logical change.\n\nOutput IMPL_COMPLETE when done.",
+      "expects": "IMPL_COMPLETE",
+      "retry": 3,
+      "blend": true
+    },
+    {
+      "id": "verify",
+      "label": "Independent Verification",
+      "agent_hint": "architect",
+      "agent_override": "merlin-verifier",
+      "input_template": "Review this implementation cold. Do not read the original task. Only evaluate the code quality, correctness, and completeness based on:\n\n{{handoff}}\n\nCheck files changed, look for bugs, missing error handling, security issues.\n\nOutput VERIFIED when review is complete.",
+      "expects": "VERIFIED",
+      "independent": true,
+      "retry": 1
+    },
+    {
+      "id": "test",
+      "label": "Testing",
+      "agent_hint": "test",
+      "input_template": "Write and run tests for the work described in:\n\n{{handoff}}\n\nWrite unit tests for core logic. Write integration tests for API endpoints. Ensure all tests pass.\n\nOutput TESTS_PASS when all tests pass.",
+      "expects": "TESTS_PASS",
+      "retry": 2
+    },
+    {
+      "id": "pr",
+      "label": "Pull Request",
+      "agent_hint": "impl",
+      "input_template": "Create a PR for the completed work.\n\nContext:\n{{handoff}}\n\nWrite a clear PR title and description summarizing all changes. Use `gh pr create`.\n\nOutput PR_CREATED when the PR is created.",
+      "expects": "PR_CREATED",
+      "action": "gh_pr_create",
+      "retry": 1
+    },
+    {
+      "id": "review",
+      "label": "Final Review",
+      "agent_hint": "spec",
+      "agent_override": "merlin-milestone-auditor",
+      "input_template": "Audit the completed work. Verify all acceptance criteria from the original plan are met.\n\nContext:\n{{handoff}}\n\nOriginal task: {{task}}\n\nCheck each criterion against actual code. Report gaps if any.\n\nOutput APPROVED if all criteria met.",
+      "expects": "APPROVED",
+      "retry": 1
+    }
+  ],
+  "on_failure": "pause",
+  "on_complete": "notify"
+}

package/files/loop/workflows/refactor.json

@@ -0,0 +1,64 @@
+{
+  "id": "refactor",
+  "name": "Code Refactor",
+  "description": "Analyze, plan, refactor, verify, test, and PR. Clean code pipeline.",
+  "version": "1.0",
+  "steps": [
+    {
+      "id": "analyze",
+      "label": "Code Analysis",
+      "agent_hint": "refactor",
+      "input_template": "Analyze the codebase for refactoring opportunities:\n\n{{task}}\n\nLook for:\n- Files over 400 lines\n- Duplicated code patterns\n- God objects / functions doing too much\n- Circular dependencies\n- Dead code\n- Inconsistent patterns\n- Missing abstractions\n\nProduce a detailed analysis with specific file paths and line counts.\n\nOutput ANALYSIS_COMPLETE with findings.",
+      "expects": "ANALYSIS_COMPLETE",
+      "output_file": "analysis.md",
+      "retry": 1
+    },
+    {
+      "id": "plan",
+      "label": "Refactor Plan",
+      "agent_hint": "architect",
+      "input_template": "Create a safe refactoring plan based on analysis:\n\n{{analysis.md}}\n\nPrevious context:\n{{handoff}}\n\nFor each refactoring:\n1. What changes (specific files and functions)\n2. Why it improves the code\n3. Risk level (low/medium/high)\n4. Order (safest first, riskiest last)\n\nEnsure each step is atomic and independently testable.\n\nOutput PLAN_COMPLETE with ordered refactoring steps.",
+      "expects": "PLAN_COMPLETE",
+      "output_file": "refactor-plan.md",
+      "retry": 1
+    },
+    {
+      "id": "refactor",
+      "label": "Apply Refactoring",
+      "agent_hint": "refactor",
+      "input_template": "Execute the refactoring plan:\n\n{{refactor-plan.md}}\n\nPrevious context:\n{{handoff}}\n\nRules:\n- One atomic commit per refactoring step\n- Run existing tests after each step\n- If tests break, fix before moving on\n- Keep files under 400 lines\n- Preserve all existing behavior\n\nOutput REFACTOR_COMPLETE when all steps done.",
+      "expects": "REFACTOR_COMPLETE",
+      "retry": 3,
+      "blend": true
+    },
+    {
+      "id": "verify",
+      "label": "Behavior Verification",
+      "agent_hint": "architect",
+      "agent_override": "merlin-verifier",
+      "input_template": "Verify that refactoring preserved all behavior.\n\nReview the changes cold — do not read the refactor plan.\nCheck:\n- No behavior changes (only structural)\n- All public APIs unchanged\n- No missing imports or broken references\n- Tests still pass\n\nContext:\n{{handoff}}\n\nOutput VERIFIED if behavior is preserved.",
+      "expects": "VERIFIED",
+      "independent": true,
+      "retry": 1
+    },
+    {
+      "id": "test",
+      "label": "Test Suite",
+      "agent_hint": "test",
+      "input_template": "Run the full test suite and add tests for any untested refactored code:\n\nContext:\n{{handoff}}\n\n1. Run all existing tests — they MUST pass\n2. Add tests for newly extracted functions/modules\n3. Verify test coverage didn't decrease\n\nOutput TESTS_PASS when all tests pass.",
+      "expects": "TESTS_PASS",
+      "retry": 2
+    },
+    {
+      "id": "pr",
+      "label": "Refactor PR",
+      "agent_hint": "impl",
+      "input_template": "Create a PR for the refactoring work.\n\nContext:\n{{handoff}}\n\nPR should explain:\n- What was refactored and why\n- Key structural changes\n- That all tests pass and behavior is preserved\n\nOutput PR_CREATED when done.",
+      "expects": "PR_CREATED",
+      "action": "gh_pr_create",
+      "retry": 1
+    }
+  ],
+  "on_failure": "pause",
+  "on_complete": "notify"
+}