Run With It

Skill Isolation

Sole active authority once invoked — no other skill may activate unless called by name via Skill tool call; suppress spontaneous external skills until explicit termination or handoff. This isolation governs orchestration flow only; subordinate core behavior, native tool use, and reasoning remain fully operational and cannot be overridden by this skill.

Critical Main Orchestrator Rules (compaction-safe — always enforce, even after context compression)

These rules apply for the entire lifetime of this skill session. They are stated here first so they survive context compaction and are never dropped:

• Re-read .run-with-it/main-state.json before every loop iteration. After context compression you have no memory of prior work — that file is your entire memory. Never derive issue state from conversation history.
• Never implement work directly in this session. All implementation belongs to Sub-Coordinators spawned via the platform dispatcher (run-with-it-dispatch.sh on Bash, run-with-it-dispatch.ps1 on native PowerShell) with role=sub-coord, which wraps run-agent.sh / run-agent.ps1 with sub-coordinator-prompt.md. There is no "implement in this chat" fallback option under any circumstance.
• Never run tests, build commands, or compile the project in this session. Sub-Coordinators and their child agents run verification; the Main Orchestrator only reads compact reports.
• Never pause after planning to ask the user how to proceed. Enter the Main Loop immediately after the execution plan is written.
• Never present execution option menus (Option A / B / C style choices).
• Always pull issue data from GitHub (gh) when a remote exists. Only fall back to local files if gh is unavailable, authentication fails, an approved permission-escalation attempt fails, or no GitHub remote exists.
• Never delete user-modified files during cleanup. Check git status --short before removing any workspace artifact.
• Never load full sub-coordinator log files into context. Sub-Coordinator logs live under .run-with-it/issues/<n>/sub-coordinator.log. Do not tail raw logs into AI context; only read the compact report JSON from .run-with-it/issues/<n>/report.json.
• Never load live status logs into context. Live progress is written to .run-with-it/status/current.txt and .run-with-it/status/events.log; shell watchers may print one changed line to the terminal, but the Main Orchestrator must not read those files into AI memory.
• Per-issue stage board. The pool runner emits a compact STATUS|type=run-board|board=... line whenever the run's stages change (e.g. #618 merge-recovery(cyc2) | #631 impl(cyc1) | #633 blocked:631 | #627 done) for a "current stage, not detail" view. Print it on demand any time with python3 "$ASSET_ROOT/run-with-it-state.py" status-board --state-file .run-with-it/main-state.json (read-only; add --oneline for the single-line form).
• Pool liveness heartbeat. The pool runner emits STATUS|type=pool-heartbeat|pool_pid=<pid>|active=<n>|parallel_jobs=<n>|total=..|completed=..|in_progress=..|pending=..|blocked=..|waiting_context=.. every POOL_HEARTBEAT_SECONDS (default 60). A heartbeat in the watch output means the pool is alive even when nothing else changed; relay its counts to the user as the periodic progress update.
• Assemble context files for ALL pending issues up front — dependents included. The pool runner can only dispatch issues whose context files already exist on disk; an issue without a context file is invisible to slot filling (full rationale in Step B). If a STATUS|type=pool-waiting-context line ever appears, assemble the missing contexts immediately (Step C) while the pool keeps running.
• Stay attached until every issue is terminal. The Main Orchestrator session must keep running the watch loop, and after each watch window print a one-line user-facing progress update from the newest run-board / pool-heartbeat lines (e.g. Pool alive — 2 running, 3 pending, 4 completed, 1 blocked). Never end the turn, go silent, or declare the run finished while any issue is still pending, in_progress, or merge_recovery. pool-empty with pending issues remaining means GOTO Step A, not done.
• GitHub operations (close, comment, e.g., gh issue close) are the Main Orchestrator control plane's sole responsibility. Sub-Coordinators never touch GitHub. The pool runner performs the per-issue terminal comment/close immediately after reading a terminal compact report.
• Never inspect, infer, or act on a Sub-Coordinator's internal routing decisions. Once a Sub-Coordinator is spawned, the agent and model it selects for its child workers are entirely its own responsibility — the Main Orchestrator has no visibility into, and no authority over, those internal choices. Do not read log files to determine which worker agent or model is running.
• Never kill, cancel, or restart a Sub-Coordinator mid-run. If a Sub-Coordinator appears to be using a different agent or model than expected, that is correct behavior — it is applying its own complexity-based routing. Do not intervene. The only valid responses to a running Sub-Coordinator are: (a) wait for it to complete and write its compact report, or (b) alert the user after SUB_COORD_TIMEOUT_SECONDS and wait for a 'continue' or 'skip' instruction. Sole exception: a user-confirmed discard, which terminates the entire run — supervisor, dispatchers, and runners — through the platform stop helper (run-with-it-stop.sh / run-with-it-stop.ps1) per the Cleanup Discard flow. Never hand-roll kills even then.
• Never inject worker-routing overrides into a Sub-Coordinator that has already been spawned. Canonical worker overrides (FORCED_AGENT, FORCED_MODEL, COMPLEXITY_LEVEL, COMPLEXITY_SCORE) may only be set before spawning, as part of the context file assembled in Step C. After the platform dispatcher calls run-agent.sh / run-agent.ps1, those values are locked and the Main Orchestrator must not attempt to change them.
• Run the platform pool runner (run-with-it-pool.sh / run-with-it-pool.ps1) as the single rolling-pool supervisor. The pool runner spawns Sub-Coordinator dispatch processes, captures each dispatcher PID, and persists issue, pid, started_at, context_file, log_file, done_file, and report_file before monitoring.
• Use the platform worker watcher (worker-watch.sh / worker-watch.ps1) inside the dispatcher for Sub-Coordinator liveness checks during pool monitoring. Pass each dispatch child PID, done_file, and log_file; treat PID liveness as diagnostic only. Completion requires the done sentinel and compact report artifacts.
• All judgments about implementation quality, routing correctness, and worker behavior come exclusively from the compact report JSON. The Main Orchestrator has no other source of truth about what happened inside a Sub-Coordinator session.
• GitHub operations on completion are immediate and sequential. Even when Sub-Coordinators run in parallel, each issue's GitHub comment/close is processed one at a time as soon as that issue reaches a terminal outcome to avoid race conditions.
• Preserve local fallback behavior when GitHub or git is unavailable.
• Keep changes minimal and focused to orchestration/control-plane behavior.

