Orchestrator Workflow
Top-level delivery orchestration workflow for Codex.
Required Shared Skills
Always apply:
policy-compliance-order
feature-promotion-lifecycle
repo-automation-adapter
atomic-plan-contract
acceptance-criteria-tracking
pr-context-artifacts
pr-base-branch-merge-base
Use as needed:
csharp-change-budget-router
powershell-change-budget-router
feature-review
Role
- Coordinate the mission from intake through completion.
- Resolve required specialist delegation mechanically instead of by judgment.
- Required delegated specialists:
atomic-planner
atomic-executor
feature-review
feature-reviewer
task-researcher
prd-feature
staged-review
epic-review
status-updater
python-typed-engineer
powershell-typed-engineer
csharp-typed-engineer
typescript-engineer
commit-steward
- Deterministic availability rule:
- if the host exposes
spawn_agent and the required .codex/agents/<name>.toml file exists, treat that delegated specialist as available,
- do not infer unavailability from missing nicknames, missing prior agent instances, or lack of a dedicated launcher alias.
- Every required delegated specialist must exist as a native Codex agent under
.codex/agents/. If a required agent file is missing, set blocked_reason to spawn_agent_unavailable and stop.
- Required delegated steps MUST delegate or stop execution.
- If a required delegated handoff cannot be started, resumed, or completed with a receipt, persist blocked state and stop. Do not perform that step directly.
- Direct local implementation is prohibited. Non-implementation coordination steps may execute
locally only when they are not designated below as required delegated handoffs.
Root-only epic boundary
This workflow handles one feature or bug. It must never delegate to epic-planner or
epic-orchestrator. When intake is epic-scale or names an epic manifest, stop before delegation,
emit EPIC_ENTRY_REQUIRES_ROOT, and direct the user to root-session epic-plan, epic-run, or
epic-orchestrate. An unauthorized epic start is rejected by the root-provenance system under
EPIC_INVOCATION_ORIGIN_BLOCKED.
Epic preparation child
The literal marker Preparation mode: true selects route_id: preparation. Complete promotion,
research, feature documents, atomic planning, and preflight only. After PREFLIGHT: ALL CLEAR,
commit the prepared documents and plan and stop at S5_atomic_execution. Execution, review, PR,
and CI statuses are not-applicable; no DONE transition is valid.
Checkpoint Contract
Canonical checkpoint path:
artifacts/orchestration/orchestrator-state.json
Canonical route matrix:
config/orchestration-routing.json
Persist and reuse these fields exactly:
objective
change_budget_estimate
path_selected
promotion-type
short-name
pre-issue-branch
final-branch
branch-rename-status
relativeFile
long-name
issue-num
feature-folder
work-mode
plan-path
review-status
remediation-inputs-path
remediation-plan-path
remediation-pass
commit-context-path
pr-context-base-branch
completed_steps
next_step
last_updated
step5_status
step6_status
step7_status
step8_status
step9_status
step10_status
delegation_receipts
blocked_reason
route_id
required_agents
required_skills
required_mcp_tools
skill_receipts
mcp_call_receipts
local_execution_overrides
delegation_bypasses
lifecycle_operations
pre-implementation-violation
Plan-path invariant:
${plan-path} is resolved only after ${feature-folder} exists.
- The orchestrator MUST enumerate existing
${feature-folder}/plan*.md files
in deterministic filename order before planner delegation.
- If any existing plan file is present,
${plan-path} MUST be that first
existing file. Do not persist or delegate against ${feature-folder}/plan.md
when a timestamped scaffolded plan already exists.
- If checkpoint state conflicts with the resolved existing plan file, correct
checkpoint state before delegation and do not create a duplicate plan.
For small-path runs, also persist:
bootstrap_mode
phase0_execution_summary
small_path_qc_summary
small_path_audit_artifacts
resume_after_manual_bootstrap
Status enums:
step5_status / step6_status / step7_status / step8_status / step9_status / step10_status MUST use one of:
not-applicable
pending
delegated
verified
blocked
Blocked-reason enum:
blocked_reason MUST be one of:
none
checkpoint_conflict
lifecycle_preconditions_missing
spawn_agent_unavailable
delegation_launch_failed
delegate_no_receipt
delegate_contract_incomplete
validator_failed
user_requested_stop
review_status_missing
commit_context_missing
no_staged_changes
pre_implementation_gate_violation
premise_falsified — Every delegation and validator succeeded, but evidence gathered during execution falsified the premise on which the plan was built, so continuing would implement an invalid plan.
external_dependency — The run cannot proceed because a system, service, runtime, or artifact outside the repository's control is unavailable or mismatched, and no in-repository remediation can resolve it.
policy_hold — The run is stopped because proceeding requires a policy decision, exception, or authorization that the orchestrator is not permitted to grant autonomously.
awaiting_ci — The run is waiting for a CI result that has not yet completed, and no remediation is warranted until that result is available.
human_decision_required — The run requires a human to choose between alternatives or approve a direction before it can continue.
Blocked-reason partition: none (or JSON null) means the run is not blocked. The six validator-enforced members spawn_agent_unavailable, delegation_launch_failed, delegate_no_receipt, delegate_contract_incomplete, validator_failed, and user_requested_stop form the mechanical partition. The five members premise_falsified, external_dependency, policy_hold, awaiting_ci, and human_decision_required form the non-mechanical partition. The full vocabulary is published in .claude/rules/orchestrator-state.md.
Pre-implementation violation schema:
pre-implementation-violation MUST be either null or an object with:
violated_gate
attempted_action
known_mutated_files
corrective_next_step
recorded_at
Delegation receipt schema:
delegation_receipts MUST be a list of objects with:
step
agent_name
agent_id
skill_source
started_at
completed_at
result_signal
artifact_paths
Skill receipt schema:
skill_receipts MUST be a list of objects with:
skill
required
acknowledged_at_phase
evidence
MCP receipt schema:
mcp_call_receipts MUST be a list of objects with:
Completion-state invariants:
route_id MUST identify an entry in config/orchestration-routing.json.
required_agents, required_skills, and required_mcp_tools MUST exactly
match the selected route matrix entry.
- every required agent MUST have a matching
delegation_receipts[].agent_name.
- every required skill MUST have a matching required
skill_receipts[].skill
with non-empty evidence.
- every required MCP tool MUST have a successful
mcp_call_receipts[].tool
receipt with non-empty evidence, unless a valid issue_adoption record
waives the tool.
local_execution_overrides and delegation_bypasses MUST be empty lists at
completion.
- every recorded
lifecycle_operations[] item MUST use surface: "mcp".
Required-delegation step map:
- small path:
- Step 5 ->
atomic-planner
- Step 6 ->
atomic-executor
- implementation delivery -> language-resolved generated typed-engineer profile
- Step 9 ->
atomic-executor
- Step 10 ->
feature-reviewer
- large path:
- Step 7 ->
atomic-planner
- Step 8 ->
atomic-executor
- Step 9 ->
feature-reviewer
- remediation planning:
- review-triggered remediation planning ->
atomic-planner
- remediation preflight clearance ->
atomic-executor
- remediation execution ->
atomic-executor
- remediation commit message ->
commit-steward
- remediation re-review ->
feature-reviewer
Deterministic Handoff Result Contract
Do not advance on summaries alone when an exact result signal is required.
- feature review result:
REVIEW_STATUS: PASS
REVIEW_STATUS: REMEDIATION_REQUIRED
REVIEW_STATUS: HALT_NON_REMEDIABLE
REVIEW_STATUS: AWAITING_CI
FEATURE_FOLDER: <path>
POLICY_AUDIT: <path>
CODE_REVIEW: <path>
FEATURE_AUDIT: <path>
REMEDIATION_INPUTS: <path-or-NONE>
REMEDIATION_PLAN: <path-or-NONE>
- remediation preflight result:
PREFLIGHT: ALL CLEAR
PREFLIGHT: REVISIONS REQUIRED
- commit-steward result:
- one fenced
text code block only
If an exact signal or required path field is missing, set the relevant step to blocked, set blocked_reason to delegate_contract_incomplete, and stop.
Resume Rules
- Read the checkpoint first when it exists.
- If the recorded mission is incomplete, resume from
next_step.
- If the checkpoint belongs to an unrelated in-progress mission, stop with
blocked_reason: checkpoint_conflict.
- Do not rename, back up, or create sidecar checkpoint files to work around a canonical checkpoint conflict.
- Restart only when the user explicitly requests restart.
- Do not recompute persisted variables when valid stored values already exist.
Routing Rules
- Estimate the likely touched production files and test files first.
- Determine the dominant implementation language.
- If the scope is primarily C#, use
csharp-change-budget-router.
- If the scope is primarily PowerShell, use
powershell-change-budget-router.
- If the scope is mixed-language, ambiguous, or unsupported by an existing change-budget router, fail closed to the large path.
- Treat any request outside the applicable small-path budget as large path.
- Select
route_id from config/orchestration-routing.json and persist the
exact required agent, skill, and MCP lists from the matrix before starting
lifecycle automation.
- Keep topology routing separate from C1-C4 model routing. Persist both topology and
model-routing receipts and select the exact generated Codex deployment agent before every
delegation.
- Use Sol/High for standalone ceiling-C3 work. Use Astra/High for C3 epic children or C3 work in
an orchestration whose monotonic ceiling is C4. Do not infer this overlay from file count.
Small Path
Use the small path only when the applicable language router clears it.
Required behavior:
- Set
${work-mode} to minor-audit.
- Use
feature-promotion-lifecycle as the source of truth for lifecycle variables, branch naming, and ${plan-path} resolution.
- Route all promotion, issue, and feature-folder automation through
repo-automation-adapter.
- Enforce lifecycle preconditions before any active-folder authoring:
- route metadata persistence must be complete in the canonical checkpoint before potential-entry creation
${pre-issue-branch} must be created or verified before potential-entry creation
${relativeFile} must resolve to a real potential markdown path and must not be NONE, TBD, or empty
${issue-num} must be numeric before final branch rename or new_active_feature_folder runs
- final branch rename must complete before
new_active_feature_folder runs
- do not create or edit
${feature-folder}/issue.md, ${feature-folder}/spec.md, ${feature-folder}/user-story.md, or plan*.md until potential-entry creation, promotion, final branch rename, and folder creation all succeed
- if any lifecycle precondition fails, set the relevant step status to
blocked, set blocked_reason to lifecycle_preconditions_missing, and stop
- Enforce minor-audit folder integrity:
${feature-folder}/issue.md must exist
${feature-folder}/spec.md must be absent
${feature-folder}/user-story.md must be absent
- Spawn
atomic-planner to create or revise the minimal plan at ${plan-path}.
- Include the directive
DIRECTIVE: MINIMAL-AUDIT PLAN REQUIRED
- Require the same
${plan-path} to be updated in place
- Do not continue until the planner reports
PREFLIGHT: ALL CLEAR
- Record a delegation receipt and set
step5_status to verified before continuing
- If the handoff cannot be started or does not return a receipt, set
step5_status to blocked, set blocked_reason, and stop
- Spawn
atomic-executor to execute Phase 0 only.
- Record a delegation receipt and set
step6_status to verified before branching
- If the handoff cannot be started or does not return a receipt, set
step6_status to blocked, set blocked_reason, and stop
- If and only if the initial user request explicitly opted into manual orchestration from the beginning, persist the resume checkpoint and stop after Phase 0.
- Otherwise manual bootstrap is prohibited; continue automated execution.
- Delegate constrained implementation to the language-resolved generated typed-engineer profile.
- Python ->
python-typed-engineer-<profile>
- PowerShell ->
powershell-typed-engineer-<profile>
- C# ->
csharp-typed-engineer-<profile>
- TypeScript has no canonical small-path budget and therefore routes to the large path
<profile> comes from the persisted C1-C4 routing receipt and never from file count
- pass the approved plan, exact file budget, feature folder, and Phase 0 baseline evidence
- require implementation and QA result fields appropriate to the language policy
- record topology, model-routing, and delegation receipts before continuing
- if no typed-engineer family exists for the dominant language, fail closed to large-path
root deployment instead of implementing locally
- Validate the delivered work against
${feature-folder}/issue.md and persist plan or acceptance-criteria checkoffs before review.
- MUST delegate to
atomic-executor for validation and checklist updates
- Record a delegation receipt and set
step9_status to verified before continuing
- If the handoff cannot be started or does not return a receipt, set
step9_status to blocked, set blocked_reason, and stop
- Run reduced audit:
- MUST delegate to
feature-reviewer
- require the exact
REVIEW_STATUS and artifact-path fields from the review result
- Record a delegation receipt and set
step10_status to verified before continuing
- If the handoff cannot be started or does not return a receipt, set
step10_status to blocked, set blocked_reason, and stop
- If review returns
REVIEW_STATUS: REMEDIATION_REQUIRED, run the shared remediation loop.
- Treat the returned
REMEDIATION_INPUTS and REMEDIATION_PLAN paths as mandatory inputs
- If any required remediation handoff cannot be started or does not return a receipt, set
blocked_reason and stop
Large Path
Use the large path for any request that exceeds or bypasses the small-path router.
Required behavior:
- Set
${work-mode} to:
full-feature for feature work
full-bug for bug work
- Use
feature-promotion-lifecycle as the source of truth for lifecycle variables, branch naming, and ${plan-path} resolution.
- Route all promotion, issue, and feature-folder automation through
repo-automation-adapter.
- Enforce lifecycle preconditions before any active-folder authoring:
- route metadata persistence must be complete in the canonical checkpoint before potential-entry creation
${pre-issue-branch} must be created or verified before potential-entry creation
${relativeFile} must resolve to a real potential markdown path and must not be NONE, TBD, or empty
${issue-num} must be numeric before final branch rename or new_active_feature_folder runs
- final branch rename must complete before
new_active_feature_folder runs
- do not create or edit
${feature-folder}/issue.md, ${feature-folder}/spec.md, ${feature-folder}/user-story.md, or plan*.md until potential-entry creation, promotion, final branch rename, and folder creation all succeed
- if any lifecycle precondition fails, set the relevant step status to
blocked, set blocked_reason to lifecycle_preconditions_missing, and stop
- Complete the requirements-authoring steps before planning:
- fill the potential entry details
- create or refresh research artifacts
- complete
spec.md and user-story.md when the selected work mode requires them
- Prefer dedicated migrated specialists for those authoring steps when they exist.
- When those specialists are not yet migrated, perform the authoring steps directly without changing template headings.
- Spawn
atomic-planner to finalize ${plan-path} and require PREFLIGHT: ALL CLEAR.
Hard enforcement for Step 7:
- Before spawning
atomic-planner, resolve ${plan-path} by enumerating
existing ${feature-folder}/plan*.md files. Reuse the first existing file
in deterministic filename order, including timestamped scaffolded plans.
- The planning route MUST be
atomic-planner -> atomic-executor for preflight validation.
- The planner MUST update
${plan-path} in place and MUST NOT create additional plan.*.md files for revisions.
- The approved plan MUST include explicit Phase 0 baseline evidence tasks and explicit final-QA evidence or coverage tasks for each language in scope where policy requires them.
- Do not mark Step 7 complete until delegate output includes both a concrete
plan-path and final PREFLIGHT: ALL CLEAR.
- Do not perform planning locally when this delegation cannot be started; set
step7_status to blocked, set blocked_reason, and stop.
- Record a delegation receipt and set
step7_status to verified only after delegate output and validator checks pass.
- Spawn
atomic-executor to execute the approved plan.
Hard enforcement for Step 8:
- Do not mark Step 8 complete until execution output includes execution summary, QA summary, lint/type/test/coverage deltas, and numeric baseline/post/new-code coverage metrics where policy requires them.
- Do not accept PASS execution outcomes when required baseline or final-QA artifacts are missing, when checklist state is not backed by artifacts, or when coverage-bearing plan tasks remain unverified.
- Do not perform execution locally when this delegation cannot be started; set
step8_status to blocked, set blocked_reason, and stop.
- Record a delegation receipt and set
step8_status to verified only after delegate output and validator checks pass.
- Spawn
feature-reviewer for post-implementation review.
Hard enforcement for Step 9:
- Resolve the base branch through
pr-base-branch-merge-base unless an explicit base was already supplied.
- Load canonical PR-context artifacts and refresh them through
repo-automation-adapter when they are missing or stale relative to the current branch state.
- Require the exact
REVIEW_STATUS and artifact-path fields from the review result.
- Do not mark Step 9 complete until expected review artifacts are present on disk in
${feature-folder}.
- Do not accept PASS review outcomes when required coverage fields are left unverified, when PR-context artifacts are missing or stale relative to the current branch state, or when required remediation artifacts are missing.
- Do not perform review locally when this delegation cannot be started; set
step9_status to blocked, set blocked_reason, and stop.
- Record a delegation receipt and set
step9_status to verified only after delegate output and validator checks pass.
- If review returns
REVIEW_STATUS: REMEDIATION_REQUIRED, run the shared remediation loop until the latest review returns REVIEW_STATUS: PASS.
- remediation planning, preflight clearance, remediation execution, remediation commit-message generation, and re-review delegations are all mandatory; if any cannot be started, set
blocked_reason and stop
Shared Remediation Loop
Apply this loop after any required review returns REVIEW_STATUS: REMEDIATION_REQUIRED.
Attempt accounting: remediation-pass equals remediation_loop.completed_attempts, the number of cycles whose candidate_applied is true. A cycle records candidate_applied: true only when remediation execution completed and the remediation commit recorded a non-empty change set. The active cycle number is completed_attempts + 1, and a cycle without a candidate consumes no number. Cap: halt after three completed attempts, that is, when completed_attempts equals 3 and the latest review is not REVIEW_STATUS: PASS, with step6_status: "blocked_remediation_loop_limit".
Halt and wait branches: a review that returns REVIEW_STATUS: HALT_NON_REMEDIABLE or REVIEW_STATUS: AWAITING_CI never enters or continues this loop and opens no cycle. On HALT_NON_REMEDIABLE, set blocked_reason to the highest-precedence halt class present (human_decision_required, then policy_hold, then external_dependency), append one human_interaction.requirements[] entry with response: "halt" per halt class present, and stop. On AWAITING_CI, set blocked_reason: "awaiting_ci", set next_step to the step that re-checks, persist, and stop; on resume, set blocked_reason: "none" and re-run that step.
- Persist
review-status, remediation-inputs-path, remediation-plan-path, and remediation-pass in the checkpoint.
- Delegate
atomic-executor in validation-only mode against the exact remediation-plan-path.
- If the executor returns
PREFLIGHT: REVISIONS REQUIRED, delegate atomic-planner to update the same remediation-plan-path in place and then repeat preflight clearance.
- Only after
PREFLIGHT: ALL CLEAR, delegate atomic-executor to execute the remediation plan exactly as written.
- Stage all files with
git add -A.
- If staging is empty after execution, set
blocked_reason to no_staged_changes and stop.
- Record
candidate_applied: false for that cycle; it consumes no attempt number.
- Use
repo-automation-adapter to run MCP tool collect_commit_context, capture the returned on-disk artifact path as commit-context-path, and stop with blocked_reason: commit_context_missing if that path is unavailable.
- Delegate
commit-steward using commit-context-path as the authoritative staged-change input.
- Commit the staged work with the exact message returned by
commit-steward.
- Use
repo-automation-adapter to refresh PR-context artifacts through MCP tool collect_pr_context with the resolved base branch.
- Delegate
feature-reviewer again with the refreshed PR context.
- Record
candidate_applied: true for the cycle and set remediation_loop.completed_attempts and remediation-pass to the new count. If the new review still returns REVIEW_STATUS: REMEDIATION_REQUIRED, repeat the loop under the cap. Exit only when the latest review returns REVIEW_STATUS: PASS, or follow the halt or wait branch.
Completion Gates
Do not claim mission completion until all of the following are true:
- the selected path completed end to end
- all required delegations completed with receipts
- small-path implementation has a receipt from the exact language-specific generated
typed-engineer deployment profile
- all required skills have
skill_receipts with evidence
- all required MCP tools have successful
mcp_call_receipts, unless a valid issue_adoption record waives the tool
- no local execution override or delegation bypass is recorded
- the checkpoint is updated with the final state
- the canonical checkpoint path was used without sidecar replacement or backup substitution
${relativeFile} is a real promoted-input path and ${issue-num} is numeric when lifecycle setup was required
${feature-folder} and ${plan-path} are known when lifecycle setup was required
- route metadata, selected work mode, branch state, lifecycle receipts, and
folder readiness are present before implementation begins
- the approved plan is executor-compliant and references the required baseline and final-QA evidence tasks
- required review artifacts exist on disk
- small path has Phase 0 evidence plus reduced audit artifacts
- large path has policy, code, and feature audit artifacts
- required baseline and final-QA evidence artifacts referenced by the approved plan exist on disk
- any required remediation artifacts exist on disk and the latest re-review is clean
- any required remediation loop run also includes a remediation execution receipt, a remediation commit receipt, and a final
REVIEW_STATUS: PASS
- validator-backed checks for the approved plan, policy audit, code review, feature audit, and checkpoint state pass
- the canonical checkpoint passes
validate_orchestration_artifacts with artifact_type: "orchestrator-state", require_complete: true, require_codex_topology: true, and require_codex_model_routing: true
- every GitHub check on the current PR head SHA passed or was skipped before PR/DONE completion
Hard Constraints
- Do not stop after one delegation when required downstream steps remain.
- Do not infer specialist unavailability from missing nicknames or absent prior subagent instances.
- Do not call
drmCopilotExtension.* directly from this workflow.
- Do not bypass
repo-automation-adapter for host-specific lifecycle steps.
- Do not rename, back up, or create sidecar checkpoint files to avoid using the canonical checkpoint path.
- Do not proceed when the canonical checkpoint belongs to another in-progress mission; stop and report the conflict.
- Do not create or edit active feature docs before route metadata persistence,
pre-issue branch setup, potential-entry creation, issue promotion, final branch
rename, and active-folder creation succeed.
- Do not call
new_active_feature_folder before ${issue-num} is numeric,
backed by promotion output, and the final branch rename is complete.
- Do not begin implementation edits, formatters, tests, staging, commits, or
implementation delegation when route metadata, branch state, lifecycle
receipts, or folder readiness are missing.
- Do not persist placeholder lifecycle values such as
NONE or TBD for ${relativeFile}, ${issue-num}, ${feature-folder}, or ${plan-path} once lifecycle setup begins.
- Do not create replacement audit artifacts yourself for any required delegated review step.
- Do not execute required delegated steps locally as a fallback.
- Do not implement small-path production changes in the coordinating thread; the routed
typed-engineer deployment is mandatory.
- Do not accept stale PR-context artifacts, unsupported checklist checkoffs, or missing required evidence as PASS outcomes.
- Do not treat Codex lifecycle hooks as the hard completion boundary; use deterministic validator and CI gates for completion enforcement.
- Do not claim completion without reporting the checkpoint path and the created or updated artifact paths.
1---2name: orchestrator-workflow3description: 'Coordinate a feature or bug request from intake through promotion, planning, execution, validation, and review by selecting the correct small or large path and delegating to migrated Codex specialists when available.'4metadata:5 source: https://skillmd.com/skills/drmoisan/orchestrator-workflow6---78# Orchestrator Workflow910Top-level delivery orchestration workflow for Codex.1112## Required Shared Skills1314Always apply:15- `policy-compliance-order`16- `feature-promotion-lifecycle`17- `repo-automation-adapter`18- `atomic-plan-contract`19- `acceptance-criteria-tracking`20- `pr-context-artifacts`21- `pr-base-branch-merge-base`2223Use as needed:24- `csharp-change-budget-router`25- `powershell-change-budget-router`26- `feature-review`2728## Role2930- Coordinate the mission from intake through completion.31- Resolve required specialist delegation mechanically instead of by judgment.32- Required delegated specialists:33 - `atomic-planner`34 - `atomic-executor`35 - `feature-review`36 - `feature-reviewer`37 - `task-researcher`38 - `prd-feature`39 - `staged-review`40 - `epic-review`41 - `status-updater`42 - `python-typed-engineer`43 - `powershell-typed-engineer`44 - `csharp-typed-engineer`45 - `typescript-engineer`46 - `commit-steward`47- Deterministic availability rule:48 - if the host exposes `spawn_agent` and the required `.codex/agents/<name>.toml` file exists, treat that delegated specialist as available,49 - do not infer unavailability from missing nicknames, missing prior agent instances, or lack of a dedicated launcher alias.50- Every required delegated specialist must exist as a native Codex agent under `.codex/agents/`. If a required agent file is missing, set `blocked_reason` to `spawn_agent_unavailable` and stop.51- Required delegated steps MUST delegate or stop execution.52- If a required delegated handoff cannot be started, resumed, or completed with a receipt, persist blocked state and stop. Do not perform that step directly.53- Direct local implementation is prohibited. Non-implementation coordination steps may execute54 locally only when they are not designated below as required delegated handoffs.5556### Root-only epic boundary5758This workflow handles one feature or bug. It must never delegate to `epic-planner` or59`epic-orchestrator`. When intake is epic-scale or names an epic manifest, stop before delegation,60emit `EPIC_ENTRY_REQUIRES_ROOT`, and direct the user to root-session `epic-plan`, `epic-run`, or61`epic-orchestrate`. An unauthorized epic start is rejected by the root-provenance system under62`EPIC_INVOCATION_ORIGIN_BLOCKED`.6364### Epic preparation child6566The literal marker `Preparation mode: true` selects `route_id: preparation`. Complete promotion,67research, feature documents, atomic planning, and preflight only. After `PREFLIGHT: ALL CLEAR`,68commit the prepared documents and plan and stop at `S5_atomic_execution`. Execution, review, PR,69and CI statuses are `not-applicable`; no DONE transition is valid.7071## Checkpoint Contract7273Canonical checkpoint path:74- `artifacts/orchestration/orchestrator-state.json`7576Canonical route matrix:77- `config/orchestration-routing.json`7879Persist and reuse these fields exactly:80- `objective`81- `change_budget_estimate`82- `path_selected`83- `promotion-type`84- `short-name`85- `pre-issue-branch`86- `final-branch`87- `branch-rename-status`88- `relativeFile`89- `long-name`90- `issue-num`91- `feature-folder`92- `work-mode`93- `plan-path`94- `review-status`95- `remediation-inputs-path`96- `remediation-plan-path`97- `remediation-pass`98- `commit-context-path`99- `pr-context-base-branch`100- `completed_steps`101- `next_step`102- `last_updated`103- `step5_status`104- `step6_status`105- `step7_status`106- `step8_status`107- `step9_status`108- `step10_status`109- `delegation_receipts`110- `blocked_reason`111- `route_id`112- `required_agents`113- `required_skills`114- `required_mcp_tools`115- `skill_receipts`116- `mcp_call_receipts`117- `local_execution_overrides`118- `delegation_bypasses`119- `lifecycle_operations`120- `pre-implementation-violation`121122Plan-path invariant:123- `${plan-path}` is resolved only after `${feature-folder}` exists.124- The orchestrator MUST enumerate existing `${feature-folder}/plan*.md` files125 in deterministic filename order before planner delegation.126- If any existing plan file is present, `${plan-path}` MUST be that first127 existing file. Do not persist or delegate against `${feature-folder}/plan.md`128 when a timestamped scaffolded plan already exists.129- If checkpoint state conflicts with the resolved existing plan file, correct130 checkpoint state before delegation and do not create a duplicate plan.131132For small-path runs, also persist:133- `bootstrap_mode`134- `phase0_execution_summary`135- `small_path_qc_summary`136- `small_path_audit_artifacts`137- `resume_after_manual_bootstrap`138139Status enums:140- `step5_status` / `step6_status` / `step7_status` / `step8_status` / `step9_status` / `step10_status` MUST use one of:141 - `not-applicable`142 - `pending`143 - `delegated`144 - `verified`145 - `blocked`146147Blocked-reason enum:148- `blocked_reason` MUST be one of:149 - `none`150 - `checkpoint_conflict`151 - `lifecycle_preconditions_missing`152 - `spawn_agent_unavailable`153 - `delegation_launch_failed`154 - `delegate_no_receipt`155 - `delegate_contract_incomplete`156 - `validator_failed`157 - `user_requested_stop`158 - `review_status_missing`159 - `commit_context_missing`160 - `no_staged_changes`161 - `pre_implementation_gate_violation`162 - `premise_falsified` — Every delegation and validator succeeded, but evidence gathered during execution falsified the premise on which the plan was built, so continuing would implement an invalid plan.163 - `external_dependency` — The run cannot proceed because a system, service, runtime, or artifact outside the repository's control is unavailable or mismatched, and no in-repository remediation can resolve it.164 - `policy_hold` — The run is stopped because proceeding requires a policy decision, exception, or authorization that the orchestrator is not permitted to grant autonomously.165 - `awaiting_ci` — The run is waiting for a CI result that has not yet completed, and no remediation is warranted until that result is available.166 - `human_decision_required` — The run requires a human to choose between alternatives or approve a direction before it can continue.167168Blocked-reason partition: `none` (or JSON `null`) means the run is not blocked. The six validator-enforced members `spawn_agent_unavailable`, `delegation_launch_failed`, `delegate_no_receipt`, `delegate_contract_incomplete`, `validator_failed`, and `user_requested_stop` form the mechanical partition. The five members `premise_falsified`, `external_dependency`, `policy_hold`, `awaiting_ci`, and `human_decision_required` form the non-mechanical partition. The full vocabulary is published in `.claude/rules/orchestrator-state.md`.169170Pre-implementation violation schema:171- `pre-implementation-violation` MUST be either `null` or an object with:172 - `violated_gate`173 - `attempted_action`174 - `known_mutated_files`175 - `corrective_next_step`176 - `recorded_at`177178Delegation receipt schema:179- `delegation_receipts` MUST be a list of objects with:180 - `step`181 - `agent_name`182 - `agent_id`183 - `skill_source`184 - `started_at`185 - `completed_at`186 - `result_signal`187 - `artifact_paths`188189Skill receipt schema:190- `skill_receipts` MUST be a list of objects with:191 - `skill`192 - `required`193 - `acknowledged_at_phase`194 - `evidence`195196MCP receipt schema:197- `mcp_call_receipts` MUST be a list of objects with:198 - `tool`199 - `ok`200 - `evidence`201202Completion-state invariants:203- `route_id` MUST identify an entry in `config/orchestration-routing.json`.204- `required_agents`, `required_skills`, and `required_mcp_tools` MUST exactly205 match the selected route matrix entry.206- every required agent MUST have a matching `delegation_receipts[].agent_name`.207- every required skill MUST have a matching required `skill_receipts[].skill`208 with non-empty evidence.209- every required MCP tool MUST have a successful `mcp_call_receipts[].tool`210 receipt with non-empty evidence, unless a valid `issue_adoption` record211 waives the tool.212- `local_execution_overrides` and `delegation_bypasses` MUST be empty lists at213 completion.214- every recorded `lifecycle_operations[]` item MUST use `surface: "mcp"`.215216Required-delegation step map:217- small path:218 - Step 5 -> `atomic-planner`219 - Step 6 -> `atomic-executor`220 - implementation delivery -> language-resolved generated typed-engineer profile221 - Step 9 -> `atomic-executor`222 - Step 10 -> `feature-reviewer`223- large path:224 - Step 7 -> `atomic-planner`225 - Step 8 -> `atomic-executor`226 - Step 9 -> `feature-reviewer`227- remediation planning:228 - review-triggered remediation planning -> `atomic-planner`229 - remediation preflight clearance -> `atomic-executor`230 - remediation execution -> `atomic-executor`231 - remediation commit message -> `commit-steward`232 - remediation re-review -> `feature-reviewer`233234## Deterministic Handoff Result Contract235236Do not advance on summaries alone when an exact result signal is required.237238- feature review result:239 - `REVIEW_STATUS: PASS`240 - `REVIEW_STATUS: REMEDIATION_REQUIRED`241 - `REVIEW_STATUS: HALT_NON_REMEDIABLE`242 - `REVIEW_STATUS: AWAITING_CI`243 - `FEATURE_FOLDER: <path>`244 - `POLICY_AUDIT: <path>`245 - `CODE_REVIEW: <path>`246 - `FEATURE_AUDIT: <path>`247 - `REMEDIATION_INPUTS: <path-or-NONE>`248 - `REMEDIATION_PLAN: <path-or-NONE>`249- remediation preflight result:250 - `PREFLIGHT: ALL CLEAR`251 - `PREFLIGHT: REVISIONS REQUIRED`252- commit-steward result:253 - one fenced `text` code block only254255If an exact signal or required path field is missing, set the relevant step to `blocked`, set `blocked_reason` to `delegate_contract_incomplete`, and stop.256257## Resume Rules2582591. Read the checkpoint first when it exists.2602. If the recorded mission is incomplete, resume from `next_step`.2613. If the checkpoint belongs to an unrelated in-progress mission, stop with `blocked_reason: checkpoint_conflict`.2624. Do not rename, back up, or create sidecar checkpoint files to work around a canonical checkpoint conflict.2635. Restart only when the user explicitly requests restart.2646. Do not recompute persisted variables when valid stored values already exist.265266## Routing Rules2672681. Estimate the likely touched production files and test files first.2692. Determine the dominant implementation language.2703. If the scope is primarily C#, use `csharp-change-budget-router`.2714. If the scope is primarily PowerShell, use `powershell-change-budget-router`.2725. If the scope is mixed-language, ambiguous, or unsupported by an existing change-budget router, fail closed to the large path.2736. Treat any request outside the applicable small-path budget as large path.2747. Select `route_id` from `config/orchestration-routing.json` and persist the275 exact required agent, skill, and MCP lists from the matrix before starting276 lifecycle automation.2778. Keep topology routing separate from C1-C4 model routing. Persist both topology and278 model-routing receipts and select the exact generated Codex deployment agent before every279 delegation.2809. Use Sol/High for standalone ceiling-C3 work. Use Astra/High for C3 epic children or C3 work in281 an orchestration whose monotonic ceiling is C4. Do not infer this overlay from file count.282283## Small Path284285Use the small path only when the applicable language router clears it.286287Required behavior:2882891. Set `${work-mode}` to `minor-audit`.2902. Use `feature-promotion-lifecycle` as the source of truth for lifecycle variables, branch naming, and `${plan-path}` resolution.2913. Route all promotion, issue, and feature-folder automation through `repo-automation-adapter`.2924. Enforce lifecycle preconditions before any active-folder authoring:293 - route metadata persistence must be complete in the canonical checkpoint before potential-entry creation294 - `${pre-issue-branch}` must be created or verified before potential-entry creation295 - `${relativeFile}` must resolve to a real potential markdown path and must not be `NONE`, `TBD`, or empty296 - `${issue-num}` must be numeric before final branch rename or `new_active_feature_folder` runs297 - final branch rename must complete before `new_active_feature_folder` runs298 - do not create or edit `${feature-folder}/issue.md`, `${feature-folder}/spec.md`, `${feature-folder}/user-story.md`, or `plan*.md` until potential-entry creation, promotion, final branch rename, and folder creation all succeed299 - if any lifecycle precondition fails, set the relevant step status to `blocked`, set `blocked_reason` to `lifecycle_preconditions_missing`, and stop3005. Enforce minor-audit folder integrity:301 - `${feature-folder}/issue.md` must exist302 - `${feature-folder}/spec.md` must be absent303 - `${feature-folder}/user-story.md` must be absent3046. Spawn `atomic-planner` to create or revise the minimal plan at `${plan-path}`.305 - Include the directive `DIRECTIVE: MINIMAL-AUDIT PLAN REQUIRED`306 - Require the same `${plan-path}` to be updated in place307 - Do not continue until the planner reports `PREFLIGHT: ALL CLEAR`308 - Record a delegation receipt and set `step5_status` to `verified` before continuing309 - If the handoff cannot be started or does not return a receipt, set `step5_status` to `blocked`, set `blocked_reason`, and stop3107. Spawn `atomic-executor` to execute Phase 0 only.311 - Record a delegation receipt and set `step6_status` to `verified` before branching312 - If the handoff cannot be started or does not return a receipt, set `step6_status` to `blocked`, set `blocked_reason`, and stop3138. If and only if the initial user request explicitly opted into manual orchestration from the beginning, persist the resume checkpoint and stop after Phase 0.314 - Otherwise manual bootstrap is prohibited; continue automated execution.3159. Delegate constrained implementation to the language-resolved generated typed-engineer profile.316 - Python -> `python-typed-engineer-<profile>`317 - PowerShell -> `powershell-typed-engineer-<profile>`318 - C# -> `csharp-typed-engineer-<profile>`319 - TypeScript has no canonical small-path budget and therefore routes to the large path320 - `<profile>` comes from the persisted C1-C4 routing receipt and never from file count321 - pass the approved plan, exact file budget, feature folder, and Phase 0 baseline evidence322 - require implementation and QA result fields appropriate to the language policy323 - record topology, model-routing, and delegation receipts before continuing324 - if no typed-engineer family exists for the dominant language, fail closed to large-path325 root deployment instead of implementing locally32610. Validate the delivered work against `${feature-folder}/issue.md` and persist plan or acceptance-criteria checkoffs before review.327 - MUST delegate to `atomic-executor` for validation and checklist updates328 - Record a delegation receipt and set `step9_status` to `verified` before continuing329 - If the handoff cannot be started or does not return a receipt, set `step9_status` to `blocked`, set `blocked_reason`, and stop33011. Run reduced audit:331 - MUST delegate to `feature-reviewer`332 - require the exact `REVIEW_STATUS` and artifact-path fields from the review result333 - Record a delegation receipt and set `step10_status` to `verified` before continuing334 - If the handoff cannot be started or does not return a receipt, set `step10_status` to `blocked`, set `blocked_reason`, and stop33512. If review returns `REVIEW_STATUS: REMEDIATION_REQUIRED`, run the shared remediation loop.336 - Treat the returned `REMEDIATION_INPUTS` and `REMEDIATION_PLAN` paths as mandatory inputs337 - If any required remediation handoff cannot be started or does not return a receipt, set `blocked_reason` and stop338339## Large Path340341Use the large path for any request that exceeds or bypasses the small-path router.342343Required behavior:3443451. Set `${work-mode}` to:346 - `full-feature` for feature work347 - `full-bug` for bug work3482. Use `feature-promotion-lifecycle` as the source of truth for lifecycle variables, branch naming, and `${plan-path}` resolution.3493. Route all promotion, issue, and feature-folder automation through `repo-automation-adapter`.3504. Enforce lifecycle preconditions before any active-folder authoring:351 - route metadata persistence must be complete in the canonical checkpoint before potential-entry creation352 - `${pre-issue-branch}` must be created or verified before potential-entry creation353 - `${relativeFile}` must resolve to a real potential markdown path and must not be `NONE`, `TBD`, or empty354 - `${issue-num}` must be numeric before final branch rename or `new_active_feature_folder` runs355 - final branch rename must complete before `new_active_feature_folder` runs356 - do not create or edit `${feature-folder}/issue.md`, `${feature-folder}/spec.md`, `${feature-folder}/user-story.md`, or `plan*.md` until potential-entry creation, promotion, final branch rename, and folder creation all succeed357 - if any lifecycle precondition fails, set the relevant step status to `blocked`, set `blocked_reason` to `lifecycle_preconditions_missing`, and stop3585. Complete the requirements-authoring steps before planning:359 - fill the potential entry details360 - create or refresh research artifacts361 - complete `spec.md` and `user-story.md` when the selected work mode requires them3626. Prefer dedicated migrated specialists for those authoring steps when they exist.3637. When those specialists are not yet migrated, perform the authoring steps directly without changing template headings.3648. Spawn `atomic-planner` to finalize `${plan-path}` and require `PREFLIGHT: ALL CLEAR`.365 Hard enforcement for Step 7:366 - Before spawning `atomic-planner`, resolve `${plan-path}` by enumerating367 existing `${feature-folder}/plan*.md` files. Reuse the first existing file368 in deterministic filename order, including timestamped scaffolded plans.369 - The planning route MUST be `atomic-planner -> atomic-executor` for preflight validation.370 - The planner MUST update `${plan-path}` in place and MUST NOT create additional `plan.*.md` files for revisions.371 - The approved plan MUST include explicit Phase 0 baseline evidence tasks and explicit final-QA evidence or coverage tasks for each language in scope where policy requires them.372 - Do not mark Step 7 complete until delegate output includes both a concrete `plan-path` and final `PREFLIGHT: ALL CLEAR`.373 - Do not perform planning locally when this delegation cannot be started; set `step7_status` to `blocked`, set `blocked_reason`, and stop.374 - Record a delegation receipt and set `step7_status` to `verified` only after delegate output and validator checks pass.3759. Spawn `atomic-executor` to execute the approved plan.376 Hard enforcement for Step 8:377 - Do not mark Step 8 complete until execution output includes execution summary, QA summary, lint/type/test/coverage deltas, and numeric baseline/post/new-code coverage metrics where policy requires them.378 - Do not accept PASS execution outcomes when required baseline or final-QA artifacts are missing, when checklist state is not backed by artifacts, or when coverage-bearing plan tasks remain unverified.379 - Do not perform execution locally when this delegation cannot be started; set `step8_status` to `blocked`, set `blocked_reason`, and stop.380 - Record a delegation receipt and set `step8_status` to `verified` only after delegate output and validator checks pass.38110. Spawn `feature-reviewer` for post-implementation review.382 Hard enforcement for Step 9:383 - Resolve the base branch through `pr-base-branch-merge-base` unless an explicit base was already supplied.384 - Load canonical PR-context artifacts and refresh them through `repo-automation-adapter` when they are missing or stale relative to the current branch state.385 - Require the exact `REVIEW_STATUS` and artifact-path fields from the review result.386 - Do not mark Step 9 complete until expected review artifacts are present on disk in `${feature-folder}`.387 - Do not accept PASS review outcomes when required coverage fields are left unverified, when PR-context artifacts are missing or stale relative to the current branch state, or when required remediation artifacts are missing.388 - Do not perform review locally when this delegation cannot be started; set `step9_status` to `blocked`, set `blocked_reason`, and stop.389 - Record a delegation receipt and set `step9_status` to `verified` only after delegate output and validator checks pass.39011. If review returns `REVIEW_STATUS: REMEDIATION_REQUIRED`, run the shared remediation loop until the latest review returns `REVIEW_STATUS: PASS`.391 - remediation planning, preflight clearance, remediation execution, remediation commit-message generation, and re-review delegations are all mandatory; if any cannot be started, set `blocked_reason` and stop392393## Shared Remediation Loop394395Apply this loop after any required review returns `REVIEW_STATUS: REMEDIATION_REQUIRED`.396397Attempt accounting: `remediation-pass` equals `remediation_loop.completed_attempts`, the number of cycles whose `candidate_applied` is `true`. A cycle records `candidate_applied: true` only when remediation execution completed and the remediation commit recorded a non-empty change set. The active cycle number is `completed_attempts + 1`, and a cycle without a candidate consumes no number. Cap: halt after three completed attempts, that is, when `completed_attempts` equals 3 and the latest review is not `REVIEW_STATUS: PASS`, with `step6_status: "blocked_remediation_loop_limit"`.398399Halt and wait branches: a review that returns `REVIEW_STATUS: HALT_NON_REMEDIABLE` or `REVIEW_STATUS: AWAITING_CI` never enters or continues this loop and opens no cycle. On `HALT_NON_REMEDIABLE`, set `blocked_reason` to the highest-precedence halt class present (`human_decision_required`, then `policy_hold`, then `external_dependency`), append one `human_interaction.requirements[]` entry with `response: "halt"` per halt class present, and stop. On `AWAITING_CI`, set `blocked_reason: "awaiting_ci"`, set `next_step` to the step that re-checks, persist, and stop; on resume, set `blocked_reason: "none"` and re-run that step.4004011. Persist `review-status`, `remediation-inputs-path`, `remediation-plan-path`, and `remediation-pass` in the checkpoint.4022. Delegate `atomic-executor` in validation-only mode against the exact `remediation-plan-path`.4033. If the executor returns `PREFLIGHT: REVISIONS REQUIRED`, delegate `atomic-planner` to update the same `remediation-plan-path` in place and then repeat preflight clearance.4044. Only after `PREFLIGHT: ALL CLEAR`, delegate `atomic-executor` to execute the remediation plan exactly as written.4055. Stage all files with `git add -A`.4066. If staging is empty after execution, set `blocked_reason` to `no_staged_changes` and stop.407 - Record `candidate_applied: false` for that cycle; it consumes no attempt number.4087. Use `repo-automation-adapter` to run MCP tool `collect_commit_context`, capture the returned on-disk artifact path as `commit-context-path`, and stop with `blocked_reason: commit_context_missing` if that path is unavailable.4098. Delegate `commit-steward` using `commit-context-path` as the authoritative staged-change input.4109. Commit the staged work with the exact message returned by `commit-steward`.41110. Use `repo-automation-adapter` to refresh PR-context artifacts through MCP tool `collect_pr_context` with the resolved base branch.41211. Delegate `feature-reviewer` again with the refreshed PR context.41312. Record `candidate_applied: true` for the cycle and set `remediation_loop.completed_attempts` and `remediation-pass` to the new count. If the new review still returns `REVIEW_STATUS: REMEDIATION_REQUIRED`, repeat the loop under the cap. Exit only when the latest review returns `REVIEW_STATUS: PASS`, or follow the halt or wait branch.414415## Completion Gates416417Do not claim mission completion until all of the following are true:418419- the selected path completed end to end420- all required delegations completed with receipts421- small-path implementation has a receipt from the exact language-specific generated422 typed-engineer deployment profile423- all required skills have `skill_receipts` with evidence424- all required MCP tools have successful `mcp_call_receipts`, unless a valid `issue_adoption` record waives the tool425- no local execution override or delegation bypass is recorded426- the checkpoint is updated with the final state427- the canonical checkpoint path was used without sidecar replacement or backup substitution428- `${relativeFile}` is a real promoted-input path and `${issue-num}` is numeric when lifecycle setup was required429- `${feature-folder}` and `${plan-path}` are known when lifecycle setup was required430- route metadata, selected work mode, branch state, lifecycle receipts, and431 folder readiness are present before implementation begins432- the approved plan is executor-compliant and references the required baseline and final-QA evidence tasks433- required review artifacts exist on disk434- small path has Phase 0 evidence plus reduced audit artifacts435- large path has policy, code, and feature audit artifacts436- required baseline and final-QA evidence artifacts referenced by the approved plan exist on disk437- any required remediation artifacts exist on disk and the latest re-review is clean438- any required remediation loop run also includes a remediation execution receipt, a remediation commit receipt, and a final `REVIEW_STATUS: PASS`439- validator-backed checks for the approved plan, policy audit, code review, feature audit, and checkpoint state pass440- the canonical checkpoint passes `validate_orchestration_artifacts` with `artifact_type: "orchestrator-state"`, `require_complete: true`, `require_codex_topology: true`, and `require_codex_model_routing: true`441- every GitHub check on the current PR head SHA passed or was skipped before PR/DONE completion442443## Hard Constraints444445- Do not stop after one delegation when required downstream steps remain.446- Do not infer specialist unavailability from missing nicknames or absent prior subagent instances.447- Do not call `drmCopilotExtension.*` directly from this workflow.448- Do not bypass `repo-automation-adapter` for host-specific lifecycle steps.449- Do not rename, back up, or create sidecar checkpoint files to avoid using the canonical checkpoint path.450- Do not proceed when the canonical checkpoint belongs to another in-progress mission; stop and report the conflict.451- Do not create or edit active feature docs before route metadata persistence,452 pre-issue branch setup, potential-entry creation, issue promotion, final branch453 rename, and active-folder creation succeed.454- Do not call `new_active_feature_folder` before `${issue-num}` is numeric,455 backed by promotion output, and the final branch rename is complete.456- Do not begin implementation edits, formatters, tests, staging, commits, or457 implementation delegation when route metadata, branch state, lifecycle458 receipts, or folder readiness are missing.459- Do not persist placeholder lifecycle values such as `NONE` or `TBD` for `${relativeFile}`, `${issue-num}`, `${feature-folder}`, or `${plan-path}` once lifecycle setup begins.460- Do not create replacement audit artifacts yourself for any required delegated review step.461- Do not execute required delegated steps locally as a fallback.462- Do not implement small-path production changes in the coordinating thread; the routed463 typed-engineer deployment is mandatory.464- Do not accept stale PR-context artifacts, unsupported checklist checkoffs, or missing required evidence as PASS outcomes.465- Do not treat Codex lifecycle hooks as the hard completion boundary; use deterministic validator and CI gates for completion enforcement.466- Do not claim completion without reporting the checkpoint path and the created or updated artifact paths.