skill-orchestrate

Orchestrate Skill

Fire-and-forget autonomous loop implementing the 10-state task lifecycle state machine. Drives research, planning, implementation, and blocker escalation without user interaction.

Context References

Architecture documentation (load as needed):

• .claude/docs/architecture/orchestrate-state-machine.md - Complete state table and transition diagram
• .claude/docs/architecture/handoff-schema.md - Orchestrator handoff JSON schema

Infrastructure (source as needed):

• .claude/scripts/skill-base.sh - Shared skill lifecycle functions

---

Execution Flow

Stage 0: Multi-Task Mode Detection

Parse multi_task_mode from the delegation context. If true, branch to multi-task stages (MT-1 through MT-5) in the Multi-Task Mode section below. If false or absent, fall through to Stage 1 (single-task mode).

Read from delegation context:

• multi_task_mode (default: false)
• session_id
• focus_prompt (default: "")
• lit_flag (default: "false")

If multi_task_mode is true: skip Stages 1-8 entirely and proceed to Stage MT-1.

---

Stage 1: Input Validation

Read from delegation context:

• task_number (from task_context.task_number)
• session_id, focus_prompt, lit_flag

Resolve from specs/state.json:

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

If TASK_DATA is empty: exit with error "Task $task_number not found in state.json".

Extract: PROJECT_NAME, TASK_TYPE (default: "general"), DESCRIPTION, TASK_DIR="specs/${PADDED_NUM}_${PROJECT_NAME}".

Stage 1b: Resolve Task-Type Routing

Map task_type to the correct research and implementation agents using extension manifests.

# Resolve agents by task_type — consult extension manifests for non-core types
case "$TASK_TYPE" in
  lean4|lean)
    RESEARCH_AGENT="lean-research-agent"
    IMPLEMENT_AGENT="lean-implementation-agent"
    ;;
  neovim)
    RESEARCH_AGENT="neovim-research-agent"
    IMPLEMENT_AGENT="neovim-implementation-agent"
    ;;
  nix)
    RESEARCH_AGENT="nix-research-agent"
    IMPLEMENT_AGENT="nix-implementation-agent"
    ;;
  *)
    RESEARCH_AGENT="general-research-agent"
    IMPLEMENT_AGENT="general-implementation-agent"
    ;;
esac
echo "[orchestrate] Task type: $TASK_TYPE → research=$RESEARCH_AGENT, implement=$IMPLEMENT_AGENT"

Extension resolution: If a task_type is not in the case table above, check for an extension manifest:

manifest=".claude/extensions/${TASK_TYPE}/manifest.json"
if [ -f "$manifest" ]; then
  ext_research=$(jq -r ".routing.research[\"$TASK_TYPE\"] // empty" "$manifest")
  ext_implement=$(jq -r ".routing.implement[\"$TASK_TYPE\"] // empty" "$manifest")
  # Map skill names to agent names (skill-X-Y -> X-Y-agent)
  if [ -n "$ext_research" ]; then
    RESEARCH_AGENT=$(echo "$ext_research" | sed 's/^skill-//' | sed 's/$/-agent/')
  fi
  if [ -n "$ext_implement" ]; then
    IMPLEMENT_AGENT=$(echo "$ext_implement" | sed 's/^skill-//' | sed 's/$/-agent/')
  fi
fi

Stage 2: Preflight — Loop Guard

Create or read the loop guard file. This tracks cycle count across conversational turns.

MAX_CYCLES=5
loop_guard_file="${TASK_DIR}/.orchestrator-loop-guard"
handoff_file="${TASK_DIR}/.orchestrator-handoff.json"

mkdir -p "$TASK_DIR"

if [ -f "$loop_guard_file" ] && jq empty "$loop_guard_file" 2>/dev/null; then
  # Resume: read existing guard
  cycle_count=$(jq -r '.cycle_count // 0' "$loop_guard_file")
  echo "[orchestrate] Resuming — cycle $cycle_count of $MAX_CYCLES"