Run With It

Purpose / When To Use

Use after requirement discovery and issue synthesis are complete. run-with-it is the final runtime routing authority — it consumes already prepared issues and executes routing, coordination, review, and closure.

Preferred upstream flow:

1. break-req resolves requirements and constraints.
2. create-git-issue publishes PRD + implementation slices with routing hints.
3. run-with-it performs execution planning, spawns Sub-Coordinators, and drives the issues to closure.

Architecture

run-with-it uses a two-layer architecture to maintain a bounded context window for indefinite run duration:

Main Orchestrator (this skill, runs in the primary session):

• Fetches all ready-for-agent issues once at startup
• Creates one shared run feature branch (Maestro/<funny-action-animal>) from the original base branch, pushes it when a GitHub remote exists, and uses it as the final PR head branch
• Determines execution order with a dependency graph and topological sort based primarily on each issue's ## Blocked by section; cycles or unresolved external blockers are marked blocked before execution
• Maintains a rolling pool of up to PARALLEL_JOBS active Sub-Coordinators via the platform dispatcher — freed slots fill immediately when any job completes rather than waiting for whole batches
• As each Sub-Coordinator completes, reads its compact report, immediately posts the terminal GitHub comment and closes/updates that issue when it has a terminal outcome, then spawns the next ready issue into the freed slot
• Writes its own status log to .run-with-it/main/main.log
• Reads ONLY the compact report JSON — never the implementation diffs or log files
• Updates main-state.json after each issue (its full external memory)
• Posts terminal GitHub comments and closes/updates issues immediately per issue, not only after the full pool finishes
• Spawns a Merge Recovery Coordinator when a Sub-Coordinator reports merge_failed; Main Orchestrator never merges issue branches itself
• Creates one final PR from the shared run feature branch after all issues are terminal, using run-with-it-pr-body.py to render the body from .run-with-it/main-state.json
• Re-reads main-state.json at the top of every loop iteration to survive context compression

