Orchestrate Skill
This skill frames work for the already-active main session, which serves as the orchestrator runtime for end-to-end feature or bug delivery. Orchestration deliberately stays in the main session on user invocation (/orchestrate <objective>); the same procedure governs a delegated Agent(orchestrator) run from epic-planner or epic-orchestrator.
Invocation Argument
When invoked as /orchestrate, the orchestration objective is:
$ARGUMENTS
A delegated Agent(orchestrator) run receives its objective in the delegation prompt instead.
Perform the scale assessment first: if the objective is epic-scale (names an epic manifest or requires multiple independently mergeable features), stop before any delegation and direct the user to /epic-plan (planning) or /epic-run (executing a prepared epic), per ## Change Budget Routing in .claude/agents/orchestrator.md.
Prerequisites
Before proceeding, the orchestrator must:
- Read
CLAUDE.mdfor repository tone policy and architectural context. - Read applicable
.claude/rules/files for the languages in scope. - Read the policy files listed in the compliance reading order section of
CLAUDE.md. - Read the
execution-environmentskill (.claude/skills/execution-environment/SKILL.md) before delegating any worker. Delegation prompts and plans reference that brief instead of restating tool routes, command-text restrictions, the batch budget, hook context, or CI shape.
Checkpoint Handling
On every invocation, the main session must:
- Read
artifacts/orchestration/orchestrator-state.jsonto check for existing state. - If a valid checkpoint exists with a matching objective, resume from the recorded
next_step. - If no checkpoint exists or the objective is new, begin the orchestration lifecycle from the start.
- Checkpoint hygiene (issue #673). When the checkpoint at
artifacts/orchestration/orchestrator-state.jsonrecords anissue-numother than the item this invocation is about, move it toartifacts/orchestration/handoff/orchestrator-state.issue-<issue-num>.<yyyy-MM-ddTHH-mm>.jsonbefore writing a new checkpoint, rather than overwriting it or leaving it in place. Apply the same move when this session hands an item whose checkpoint it holds to another session or worktree. A checkpoint left at a session root is read by gates that resolve against that root, so a foreign one there is state a gate can answer from. - Required checkpoint keys (issue #798). Every checkpoint write carries each top-level key listed in
.claude/rules/orchestrator-state.mdunder## Required Top-Level Keys; plain validation reports each absent key asCheckpoint missing required key: <key>under every flag combination. The list includeslast_updated, an ISO-8601 UTC date-time string (for example2026-10-08T17:28:00Z) that is rewritten on every checkpoint write: after every completed step and every state transition, including halts.
Prepared-State Portable Handoff Intake
Treat a portable prepared-state checkpoint as a request to resume the recorded lifecycle, not as a new orchestration intake. Before any destination launch:
- Validate the envelope through the published, workspace-explicit handoff
authority. Require exact repository, workspace, branch lineage, issue,
feature folder, work mode, scheduler, capability, and transition bindings.
Supply the complete caller-controlled independent expected context on every
call to
resolve_orchestration_topology,resolve_provider_routing, andtransition_prepared_orchestration:expected_repository_id,expected_workspace_root,expected_branch,expected_source_head_sha,allowed_head_relationship,expected_issue_number,expected_feature_folder,expected_work_mode,expected_plan_path, andexpected_plan_sha256. Derive each value from the destination checkout and the caller's own record. A call that omits a value, or that copies one from the envelope under validation, is rejected before any service invocation. - Prove the plan using only the independently expected repository-relative
path and raw-byte SHA-256 the caller supplied in
expected_plan_pathandexpected_plan_sha256. Do not rediscover, rename, or substitute a plan, and do not read the plan identity from the envelope. - Use
transition_prepared_orchestrationas the only authority that may materialize a provider-native destination checkpoint. Dry run validates and projects state without source archival or canonical-checkpoint replacement. - Preserve the envelope's completed phases and reject replay before mutation. Promotion, research, feature-document authoring, atomic planning, and preflight remain complete when the source recorded them as complete.
- Keep source-provider model, reasoning, profile, topology, launch, worktree, and receipt evidence opaque. Create destination routing evidence only for the first new delegation after materialization.
When Claude is the destination, resolve its model through the existing Claude
model-routing procedure and launch with the existing Agent(...) and Claude
worktree mechanisms. Do not translate Codex deployment receipts into Claude
launch evidence. When Claude is the source, preserve Claude launch and
worktree evidence in the portable source expression and allow the Codex
destination to resolve its own topology and model. An ordinary handoff whose
recorded transition is atomic_execution resumes the exact approved plan at
that transition without invoking a parent scheduler. Any validation,
authority, plan, replay, or materialization failure returns the deterministic
blocked result before launch.
Model-choice reconciliation on resume
Because model selection is required once delegation occurs (see ## Model Selection), a resuming orchestrator must repair a missing model choice deterministically before delegating at a delegating next_step. When the resumed next_step is a delegating step:
a. Preflight the checkpoint. Run the orchestrator-state validator with --require-model-routing (via mcp__drm-copilot__validate_orchestration_artifacts or the repository-local validator CLI documented in .claude/rules/orchestrator-state.md) against artifacts/orchestration/orchestrator-state.json before the first delegation. Record the result in a model_routing_preflight block { status ("pass"|"fail"), checked_at (ISO-8601 UTC), validator_command, output_summary }.
b. Recompute the floor. For the upcoming phase, recompute the complexity floor with Get-ComplexityFloor -SignalsPresent <names> (.claude/lib/model-routing/ModelRouting.psm1); do not reimplement the formula.
c. Record the assessment. Write a complexity_assessments[] entry { phase, band, floor, signals_present[], rationale, assessed_at } with floor equal to the recomputed value and band >= floor.
d. Resolve and record the receipt. Resolve the model with Resolve-DelegationModel -Agent <agent> -Band <complexity_band> -FablePolicy <fable_policy> (.claude/lib/model-routing/ModelRouting.psm1) and write a model_routing_receipts[] entry { agent, phase, complexity_band, fable_policy, table_model, clamped_from | null, model }.
e. Persist and delegate. Persist the checkpoint, then delegate with model equal to the receipt's model.
The orchestrator MUST NOT delegate at a delegating next_step while model_routing_preflight status is fail; it repairs the missing choice (steps b-e) and re-preflights until the status is pass.
Autonomous-Execution Mandate
The orchestrator must achieve all actions agentically with no human interaction; full autonomy is a hard requirement. A silent manual blocker discovered at the end of a workflow is a defect, not an acceptable outcome. Every unautomatable (human-interaction) requirement must be detected early, resolved by exactly one of three permitted responses, and recorded in orchestrator state.
Detection points
- Unautomatable requirements are enumerated as mandatory-unachievable requirements before kickoff wherever they are knowable up front.
- Where research is needed to discover them, they MUST be surfaced no later than the research stage.
- Research that touches third-party UIs (for example the Azure portal / Entra admin center, Outlook desktop or mobile, the Microsoft 365 admin center) MUST include an explicit automation-feasibility / human-interaction assessment recorded under an
## Automation Feasibilitysection in the research artifact.
Three permitted responses
When a step cannot be performed without a human, the orchestrator chooses exactly one response per requirement and records it in orchestrator state under human_interaction.requirements[]:
scope_change— change the scope to remove the manual dependency (for example, replace a portal click with anazCLI step that runs unattended).exception— permit an exception. This requires emitting a human-exception runbook (see below). The exception is unresolved until its runbook file exists on disk.halt— halt until further instruction. Ahaltblocks DONE while present. Ahaltis recoverable: a later checkpoint update that resolves the requirement (toscope_changeor a runbook-backedexception, or clears the halt) lifts the block.
Exception-runbook requirement
On a permitted exception, the orchestrator delegates runbook authoring to Agent(human-exception-runbook), which emits a human-readable runbook at <FEATURE>/runbooks/<name>.runbook.md and returns the runbook_path. The orchestrator records the returned repo-root-relative path in human_interaction.requirements[].runbook_path. The runbook contract — canonical path, the five required sections (Cue, Prerequisites, Step-by-step Instructions, Verification, Source and Citation), and the MCP-first / web-second sourcing rule — is defined authoritatively in .claude/skills/human-exception-runbook/SKILL.md.
Enforcement points
The mandate is enforced mechanically, so DONE cannot be written while a human-interaction requirement is unresolved:
- Validator invariants. The top-level
human_interaction.requirements[]invariants — theresponseenumscope_change|exception|halt, and the exception-requires-runbook invariant (response == "exception"requires a non-emptyrunbook_path) — are enforced byscripts/dev_tools/validate_orchestrator_state.pyand byTest-HumanInteractionShapein.claude/hooks/validate-orchestrator-output.ps1, per the documented contract in.claude/rules/orchestrator-state.md. Checkpoints without ahuman_interactionkey stay valid, so existing checkpoints are unaffected. - Completion gate.
Test-HumanInteractionShapein.claude/hooks/validate-orchestrator-output.ps1blocks DONE when a requirement has no resolvedresponse, aresponseoutside the enum, anyresponse == "halt", or anexceptionwhoserunbook_pathis missing/empty or whose file does not exist. An absenthuman_interactionkey passes. - Research gate.
Test-AutomationFeasibilitySectionin.claude/hooks/validate-task-researcher-output.ps1requires the## Automation Feasibilitysection for applicable autonomous-execution research artifacts and blocks otherwise; non-applicable research is unaffected.
Delegation Model
After reading artifacts/orchestration/orchestrator-state.json, the main session delegates work exclusively through configured workers:
atomic-planner— generates phased implementation plansatomic-executor— executes approved plans task-by-taskfeature-review— produces policy, code, and feature audit artifactstask-researcher— performs deep research and writes findings to the research path the orchestrator resolves before delegating:docs/features/<feature>/research/when an activefeature-folderis in scope inorchestrator-state.json, otherwisedocs/research/for one-off research. The orchestrator passes the resolved path in the delegation prompt.
The orchestrator does not perform deep implementation itself. It coordinates, tracks state, and enforces completion.
Single-pass preflight for S4 planning (and for preparation mode). The directive DIRECTIVE: PREFLIGHT VALIDATION ONLY goes in the atomic-executor delegation prompt only, never in the plan file. Preflight follows ### Single-Pass Preflight in the atomic-plan-contract skill: the preflight executor fixes trivial defects in place and returns only substantive defects as PREFLIGHT-DEFECT: lines. The at-most-one-return rule applies:
- Preflight round one returns
PREFLIGHT: ALL CLEAR(in-placePREFLIGHT-FIX:lines permitted) orPREFLIGHT: REVISIONS REQUIREDwith every substantive defect listed. - On
PREFLIGHT: REVISIONS REQUIRED, delegate oneatomic-plannerrevision of the same plan file carrying the fullPREFLIGHT-DEFECT:list, then run preflight round two. A plan returns to the planner at most once. - If round two still returns a substantive defect, halt with
blocked_reason: "validator_failed"and record both preflight returns in the checkpoint. Do not open a third round.
Preparation Mode
A delegation prompt carrying the literal marker Preparation mode: true (issued by epic-planner per the .claude/skills/epic-plan/SKILL.md kickoff line) scopes the run to planning only:
- Route. Select
route_id: preparation. The route's routing-matrix entry requires receipts fortask-researcher,prd-feature,atomic-planner, andatomic-executor; the skillsorchestrate,feature-promotion-lifecycle, andatomic-plan-contract; and the promotion plus validator MCP tools. - Scope. Run promotion (MCP surface), research, feature documents (
spec.md,user-story.md), atomic planning, and the atomic-executor preflight (precondition validation only, under the single-pass preflight and at-most-one-return rule stated under## Delegation Model). Atomic execution, PR authoring, CI monitoring, and feature review are out of scope and are executed later byepic-orchestrator. - Terminal checkpoint. Stop with
completed_stepscontainingS3_promotionandS4_atomic_planning,next_step: "S5_atomic_execution", out-of-scope step statuses set tonot-applicable, andblocked_reason: "none". Do NOT assert completion (next_step: "complete",S12_complete, or acompletedstep8/9/10 status): the run has no PR or CI evidence, and the route'srequires_ci_gate: falseexempts it fromci_gateat the completion validator instead. - Premise-falsified halt. Use
blocked_reason: "premise_falsified"when every delegation and validator succeeded but evidence gathered during execution falsified the plan's premise. Still record the evidence path in free-form checkpoint keys;blocked_reasoncarries only the classification. The preparation terminal checkpoint above still setsblocked_reason: "none". The fullblocked_reasonvocabulary and its partition are in.claude/rules/orchestrator-state.md. - Commit. Commit the prepared feature folder and plan to the current branch (the worktree branch created off the epic integration branch) before stopping, and report the
plan-pathand preflight status in the final output.
Epic Mode Bounded Return
Under Epic mode: true, your final report must be exactly this eight-field shape and nothing else:
issue_num, feature_folder, merge_status, pr_number, merge_commit_sha, blocked_reason,
branch_name, worktree_path.
Content beyond those fields is discarded unread, so spend no effort on it. The parent
epic-orchestrator re-derives authoritative state from git and gh regardless, per
## Bounded Child Return Contract in .claude/skills/epic-orchestrate/SKILL.md.
Model Selection
Model selection is a second axis, strictly separate from route. route (small | large | remediation | preparation | epic) is deterministic — file-count driven for small/large, marker-driven for preparation (the Preparation mode: true kickoff line) and epic; it governs required_agents, required_skills, and required_mcp_tools only. route is NOT an input to model selection anywhere. The sole feature-level input to the delegation model tier is a judgment-based complexity_band (C1 | C2 | C3 | C4). The authoritative values live in the model_policy block of config/orchestration-routing.json.
The two canonical, tested reference implementations express the formulas the orchestrator applies by judgment:
.claude/lib/model-routing/ModelRouting.psm1(Get-ComplexityFloor) — the deterministic complexity-floor formula. Each present[floor]signal contributes a candidate band ofC3; the floor is the maximum triggered candidate band; the floor never exceedsC3. C4 is never floor-forced; it is reached only by judgment..claude/lib/model-routing/ModelRouting.psm1(Resolve-DelegationModel) — the delegation-model selection formula (basecomplexity_to_modeltable, thepreferredoverlay, and thedisabledclamp).
The runnable reference the destination runtime applies is the .claude-resident PowerShell module above; the repository validator remains the Python authority (scripts/dev_tools/compute_complexity_floor.py and scripts/dev_tools/resolve_delegation_model.py), pinned to the same config/orchestration-routing.json truth table by a static config-parity test.
End-to-end procedure:
Parse the kickoff marker. Read the session
model_budget.fable_policyvalue (disabled | available | preferred, defaultdisabled) from the kickoff marker line. This is the only session-level model-budget switch.Assess
complexity_bandand record it. For each assessed phase, judge thecomplexity_bandagainst themodel_policy.complexitysignal catalog and anchors, then record acomplexity_assessments[]entry{ phase, band, floor, signals_present[], rationale, assessed_at }. The recordedfloormust equalcompute_complexity_floor(signals_present), and the assessedbandmust satisfyband >= floor. The floor is a lower bound only; it never raises a judgment or evaluates its merit.Run the per-delegation selection order. For each delegation, resolve the model as
resolve_delegation_model(agent, complexity_band, fable_policy): thetable_modelis thepreferredoverlay value when (fable_policy == "preferred"and the agent is in the overlay set{atomic-planner, prd-feature, feature-review, task-researcher}andband == "C3"), otherwise the basecomplexity_to_model[band]. Underfable_policy == "disabled", afabletable_modelclamps tomodel = "opus"withclamped_from = "fable".atomic-executorandpr-authorC3 cells stayopusunder every policy.Emit a routing receipt. Record a
model_routing_receipts[]entry{ agent, phase, complexity_band, fable_policy, table_model, clamped_from | null, model }.table_modelis the pre-clamp lookup;modelis the post-clamp result.Delegate with the resolved model. Pass
modelequal to the receipt'smodelon theAgent(...)spawn call for that delegation. The orchestrator MUST NOT omitmodelon the spawn (an omittedmodelfalls back to the delegate's frontmatter default —opusfor most workers — which suppresses afableorsonnetresolution), and MUST NOT hard-codemodel=opusin a way that overrides the resolved routing model. This applies to every fresh delegation, mirroring the resume-path rule ("delegate withmodelequal to the receipt'smodel") so both paths bind the spawn model to the routing receipt.
The complexity_assessments[] and model_routing_receipts[] invariants are enforced by scripts/dev_tools/validate_orchestrator_state.py per .claude/rules/orchestrator-state.md; both arrays remain additive (a checkpoint that predates model routing stays valid).
Required-once-delegated invariant (require_model_routing mode)
The validate_orchestrator_state_text(...) validator accepts a require_model_routing mode (CLI flag --require-model-routing; MCP parameter require_model_routing). Under this mode the arrays stop being merely optional: once the checkpoint records at least one delegation (a well-formed delegation_receipts[] entry, or a next_step that names a delegating agent), every delegated agent must have a matching model_routing_receipts[] entry, each matched receipt's phase must have a complexity_assessments[] entry, and every present receipt/assessment must be consistent with the reference formulas. A delegation-free checkpoint imposes no requirement, so old checkpoints stay valid. The gate is implemented in scripts/dev_tools/_orchestrator_state_model_routing_gate.py; it reuses the per-entry validators and never reimplements compute_complexity_floor or resolve_delegation_model. Two enforcement layers consume it: the completion gate (.claude/hooks/validate-orchestrator-output.ps1 passes --require-model-routing and surfaces failures as MODEL_ROUTING_BLOCKED:), and the pre-delegation deterrent (.claude/hooks/enforce-model-routing-receipt.ps1, presence-only). The MCP TypeScript surface performs the existence check only (delegated-agent set ⊆ routing-receipt-agent set); the Python validator is authoritative for per-receipt correctness.
fork caveat. A skill whose frontmatter context field holds the value fork inherits the parent model and ignores a model override. Model selection therefore applies to agent delegations, not to fork-routed skill invocations.
PR Authoring (pr-author Handoff)
PR creation and PR body edits are delegated work, not orchestrator work. The orchestrator MUST NOT call gh pr create or gh pr edit --body* directly from the main thread; the enforce-pr-author-skill.ps1 PreToolUse hook blocks those commands unless the --body-file argument resolves to a canonical artifacts/pr_body_<N>.md path with a matching, verified artifacts/pr_body_<N>.receipt.json.
The mandatory sequence is:
- The orchestrator first refreshes the PR-context artifact via
mcp__drm-copilot__collect_pr_context(or the equivalent context-collection mechanism), which writesartifacts/pr_context.summary.txt. - The orchestrator runs the orchestrator-state validator (
mcp__drm-copilot__validate_orchestration_artifactsor the equivalent repository-local validator CLI documented in.claude/rules/orchestrator-state.md) againstartifacts/orchestration/orchestrator-state.json --require-pr-creation-readyand records the pass/fail result under a newpr_author_preflightfield in the checkpoint, alongsidepr_author_receipt:{status ("pass"|"fail"), checked_at (ISO-8601 UTC), checkpoint_path, validator_command, output_summary}. The orchestrator must not delegate toAgent(pr-author)when this preflight fails. The validator's full-lifecycle completion flag (ci_gate/pr_gate/routing-contract receipts) remains reserved for the post-PR/CI completion context (Step S9 / PR Creation Gate condition 6), not this pre-PR-creation preflight, because those values cannot exist before the firstgh pr createof a branch. - The orchestrator then delegates PR creation and any PR body edits to
Agent(pr-author). Thepr-authoragent runs thepr-authorskill to author the body, writes the body fileartifacts/pr_body_<N>.mdand the sibling receiptartifacts/pr_body_<N>.receipt.jsonwith the shape{skill, pr_body_path, number, sha256 (lowercase hex of the body bytes), context_summary_path, created_at (ISO-8601 UTC, strictly newer thanartifacts/pr_context.summary.txtlast-write)}, issuesgh pr create --body-file artifacts/pr_body_<N>.md(orgh pr edit --body-file ...), and reports the resulting PR URL or PR number. - The orchestrator records
pr_author_receiptin the checkpoint, citing the body-file path and the receipt path that were verified.
When the pr-author agent runs outside the item worktree (its process directory is not the worktree that holds the item's artifacts/ tree), it passes the absolute canonical path <item worktree>/artifacts/pr_body_<N>.md to --body-file. The enforce-pr-author-skill.ps1 hook resolves the item worktree from --head and reads the PR context summary, the body, and the receipt beneath it; in that topology it denies a relative --body-file with PR_BODY_PATH_NONCANONICAL, because gh would read the relative path from its own process directory.
Agent(pr-author) is the mandatory delegate for PR creation and PR body edits. Direct gh pr create/gh pr edit --body* from the main thread is prohibited and is blocked by the hook. Before the five receipt checks, the enforce-pr-author-skill.ps1 PreToolUse hook independently re-validates the orchestrator-state checkpoint against --require-pr-creation-ready (via an injectable $Invoker subprocess seam) and blocks with ORCHESTRATOR_STATE_PREFLIGHT_FAILED when the checkpoint is missing or invalid — this is the local, hook-level enforcement mechanism that closes the bypass path (it runs inside the same hook that already intercepts gh pr create/gh pr edit, not as a CI check). The PreToolUse hook then verifies the receipt in five ordered checks: canonical body-file path, receipt present, number match, sha256 match against the body bytes, and created_at strictly newer than the context summary last-write.
The SHA-256 receipt is a policy-level integrity check, not a cryptographic or security boundary; any actor with Write(/artifacts/**) access can replace both the body file and its receipt together with a matching SHA-256. It binds the body bytes to the receipt, prevents accidental bypass, and requires a deliberate, documented act to circumvent.
Evidence Location Authority
All evidence artifacts produced during orchestration MUST comply with the canonical scheme defined in .claude/skills/evidence-and-timestamp-conventions/SKILL.md. Evidence MUST be written to <FEATURE>/evidence/<kind>/ only.
Permitted artifacts/-rooted sub-paths (non-evidence orchestration use only):
artifacts/orchestration/— orchestrator state and checkpointsartifacts/pr_context— PR context artifactsartifacts/reviews/— review staging artifactsartifacts/status/— status update artifactsartifacts/python/— Python coverage and lcov outputsartifacts/pester/— Pester coverage outputsartifacts/csharp/— C# coverage outputs
All other artifacts/ sub-paths (e.g., artifacts/baselines/, artifacts/qa/, artifacts/coverage/, artifacts/evidence/) are FORBIDDEN for evidence output and will be blocked by the enforce-evidence-locations.ps1 PreToolUse hook.
GitHub Actions Reusable Workflows
Every new CI gate in this repository ships as a callable reusable workflow named _<name>.yml that declares both on: workflow_call: and on: workflow_dispatch:. Orchestrator workflows (for example pr-pipeline.yml) reference these callees via uses: ./.github/workflows/_<name>.yml and contain no inline steps: of their own. Cross-job filesystem reliance is not implicit; any job that needs to share files with another job must use explicit actions/upload-artifact + actions/download-artifact. The GitHub Actions reusable-workflow nesting depth cap is 4; this repository uses one level of nesting and does not introduce additional levels without an explicit design review. See .github/workflows/README.md for the full per-stage dispatch and branch-protection rename procedure.
Completion Requirements
The orchestrator must not report completion until:
- All required artifacts for the selected workflow path are present on disk.
- All validation gates (toolchain, acceptance criteria, audit artifacts) have passed.
- The checkpoint file at
artifacts/orchestration/orchestrator-state.jsonreflects the completed state. - The model-routing gate passes:
.claude/hooks/validate-orchestrator-output.ps1runs the validator with--require-model-routingalongside--require-completeand refuses DONE withMODEL_ROUTING_BLOCKED:when a recorded delegation lacks a matchingmodel_routing_receipts[]/complexity_assessments[]entry (see the required-once-delegated invariant under## Model Selection).
Pre-Feature-Review Commit
Before delegating to the feature-review subagent, the orchestrator must:
- Confirm the self-review: the lexicographically greatest
self-review.*.mdunder<FEATURE>/evidence/qa-gates/exists and records no FAIL row. If it is missing or records a FAIL row, run a proportionate correction (one planner delegation and one combined preflight-and-execute executor delegation, as under## Remediation Loop (R1–R5)) that fixes the failing items and rewrites the self-review, then repeat this check before the commit. - Stage all modified and new files:
git add -A. - Delegate to
Agent(commit-message)to generate a conventional commit message from the staged diff. The agent is read-only and returns message text only; it does not commit. - Commit using the generated message:
git commit -m "<generated message>". Thegit addandgit commitactions remain on the orchestrator. - Only after a successful commit may the orchestrator proceed to the
feature-reviewdelegation.
The review subagent compares against a base branch; uncommitted changes are invisible to the diff tool and cannot be audited.
Post-Review Outcome Evaluation
After each feature-review delegation returns:
- Locate
remediation-inputs.<timestamp>.mdin the active feature folder (match the highest ISO-8601 timestamp). - If no such file exists, treat as zero blocking findings and advance to the PR creation gate.
- If the file exists, count lines matching
BLOCKINGorSeverity: Blocking(case-sensitive). If count >= 1, enter the remediation loop. If count = 0, advance to the PR creation gate. This count rule applies unchanged when the file carries noReview-Verdict:line: a count of at least 1 isREMEDIATION_REQUIREDand every finding is treated asautonomous. - If the file carries a
Review-Verdict:line, recompute the verdict from theRemediability:lines of the blocking findings (a blocking finding block without aRemediability:line counts asautonomous): no blocking finding isPASS; anyautonomousfinding isREMEDIATION_REQUIRED; otherwise anyexternal_dependency,policy_hold, orhuman_decision_requiredfinding isHALT_NON_REMEDIABLE; otherwiseAWAITING_CI. Theremediation-inputsfile is authoritative; the optionalreview-status:token in the review result is a cross-check. - A mismatch between the declared and recomputed verdicts is a reviewer contract error: record it under
artifact_errors, re-request the review once, and halt withblocked_reason: "delegate_contract_incomplete"if it persists. - Append a
remediation_loop.review_outcomes[]entry (verdictplus onefindings[]object withremediabilityper blocking finding) for every review, includingPASS. - Act on the verdict:
PASSadvances to the PR creation gate;REMEDIATION_REQUIREDenters the remediation loop with the plan scoped to theautonomousfindings, carrying the non-remediable findings forward unchanged;HALT_NON_REMEDIABLEfollows the halt branch;AWAITING_CIfollows the wait branch.
Halt branch (HALT_NON_REMEDIABLE): set blocked_reason to the highest-precedence halt class present, append one human_interaction.requirements[] entry with response: "halt" for each halt class present (external_dependency, policy_hold, human_decision_required) describing the human action needed, leave remediation_loop.completed_attempts unchanged, write no cycle, create no remediation plan, and stop. The precedence is:
Halt precedence: human_decision_required > policy_hold > external_dependency
Wait branch (AWAITING_CI): set blocked_reason: "awaiting_ci" and set next_step to the step that re-checks (S7_feature_review for a review-time wait, S9_ci_green for an S9 poll timeout). Record no human_interaction.requirements[] entry for a wait, write no cycle, and create no remediation plan. Poll within the existing bounded S9 interval and timeout; when the bound is exhausted, persist and stop. On resume, set blocked_reason: "none" and re-run the named step. For S9, the awaited run is identified by ci_gate.head_sha and ci_gate.pr_pipeline_run_id with conclusion: "pending"; for a review-time wait, the awaited workflow is named in the finding's Remediability-Evidence: line.
Remediation Loop (R1–R5)
A bounded loop consisting of five steps. The attempt count is remediation_loop.completed_attempts, and remediation_pass equals remediation_loop.completed_attempts. The active cycle number is completed_attempts + 1, and remediation.cycle_N in next_step uses that number; remediation_loop.current_cycle is a record position in cycles[], not a count. A halt or wait verdict never opens a cycle, and every cycle opened from a review records opened_by_review, the zero-based index of that review_outcomes[] entry.
Cycle accounting: a remediation attempt is complete when R3 execution finished (execution_status: "complete") and the pre-R4 commit recorded a non-empty change set; only then set candidate_applied: true on that cycle and increment completed_attempts. A cycle that ends without a candidate (execution not started, execution failed, or an empty staged change set) records candidate_applied: false and consumes no number. It is followed by at most one re-plan under the same number when the executor output identifies an autonomous plan defect; otherwise reclassify the blocker (typically external_dependency) and halt. Two consecutive no-candidate cycles halt with step6_status: "blocked_remediation_loop_limit". Local, CI-failure, merge-conflict, and parallel-drift cycles share the one count.
Remediation mode. Before R1, the orchestrator writes exactly one line into the cycle's remediation-inputs.<timestamp>.md: Remediation-Mode: proportionate or Remediation-Mode: design. The classification rule: a cycle is proportionate when every autonomous finding can be fixed without changing a spec acceptance criterion, a public interface, or the item's file inventory beyond the files already in the branch diff plus their tests and mirrors; otherwise the cycle is design. CI-failure findings are normally proportionate.
Proportionate cycle. R1 is one
atomic-plannerdelegation that writes a short remediation plan carrying a## Pre-Mortemsection and a final self-review task. R2 and R3 run as oneatomic-executordelegation: the executor runs single-pass preflight with in-place trivial fixes (### Single-Pass Preflightinatomic-plan-contract) and then executes the plan. Recordpreflight: {iterations: 1, final_status: "clear"}on the cycle beforeexecution_status. If preflight finds a substantive defect, the executor stops withBLOCKED at preflight (before [P0-T1]), a plan delta, and no checked task; the orchestrator rewrites the mode line toRemediation-Mode: designand the cycle continues as a design cycle with one planner revision. The pre-R4 commit, R4, and R5 are unchanged.Design cycle. R1 to R5 run as listed below, and R2 follows the single-pass preflight and at-most-one-return rule.
R1 — Remediation planning: Delegate to
atomic-plannerwithremediation-inputs.<timestamp>.mdpath as primary context. Receiveremediation-plan.<timestamp>.mdin the active feature folder.R2 — Preflight clearance: Delegate to
atomic-executorfor precondition validation only (no implementation), with the preflight directive in the delegation prompt. Trivial defects are fixed in place. If the executor returnsPREFLIGHT: REVISIONS REQUIRED, return to R1 once and re-delegate toatomic-plannerwith the fullPREFLIGHT-DEFECT:list; if the following preflight still reports a substantive defect, recordfinal_status: "blocked_preflight_iteration_limit"on the cycle and halt per.claude/skills/remediation-handoff-atomic-planner/SKILL.md. Only afterPREFLIGHT: ALL CLEARmay the orchestrator advance to R3.R3 — Remediation execution: Delegate to
atomic-executorwith full execution authorization. Each task's toolchain loop (format → lint → type-check → test) is mandatory; no skipping.Pre-R4 commit: Stage all changes (
git add -A), delegate toAgent(commit-message)to generate a commit message from the staged diff (the agent returns message text only and does not commit), then commit with the generated message. Thegit commitaction remains on the orchestrator. Advance to R4 only after a successful commit.R4 — Re-audit: Delegate to
feature-reviewwith the same inputs as the original review (resolved base branch, feature folder, refreshed PR context artifacts, acceptance-criteria source). No scope narrowing. The canonical issue number line must be included.R5 — Loop-exit decision: Evaluate the re-audit per Post-Review Outcome Evaluation. If it produces zero blocking findings, exit the loop and advance to the PR creation gate. If its verdict is
HALT_NON_REMEDIABLEorAWAITING_CI, follow the halt or wait branch instead of opening the next cycle. Otherwise, record the cycle'scandidate_appliedvalue and the resultingcompleted_attemptsin the checkpoint and return to R1.
Termination guard: Halt after three completed attempts: when remediation_loop.completed_attempts equals 3 and the latest verdict is not PASS, the orchestrator records step6_status: "blocked_remediation_loop_limit" in the checkpoint and halts. No further automation is attempted.
Issue Number Consistency
The canonical issue number is derived once from the active feature folder name: extract the trailing integer from the folder base name (e.g., 2026-04-26-push-down-claude-customizations-162 yields 162). Record as issue-num in the checkpoint; the hyphenated key is the one listed in .claude/rules/orchestrator-state.md under ## Required Top-Level Keys.
Every delegation prompt to a receipt-gated subagent type — atomic-planner, atomic-executor, feature-review, task-researcher, prd-feature, and pr-author — must include the line:
Canonical issue number for this feature is <issue_num>. All artifact content, file paths, and cross-references must use this number.
Each such prompt also carries a branch: <name> label naming the branch checked out in the item's worktree, written as the first branch: occurrence in the prompt. Before promotion assigns an issue number, the branch label alone is required. Three gates, enforce-model-routing-receipt.ps1, enforce-prd-feature-before-planner.ps1, and enforce-orchestration-preimplementation-gate.ps1, identify the item from these two lines: they deny a gated delegation they cannot identify rather than checking it against whichever checkpoint occupies the calling session's root, and they never use a feature-folder path to choose the worktree, because a merged feature folder exists in every checkout branched from main.
The same two lines are required on every delegation to an implementation agent (python-typed-engineer, powershell-typed-engineer, typescript-engineer, csharp-typed-engineer, and atomic-executor) and on every Agent(orchestrator) delegation that carries no epic-mode, parallel-mode, or preparation-mode kickoff marker. enforce-orchestration-preimplementation-gate.ps1 resolves such a delegation's worktree from these lines and denies it with TARGET_WORKTREE_NOT_DERIVABLE when neither line is present, or with TARGET_WORKTREE_AMBIGUOUS when the lines disagree or match more than one live worktree.
If a subagent artifact references a different issue number, the orchestrator rejects it, requests correction, and records the discrepancy under artifact_errors in th
…(truncated)