phase-orchestrator · diff
git:20260821.66ec15d to git:20260829.3a8221d
461 added, 162 removed. Audit A to A.
---
name: phase-orchestrator
- description: Orchestrate phase-based implementation plans in Codex with dependency analysis, parallel sub-agent lanes, join gates, validation, review/fix loops, and final integration. Use when the user provides a plan, checklist, PRD, or phased task and explicitly asks Codex to execute it with phases, delegation, parallel agents, or orchestration in any repository.
+ description: >-
+ Orchestrates phase-based implementation plans using the host's todo tracker
+ and subagents for implementation, review, validation, default phase commits,
+ plan finalization, and a final end-to-end review. Delegates work through the
+ companion phase-implementer, phase-reviewer, and phase-final-reviewer skills
+ and consumes plans in the write-phase-plan format. Use when the user provides
+ a plan, checklist, PRD, or phase document and asks for delegated multi-agent
+ execution across phases.
+ license: MIT
metadata:
internal: true
---
# Phase Orchestrator
- Execute a phased plan safely. Treat the plan as the source of scope and repository
- instructions as the authority for tooling, validation, version control, and delivery.
+ ## Goal
- ## Rules
+ 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.
- - Read applicable repository instructions and the complete plan before acting.
- - Use `update_plan` for orchestration state. Keep at most one orchestration step
- `in_progress`; represent parallel lanes inside that step or as pending siblings until
- they join.
- - Use Codex collaboration tools for bounded work: `spawn_agent`, `send_message`,
- `followup_task`, `wait_agent`, `interrupt_agent`, and `list_agents`.
- - Record each agent id, task path, owned scope, and result. Resume the same agent with
- `followup_task` when continuity helps; use a fresh agent for independent review.
- - Respect the active concurrency limit. Keep one slot for the root orchestrator; when
- four slots are available, run at most three worker agents concurrently.
- - Run dependent work sequentially. Parallelize read-only work freely. Parallelize writers
- only with disjoint paths in one checkout or isolated worktrees/workspaces.
- - Remember that Codex agents share the same filesystem. A prompt alone does not isolate
- writes; give every writer an explicit worktree path and ownership boundary.
- - Preserve user-owned changes. Never revert, overwrite, stage, or commit unrelated work.
- - Do not commit, push, open/modify PRs, merge, deploy, or make other external writes
- unless the user authorized them.
- - Never rebase or amend a pushed branch, force-push, or use destructive VCS commands
- unless the user explicitly requested the exact operation.
- - Follow repository policy over this skill.
+ 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.
- ## Orient
+ ## Companion Skills
- Before implementation:
+ This skill is the parent of a five-skill workflow:
- 1. Locate the repository root and read applicable `AGENTS.md`, contributor, workflow,
- writing, and delivery instructions.
- 2. Inspect VCS status, active branch/change, remotes when relevant, and existing changes.
- 3. Discover setup, focused checks, aggregate checks, generated-file policy, migrations,
- release/version rules, CI, review gates, and PR conventions.
- 4. Read the plan and supporting specification.
- 5. Capture the requested stopping point and authorization for commits, pushes, PRs,
- merges, or deploys.
- 6. Identify dependencies, write scopes, shared files, acceptance criteria, and validation.
+ - `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).
- Ask only when a missing choice materially changes the result or requires new authority.
+ 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.
- ## Build the orchestration graph
+ How to dispatch a worker role depends on the host:
- Convert the plan into a dependency DAG before spawning workers.
+ 1. **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.
+ 2. **General subagent + installed skill.** Otherwise, launch a general-purpose
+ subagent and instruct it to load and follow the matching installed
+ companion skill by name.
+ 3. **Inline rules.** If the subagent cannot load skills, paste the companion
+ skill's standing rules into the prompt along with the per-run context.
- Classify each node:
+ ## Host Mapping
- - **Convergence**: shared contracts, schemas, migrations, barrels, integration, release.
- Run with one owner.
- - **Parallel lane**: bounded work with independent inputs and disjoint writes.
- - **Join gate**: integrate lanes and prove cross-lane contracts before downstream work.
- - **Validation/review**: read-heavy work that may run concurrently after a stable diff.
+ - 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.
- For every parallel fan-out, record:
+ ## Inputs
- - prerequisites and join gate;
- - owned directories/files per lane;
- - shared files deferred to the integration owner;
- - focused validation and required evidence;
- - whether isolation needs Git worktrees or jj workspaces.
+ Accept any of these as the plan source:
- Do not parallelize unresolved shared-interface design. Freeze the shared contract first,
- then fan out. Prefer this shape:
+ - 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.
- ```text
- contract phase
- ├─ independent lane A
- └─ independent lane B
- ↓ join gate
- ┌───────┼───────┐
- lane C lane D lane E
- └───────┼───────┘
- final join
- ```
+ Optional inputs:
- Update the plan document when orchestration changes are part of the user's request.
+ - 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.
- ## Prepare parallel writers
+ 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.
- Use the repository's documented isolation mechanism. For Git worktrees:
+ 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.
- 1. Start from the intended feature base.
- 2. Create one `codex/` topic branch and worktree per concurrent writer.
- 3. Tell each agent its absolute worktree path and require every command to use it.
- 4. Keep shared barrels, manifests, lockfiles, generated indexes, docs, and version files
- with the integration owner unless one lane explicitly owns them.
- 5. Integrate completed lane commits into one feature branch without rewriting pushed
- history.
- 6. Prove intended commits are contained in the integration tip before cleanup.
+ ## Orchestrator Duties
- If writers operate in one checkout, allow only disjoint paths and tell agents that edits
- are immediately visible to every worker. Stop the fan-out if overlapping edits appear.
+ Before spawning implementation workers:
- ## Execute each phase
+ 1. Read the plan, optional PRD/spec, repo instructions, relevant contributor
+ docs, and current git status.
+ 2. Identify phases, dependencies, validation requirements, ownership boundaries,
+ and whether the user opted out of the default commit workflow.
+ 3. Create or update the in-chat todo plan with one active phase or orchestration
+ step.
+ 4. Note existing dirty worktree changes and treat them as user-owned unless a
+ subagent clearly made them for this workflow.
- ### 1. Orient the phase
+ During the run:
- - Re-read its criteria, prior results, current status, and owned paths.
- - Confirm prerequisites and isolation.
- - Mark the phase or fan-out orchestration step `in_progress`.
+ - 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.
- ### 2. Delegate bounded implementation
+ ## Phase Topologies
- Spawn workers only for concrete independent tasks. Include the plan path or relevant
- excerpt, repository rules, acceptance criteria, worktree, ownership, validation, existing
- changes, and commit policy. Do not assume workers infer parent-only context.
+ 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:
- Continue useful root work while agents run. Send concise commentary updates at least once
- per minute during long operations.
+ - **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.
- ### 3. Inspect and validate
+ 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.
- For each worker result:
+ ## Phase Loop
- - inspect its summary, status, diff, changed files, validation, deviations, and blockers;
- - independently inspect the focused diff and repository status;
- - run the smallest repository-documented checks that establish lane correctness;
- - use `followup_task` for bounded corrections.
+ Run this loop for each phase in dependency order.
- Do not silently replace a blocked check with a weaker one. Record the command, blocker,
- and risk.
+ ### 1. Orient The Phase
- ### 4. Join
+ - 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.
- At a join gate:
+ ### 2. Implementation Worker
- 1. Wait for every required lane.
- 2. Integrate all completed work into the feature tip.
- 3. Prove no intended lane commit or file remains outside it.
- 4. Resolve shared files once through the integration owner.
- 5. Run contract and cross-lane tests, then aggregate focused checks.
- 6. Freeze the next shared interface before another fan-out.
+ 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.
- Do not advance because each lane passes alone. The join gate proves composition.
+ After the worker returns:
- ### 5. Review and fix
+ - 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.
- After implementation and initial validation, spawn a fresh reviewer with the phase diff,
- criteria, repository rules, and validation evidence. Ask it to patch bounded issues, avoid
- commits unless authorized, and report a clear no-op when clean. Re-run affected checks.
+ ### 3. Validation
- ### 6. Finalize the phase
+ 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:
- - Done, Partial, or Blocked;
- - behavior and changed areas;
- - validation commands/results;
- - review result;
- - commit/change ids when authorized;
- - deviations, downstream changes, risks, and manual checks.
+ - 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.
- ## Whole-feature pass
+ Commit the plan/log update separately from implementation changes unless the
+ user opted out of commits.
- After requested phases complete:
+ ## Final Whole-Feature Pass
- 1. Integrate every lane into one feature tip or working tree.
- 2. Prove no worker output was omitted.
- 3. Run repository-appropriate aggregate validation.
- 4. Spawn a fresh final reviewer against the complete diff.
- 5. Validate final fixes.
- 6. Deliver only to the user's authorized stopping point.
- 7. Follow repository-specific PR, CI, readiness, merge, and deployment workflows.
+ After all requested phases are finalized:
- Respect partial stopping points. Do not implement or review future phases the user did not
- request.
+ 1. Run aggregate validation appropriate for the whole feature.
+ 2. Spawn a worker under the `phase-final-reviewer` contract to inspect the
+ complete feature against the plan and PRD/spec.
+ 3. If the final reviewer changed files, validate those fixes.
+ 4. Commit final fixes or final plan/log updates unless the user opted out of
+ commits.
+ 5. Give the user a concise final summary with phase status, validation, commit
+ SHAs if any, remaining manual gaps, and branch/worktree status.
- ## Worker prompt
+ 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:
+
+ 1. 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`.
+ 2. Fetch and branch from `origin/<default-branch>`, not the local checkout:
+ `git worktree add <worktree-path> origin/<default-branch> --detach`.
+ 3. 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.
+ 4. 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.
+ 5. 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:
+
+ 1. `Outcome` — concise result or explicit no-op.
+ 2. `Changed files` — files the worker changed, not every file it inspected.
+ 3. `Behavior or findings` — implemented behavior or review findings and fixes.
+ 4. `Validation` — exact commands or checks and their results.
+ 5. `Downstream impact` — plan changes, follow-up work, or `None`.
+ 6. `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`)
+
```text
- Implement {phase_or_lane} in {absolute_worktree_path}.
+ You are implementing phase {phase_name} of this plan.
Context:
- - Plan: {plan_path_and_relevant_scope}
- - Acceptance criteria: {criteria}
- - Dependencies/prior results: {summary}
- - Repository rules: {rules}
- - Validation: {commands}
- - Existing user-owned changes: {summary}
+ - 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:
- - Own only {paths_or_modules}.
- - Defer {shared_files} to the integration owner.
- - Other agents may be working concurrently. Do not revert or overwrite their work.
+ - 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 this lane.
- - Report evidence that invalidates the plan and its downstream impact.
- - Commit policy: {policy}. Do not commit unless explicitly delegated.
+ - 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.
- Return:
- - Behavior and changed files.
- - Validation and exact results.
- - Deviations, blockers, risks, and integration notes.
+ 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 prompt
+ ### Review And Fix Worker (`phase-reviewer`)
```text
- Review and fix {scope} in {absolute_worktree_path}.
+ Review and fix phase {phase_name}.
Context:
- - Plan/criteria: {context}
- - Diff scope: {diff}
- - Repository rules: {rules}
- - Validation so far: {results}
- - Commit policy: {policy}
+ - 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}
- Review correctness, criteria, repository conventions, security, data ownership,
- migrations, tests, and integration boundaries. Patch concrete bounded issues. Do not
- commit unless delegated. Report fixes or a clear no-op, validation, and residual risks.
+ 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.
```
- ## Completion standard
+ ### Final Reviewer (`phase-final-reviewer`)
- Complete the run only when:
+ ```text
+ Review the entire feature after all requested phases.
- - every requested phase has a terminal status;
- - every intended worker result is integrated;
- - join gates and aggregate checks have recorded results;
- - review fixes are validated;
- - no unauthorized external writes occurred;
- - the final report states exact repository, branch/worktree, validation, and remaining
- risk.
+ 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.