Sub-Coordinator (spawned via sub-coordinator-prompt.md, runs in a child agent session):

• Handles exactly ONE issue end-to-end
• Creates an issue branch and issue worktree from the shared run feature branch
• Runs complexity analysis, deterministic routing, gated read-only planning, implementation, review, and modification loops
• Runs child workers with REPO_ROOT pointing at the issue worktree while keeping logs/reports under the root .run-with-it/
• Spawns an Artifact Recovery Worker when implementation/modification artifact retries are exhausted so dirty work can be inspected, verified, committed, or requeued before any terminal blocked report
• Attempts the normal merge back into the shared feature branch under .run-with-it/locks/merge.lock
• Writes a compact report JSON and full log file under .run-with-it/issues/<n>/ when done
• Spawns worker agents whose logs/results/done sentinels are written under .run-with-it/issues/<n>/workers/<role>/
• Never touches GitHub; never updates main-state.json

Plan Worker (spawned via plan-prompt.md, gated, runs after complexity and before implementation):

• Reads the issue worktree read-only with a strong model and writes a concrete approach plan to .run-with-it/issues/<n>/plan.md plus a machine-readable plan.json under workers/plan/
• Never edits or commits — it runs before the baseline SHA so it cannot corrupt the implementer's diff
• Re-scores complexity from the real code; the Sub-Coordinator prefers that grounded band over the blind score when routing implementation and modification (the hybrid refinement)
• Gated by RUN_WITH_IT_PLAN_MIN_COMPLEXITY (default medium-hard) and toggled by RUN_WITH_IT_PLAN_ENABLED (default 1); trivial issues skip planning and route weak regardless
• The implementer, reviewer, and modifier all consume plan.md via RUN_WITH_IT_PLAN_FILE

Artifact Recovery Worker (spawned via artifact-recovery-prompt.md, runs only after exhausted impl/modify artifact failures):

• Inspects the issue worktree, including dirty uncommitted work and preserved recovery patches
• Runs verification and commits salvaged work on the issue branch when the work is complete
• Writes the missing impl or modify result artifact only with concrete commit and verification evidence
• Returns a structured synthesized-result, requeue, or blocked decision to the Sub-Coordinator

Merge Recovery Coordinator (spawned via merge-recovery-prompt.md, runs only after merge_failed):

• Handles one failed issue-branch merge
• Reads the shared feature branch holistically because it contains prior Sub-Coordinator work
• Resolves conflicts or merge-induced verification failures under the same merge lock
• Pushes the shared feature branch on success and writes a compact recovery report
• Never closes issues, creates the final PR, or updates main-state.json

This isolation means each issue's implementation complexity is contained to its own isolated Sub-Coordinator session. The Main Orchestrator's context grows by only one compact JSON record per completed issue, allowing runs of hours or days without context degradation.

Hard Boundaries

• Do not synthesize PRDs.
• Do not author initial issue templates.
• Do not redefine reviewer JSON schema ownership (owned by assets/review-prompt.md).
• Do not modify runner script implementation details.
• Do not mutate registry data definitions in assets/agent-registry.json.

OS Detection

Detect the current OS before asset discovery and runner selection, and capture it in the OS_FAMILY environment variable:

• Windows (native PowerShell) (OS_FAMILY=windows): use .ps1 runners (run-with-it-pool.ps1, run-with-it-dispatch.ps1, worker-watch.ps1, run-agent.ps1) and $env:USERPROFILE for home dir.
• macOS / Linux / Git Bash / WSL (OS_FAMILY=unix): uname -s returns Darwin, Linux, MINGW*, MSYS*, or CYGWIN*. Use .sh runners and $HOME for home dir.

Adapt all shell commands in this skill to the detected runtime:

Inputs

Provide a task summary before execution. All other inputs are optional overrides.

Automatic Worker Model Matrix

