From session-orchestrator
Orchestrates agreed session plans in waves using role-based parallel subagents with inter-wave quality checks, plan adaptation, and progress tracking. Core engine for feature and deep sessions; triggered by /go.
npx claudepluginhub kanevry/session-orchestrator --plugin session-orchestratorThis skill uses the workspace's default tool permissions.
You are the **coordinator**. You do NOT implement — you orchestrate. Your job:
Guides strict Test-Driven Development (TDD): write failing tests first for features, bugfixes, refactors before any production code. Enforces red-green-refactor cycle.
Guides systematic root cause investigation for bugs, test failures, unexpected behavior, performance issues, and build failures before proposing fixes.
Guides A/B test setup with mandatory gates for hypothesis validation, metrics definition, sample size calculation, and execution readiness checks.
You are the coordinator. You do NOT implement — you orchestrate. Your job:
This harness exists to enable multi-agent coordination at scale — not by removing friction, but by making it visible, classifiable, and recoverable.
The wave-executor is process scaffolding around LLM agents. It handles task breakdown, scope enforcement, circuit breaker guards, and recovery patterns. Unlike direct chat with an agent, it trades flexibility for safety and repeatability across a bounded execution envelope.
Every harness creates friction. The goal is not minimum friction — it is useful friction that prevents higher-cost problems downstream.
Friction we accept:
wave-scope.json pre-dispatch setupFriction we prevent:
The harness does not hope agents self-correct. It detects stagnation patterns — pagination-spiral, turn-key-repetition, error-echo — classifies them into the Error-Class Taxonomy defined in circuit-breaker.md, and re-scopes mechanically. Review logic lives in wave-loop.md § "Review Agent Outputs".
State files live in the platform's native directory:
.claude/for Claude Code,.codex/for Codex CLI,.cursor/for Cursor IDE. All references to.claude/below should use the platform's state directory. Shared metrics (sessions.jsonl, learnings.jsonl) live in.orchestrator/metrics/— both platforms read and write there. Seeskills/_shared/platform-tools.mdfor tool mappings.
Read skills/_shared/bootstrap-gate.md and execute the gate check. If the gate is CLOSED, invoke skills/bootstrap/SKILL.md and wait for completion before proceeding. If the gate is OPEN, continue to the Pre-Execution Check.
Do NOT proceed past Phase 0 if GATE_CLOSED. There is no bypass. Refer to `skills/_shared/bootstrap-gate.md` for the full HARD-GATE constraints.Session-start only: This gate check runs ONCE at the start of
/goexecution — before the first wave. It does NOT run before each wave step. Repeating the check per wave would add latency with no safety benefit, sincebootstrap.lockis immutable within a session.
Before starting the first wave (Discovery role):
git status --short — ensure clean working directory (commit or stash if needed)
Verify no parallel session conflicts (unexpected modified files)
Confirm the agreed plan is still valid (no new critical issues since planning)
Verify jq is installed — run command -v jq. If not found, warn the user: "⚠ jq is not installed. Scope and command enforcement hooks will be DISABLED. Install jq (brew install jq / apt install jq) to enable security enforcement." Do NOT proceed with waves until user acknowledges.
Read Session Config: Parse Session Config per skills/_shared/config-reading.md. Store result as $CONFIG. Extract these fields:
persistence (default: true), enforcement (default: warn), isolation (default: auto)agents-per-wave (default: 6), max-turns (default: auto), pencil (default: null)Execution Config shortcut: If the session-plan output contains an ### Execution Config section, its execution-level fields (waves, agents-per-wave, isolation, enforcement, max-turns) take precedence over $CONFIG. Session-level fields (persistence, pencil) always come from $CONFIG. If the Execution Config section is missing, use $CONFIG alone.
Initialize session metrics (if persistence enabled): Prepare a metrics tracking object for this session:
session_id: <branch>-<YYYY-MM-DD>-<HHmm> (HHmm from started_at — ensures uniqueness across multiple sessions per day)session_type: from Session Configstarted_at: ISO 8601 timestampwaves: empty array (populated after each wave)
This object lives in memory during execution — it is written to disk by session-end.If the user provided additional instructions with /go (e.g., /go focus on API endpoints), apply them as a priority modifier:
Example: If user said /go focus on API endpoints, each agent prompt includes:
**Priority Focus (from user):** focus on API endpoints
Before dispatching Wave 1, capture the current commit as the session baseline:
SESSION_START_REF=$(git rev-parse HEAD)
Store this value for use throughout the session — it is needed by the simplification pass (Quality wave) and session-reviewer dispatch to determine which files changed during this session. Include it in the coordinator's context, NOT in individual agent prompts.
Skip this section entirely if
persistence: false.
Before dispatching Wave 1, write <state-dir>/STATE.md with YAML frontmatter and Markdown body:
---
schema-version: 1
session-type: feature|deep|housekeeping
branch: <current branch>
issues: [<issue numbers from plan>]
started_at: <ISO 8601 timestamp with timezone>
status: active
current-wave: 0
total-waves: <from session plan>
---
## Current Wave
Wave 0 — Initializing
## Wave History
(none yet)
## Deviations
(none yet)
Create the <state-dir> directory if needed (mkdir -p <state-dir>) before writing. This file is the persistent state record — other skills and resumed sessions read it.
After writing the base STATE.md frontmatter above, conditionally persist the docs tasks block emitted by session-plan:
Condition: BOTH of the following must be true:
### Docs Tasks (machine-readable) section with a YAML code block.$CONFIG."docs-orchestrator".enabled is true.If either condition is false → omit the docs-tasks field entirely. Do NOT write an empty key (docs-tasks: []). Absence means "no docs tasks planned this session" — downstream consumers (session-end Phase 3.2) treat absence the same as an empty list.
When the condition is met, parse the YAML block from the session plan's ### Docs Tasks (machine-readable) section and append the following field to the STATE.md YAML frontmatter (alongside the base fields above):
docs-tasks:
- id: <task id from plan>
audience: <user|dev|vault>
target-pattern: <glob pattern from plan>
rationale: <rationale string from plan>
wave: <wave number the task is assigned to>
status: planned
Each entry's status is initialized to planned. session-end Phase 3.2 (Docs Verify) writes the terminal value per task: ok (diff is substantive), partial (diff region contains <!-- REVIEW: source needed --> markers), or gap (no matching diff). wave-executor does NOT perform intermediate status updates — planned remains until session-end runs.
Schema note:
schema-version: 1now includes the optionaldocs-tasksarray. The field is backwards-compatible — its absence is a valid schema-version-1 STATE.md meaning "no docs tasks planned". Readers MUST treat a missingdocs-taskskey identically todocs-tasks: [].
Ownership clarification: session-plan does NOT write STATE.md directly. The wave-executor owns ALL STATE.md writes — initialization here (Pre-Wave 1b) is the canonical write point for
docs-tasks. session-plan only emits the source### Docs Tasks (machine-readable)block for the coordinator to consume. Seeskills/_shared/state-ownership.mdfor the full ownership matrix.
Consumer cross-reference: session-end reads
STATE.mdfrontmatter'sdocs-tasksfield (if present) during Phase 3.2 Docs Verify — seeskills/session-end/SKILL.md. The field is also readable by the docs-writer agent if it needs to know which tasks were planned for the current session.
Ownership: STATE.md is owned by the wave-executor. Only the wave-executor writes to it (initialization + post-wave updates). session-end reads it for metrics extraction and sets
status: completed. session-start reads it only for continuity checks (Phase 0.5). No other skill should write to STATE.md.
Read and follow wave-loop.md in this skill directory for the complete wave execution loop, including agent dispatch, output review, plan adaptation, progress updates, and scope manifest creation.
Reference: See
circuit-breaker.mdin this skill directory for MaxTurns enforcement, spiral detection, recovery protocol, and worktree isolation configuration. Apply those rules during every wave dispatch and post-wave review.
Claude Code's Agent tool with isolation: "worktree" changes process.cwd() into the agent's worktree and does not restore it on agent return. Without discipline, the coordinator's subsequent Edit/Write/Bash calls silently route to a worktree branch — producing data loss when the worktree is later pruned.
Rules for the coordinator (this is YOU during wave execution):
restoreCoordinatorCwd() from scripts/lib/worktree.mjs. wave-loop.md § 2 makes this explicit.cd inside a subshell (cd /path && cmd) or rely on git -C /path <cmd>. Do not assume CWD.git rev-parse --show-toplevel to confirm which tree is currently active.cd into a worktree in the coordinator's top-level shell. If you need to inspect a worktree, use git -C <wt-path> ... or spawn a subshell.Each agent prompt MUST include:
circuit-breaker.mdEach agent prompt MUST NOT include:
Housekeeping sessions use a simplified single-wave execution model instead of the multi-wave role-based dispatch:
session-type: housekeeping, total-waves: 1)wave-scope.json — scope enforcement is not needed for low-risk housekeeping tasksstatus: completed when done/close)Focus: git cleanup, SSOT refresh, CI fixes, branch merges, documentation. End with a single commit summarizing all housekeeping work.
| Situation | Action |
|---|---|
| Agent times out | Re-dispatch with smaller scope |
| Agent produces broken code | Add fix task to next wave |
| Tests fail after wave | Diagnose in next wave, don't skip |
| Merge conflict between agents | Resolve manually, document |
| TypeScript errors introduced | Track count, run Full Gate per quality-gates by Quality wave |
| New critical issue discovered | Inform user, add to Impl-Polish+ roles if fits scope |
| Agent edits wrong files | Revert via git, re-dispatch with stricter scope |
After the Finalization wave completes successfully:
/close to finalize the session/close handles that with proper verificationrun_in_background: true during waves — you lose coordination abilityagents-per-wave