else
  # Fresh start: create guard atomically via init-marker (task 808). A plain
  # `>` redirect has no O_EXCL semantics, so two racing writers could both take
  # this branch and stomp each other's counters; init-marker's mkdir-gate +
  # tmp-mv payload guarantees exactly one winner. On a lost race (exit 1),
  # degrade to the same resume-read the `if`-branch above performs.
  if 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",
      "started": $started,
      "last_updated": $started
    }' | bash .claude/scripts/task-lock.sh init-marker "$loop_guard_file"; then
    cycle_count=0
    echo "[orchestrate] Starting fresh — MAX_CYCLES=$MAX_CYCLES"
  else
    # Lost the creation race: another writer won. Resume from their guard.
    cycle_count=$(jq -r '.cycle_count // 0' "$loop_guard_file")
    echo "[orchestrate] Resuming (lost init race) — cycle $cycle_count of $MAX_CYCLES"
  fi
fi

# Blocker escalation counter (reset each /orchestrate invocation)
blocker_escalation_count=0
MAX_BLOCKER_ESCALATIONS=2

# Drift detection constants (reset each /orchestrate invocation)
drift_inspection_count=0
MAX_DRIFT_INSPECTIONS=1
DRIFT_COMPLETION_THRESHOLD=0.70
DRIFT_REVISION_THRESHOLD=0.30

Stage 3: State Machine Loop

The loop runs until a terminal condition is reached or MAX_CYCLES is hit.

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 "[orchestrate] Cycle $((cycle_count + 1))/$MAX_CYCLES — status: $current_status"

3b. Update loop guard with current state

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"

# Task-lock heartbeat: refresh at the same per-cycle boundary as the loop guard, so a
# multi-hour single-task /orchestrate run (whose lock was acquired once at orchestrate.md's
# CHECKPOINT 1) never goes stale under its own hand. No-op with a warning if the lock is
# somehow missing or held by another session — heartbeat never blocks this loop. See
# .claude/context/patterns/task-lock.md.
bash .claude/scripts/task-lock.sh heartbeat "$task_number" "$session_id" 2>/dev/null || true

3c. Dispatch by state (see State Handlers in Stage 4)

---

Stage 4: State Handlers

State: not_started or not started

Invoke the Agent tool:

After Agent tool returns: read handoff (Stage 5). Increment cycle_count.

State: researching

In-flight state (another session is actively researching). Exit with warning.

echo "[orchestrate] WARNING: Task $task_number is currently being researched in another session."
echo "Wait for the research to complete, then run /orchestrate $task_number again."
EXIT (partial)

State: researched

Read research artifact path from state.json:

research_artifact=$(jq -r --argjson num "$task_number" \
  '[.active_projects[] | select(.project_number == $num) | .artifacts // [] | .[] | select(.type == "report")] | .[0].path // ""' \
  specs/state.json)

Invoke the Agent tool:

After Agent tool returns: read handoff. Increment cycle_count.

State: planning

In-flight state. Exit with warning (same pattern as researching).

State: planned or implementing

Read plan path:

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

Invoke the Agent tool:

After Agent tool returns: read handoff. Increment cycle_count.

State: partial

Read .orchestrator-handoff.json to determine sub-state:

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

Sub-state: continuation available (continuation != null AND has handoff_path):

Read plan path:

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

Invoke the Agent tool:

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

Invoke blocker escalation (Stage 6). Increment cycle_count after escalation.

Sub-state: no handoff, no blockers (cycle limit or stuck):

echo "[orchestrate] Task $task_number in partial state with no continuation and no blockers."
echo "Cycle $cycle_count/$MAX_CYCLES consumed. Run /orchestrate $task_number to retry or /implement $task_number for manual resume."
EXIT (partial, cycle_count)

State: blocked

Read blockers from state.json (not handoff — task was blocked outside orchestrator context):

blocker_desc=$(jq -r --argjson num "$task_number" \
  '.active_projects[] | select(.project_number == $num) | .blockers // "Unspecified blocker"' \
  specs/state.json)

Invoke blocker escalation (Stage 6) with blocker_desc.

State: completed

echo "[orchestrate] Task $task_number completed successfully."
# Clean up loop guard
rm -f "$loop_guard_file"
EXIT (success)

States: abandoned, expanded

echo "[orchestrate] Task $task_number is in terminal state [$current_status]. No action taken."
EXIT (no-op)

Unknown state

echo "[orchestrate] WARNING: Unrecognized state '$current_status' for task $task_number."
EXIT (partial)

---

Stage 5: Handoff Reading (after each dispatch)

After every Agent tool invocation, read the orchestrator handoff to learn the outcome. Never read the full research report, plan, or implementation summary — only the handoff.

