dispatch-issue-closeout

name	dispatch-issue-closeout
description	Close out an existing plan-issue runtime where main-agent owns orchestration and review only, subagents own implementation task lanes, and close gates require approval plus merged PRs.

Dispatch Issue Closeout

Contract

Prereqs:

• Run inside (or have access to) the target repository.
• plan-issue available on PATH.
• gh available on PATH, and gh auth status succeeds for live issue/PR reads and writes.
• dispatch-pr-review is the review decision workflow after handoff.

Inputs:

• Plan issue number (--issue <number>) created during plan orchestration.
• ISSUE_NUMBER should be captured from upstream plan-issue start-plan output and reused across all commands in this skill.
• Optional repository override (--repo <owner/repo>).
• Optional review summary text (--summary).
• Plan-close approval comment URL (PLAN_APPROVED_COMMENT_URL) for close-plan.
• Approval URL format: https://github.com/<owner>/<repo>/(issues|pull)/<n>#issuecomment-<id>.
• PR linkage inputs for runtime row sync (--task <task-id> or --sprint <n> [--pr-group <group>], plus --pr <#123|123|pull-url>).
• Conditional subagent dispatch bundle (required when this issue is plan-sprint originated via plan-issue start-sprint):
  • rendered TASK_PROMPT_PATH artifact for the assigned lane/task
  • issue-scoped PLAN_SNAPSHOT_PATH
  • task-scoped DISPATCH_RECORD_PATH
  • plan task section context (exact snippet and/or direct link/path)
• Local rehearsal policy:
  • This main skill is live-mode default (plan-issue ...).
  • If rehearsal is explicitly requested, load references/LOCAL_REHEARSAL.md.
• Task owners must be subagent identities (must reference subagent); main-agent ownership is invalid for implementation tasks.

Outputs:

• Deterministic orchestration over typed plan-issue command flows with explicit gate checks.
• Status snapshots and review-request markdown blocks for traceable issue history.
• Deterministic PR linkage/status sync through link-pr before review and close gates.
• Issue close only when review approval and merged-PR checks pass via close-plan.
• Definition of done: execution is complete only when close-plan succeeds and the target issue is actually closed. The done state also requires one deliver-dispatch-plan:closeout:v1 marker, plus a current dashboard that links latest dispatch state/session/validation evidence.
• Error contract: if any gate/command fails, stop forward progress and report the failing command plus key stderr/stdout gate errors.
• Main-agent acts as orchestrator/reviewer only; implementation branches/PRs are delegated to subagents.
• Issue task table remains the single execution source of truth (Subagent PRs section is removed by sync).
• Subagent-owned task lanes stay stable across implementation, clarification, CI, and review follow-up unless main-agent explicitly reassigns the lane.

Exit codes:

• 0: success
• 1: runtime failure / gate failure
• 2: usage error

Failure modes:

• Missing required options (--issue, --approved-comment-url, --summary when required by policy).
• Missing required binaries (plan-issue; gh for live mode).
• Invalid approval URL format or repo mismatch with --repo.
• link-pr target ambiguity (for example sprint selector spans multiple runtime lanes without --pr-group).
• link-pr rejected PR selector (--pr does not resolve to a concrete PR number).
• Task rows violate close gates (status not done, execution metadata/PR missing, or PR not merged).
• Issue/PR metadata fetch fails via gh in live mode.
• Task Owner is main-agent/non-subagent identity in Task Decomposition.
• Plan-sprint originated dispatch launched without required bundle (TASK_PROMPT_PATH, PLAN_SNAPSHOT_PATH, DISPATCH_RECORD_PATH, plan task snippet/link/path).
• Review or clarification follow-up is redirected into a replacement branch/worktree/PR without explicit task-lane reassignment.

Entrypoint

• None. This orchestration skill intentionally uses plan-issue command flows and has no repo-local scripts/ entrypoint.

Role Boundary (Mandatory)

• Main-agent is limited to issue orchestration:
  • status/review-handoff/close gates
  • dispatch and acceptance decisions
• Main-agent must not implement issue tasks directly.
• Even for a single-PR issue, implementation must be produced by a subagent PR and then reviewed by main-agent.
• Main-agent review/merge decisions should use dispatch-pr-review; this loop skill enforces ownership and close gates.

Task Lane Continuity (Mandatory)

• Follow the shared task-lane continuity policy: skills/workflows/issue/_shared/references/TASK_LANE_CONTINUITY.md
• Treat each Task Decomposition row as one task lane and keep follow-up on that lane by default.
• Replacement dispatch is allowed only when the original subagent cannot continue or when assignment facts must change; preserve issue row and PR linkage deterministically when reassigning.

References

• Local rehearsal playbook (plan-issue-local and plan-issue --dry-run): references/LOCAL_REHEARSAL.md
• Shared task-lane continuity policy (canonical): skills/workflows/issue/_shared/references/TASK_LANE_CONTINUITY.md
• Shared main-agent review rubric (canonical): skills/workflows/issue/_shared/references/MAIN_AGENT_REVIEW_RUBRIC.md
• Shared post-review outcome handling (canonical): skills/workflows/issue/_shared/references/POST_REVIEW_OUTCOMES.md
• Dispatch issue record contract: skills/workflows/issue/_shared/references/DISPATCH_ISSUE_RECORD_CONTRACT.md

Core usage

1. Live mode is default in this main skill: plan-issue <subcommand> ....
2. Resolve and reuse a single ISSUE_NUMBER from upstream plan orchestration, then dispatch implementation to subagents via dispatch-subagent-pr.
   • If the issue originated from plan-issue start-sprint, dispatch each subagent with:
     • rendered TASK_PROMPT_PATH
     • PLAN_SNAPSHOT_PATH
     • DISPATCH_RECORD_PATH
     • assigned plan task section snippet/link/path
3. Keep runtime-truth rows synchronized with link-pr; add status-plan checkpoints when needed, and use blocked while a task lane is waiting on clarification or another external unblock.
4. Handoff review with ready-plan, apply the shared main-agent review rubric, run review decisions through dispatch-pr-review, and route follow-up back to the same subagent-owned task lane until close gates are satisfied.
5. Close with close-plan using PLAN_APPROVED_COMMENT_URL.
6. After close-plan, post or verify one deliver-dispatch-plan:closeout:v1 comment, verify latest dispatch state/session/validation links, and repair the current dashboard when it points at stale evidence.
7. If local rehearsal is explicitly requested, switch to references/LOCAL_REHEARSAL.md.

Completion Policy (Mandatory)

• Do not stop at status-plan or ready-plan as a final state.
• A successful run must terminate at close-plan with issue state CLOSED.
• close-plan success is not enough by itself; the issue must also contain one deliver-dispatch-plan:closeout:v1 marker, latest dispatch state/session/validation links, and a current dashboard.
• If close gates fail, treat the run as unfinished and report:
  • failing command
  • gate errors (task status, PR merge, approval URL, or owner policy)
  • next required unblock action

Full Skill Flow

1. Confirm repository context, runtime mode (plan-issue), and gh auth status for live mode.
2. Confirm the plan issue already exists, capture ISSUE_NUMBER from upstream orchestration output, and keep using that single value for all --issue flags.
3. Confirm task decomposition ownership remains subagent-only.
4. Main-agent dispatches implementation tasks to subagents (for example via dispatch-subagent-pr), while remaining orchestration/review-only.
   • For plan-sprint originated issues, dispatch must include the required bundle:
     • rendered TASK_PROMPT_PATH
     • PLAN_SNAPSHOT_PATH
     • DISPATCH_RECORD_PATH
     • assigned plan task section snippet/link/path
5. As subagent PRs progress, run link-pr to update issue task PR and Status fields (instead of manual table edits).
   • Task-scoped link: plan-issue link-pr --issue <number> --task <task-id> --pr <#123|123|pull-url> [--status <planned|in-progress|blocked>]
   • --task automatically syncs shared-lane rows (per-sprint / pr-shared) in one operation.
   • Sprint-scoped link is valid only when the target resolves to one runtime lane; otherwise specify --pr-group.
   • Use in-progress while a lane is actively implementing or addressing requested follow-up.
   • Use blocked while a lane is waiting on missing/conflicting context or an external unblock.
6. If a subagent reports missing/conflicting context or another blocker, stop forward progress, clarify the task, and send the work back to the same task lane by default instead of widening scope or opening a replacement PR path.
7. Run status-plan to generate a main-agent snapshot comment for task/PR/review state checkpoints.
8. Run ready-plan when the issue is ready for main-agent review handoff.
9. Main-agent reviews subagent PRs against skills/workflows/issue/_shared/references/MAIN_AGENT_REVIEW_RUBRIC.md (typically using dispatch-pr-review), requests follow-up back to the current subagent-owned task lane or merges until close gates are satisfied.
10. After each review decision, apply skills/workflows/issue/_shared/references/POST_REVIEW_OUTCOMES.md to keep issue/task state synchronized before any further dispatch or final close gate work.
11. Run close-plan with PLAN_APPROVED_COMMENT_URL to enforce final gates (task status plus merged PR checks), re-sync/normalize the issue task table, and close the issue.
12. Post or verify the dispatch closeout marker and dashboard evidence described by skills/workflows/issue/_shared/references/DISPATCH_ISSUE_RECORD_CONTRACT.md; latest dispatch state/session/validation comments are the issue-visible recovery trail for the close.

Notes

• Keep local rehearsal details in references/LOCAL_REHEARSAL.md; load it only when explicitly requested.
• Prefer link-pr for PR/status updates so row normalization and lane sync rules stay consistent.
• Execution Mode controls branch/worktree uniqueness checks: only pr-isolated requires unique branch/worktree per row.
• Use --dry-run to suppress write operations while previewing commands.
• Use a single ISSUE_NUMBER variable across the run to avoid cross-issue updates.
• If the original subagent cannot continue, reassign explicitly and keep the new subagent on the same task-lane facts unless the issue row is intentionally updated first.
• After request-followup or close-pr, do not continue orchestration from a stale row; apply the shared post-review outcome handling first.
• For dispatch-pr-review, prefer structured outcome flags (request-followup: --row-status, --next-owner; close-pr: --close-reason, --next-action, optional --replacement-pr, --row-status) so row sync comments are deterministic.