After calculating the effective routing band, every non-complexity automatic route uses this exact model set:

Complexity scoring is exempt from this automatic matrix and retains its independent weight-based routing. Review applies its existing one-band increase; planning applies its existing two-band increase before applying the matrix. Explicit FORCED_MODEL values bypass automatic membership but must still pass compatibility and availability checks.

Effective-band effort:

• Sol: high at medium-hard, xhigh at complex and holy-fuck.
• Sonnet 5: low, medium, medium from quite-easy through medium.
• Opus 5: high at medium-hard, xhigh at complex, max at holy-fuck.
• Fable 5: max at holy-fuck.

The generic route effort becomes Codex model_reasoning_effort or Claude Code --effort; Agy receives no effort flag.

Asset Discovery (Required)

Resolve assets in this order:

1. $ASSETS_DEST if set and complete.
2. $HOME/.ai-skill-collections/assets.
3. ./assets.

Shared required files:

• prompt.md
• agent-registry.json
• review-prompt.md
• modifier-prompt.md
• complexity-prompt.md
• plan-prompt.md
• coordinator-rules.md
• sub-coordinator-prompt.md
• main-orchestrator-rules.md
• artifact-recovery-prompt.md
• merge-recovery-prompt.md
• run-with-it-state.py
• run-with-it-github-update.py
• run-with-it-pr-body.py
• run-with-it-router.py
• run-with-it-artifacts.py

Bash required helper files:

• run-agent.sh
• run-with-it-dispatch.sh
• run-with-it-pool.sh
• run-with-it-watch.sh
• run-with-it-stop.sh
• worker-watch.sh

PowerShell required helper files:

• run-agent.ps1
• run-with-it-dispatch.ps1
• run-with-it-pool.ps1
• run-with-it-watch.ps1
• run-with-it-stop.ps1
• worker-watch.ps1

Selection rules:

• Use first path that contains all shared files plus the helper files for the detected platform.
• Bash/macOS/Linux/Git Bash/WSL runs must not require .ps1 helper files.
• Native PowerShell runs must not require .sh helper files.
• Both platform pool runners require python3 (or PYTHON_BIN pointing to a Python 3 interpreter) for shared state, GitHub update, and routing helper scripts.
• If none are complete, stop and report missing files.
• Do not require git to resolve assets.
• Resolved asset root is the single source for that run.

Fresh/No-Git Project Notes

• Without git, this skill supports asset discovery and local-issue intake only; issue branches, worktrees, merges, merge recovery, and the final PR require a git repository.
• Asset discovery is filesystem-based, not git-root-based.
• If assets are missing, report the platform-appropriate one-command fix:

PowerShell (Windows):

New-Item -ItemType Directory -Force "$env:USERPROFILE\.ai-skill-collections\assets"; Copy-Item -Force .\assets\prompt.md, .\assets\run-agent.ps1, .\assets\run-with-it-dispatch.ps1, .\assets\run-with-it-pool.ps1, .\assets\run-with-it-watch.ps1, .\assets\run-with-it-stop.ps1, .\assets\worker-watch.ps1, .\assets\run-with-it-state.py, .\assets\run-with-it-github-update.py, .\assets\run-with-it-pr-body.py, .\assets\run-with-it-router.py, .\assets\run-with-it-artifacts.py, .\assets\agent-registry.json, .\assets\review-prompt.md, .\assets\modifier-prompt.md, .\assets\artifact-recovery-prompt.md, .\assets\complexity-prompt.md, .\assets\plan-prompt.md, .\assets\coordinator-rules.md, .\assets\sub-coordinator-prompt.md, .\assets\main-orchestrator-rules.md, .\assets\merge-recovery-prompt.md "$env:USERPROFILE\.ai-skill-collections\assets\"

Bash (macOS / Linux / Git Bash):

