skill-orchestrate-hard

name	skill-orchestrate-hard
description	Full structural hard-mode orchestration state machine with per-phase dispatch (H1), adversarial verification (H4), convergence policing (H6), territory contracts (H7), and churn detection (H5). Invoke for /orchestrate --hard.
allowed-tools	Agent, Bash, Read, Edit

Orchestrate Hard Skill

IMPORTANT: This is a FULL STRUCTURAL VARIANT, not a thin wrapper over skill-orchestrate. Loop-level changes (per-phase dispatch, churn detection, adversarial verification gate) cannot be expressed as prompt injection into the base skill. Maintenance: both skills should evolve together -- changes to escalation ladder and handoff schema in skill-orchestrate should be reflected here.

Hard-mode additions over base skill-orchestrate:

• H1 Per-Phase Dispatch: Each implement cycle dispatches exactly one phase, not the whole plan
• H4 Adversarial Verification Gate: Research output is verified before plan/implement dispatch
• H5 Divergence Audit: Three-strikes on any target triggers a dedicated audit research dispatch
• H6 Convergence Policing: Churn detection with per-target counters (defect_claims, sorry_relocations)
• H7 Territory Contracts: Parallel phase waves get explicit file territory in their dispatch context

Context References

Architecture documentation (load as needed):

• .claude/context/contracts/convergence.md - H6 convergence policing rules
• .claude/context/contracts/territory.md - H7 territory contract for parallel dispatch
• .claude/context/contracts/anti-analysis.md - H2 contract injected into each implement dispatch
• .claude/context/contracts/wrap-up.md - H9 contract for handoff discipline
• .claude/docs/architecture/orchestrate-state-machine.md - Base state table (reference)
• .claude/docs/architecture/handoff-schema.md - Handoff JSON schema

---

Execution Flow

Stage 0: Multi-Task Mode Detection

Same as base skill-orchestrate. Parse multi_task_mode. If true, use base multi-task stages (per-phase dispatch applies to each task independently within the wave).

source .claude/scripts/skill-base.sh
multi_task_mode=$(echo "$delegation_context" | jq -r '.multi_task_mode // false')
session_id=$(echo "$delegation_context" | jq -r '.session_id')
focus_prompt=$(echo "$delegation_context" | jq -r '.focus_prompt // ""')
effort_flag=$(echo "$delegation_context" | jq -r '.effort_flag // "hard"')

---

Stage 1: Input Validation

task_number=$(echo "$delegation_context" | jq -r '.task_context.task_number')
PADDED_NUM=$(printf "%03d" "$task_number")
TASK_DATA=$(jq -r --argjson num "$task_number" \
  '.active_projects[] | select(.project_number == $num)' \
  specs/state.json)

if [ -z "$TASK_DATA" ]; then
  echo "ERROR: Task $task_number not found in state.json" >&2
  exit 1
fi

PROJECT_NAME=$(echo "$TASK_DATA" | jq -r '.project_name')
TASK_TYPE=$(echo "$TASK_DATA" | jq -r '.task_type // "general"')
DESCRIPTION=$(echo "$TASK_DATA" | jq -r '.description // ""')
TASK_DIR="specs/${PADDED_NUM}_${PROJECT_NAME}"

---

Stage 1b: Resolve Hard-Mode Agent Routing

Map task_type to hard-mode research and implementation agents.

# Default to hard-mode variants; fall back to base agents if hard variant doesn't exist
case "$TASK_TYPE" in
  lean4|lean)
    RESEARCH_AGENT="lean-research-hard-agent"
    IMPLEMENT_AGENT="lean-implementation-hard-agent"
    PLANNER_AGENT="planner-hard-agent"
    # Verify hard variants exist, fall back if not
    [ ! -f ".claude/agents/${RESEARCH_AGENT}.md" ] && RESEARCH_AGENT="lean-research-agent"
    [ ! -f ".claude/agents/${IMPLEMENT_AGENT}.md" ] && IMPLEMENT_AGENT="lean-implementation-agent"
    ;;
  neovim)
    RESEARCH_AGENT="general-research-hard-agent"
    IMPLEMENT_AGENT="general-implementation-hard-agent"
    PLANNER_AGENT="planner-hard-agent"
    ;;
  nix)
    RESEARCH_AGENT="general-research-hard-agent"
    IMPLEMENT_AGENT="general-implementation-hard-agent"
    PLANNER_AGENT="planner-hard-agent"
    ;;
  *)
    RESEARCH_AGENT="general-research-hard-agent"
    IMPLEMENT_AGENT="general-implementation-hard-agent"
    PLANNER_AGENT="planner-hard-agent"
    ;;
