| name | subagent-pr-orchestration |
| description | Coordinate WDD task worker agents from task files, track each active task independently, run review gates, route feedback, reconcile shared context, and merge only after verification and branch freshness pass. |
Subagent PR Orchestration
Use this when wdd-start-wave has activated a wave, or when a single task file
is ready for delegated implementation.
Honor profile, reviewMode, and monitoringMode from orchestration.json
or micro-wave state.json when present. Honor wave or micro-wave
executionMode when a strategy is recorded.
User Input
Use any named epic, wave, ticket, task, branch, PR URL, patch path, worker
thread ID, or review thread ID. If none is provided, read the active controller
state and orchestration state.
Preconditions
orchestration.json exists with schemaVersion: 1, a schema-v2 controller
state exists for the scope, or a single task file is provided.- Each worker receives the task file set assigned by strategy: one task for
parallel or single-task dispatch, all active wave tasks for bundled, or one
bundle group's tasks for hybrid.
- The controller does not implement task code.
- The controller creates or verifies the epic branch before any worker starts.
- The controller creates or verifies one isolated worktree per repository-writing
task or bundle before dispatch.
- Workers start in their assigned worktree and must not switch branches in the
controller checkout.
- Workers do not merge their own PRs.
- GitHub is optional. If no PR system exists, use branches, patches, or local
status notes while preserving the same gates.
- In a schema-v2 scope, use
wddctl monitor --once, wddctl review collect,
wddctl verify collect, and wddctl freshness record for mechanical evidence
and gate updates. Do not hand-edit their canonical JSON state.
Workflow
-
Load controller context:
- Constitution.
- Epic.
- Shared-context index and relevant resources.
- Wave plan.
orchestration.json.controller-state.md.- Active task files.
- Profile, review mode, and monitoring mode.
- Wave strategy or micro-wave strategy, including
executionMode and
bundleGroups.
-
Ensure each active task has independent state:
- Task ID and path.
- Ticket ID.
- Worker reference.
- Reviewer reference.
- Branch.
- Assigned worker worktree path.
- Worktree status.
- PR or patch reference.
- Latest commit.
- Branch freshness.
- Current gate.
- Open P1/P2 feedback.
- Verification result.
- Shared-context update status.
- Cleanup state.
- For
bundled or hybrid, also track bundle ID, bundle branch, bundle
worktree, bundle worker reference, bundle review reference, bundle current
gate, and bundle cleanup state.
-
Dispatch implementation workers:
- For
parallel, dispatch one task file per worker.
- For
bundled, dispatch one worker with every task file in the wave.
- For
hybrid, dispatch one worker per bundle group with only that bundle's
task files.
- Before dispatch, verify the epic branch exists or create it from the
target branch. If this cannot be done, record
blocked and do not start
workers.
- Before creating task or bundle branches and worktrees, verify the epic
branch contains the current activation artifact state: moved task paths,
active gates, planned task or bundle branches, and assigned worktree paths.
If not, sync those controller-owned artifact changes to the epic branch
first, or record
blocked.
- Before dispatch, create or verify the task branch or bundle branch from the
current epic branch. Branches must start from the epic branch commit that
contains the current activation artifact state.
- Before dispatch, create or verify one isolated worktree per repository
task or bundle, checked out on its assigned branch.
- Verify the assigned task file path or bundle task paths and current
orchestration state exist in the worker worktree before starting the
worker.
- Record the assigned worktree path before starting the worker.
- Require the worker to read assigned task file paths first.
- Require the worker to inspect named files/domains before broad discovery.
- Require the worker to read only relevant shared-context resources.
- Tell the worker the exact worktree path and assigned branch to use.
- Tell the worker to start in that worktree and never switch branches in the
controller checkout.
- Require RED/GREEN TDD unless the task explains why it is inapplicable.
- Require branch, commit, verification evidence, and PR or patch output.
- Require proposed shared-context updates when durable discoveries matter.
- Require final status token:
DONE, DONE_WITH_CONCERNS,
NEEDS_CONTEXT, or BLOCKED.
-
Worker prompt contract:
- Start in the assigned worktree path provided by the controller.
- Confirm the worktree is on the assigned branch before editing.
- Confirm the assigned task file path or bundle task paths and orchestration
state exist in that worktree before editing.
- Do not switch, create, or reset branches in the controller checkout.
- Move or verify assigned task file status transitions from
todo/ to
in-progress/ when starting, inside the assigned worktree.
- Stay within task scope.
- Do not start dependent tasks.
- Do not merge your own PR.
- Move assigned task files to
review/ after PR or patch creation.
- Return PR URL or patch reference.
-
Review gate:
- When a task PR or patch exists, start a separate reviewer where available.
- If review mode is
risk_based, require separate review for high-risk
tasks: auth, security, persistence, migrations, public APIs, generated
code, broad shared contracts, or tasks marked high risk.
- If review mode is
risk_based, allow controller checklist review for
low-risk docs, tests, isolated cleanup, or narrow internal changes when the
constitution allows it.
- If profile is
full, prefer separate reviewer coverage for every
repository-writing task.
- Reviewer checks task compliance, correctness, tests, security,
maintainability, dependency boundaries, conflict domains, scope control,
and whether durable shared context should be extracted.
- Reviewer labels findings P1, P2, or P3.
- P1 and P2 block merge unless the constitution says otherwise and the user
explicitly accepts the risk.
-
Feedback processing:
- Route unresolved P1/P2 feedback to the original worker if its context is
still usable.
- Use a fresh feedback-fix worker when the original worker is unavailable,
stale, context-compressed, or a fresh pass is safer.
- Feedback-fix workers receive the task file, PR or patch, review comments,
relevant shared context, verification expectations, and definition of done.
- Feedback-fix work must not broaden task scope.
-
Branch freshness gate:
- Before merge or merge-ready, check whether the task or bundle branch is stale
relative to the current epic branch.
- If stale, require rebase onto the latest epic branch or merge the latest
epic branch into the task or bundle branch.
- Rerun relevant verification after branch freshness updates.
- Rerun review if touched areas changed materially.
- Do not merge stale task or bundle branches blindly.
-
Shared-context write discipline:
- Workers may propose shared-context updates in task or bundle branches.
- The controller owns reconciliation into the epic branch.
- If two workers update the same shared-context resource, resolve conflicts
during review or wave reconciliation.
- Prefer focused resource files over editing large shared files.
-
Merge gate:
- Deliverable is met.
- Task-level definition of done is met.
- Verification passes or non-blocking failures are explicitly documented.
- High-rigor review has no unresolved P1/P2 findings.
- CI or repo checks are green, unavailable, or explicitly non-blocking.
- Branch freshness is current.
- Linked task file is updated.
- Shared-context updates are reconciled or queued for reconciliation.
- Controller merges into the epic branch, or marks
merge_ready when
repository policy requires human merge.
- For
bundled, the bundle gate clears only when every task in the bundle
has verification evidence and no unresolved blocking feedback.
- For
hybrid, each bundle clears independently; wave reconciliation waits
for all bundles.
-
Worktree cleanup gate:
- After a task or bundle is merged, explicitly closed, cancelled, or blocked
with no pending local evidence needed, inspect its assigned worktree before
wave reconciliation.
- Do not remove a worktree that has uncommitted changes, unpushed commits,
unresolved review/fix work, or evidence that still needs to be copied into
controller artifacts. Record
cleanup_blocked with the reason instead.
- For safe completed worktrees, remove the Git worktree from the controller
checkout with
git worktree remove <assigned-worktree-path>, then run
git worktree prune when stale administrative entries remain.
- Mark task or bundle cleanup state as
cleaned_up, keep the branch and PR
references in artifacts, and set worktreeStatus to cleaned_up.
- If repository policy requires preserving worktrees for a short audit
window, record
cleanup_deferred, the owner, and the exact follow-up
condition.
-
Heartbeat loop:
- Treat each heartbeat as one bounded, idempotent controller tick.
- Start every tick by reading current
orchestration.json,
controller-state.md, task files, and relevant PR or patch state.
- Do not depend on hidden conversation context from a prior tick.
- If monitoring mode is
adaptive, use slower cadence, usually 15-30
minutes, while workers have no PR or patch; use faster cadence, usually 5
minutes, during review, fixes, branch freshness, or merge-ready gates.
Repeated no-change ticks may downgrade to manual fallback when safe.
- If an active wave has missing, inactive, stale, or failed monitoring and
tasks are not yet ready for reconciliation, repair monitoring before
ending the tick. In Codex, create or update a thread heartbeat through
codex_app.automation_update when available; otherwise delegate to the
next scheduler option or downgrade to manual with a durable fallback
prompt and due time.
- Do not record or preserve
codex_thread_heartbeat unless the active
scheduler reference is verified in the current tick.
- not_started: create or verify the epic branch, sync activation artifacts,
create or verify task or bundle branches and assigned isolated worktrees
from that synced state, then dispatch if eligible.
- no_pr: inspect worker state and nudge exact missing deliverable.
- needs_review: start or request review.
- reviewing: poll review state and comments.
- needs_fixes: route current P1/P2 feedback.
- merge_ready: verify evidence, branch freshness, and merge policy.
- merged: update task file, orchestration state, controller state, and
perform the worktree cleanup gate when safe.
- blocked: record blocker, owner, next required input, and whether cleanup
is blocked or safe.
- At the end of each tick, update monitoring last check, next check, status,
scheduler reference, and fallback prompt.
- If all active-wave tasks are merged,
merge_ready, closed, blocked,
cancelled, or otherwise ready for wave reconciliation, stop or deactivate
the monitor and hand off to wdd-reconcile-wave.
- If monitoring cannot be scheduled or resumed, set mode to
manual and
record the exact prompt and due time needed for a human or fresh agent to
run the next tick.
-
Update state after every meaningful event:
- Epic branch created or verified.
- Task branch created or verified.
- Worker worktree created or verified.
- Worker started.
- Bundle branch, worktree, or worker started.
- Task moved.
- PR or patch created.
- Review started.
- P1/P2 found.
- Feedback routed.
- Fix pushed.
- Branch freshness checked.
- Verification passed or failed.
- Merge or merge-ready decision completed.
- Worktree cleanup completed, blocked, or deferred.
- Shared-context reconciliation completed or queued.
- Blocker encountered.
- Monitoring tick completed, rescheduled, stopped, or downgraded to manual.
-
Completion handoff:
- When all active-wave tasks are merged,
merge_ready, closed, blocked,
cancelled, or otherwise ready for wave reconciliation, invoke
wdd-reconcile-wave.
- Do not start the next wave before reconciliation.
Done When
- Every active task has current independent state.
- Every active bundle has current independent state when execution mode is
bundled or hybrid.
- P1/P2 feedback is routed.
- Branch freshness is enforced before merge.
- Merge happens only after verification, review, and freshness gates pass.
- Completed, closed, cancelled, or safely blocked worktrees are removed, or a
concrete cleanup blocker/deferment is recorded.
- Completed wave is ready for
wdd-reconcile-wave.