mkdir -p "$HOME/.ai-skill-collections/assets" && cp -f ./assets/prompt.md ./assets/run-agent.sh ./assets/run-with-it-dispatch.sh ./assets/run-with-it-pool.sh ./assets/run-with-it-watch.sh ./assets/run-with-it-stop.sh ./assets/worker-watch.sh ./assets/run-with-it-state.py ./assets/run-with-it-github-update.py ./assets/run-with-it-pr-body.py ./assets/run-with-it-router.py ./assets/run-with-it-artifacts.py ./assets/agent-registry.json ./assets/review-prompt.md ./assets/modifier-prompt.md ./assets/artifact-recovery-prompt.md ./assets/complexity-prompt.md ./assets/plan-prompt.md ./assets/coordinator-rules.md ./assets/sub-coordinator-prompt.md ./assets/main-orchestrator-rules.md ./assets/merge-recovery-prompt.md "$HOME/.ai-skill-collections/assets/" && chmod +x "$HOME/.ai-skill-collections/assets/run-agent.sh" "$HOME/.ai-skill-collections/assets/run-with-it-dispatch.sh" "$HOME/.ai-skill-collections/assets/run-with-it-pool.sh" "$HOME/.ai-skill-collections/assets/run-with-it-watch.sh" "$HOME/.ai-skill-collections/assets/run-with-it-stop.sh" "$HOME/.ai-skill-collections/assets/worker-watch.sh" "$HOME/.ai-skill-collections/assets/run-with-it-state.py" "$HOME/.ai-skill-collections/assets/run-with-it-github-update.py" "$HOME/.ai-skill-collections/assets/run-with-it-pr-body.py" "$HOME/.ai-skill-collections/assets/run-with-it-router.py" "$HOME/.ai-skill-collections/assets/run-with-it-artifacts.py"

Main Orchestrator Rules File

At the very start of execution (before preflight), copy $ASSET_ROOT/main-orchestrator-rules.md to .run-with-it/main-orchestrator-rules.md:

mkdir -p .run-with-it
cp "$ASSET_ROOT/main-orchestrator-rules.md" .run-with-it/main-orchestrator-rules.md

Re-read .run-with-it/main-orchestrator-rules.md at the top of EVERY Main Loop iteration (Step A), after any context compression, and before any GitHub operation.

.run-with-it/main-orchestrator-rules.md (the working copy) is deleted as part of normal cleanup.

Preflight Checks

Before execution verify:

1. Resolved asset root exists and contains all required files listed in Asset Discovery. On Bash, runners (run-agent.sh, run-with-it-dispatch.sh, run-with-it-pool.sh, run-with-it-watch.sh, run-with-it-stop.sh, worker-watch.sh) and Python helpers (run-with-it-state.py, run-with-it-github-update.py, run-with-it-pr-body.py, run-with-it-router.py, run-with-it-artifacts.py) are executable. On native PowerShell, verify the .ps1 runners exist; executable bits are not required.

2. python3 is available, or PYTHON_BIN points to a Python 3 interpreter, for the shared pool helper scripts.

3. gh auth when GitHub intake is required.

4. SUB_COORD_AGENT is installed (detected): on Bash, run "$ASSET_ROOT/run-agent.sh" --list-agents --detected-only; on native PowerShell, run & (Join-Path $ASSET_ROOT "run-agent.ps1") --list-agents --detected-only. Confirm SUB_COORD_AGENT appears.

5. SUB_COORD_MODEL is in SUB_COORD_AGENT's known_models in agent-registry.json.

6. Existing-state detection (resume vs. discard prompt): before any issue intake or fresh task selection, check whether .run-with-it/main-state.json exists in the current working directory.

   • If it exists, pause and present exactly this prompt to the user:

     Existing run state found at .run-with-it/main-state.json.
     Type "resume" to continue the previous run, or "discard" to delete it and start fresh.
     

   • resume: do not delete the file. Proceed to the Resume Flow section.

   • discard: apply the Cleanup Discard policy, then continue with normal preflight and fresh issue intake as if no prior state existed.

   • Do not start any new task, fetch any issue, or spawn any Sub-Coordinator until the user responds.

If any required file from Asset Discovery is missing at the resolved asset root, fail fast with the same platform-appropriate one-line fix message used in asset discovery.

Initial Batch Issue Fetch