esac

# Check routing_hard extension manifests for overrides
for manifest in .claude/extensions/*/manifest.json; do
  if [ -f "$manifest" ]; then
    ext_hard_research=$(jq -r --arg tt "$TASK_TYPE" '.routing_hard.research[$tt] // empty' "$manifest" 2>/dev/null)
    ext_hard_implement=$(jq -r --arg tt "$TASK_TYPE" '.routing_hard.implement[$tt] // empty' "$manifest" 2>/dev/null)
    if [ -n "$ext_hard_research" ]; then
      RESEARCH_AGENT=$(echo "$ext_hard_research" | sed 's/^skill-//' | sed 's/$/-agent/')
    fi
    if [ -n "$ext_hard_implement" ]; then
      IMPLEMENT_AGENT=$(echo "$ext_hard_implement" | sed 's/^skill-//' | sed 's/$/-agent/')
    fi
  fi
done

echo "[hard-orchestrate] Routing: research=$RESEARCH_AGENT, implement=$IMPLEMENT_AGENT, plan=$PLANNER_AGENT"

---

Stage 2: Preflight — Loop Guard and Churn State

Create or read the loop guard file with hard-mode churn counters.

MAX_CYCLES=13
loop_guard_file="${TASK_DIR}/.orchestrator-loop-guard"
handoff_file="${TASK_DIR}/.orchestrator-handoff.json"
churn_file="${TASK_DIR}/.orchestrator-churn-state.json"

mkdir -p "$TASK_DIR"

if [ -f "$loop_guard_file" ] && jq empty "$loop_guard_file" 2>/dev/null; then
  cycle_count=$(jq -r '.cycle_count // 0' "$loop_guard_file")
  echo "[hard-orchestrate] Resuming — cycle $cycle_count of $MAX_CYCLES"
else
  cycle_count=0
  jq -n \
    --arg session_id "$session_id" \
    --argjson max_cycles "$MAX_CYCLES" \
    --arg started "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
    '{
      "session_id": $session_id,
      "cycle_count": 0,
      "max_cycles": $max_cycles,
      "current_state": "reading",
      "hard_mode": true,
      "started": $started,
      "last_updated": $started
    }' > "$loop_guard_file"
fi

# Initialize or read churn state (per-target churn counters)
if [ -f "$churn_file" ] && jq empty "$churn_file" 2>/dev/null; then
  total_churn=$(jq -r '.total_churn // 0' "$churn_file")
else
  jq -n '{"total_churn": 0, "target_churn": {}, "adversarial_triggers": 0, "audit_dispatches": 0}' > "$churn_file"
  total_churn=0
fi

blocker_escalation_count=0
MAX_BLOCKER_ESCALATIONS=2
adversarial_verified=false

Note: MAX_CYCLES is increased from 5 to 13 in hard mode to accommodate per-phase dispatch. Each phase requires its own cycle; a 7-phase plan needs ~7 cycles minimum.

---

Stage 3: State Machine Loop

while [ "$cycle_count" -lt "$MAX_CYCLES" ]; do

At the top of each iteration:

3a. Read current task status

current_status=$(jq -r --argjson num "$task_number" \
  '.active_projects[] | select(.project_number == $num) | .status' \
  specs/state.json)
echo "[hard-orchestrate] Cycle $((cycle_count + 1))/$MAX_CYCLES — status: $current_status"

3b. Update loop guard

jq --arg state "$current_status" \
   --arg updated "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
   --argjson count "$cycle_count" \
  '.current_state = $state | .last_updated = $updated | .cycle_count = $count' \
  "$loop_guard_file" > "${loop_guard_file}.tmp" && mv "${loop_guard_file}.tmp" "$loop_guard_file"

---

Stage 4: State Handlers

State: not_started

Dispatch research via hard-mode research agent.

Agent tool:
  subagent_type: $RESEARCH_AGENT
  prompt: "Research task $task_number: $DESCRIPTION${focus_prompt:+. Focus: $focus_prompt}"
  delegation_context: {task_number, session_id, effort_flag: "hard", orchestrator_mode: false}

After Agent tool returns: read handoff (Stage 5). Set adversarial_verified=false. Increment cycle_count.

State: researching

In-flight. Exit with warning (another session is researching). Same as base skill.

State: researched — WITH Adversarial Verification Gate (H4)

HARD MODE DIFFERS FROM BASE: Before dispatching planning, verify the research report.

# H4: Adversarial verification gate
if [ "$adversarial_verified" = "false" ]; then
  echo "[hard-orchestrate] H4: Dispatching adversarial verification before planning" >&2
  research_path=$(jq -r --argjson num "$task_number" \
    '[.active_projects[] | select(.project_number == $num) | .artifacts // [] | .[] | select(.type == "report")] | .[0].path // ""' \
    specs/state.json)

  if [ -n "$research_path" ] && [ -f "$research_path" ]; then
    # Check if adversarial verification section already exists in report
    if grep -q "## Adversarial Self-Verification" "$research_path"; then
      echo "[hard-orchestrate] H4: Adversarial verification section found in report. Proceeding to planning." >&2
      adversarial_verified=true
    else
      # Dispatch a focused verification research pass
      Agent tool:
        subagent_type: $RESEARCH_AGENT
        prompt: "Adversarial verification pass for task $task_number. Read the research report at $research_path and verify all load-bearing claims. Focus: divergence audit — check for analysis-paralysis signatures, verify source citations, flag uncertain claims."
        delegation_context: {task_number, session_id, effort_flag: "hard", focus_prompt: "divergence audit"}
      Increment cycle_count. Loop continues.
    fi
  else
    adversarial_verified=true  # No report to verify; proceed
  fi
fi

# After verification: dispatch planning
if [ "$adversarial_verified" = "true" ]; then
  Agent tool:
    subagent_type: $PLANNER_AGENT
    prompt: "Create hard-mode implementation plan for task $task_number${focus_prompt:+. Focus: $focus_prompt}"
    delegation_context: {task_number, session_id, effort_flag: "hard", orchestrator_mode: false, ...}
fi

State: planning

In-flight. Exit with warning. Same as base skill.

State: planned or implementing — Per-Phase Dispatch (H1)

HARD MODE DIFFERS FROM BASE: Dispatch exactly one phase per cycle.

plan_path=$(ls -1 "${TASK_DIR}/plans/"*.md 2>/dev/null | sort -V | tail -1)

# Read current handoff to determine next phase
if [ -f "$handoff_file" ]; then
  phases_completed=$(jq -r '.phases_completed // 0' "$handoff_file")
  phases_total=$(jq -r '.phases_total // 0' "$handoff_file")
else
  phases_completed=0
  phases_total=0
fi

next_phase=$((phases_completed + 1))

# Determine territory for this phase (single-phase dispatch, no parallel territory needed)
# Territory becomes relevant for parallel wave dispatch (see Stage 4c: Parallel Waves)
dispatch_context='{
  "task_number": '$task_number',
  "task_type": "'$TASK_TYPE'",
  "session_id": "'$session_id'",
  "orchestrator_mode": true,
  "effort_flag": "hard",
  "plan_path": "'$plan_path'",
  "phase_number": '$next_phase'
}'

echo "[hard-orchestrate] H1: Per-phase dispatch — phase $next_phase" >&2

Agent tool:
  subagent_type: $IMPLEMENT_AGENT
  prompt: "Implement phase $next_phase of task $task_number. $(build_hard_mode_prompt_context)"
  delegation_context: $dispatch_context

Hard-mode prompt context (built inline):

build_hard_mode_prompt_context() {
  echo "
HARD MODE DISPATCH — CONTRACT SLOTS:

1. Mission: Implement phase $next_phase only. Do not continue past this phase.
2. Anti-Analysis Rules: Read .claude/context/contracts/anti-analysis.md. First file edit within 20% of tool calls.
3. Wrap-up Contract: Write .orchestrator-handoff.json before terminating. Incremental commits.
4. Settled Design Preamble: State the decided design before first tool call.

PHASES COMPLETED: $phases_completed of $phases_total
"
}

After dispatch: read handoff (Stage 5). Check churn state (Stage 4b). Increment cycle_count.

State: planned or implementing — Parallel Wave Dispatch (optional H7)

When the plan has phases in the same dependency wave that can run in parallel:

# Read plan's wave map (from Dependency Analysis table in plan)
# If multiple phases are in the current wave and all their predecessors are COMPLETED:
if [ "$parallel_wave_size" -gt 1 ]; then
  echo "[hard-orchestrate] H7: Parallel wave dispatch — $parallel_wave_size phases" >&2

  # Build territory for each phase
  for phase in "${wave_phases[@]}"; do
    territory=$(build_phase_territory "$plan_path" "$phase")
    # Dispatch each phase with territory contract
    Agent tool:
      subagent_type: $IMPLEMENT_AGENT
      prompt: "Implement phase $phase (parallel wave). Territory: $territory. $(build_hard_mode_prompt_context)"
      delegation_context: {..., phase_number: $phase, territory: $territory}
  done
  # NOTE: Parallel dispatch via multiple simultaneous Agent tool calls
fi

Territory building: Extract the files listed under each phase in the plan and assign them as owned_files. Other plan phases' files become read_only_files.

State: partial

Read handoff to determine sub-state:

handoff=$(cat "$handoff_file" 2>/dev/null || echo '{}')
blockers=$(echo "$handoff" | jq -c '.blockers // []')
continuation=$(echo "$handoff" | jq -r '.continuation_path // null')
blocker_count=$(echo "$blockers" | jq 'length')
phases_completed=$(echo "$handoff" | jq -r '.phases_completed // 0')
phases_total=$(echo "$handoff" | jq -r '.phases_total // 0')

Sub-state: continuation available (continuation != null):

Dispatch implement with continuation context (per-phase, H1).

Sub-state: blockers present (blocker_count > 0):

Check churn counters BEFORE escalating (Stage 4b may have already handled this). If not at three-strikes threshold, invoke blocker escalation (Stage 6).

Sub-state: no handoff, no blockers:

echo "[hard-orchestrate] Task $task_number: partial state with no continuation. Cycle limit may have been reached."
EXIT (partial)

State: pr_ready

echo "[hard-orchestrate] Task $task_number is PR READY — use /merge to submit the pull request."
rm -f "$loop_guard_file"
EXIT (success, pr_ready)

State: blocked

Read blockers from state.json. Invoke blocker escalation (Stage 6).

State: completed

echo "[hard-orchestrate] Task $task_number completed."
rm -f "$loop_guard_file"
EXIT (success)

---

Stage 4b: Churn Detection (H6) — After Each Implement Dispatch

After every implement dispatch, check the handoff for churn signatures:

# Read updated churn state
total_churn=$(jq -r '.total_churn // 0' "$churn_file")

# Check for churn signatures in handoff
handoff_status=$(echo "$handoff" | jq -r '.status')
has_blockers=$(echo "$handoff" | jq '.blockers | length > 0')
phases_delta=$((phases_completed_after - phases_completed_before))

if [ "$handoff_status" = "partial" ] && [ "$has_blockers" = "true" ] && [ "$phases_delta" -eq 0 ]; then
  # No progress: churn signature
  blocker_target=$(echo "$handoff" | jq -r '.blockers[0].target // "unknown"')
  current_target_churn=$(jq -r --arg target "$blocker_target" \
    '.target_churn[$target] // 0' "$churn_file")
  new_target_churn=$((current_target_churn + 1))

  # Update churn counters
  jq --arg target "$blocker_target" \
     --argjson count "$new_target_churn" \
     --argjson total "$((total_churn + 1))" \
    '.target_churn[$target] = $count | .total_churn = $total' \
    "$churn_file" > "${churn_file}.tmp" && mv "${churn_file}.tmp" "$churn_file"

  echo "[hard-orchestrate] H6: Churn detected on '$blocker_target' (count: $new_target_churn)" >&2

  # Three-strikes: dispatch divergence audit instead of another implement
  if [ "$new_target_churn" -ge 3 ]; then
    echo "[hard-orchestrate] H5: Three-strikes — dispatching divergence audit for '$blocker_target'" >&2
    verbatim_goal=$(echo "$handoff" | jq -r '.blockers[0].verbatim_goal // ""')

    Agent tool:
      subagent_type: $RESEARCH_AGENT
      prompt: "DIVERGENCE AUDIT for task $task_number. Target: '$blocker_target'. Verbatim goal: '$verbatim_goal'. This target has failed 3 times. Identify root cause of repeated failure. Write a divergence table, postmortem, and corrected target definition."
      delegation_context: {task_number, session_id, effort_flag: "hard", focus_prompt: "divergence audit $blocker_target"}

    # Reset churn counter for this target after audit
    jq --arg target "$blocker_target" \
      '.target_churn[$target] = 0 | .audit_dispatches += 1' \
      "$churn_file" > "${churn_file}.tmp" && mv "${churn_file}.tmp" "$churn_file"

    Increment cycle_count. Loop continues (next iteration will re-dispatch implement with audit findings).
  fi
fi

---

Stage 5: Handoff Reading (after each dispatch)

Same as base skill-orchestrate Stage 5, plus:

# Additional hard-mode handoff fields
sorry_inventory=$(echo "$handoff" | jq -c '.sorry_inventory // []')
if [ "$(echo "$sorry_inventory" | jq 'length')" -gt 0 ]; then
  echo "[hard-orchestrate] Sorry inventory: $(echo "$sorry_inventory" | jq 'length') sorrys" >&2
fi

---

Stage 6: Blocker Escalation

Extended escalation ladder (same as base + audit step):

1. Standard dispatch (handled in Stage 4)
2. On 3 churn strikes: Divergence audit (Stage 4b, H5)
3. After audit: Revised dispatch with audit findings
4. If still blocked: AskUserQuestion for architectural decision
5. If 2nd authorization fails: Mark phase BLOCKED, continue with other phases

When escalation is invoked:

if [ "$blocker_escalation_count" -lt "$MAX_BLOCKER_ESCALATIONS" ]; then
  blocker_escalation_count=$((blocker_escalation_count + 1))

  # Escalate to blocker research
  blocker_desc=$(echo "$handoff" | jq -r '.blockers[0].verbatim_goal // "Unspecified blocker"')
  Agent tool:
    subagent_type: $RESEARCH_AGENT
    prompt: "Research blocker for task $task_number: $blocker_desc. Find a concrete resolution path."
    delegation_context: {task_number, session_id, effort_flag: "hard", focus_prompt: "blocker research"}

  Increment cycle_count.
else
  # Cap reached: AskUserQuestion for architectural decision
  AskUserQuestion:
    question: "Task $task_number is repeatedly blocked on: $blocker_desc. Choose: (a) Accept proposed pivot, (b) Proceed with current approach, (c) Abandon this path"
    options: ["(a) Accept pivot", "(b) Proceed current", "(c) Abandon"]
fi

---

Stage 7: Terminal Conditions

# MAX_CYCLES reached
if [ "$cycle_count" -ge "$MAX_CYCLES" ]; then
  echo "[hard-orchestrate] MAX_CYCLES ($MAX_CYCLES) reached for task $task_number."
  echo "Phases completed: $phases_completed of $phases_total"
  echo "Run /orchestrate $task_number --hard to resume, or /implement $task_number --hard for manual phase dispatch."
  EXIT (partial, cycle_count=$MAX_CYCLES)
fi

---

Stage 8: Cleanup

rm -f "$loop_guard_file"
rm -f "$churn_file"

(Only on successful completion. Leave loop guard and churn state on partial for resume.)

---

Multi-Task Mode

Same as base skill-orchestrate multi-task stages (MT-1 through MT-5). Hard-mode applies to each individual task in the wave — they each use the per-phase dispatch H1 loop above.

---

Key Differences from skill-orchestrate

Feature	skill-orchestrate	skill-orchestrate-hard
MAX_CYCLES	5	13
Implement dispatch	Whole plan per cycle	One phase per cycle (H1)
Adversarial gate	None	Research verified before plan (H4)
Churn detection	None	Per-target counters (H6)
Three-strikes	None	Audit dispatch at 3 (H5)
Parallel dispatch	None	Wave-based with territory (H7)
Agents used	Base agents	Hard-mode agents
Prompt construction	Simple	Contract-slot injection