orchestrate-execution

Imported from roborew/opencode-config (skills/orchestrate-execution/SKILL.md). Install upstream with npx skills add roborew/opencode-config --skill orchestrate-execution. Copyright stays with the author.

Hard Rules live in the orchestrate agent markdown; this skill adds protocol detail only for execution (steady path and completion gates). Non-negotiables—delegation, scribe trust, brevity—come from the agent, not from this file.

Orchestrate (execution)

You execute an existing plan artifact by coordinating subagents. You do not edit files directly.

Tool Awareness (critical)

You have the Task tool to invoke subagents (scribe, worktree-env, preflight, developer, frontend-dev, ux-dev, verifier, helper, vision, senior-dev, review). You do not have write or edit tools—by design. Never ask the user to enable write/edit.

No bash tool: You cannot run shell yourself. Route by task type:

• Bootstrap / env readiness → Task worktree-env (env copies), then Task preflight (runtime, deps, smoke, indexing). Never route bootstrap shell to developer.
• Implementation → developer, frontend-dev, or ux-dev.
• GitHub / helper scripts → developer (load: minimal).

Markdown writes (artifact updates only) are done by delegating to scribe. You do not run final review or documentation—those are architect responsibilities after you prompt handoff. On completion, prompt user to switch to architect.

Supplementary Hard Rules (agent overrides on conflict)

1. Never write or edit files directly.
2. Always use scribe for docs markdown writes — not for GitHub issue bodies.
3. Execute one stage at a time and require completion report before next stage.
4. Run verifier at stage gates and before final completion. Run CodeRabbit gate via review once at orchestration completion (after the entire GitHub feature queue) — never per stage, per GitHub issue, or mid-queue.
5. Trigger helper when any enforced condition is met (see orchestrate-recovery for trigger detail and recovery steps).
6. Do not create new retry artifacts; amend existing issue via scribe.
7. Do not wait for manual @scribe prompting; invoke required subagents automatically.
8. You MUST delegate work through Task calls (scribe, worktree-env, preflight, developer, frontend-dev, ux-dev, verifier, helper, vision, senior-dev, review) and never perform those tasks yourself.
9. If you have not issued a required Task call for the current stage, you are not allowed to declare stage progress.
10. You must grade each child response before deciding next action.
11. Do not advance stages on incomplete/low-evidence child reports.
12. Brevity: Concise structured output; no reasoning narration unless the user asks; never repeat unchanged plan sections (deltas only).
13. Claude Context readiness. Before work selection or discovery-heavy delegation, call get_indexing_status for the workspace path. If the index is missing, stale, or not ready, call index_codebase, then re-check until ready. Run after preflight when the user opts in during bootstrap.
14. Preflight prompt (session bootstrap). On greeting or fresh context with no work source yet: ask “Run preflight now? (yes/no)” unless env_gate_passed or env_gate_declined is already set this session. Do not show the work-selection menu until the user answers and any opted-in preflight finishes (or is skipped). Do not re-ask if preflight already passed or was declined this session.

Required Inputs

• Stage order and acceptance checks from artifact

Environment readiness gate (on user opt-in)

Run only when the user answers yes to the preflight prompt, requests a preflight rerun, or remediation requires it after Blocked / ENV_BLOCKED.

Mandatory routing: Issue Task calls to worktree-env and preflight only. Do not narrate "delegating shell to developer" during bootstrap — that rule applies to GitHub/stage execution, not env readiness.

Bootstrap state (session)

Track during bootstrap:

• worktree_env_checked: true after worktree-env completes with canonical evidence (or a skip status)
• worktree_env_evidence: { wt_root, main_root, files[] } from the child report
• preflight_repair_attempted: true after one automatic preflight repair pass

Repair-first flow (one pass before blocking)

1. Worktree env (once per bootstrap unless canonical contradiction):

   • Invoke worktree-env via Task with load: full unless worktree_env_checked: true and the prior report had worktree_env: ok | skipped_not_linked_worktree | skipped_not_git with canonical evidence.
   • Grade the report: require wt_root, main_root, files[] with per-file source, target, is_regular_file, and status (ok | ok_existing | …).
   • On worktree_env: ok with evidence: set worktree_env_checked: true, store worktree_env_evidence, do not invoke worktree-env again this bootstrap unless a later canonical verification contradicts it.
   • On failed_cp or ENV_BLOCKED: retry worktree-env once; if still failing, stop with one recommended_env_fix — no multi-option menus.

2. Preflight (repair pass):

   • Invoke preflight via Task with load: full. Instruct: repair-first — run documented setup/repair commands once when checks fail (mise-prefixed runtime, dependency install, indexing); include canonical env copy evidence on worktree checks.
   • If preflight reports env copy failed while worktree-env reported ok: do not immediately re-run worktree-env. Require contradictory canonical evidence from preflight (wt_root, main_root, per-file test -f + test ! -L). If contradiction is proven, run one canonical verification via preflight load: minimal (bash only: test -f / test ! -L for each file) or retry worktree-env once — not both.
   • If Status: Blocked with a repairable cause (missing node_modules, wrong PATH node vs .mise.toml, not indexed): when preflight_repair_attempted is false, instruct preflight to run the repair pass once, set preflight_repair_attempted: true, then re-Task preflight once. If still Blocked, stop with one recommended_env_fix — no (a)/(b)/(c) menus.
   • If Status: Blocked with an unsafe cause (missing env copy, runtime missing entirely, install failed after repair): stop with one remediation line.

3. On success: set env_gate_passed: true. If the preflight report includes sandbox / expose, store sandbox_status (ready | unavailable) for Docker sandbox routing. Return a brief structured report (deltas only).

Loop guard: If worktree-env or preflight returns the same success/blocker report twice with identical canonical evidence, treat as LOOP_DETECTED — do not re-invoke that subagent; report the contradiction or blocker once.

Do not re-run the full gate between stages or between GitHub issues unless the user asks or recovery policy applies.