if [ ! -f "$handoff_file" ]; then
  echo "[orchestrate] ERROR: Skill did not write orchestrator handoff."
  echo "This may mean orchestrator_mode was not propagated correctly."
  # Increment cycle and continue — state.json may still have been updated
else
  handoff=$(cat "$handoff_file")
  dispatch_status=$(echo "$handoff" | jq -r '.status')
  dispatch_summary=$(echo "$handoff" | jq -r '.summary // ""')
  blockers=$(echo "$handoff" | jq -c '.blockers // []')
  continuation=$(echo "$handoff" | jq -c '.continuation_context // null')
  next_hint=$(echo "$handoff" | jq -r '.next_action_hint // "none"')
  phases_completed=$(echo "$handoff" | jq -r '.phases_completed // 0')
  phases_total=$(echo "$handoff" | jq -r '.phases_total // 0')
  echo "[orchestrate] Dispatch result: $dispatch_status — $dispatch_summary"
  [ "$phases_total" -gt 0 ] && echo "[orchestrate] Phase progress: $phases_completed/$phases_total"

  # Drift detection: arithmetic gate (cheap check before expensive inspection fork)
  if [ "$phases_total" -gt 0 ] && [ "$dispatch_status" = "partial" ]; then
    # Use awk for floating-point comparison (bash only does integer math)
    completion_ratio=$(awk "BEGIN { printf \"%.4f\", $phases_completed / $phases_total }")
    is_below_threshold=$(awk "BEGIN { print ($completion_ratio < $DRIFT_COMPLETION_THRESHOLD) ? \"yes\" : \"no\" }")
    if [ "$is_below_threshold" = "yes" ]; then
      echo "[orchestrate] Low phase completion ($phases_completed/$phases_total). Inspecting plan for drift..."
      invoke_drift_inspection "$task_number" "$plan_path" "$session_id"
    fi
  fi

  # Postflight status update: trigger state.json + TODO.md Task Order regeneration
  case "$dispatch_status" in
    researched)
      skill_postflight_update "$task_number" "research" "$session_id" "$dispatch_status"
      ;;
    planned)
      skill_postflight_update "$task_number" "plan" "$session_id" "$dispatch_status"
      ;;
    implemented)
      skill_postflight_update "$task_number" "implement" "$session_id" "$dispatch_status"
      ;;
    *)
      echo "[orchestrate] Dispatch status '$dispatch_status' — no postflight update needed"
      ;;
  esac

  # Artifact linking: extract artifact path/type from handoff and link in TODO.md + state.json
  handoff_artifact_path=$(echo "$handoff" | jq -r '.artifacts[0].path // ""')
  handoff_artifact_type=$(echo "$handoff" | jq -r '.artifacts[0].type // ""')
  handoff_artifact_summary=$(echo "$handoff" | jq -r '.artifacts[0].summary // ""')
  if [ -n "$handoff_artifact_path" ] && [ "$handoff_artifact_path" != "null" ]; then
    case "$handoff_artifact_type" in
      report)
        field_name='**Research**'
        next_field='**Plan**'
        ;;
      plan)
        field_name='**Plan**'
        next_field='**Description**'
        ;;
      summary)
        field_name='**Summary**'
        next_field='**Description**'
        ;;
      *)
        field_name='**Summary**'
        next_field='**Description**'
        ;;
    esac
    skill_link_artifacts "$task_number" "$handoff_artifact_path" "$handoff_artifact_type" \
      "$handoff_artifact_summary" "$field_name" "$next_field"
  fi
fi

# Increment cycle_count
cycle_count=$((cycle_count + 1))

---

Stage 5a: Drift Inspection

Called from Stage 5 when phase completion is below DRIFT_COMPLETION_THRESHOLD and dispatch_status is "partial". Capped at MAX_DRIFT_INSPECTIONS=1 per /orchestrate invocation.

1. If drift_inspection_count >= MAX_DRIFT_INSPECTIONS: log warning and return (skip inspection).

2. Increment drift_inspection_count. Log: "[orchestrate] Drift inspection attempt N/MAX".

3. Invoke the Agent tool (fork — to inspect the plan file):

4. After Agent tool returns: read ${TASK_DIR}/.drift-inspection.json.

   • If file exists: extract drift_pct and drift_summary.
   • If file missing: log warning, set drift_pct=0, drift_summary="Inspection output missing".

