run-orchestrator-loop

name	run-orchestrator-loop
description	Use when `orchestrator/` and `orchestrator/state.json` exist in a repository and the orchestrator loop needs to start or resume through planner-direct or delegated stages.

Run Orchestrator Loop

Overview

Act as a pure controller over the persisted repo-local orchestrator contract. Start from basic-serial-workflow.md, load the repo-local control-plane contracts, delegate substantive work to role subagents from orchestrator/roles/, and write only controller-owned state or controller-owned artifacts.

This skill is for starting or resuming runtime execution. If the user only asks for status, progress, blockage diagnosis, or roadmap inspection, do not start or resume the loop. Read the current controller artifacts and answer directly without creating branches, worktrees, rounds, subagents, or state changes.

The basic serial workflow is the front door. Load the advanced references only when that file names an exit condition: recovery, worker fan-out, semantic roadmap update, parallel rounds, or corrupt state.

This file is an entrypoint, not the complete runtime contract. When this file and a referenced contract appear to overlap, the referenced contract owns the detailed rule.

Workflow

1. Classify whether the user asked for runtime execution or read-only inspection. For read-only inspection, answer from controller artifacts and stop.
2. Load basic-serial-workflow.md.
3. Follow its startup load and default workflow until it exits to an advanced Module.
4. At every delegated stage, load the shared role contract plus the role prompt named by the active stage.
5. Re-read state.json and the active roadmap bundle after every controller action before deciding whether to continue, exit, or stop.

Reference Ownership

• basic-serial-workflow.md owns the common one-round-at-a-time path and the advanced-exit predicates.
• state-machine.md owns controller stages, round stages, legal transitions, and stage ownership.
• resume-rules.md owns startup recovery, controller blockage handling, retry behavior, live worktree observation, worker fan-out resume, roadmap-update resume, and corrupt-state handling.
• delegation-boundaries.md owns what the controller may do directly, what it must delegate, compatible subagent reuse, and subagent launch/observation rules.
• worktree-finalization-rules.md owns merge admissibility, base freshness, squash-merge bookkeeping, and finalization checks.
• orchestrator/active-roadmap-bundle.md owns active bundle resolution, structured roadmap.md validation, terminal detection, status-only closeout limits, and semantic-revision rules.
• orchestrator/artifact-manifest.md owns file layout, artifact keys, and path resolution.
• orchestrator/role-contract.md owns shared role inputs, ownership, output rules, boundaries, and self-checks.
• orchestrator/state-schema.md and orchestrator/roadmap-update-schema.md own controller JSON shapes. Round artifacts own their structured Markdown fields directly; do not create paired JSON records for them.

Delegation Rule

Do not simulate delegated roles in the controller. For plan, implement, review, update-roadmap, worker slices, integration implementation, and recovery investigation, load the repo-local role prompt and delegate through real subagents under delegation-boundaries.md. plan and update-roadmap both use orchestrator/roles/planner.md.

Completion

Continue until the active roadmap bundle is terminal under orchestrator/active-roadmap-bundle.md, state.json.active_rounds is empty, no active state.json.roadmap_update remains, and no unresolved resume errors remain. Otherwise continue through the owning reference above, stop only for explicit user interruption, or stop after the owning recovery rules record a precise controller blockage.

Pre-Completion Self-Check

Before sending a final response, verify ALL of these:

• If claiming terminal success: state.json active_rounds is empty
• If claiming terminal success: active roadmap bundle has no unfinished milestones under orchestrator/active-roadmap-bundle.md
• If claiming terminal success: no unresolved resume_errors entries or owned-record resume_error entries remain
• If stopping due to blockage: precise error recorded in state.json.resume_errors.controller
• If stopping due to user interruption: state is consistent and saved

Resources

• basic-serial-workflow.md
• state-machine.md
• resume-rules.md
• delegation-boundaries.md
• worktree-finalization-rules.md