Checkout identity gate (mandatory — independent of preflight)

Preflight is optional; current checkout and branch identity are not.

Run before work selection, before any GitHub issue transition to state:in-progress, and before any implementation dispatch (GitHub or legacy .plan). Declining preflight (env_gate_declined) does not skip this gate.

Session state

Track:

• checkout_contract: JSON from checkout-contract.sh with impl_repo_path, branch, is_linked_worktree, main_checkout_root, protected_branch, head_sha, branch_policy
• checkout_identity_verified: true after successful capture

Procedure

1. Task developer load: minimal:

   OC="${OPENCODE_CONFIG:-$HOME/.config/opencode}"
   bash "$OC/skills/github-issue-run/lib/checkout-contract.sh"

2. Grade: require status: ok, non-empty impl_repo_path and branch.
3. If protected_branch: true (develop/main/master): stop before implementation or state:in-progress; ask user to confirm working on a protected branch or switch to a feature/topic branch.
4. Set checkout_identity_verified: true; store checkout_contract for the session.
5. Export for helper scripts when delegating shell:
   • OPENCODE_EXPECT_REPO_ROOT=<impl_repo_path>
   • OPENCODE_EXPECT_BRANCH=<branch>

Execution dispatch contract (required on every implement/verify Task)

Include in every Task to developer, frontend-dev, ux-dev, and verifier for implementation work:

impl_repo_path: <absolute verified git root>
expected_branch: <current verified branch>
is_linked_worktree: true|false
main_checkout_root: <absolute root when detectable>
branch_policy: do not create, switch, checkout, or rename branches unless user explicitly requests in this turn

When Docker sandbox routing applies (below), also include sandbox: preferred|required, optional publish_review_url: true|false, and the load/sandbox exec instructions from that section.

Additional verifier-only fields (required every verify Task):

issue_number: <n>   # GitHub mode — verifier fetches the issue directly for the checklist
repo: <owner/name>  # GitHub mode
diff_base: <parent commit SHA or base ref>
files_changed: <list from implementer report>   # evidence to inspect, NOT authoritative scope
acceptance_to_test: <mapping from implementer report>  # claim to check against the issue, NOT the checklist
red_phase: <RED test evidence from implementer report>
green_phase: <GREEN test evidence from implementer report>
assertion_delta: <from implementer report>
security_review: auto  # default; verifier computes required|not_applicable from triggers
compose_test_file: <docker-compose.test.yml | compose.test.yaml | none>  # required when test_commands present

Independent verifier (GitHub mode): instruct the verifier to fetch the issue directly (gh issue view <n> --repo <repo> --json body) and derive the acceptance criteria, scope, and test_commands from it. The developer's acceptance_to_test / files_changed are evidence to be independently checked against the issue, never the authoritative checklist. The verifier must verify against the full issue criteria and flag any developer-narrowed scope. In .plan mode, the artifact is the source of truth.

Docker-default verification (every verify Task with test_commands): always include sandbox: preferred + load skill: docker-sandbox + compose_test_file, and instruct the verifier to run test_commands via the Docker path (Sysbox sandbox exec on opencode-server, or direct docker compose -f <compose_test_file> on local dev when the sandbox CLI is absent). This is the default, not conditional on compose mentions. Host execution is only APPROVED-eligible when the user explicitly approves it for a confirmed-host-runnable project.

Subagents must cd to impl_repo_path, verify branch matches, and report CHECKOUT_CONTRACT_FAILED on mismatch. They must never create branches or run git switch/git checkout <branch>/git branch on their own.

Provider fallback dispatch contract (additional recovery path)

When a bounded child Task fails and orchestrate-recovery paths (same-agent transient retry, helper amendment, optional operator-confirmed senior-dev escalation) are exhausted for the same Task, dispatch a provider-fallback subagent. This is the last retry path, not a replacement for helper / senior-dev.

Chain

Default chain: kilo-fallback (Kilo / MiniMax-M3) → openrouter-fallback (OpenRouter / GPT-5.6 Luna). Operator can name either explicitly (use Kilo fallback, use OpenRouter fallback); otherwise the chain runs in order.

Eligibility

• original_agent MUST resolve to a child role eligible from the orchestrate Task allowlist (developer, frontend-dev, ux-dev, verifier, scribe, worktree-env, preflight, vision, helper, senior-dev, review). Never a primary agent (orchestrate / architect), never another fallback.
• The original task_contract and original_skill apply unchanged to the fallback. Fallback cannot broaden scope, switch branches, advance stages, or skip gates.

Task prompt template (fallback dispatch)

When dispatching kilo-fallback or openrouter-fallback, include in the Task prompt (alongside the execution dispatch contract above when the original was an implement/verify task):

fallback_context:
  original_agent: <child role that failed>
  original_skill: <skill name; do NOT infer from transcript>
  task_contract: <verbatim original Task prompt>
  failure_evidence: <error class, retry count, unfinished work>
  attempt_history: <providers and load levels already tried for this Task>
  recovery_strategy: <short helper/scribe amendment summary, or omit for transient provider failures>
  requested_provider: kilo | openrouter   # when operator named one explicitly
# plus, when the original was an implement/verify Task:
impl_repo_path: <absolute verified git root>
expected_branch: <current verified branch>
is_linked_worktree: true|false
main_checkout_root: <absolute root when detectable>
branch_policy: do not create, switch, checkout, or rename branches unless user explicitly requests in this turn
diff_base: <parent commit SHA or base ref>
files_changed: <list from implementer report>
acceptance_to_test: <mapping from implementer report>
red_phase: <RED test evidence from implementer report>
green_phase: <GREEN test evidence from implementer report>
assertion_delta: <from implementer report>
security_review: auto
sandbox: <pass-through from original Task; or omit>
publish_review_url: <pass-through; or omit>

The fallback loads fallback-dispatch then original_skill (in that order) before any substantive work. If original_skill fails to load, the fallback returns SKILL_UNAVAILABLE: <original_skill>; treat that as a fallback stop, not as FALLBACK_EXHAUSTED.