5. If drift_pct > DRIFT_REVISION_THRESHOLD: trigger plan revision:

   Invoke the Agent tool (reviser):

   Field	Value
   subagent_type	"reviser-agent"
   prompt	"Revise the implementation plan for task $task_number to address plan drift (drift_pct=$drift_pct). Summary: $drift_summary"
   context	{ task_number, session_id, plan_path, revision_reason: "drift", drift_pct, orchestrator_mode: false }

   After Agent tool returns: read handoff to confirm revision.

6. If drift_pct <= DRIFT_REVISION_THRESHOLD: log "Drift check passed. Continuing."

---

Stage 6: Blocker Escalation (5-Step Sequence)

Called when: partial state with non-empty blockers, or blocked state. Capped at MAX_BLOCKER_ESCALATIONS=2 per /orchestrate invocation.

If blocker_escalation_count >= MAX_BLOCKER_ESCALATIONS: log error and return. Manual intervention required. Suggest: (1) /research $task_number, (2) /revise $task_number, (3) /implement $task_number.

Increment blocker_escalation_count. Log escalation attempt and blocker description.

Step 1: DETECT — blocker_desc is passed in by caller (from handoff or state.json).

Step 2: RESEARCH FORK — Invoke the Agent tool:

After Agent tool returns: read $handoff_file for research findings.

Step 3: READ FINDINGS — From handoff:

findings_summary=$(jq -r '.summary // "No findings"' "$handoff_file")
findings_artifact=$(jq -r '.artifacts[0].path // ""' "$handoff_file")

Step 4: REVISE PLAN — Read latest plan path, then invoke the Agent tool:

After Agent tool returns: read handoff to confirm revision.

Step 5: RE-DISPATCH IMPLEMENT — Read revised plan path, then invoke the Agent tool:

After Agent tool returns: read handoff.

---

Stage 7: Loop Guard Update (end of each cycle)

After each cycle (whether dispatch succeeded or failed):

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"

If MAX_CYCLES reached (cycle_count >= MAX_CYCLES):

echo "[orchestrate] MAX_CYCLES ($MAX_CYCLES) reached for task $task_number."
echo "Current state: $current_status. Run /orchestrate $task_number to continue."
EXIT (partial)

---

Stage 8: Postflight

On clean exit (task completed or terminal state):

# Remove loop guard on success
rm -f "$loop_guard_file"
# Clean up drift inspection artifact if present
rm -f "${TASK_DIR}/.drift-inspection.json"
echo "[orchestrate] Task $task_number: orchestration complete."
echo "Final status: $current_status | Cycles used: $cycle_count/$MAX_CYCLES"

On partial exit (MAX_CYCLES, in-flight warning, escalation cap):

# Preserve loop guard for next /orchestrate invocation
echo "[orchestrate] Task $task_number: orchestration paused."
echo "Status: $current_status | Cycles: $cycle_count/$MAX_CYCLES | Run /orchestrate $task_number to continue."

Write metadata file.

On clean exit:

mkdir -p "${TASK_DIR}/summaries"
jq -n \
  --arg status "completed" \
  --argjson cycles "$cycle_count" \
  --arg final_state "$current_status" \
  '{
    "status": $status,
    "metadata": {
      "cycles_used": $cycles,
      "final_state": $final_state
    }
  }' > "${TASK_DIR}/.return-meta.json"

On partial exit:

mkdir -p "${TASK_DIR}/summaries"
jq -n \
  --arg status "partial" \
  --argjson cycles "$cycle_count" \
  --arg final_state "$current_status" \
  '{
    "status": $status,
    "metadata": {
      "cycles_used": $cycles,
      "final_state": $final_state
    }
  }' > "${TASK_DIR}/.return-meta.json"

---

Multi-Task Mode

Entered when multi_task_mode=true in the delegation context (detected in Stage 0). All single-task stages (1-8) are skipped. The skill receives a pre-computed wave schedule from orchestrate.md and manages all tasks in a single orchestrator instance.

Stage MT-1: Parse Multi-Task Context

Read from delegation context:

• task_numbers — array of task numbers to manage
• dependency_graph — map of task_number -> [predecessor_task_numbers]
• waves — pre-computed topological wave schedule
• session_id, lit_flag

Compute: task_count = length(task_numbers), MAX_CYCLES_MT = min(task_count * 5, 25).

