create-dispatch-lane-pr

name	create-dispatch-lane-pr
description	Open a draft GitHub dispatch lane PR for a plan-issue implementation lane using the assigned dispatch record, PLAN_BRANCH base branch, and canonical dispatch lane PR body schema.

Create Dispatch Lane PR

Contract

Prereqs:

• Run inside, or have access to, the target git repository.
• git, gh, and python3 available on PATH.
• gh auth status succeeds when creating a real PR.
• A plan-issue dispatch record exists for the assigned implementation lane.
• The assigned worktree is an existing git work tree under the plan-issue runtime root.

Inputs:

• Required:
  • --dispatch-record <path> pointing at dispatch-<TASK_ID>.json.
  • --issue <number> for the ## Issue bullet.
  • At least one --summary <text>, --scope <text>, and --testing <text>.
• Optional:
  • --repo-slug <owner/repo> for title context.
  • --title <text> to override the default sprint title.
  • --body-only to render the PR body without calling gh.
  • --body-out <path> to write the rendered body before creating the PR.
  • Repeatable --test-first-evidence <text> to override the default ## Test-First Evidence bullets.
  • --ready to run gh pr ready after draft creation.

Outputs:

• Rendered PR body matching Summary / Scope / Test-First Evidence / Testing / Issue.
• In create mode, a draft PR opened from the dispatch-record worktree:
  • --base is the dispatch record base_branch (PLAN_BRANCH).
  • --head is the dispatch record branch.
  • body follows $AGENT_HOME/skills/automation/issue/deliver-dispatch-plan/references/SPRINT_PR_TEMPLATE.md.
• PR URL printed on stdout after creation.

Exit codes:

• 0: success
• 1: failure
• 2: usage error

Failure modes:

• Dispatch record missing or malformed.
• Dispatch record has no branch, base_branch, task ID, or worktree path.
• Assigned worktree path is not an existing git top-level.
• Rendered body contains validator-rejected placeholders (TODO, TBD, <...>, #<number>, not run (reason), <command> (pass)).
• gh pr create fails because auth, branch, remote, or permission prerequisites are missing.

Scripts (only entrypoints)

• $AGENT_HOME/skills/workflows/pr/dispatch/create-dispatch-lane-pr/scripts/create-dispatch-lane-pr.sh
  • Optional repeatable input: --test-first-evidence <text> for concrete failing-test, waiver, and final-validation evidence bullets.

Workflow

1. Read DISPATCH_RECORD_PATH and resolve:

   • worktree_abs_path (preferred) or worktree.
   • branch.
   • base_branch (PLAN_BRANCH).
   • task_id plus any sibling task IDs recorded for the lane.

2. Verify the worktree is the active git top-level:

   git -C "$WORKTREE" rev-parse --show-toplevel
   

3. Render the PR body with the bundled renderer:

   $AGENT_HOME/skills/workflows/pr/dispatch/create-dispatch-lane-pr/scripts/create-dispatch-lane-pr.sh \
     --dispatch-record "$DISPATCH_RECORD_PATH" \
     --issue "$ISSUE_NUMBER" \
     --summary "Sprint 2 completes the grouped storage lane." \
     --scope "src/storage/: implements S2T2 and S2T3." \
     --test-first-evidence "Change classification: behavior change." \
     --test-first-evidence "Failing test before fix: tests/unit/test_storage.py::test_groups_by_key (failed before implementation)." \
     --test-first-evidence "Final validation: scripts/check.sh --tests -- -k storage (pass)." \
     --test-first-evidence "Waiver reason: N/A." \
     --testing "scripts/check.sh --tests -- -k storage (pass)" \
     --body-only
   

4. Create the draft PR only after local lane validation has run:

   $AGENT_HOME/skills/workflows/pr/dispatch/create-dispatch-lane-pr/scripts/create-dispatch-lane-pr.sh \
     --dispatch-record "$DISPATCH_RECORD_PATH" \
     --issue "$ISSUE_NUMBER" \
     --summary "Sprint 2 completes the grouped storage lane." \
     --scope "src/storage/: implements S2T2 and S2T3." \
     --test-first-evidence "Change classification: behavior change." \
     --test-first-evidence "Failing test before fix: tests/unit/test_storage.py::test_groups_by_key (failed before implementation)." \
     --test-first-evidence "Final validation: scripts/check.sh --tests -- -k storage (pass)." \
     --test-first-evidence "Waiver reason: N/A." \
     --testing "scripts/check.sh --tests -- -k storage (pass)"
   

5. Send the printed PR URL back to the main agent so it can run plan-issue link-pr.

Rules

• Dispatch lane PRs target PLAN_BRANCH, not the default branch.
• Keep PRs draft until the implementation lane validation is green; pass --ready only after validation is complete.
• Do not use the feature/bug PR body templates for dispatch lane PRs.
• Do not self-merge the dispatch lane PR. Merge authority belongs to the dispatch main agent.
• For grouped lanes, include all task IDs in --scope bullets so reviewers can map diff scope back to the plan.