If issue data is missing in context, fetch only open issues with the configured intake label (ready-for-agent by default) at startup.

Use ISSUE_LIMIT (default 1000) as the --limit argument — this fetches all matching issues by default. Do not cap the result unless the user explicitly sets ISSUE_LIMIT to a lower value.

gh issue list --state "${ISSUE_STATE:-open}" --label "${ISSUE_LABEL:-ready-for-agent}" --limit "${ISSUE_LIMIT:-1000}" --json number,title,labels,body,url

Fallback policy:

• Primary: GitHub issues via gh. Always use GitHub when the repo has a GitHub remote. Never silently fall back to a local file when GitHub may be reachable.
• If gh fails because the current tool is sandboxed (permission error, named-pipe, socket), use that tool's explicit approved permission-escalation flow when available before considering fallback. If escalation is unavailable or denied, emit STATUS|type=intake-fallback|reason=gh-permission-blocked and use local fallback only when allowed below.
• Fallback: local issues.md (LOCAL_ISSUES_FILE override supported) — only when gh is unavailable, authentication fails, an approved permission-escalation attempt fails, or no GitHub remote exists. Emit STATUS|type=intake-fallback|reason=<no-gh-auth|no-remote|gh-permission-blocked|gh-failed-after-escalation> before using local file.
• If git metadata is unavailable, continue with empty commit context.

Before fetching work begins, create the shared run feature branch:

1. Capture original base branch and SHA.
2. Generate a human-readable branch name as Maestro/<funny-action-animal> instead of a UUID branch.
   • Use a lowercase, hyphenated slug with exactly two words after the prefix: <action-or-trait>-<animal>.
   • Prefer funny but work-safe names such as cunning-fox, unfaithful-lion, scheming-otter, dramatic-llama, sneaky-raven, tapdancing-badger, plotting-penguin, or chaotic-hamster.
   • Do not use raw UUIDs in the branch name.
   • If the generated branch already exists locally or on the remote, generate a different slug; only append a short numeric suffix when several reasonable retries collide.
3. Create Maestro/<funny-action-animal> from that base.
4. Push the branch when a GitHub remote exists.
5. Record run_branch.base_branch, run_branch.base_sha, run_branch.feature_branch, run_branch.feature_branch_start_sha, run_branch.remote, and run_branch.pushed.

After fetching all issues:

1. Filter the fetched issue set before planning: every executable issue must have the configured intake label (ready-for-agent by default). Do not add unlabelled issues, PRD/parent issues, needs-triage issues, or issues discovered only through cross-references to main-state.json.
2. Build a dependency graph only from each executable issue's ## Blocked by section. Normalize #123, full GitHub issue URLs, and plain issue numbers. Treat None - can start immediately as no dependencies.
3. Treat PRD/parent references as context, not dependencies. Ignore issue references from ## Parent, titles such as PRD: ..., labels such as needs-triage, and incidental issue links elsewhere in the body when computing deps.
4. A dependency is actionable only if it points to another fetched executable issue in the same intake set. If ## Blocked by names a PRD/parent issue or an issue outside the intake set, ignore it and record the ignored reference in dependency_proof as non-blocking context rather than marking the issue blocked.
5. Detect cycles and unresolved dependencies among executable issues only; mark affected issues blocked with dependency_proof and blocking_reasons.
6. Determine execution order: topological sort respecting dependencies. Priority order within the same dependency tier: critical fixes → development infrastructure → tracer-bullet feature slices → polish and quick wins → refactors. When PARALLEL_JOBS > 1, issues fill a rolling pool (up to PARALLEL_JOBS active at a time) — freed slots are filled immediately rather than waiting for a full batch to complete.
7. Issues whose executable dependencies have open/unresolved status, merge_recovery, failed-merge, or blocked are not ready until the dependency becomes completed. The pool runner dispatches merge recovery for merge_recovery issues before dependents become ready.
8. Write the complete execution plan to .run-with-it/main-state.json before doing any work. Record parallel_jobs, execution_mode (sequential when PARALLEL_JOBS=1, rolling-pool otherwise), topo_order, dependency_tiers, and each issue's dependency_proof, parallel_safe, and normalized ownership_scope. Derive the concurrency metadata like this:
   • ownership_scope: the list of top-level directories (or deeper paths when the issue is precise) the issue's body, title, and acceptance criteria name. Use plain repo-relative directory paths without glob characters; a glob-bearing scope is compared by its literal directory prefix only, and absolute paths, drive/UNC paths, and ..-escaping paths are rejected as malformed (the issue then runs exclusively).
   • parallel_safe: true unless the issue is a repo-wide refactor, migration, formatting sweep, or otherwise touches files that cannot be attributed to a bounded scope — then set parallel_safe: false to force exclusive execution.
   • concurrency_policy: newly written plans MUST set execution_plan.concurrency_policy: "strict" and derive the metadata above for every issue. Under strict, an issue with missing concurrency metadata runs exclusively — worktrees isolate filesystem conflicts only, not semantic conflicts, migrations, generated files, or shared external resources.
   • Legacy states without concurrency_policy run permissive: missing metadata admits in parallel, relying on worktree isolation plus merge recovery. This fail-open behavior exists only for backward compatibility with states written before the flag; do not write new plans without the flag.
   • Explicit parallel_safe: false, root/malformed metadata, or a proven ownership_scope overlap always defers an issue regardless of policy; the pool runner reports deferrals as STATUS|type=pool-admission-deferred|count=<n>|deferrals=<issue:reason,...>.