Attempts and grading

• One attempt per provider per bounded Task. Track attempted_providers per Task — do not retry the same provider twice or loop between providers.
• The fallback completion report carries the original role's completion payload verbatim plus a fallback_used: { original_agent, original_skill, fallback_agent, provider, model, attempt_number, recovered_from } envelope. On this attempt's own provider failure the fallback emits only fallback_used.provider_failure plus blocker_code: PROVIDER_FAILURE (no partial original schema).
• Grade fallback reports using the same rubric as the original role's report (report_grade: PASS | NEEDS_RETRY | BLOCKED). The fallback_used envelope is metadata only — never lowers the bar or excuses missing evidence.
• On successful fallback, resume the normal workflow at the next normal gate (verifier, review gate, etc.).
• A pasted fallback completion report follows the manual handoff recovery flow in orchestrate-recovery.

Exhaustion

After both kilo-fallback and openrouter-fallback fail for the same Task, halt with FALLBACK_EXHAUSTED listing the original role, both attempts, both providers, both error classes, unfinished work (files / commands / tests remaining), and any partial evidence. Ask the operator how to proceed (retry with a fresh context, accept partial work, abandon, or relax a constraint). Do not invent a third provider.

Docker sandbox routing

Orchestrate does not load skill docker-sandbox. Instruct implementer/verifier Tasks to load it when compose/Docker or review publish applies. Do not conflate with Cloudflare Workers Sandbox (skills/cloudflare/references/sandbox/ — different product).

Session state

Track when known:

• sandbox_status: ready | unavailable | unknown (from preflight report when env gate ran; else unknown until a child probes)
• publish_review_url: true | false | unset
• sandbox_compose_path: documented compose file when detected (e.g. docker-compose.test.yml)

When routing applies

Treat as compose/Docker work if any are true:

• test_commands, acceptance, or stage objective mention docker compose, docker-compose, Compose, or Sysbox/sandbox exec
• Issue/stage asks for a feature review URL / {slug}.{apex} / web expose
• Parent/user asks for sandbox compose build/test or review publish
• Preflight reported sandbox: ready and the impl repo has a documented compose test file (docker-compose.test.yml, compose.test.yaml, or README-documented equivalent)

Review URL ask (once per session)

When routing applies and publish_review_url is unset: ask “Publish review URL?” (yes/no) once. Set publish_review_url from the answer. Do not ask again this session unless the user changes it. Skip the ask when the user already requested or declined review publish in this turn.

Task prompt instructions (developer / frontend-dev / verifier)

When routing applies, include on implement and verify Tasks (in addition to the execution dispatch contract):

sandbox: preferred   # or required when stage/issue explicitly requires Compose
load skill: docker-sandbox
# probe first; if ready: create → sandbox exec for compose test_commands → destroy (always)
# if sandbox CLI absent but docker present (local dev): direct `docker compose -f <compose_test_file>` (same compose file)
# if neither available: Blocked (do not silently fall back to host for test_commands)
publish_review_url: true|false
# when true and sandbox ready: after stack is up, sandbox expose + cloudflare-api via MCPJungle tunnel hostname + optional DNS per docker-sandbox; never tunnel create

• Prefer wrapping Docker/docker compose entries in test_commands as sandbox exec --id <slug> -- <command> when probe is ready; keep non-Docker lint/type/unit commands on the host/worktree as usual.
• Soft-skip when unavailable unless sandbox: required.
• Never instruct ad-hoc docker run --runtime=sysbox-runc or host docker.sock into app compose.

Session Bootstrap (mandatory, first in fresh context)

When no artifact path or feature:<slug> is provided (new session, greeting, unspecified task):

1. Preflight choice — unless env_gate_passed or env_gate_declined is already set this session, ask: "Run preflight now? (yes/no)" and wait for the answer. Do not list work options yet.
   • yes → run Environment readiness gate above (repair-first, one auto-retry); on hard Blocked report one fix; on Ready continue.
   • no → set env_gate_declined: true; do not run preflight this session unless the user later asks to rerun.
   • Already env_gate_passed or env_gate_declined → do not ask again; continue.
2. Checkout identity gate (above) — mandatory even when preflight was declined.
3. Claude Context readiness gate (below).
4. Fresh Context: Work selection — present the (1)/(2)/(3)/(4)/(5) menu only after steps 1–3 are resolved.
5. Issue-expand readiness gate (GitHub backlog (1) only — after slug is captured from menu choice) — see below.

When the user provides a .plan path or feature:<slug> before bootstrap completed: if neither env_gate_passed nor env_gate_declined, ask the preflight yes/no first; run checkout identity gate; run Claude Context readiness gate; run issue-expand readiness gate for feature:<slug> only (after slug is captured); then enter the stage or GitHub loop.

Claude Context Readiness Gate (mandatory)

On fresh context, and before delegating discovery-heavy planning or review work:

1. Call claude-context get_indexing_status for the workspace path.
2. If the index is missing, stale, or not ready, call index_codebase, then re-check until ready before continuing.
3. If claude-context is unavailable or indexing still fails after retry, report that readiness could not be confirmed. Continue only for non-discovery steps; any discovery-heavy child must still enforce its own readiness gate before falling back to bash, glob, or rg.

Issue-expand readiness gate (GitHub backlog — mandatory)

Orchestrate never runs issue-expand. It only verifies that planning completed in the spec architect session.

After checkout identity gate, Claude Context readiness gate, and after the user has chosen GitHub backlog option (1) and provided the slug — run before entering the GitHub backlog loop:

1. Task developer load: minimal with OPENCODE_EXPECT_REPO_ROOT from checkout_contract:
   • opencode-run impl orchestrate-readiness-check <slug>
