Phase Orchestrator
Goal
Run a phase-based plan through a repeatable delegated workflow. The plan is
the source of truth, any PRD/spec is supporting context, and each phase should
move through orientation, implementation, validation, review, plan updates, and
commits by default.
Use this skill only when the user explicitly asks for delegated phase
orchestration, invokes this skill, or asks to implement a plan/checklist using
subagents.
Companion Skills
This skill is the parent of a five-skill workflow:
write-phase-plan — authors plans in the format this skill consumes best.
phase-implementer — the delegated worker contract for implementing exactly
one phase (Phase Loop step 2).
phase-reviewer — the delegated worker contract for the review-and-fix pass
on a completed phase (Phase Loop step 4).
phase-final-reviewer — the delegated worker contract for the end-to-end
review of the whole feature after all phases (Final Whole-Feature Pass).
Each worker skill carries that role's standing rules: single-phase or
single-pass scope, no-revert discipline, no-commit default, and the required
final-response format. The parent's prompt only needs to supply the per-run
context from the templates below.
How to dispatch a worker role depends on the host:
- Named custom agents. If the host supports named custom agents or
subagent types (Cursor custom agents, for example), prefer a dedicated
agent per role whose definition is the matching companion skill's body.
- General subagent + installed skill. Otherwise, launch a general-purpose
subagent and instruct it to load and follow the matching installed
companion skill by name.
- Inline rules. If the subagent cannot load skills, paste the companion
skill's standing rules into the prompt along with the per-run context.
Host Mapping
- Use the host's todo tracker (
TodoWrite in Cursor) for the in-chat
orchestration state. Keep exactly one phase or orchestration step
in_progress.
- Use the host's subagent or task tool (
Subagent in Cursor) for delegated
implementation, broad read-only exploration, review/fix passes, validation,
and shell/git work when delegation is useful.
- Use fast read-only subagents (Cursor's
explore type, where available) for
broad codebase discovery before implementation.
- Use shell-focused subagents only for command-heavy validation or git
operations.
- Respect the user's or host's model choice for workers. Pass a model
explicitly only when the user requests a specific model for the run or for
a specific worker.
- Use background subagents when the host supports them and independent
read-only investigations can run in parallel.
- Do not assume subagents can be "closed"; inspect their final response and
continue from the parent agent.
- Record every spawned subagent's ID in the main thread (alongside its phase
in the todo/phase notes) when the host exposes one. Some hosts can resume a
completed subagent by ID with its full context preserved (Cursor's task
tool
resume parameter). The user may ask for flows that reuse the same
agent across the run — the same reviewer re-checking its own earlier
findings, or an implementer revisiting its phase after review — and
resuming beats a fresh dispatch there because the agent keeps everything it
already learned. Keeping the IDs in thread history is what makes that
possible later.
- Treat worker responses as structured handoffs. Require the result fields
defined below so the parent can compare and combine results without
carrying an unstructured transcript in context.
- Follow the host's normal tool rules: read tool schemas before unfamiliar
calls, avoid destructive git commands, and never revert user-owned work.
Inputs
Accept any of these as the plan source:
- A path to a plan, checklist, task breakdown, issue list, or phase document.
- A pasted plan in the conversation.
- A PRD or spec plus a request to derive implementation phases.
Optional inputs:
- PRD, design doc, ticket, issue, or acceptance criteria.
- Branch, commit style, validation commands, release constraints, or PR target.
- A stopping point such as "phase 2 only" or "implementation only", plus a
separate commit constraint such as "no commits". Treat "implementation only"
as stopping after implementation and affected validation, not as opting out
of commits.
If the plan does not name phases, derive a conservative dependency-ordered phase
list and record that grouping in the plan or in the in-chat todos before
starting implementation.
The companion write-phase-plan skill defines the plan format this skill
consumes best (phase sections with status, scope, acceptance criteria,
validation commands, and an implementation log). A plan in that shape needs no
derivation step; prefer it when authoring a plan ahead of an orchestration run.
Orchestrator Duties
Before spawning implementation workers:
- Read the plan, optional PRD/spec, repo instructions, relevant contributor
docs, and current git status.
- Identify phases, dependencies, validation requirements, ownership boundaries,
and whether the user opted out of the default commit workflow.
- Create or update the in-chat todo plan with one active phase or orchestration
step.
- Note existing dirty worktree changes and treat them as user-owned unless a
subagent clearly made them for this workflow.
During the run:
- Execute phases sequentially unless the plan marks phases as independent and
their write scopes are disjoint.
- Give every subagent enough context to act safely: plan path, PRD/spec path,
phase scope, prior phase results, repo rules, validation commands, ownership
scope, dirty-worktree notes, and commit policy.
- Tell coding subagents they are not alone in the worktree, must not revert work
they did not make, and must adapt to existing or concurrent changes.
- If new information invalidates the plan, update the plan and downstream phase
items instead of silently following stale instructions.
- Keep the user updated at phase boundaries, before edits, during long
validation, and whenever a blocker or plan deviation appears.
Phase Topologies
The default topology for a phase is one implementer, then validation, then one
reviewer. During orientation, pick a different topology when the phase's shape
calls for it:
- Batch migration — one worker discovers the target items, parallel
implementers each own a disjoint batch, then aggregate validation and one
reviewer over the combined diff. For mechanical changes across many files.
- Audit / sweep — parallel read-only workers each inspect a slice, a
separate verifier confirms each finding against the code, and the parent
deduplicates and ranks before acting. For phases whose output is findings
rather than edits.
- Fix-until-green — run the failing check, dispatch a fix worker, re-run,
repeat. Stop when the check passes or two consecutive rounds make no
progress; then escalate to the user or update the plan instead of looping.
- Competing drafts — for a high-stakes design decision inside a phase, two
or three workers draft independently; the parent compares and adopts or
synthesizes one before implementation proceeds.
Rules for every topology: parallel workers must have disjoint write scopes;
every loop needs an explicit stop condition (success, an attempt ceiling, or
no-progress detection); and results come back in the Worker Result Contract
shape so the parent can combine them without carrying transcripts.
Phase Loop
Run this loop for each phase in dependency order.
1. Orient The Phase
- Re-read the phase section, acceptance criteria, and prior logs.
- Inspect git status and recent relevant commits.
- Choose the phase's topology (see Phase Topologies): the default single
implementer, or a fan-out/loop shape when the phase calls for one.
- Update the todo tracker before spawning workers.
2. Implementation Worker
Spawn a worker under the phase-implementer contract to implement only the
active phase. The worker edits files directly. The parent orchestrator owns
implementation commits by default. If the user opted out, neither parent nor
worker commits. Otherwise, delegate commit authority to the worker only
through an explicit prompt.
After the worker returns:
- Note its agent ID in the phase's todo/notes for possible resumption.
- Inspect its summary, changed paths, validation results, blockers, and risks.
- Inspect git status and a focused diff.
- If implementation is incomplete because assumptions changed, send a bounded
follow-up (resume the same worker by ID so it keeps its context) or update
the plan before continuing.
3. Validation
Run or delegate affected validation for the phase. Use the repo's documented
commands when available, and include tests, lint, typecheck, migrations, or
browser checks when relevant.
If validation cannot run, record the exact command, blocker, and risk in the
phase notes or plan log.
When commits are permitted and the validated implementation is complete,
ensure an exact implementation commit exists before dispatching the reviewer.
The parent creates it unless the implementer already did so under explicitly
delegated authority; inspect and record the exact commit either way. This
preserves a pre-review snapshot so later review fixes can remain distinct. If
the user opted out of commits, leave the implementation uncommitted and carry
that constraint through review and finalization.
If the user requested "implementation only", skip the review-and-fix and final
whole-feature passes after this step, then finalize the plan state and summary.
4. Review And Fix Worker
Spawn a worker under the phase-reviewer contract after implementation and
initial validation. Note its agent ID alongside the phase.
Build the review prompt from primary evidence first: the plan and acceptance
criteria, the actual diff or commit range, repo rules, and validation results.
Do not lead with the implementer's summary. Include implementer notes only as
supplemental context for the reviewer to consult after independently inspecting
the change. This avoids anchoring the review to what the implementer believed it
changed.
The reviewer/fixer should:
- Review the phase against the plan, PRD/spec, repo rules, security, tenancy/data
ownership, migrations, tests, and likely regressions.
- Patch concrete issues directly when bounded and low-risk.
- Leave review fixes uncommitted for the parent orchestrator. Delegate commit
authority to the reviewer/fixer only when the user has not opted out of
commits and the prompt explicitly says so.
- Report no-op clearly if no changes are needed.
- Report larger design issues with the exact plan changes needed.
5. Review-Fix Commit
When the reviewer changed files and commits are permitted, ensure only those
validated review fixes form a second phase commit. The parent creates it unless
the reviewer already did so under explicitly delegated authority; inspect and
record the exact commit either way. Do not reconstruct a pre-review split from
a mixed working-tree diff; step 3 owns the implementation checkpoint. If the
reviewer made no changes, create no review-fix commit. If the user requested
"no commits" or another no-commit constraint, leave every phase change
uncommitted. Prefer the parent agent's normal commit workflow unless a
dedicated shell subagent is clearly useful.
When committing:
- Follow the host's git safety rules.
- Inspect git status, full staged/unstaged diff, and recent log first.
- Stage only files that belong to the active phase.
- Run repo-required pre-commit validation and affected tests.
- Fix validation failures only when the fix is clearly in phase scope.
- Create a focused commit, or report an explicit no-op if there are no phase
changes.
6. Plan Finalization
Update the plan or phase log for the active phase.
Record:
- Phase status: Done, Partial, or Blocked.
- Implementation summary and changed behavior.
- Validation commands and results.
- Review outcome.
- Commit SHAs, if commits were created.
- Deviations from the original plan.
- Downstream changes, remaining risks, and manual checks not performed.
Commit the plan/log update separately from implementation changes unless the
user opted out of commits.
Final Whole-Feature Pass
After all requested phases are finalized:
- Run aggregate validation appropriate for the whole feature.
- Spawn a worker under the
phase-final-reviewer contract to inspect the
complete feature against the plan and PRD/spec.
- If the final reviewer changed files, validate those fixes.
- Commit final fixes or final plan/log updates unless the user opted out of
commits.
- Give the user a concise final summary with phase status, validation, commit
SHAs if any, remaining manual gaps, and branch/worktree status.
Give the final reviewer the plan, acceptance criteria, complete diff or commit
range, and aggregate validation before phase summaries. Phase summaries are
supplemental and should be read only after an independent pass over the primary
evidence.
Worktrees And Stacked PRs (Option For Complex Plans)
For a plan with sequenced phases plus parallel tracks — especially when the
user's checkout is on their own branch, is behind the default branch, or
carries dirty user-owned work — run the orchestration in dedicated git
worktrees. When the user's request and the target repository's rules authorize
remote delivery, land each phase as a PR in a stack; otherwise keep the stack
local and report the branches and commits without pushing or opening PRs.
Plan complexity and an unsafe checkout authorize local isolation, not remote
mutation. Before any push, PR creation or update, merge, or other external
change, confirm that the user's request or standing repository policy grants
that authority and follow the target repository's required gates.
When to choose this mode:
- The plan names foundations that later phases build on, so phases must land
as separate reviewable PRs in dependency order.
- Two or more tracks touch disjoint areas (for example API vs web) and can run
as concurrent implementation workers without colliding.
- The current checkout is not a safe base: behind origin, on a personal
branch, or dirty with user-owned edits.
Setup:
- Choose worktree locations and branch names from the target repo's
contributor docs and the user's rules — conventions differ (some require a
specific in-repo directory, others forbid one). Only when no rule exists,
default to a sibling directory such as
../<repo>-<feature>-work.
- Fetch and branch from
origin/<default-branch>, not the local checkout:
git worktree add <worktree-path> origin/<default-branch> --detach.
- Make the worktree runnable before spawning workers: copy gitignored env
files from the user's checkout, install dependencies, run the repo's
build-before-measure steps (built packages, generated clients). Workers
inherit a broken toolchain otherwise.
- Create one additional worktree per concurrent track
(
git worktree add <track-worktree-path> <base-branch> -b <track-branch>)
so parallel workers never share a checkout. Point each worker at its own
worktree path in its prompt.
- Remove temporary worktrees when done (
git worktree remove <worktree-path>),
and if the host can point its diff view at a worktree (Cursor's
SetActiveBranch), do so, so the IDE diff follows the work.
Branching and stacking:
- One branch per phase, cut from the previous phase's branch when the phase
depends on it: foundations first, then tracks stacked on the last foundation
they need. Parallel tracks branch from the same base, not from each other.
- Commit each phase on its branch when the commit policy permits it
(orchestrator owns commits). When remote delivery is authorized, push with
git push -u origin <branch>, then open the PR with the gh CLI, setting
--base to the parent branch for stacked phases and to the default branch
for the stack root:
gh pr create --title "type(scope): subject" --body "$(cat <<'EOF' ... EOF)" --base <parent-branch>.
- Record the PR number in the phase's todo item so the final summary can map
phases to PRs.
- A schema/migration phase ships as its own PR based on the default branch;
code that depends on it stacks on the migration branch (many repos require
this — check the repo's contributor docs).
Keeping the stack healthy during the run:
- Check CI on every open PR after pushes (
gh pr checks <n>); investigate
failures with gh api .../actions/jobs/<id>/logs before assuming a worker's
change caused them — a failure may predate the stack's base.
- If the default branch gains a fix the stack needs, merge it forward through
the stack in order (base branch first, then each child), using a temporary
worktree if the branches are checked out elsewhere. Never rebase or
force-push pushed branches.
- When an inner PR merges early, GitHub retargets its children automatically;
verify with
gh pr view <n> --json baseRefName.
- Follow the repo's stack-collapse rules before final review if it has them
(prove containment with
git merge-base --is-ancestor before closing inner
PRs; the survivor merges, never closes).
The final summary must report the stack shape: which PRs are open, their base
branches, merge order, CI state, and which worktrees were created or removed.
Prompt Templates
Adapt these to the repo and phase. These templates are the per-invocation
context to hand each worker — the standing role rules (scope discipline,
no-commit default, response format) live in the companion skills, so the
prompt's job is the run-specific facts. If the worker runs as a named custom
agent built from the companion skill, the template alone is enough; if it runs
as a general subagent, prepend an instruction to load and follow the matching
companion skill, or paste that skill's standing rules above the template.
When resuming a prior worker by ID instead of dispatching fresh, send only
what changed since its last response; it retains the rest.
Worker Result Contract
Every worker response must use these headings in this order:
Outcome — concise result or explicit no-op.
Changed files — files the worker changed, not every file it inspected.
Behavior or findings — implemented behavior or review findings and fixes.
Validation — exact commands or checks and their results.
Downstream impact — plan changes, follow-up work, or None.
Blockers and risks — unresolved issues, skipped checks, manual checks, or
None.
Keep Changed files proportional. List paths individually when the list is
short. When it would become a long, low-signal inventory, group paths by
module/directory, give counts, and name only high-signal or exceptional files.
Label a grouped list as a summary rather than exhaustive; the parent inspects
git status and the diff for the authoritative file list.
Implementation Worker (phase-implementer)
You are implementing phase {phase_name} of this plan.
Context:
- Plan: {plan_path_or_summary}
- PRD/spec: {prd_path_or_summary_or_none}
- Prior phase commits and notes: {prior_phase_summary}
- Repo instructions and validation requirements: {repo_rules_summary}
- Current dirty-worktree notes: {dirty_worktree_summary}
Ownership:
- You own {owned_files_or_modules}.
- Other agents or the user may have changes in the worktree. Do not revert work
you did not make. Adapt to existing changes.
Task:
- Implement only phase {phase_name}.
- It is acceptable to deviate from the plan when the codebase shows a better
path, but document the reason and downstream impact.
- Commit policy: {commit_policy}. The parent orchestrator commits by default;
do not commit from this worker unless this explicitly delegates commit
authority to you.
Validation:
- Run {affected_tests_or_checks} where practical.
- If a required check is not practical, explain why.
Final response:
- Use the Worker Result Contract headings in order.
- In `Behavior or findings`, describe the behavior implemented.
Review And Fix Worker (phase-reviewer)
Review and fix phase {phase_name}.
Context:
- Plan: {plan_path_or_summary}
- PRD/spec: {prd_path_or_summary_or_none}
- Change under review: {commit_range_or_diff_scope}
- Validation evidence: {phase_validation_results}
- Validation requirements: {validation_commands}
- Repo rules: {repo_rules_summary}
- Ownership scope: {owned_files_or_modules}
- Dirty-worktree notes: {dirty_worktree_summary}
- Commit policy: {commit_policy}
- Supplemental implementer notes: {phase_result}
Task:
- First inspect the plan, acceptance criteria, and actual change. Form an
independent assessment before reading the supplemental implementer notes.
- Review the phase against acceptance criteria, repo conventions, security,
tenancy/data ownership, migrations, and test coverage.
- Patch concrete issues directly when bounded and low-risk.
- Do not commit from this worker unless the commit policy explicitly delegates
commit authority to you.
- If no changes are needed, say so clearly.
- If the plan should change, describe the exact plan and downstream updates.
Final response:
- Use the Worker Result Contract headings in order.
- In `Behavior or findings`, report findings fixed, the no-op result, and any
findings not fixed.
Final Reviewer (phase-final-reviewer)
Review the entire feature after all requested phases.
Context:
- Plan: {plan_path}
- PRD/spec: {prd_path_or_none}
- Complete change: {commit_range_or_diff_scope}
- Final validation results so far: {validation_summary}
- Validation requirements: {validation_commands}
- Repo rules: {repo_rules_summary}
- Ownership scope: {owned_files_or_modules}
- Dirty-worktree notes: {dirty_worktree_summary}
- Commit policy: {commit_policy}
- Supplemental phase results: {all_phase_results}
Task:
- First inspect the plan, acceptance criteria, and complete change. Form an
independent assessment before reading the supplemental phase results.
- Review end-to-end behavior against the plan and PRD/spec.
- Look for integration bugs, missing acceptance criteria, stale plan state,
validation gaps, unsafe data ownership, and regressions across phase
boundaries.
- Patch only concrete issues that are safe to fix now.
- Do not commit from this worker unless the commit policy explicitly delegates
commit authority to you.
Final response:
- Use the Worker Result Contract headings in order.
- In `Behavior or findings`, report findings fixed, the no-op result, and any
findings not fixed.
Plan Conventions
Prefer a stable plan structure:
- Phase status: Not started, In progress, Done, Partial, or Blocked.
- Implementation log entries with date, phase, summary, validation, review
result, commits if any, deviations, and remaining risks.
- Downstream changes called out where the original phase plan changed.
- Manual checks listed separately from automated checks.
Do not let the plan become ceremonial. If implementation or review shows that a
task is obsolete, split, merged, or better solved differently, update the plan
and explain why.
Git And Validation Rules
- Follow repo contributor instructions before every commit.
- Use non-interactive git commands.
- Stage intentionally and avoid unrelated dirty files.
- Never use destructive git commands unless the user explicitly requested them.
- Keep implementation, review fixes, plan finalization, and final feature fixes
distinct when committing.
- For multi-phase plans that should land as reviewable PRs rather than commits
on the user's checkout, use the worktree + stacked-PR mode above.
- If required validation cannot run, record the command, blocker, and risk in
both the subagent result and the plan log.
1---2name: phase-orchestrator-43description: >-4 Orchestrates phase-based implementation plans using the host's todo tracker5 and subagents for implementation, review, validation, default phase commits,6 plan finalization, and a final end-to-end review. Delegates work through the7 companion phase-implementer, phase-reviewer, and phase-final-reviewer skills8 and consumes plans in the write-phase-plan format. Use when the user provides9 a plan, checklist, PRD, or phase document and asks for delegated multi-agent10 execution across phases.11license: MIT12metadata:13 source: https://skillmd.com/skills/hraness/phase-orchestrator-414 internal: true15---1617# Phase Orchestrator1819## Goal2021Run a phase-based plan through a repeatable delegated workflow. The plan is22the source of truth, any PRD/spec is supporting context, and each phase should23move through orientation, implementation, validation, review, plan updates, and24commits by default.2526Use this skill only when the user explicitly asks for delegated phase27orchestration, invokes this skill, or asks to implement a plan/checklist using28subagents.2930## Companion Skills3132This skill is the parent of a five-skill workflow:3334- `write-phase-plan` — authors plans in the format this skill consumes best.35- `phase-implementer` — the delegated worker contract for implementing exactly36 one phase (Phase Loop step 2).37- `phase-reviewer` — the delegated worker contract for the review-and-fix pass38 on a completed phase (Phase Loop step 4).39- `phase-final-reviewer` — the delegated worker contract for the end-to-end40 review of the whole feature after all phases (Final Whole-Feature Pass).4142Each worker skill carries that role's standing rules: single-phase or43single-pass scope, no-revert discipline, no-commit default, and the required44final-response format. The parent's prompt only needs to supply the per-run45context from the templates below.4647How to dispatch a worker role depends on the host:48491. **Named custom agents.** If the host supports named custom agents or50 subagent types (Cursor custom agents, for example), prefer a dedicated51 agent per role whose definition is the matching companion skill's body.522. **General subagent + installed skill.** Otherwise, launch a general-purpose53 subagent and instruct it to load and follow the matching installed54 companion skill by name.553. **Inline rules.** If the subagent cannot load skills, paste the companion56 skill's standing rules into the prompt along with the per-run context.5758## Host Mapping5960- Use the host's todo tracker (`TodoWrite` in Cursor) for the in-chat61 orchestration state. Keep exactly one phase or orchestration step62 `in_progress`.63- Use the host's subagent or task tool (`Subagent` in Cursor) for delegated64 implementation, broad read-only exploration, review/fix passes, validation,65 and shell/git work when delegation is useful.66- Use fast read-only subagents (Cursor's `explore` type, where available) for67 broad codebase discovery before implementation.68- Use shell-focused subagents only for command-heavy validation or git69 operations.70- Respect the user's or host's model choice for workers. Pass a model71 explicitly only when the user requests a specific model for the run or for72 a specific worker.73- Use background subagents when the host supports them and independent74 read-only investigations can run in parallel.75- Do not assume subagents can be "closed"; inspect their final response and76 continue from the parent agent.77- Record every spawned subagent's ID in the main thread (alongside its phase78 in the todo/phase notes) when the host exposes one. Some hosts can resume a79 completed subagent by ID with its full context preserved (Cursor's task80 tool `resume` parameter). The user may ask for flows that reuse the same81 agent across the run — the same reviewer re-checking its own earlier82 findings, or an implementer revisiting its phase after review — and83 resuming beats a fresh dispatch there because the agent keeps everything it84 already learned. Keeping the IDs in thread history is what makes that85 possible later.86- Treat worker responses as structured handoffs. Require the result fields87 defined below so the parent can compare and combine results without88 carrying an unstructured transcript in context.89- Follow the host's normal tool rules: read tool schemas before unfamiliar90 calls, avoid destructive git commands, and never revert user-owned work.9192## Inputs9394Accept any of these as the plan source:9596- A path to a plan, checklist, task breakdown, issue list, or phase document.97- A pasted plan in the conversation.98- A PRD or spec plus a request to derive implementation phases.99100Optional inputs:101102- PRD, design doc, ticket, issue, or acceptance criteria.103- Branch, commit style, validation commands, release constraints, or PR target.104- A stopping point such as "phase 2 only" or "implementation only", plus a105 separate commit constraint such as "no commits". Treat "implementation only"106 as stopping after implementation and affected validation, not as opting out107 of commits.108109If the plan does not name phases, derive a conservative dependency-ordered phase110list and record that grouping in the plan or in the in-chat todos before111starting implementation.112113The companion `write-phase-plan` skill defines the plan format this skill114consumes best (phase sections with status, scope, acceptance criteria,115validation commands, and an implementation log). A plan in that shape needs no116derivation step; prefer it when authoring a plan ahead of an orchestration run.117118## Orchestrator Duties119120Before spawning implementation workers:1211221. Read the plan, optional PRD/spec, repo instructions, relevant contributor123 docs, and current git status.1242. Identify phases, dependencies, validation requirements, ownership boundaries,125 and whether the user opted out of the default commit workflow.1263. Create or update the in-chat todo plan with one active phase or orchestration127 step.1284. Note existing dirty worktree changes and treat them as user-owned unless a129 subagent clearly made them for this workflow.130131During the run:132133- Execute phases sequentially unless the plan marks phases as independent and134 their write scopes are disjoint.135- Give every subagent enough context to act safely: plan path, PRD/spec path,136 phase scope, prior phase results, repo rules, validation commands, ownership137 scope, dirty-worktree notes, and commit policy.138- Tell coding subagents they are not alone in the worktree, must not revert work139 they did not make, and must adapt to existing or concurrent changes.140- If new information invalidates the plan, update the plan and downstream phase141 items instead of silently following stale instructions.142- Keep the user updated at phase boundaries, before edits, during long143 validation, and whenever a blocker or plan deviation appears.144145## Phase Topologies146147The default topology for a phase is one implementer, then validation, then one148reviewer. During orientation, pick a different topology when the phase's shape149calls for it:150151- **Batch migration** — one worker discovers the target items, parallel152 implementers each own a disjoint batch, then aggregate validation and one153 reviewer over the combined diff. For mechanical changes across many files.154- **Audit / sweep** — parallel read-only workers each inspect a slice, a155 separate verifier confirms each finding against the code, and the parent156 deduplicates and ranks before acting. For phases whose output is findings157 rather than edits.158- **Fix-until-green** — run the failing check, dispatch a fix worker, re-run,159 repeat. Stop when the check passes or two consecutive rounds make no160 progress; then escalate to the user or update the plan instead of looping.161- **Competing drafts** — for a high-stakes design decision inside a phase, two162 or three workers draft independently; the parent compares and adopts or163 synthesizes one before implementation proceeds.164165Rules for every topology: parallel workers must have disjoint write scopes;166every loop needs an explicit stop condition (success, an attempt ceiling, or167no-progress detection); and results come back in the Worker Result Contract168shape so the parent can combine them without carrying transcripts.169170## Phase Loop171172Run this loop for each phase in dependency order.173174### 1. Orient The Phase175176- Re-read the phase section, acceptance criteria, and prior logs.177- Inspect git status and recent relevant commits.178- Choose the phase's topology (see Phase Topologies): the default single179 implementer, or a fan-out/loop shape when the phase calls for one.180- Update the todo tracker before spawning workers.181182### 2. Implementation Worker183184Spawn a worker under the `phase-implementer` contract to implement only the185active phase. The worker edits files directly. The parent orchestrator owns186implementation commits by default. If the user opted out, neither parent nor187worker commits. Otherwise, delegate commit authority to the worker only188through an explicit prompt.189190After the worker returns:191192- Note its agent ID in the phase's todo/notes for possible resumption.193- Inspect its summary, changed paths, validation results, blockers, and risks.194- Inspect git status and a focused diff.195- If implementation is incomplete because assumptions changed, send a bounded196 follow-up (resume the same worker by ID so it keeps its context) or update197 the plan before continuing.198199### 3. Validation200201Run or delegate affected validation for the phase. Use the repo's documented202commands when available, and include tests, lint, typecheck, migrations, or203browser checks when relevant.204205If validation cannot run, record the exact command, blocker, and risk in the206phase notes or plan log.207208When commits are permitted and the validated implementation is complete,209ensure an exact implementation commit exists before dispatching the reviewer.210The parent creates it unless the implementer already did so under explicitly211delegated authority; inspect and record the exact commit either way. This212preserves a pre-review snapshot so later review fixes can remain distinct. If213the user opted out of commits, leave the implementation uncommitted and carry214that constraint through review and finalization.215216If the user requested "implementation only", skip the review-and-fix and final217whole-feature passes after this step, then finalize the plan state and summary.218219### 4. Review And Fix Worker220221Spawn a worker under the `phase-reviewer` contract after implementation and222initial validation. Note its agent ID alongside the phase.223224Build the review prompt from primary evidence first: the plan and acceptance225criteria, the actual diff or commit range, repo rules, and validation results.226Do not lead with the implementer's summary. Include implementer notes only as227supplemental context for the reviewer to consult after independently inspecting228the change. This avoids anchoring the review to what the implementer believed it229changed.230231The reviewer/fixer should:232233- Review the phase against the plan, PRD/spec, repo rules, security, tenancy/data234 ownership, migrations, tests, and likely regressions.235- Patch concrete issues directly when bounded and low-risk.236- Leave review fixes uncommitted for the parent orchestrator. Delegate commit237 authority to the reviewer/fixer only when the user has not opted out of238 commits and the prompt explicitly says so.239- Report no-op clearly if no changes are needed.240- Report larger design issues with the exact plan changes needed.241242### 5. Review-Fix Commit243244When the reviewer changed files and commits are permitted, ensure only those245validated review fixes form a second phase commit. The parent creates it unless246the reviewer already did so under explicitly delegated authority; inspect and247record the exact commit either way. Do not reconstruct a pre-review split from248a mixed working-tree diff; step 3 owns the implementation checkpoint. If the249reviewer made no changes, create no review-fix commit. If the user requested250"no commits" or another no-commit constraint, leave every phase change251uncommitted. Prefer the parent agent's normal commit workflow unless a252dedicated shell subagent is clearly useful.253254When committing:255256- Follow the host's git safety rules.257- Inspect git status, full staged/unstaged diff, and recent log first.258- Stage only files that belong to the active phase.259- Run repo-required pre-commit validation and affected tests.260- Fix validation failures only when the fix is clearly in phase scope.261- Create a focused commit, or report an explicit no-op if there are no phase262 changes.263264### 6. Plan Finalization265266Update the plan or phase log for the active phase.267268Record:269270- Phase status: Done, Partial, or Blocked.271- Implementation summary and changed behavior.272- Validation commands and results.273- Review outcome.274- Commit SHAs, if commits were created.275- Deviations from the original plan.276- Downstream changes, remaining risks, and manual checks not performed.277278Commit the plan/log update separately from implementation changes unless the279user opted out of commits.280281## Final Whole-Feature Pass282283After all requested phases are finalized:2842851. Run aggregate validation appropriate for the whole feature.2862. Spawn a worker under the `phase-final-reviewer` contract to inspect the287 complete feature against the plan and PRD/spec.2883. If the final reviewer changed files, validate those fixes.2894. Commit final fixes or final plan/log updates unless the user opted out of290 commits.2915. Give the user a concise final summary with phase status, validation, commit292 SHAs if any, remaining manual gaps, and branch/worktree status.293294Give the final reviewer the plan, acceptance criteria, complete diff or commit295range, and aggregate validation before phase summaries. Phase summaries are296supplemental and should be read only after an independent pass over the primary297evidence.298299## Worktrees And Stacked PRs (Option For Complex Plans)300301For a plan with sequenced phases plus parallel tracks — especially when the302user's checkout is on their own branch, is behind the default branch, or303carries dirty user-owned work — run the orchestration in dedicated git304worktrees. When the user's request and the target repository's rules authorize305remote delivery, land each phase as a PR in a stack; otherwise keep the stack306local and report the branches and commits without pushing or opening PRs.307308Plan complexity and an unsafe checkout authorize local isolation, not remote309mutation. Before any push, PR creation or update, merge, or other external310change, confirm that the user's request or standing repository policy grants311that authority and follow the target repository's required gates.312313When to choose this mode:314315- The plan names foundations that later phases build on, so phases must land316 as separate reviewable PRs in dependency order.317- Two or more tracks touch disjoint areas (for example API vs web) and can run318 as concurrent implementation workers without colliding.319- The current checkout is not a safe base: behind origin, on a personal320 branch, or dirty with user-owned edits.321322Setup:3233241. Choose worktree locations and branch names from the target repo's325 contributor docs and the user's rules — conventions differ (some require a326 specific in-repo directory, others forbid one). Only when no rule exists,327 default to a sibling directory such as `../<repo>-<feature>-work`.3282. Fetch and branch from `origin/<default-branch>`, not the local checkout:329 `git worktree add <worktree-path> origin/<default-branch> --detach`.3303. Make the worktree runnable before spawning workers: copy gitignored env331 files from the user's checkout, install dependencies, run the repo's332 build-before-measure steps (built packages, generated clients). Workers333 inherit a broken toolchain otherwise.3344. Create one additional worktree per concurrent track335 (`git worktree add <track-worktree-path> <base-branch> -b <track-branch>`)336 so parallel workers never share a checkout. Point each worker at its own337 worktree path in its prompt.3385. Remove temporary worktrees when done (`git worktree remove <worktree-path>`),339 and if the host can point its diff view at a worktree (Cursor's340 `SetActiveBranch`), do so, so the IDE diff follows the work.341342Branching and stacking:343344- One branch per phase, cut from the previous phase's branch when the phase345 depends on it: foundations first, then tracks stacked on the last foundation346 they need. Parallel tracks branch from the same base, not from each other.347- Commit each phase on its branch when the commit policy permits it348 (orchestrator owns commits). When remote delivery is authorized, push with349 `git push -u origin <branch>`, then open the PR with the `gh` CLI, setting350 `--base` to the parent branch for stacked phases and to the default branch351 for the stack root:352 `gh pr create --title "type(scope): subject" --body "$(cat <<'EOF' ... EOF)" --base <parent-branch>`.353- Record the PR number in the phase's todo item so the final summary can map354 phases to PRs.355- A schema/migration phase ships as its own PR based on the default branch;356 code that depends on it stacks on the migration branch (many repos require357 this — check the repo's contributor docs).358359Keeping the stack healthy during the run:360361- Check CI on every open PR after pushes (`gh pr checks <n>`); investigate362 failures with `gh api .../actions/jobs/<id>/logs` before assuming a worker's363 change caused them — a failure may predate the stack's base.364- If the default branch gains a fix the stack needs, merge it forward through365 the stack in order (base branch first, then each child), using a temporary366 worktree if the branches are checked out elsewhere. Never rebase or367 force-push pushed branches.368- When an inner PR merges early, GitHub retargets its children automatically;369 verify with `gh pr view <n> --json baseRefName`.370- Follow the repo's stack-collapse rules before final review if it has them371 (prove containment with `git merge-base --is-ancestor` before closing inner372 PRs; the survivor merges, never closes).373374The final summary must report the stack shape: which PRs are open, their base375branches, merge order, CI state, and which worktrees were created or removed.376377## Prompt Templates378379Adapt these to the repo and phase. These templates are the per-invocation380context to hand each worker — the standing role rules (scope discipline,381no-commit default, response format) live in the companion skills, so the382prompt's job is the run-specific facts. If the worker runs as a named custom383agent built from the companion skill, the template alone is enough; if it runs384as a general subagent, prepend an instruction to load and follow the matching385companion skill, or paste that skill's standing rules above the template.386When resuming a prior worker by ID instead of dispatching fresh, send only387what changed since its last response; it retains the rest.388389### Worker Result Contract390391Every worker response must use these headings in this order:3923931. `Outcome` — concise result or explicit no-op.3942. `Changed files` — files the worker changed, not every file it inspected.3953. `Behavior or findings` — implemented behavior or review findings and fixes.3964. `Validation` — exact commands or checks and their results.3975. `Downstream impact` — plan changes, follow-up work, or `None`.3986. `Blockers and risks` — unresolved issues, skipped checks, manual checks, or399 `None`.400401Keep `Changed files` proportional. List paths individually when the list is402short. When it would become a long, low-signal inventory, group paths by403module/directory, give counts, and name only high-signal or exceptional files.404Label a grouped list as a summary rather than exhaustive; the parent inspects405git status and the diff for the authoritative file list.406407### Implementation Worker (`phase-implementer`)408409```text410You are implementing phase {phase_name} of this plan.411412Context:413- Plan: {plan_path_or_summary}414- PRD/spec: {prd_path_or_summary_or_none}415- Prior phase commits and notes: {prior_phase_summary}416- Repo instructions and validation requirements: {repo_rules_summary}417- Current dirty-worktree notes: {dirty_worktree_summary}418419Ownership:420- You own {owned_files_or_modules}.421- Other agents or the user may have changes in the worktree. Do not revert work422 you did not make. Adapt to existing changes.423424Task:425- Implement only phase {phase_name}.426- It is acceptable to deviate from the plan when the codebase shows a better427 path, but document the reason and downstream impact.428- Commit policy: {commit_policy}. The parent orchestrator commits by default;429 do not commit from this worker unless this explicitly delegates commit430 authority to you.431432Validation:433- Run {affected_tests_or_checks} where practical.434- If a required check is not practical, explain why.435436Final response:437- Use the Worker Result Contract headings in order.438- In `Behavior or findings`, describe the behavior implemented.439```440441### Review And Fix Worker (`phase-reviewer`)442443```text444Review and fix phase {phase_name}.445446Context:447- Plan: {plan_path_or_summary}448- PRD/spec: {prd_path_or_summary_or_none}449- Change under review: {commit_range_or_diff_scope}450- Validation evidence: {phase_validation_results}451- Validation requirements: {validation_commands}452- Repo rules: {repo_rules_summary}453- Ownership scope: {owned_files_or_modules}454- Dirty-worktree notes: {dirty_worktree_summary}455- Commit policy: {commit_policy}456- Supplemental implementer notes: {phase_result}457458Task:459- First inspect the plan, acceptance criteria, and actual change. Form an460 independent assessment before reading the supplemental implementer notes.461- Review the phase against acceptance criteria, repo conventions, security,462 tenancy/data ownership, migrations, and test coverage.463- Patch concrete issues directly when bounded and low-risk.464- Do not commit from this worker unless the commit policy explicitly delegates465 commit authority to you.466- If no changes are needed, say so clearly.467- If the plan should change, describe the exact plan and downstream updates.468469Final response:470- Use the Worker Result Contract headings in order.471- In `Behavior or findings`, report findings fixed, the no-op result, and any472 findings not fixed.473```474475### Final Reviewer (`phase-final-reviewer`)476477```text478Review the entire feature after all requested phases.479480Context:481- Plan: {plan_path}482- PRD/spec: {prd_path_or_none}483- Complete change: {commit_range_or_diff_scope}484- Final validation results so far: {validation_summary}485- Validation requirements: {validation_commands}486- Repo rules: {repo_rules_summary}487- Ownership scope: {owned_files_or_modules}488- Dirty-worktree notes: {dirty_worktree_summary}489- Commit policy: {commit_policy}490- Supplemental phase results: {all_phase_results}491492Task:493- First inspect the plan, acceptance criteria, and complete change. Form an494 independent assessment before reading the supplemental phase results.495- Review end-to-end behavior against the plan and PRD/spec.496- Look for integration bugs, missing acceptance criteria, stale plan state,497 validation gaps, unsafe data ownership, and regressions across phase498 boundaries.499- Patch only concrete issues that are safe to fix now.500- Do not commit from this worker unless the commit policy explicitly delegates501 commit authority to you.502503Final response:504- Use the Worker Result Contract headings in order.505- In `Behavior or findings`, report findings fixed, the no-op result, and any506 findings not fixed.507```508509## Plan Conventions510511Prefer a stable plan structure:512513- Phase status: Not started, In progress, Done, Partial, or Blocked.514- Implementation log entries with date, phase, summary, validation, review515 result, commits if any, deviations, and remaining risks.516- Downstream changes called out where the original phase plan changed.517- Manual checks listed separately from automated checks.518519Do not let the plan become ceremonial. If implementation or review shows that a520task is obsolete, split, merged, or better solved differently, update the plan521and explain why.522523## Git And Validation Rules524525- Follow repo contributor instructions before every commit.526- Use non-interactive git commands.527- Stage intentionally and avoid unrelated dirty files.528- Never use destructive git commands unless the user explicitly requested them.529- Keep implementation, review fixes, plan finalization, and final feature fixes530 distinct when committing.531- For multi-phase plans that should land as reviewable PRs rather than commits532 on the user's checkout, use the worktree + stacked-PR mode above.533- If required validation cannot run, record the command, blocker, and risk in534 both the subagent result and the plan log.