| name | orchestrator |
| description | Orchestrate staged repository work through delegated preflight, single-writer implementation, independent validation, and a final closure gate. Use for multi-stage refactors, migrations, phased rollouts, or other work with clean stage boundaries. The parent coordinates; subagents perform all repository observation and mutation. |
Use this skill when repository work should advance through explicit stages with checkable boundaries.
Parent boundary
The parent plans and coordinates; it never performs repository work.
The parent may only:
- Define and amend the task contract, stages, and success criteria.
- Resolve the commit policy and role models with the user.
- Launch, resume, and coordinate subagents.
- Relay structured reports and request decisions.
- Decide whether to continue, repair, block, or complete the run.
The parent does not read repository files, inspect Git state or diffs, run commands or tests, edit files, stage changes, commit, or push. It works from user input, structured subagent reports, and recorded decisions.
Load the harness branch
Before the first subagent launch, identify the active agent harness and read exactly the matching reference:
Do not load references for inactive harnesses. The selected reference is authoritative for tool names, agent discovery, model syntax, context isolation, async behavior, child handles, and lifecycle operations. This file remains authoritative for stage semantics and safety.
Completion criterion: one harness reference is loaded, every required role can be represented in that harness, and unresolved model or lifecycle choices have been raised to the user.
Run preflight
Before Stage 1, resolve the commit policy unless the user already stated it. General permission to implement is not permission to commit.
Use exactly one policy:
all_stage_commits_authorizedask_before_each_stage_commitno_commits
Delegate preflight as the first repository-touching action. For a commit-capable policy on the default branch, the preflight child creates a dedicated local branch before any implementation mutation. Require it to report:
- A short run ID, repository root, original branch, active run branch, default branch, and
run_base_sha.
- Initial staged, unstaged, and untracked paths.
- A sanitized run-base evidence bundle: initial patches, untracked manifest, stage-relevant hashes or snapshots, and a state fingerprint.
- Protected dirty paths: every path dirty before the run.
- The run artifact directory, ledger path, and retention policy.
- Resolved role models, commit policy, and
no_push: true.
Protected dirty paths must not be edited, staged, restored, or otherwise altered. If one overlaps a possible stage write scope, stop before implementation and ask the user how to proceed.
Branch creation authorizes neither commit nor push.
Never push, force-push, amend, hard reset, clean, stash, or discard user changes unless the user separately requests that exact action.
Completion criterion: sanitized evidence can identify the initial state and distinguish later run changes without exposing protected content; protected paths are known; the commit policy and active run branch are explicit; and no unresolved protected-path overlap remains.
Run ledger
Keep one run-scoped artifact directory containing the narrative ledger and sanitized state evidence. Prefer a harness-shared directory outside the repository. If none exists, use a clearly identified repository-local fallback and exclude it from staging, commits, changed-file accounting, and hygiene findings except to verify that exclusion.
The narrative ledger records:
- Run metadata, original task contract, whole-task criteria, and amendments.
- User decisions, accepted risks, and commit policy.
- Stage contracts, attempts, verdicts, lessons, and commit records.
- Closure reports and final outcome.
Validators never read the narrative ledger. They may read only exact, named sanitized evidence artifacts containing factual state, never implementation rationale or conclusions. Do not copy secrets or full protected-file contents into evidence; prefer paths, metadata, hashes, and minimal safe snapshots.
Use stable IDs for stages, criteria, validation attempts, findings, decisions, and lessons. Fingerprint findings from criterion, location, and normalized cause. Append amendments and attempts; never rewrite history. Give each child only the contract, verified lessons, reports, and evidence it needs.
Keep artifacts while the run is active or blocked. Do not remove them before the final user report; repository-local cleanup requires prior authorization.
Stage contract
Define every stage before implementation:
- Stable stage ID, title, goal, user-visible outcome, and dependencies.
stage_base_sha; if the baseline is uncommitted, a sanitized stage-base evidence bundle sufficient to identify the baseline and distinguish the stage delta. Include exact content only for safe, stage-relevant files.- Expected write scope, explicit exclusions, and protected paths.
- Acceptance criteria with stable criterion IDs.
- Required checks and evidence.
- Commit intent under the run policy.
- Conditions requiring user input.
A repair that only satisfies the current contract remains in the same stage and resumes the same implementation context. A changed goal, scope, architecture, dependency, or criterion requires an appended contract amendment or a coherent repair stage.
Completion criterion: every intended change and required check maps to a criterion, exclusions are explicit, and the baseline can be independently identified well enough to compute the stage delta without exposing protected content.
Stage loop
- Launch one implementation child using the selected harness reference. It is the sole product-code writer for the stage. Give it the current contract and only relevant verified lessons.
- Require the implementation report to include changed files and behavior, commands and observed results, failed approaches worth preserving, remaining risks, current head, and repository-state evidence.
- After implementation finishes, launch a brand-new validation child in independent context. Give it the task and stage contracts, baseline SHA and named sanitized evidence, expected scope, exclusions, and protected paths. Do not provide the narrative ledger, implementation report, rationale, or conclusions.
- The validator independently computes repository state and the stage delta, runs relevant checks, and returns the report below.
- Delegate evidence review and lesson synthesis after both reports exist. The ledger child may question completed children only as the selected harness allows; it never changes product code or negotiates findings.
- A changed verdict must come from the validator as an amended report. Record the amendment before acting.
- Apply the verdict rules, obtain user decisions for risks and INFO findings, and apply commit policy. A
NOT_READY stage retains the implementation context for repair and returns to step 2.
- After an accepted stage's risk, INFO, and commit decisions finish, delegate a final ledger update and compact the stage record.
- Retire accepted-stage children according to the harness reference and never reuse a released validator.
Completion criterion: the stage has a final independent verdict; every finding, user decision, lesson, and commit result is recorded; product state matches the validated fingerprint; and every accepted-stage child is retired while a NOT_READY implementation child remains available for same-stage repair.
Stage validation report
## Stage Validation Report
### Identity
- run_id:
- stage_id:
- contract_version:
- attempt:
- validator_handle:
- model:
- stage_base_sha:
### Observed Repository State
- branch:
- head_sha:
- state_fingerprint:
- committed_delta:
- staged_delta:
- unstaged_delta:
- untracked_paths:
### Criterion Coverage
- criterion_id: PASS | FAIL | UNVERIFIED — evidence
### Checks
- command: exit/result — evidence
### Findings
- [BLOCKING | RISK | INFO] finding_id path:line — issue, impact, evidence, required action
### Hygiene
- protected_paths_untouched:
- unexpected_paths:
- ledger_excluded:
- required_checks_complete:
### Residual Risks
- risk_id — description and impact
### Verdict
PASS | CONDITIONAL | NOT_READY
Verdicts are mechanical:
PASS: every required criterion passes, required checks completed, state is known, and no BLOCKING or RISK finding remains.CONDITIONAL: every required criterion passes, no blocker remains, and explicit RISK findings can be meaningfully accepted by the user.NOT_READY: any required criterion failed or is unverified; required evidence is missing; state is unknown; protected paths overlap; or a blocking or hygiene finding exists.
Never use CONDITIONAL to disguise a failed or unverified criterion.
Verdict actions
NOT_READY: do not commit or release. Debrief, return the findings to the same implementation context, repair the same stage, and use a fresh validator.CONDITIONAL: ask the user to accept named risk IDs, continue repair, or stop. Acceptance records risk; it does not convert the verdict to PASS.PASS: resolve INFO findings, then apply commit policy.
Report every INFO finding and ask the user before fixing it. Every INFO decision happens before commit:
- Fix: after approval, the same implementation context changes the stage; invalidate the verdict and use a fresh validator.
- Defer or reject: record the user's decision and continue without changing product code.
If two consecutive fresh reports repeat the same blocking fingerprint, evidence, and required action, stop the automatic repair loop and report the blocker.
Commit handling
For an accepted stage:
all_stage_commits_authorized: delegate the validated stage commit unless an uncommitted chain already exists.ask_before_each_stage_commit: ask before delegating. If declined, either stop or, with explicit confirmation, mark the stage accepted-uncommitted and amend the remainder to no_commits.no_commits: record accepted-uncommitted state and begin or continue an uncommitted chain.
Once an uncommitted chain begins, make no later stage commits in the run. A later cumulative commit is a separate post-closure review and commit workflow.
Give the commit child a sanitized packet containing authorization, final report ID and fingerprint, exact validated paths and baseline, protected and initially staged paths, artifact-directory exclusion, expected branch, and validated head.
The commit child must confirm state still matches, inspect the index, stage only exact validated paths, preserve unrelated index entries, review the exact commit diff, commit only the stage delta, return the commit SHA and remaining state, and never push. If validated content changed or a safe path-limited commit cannot be formed, do not commit; return to validation or ask whether to continue uncommitted.
Completion criterion: either the exact validated delta has a reported commit SHA, or accepted-uncommitted state and the resulting policy amendment are recorded.
Lesson discipline
The ledger child may update only the ledger and approved run-note artifacts. Record a lesson only when it is likely to matter later, supported by concrete evidence, narrowly scoped, and not already represented.
Format:
lesson_id | scope | trigger | failed/baseline → validated delta | evidence references | rule
Choose one action per candidate: accept, merge(target), supersede(target), or reject. Prefer no_lesson over speculation. Do not preserve raw transcripts, incidental mistakes, or unsupported causes.
Compact each completed stage to outcome and evidence, final verdict and accepted risks, verified lessons, residual risks and deferred INFO, commit or accepted-uncommitted state, and the next-stage handoff.
Closure gate
After all planned stages are accepted and released, launch a fresh end-to-end validator. Give it the original contract and amendments, whole-task criteria, run_base_sha, protected initial paths, stage contracts and final decisions, expected branch or worktree identity, exact sanitized evidence paths, and artifact-directory exclusion. Do not provide implementation narratives or conclusions.
Require independent inspection of:
- Every whole-task criterion.
run_base_sha..HEAD plus remaining staged, unstaged, and untracked implementation state.- Cross-stage integration, interfaces, and regressions.
- Available build, test, migration, and deployment checks.
- Hygiene, unintended changes, protected paths, and artifact exclusion.
- The committed prefix and any accepted-uncommitted suffix.
Require Acceptance Coverage, Integration and Regression, Findings, Residual Risks, Verdict, and Proposed Repair Stages sections. Apply the same mechanical verdict mapping as stage validation.
PASS: resolve closure INFO findings, then close COMPLETE.CONDITIONAL: ask the user to accept named risks, repair, or stop. Explicit acceptance may close COMPLETE_WITH_ACCEPTED_RISK after INFO decisions.NOT_READY: append the smallest coherent repair stages, run each through the normal stage loop, then use another fresh closure validator.
Any closure product-code fix is a new repair stage. Group findings by shared cause or implementation boundary rather than creating one stage per finding. Apply the repeated-fingerprint stop rule at closure. Delegate the final ledger update after every closure report.
Completion criterion: every whole-task criterion has evidence, closure reached an accepted verdict, all final decisions are recorded, and no unreported repository state remains.
Run completion
If the user cancels, retire active children, delegate an ABANDONED ledger entry, preserve current commits and working-tree state without rollback, and apply the retention policy.
Always report:
COMPLETE, COMPLETE_WITH_ACCEPTED_RISK, BLOCKED, or ABANDONED.- Acceptance coverage and closure verdict.
- Stage commits or accepted-uncommitted state.
- Accepted risks, deferred INFO, and blockers.
- Checks actually run and observed results.
- Artifact directory, ledger path, and retention action.
Keep reports short and evidence-based. Distinguish verified outcomes, user-accepted risks, unverified checks, and remaining work.