Initialize mt_state_file = "specs/.orchestrator-multi-state.json" with fields: session_id, task_numbers, waves, max_cycles, cycle_count: 0, failed_tasks: [], completed_tasks: [], current_statuses: {}, task_dirs: {}, research_agents: {}, implement_agents: {}.

Stage MT-2: Build Per-Task Routing Table

For each task in task_numbers, read state.json to get task_type, project_name. Compute task_dir = "specs/${padded}_${project_name}". Resolve research_agent and implement_agent using the same routing table as Stage 1b:

Check .claude/extensions/${task_type}/manifest.json for override routing. Populate all per-task maps into mt_state_file.

Stage MT-3: Lifecycle-Cycling Loop

Initialize cycle_count = 0. Loop while cycle_count < MAX_CYCLES_MT:

1. Status refresh: For each task in task_numbers, read current status from state.json and update mt_state_file.current_statuses.

2. All-terminal check: If every task is in {completed, abandoned, expanded} or in failed_tasks — break loop (exit success or partial).

3. Build eligible_tasks: For each task, include it if ALL of the following are true:

   • Status is NOT {completed, abandoned, expanded} and NOT in failed_tasks
   • Status is NOT {researching, planning} (in-flight from prior cycle)
   • All predecessors from dependency_graph[task_num] are in terminal state or failed_tasks

   If a predecessor is in failed_tasks: mark this task in failed_tasks with status blocked and skip it. If a predecessor is still in-progress: skip this task (wait for next cycle).

4. No-eligible circuit breaker: If eligible_tasks is empty, log warning with list of stuck tasks and break loop (exit partial).

4.5. Runtime wave-split check (cross-batch defense-in-depth): Before dispatching eligible_tasks when it contains 2+ tasks, compare every pair using the shared directory-prefix overlap algorithm in .claude/context/patterns/file-footprint-overlap.md (referenced by path — not restated here), applied to each task's file_scope (read only for the tasks already in task_numbers for this invocation — no repo-wide scan). If two tasks in eligible_tasks have overlapping file_scope and no edge between them in dependency_graph, remove the lower-priority task (higher project_number) from this cycle's dispatch batch (it becomes eligible again next cycle, once the other completes) and log a visible warning:

[orchestrate] WARNING: Tasks #{X} and #{Y} have overlapping file_scope with no
  dependency_graph edge between them. Deferring #{Y} to a later cycle to avoid
  concurrent edits to the same files.

This mirrors the same check documented in orchestrate.md Step 3 for the pre-computed wave schedule; here it applies per-cycle to eligible_tasks since Multi-Task Mode dispatches cycle-by-cycle rather than strictly wave-by-wave. If this proves too aggressive in practice, it can be relaxed to warn-only by editing this step (see Rollback/Contingency in specs/787_file_footprint_aware_dependencies/plans/01_file-footprint-aware-dependencies.md).

5. Dispatch (Stage MT-4) — see below.

6. Increment cycle_count, update mt_state_file.cycle_count. If cycle_count >= MAX_CYCLES_MT: log partial status and break.

Stage MT-4: Phase-Aware Dispatch and Per-Task Postflight

BATCHING RULE: ALL Agent tool calls for the current cycle's dispatch batch MUST be issued in a SINGLE orchestrator message with multiple tool-use content blocks. Do NOT issue calls across multiple messages — Claude Code processes all calls in a single message concurrently; multiple messages force sequential execution.

COMPLETION SEQUENCING: After ALL Agent tool calls complete (Claude Code returns control after all calls in the single message finish), read handoffs for every dispatched task. Do NOT read handoffs interleaved with dispatches.

Phase grouping — Classify each eligible task by its current status:

Task-lock acquire (per-task, before dispatch): Multi-task dispatch bypasses the single-task gate scripts entirely (command-gate-in.sh/command-gate-out.sh are never sourced here), so this stage acquires/releases the lock itself. See .claude/context/patterns/task-lock.md for the full contract. For each task across research_tasks + plan_tasks + implement_tasks (before building the single dispatch message):

bash .claude/scripts/task-lock.sh acquire "$task_num" "$op" "${session_id}_${task_num}" "/orchestrate (multi-task)"