9. Emit: STATUS|type=plan|total_issues=<n>|mode=<sequential|rolling-pool>|parallel_jobs=<PARALLEL_JOBS>|pending=<n>|blocked=<n>
10. Emit: STATUS|type=memory-refresh|state_file=.run-with-it/main-state.json|tasks_loaded=<n>|completed=0|pending=<n>

Main Orchestrator Loop

Execute immediately and unconditionally after writing the plan. Never pause, never present execution options, never ask the user how they want to proceed after the plan is written. Enter the loop immediately.

MAIN ORCHESTRATOR LOOP
Repeat until all issues in main-state.json have a terminal status
(completed / failed-review / failed-merge / blocked):

══ STEP A: MEMORY REFRESH ══════════════════════════════════════════════════════
Re-read .run-with-it/main-orchestrator-rules.md from disk.
Re-read .run-with-it/main-state.json from disk.
This is mandatory at the TOP of every iteration, no exceptions.
After context compression, these files are the sole source of truth.

Emit: STATUS|type=memory-refresh|state_file=.run-with-it/main-state.json
      |tasks_loaded=<total>|completed=<n>|pending=<n>|failed=<n>
Emit: STATUS|type=main-loop|iteration=<n>|pending=<count>|completed=<count>
      |failed=<count>

══ STEP B: SUPPLY CONTEXTS FOR THE ROLLING POOL ════════════════════════════════
Compute ACTIVE_POOL = all issues in issue_registry with status="in_progress"
(cross-check against active_pool_issues in state for consistency).

Collect NEWLY_QUEUED = ALL issues with status="pending" that do not yet have a
context file on disk (issue_registry[<n>].context_file unset, or the recorded
path no longer exists) — INCLUDING issues whose dependencies are not yet
completed. Order by priority:
  critical fixes → dev infra → tracer-bullet slices → polish → refactors.

Rationale (do not "optimize" this back to a slot-sized batch): the pool runner
is the only dispatcher, and it can only dispatch issues whose context files
already exist — issues without contexts are invisible to slot filling. Writing
every context up front is what lets the pool fill freed slots immediately and
auto-dispatch dependents the moment their dependencies complete, without
waiting on this session. Context staleness is acceptable: the Sub-Coordinator
re-fetches the issue body when it starts.

For each issue <n> in NEWLY_QUEUED:
  Leave issue status="pending" until the platform pool runner spawns it.
  Record its context file path in main-state.json during Step C.
  The pool runner marks status="in_progress" and appends <n> to
  active_pool_issues when it captures the dispatcher PID.
