dispatch-subagent-pr

name	dispatch-subagent-pr
description	Subagent workflow for assigned task-lane implementation, blocker clarification handoffs, draft PR creation, and review-response updates linked back to the owning issue.

Dispatch Subagent PR

Subagent owns implementation execution on an assigned task lane (Owner / Branch / Worktree / Execution Mode / PR) and keeps PR/issue artifacts synchronized.

Contract

Prereqs:

• Run inside the target git repo.
• git and gh available on PATH, and gh auth status succeeds.
• Worktree/branch ownership assigned by main-agent (or the issue Task Decomposition table when using plan-issue flows).

Inputs:

• Repository context:
  • issue number (ISSUE) and task ID (TASK_ID)
  • optional repository override (owner/repo) for gh commands
• Required implementation context in live mode (same priority, both required):
  • GitHub issue artifacts:
    • assigned ## Task Decomposition row for TASK_ID
    • target sprint section context from issue comments (prefer ## Sprint <N> Start)
  • Main-agent dispatch artifacts:
    • rendered task prompt artifact (TASK_PROMPT_PATH)
    • PLAN_SNAPSHOT_PATH when dispatch came from deliver-dispatch-plan
    • DISPATCH_RECORD_PATH when dispatch came from deliver-dispatch-plan (including workflow_role and optional runtime adapter metadata)
    • plan task section context (exact snippet and/or direct link/path)
• Required implementation context in local rehearsal mode:
  • local rendered task prompt/artifacts and plan task context (no GitHub lookup for placeholder issues such as 999)
• Base branch, PR title, and PR body markdown file path.
  • In deliver-dispatch-plan mode, base branch must come from main-agent dispatch (PLAN_BRANCH); do not assume main.
• Optional follow-up context for lane re-entry:
  • review comment URL + response body markdown for follow-up comments
  • clarification/unblock notes from main-agent for a previously assigned lane

Outputs:

• Dedicated task worktree checked out to the assigned branch, either by re-entering the existing lane or by creating the lane if it does not exist yet.
• Draft PR URL for the implementation branch, or confirmed reuse of the assigned PR for follow-up work.
• PR/body validation evidence (required sections present; placeholders removed).
• Blocker/clarification handoff packet when required context is missing/conflicting or an external blocker stops forward progress.
• Review response comments on the PR that reference the main-agent review comment URL.
• Optional issue sync comments (gh issue comment) that mirror task status and PR linkage.
• plan-issue artifact compatibility: canonical issue/PR references (#<number>) suitable for Task Decomposition sync.

Exit codes:

• 0: success
• non-zero: invalid inputs, failed validation checks, repo context issues, or git/gh failures

Failure modes:

• Missing assigned execution facts (issue/task/owner/branch/worktree).
• Live mode: unable to resolve the assigned task row from issue ## Task Decomposition.
• Live mode: unable to resolve target sprint task context from issue comments.
• Live mode: missing TASK_PROMPT_PATH or missing plan task section context from main-agent dispatch.
• deliver-dispatch-plan mode: missing PLAN_SNAPSHOT_PATH fallback artifact from dispatch.
• deliver-dispatch-plan mode: missing DISPATCH_RECORD_PATH assignment artifact from dispatch.
• deliver-dispatch-plan mode: DISPATCH_RECORD_PATH missing canonical workflow_role.
• deliver-dispatch-plan mode: DISPATCH_RECORD_PATH declares a non-implementation workflow_role for implementation execution.
• Named-role runtime fallback used but runtime_role_fallback_reason missing.
• Missing/empty base-branch assignment from dispatch (for example PLAN_BRANCH not provided in deliver-dispatch-plan mode).
• Context mismatch between issue artifacts and main-agent dispatch artifacts (scope, ownership, branch/worktree, execution mode).
• Context mismatch where linked/opened PR base branch differs from assigned base branch.
• deliver-dispatch-plan mode: assigned WORKTREE path is outside $AGENT_HOME/out/deliver-dispatch-plan/....
• Worktree path collision or branch already bound to another worktree.
• Follow-up/re-entry drifts away from the assigned task lane by inventing a replacement Owner, Branch, Worktree, or PR without explicit reassignment.
• Empty PR body file or unresolved template placeholders (TBD, TODO, <...>, #<number>, template stub lines).
• Missing required PR body sections (## Summary, ## Scope, ## Testing, ## Issue).
• gh auth/permission failures for PR/issue reads or writes.

Test-First Evidence Gate

• Before editing production behavior, capture failing-test evidence or an explicit waiver.
• This gate applies before editing production behavior.
• The subagent must report Change classification, Failing test before fix, Final validation, and Waiver reason when applicable.
• Docs-only, generated-only, formatting-only, visual-only, or no-harness tasks may use a waiver plus substitute validation.
• Main-agent review may request follow-up when a behavior-changing PR lacks both failing-test evidence and a waiver.

Task Lane Continuity (Mandatory)

• Follow the shared task-lane continuity policy: skills/workflows/issue/_shared/references/TASK_LANE_CONTINUITY.md
• Treat assigned Owner / Branch / Worktree / Execution Mode / PR as one task lane.
• Re-enter an existing worktree/branch/PR when the lane already exists; create lane artifacts only when they do not exist yet or when main-agent explicitly reassigns the lane.
• If clarification or follow-up is needed, hand control back to main-agent with exact lane facts and continue on that same lane once clarified.

Command Contract (Scriptless)

• Use native git for worktree and branch lifecycle.
• Use native gh for draft PR creation and PR/issue comments.
• Use rg-based checks (or equivalent) for PR body section/placeholder validation before PR open and before final review updates.

Ordered workflow (read requirements first)

1. Determine execution mode and initialize context variables:

   • REPO="owner/repo"   # optional when current remote context is correct
     ISSUE=175
     SPRINT=2
     TASK_ID="S2T3"
     BASE="plan/issue-175"  # required from dispatch in deliver-dispatch-plan mode
     

   • Live mode: ISSUE is a real GitHub issue number.

   • Local rehearsal mode: ISSUE is placeholder (for example 999), so use local artifacts only.

2. Collect required context artifacts before edits:

   • Live mode: collect issue artifacts with gh:

     • gh issue view "$ISSUE" -R "$REPO" --json body --jq '.body' \
       | awk -F'|' -v t="$TASK_ID" '
           /^\|/ { task=$2; gsub(/^ +| +$/, "", task); if (task==t) print $0 }'
       

     • gh api "repos/$REPO/issues/$ISSUE/comments" --paginate \
         --jq '.[] | select(.body|contains("## Sprint '"$SPRINT"' Start")) | .html_url, .body'
       

   • Collect main-agent artifacts in both modes:

     • TASK_PROMPT_PATH
     • PLAN_SNAPSHOT_PATH (required in deliver-dispatch-plan mode)
     • DISPATCH_RECORD_PATH (required in deliver-dispatch-plan mode)
     • workflow_role from DISPATCH_RECORD_PATH
     • optional runtime_name / runtime_role from DISPATCH_RECORD_PATH
     • plan task section snippet/link/path

3. Reconcile context and apply hard start gate:

   • Treat issue artifacts and main-agent artifacts as equal-priority sources in live mode.
   • Confirm assigned task facts align across sources: owner, branch, worktree, execution mode, task scope, and acceptance intent.
   • In deliver-dispatch-plan mode, confirm DISPATCH_RECORD_PATH facts match assigned task row (Task Decomposition) and runtime artifact paths.
   • In deliver-dispatch-plan mode, confirm workflow_role is implementation before starting implementation.
   • If runtime adapter metadata is present, confirm it is internally consistent; when runtime_role=generic, require a recorded fallback rationale.
   • Confirm assigned base branch is present; in deliver-dispatch-plan mode it must match dispatched PLAN_BRANCH.
   • In deliver-dispatch-plan mode, enforce WORKTREE prefix: $AGENT_HOME/out/deliver-dispatch-plan/.
   • If any required context is missing or conflicting, stop and request clarification from main-agent before implementation.
   • When pausing for clarification, return a concise blocker packet:
     • confirmed task-lane facts
     • missing/conflicting context
     • current status (blocked vs in-progress)
     • exact next unblock action needed from main-agent

4. Create or re-enter the assigned worktree/branch:

   • AGENT_HOME="${AGENT_HOME:?AGENT_HOME is required}"
     ISSUE=123
     TASK_ID=T1
     BASE="${BASE:?BASE is required from lane assignment}"
     REPO_SLUG="owner__repo"
     BRANCH="issue/${ISSUE}/${TASK_ID}-api"
     WORKTREE="$AGENT_HOME/out/deliver-dispatch-plan/${REPO_SLUG}/issue-${ISSUE}/worktrees/pr-isolated/${TASK_ID}"
     
     if [ -e "$WORKTREE/.git" ]; then
       cd "$WORKTREE"
     else
       git fetch origin --prune
       git worktree add -b "$BRANCH" "$WORKTREE" "origin/$BASE"
       cd "$WORKTREE"
     fi
     
     git branch --show-current
     git worktree list
     

5. Implement task scope and run required task-level validation:

   • Capture the Test-First Evidence Gate before production behavior edits.
   • Prefer validation commands from task context (TASK_PROMPT_PATH / sprint task section / Task Decomposition notes).
   • Keep edits inside assigned task scope; escalate before widening scope.
   • If required context is discovered missing/conflicting during implementation, stop, report the blocker packet, and wait for main-agent clarification instead of inventing replacement lane facts.

6. Prepare and validate PR body (required sections + placeholder checks):

   • BODY_FILE="$WORKTREE/.tmp/pr-${ISSUE}-${TASK_ID}.md"
     mkdir -p "$(dirname "$BODY_FILE")"
     cp $HOME/.config/agent-kit/skills/workflows/issue/dispatch-subagent-pr/references/PR_BODY_TEMPLATE.md "$BODY_FILE"
     # Edit BODY_FILE and replace all template placeholders before continuing.
     
     for section in "## Summary" "## Scope" "## Testing" "## Issue"; do
       rg -q "^${section}$" "$BODY_FILE" || { echo "Missing section: ${section}" >&2; exit 1; }
     done
     
     rg -n 'TBD|TODO|<[^>]+>|#<number>|<implemented scope>|<explicitly excluded scope>|<command> \\(pass\\)|not run \\(reason\\)' "$BODY_FILE" \
       && { echo "Placeholder content found in PR body" >&2; exit 1; } || true
     

7. Open draft PR (initial run only):

   • In deliver-dispatch-plan mode, prefer the dispatch lane PR helper so the body matches the canonical schema and the PR targets the dispatched PLAN_BRANCH:

     $AGENT_HOME/skills/workflows/pr/dispatch/create-dispatch-lane-pr/scripts/create-dispatch-lane-pr.sh \
       --dispatch-record "$DISPATCH_RECORD_PATH" \
      --issue "$ISSUE" \
      --summary "<real summary bullet>" \
      --scope "<file/module>: <change> (${TASK_ID})" \
      --test-first-evidence "Change classification: <behavior|bug|refactor|docs|test-only>" \
      --test-first-evidence "Failing test before fix: <test/command/evidence or explicit waiver>" \
      --test-first-evidence "Final validation: <command> (pass)" \
      --test-first-evidence "Waiver reason: <N/A or reason>" \
      --testing "<real command> (pass)"
     

   • For non-plan-issue flows, use the audited GitHub PR marker:

   • if [ -z "${PR_NUMBER:-}" ]; then
       AGENT_KIT_PR_SKILL=create-github-pr gh pr create \
         --draft \
         --base "$BASE" \
         --head "$BRANCH" \
         --title "feat(issue-${ISSUE}): implement ${TASK_ID} API changes" \
         --body-file "$BODY_FILE"
     fi
     
     PR_NUMBER="$(gh pr view --json number --jq '.number')"
     PR_URL="$(gh pr view --json url --jq '.url')"
     echo "Opened ${PR_URL}"
     

   • If the assigned PR already exists, skip gh pr create, keep the same branch/worktree/PR lane, and continue updates on that PR.

   • In deliver-dispatch-plan mode, keep the sprint PR open for main-agent ready-sprint review; do not self-merge.

8. Post review response comment with gh pr comment (when follow-up requested on the assigned PR):

   • REVIEW_COMMENT_URL="https://github.com/<owner>/<repo>/pull/<pr>#issuecomment-<id>"
     RESPONSE_FILE="$WORKTREE/.tmp/review-response-${PR_NUMBER}.md"
     cp $HOME/.config/agent-kit/skills/workflows/issue/dispatch-subagent-pr/references/REVIEW_RESPONSE_TEMPLATE.md "$RESPONSE_FILE"
     # Edit RESPONSE_FILE: include REVIEW_COMMENT_URL and concrete change/testing notes.
     
     gh pr comment "$PR_NUMBER" --body-file "$RESPONSE_FILE"
     

9. Optional issue sync comment with gh issue comment (traceability):

   • gh issue comment "$ISSUE" \
       --body "Task ${TASK_ID} in progress by subagent. Branch: \`${BRANCH}\`. Worktree: \`${WORKTREE}\`. PR: #${PR_NUMBER}. Review response: ${REVIEW_COMMENT_URL}"
     

10. Optional plan-issue artifact sync note:

• In plan-issue flows, prefer main-agent link-pr updates over manual markdown edits:
  • plan-issue link-pr --issue "$ISSUE" --task "$TASK_ID" --pr "#${PR_NUMBER}" --status in-progress
• Subagent should include exact task selector + PR number in handoff comments so main-agent can run link-pr deterministically.
• Keep Task Decomposition row fields (Owner, Branch, Worktree, Execution Mode, PR) aligned with actual execution facts so plan-issue status-plan / ready-plan snapshots remain consistent.

References

• PR body template: references/PR_BODY_TEMPLATE.md
• Review response template: references/REVIEW_RESPONSE_TEMPLATE.md
• Subagent task prompt template: references/SUBAGENT_TASK_PROMPT_TEMPLATE.md
• Shared task-lane continuity policy (canonical): skills/workflows/issue/_shared/references/TASK_LANE_CONTINUITY.md

Notes

• Subagent may pre-fill references/SUBAGENT_TASK_PROMPT_TEMPLATE.md from assigned execution facts to avoid owner/branch/worktree drift during implementation.
• Treat PR body validation as a required gate, not an optional cleanup step.
• Keep implementation details and evidence in PR comments; issue comments should summarize status and link back to PR artifacts.
• Subagent owns implementation execution; main-agent remains orchestration/review-only.
• Even for single-PR issues, implementation PR authorship/ownership stays with subagent.
• Clarification/follow-up pauses are expected control-flow, not permission to widen scope or create replacement execution facts.