-
Validate: plan-tooling validate --file <plan.md>
-
Start plan:
plan-issue start-plan --plan <plan.md> --strategy auto --default-pr-grouping group [--repo <owner/repo>]
-
Initialize branch contract (after capturing ISSUE_NUMBER):
DEFAULT_BRANCH="$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')"
PLAN_BRANCH="plan/issue-${ISSUE_NUMBER}"
PLAN_BRANCH_REF_PATH="$AGENT_HOME/out/deliver-dispatch-plan/<repo-slug>/issue-${ISSUE_NUMBER}/plan/plan-branch.ref"
git fetch origin --prune
git checkout -B "$PLAN_BRANCH" "origin/$DEFAULT_BRANCH"
git push -u origin "$PLAN_BRANCH"
printf '%s\n' "$PLAN_BRANCH" > "$PLAN_BRANCH_REF_PATH"
-
Start sprint:
plan-issue start-sprint --plan <plan.md> --issue <number> --sprint <n> --strategy auto --default-pr-grouping group [--repo <owner/repo>]
-
Link PR (task scope):
plan-issue link-pr --issue <number> --task <task-id> --pr <#123|123|pull-url> [--status <planned|in-progress|blocked>] [--repo <owner/repo>]
-
Link PR (sprint lane scope):
plan-issue link-pr --issue <number> --sprint <n> [--pr-group <group>] --pr <#123|123|pull-url> [--status <planned|in-progress|blocked>] [--repo <owner/repo>]
-
Status checkpoint (optional): plan-issue status-plan --issue <number> [--repo <owner/repo>]
-
Ready sprint:
plan-issue ready-sprint --plan <plan.md> --issue <number> --sprint <n> --strategy auto --default-pr-grouping group [--repo <owner/repo>]
-
Pre-merge review check (recommended before merge decisions):
gh pr view <pr-number> --json state,baseRefName,headRefName,isDraft,statusCheckRollup
- Expected:
state=OPEN, baseRefName=$PLAN_BRANCH, required checks green.
- Treat
no checks reported as blocking failure unless user explicitly approves override.
-
Accept sprint:
plan-issue accept-sprint --plan <plan.md> --issue <number> --sprint <n> --strategy auto --default-pr-grouping group --approved-comment-url <comment-url> [--repo <owner/repo>]
-
Local sync after sprint acceptance:
git fetch origin --prune
git switch "$PLAN_BRANCH" || git switch -c "$PLAN_BRANCH" --track "origin/$PLAN_BRANCH"
git pull --ff-only
-
Ready plan: plan-issue ready-plan --issue <number> [--repo <owner/repo>]
-
Write final plan conformance review (PLAN_CONFORMANCE_REVIEW_PATH):
PLAN_CONFORMANCE_REVIEW_PATH="$AGENT_HOME/out/deliver-dispatch-plan/<repo-slug>/issue-${ISSUE_NUMBER}/plan/plan-conformance-review.md"
-
Final integration PR (PLAN_BRANCH -> DEFAULT_BRANCH):
gh pr create --base "$DEFAULT_BRANCH" --head "$PLAN_BRANCH" --title "plan(issue-${ISSUE_NUMBER}): merge ${PLAN_BRANCH} into ${DEFAULT_BRANCH}" --body "<summary>"
-
Verify integration required checks before merge and write PLAN_INTEGRATION_CI_PATH:
INTEGRATION_PR_NUMBER="<number>"
PLAN_INTEGRATION_CI_PATH="$AGENT_HOME/out/deliver-dispatch-plan/<repo-slug>/issue-${ISSUE_NUMBER}/plan/plan-integration-ci.md"
gh pr checks "$INTEGRATION_PR_NUMBER" --required --watch
-
Post and persist the final integration delivery outcome comment before
merge:
INTEGRATION_PR_NUMBER="<number>"
PLAN_INTEGRATION_OUTCOME_PATH="$AGENT_HOME/out/deliver-dispatch-plan/<repo-slug>/issue-${ISSUE_NUMBER}/plan/plan-integration-outcome.url"
OUTCOME_COMMENT_PATH="$AGENT_HOME/out/deliver-dispatch-plan/<repo-slug>/issue-${ISSUE_NUMBER}/plan/plan-integration-outcome.md"
gh pr comment "$INTEGRATION_PR_NUMBER" --body-file "$OUTCOME_COMMENT_PATH"
printf '%s\n' "$PLAN_INTEGRATION_OUTCOME_URL" > "$PLAN_INTEGRATION_OUTCOME_PATH"
-
Merge integration PR only after conformance + required-check + outcome
comment gates pass (prefer squash, fallback to merge when squash is
unavailable):
if gh repo view --json squashMergeAllowed --jq '.squashMergeAllowed' | grep -q true; then
gh pr merge "$INTEGRATION_PR_NUMBER" --squash || gh pr merge "$INTEGRATION_PR_NUMBER" --merge
else
gh pr merge "$INTEGRATION_PR_NUMBER" --merge
fi
-
Mention integration PR on the plan issue and persist comment URL:
INTEGRATION_PR_NUMBER="<number>"
PLAN_INTEGRATION_MENTION_PATH="$AGENT_HOME/out/deliver-dispatch-plan/<repo-slug>/issue-${ISSUE_NUMBER}/plan/plan-integration-mention.url"
PLAN_INTEGRATION_MENTION_URL="<https://github.com/<owner>/<repo>/issues/${ISSUE_NUMBER}#issuecomment-...>"
gh issue comment "$ISSUE_NUMBER" \
--body "Final integration PR merged: #${INTEGRATION_PR_NUMBER} (\`${PLAN_BRANCH}\` -> \`${DEFAULT_BRANCH}\`)."
printf '%s\n' "$PLAN_INTEGRATION_MENTION_URL" > "$PLAN_INTEGRATION_MENTION_PATH"
-
Close plan: plan-issue close-plan --issue <number> --approved-comment-url <comment-url> [--repo <owner/repo>]
-
Local sync after final close:
git fetch origin --prune
git switch "$DEFAULT_BRANCH" || git switch -c "$DEFAULT_BRANCH" --track "origin/$DEFAULT_BRANCH"
git pull --ff-only