Emit: STATUS|type=pool-fill|active=<len(ACTIVE_POOL)>
      |newly_queued=<len(NEWLY_QUEUED)>|pending_remaining=<pending_after>
      |parallel_jobs=<PARALLEL_JOBS>

If ACTIVE_POOL is empty and NEWLY_QUEUED is empty:
  Check if any issues remain with status="pending" — if all have unmet deps
  whose blockers are terminal-but-not-completed, re-evaluate them; if still
  unresolvable, mark them "blocked".
  If ALL issues are terminal (completed / failed-review / failed-merge / blocked):
    EXIT LOOP → proceed to Final Ledger and Cleanup.

══ STEP C: ASSEMBLE SUB-COORDINATOR CONTEXT FILES ══════════════════════════════
Repeat for EACH issue <n> in NEWLY_QUEUED:

Build $SUB_COORD_CONTEXT_FILE_<n> (a separate temp file per issue) containing, in order:
  1. Full issue body: re-fetch using:
       gh issue view <n> --json number,title,body,labels,url,comments
     (re-fetch even if pre-fetched at startup — ensures freshest data)
     If gh fails because the current tool is sandboxed, use that tool's explicit approved permission-escalation flow when available. If the approved retry fails and local file exists,
     use cached issue body with a note.
  2. Last COMMITS_LIMIT (default 5) recent commits:
       git log --oneline -<COMMITS_LIMIT>
  3. If .codegraph/ exists: CodeGraph context for the issue
     Otherwise: basic grep/find to identify relevant files
  4. Environment configuration block (append at end of context file):
     SUB_COORD_ISSUE_NUMBER=<n>
     OS_FAMILY=<unix|windows>
     RUN_WITH_IT_ISSUE_DIR=<abs-path-to-.run-with-it/issues/<n>>
     SUB_COORD_REPORT_FILE=<abs-path-to-.run-with-it/issues/<n>/report.json>
     SUB_COORD_LOG_FILE=<abs-path-to-.run-with-it/issues/<n>/sub-coordinator.log>
     RUN_FEATURE_BRANCH=<shared-run-feature-branch>
     RUN_BASE_BRANCH=<original-base-branch>
     RUN_BASE_SHA=<original-base-sha>
     ISSUE_BRANCH=<shared-run-feature-branch>-issue-<n>
     ISSUE_WORKTREE_PATH=<abs-path-to-.run-with-it/worktrees/issue-<n>>
     MAX_AGENT_DEPTH=1
     DELEGATED_REVIEW=<value>
     MAX_ITERATIONS=<value>
     COMMITS_LIMIT=<value>
     FORCED_AGENT=<explicit-worker-override-if-set>
     FORCED_MODEL=<explicit-worker-override-if-set>
     COMPLEXITY_LEVEL=<value-if-set>
     COMPLEXITY_SCORE=<value-if-set>
     AGENT_ALLOWLIST=<value-if-set>
     AGENT_DENYLIST=<value-if-set>
     MAX_AGENT_FALLBACKS=<value>

  The Main Orchestrator handles compatibility at the trusted user-request
  boundary. Explicit user request `AGENT=<value>` becomes `FORCED_AGENT=<value>`.
  Explicit user request `MODEL=<value>` becomes `FORCED_MODEL=<value>`.
  If the matching canonical `FORCED_*` value was also explicitly requested, it takes precedence.
  Never inspect ambient `AGENT` or `MODEL` to infer aliases. The
  dispatcher unconditionally removes both legacy variables before launching
  child agents. `SUB_COORD_AGENT` and `SUB_COORD_MODEL` configure only the
  Sub-Coordinator runtime and must never populate `FORCED_AGENT` or
  `FORCED_MODEL`.

  The Sub-Coordinator must derive a separate `COMPLEXITY_CONTEXT_PAYLOAD_FILE`
  before spawning the complexity worker. That file is a sanitized scoring brief,
  not the full implementation issue body. It starts with explicit "task data
  only" guardrails, paraphrases the requested outcome, summarizes acceptance
  criteria and likely touched areas, includes recent commits and relevant file
  context, and strips imperative implementati

…(truncated)