kws-claude-multi-agent-executor

name: kws-claude-multi-agent-executor description: Use when you have an implementation plan and design spec to execute autonomously — Opus orchestrates, Sonnet sub-agents implement/review/verify/document. Provide plan path and spec path at invocation. NOTE — single-session execution is preferable for ≤5-task plans or plans with deep cross-task coupling (multi-agent overhead exceeds the parallelism win). metadata: version: "2.29.0" updated_at: "2026-06-07"

KWS Claude Multi-Agent Executor

Path layout

All persistent state lives under ~/.claude/, NOT inside the source repo or repo-sibling directories. The two key locations are paired by a shared <plan-slug>-<YYYYMMDD-HHMMSS> suffix derived once per run:

The shared suffix is computed ONCE in Phase 0 Step 2 (or Phase -1 step a when self-spawning) and persisted into state.worktree and state.orchestrator_dir. Every downstream step reads these fields rather than re-deriving paths. The worktree and orchestrator-state directory are siblings, NOT nested.

Worktree contents: code + .git + <worktree>/.claude/settings.json (claude code loads project-local settings from cwd; the file's command strings reference absolute paths under <orch_dir>/hooks/...). Nothing else added by this skill. Sub-worktrees in the Parallel Sub-Flow get the same settings.json byte-identical — no path rewrite needed because hook scripts live outside every worktree.

Tilde expansion: ~/.claude/ MUST be expanded to $HOME/.claude/ (or the absolute equivalent) before being written into state.json or passed to sub-agents. Sub-agents and headless subprocesses cannot reliably expand ~ themselves. Bash command examples in this document write the literal ~/.claude/... for readability; the orchestrator MUST substitute the absolute path before execution.

Overview

You are the Orchestrator running on Opus. Execute an implementation plan from start to finish autonomously using fresh Sonnet sub-agents. Do not ask the user for approval between tasks.

At invocation, the user provides:

• Plan path — plan=<path> (required). For multi-plan sequential runs (v2.13), add plan2=<path>, plan3=<path>, … planN=<path> and matching specN=<path> pairs; the skill auto-chains them in numeric order with manifest= NOT required.
• Spec path — spec=<path> (required for the primary plan). For multi-plan runs add spec2=, spec3=, … paired with each planN=.
• Optionally: risk=<low|mid|high> to override risk level for all tasks (run-level — shared across all plans in a chain).
• Optionally: docs_scope=<file1,file2> to override which docs are updated.
• Optionally: implementer_model=<opus|sonnet> — override the Implementer sub-agent's model. Default is sonnet. The Reviewer and Verifier always run on Sonnet regardless (judge consistency). See docs/experiments/v2.12-implementer-opus-vs-sonnet/ for the rationale.
• Optionally: parallel=off to force sequential task dispatch (default is parallel where possible).
• Optionally: mode=interactive for single-session execution (no headless self-spawn — uses subscription pool instead of Agent SDK credits).

Natural-language args (v2.13): instead of writing implementer_model=opus parallel=off, you may include the words opus (or 오푸스) and 순차 (or sequential) anywhere in the args text. The skill scans free-text tokens and applies them. Explicit key=value always wins; contradictions halt. See Phase -1.0 for the full lexicon and conflict rules.

Active-tree resolution (v2.13)

Throughout the rest of this document, the placeholder <active> refers to the JSON path of the currently-active plan's per-plan state. It expands at runtime as follows:

state.active_plan is an integer index (0, 1, 2, …) whenever plan_chain is present. A legacy v2.12 plan2_state-shaped state.json is rewritten into this plan_chain shape by the one-time migration shim at Phase 0 Step 0 (scripts/migrate_legacy_state.py) before any <active> logic runs, so no live state.json reaching Phase 1 carries plan2_state.

Per-plan fields (live under <active>, NOT directly under state in multi-plan runs): tasks, task_summaries, quality_trend, baseline, low_tasks_pending_verification, global_constraints, compaction_points, execution_plan, risk_levels, task_complexity, last_compaction_after_task, last_completed_task, last_completed_at, plan_review.

Run-level fields (always at top-level state.*, shared across all plans in a chain): active_plan, plan_chain, implementer_model, spec_edits, test_command, mode, branch, worktree, timestamps, chain_resume, plan, spec (legacy mirrors of plan_chain[0]).

Every read or write to a per-plan field MUST go through <active> resolution. Hard-coding state.tasks or state.quality_trend for a multi-plan run silently corrupts the chain: plan 0's data writes to top-level while plan 1's writes to plan_chain[1], and the two trees diverge. The placeholder is not optional — wherever you see <active>.foo below, substitute the correct path before reading or writing.

In bash/jq fragments throughout the skill (e.g., Monitor scripts), the same rule applies via the active_plan dispatch:

if jq -e '.plan_chain' state.json >/dev/null 2>&1; then
  ACTIVE='.plan_chain[.active_plan]'
else
  ACTIVE='.'
fi

Use $ACTIVE.tasks, $ACTIVE.quality_trend, etc. in jq queries downstream.

Phase -1: Mode Selection (Autonomy Gate)

Procedure extracted (v2.19 T1.1): argument parsing, mode detection, self-spawn, and Resume Chain procedures live in references/phases/phase-minus-1-args-and-spawn.md.

Required action at the start of every invocation: before doing anything else, Read references/phases/phase-minus-1-args-and-spawn.md and follow its instructions to completion. That file specifies:

1. Phase -1.0 — three-pass argument parser (key=value, multi-plan auto-detection, NL keyword lexicon) with the echo line and conflict halt rules.
2. Phase -1.1 — mode detection (mode=interactive skip, <<HEADLESS_KWS_ORCHESTRATOR>> skip, otherwise Self-Spawn).
3. Self-Spawn Procedure — interactive Phase 0 Steps 1, 1.5, 2, 2.5; minimal state.json write with AgentLens run-open; headless prompt file; detached subprocess spawn with subshell-cd cwd enforcement; Monitor real-time progress notifications.
4. Resume Chain — token-aware + legacy-floor trigger; UUID resume session; PID atomic swap; kws-cme.context_health boundary emit; AGENTLENS_PARENT_RUN_ID propagation.

All values resolved in Phase -1 (parsed args, ORCH_RUN_ID, plan_chain list, branch/worktree paths) persist into state.json so downstream phases read them from state rather than re-parsing. See the reference file for the authoritative JSON shapes.

Phase 0: Setup

Procedure extracted (v2.21 D005): the full Phase 0 setup procedure — resume protocol + legacy plan2_state migration, plan/spec validation gates, clean-tree + cross-run isolation checks, worktree + safety-hook creation, document reading, ambiguity gate, spec manifest, risk assignment, local-env preflight, baseline test, dependency graph / compaction points / execution plan, Plan Reviewer preflight, state.json initialization, and the mandatory kws-cme.phase_0_started boundary emit — lives in references/phases/phase-0-setup.md.

Required action when you reach Phase 0: Read references/phases/phase-0-setup.md and follow it to completion before entering Phase 1. It defines Steps 0 through 7.5; on the headless_pending resume path it specifies which Steps (1, 1.5, 2, 2.5) to skip. Every value it resolves (baseline, risk_levels, execution_plan, the full state.json) persists into state.json so downstream phases read from state rather than re-deriving.

Phase 1: Per-Task Cycle

Procedure extracted (v2.21 D005): the per-task execution cycle — Step 1 Dispatch Implementer, Step 2 Combined Reviewer (incl. the P15 spec-edit branch and the standard retry branch), Step 3 Verifier (MID/HIGH only), Step 3.5 learning-log candidate scan, and Step 4 Agent Cleanup — lives in references/phases/phase-1-task-cycle.md. The multi-task Parallel Sub-Flow (P2) lives in references/phases/phase-1-parallel-subflow.md.

Required action when you reach Phase 1: Read references/phases/phase-1-task-cycle.md and follow it for every task in <active>.execution_plan (waves outer, parallel groups inner). For a parallel group of size ≥ 2 it directs you to the Parallel Sub-Flow reference. Advance only when the current task or group reaches Agent Cleanup successfully.

Phase Transition

Procedure extracted (v2.21 D005): the compaction-point procedure — Step T1 batch Verifier for accumulated LOW tasks, Step T2 Phase Docs Updater, and Step T3 state anchor + context drop (token-health evaluation + Resume Chain trigger) — lives in references/phases/phase-transition.md.

Required action at each compaction point: Read references/phases/phase-transition.md and follow T1 → T2 → T3 after Agent Cleanup of the boundary task, before starting the next task.

Escalation Protocol

Procedure extracted (v2.21 D005): the orchestrator's full response to any sub-agent STATUS: ESCALATE (AMBIGUITY, SPEC_BLOCKER, ENV_BLOCKER, escalation cap) plus the ENV_BLOCKER triage pointer — lives in references/phases/phase-1-escalation.md.

Required action when a sub-agent escalates: Read references/phases/phase-1-escalation.md and follow it. The ESCALATE type enum is summarized in the Safety Gates section below; the response procedure (and the rule that the orchestrator — never a sub-agent — updates spec/plan documents) lives in the reference.

Phase 2: Final Phase

Procedure extracted (v2.21 D005): the finalization procedure — Step -1 Cross-Plan Trigger (multi-plan plan_chain advance), Step 0 LOW batch Verifier sweep, Step 1 Final Docs Updater, Step 1.5 Method Audit Validation, and Step 2 Generate Final Summary Report (including the ## Execution Summary report template the orchestrator emits) plus the final agentlens run-close — lives in references/phases/phase-2-finalization.md.

Required action when all tasks are processed (COMPLETE or SKIPPED): Read references/phases/phase-2-finalization.md and follow it to completion. It defines the exact Final Summary Report layout and the success/blocked/aborted run-close outcomes.

Cross-cutting references

Topics that span multiple phases live in references/cross-cutting/. The phase files link to them; read the relevant one when you need the full detail behind a guardrail or schema field:

The <active> resolution table above and the Guardrails table below are the load-bearing summaries kept in this entrypoint; the cross-cutting files hold the expanded detail, not a duplicate of the invariants.

Guardrails

These rules are absolute. No exceptions.

Sub-agent Prompt Templates

The Implementer, Combined Reviewer, Verifier, and Docs Updater prompt templates live in references/. Read the relevant file via the Read tool at the moment of dispatch — do NOT preload them.

Each file is a self-contained prompt body with {placeholders} to fill from the current task context. The dispatch mechanics (Agent vs. headless), result-file paths, and ESCALATE handling are defined in the SKILL.md phases above — the reference files do not repeat that logic.

All sub-agent prompt templates must bootstrap Skill("superpowers:using-superpowers") as their first action. Implementers must additionally invoke Skill("superpowers:test-driven-development") for executable implementation work before writing implementation code, independent of task size, and must report RED/GREEN evidence in their structured output.