2. PASS — substantive Implementation plan and non-empty stages[] on every open issue; proceed to the backlog loop.
3. FAIL — stop; do not enter flat mode or implement placeholder issues. Emit a table handoff: return to spec repo → architect option 1 (issue-expand) with the slug; include readiness-check stderr summary.
4. Re-run — if issues are already expanded, readiness check passes immediately; orchestrate does not re-expand.

Fresh Context: Work selection (mandatory)

After session bootstrap (steps 1-3 above), when no artifact path or feature:<slug> is provided:

1. Present the work-selection menu verbatim from the orchestrate agent Fresh Context: Session Bootstrap + Work Selection block ((1) GitHub backlog first; (2) sandbox build/refresh; numbers match display order).
2. On (1): obtain kebab slug if missing; run issue-expand readiness gate if not already done; then proceed to GitHub feature backlog loop.
3. On (2): proceed to Sandbox feature build mode (below). Do not run issue-expand.
4. On (3): stop and prompt: switch to architect with the user's goal (e.g. Mode F sign-off, new planning).
5. On (4): ask for a one-line description; route to architect for non-backlog work unless the user supplies a feature:<slug>, issue #, or explicit execution scope—then use (1) or targeted issue flow as appropriate. If they ask only for sandbox build/refresh, use (2).

Sandbox feature build mode (menu (2) — parallel workflow)

Purpose: Build / test / optionally publish the current checkout feature branch in a Sysbox sibling without running the GitHub issue queue. Typical use: start a sandbox build while doing other work (e.g. frontend) in another session; later say refresh after code changes.

Orchestrate does not load docker-sandbox. Task developer (load: full) with that skill.

Session state

Track:

• sandbox_build_active: true after a successful create (or reuse) for this session
• sandbox_slug: DNS-label slug (from branch / feature / user)
• sandbox_compose_file: e.g. docker-compose.test.yml
• publish_review_url: true | false
• review_url: last reported https://{slug}.{apex} when exposed

Procedure (first run or menu (2))

1. Ensure checkout identity gate has run. If protected_branch: true, stop and ask user to switch to a feature/topic branch (same as other execution).
2. Derive sandbox_slug: sanitize current branch to a DNS label, or ask once for kebab slug / feature:<slug>.
3. Ask build intent once if unclear (default a when user said “build”):
   • (a) build + test — compose build + compose run --rm test (or documented test service), then keep sibling for refresh or destroy if user prefers teardown
   • (b) live stack — compose up -d (self-contained + Caddy) for review; keep sibling running
   • (c) refresh — reuse existing sibling if sandbox status ready; re-build / re-up / re-test only
4. Ask “Publish review URL?” when intent is (b) or user wants expose; set publish_review_url. For (a) default no unless asked.
5. Task developer with:

   execution_mode: sandbox_feature_build
   load: full
   load skill: docker-sandbox
   sandbox: required
   sandbox_action: create_build_test | up_live | refresh
   publish_review_url: true|false
   sandbox_slug: <slug>
   impl_repo_path / expected_branch / branch_policy from checkout_contract

   Instruct: probe → env gate → create (or reuse) → exec documented compose → optional expose + CF tunnel/DNS per skill → report sandbox_id, commands run, review_url if any, keep-or-destroy. Soft-skip only if probe unavailable and user accepts — otherwise Blocked with one remediation (enable Sysbox / rebuild image).
6. Grade child report: require probe result, compose commands + exit evidence, destroy-or-keep note. On PASS: set sandbox_build_active, store slug / URL; print a short status table.
7. Stay available for refresh: after PASS, prompt once:

   Sandbox ready. Say: refresh (rebuild after code changes) | expose (if not yet) | destroy | or pick another menu option (1)/(3)/(4)/(5).

   On refresh / expose / destroy: re-Task developer with the same execution_mode and sandbox_action: refresh|expose|destroy — do not re-run issue-expand or the backlog loop.

Soft-skip / unavailable

If sandbox probe is unavailable (Mac / OPENCODE_SANDBOX_MODE=off): report once; do not invent docker.sock. Offer to return to the work menu.

GitHub feature backlog loop

Use this path after spec fanout and issue-expand in the spec repo (feature:<slug>, state:ready-for-agent, opencode-task-json with non-empty stages[]). You have no bash tool — for this loop only, delegate every gh invocation and helper script to developer via Task (load: minimal for pure shell, load: full for implementation). (Bootstrap env shell uses worktree-env / preflight, not developer.)

Load github-issue-run together with this skill when the user chooses GitHub execution or provides a feature:<slug> / kebab slug.

Prerequisite: Issue-expand readiness gate above must PASS before step 1 of the loop below.

Config path for helper scripts

"${OPENCODE_CONFIG:-$HOME/.config/opencode}/skills/github-issue-run/lib/<script>.sh"

Loop

1. Obtain kebab-case feature slug from the user if missing.
2. Ensure checkout identity gate has run (checkout_identity_verified: true). If not, run it before step 3.
3. Task developer load: minimal: bash "$OC/skills/github-issue-run/lib/next-runnable-issue.sh" "<slug>" — capture stdout JSON. Do not run unscoped gh issue list; discovery is label-filtered server-side by the helper only.
4. Task developer load: minimal with OPENCODE_EXPECT_REPO_ROOT and OPENCODE_EXPECT_BRANCH set from checkout_contract: issue-state-transition.sh "<repo>" "<number>" state:in-progress
5. Stages vs flat issue: Parse opencode_meta from the discovery JSON.
   • If stages is a non-empty array (from issue-expand): run GitHub issue stage loop below for this issue only — do not advance to the next issue until all stages pass verifier.
   • Else flat mode: blocked on spec-driven path — readiness gate should have prevented this. Stop and return user to spec architect option 1. Flat mode applies only to legacy targeted issues without stages[] when explicitly not using the spec fanout path.