where $op is research/plan/implement matching the task's group. If acquire refuses (exit 1 — a fresh lock held by a genuinely different session; same-session re-entry, including a prior cycle of this SAME multi-task run, never refuses), remove that task from this cycle's dispatch batch (do NOT add it to failed_tasks — it becomes eligible again next cycle, mirroring the wave-split check's defer-not-fail behavior in Stage MT-3 step 4.5) and log:

[orchestrate] WARNING: Task #{task_num} is locked by another session; deferring to a later cycle.

Dispatch all groups in ONE message:

For each task in research_tasks:

• Invoke Agent tool: subagent_type = research_agents[task_num], prompt = "Research task $task_num: $description", context = { task_number: task_num, task_type, session_id: "${session_id}_${task_num}", orchestrator_mode: false, lit_flag }

For each task in plan_tasks:

• Read research_artifact path from state.json artifacts (type=report)
• Invoke Agent tool: subagent_type = "planner-agent", prompt = "Create implementation plan for task $task_num", context = { task_number: task_num, task_type, session_id: "${session_id}_${task_num}", research_artifacts: [research_artifact], orchestrator_mode: false, lit_flag }

For each task in implement_tasks:

• Read plan_path from task_dir/plans/ (latest .md)
• Read continuation from task_dir/.orchestrator-handoff.json (or null)
• Invoke Agent tool: subagent_type = implement_agents[task_num], prompt = "Implement task $task_num following the plan", context = { task_number: task_num, task_type, session_id: "${session_id}_${task_num}", orchestrator_mode: true, plan_path, continuation_context: continuation, lit_flag }

After all Agent tool calls complete, read handoffs and run per-task postflight for each dispatched task:

For each task in research_tasks + plan_tasks + implement_tasks:

1. Read task_dir/.orchestrator-handoff.json. If missing: mark task in failed_tasks, skip.
2. Extract dispatch_status, dispatch_summary, artifact path/type/summary.
3. Call skill_postflight_update:
   • dispatch_status = "researched" → skill_postflight_update task_num "research" "${session_id}_${task_num}" researched
   • dispatch_status = "planned" → skill_postflight_update task_num "plan" "${session_id}_${task_num}" planned
   • dispatch_status = "implemented" → skill_postflight_update task_num "implement" "${session_id}_${task_num}" implemented
   • Other → no postflight update
4. Call skill_link_artifacts if artifact path is present (same field mapping as Stage 5).
5. Re-read fresh status from state.json (postflight may have updated it). Update mt_state_file.current_statuses[task_num]:
   • If fresh_status = "completed": also add to completed_tasks.
   • If dispatch_status is "failed" or "blocked": add to failed_tasks.
   • Otherwise: set current_statuses[task_num] = fresh_status.
6. Task-lock release (per-task, unconditional): regardless of the outcome above (success, failed, or blocked):

   bash .claude/scripts/task-lock.sh release "$task_num" "${session_id}_${task_num}"
   

Stage MT-5: Multi-Task Postflight

After the lifecycle-cycling loop exits (all terminal, no eligible tasks, or MAX_CYCLES_MT reached):

1. Read from mt_state_file: completed_tasks, failed_tasks, cycles_used, counts.
2. Determine exit_status:
   • failed_count == 0 → "completed" (remove mt_state_file)
   • failed_count > 0 → "partial" (preserve mt_state_file for diagnostics)
3. Write specs/.return-meta-multi.json:

jq -n \
  --arg status "$exit_status" \
  --argjson tasks_completed "$completed_tasks" \
  --argjson tasks_failed "$failed_tasks" \
  --argjson cycles_used "$cycles_used" \
  '{
    "status": $status,
    "metadata": {
      "tasks_completed": $tasks_completed,
      "tasks_failed": $tasks_failed,
      "cycles_used": $cycles_used,
      "multi_task_mode": true
    }
  }' > "specs/.return-meta-multi.json"

---

MUST NOT (Context Flatness Constraint)

This skill MUST NOT:

1. Read research reports (reports/*.md) during the state machine loop
2. Read plan files (plans/*.md) during the state machine loop
3. Read implementation summaries (summaries/*.md) during the state machine loop
4. Read continuation handoff files (handoffs/*.md) — pass the path, not the content

The ONLY file read after each dispatch is .orchestrator-handoff.json (≤400 tokens). This ensures context grows by only ~450 tokens per cycle regardless of artifact complexity.

Skill-to-Agent Mapping

Default agents: general-research-agent, general-implementation-agent. Extension agents resolved in Stage 1b.