6. Implement (flat mode): Task developer or frontend-dev per opencode_meta.owner with load: full. GitHub issue contract:
   • execution_mode: github_issue
   • issue_number, repo, title
   • opencode_meta verbatim
   • impl_repo_path, expected_branch, is_linked_worktree, main_checkout_root, branch_policy from checkout_contract
   • When Docker sandbox routing applies: sandbox: preferred|required, publish_review_url, and load/sandbox exec instructions from that section
7. Verify (flat or per-stage): Task verifier with load: full and the same contract plus completion report (include sandbox fields when routing applies). Instruct the verifier to fetch the issue directly (gh issue view <n> --repo <repo> --json body) and derive the checklist from it — the developer's handoff is evidence to check, not the authoritative scope.
8. Grade using Child Report Grading Gate (git_commit with Refs: #<issue_number> when files changed).
9. On PASS (flat or all stages done): transition state:ready-for-review; optional gh issue comment with summary and commit hash. Do not run CodeRabbit here — one feature-wide gate runs after the queue is exhausted (see Exit when queue empty).
10. On FAIL: state:blocked or helper per orchestrate-recovery — do not advance queue.
11. Repeat from step 3 for the same slug until discovery fails.

GitHub issue stage loop (opencode_meta.stages)

When stages[] is present, for each stage in order:

1. Task owner from stage.owner (developer | frontend-dev) with load: full and contract:
   • execution_mode: github_issue_stage
   • issue_number, repo, stage_id, stage object (objective, files, acceptance, test_commands, commit_message)
   • issue_ref: #<n> for commits
   • impl_repo_path, expected_branch, is_linked_worktree, main_checkout_root, branch_policy from checkout_contract
   • When Docker sandbox routing applies: sandbox: preferred|required, publish_review_url, and load/sandbox exec instructions from that section
2. Task verifier with the same stage contract + completion report (include sandbox fields when routing applies). Instruct the verifier to fetch the issue directly (gh issue view <n> --repo <repo> --json body) and derive the acceptance criteria, scope, and test_commands from it — the developer's handoff is evidence to check, not the authoritative checklist. The stage is BLOCKED until this Task returns APPROVED; do not advance to stage N+1, do not transition the issue, and do not close the implementer's todo until the verifier's completion report is graded PASS with APPROVED. A missing verifier Task is a BLOCKED stage, not an in-progress one.
3. Post the per-stage verifier gate comment via Task developer load: minimal (gh issue comment) before advancing to stage N+1. The same Task must also set the verified label atomically with the comment (gh issue edit <n> --repo <repo> --add-label verified --remove-label unverified):

   verifier_gate:
     issue: #<n>
     stage: <stage_id>
     verdict: APPROVED
     report_grade: PASS
     test_ids: [...]
     coverage: direct=<n> indirect=<n> manual=<n> missing=<n>

4. Require git_commit subject aligned with stage commit_message and Refs: #<issue_number> (final stage may use Closes: #n).
5. After the last stage PASS, post the final gate comment that issue-state-transition.sh checks before state:ready-for-review. The same Task must also set the verified label atomically with the comment (gh issue edit <n> --repo <repo> --add-label verified --remove-label unverified):

   verifier_gate:
     issue: #<n>
     all_stages: true
     stages_verified: <N>
     verdict: APPROVED

6. On stage FAIL: retry or helper; do not advance stage index.
7. After last stage PASS (final gate comment posted): proceed to step 8 (ready-for-review only — no CodeRabbit per issue).

Exit when queue empty

When discovery fails (queue exhausted):

1. CodeRabbit gate (once per feature): When difficulty is not easy, run the CodeRabbit gate section below before opening/finishing the PR. Review all implementation changes on the feature branch (aggregated files_changed / commits since base). Do not re-run CodeRabbit for individual issues you already marked ready-for-review, and do not re-run it after remediation. On CODERABBIT_GATE: BLOCKED, remediate every numbered finding that is not explicitly deferred → verifier checks the local fixes → continue without a second CodeRabbit call. On CODERABBIT_GATE: PASS (or easy), continue.
2. Task developer load: minimal with OPENCODE_EXPECT_* from checkout_contract: bash "$OC/skills/github-issue-run/lib/feature-finish-pr.sh" "<slug>" — parse JSON (branch, base, pr_url, action, message).
3. Run Difficulty-based completion gates when applicable (GitHub-only: assume medium unless user/issue meta says otherwise).
4. Enter Post-PR stabilization (see section below) — do not immediately hand off to architect.
5. After stabilization is finalized, report the sealed bundle including pr_url or skip reason inside the mandatory Completion report template below.
6. Prompt with the table-driven sign-off handoff from Completion (mandatory). Do not use a standalone generic sentence such as "Switch to architect" without the feature slug/name, PR, and next-step table.

Opt-out: ORCHESTRATE_AUTO_PR=0 or user instruction not to open a PR. Protected branch: if session is on develop/main/master, script skips push/PR — do not attempt to move commits retroactively.

Remediation session (user first message includes Remediation: or architect remediation handoff): when queue empties, skip CodeRabbit gate (already ran on initial orchestration). Push to existing PR via feature-finish-pr.sh (pr-exists expected). After stabilization, emit the remediation-return script (not first-complete script) pointing to impl architect option 4 → R.

Post-PR stabilization (bounded — after PR, before architect handoff)

After feature-finish-pr.sh creates or updates the PR, do not immediately issue the architect Phase R handoff. Enter execution_mode: pr_stabilization inside the same orchestrator session.

Stabilization checklist (user-controlled):

1. Collect current state:

   • Current PR checks, mergeability, review threads/comments, CodeRabbit/Kilo/bot comments, and the one-shot CodeRabbit CLI inventory already captured by orchestrate.
   • Never poll indefinitely for external review bots; report the current feedback timestamp and hand control to the user when external feedback is still pending.

2. Ask for product acceptance feedback:

   • Use a concise structured prompt: tested flows, failures, visual/runtime concerns, and intentional deferrals.

3. Classify each finding:

   • fix-now: must be traceable to a named issue/remediation item and executed through the normal developer → verifier lane.
   • defer: with rationale.
   • not-applicable: with reason.
   • awaiting-external-review: still pending.

4. Execute fix-now findings:

   • Execute through developer → verifier lane.
   • After remediation, re-check only affected tests, PR checks, and affected feedback threads; push the changes.
   • Never re-run CodeRabbit CLI.

5. Stabilization checkpoint:

   • Present a checkpoint instead of architect handoff while feedback is pending or the user wants another review round.
   • Each round collects the latest hosted comments/checks and user feedback together, groups fix-now findings into one remediation queue.
   • The checkpoint must offer only two exits: review another round or finalize stabilization.
   • On review another round, collect only deltas since the previous checkpoint and repeat.
   • On finalize stabilization, collect a final PR delta, record a cutoff timestamp, and create the sealed evidence bundle.
   • External feedback that arrives after the cutoff is architect-relevant only if new and material.

Stabilization remediation scope:

• Automatically execute only concrete CodeRabbit/Kilo/human/CI findings with clear acceptance conditions and no product-scope ambiguity.
• Publish a remediation issue before implementation when the finding is a material change, crosses stage boundaries, or lacks a clear acceptance condition.
• Defer speculative style suggestions and non-blocking observations with rationale.
• Do not use architect for deciding ordinary local fixes.

Sealed PR stabilization report:

• PR URL, branch/base, CI/check state, mergeability.
• All review comments with status and resolution evidence.
• One-shot CodeRabbit inventory and resolution status.
• Verifier results, coverage/security/sandbox evidence.
• User acceptance feedback and whether each item was fixed/deferred.
• Open remediation issues (must be none unless explicitly deferred).
• stabilization_status: ready_for_architect|blocked and a feedback_cutoff_at timestamp.

Prerequisite (enforced): Issue-expand readiness gate — substantive Implementation plan and non-empty stages[] in opencode-task-json. Orchestrate does not run issue-expand.

Completed-stage context compression

After a stage is COMPLETE and verifier has APPROVED, keep a running handoff state in a few lines (last_completed_stage, one-sentence outcome, next_stage_id). Do not re-quote full prior transcripts, verifier checklists, or stale child reports for later stages unless the user asks or a regression explicitly requires it. Prefer current stage + next action when updating the user.

Delegation Gate (mandatory)

Before any stage status update, confirm these Task calls occurred:

• Execution: developer, frontend-dev, or ux-dev — must match the stage's Owner. Strict TDD required: Execution subagents must report red_phase then green_phase evidence with matching test ids plus an acceptance_to_test mapping for every numbered criterion. Do not advance the stage on tests that were only green, on a missing/mismatched RED, or on an unexplained assertion_delta.
• Verification (mandatory, not advisory): a verifier Task must have run for this stage, with a completion report graded report_grade: PASS. A missing verifier Task is a BLOCKED stage, not an in-progress one.
• Recovery: helper on trigger conditions
• Image review: vision when child reports IMAGE_REVIEW_NEEDED (see Image Review Gate)
• Each child Task instruction explicitly required a one-shot final report_to_parent payload (completion or blocker) followed by immediate return

If any required call is missing, stop and issue the missing Task call first.

Image Review Gate

When a child (developer, frontend-dev, ux-dev, verifier) reports IMAGE_REVIEW_NEEDED: path=<path> context=<what to verify>:

1. Invoke vision with the image path and context.
2. Require vision agent to return structured analysis.
3. Pass the analysis back to the requesting agent as context for the next task (or re-dispatch with analysis).
4. Do not advance stage until vision analysis is incorporated.
5. Do NOT auto-invoke vision on every test run; only when the child explicitly requests it because the model needs to see the UI. If a stage has no Owner, invoke helper to amend the artifact before dispatching.

Child Report Grading Gate (mandatory)

For every child completion report, assign:

• report_grade: PASS | NEEDS_RETRY | BLOCKED

Use this rubric:

• PASS only if all are present:
  • expected stage_id
  • files changed list (including test files when stage adds/changes behavior)
  • red_phase evidence — failing test output from before the code change, demonstrating the bug or the desired-but-unimplemented behavior. For brand-new behavior this is the new test failing on the unfixed code; for behavior changes it is the updated/new test failing on the pre-change code.
  • green_phase evidence — the same test(s) passing after the code change, with the exact same test identifier so RED can be matched to GREEN.
  • assertion_delta — if any test assertion was removed or weakened, it is listed explicitly with a one-line justification. Surface this for verifier scrutiny. (Empty list is fine; a missing field is not.)
  • acceptance_to_test mapping — for every numbered acceptance criterion in the issue/artifact, the report names the test (file + test name + line) that proves it. Criteria without a test are listed separately under uncovered.
  • no unresolved blockers
• NEEDS_RETRY if output is low quality/incomplete:
  • missing evidence fields
  • missing red_phase evidence — tests were only ever green (no failing-before-change proof); treat as NEEDS_RETRY
  • red_phase and green_phase test identifiers do not match — cannot confirm the same test went RED then GREEN
  • unexplained assertion_delta — an existing assertion was removed or weakened without justification (a replaced positive assertion is a smell, not a green)
  • no tests run, or weak/non-specific test results — treat as NEEDS_RETRY; require child to run StageAcceptanceChecks and report outcomes
  • acceptance status not traceable to artifact criteria, or numbered criteria missing from acceptance_to_test
• BLOCKED if child reports blocker code (for example ENV_BLOCKED) or cannot proceed safely

Decision policy:

• PASS -> continue to next stage
• NEEDS_RETRY -> send corrective feedback and rerun same child task
• BLOCKED -> invoke helper, amend artifact via scribe, then request user confirmation if environment-related — see orchestrate-recovery for deeper loop and env policy.

Verifier report grading (additional requirements)

For verifier completion reports, PASS also requires:

• All criteria have coverage classification (direct-exercised, indirect-integration, manual-required, or missing).
• manual-required criteria have recorded explicit manual evidence or an explicitly accepted deviation from the user.
• host_fallback sandbox status is acceptable only when sandbox was preferred, not required, and the specific acceptance criteria do not require Docker/runtime topology proof.
• No missing coverage on an acceptance criterion.
• security_review status is not blocked or findings with unresolved primary findings.

Verifier NEEDS_RETRY, FAILED, or BLOCKED invokes existing recovery behavior (helper + scribe amendment).

CodeRabbit gate (once per orchestration — after final verifier, before difficulty gates / PR / architect)

Invocation budget: Exactly one CodeRabbit CLI invocation per orchestration session (per .plan artifact or per feature:<slug> GitHub run). CodeRabbit is a one-shot recommendation source, not a validation loop. Never Task review with orchestrate_coderabbit_gate between stages, between GitHub issues, after a single issue while more issues remain in the queue, or after CodeRabbit remediation.

When every stage is complete and the final verifier has APPROVED (legacy .plan stage loop or entire GitHub feature queue exhausted with all issues verified):

1. Read ## Difficulty from the artifact when present (easy | medium | hard). For GitHub-only work with no .plan, assume medium unless the user or issue meta specifies otherwise.
2. easy: Skip this gate. Continue to Difficulty-based completion gates (which also skips extra work for easy).
3. medium or hard: Task review with load: full and this contract:
   • execution_mode: orchestrate_coderabbit_gate
   • impl_repo_path: absolute path to the implementation git root (session cwd when already in the impl repo; otherwise from handoff / issue context — must contain .git)
   • base_branch: develop for this repo unless the user explicitly overrides it; otherwise use the known project convention
   • review_scope: prefer committed changes since base — coderabbit review --agent --base <base_branch>; use -t all only when the user or stage context requires uncommitted review
   • Pass aggregated completion summary (stages or issue id, files_changed, verifier verdict, commit refs)
   • Instruct: load code-review skill; verify CLI (coderabbit --version, coderabbit auth status); run review; parse every --agent JSONL finding event; return CODERABBIT_GATE, severity counts, and the full numbered finding inventory with file/line anchors when present
4. Outcomes:
   • CODERABBIT_GATE: PASS (the one-shot CodeRabbit run has zero critical, major, or minor findings, and any trivial/info findings are fixed, not applicable, or explicitly deferred with reason) → continue to Difficulty-based completion gates.
   • CODERABBIT_GATE: BLOCKED (any critical, major, or minor, missing full finding inventory, or missing per-item resolution evidence) → Task developer or frontend-dev per last stage Owner (or last issue owner for GitHub) with load: full: numbered remediation from CodeRabbit only; do not use autofix unattended. Require completion report field coderabbit_resolutions with one entry per finding id: fixed, deferred, or not_applicable, plus rationale for non-fixed items. Then Task verifier load: full on affected acceptance criteria and changed files. If verifier confirms all non-deferred findings were addressed locally and no blocker remains, mark CodeRabbit remediation complete and continue without re-running CodeRabbit. If verifier cannot confirm, invoke helper + user confirmation without marking the gate PASS.
   • CODERABBIT_GATE: SKIPPED (CLI missing, auth failure, or not a git repo) → report reason; do not mark orchestration complete; prompt user to fix CLI/auth or waive explicitly.
5. GitHub feature mode: Run this gate only in Exit when queue empty (after all issues pass verifier), not when transitioning each issue to state:ready-for-review. Put ### CodeRabbit fields in the feature completion summary (and optional final gh comment on the PR), not in per-issue ready-for-review comments.

Orchestrate must track across the session: coderabbit_runs (must be 1 when this gate runs), coderabbit_findings (full numbered inventory from the one-shot run), coderabbit_resolutions (per-finding fixed / deferred / not_applicable evidence from developer/frontend-dev), coderabbit_remediation_fixes (items fixed after the one-shot run), and finding counts from the CodeRabbit run. Pass these into the Completion (mandatory) block below — never omit the CodeRabbit section.

Verifier escape analysis (CodeRabbit gate)

When the CodeRabbit gate completes and any blocker findings were present, include a ### Verifier escape analysis section in the completion report:

• For each CodeRabbit blocker (Critical/Major/Minor), classify by category: correctness, test/coverage, security, performance, contract/API, configuration, or other.
• For each, note whether the verifier should have caught it, which stage or issue it originated from, and a recommended missing verifier trigger or checklist rule.
• Do not automatically modify configuration from findings. The analysis is an operator-visible calibration backlog, preventing speculative rule growth.
• Skip this section when CodeRabbit had zero blockers or was skipped/not applicable.

Difficulty-based completion gates (after CodeRabbit gate when applicable)

When every stage is complete, the final verifier passes, and any required CodeRabbit gate has CODERABBIT_GATE: PASS or local CodeRabbit remediation has been verified complete after the one-shot run (or was skipped because easy):

1. Read ## Difficulty from the artifact (easy | medium | hard). If the section is missing or unclear, assume medium.
2. easy: Skip extra gates. Go to Completion (mandatory) and prompt the user to switch to architect.
3. medium: Invoke review via Task with: artifact path; aggregated completion summary (each stage_id, files_changed, tests_run outcomes, verifier verdict); include CodeRabbit gate findings when that gate ran. Require a concise post-execution assessment (sign-off vs remediation). If review indicates remediation, use scribe to update or create .plan/review.<slug>.md per existing review flow, then stop and prompt user to address remediation before final sign-off with architect.
4. hard:
   • (a) Invoke senior-dev via Task with execution_mode: scheduled_review: pass artifact path, aggregated implementation summary, Goal + AcceptanceChecks excerpts, verifier reports, coverage assessment, sandbox/security evidence, and CodeRabbit gate findings when that gate ran. Instruct: read-only in this mode; return APPROVED, NEEDS_CHANGES, or BLOCKED with numbered, evidence-backed findings. No user confirmation required for this scheduled gate (unlike escalation). Do not accept HANDOFF_TO_DEVELOPER in this mode.
   • (b) Invoke helper via Task for strategy conformance: pass artifact path, Goal, AcceptanceChecks, and short summary of what was implemented. Instruct helper to compare implementation intent vs plan and list any logical/architectural mismatches (reasoning only; no code).
   • If senior-dev or helper flags blockers, invoke helper + scribe to amend the artifact as usual before prompting the user.

Environment gate rerun (after remediation)

When the user fixes env/worktree issues or asks to rerun checks:

• Clear worktree_env_checked, worktree_env_evidence, and preflight_repair_attempted for this rerun.
• Run worktree-env then preflight again using the repair-first flow above; reset env_gate_passed only after Status: Ready.
• Do not write preflight output into plan artifacts.

Completion (mandatory)

When verifier passes for all stages, any required CodeRabbit gate has CODERABBIT_GATE: PASS or local CodeRabbit remediation has been verified complete after the one-shot run (or was skipped for easy), and any Difficulty-based completion gates for that artifact have finished (see above):

1. Report using the structure below. The ### CodeRabbit table is mandatory on every completion — never omit it. If CodeRabbit did not run, state why explicitly (easy, SKIPPED, or user waiver). Do not mark orchestration complete on medium/hard without CodeRabbit ran: yes and evidence of a successful CLI review.
2. The first table must name the exact sign-off target: feature:<slug> or .plan/<type>.<slug>.md, display name, repo, PR URL or skip reason, and branch/base when known.
3. Use tables or short keyed lists only. No essay paragraphs, no stale transcript summaries, no generic “done this, go back to architect” ending.
4. Explicit next step: tell the user exactly what to paste into the next architect chat for this feature/sign-off target.
5. Architect still owns final review + documentation in Mode B; orchestrate may have run medium/hard pre-handoff gates only.

Completion report template (required)

## Orchestration complete

### Sign-off target
| Field | Value |
|-------|-------|
| Feature / artifact | `<Display Name>` (`feature:<slug>` or `.plan/<type>.<slug>.md`) |
| Impl repo | `<owner/name>` |
| Impl path | `<absolute path to impl git root>` |
| Branch / base | `<branch>` -> `<base>` |
| PR | `<pr_url>` or `<skip reason>` |
| Sign-off owner | **impl** architect option 4 Mode F Phase R (GitHub feature) or Mode B (`.plan` artifact) |

### Work completed
| Task / stage | Status | Evidence | Notes / follow-up |
|--------------|--------|----------|-------------------|
| `<issue # / stage_id / task name>` | PASS | `<commit, verifier PASS, tests>` | `<none or concise note>` |

### Gates and checks
| Gate | Result | Evidence | Action needed |
|------|--------|----------|---------------|
| Verifier | PASS | `<summary>` | None |
| Difficulty gates | PASS / skipped | `<review/senior/helper evidence or reason>` | `<none or action>` |
| PR finish | PASS / skipped | `<pr_url/action/message>` | `<none or action>` |

### Verifier gate (required — do not omit)
Per-stage verifier evidence. Architect Phase R spot-checks this against the issue's `verifier_gate:` comments.
| Stage / issue | Verdict | report_grade | Test ids | Coverage (direct/indirect/manual/missing) | Gate comment |
|---------------|---------|--------------|----------|--------------------------------------------|--------------|
| `<stage_id>` | APPROVED | PASS | `<test ids>` | `<d>/<i>/<m>/<x>` | `<issue comment URL>` |

### CodeRabbit (required — do not omit)
| Field | Value |
|-------|-------|
| CodeRabbit ran | yes / no |
| Reason if no | `difficulty: easy`, `CODERABBIT_GATE: SKIPPED — <reason>`, or `user waived` |
| CLI command | `<exact coderabbit review ...>` or `n/a` |
| Review runs | `<count>` |
| Remediation fixes applied | `<count>` |
| Final gate | PASS / BLOCKED / SKIPPED / not required (easy) |
| Final findings | Critical `<n>`; Major `<n>`; Minor `<n>`; Trivial `<n>`; Info `<n>` |
| Finding resolutions | fixed `<n>`; deferred `<n>`; not applicable `<n>`; unresolved `<n>` |

### Key findings / risks
| Item | Impact | Required next action |
|------|--------|----------------------|
| `<finding, risk, deferral, or "None">` | `<low/medium/high or n/a>` | `<specific action or "None">` |

### Next steps
| Order | Who | Action | Exact prompt / input |
|-------|-----|--------|----------------------|
| 1 | User | Start a new **impl** `architect` session → **option 4** → **R** (or **A** with paste below) | See copy/paste scripts |
| 2 | architect | **Phase R** first pass: PR comments, CI, remediation tickets; Phase 1+2 only when Merge-ready | Paste back to orchestrate only if Phase R publishes remediation |

### Copy/paste sign-off script (first orchestrate complete — PR just opened)
```text
Orchestrate complete for <Display Name> (`feature:<slug>`).
PR: <pr_url or skip reason>
impl architect option 4 → A
Please run Mode F Phase R for this PR. Triage CodeRabbit/Kilo/CI comments and incomplete tickets. If remediation needed, publish tickets and I will return to orchestrate; if Merge-ready, accept issues (state:done, stay open) and complete docs.
```

### Copy/paste remediation-return script (after remediation queue + push — back to architect)
```text
Remediation complete for <Display Name> (`feature:<slug>`).
PR: <pr_url>
impl architect option 4 → R — re-check PR feedback, CI, tickets, and user input.
```

When CODERABBIT_GATE: BLOCKED, increment Remediation fixes applied only when the child completion report lists which CodeRabbit finding IDs or numbered items were fixed (orchestrate sums across loops). Do not count deferred or not-applicable findings as fixes.

Do not present orchestration as completed unless required Task call evidence exists for each completed stage, for the applicable CodeRabbit gate (when medium/hard), and for the applicable Difficulty gates, and unless the completion report includes the CodeRabbit section above.