How long does the integration take?

Change one base URL in an OpenAI-compatible client, or install the Python or TypeScript SDK; the quickstart routes a first request in a few minutes.

Will this lock us into another vendor?

No. The router is Apache-2.0 open source, your provider keys stay yours, and the API is OpenAI-compatible, so leaving is a change of base URL.

What happens when a provider fails?

The router falls back to the next model your policy allows and records the fallback in the trace, so an outage costs a retry, not an incident.

pr:drive - Prompt - OpenSmartRoute

Name: pr:drive
Author: helalifaker

Prompt file imported from helalifaker/budfin (.codex/prompts/pr.drive.md). Fill in {{QUEUE_INDEX}}, {{QUEUE_SIZE}} before use. Copyright stays with the author.

Parse the argument:

Three modes:

Story mode: /pr:drive [story-issue-number] -- finds PR via Fixes #N search, enforces phase gate
PR mode: /pr:drive --pr N [N...] -- drives one or more PRs by number directly, no phase gate
Epic mode: /pr:drive --epic [epic-#] -- drives ALL open PRs for an Epic in dependency order

If none match, ask: "Provide a story number, use --pr N [N...] for direct PR numbers, or --epic N for all Epic PRs."

Step 0 -- Initialize

0a. Verify gh auth

gh auth status

If not authenticated, guide user to gh auth login and stop.

0b. Build PR queue

Story mode:

Phase gate: read .claude/workflow/STATUS.md
- Phase 6 (IMPLEMENT) with an existing draft PR: proceed
- Phase 7 (REVIEW): proceed
- Otherwise: stop with error:
```
Error: /pr:drive requires Phase 6 (with a draft PR) or Phase 7.
Current phase is [N] -- [NAME].
```

Find PR:

gh pr list --search "Fixes #$STORY_NUMBER" --json number,url,headRefName,isDraft --state open

If no PR found:

No open PR found for story #$STORY_NUMBER.
Run /impl:commit [$STORY_NUMBER] to create one first.

Stop.

PR queue = single PR found above.

PR mode (--pr N [N...]):

No phase gate -- proceed regardless of current phase.

Fetch metadata for each PR number:

gh pr view $PR_NUMBER --json number,url,headRefName,isDraft,title,body

If any PR not found, report and skip it.

PR queue = all valid PRs in the order given.

Epic mode (--epic N):

No phase gate -- proceed regardless of current phase.

Find all open PRs for this Epic:

gh pr list --search "Part of Epic #$EPIC_NUMBER" --json number,url,headRefName,isDraft,title,body --state open

Sort PRs by story dependency order (parse story dependencies from PR bodies and linked issue bodies).
PR queue = all PRs in dependency order.

0c. Extract metadata per PR

For each PR in the queue, extract from PR body:

STORY_NUMBER: parse Fixes #N if present (may be absent in PR mode)
EPIC_NUMBER: parse Part of Epic #N if present (may be absent in PR mode)

These are optional in PR mode -- steps that reference them become no-ops when absent.

0d. Process queue

For each PR in the queue, run Steps 1-8 below sequentially. Before each PR:

Checkout + pull:

git checkout $BRANCH_NAME && git pull origin $BRANCH_NAME

Initialize loop state:

CYCLE = 0
LAST_CI_FINGERPRINT = ""
LAST_REVIEW_FINGERPRINT = ""
FIX_LOG = []

Report: === Driving PR #$PR_NUMBER: $PR_TITLE ({{QUEUE_INDEX}}/{{QUEUE_SIZE}}) ===

Step 1 -- CI Check (top of loop)

Increment: CYCLE = CYCLE + 1

Report: --- Cycle $CYCLE: Checking CI ---

gh pr checks $PR_NUMBER --watch

Parse the output. If ALL checks pass -> jump to Step 3 (Review).

If checks are failing:

Build CI fingerprint: sort failing job names alphabetically, join with | Example: lint|test|typecheck
Compare to LAST_CI_FINGERPRINT
- If identical -> jump to Step 7 (STUCK)
- If different -> set LAST_CI_FINGERPRINT = new fingerprint, proceed to Step 2

Step 2 -- CI Fix

Apply fixes in priority order. For each failing job:

CI Job	Fix Action
format	`pnpm prettier --write .`
lint	`pnpm eslint . --fix && pnpm prettier --write .`
lint-md	`pnpm markdownlint --fix "*/.md"`
typecheck	`pnpm typecheck` to see errors, then apply targeted fixes
test	`pnpm test` to see failures, diagnose each, fix implementation (NEVER weaken tests)
audit	`pnpm audit --fix` then manually review remaining
build	Run all above first (build depends on all others), then `pnpm build`

Execute in this order: format -> lint -> lint-md -> typecheck -> test -> audit -> build.

2a. Pre-flight verification

After all fixes applied, run:

pnpm test && pnpm lint && pnpm typecheck

If pre-flight fails, apply additional fixes until clean.

2b. Commit and push

git add -A && git commit -m "fix(ci): resolve CI failures for PR #$PR_NUMBER (cycle $CYCLE)" && git push

Append to FIX_LOG: "Cycle $CYCLE: CI fix -- [list of jobs fixed]"

2c. Wait for CI

gh pr checks $PR_NUMBER --watch

Loop back to Step 1.

Step 3 -- Review

Report: --- Cycle $CYCLE: CI green. Running review ---

3a. Check for unresolved conversations

gh api repos/{owner}/{repo}/pulls/$PR_NUMBER/comments --jq '[.[] | select(.in_reply_to_id == null)] | length'

3b. Get PR diff

gh pr diff $PR_NUMBER

3c. Spawn 3 review agents in parallel

Use Agent tool to spawn three agents simultaneously:

workflow-reviewer -- code quality, security, financial precision, OWASP top 10
workflow-qa -- acceptance criteria coverage, edge cases, regression risk, coverage >= 80%
workflow-documentor -- CHANGELOG, ADR if applicable, STATUS.md consistency

Provide each agent with:

PR number and title
Story issue number and Epic number (if available)
The PR diff
List of changed files

Wait for ALL THREE agents to return results.

3d. Evaluate results

If all three agents return APPROVED -> jump to Step 3.5 (Conversation Resolution).

If any agent returns blockers:

Build review fingerprint: sort blockers as agent:file:description-hash, join with |
Compare to LAST_REVIEW_FINGERPRINT
- If identical -> jump to Step 7 (STUCK)
- If different -> set LAST_REVIEW_FINGERPRINT = new fingerprint, proceed to fix

3e. Fix review blockers

For each blocker:

Read the file referenced
Apply the fix described by the review agent
NEVER weaken tests or bypass checks

After all blockers fixed:

pnpm test && pnpm lint && pnpm typecheck

git add -A && git commit -m "fix(review): resolve review blockers for PR #$PR_NUMBER (cycle $CYCLE)" && git push

Append to FIX_LOG: "Cycle $CYCLE: Review fix -- [N] blockers resolved"

Loop back to Step 1 (CI first, since code changed).

Step 3.5 -- Conversation Resolution

Report: --- Checking PR conversations ---

3.5a. Check for CHANGES_REQUESTED reviews

gh api repos/{owner}/{repo}/pulls/$PR_NUMBER/reviews --jq '[.[] | select(.state == "CHANGES_REQUESTED")] | length'

3.5b. Check for unresolved comment threads

gh api repos/{owner}/{repo}/pulls/$PR_NUMBER/comments --jq '[.[] | select(.in_reply_to_id == null)] | length'

3.5c. Resolution

If unresolved threads or CHANGES_REQUESTED reviews exist:

List each thread with context
Attempt to address each finding (fix code or respond to comment)
If code changes needed: fix, commit, push, loop back to Step 1
Request re-review if CHANGES_REQUESTED was present

Gate: 0 unresolved conversations, no CHANGES_REQUESTED reviews pending.

If clean -> proceed to Step 4 (PR Clean).

Step 4 -- PR Clean

Report: --- All reviews approved. Cleaning PR ---

4a. Verify PR title (story mode only)

If STORY_NUMBER is available:

Fetch story title:

gh issue view $STORY_NUMBER --json title --jq '.title'

Compare to PR title. If mismatched:

gh pr edit $PR_NUMBER --title "$STORY_TITLE"

4b. Verify PR body (story mode only)

If STORY_NUMBER is available, PR body must contain:

Fixes #$STORY_NUMBER
Part of Epic #$EPIC_NUMBER (if EPIC_NUMBER available)
A summary section
A test plan section

If any missing, update:

gh pr edit $PR_NUMBER --body "$UPDATED_BODY"

In PR mode (no story), skip body validation.

4c. Verify labels (story mode only)

If STORY_NUMBER is available:

gh issue edit $STORY_NUMBER --add-label "in-review"

4d. Mark PR ready

gh pr ready $PR_NUMBER

Step 5 -- Merge

Report: --- Merging PR #$PR_NUMBER ---

5a. Final pre-flight

pnpm test && pnpm lint && pnpm typecheck

If fails, fix and commit (loop back to Step 1).

5b. Final CI check

gh pr checks $PR_NUMBER

If any check failing, loop back to Step 1.

5c. Squash merge

gh pr merge $PR_NUMBER --squash --delete-branch

If merge conflict:

git fetch origin main && git rebase origin/main

If rebase conflicts arise, resolve them, then:

git push --force-with-lease

Append to FIX_LOG: "Cycle $CYCLE: Resolved merge conflict via rebase"

Loop back to Step 1.

5d. Confirm story closed (story mode only)

If STORY_NUMBER is available:

gh issue view $STORY_NUMBER --json state --jq '.state'

If not CLOSED:

gh issue close $STORY_NUMBER --comment "Closed by merge of PR #$PR_NUMBER."

If no STORY_NUMBER (PR mode), skip this step.

Step 6 -- Epic Rollup (story mode only)

Skip this entire step if EPIC_NUMBER is not available (PR mode without epic metadata).

6a. Check all stories

gh issue list --label "story" --search "Part of Epic #$EPIC_NUMBER" --json number,state --state all

Count open vs closed stories.

6b. If all stories closed

gh issue comment $EPIC_NUMBER --body "All stories merged -- Epic #$EPIC_NUMBER complete."
gh issue close $EPIC_NUMBER
gh issue edit $EPIC_NUMBER --add-label "done"

Update .claude/workflow/STATUS.md:

Mark current Epic as DONE in Feature Progress table
Advance phase to Phase 4 for next Epic

6c. Auto-select next Epic

Read Feature Progress table from STATUS.md. Filter out DONE Epics. Respect dependency order (all dependencies must be DONE). Among eligible, pick highest MoSCoW priority (Must > Should > Could).

Report next Epic recommendation.

Jump to Step 8 (DONE).

Step 7 -- STUCK (terminal)

STUCK on PR #$PR_NUMBER after $CYCLE cycles.

Repeated failure fingerprint:
  CI:     $LAST_CI_FINGERPRINT
  Review: $LAST_REVIEW_FINGERPRINT

Fix log:
  [full FIX_LOG entries]

Suggested next steps:
  1. /fix:debug "[description of repeating failure]"
  2. Manual investigation of the failing area
  3. Re-run after manual fix: /pr:drive --pr $PR_NUMBER

If processing a multi-PR queue, stop the entire queue (do not continue to next PR).

Stop.

Step 8 -- DONE (terminal)

For each merged PR, report:

PR #$PR_NUMBER merged successfully.

Merge commit: [hash]
Story #$STORY_NUMBER: CLOSED  (or "N/A -- PR mode" if no story)
Epic #$EPIC_NUMBER: [DONE / N stories remaining]  (or "N/A" if no epic)

Cycles: $CYCLE
Fix log:
  [full FIX_LOG entries, or "No fixes needed" if empty]

After all PRs in the queue are merged, report summary:

All $QUEUE_SIZE PR(s) merged successfully.

  [list each PR # and merge commit]

Next:
  [If Epic done: "Epic complete. Next Epic: #N -- [Name]. Run /workflow:run [N]"]
  [If Epic not done / PR mode: "Done. No further action needed."]

Rules (non-negotiable)

Never weaken tests -- fix implementation to match tests, never modify test expectations
Never --no-verify -- fix the underlying issue instead of bypassing pre-commit hooks
New commits only -- never amend in the loop; each fix cycle gets its own commit
Force-with-lease only -- for rebase conflicts, never bare --force
No retry limit -- loop until merged or stuck; stuck detection is the safety valve
CI after review fixes -- always restart from Step 1 after any code change
Never --no-gpg-sign -- respect signing config
Conversations resolved -- never merge with unresolved PR review threads

Install pr:drive and it becomes one more candidate the router can pick - when it fits.

A listing is a routing target with a manifest: what it does, which domains it covers, what it costs and who publishes it. Once installed it sits beside your own models and tools, is scored like any other candidate for each request, and shows up in the trace when it wins. Ratings come from workspaces that installed it, one per account.

Parse the argument: Three modes: - **Story mode**: `/pr:drive [story-issue-number]` -- finds PR via `Fixes #N` search, enforces phase gate - **PR mode**: `/pr:drive --pr N [N...]` -- drives one or more PRs by number directly, no phase gate - **Epic mode**: `/pr:drive --epic [epic-#]` -- drives ALL open PRs for an Epic in dependency order If none match, ask: "Provide a story number, use --pr N [N...] for direct PR numbers, or --epic N for all Epic PRs." --- ## Step 0 -- Initialize ### 0a. Verify gh auth ```bash gh auth status ``` If not authenticated, guide user to `gh auth login` and stop. ### 0b. Build PR queue **Story mode:** 1. Phase gate: read `.claude/workflow/STATUS.md` - Phase 6 (IMPLEMENT) with an existing draft PR: proceed - Phase 7 (REVIEW): proceed - Otherwise: stop with error: ``` Error: /pr:drive requires Phase 6 (with a draft PR) or Phase 7. Current phase is [N] -- [NAME]. ``` 2. Find PR: ```bash gh pr list --search "Fixes #$STORY_NUMBER" --json number,url,headRefName,isDraft --state open ``` If no PR found: ``` No open PR found for story #$STORY_NUMBER. Run /impl:commit [$STORY_NUMBER] to create one first. ``` Stop. 3. PR queue = single PR found above. **PR mode (--pr N [N...]):** 1. No phase gate -- proceed regardless of current phase. 2. Fetch metadata for each PR number: ```bash gh pr view $PR_NUMBER --json number,url,headRefName,isDraft,title,body ``` If any PR not found, report and skip it. 3. PR queue = all valid PRs in the order given. **Epic mode (--epic N):** 1. No phase gate -- proceed regardless of current phase. 2. Find all open PRs for this Epic: ```bash gh pr list --search "Part of Epic #$EPIC_NUMBER" --json number,url,headRefName,isDraft,title,body --state open ``` 3. Sort PRs by story dependency order (parse story dependencies from PR bodies and linked issue bodies). 4. PR queue = all PRs in dependency order. ### 0c. Extract metadata per PR For each PR in the queue, extract from PR body: - `STORY_NUMBER`: parse `Fixes #N` if present (may be absent in PR mode) - `EPIC_NUMBER`: parse `Part of Epic #N` if present (may be absent in PR mode) These are optional in PR mode -- steps that reference them become no-ops when absent. ### 0d. Process queue For each PR in the queue, run **Steps 1-8** below sequentially. Before each PR: 1. Checkout + pull: ```bash git checkout $BRANCH_NAME && git pull origin $BRANCH_NAME ``` 2. Initialize loop state: ``` CYCLE = 0 LAST_CI_FINGERPRINT = "" LAST_REVIEW_FINGERPRINT = "" FIX_LOG = [] ``` 3. Report: `=== Driving PR #$PR_NUMBER: $PR_TITLE ({{QUEUE_INDEX}}/{{QUEUE_SIZE}}) ===` --- ## Step 1 -- CI Check (top of loop) Increment: `CYCLE = CYCLE + 1` Report: `--- Cycle $CYCLE: Checking CI ---` ```bash gh pr checks $PR_NUMBER --watch ``` Parse the output. If ALL checks pass -> jump to **Step 3** (Review). If checks are failing: 1. Build CI fingerprint: sort failing job names alphabetically, join with `|` Example: `lint|test|typecheck` 2. Compare to `LAST_CI_FINGERPRINT` - If identical -> jump to **Step 7** (STUCK) - If different -> set `LAST_CI_FINGERPRINT = new fingerprint`, proceed to **Step 2** --- ## Step 2 -- CI Fix Apply fixes in priority order. For each failing job: | CI Job | Fix Action | | --------- | ----------------------------------------------------------------------------------- | | format | `pnpm prettier --write .` | | lint | `pnpm eslint . --fix && pnpm prettier --write .` | | lint-md | `pnpm markdownlint --fix "**/*.md"` | | typecheck | `pnpm typecheck` to see errors, then apply targeted fixes | | test | `pnpm test` to see failures, diagnose each, fix implementation (NEVER weaken tests) | | audit | `pnpm audit --fix` then manually review remaining | | build | Run all above first (build depends on all others), then `pnpm build` | Execute in this order: format -> lint -> lint-md -> typecheck -> test -> audit -> build. ### 2a. Pre-flight verification After all fixes applied, run: ```bash pnpm test && pnpm lint && pnpm typecheck ``` If pre-flight fails, apply additional fixes until clean. ### 2b. Commit and push ```bash git add -A && git commit -m "fix(ci): resolve CI failures for PR #$PR_NUMBER (cycle $CYCLE)" && git push ``` Append to `FIX_LOG`: `"Cycle $CYCLE: CI fix -- [list of jobs fixed]"` ### 2c. Wait for CI ```bash gh pr checks $PR_NUMBER --watch ``` Loop back to **Step 1**. --- ## Step 3 -- Review Report: `--- Cycle $CYCLE: CI green. Running review ---` ### 3a. Check for unresolved conversations ```bash gh api repos/{owner}/{repo}/pulls/$PR_NUMBER/comments --jq '[.[] | select(.in_reply_to_id == null)] | length' ``` ### 3b. Get PR diff ```bash gh pr diff $PR_NUMBER ``` ### 3c. Spawn 3 review agents in parallel Use Agent tool to spawn three agents simultaneously: 1. **workflow-reviewer** -- code quality, security, financial precision, OWASP top 10 2. **workflow-qa** -- acceptance criteria coverage, edge cases, regression risk, coverage >= 80% 3. **workflow-documentor** -- CHANGELOG, ADR if applicable, STATUS.md consistency Provide each agent with: - PR number and title - Story issue number and Epic number (if available) - The PR diff - List of changed files Wait for ALL THREE agents to return results. ### 3d. Evaluate results If all three agents return APPROVED -> jump to **Step 3.5** (Conversation Resolution). If any agent returns blockers: 1. Build review fingerprint: sort blockers as `agent:file:description-hash`, join with `|` 2. Compare to `LAST_REVIEW_FINGERPRINT` - If identical -> jump to **Step 7** (STUCK) - If different -> set `LAST_REVIEW_FINGERPRINT = new fingerprint`, proceed to fix ### 3e. Fix review blockers For each blocker: - Read the file referenced - Apply the fix described by the review agent - NEVER weaken tests or bypass checks After all blockers fixed: ```bash pnpm test && pnpm lint && pnpm typecheck ``` ```bash git add -A && git commit -m "fix(review): resolve review blockers for PR #$PR_NUMBER (cycle $CYCLE)" && git push ``` Append to `FIX_LOG`: `"Cycle $CYCLE: Review fix -- [N] blockers resolved"` Loop back to **Step 1** (CI first, since code changed). --- ## Step 3.5 -- Conversation Resolution Report: `--- Checking PR conversations ---` ### 3.5a. Check for CHANGES_REQUESTED reviews ```bash gh api repos/{owner}/{repo}/pulls/$PR_NUMBER/reviews --jq '[.[] | select(.state == "CHANGES_REQUESTED")] | length' ``` ### 3.5b. Check for unresolved comment threads ```bash gh api repos/{owner}/{repo}/pulls/$PR_NUMBER/comments --jq '[.[] | select(.in_reply_to_id == null)] | length' ``` ### 3.5c. Resolution If unresolved threads or CHANGES_REQUESTED reviews exist: 1. List each thread with context 2. Attempt to address each finding (fix code or respond to comment) 3. If code changes needed: fix, commit, push, loop back to **Step 1** 4. Request re-review if CHANGES_REQUESTED was present Gate: 0 unresolved conversations, no CHANGES_REQUESTED reviews pending. If clean -> proceed to **Step 4** (PR Clean). --- ## Step 4 -- PR Clean Report: `--- All reviews approved. Cleaning PR ---` ### 4a. Verify PR title (story mode only) If `STORY_NUMBER` is available: Fetch story title: ```bash gh issue view $STORY_NUMBER --json title --jq '.title' ``` Compare to PR title. If mismatched: ```bash gh pr edit $PR_NUMBER --title "$STORY_TITLE" ``` ### 4b. Verify PR body (story mode only) If `STORY_NUMBER` is available, PR body must contain: - `Fixes #$STORY_NUMBER` - `Part of Epic #$EPIC_NUMBER` (if `EPIC_NUMBER` available) - A summary section - A test plan section If any missing, update: ```bash gh pr edit $PR_NUMBER --body "$UPDATED_BODY" ``` In PR mode (no story), skip body validation. ### 4c. Verify labels (story mode only) If `STORY_NUMBER` is available: ```bash gh issue edit $STORY_NUMBER --add-label "in-review" ``` ### 4d. Mark PR ready ```bash gh pr ready $PR_NUMBER ``` --- ## Step 5 -- Merge Report: `--- Merging PR #$PR_NUMBER ---` ### 5a. Final pre-flight ```bash pnpm test && pnpm lint && pnpm typecheck ``` If fails, fix and commit (loop back to **Step 1**). ### 5b. Final CI check ```bash gh pr checks $PR_NUMBER ``` If any check failing, loop back to **Step 1**. ### 5c. Squash merge ```bash gh pr merge $PR_NUMBER --squash --delete-branch ``` If merge conflict: ```bash git fetch origin main && git rebase origin/main ``` If rebase conflicts arise, resolve them, then: ```bash git push --force-with-lease ``` Append to `FIX_LOG`: `"Cycle $CYCLE: Resolved merge conflict via rebase"` Loop back to **Step 1**. ### 5d. Confirm story closed (story mode only) If `STORY_NUMBER` is available: ```bash gh issue view $STORY_NUMBER --json state --jq '.state' ``` If not CLOSED: ```bash gh issue close $STORY_NUMBER --comment "Closed by merge of PR #$PR_NUMBER." ``` If no `STORY_NUMBER` (PR mode), skip this step. --- ## Step 6 -- Epic Rollup (story mode only) Skip this entire step if `EPIC_NUMBER` is not available (PR mode without epic metadata). ### 6a. Check all stories ```bash gh issue list --label "story" --search "Part of Epic #$EPIC_NUMBER" --json number,state --state all ``` Count open vs closed stories. ### 6b. If all stories closed ```bash gh issue comment $EPIC_NUMBER --body "All stories merged -- Epic #$EPIC_NUMBER complete." gh issue close $EPIC_NUMBER gh issue edit $EPIC_NUMBER --add-label "done" ``` Update `.claude/workflow/STATUS.md`: - Mark current Epic as DONE in Feature Progress table - Advance phase to Phase 4 for next Epic ### 6c. Auto-select next Epic Read Feature Progress table from STATUS.md. Filter out DONE Epics. Respect dependency order (all dependencies must be DONE). Among eligible, pick highest MoSCoW priority (Must > Should > Could). Report next Epic recommendation. Jump to **Step 8** (DONE). --- ## Step 7 -- STUCK (terminal) ``` STUCK on PR #$PR_NUMBER after $CYCLE cycles. Repeated failure fingerprint: CI: $LAST_CI_FINGERPRINT Review: $LAST_REVIEW_FINGERPRINT Fix log: [full FIX_LOG entries] Suggested next steps: 1. /fix:debug "[description of repeating failure]" 2. Manual investigation of the failing area 3. Re-run after manual fix: /pr:drive --pr $PR_NUMBER ``` If processing a multi-PR queue, stop the entire queue (do not continue to next PR). Stop. --- ## Step 8 -- DONE (terminal) For each merged PR, report: ``` PR #$PR_NUMBER merged successfully. Merge commit: [hash] Story #$STORY_NUMBER: CLOSED (or "N/A -- PR mode" if no story) Epic #$EPIC_NUMBER: [DONE / N stories remaining] (or "N/A" if no epic) Cycles: $CYCLE Fix log: [full FIX_LOG entries, or "No fixes needed" if empty] ``` After all PRs in the queue are merged, report summary: ``` All $QUEUE_SIZE PR(s) merged successfully. [list each PR # and merge commit] Next: [If Epic done: "Epic complete. Next Epic: #N -- [Name]. Run /workflow:run [N]"] [If Epic not done / PR mode: "Done. No further action needed."] ``` --- ## Rules (non-negotiable) 1. **Never weaken tests** -- fix implementation to match tests, never modify test expectations 2. **Never `--no-verify`** -- fix the underlying issue instead of bypassing pre-commit hooks 3. **New commits only** -- never amend in the loop; each fix cycle gets its own commit 4. **Force-with-lease only** -- for rebase conflicts, never bare `--force` 5. **No retry limit** -- loop until merged or stuck; stuck detection is the safety valve 6. **CI after review fixes** -- always restart from Step 1 after any code change 7. **Never `--no-gpg-sign`** -- respect signing config 8. **Conversations resolved** -- never merge with unresolved PR review threads

{ "prompt": "Parse the argument:\n\nThree modes:\n\n- **Story mode**: `/pr:drive [story-issue-number]` -- finds PR via `Fixes #N` search, enforces phase gate\n- **PR mode**: `/pr:drive --pr N [N...]` -- drives one or more PRs by number directly, no phase gate\n- **Epic mode**: `/pr:drive --epic [epic-#]` -- drives ALL open PRs for an Epic in dependency order\n\nIf none match, ask: \"Provide a story number, use --pr N [N...] for direct PR numbers, or --epic N for all Epic PRs.\"\n\n---\n\n## Step 0 -- Initialize\n\n### 0a. Verify gh auth\n\n```bash\ngh auth status\n```\n\nIf not authenticated, guide user to `gh auth login` and stop.\n\n### 0b. Build PR queue\n\n**Story mode:**\n\n1. Phase gate: read `.claude/workflow/STATUS.md`\n - Phase 6 (IMPLEMENT) with an existing draft PR: proceed\n - Phase 7 (REVIEW): proceed\n - Otherwise: stop with error:\n ```\n Error: /pr:drive requires Phase 6 (with a draft PR) or Phase 7.\n Current phase is [N] -- [NAME].\n ```\n\n2. Find PR:\n\n ```bash\n gh pr list --search \"Fixes #$STORY_NUMBER\" --json number,url,headRefName,isDraft --state open\n ```\n\n If no PR found:\n\n ```\n No open PR found for story #$STORY_NUMBER.\n Run /impl:commit [$STORY_NUMBER] to create one first.\n ```\n\n Stop.\n\n3. PR queue = single PR found above.\n\n**PR mode (--pr N [N...]):**\n\n1. No phase gate -- proceed regardless of current phase.\n\n2. Fetch metadata for each PR number:\n\n ```bash\n gh pr view $PR_NUMBER --json number,url,headRefName,isDraft,title,body\n ```\n\n If any PR not found, report and skip it.\n\n3. PR queue = all valid PRs in the order given.\n\n**Epic mode (--epic N):**\n\n1. No phase gate -- proceed regardless of current phase.\n\n2. Find all open PRs for this Epic:\n\n ```bash\n gh pr list --search \"Part of Epic #$EPIC_NUMBER\" --json number,url,headRefName,isDraft,title,body --state open\n ```\n\n3. Sort PRs by story dependency order (parse story dependencies from PR bodies and linked issue bodies).\n\n4. PR queue = all PRs in dependency order.\n\n### 0c. Extract metadata per PR\n\nFor each PR in the queue, extract from PR body:\n\n- `STORY_NUMBER`: parse `Fixes #N` if present (may be absent in PR mode)\n- `EPIC_NUMBER`: parse `Part of Epic #N` if present (may be absent in PR mode)\n\nThese are optional in PR mode -- steps that reference them become no-ops when absent.\n\n### 0d. Process queue\n\nFor each PR in the queue, run **Steps 1-8** below sequentially.\nBefore each PR:\n\n1. Checkout + pull:\n\n ```bash\n git checkout $BRANCH_NAME && git pull origin $BRANCH_NAME\n ```\n\n2. Initialize loop state:\n\n ```\n CYCLE = 0\n LAST_CI_FINGERPRINT = \"\"\n LAST_REVIEW_FINGERPRINT = \"\"\n FIX_LOG = []\n ```\n\n3. Report: `=== Driving PR #$PR_NUMBER: $PR_TITLE ({{QUEUE_INDEX}}/{{QUEUE_SIZE}}) ===`\n\n---\n\n## Step 1 -- CI Check (top of loop)\n\nIncrement: `CYCLE = CYCLE + 1`\n\nReport: `--- Cycle $CYCLE: Checking CI ---`\n\n```bash\ngh pr checks $PR_NUMBER --watch\n```\n\nParse the output. If ALL checks pass -> jump to **Step 3** (Review).\n\nIf checks are failing:\n\n1. Build CI fingerprint: sort failing job names alphabetically, join with `|`\n Example: `lint|test|typecheck`\n2. Compare to `LAST_CI_FINGERPRINT`\n - If identical -> jump to **Step 7** (STUCK)\n - If different -> set `LAST_CI_FINGERPRINT = new fingerprint`, proceed to **Step 2**\n\n---\n\n## Step 2 -- CI Fix\n\nApply fixes in priority order. For each failing job:\n\n| CI Job | Fix Action |\n| --------- | ----------------------------------------------------------------------------------- |\n| format | `pnpm prettier --write .` |\n| lint | `pnpm eslint . --fix && pnpm prettier --write .` |\n| lint-md | `pnpm markdownlint --fix \"**/*.md\"` |\n| typecheck | `pnpm typecheck` to see errors, then apply targeted fixes |\n| test | `pnpm test` to see failures, diagnose each, fix implementation (NEVER weaken tests) |\n| audit | `pnpm audit --fix` then manually review remaining |\n| build | Run all above first (build depends on all others), then `pnpm build` |\n\nExecute in this order: format -> lint -> lint-md -> typecheck -> test -> audit -> build.\n\n### 2a. Pre-flight verification\n\nAfter all fixes applied, run:\n\n```bash\npnpm test && pnpm lint && pnpm typecheck\n```\n\nIf pre-flight fails, apply additional fixes until clean.\n\n### 2b. Commit and push\n\n```bash\ngit add -A && git commit -m \"fix(ci): resolve CI failures for PR #$PR_NUMBER (cycle $CYCLE)\" && git push\n```\n\nAppend to `FIX_LOG`: `\"Cycle $CYCLE: CI fix -- [list of jobs fixed]\"`\n\n### 2c. Wait for CI\n\n```bash\ngh pr checks $PR_NUMBER --watch\n```\n\nLoop back to **Step 1**.\n\n---\n\n## Step 3 -- Review\n\nReport: `--- Cycle $CYCLE: CI green. Running review ---`\n\n### 3a. Check for unresolved conversations\n\n```bash\ngh api repos/{owner}/{repo}/pulls/$PR_NUMBER/comments --jq '[.[] | select(.in_reply_to_id == null)] | length'\n```\n\n### 3b. Get PR diff\n\n```bash\ngh pr diff $PR_NUMBER\n```\n\n### 3c. Spawn 3 review agents in parallel\n\nUse Agent tool to spawn three agents simultaneously:\n\n1. **workflow-reviewer** -- code quality, security, financial precision, OWASP top 10\n2. **workflow-qa** -- acceptance criteria coverage, edge cases, regression risk, coverage >= 80%\n3. **workflow-documentor** -- CHANGELOG, ADR if applicable, STATUS.md consistency\n\nProvide each agent with:\n\n- PR number and title\n- Story issue number and Epic number (if available)\n- The PR diff\n- List of changed files\n\nWait for ALL THREE agents to return results.\n\n### 3d. Evaluate results\n\nIf all three agents return APPROVED -> jump to **Step 3.5** (Conversation Resolution).\n\nIf any agent returns blockers:\n\n1. Build review fingerprint: sort blockers as `agent:file:description-hash`, join with `|`\n2. Compare to `LAST_REVIEW_FINGERPRINT`\n - If identical -> jump to **Step 7** (STUCK)\n - If different -> set `LAST_REVIEW_FINGERPRINT = new fingerprint`, proceed to fix\n\n### 3e. Fix review blockers\n\nFor each blocker:\n\n- Read the file referenced\n- Apply the fix described by the review agent\n- NEVER weaken tests or bypass checks\n\nAfter all blockers fixed:\n\n```bash\npnpm test && pnpm lint && pnpm typecheck\n```\n\n```bash\ngit add -A && git commit -m \"fix(review): resolve review blockers for PR #$PR_NUMBER (cycle $CYCLE)\" && git push\n```\n\nAppend to `FIX_LOG`: `\"Cycle $CYCLE: Review fix -- [N] blockers resolved\"`\n\nLoop back to **Step 1** (CI first, since code changed).\n\n---\n\n## Step 3.5 -- Conversation Resolution\n\nReport: `--- Checking PR conversations ---`\n\n### 3.5a. Check for CHANGES_REQUESTED reviews\n\n```bash\ngh api repos/{owner}/{repo}/pulls/$PR_NUMBER/reviews --jq '[.[] | select(.state == \"CHANGES_REQUESTED\")] | length'\n```\n\n### 3.5b. Check for unresolved comment threads\n\n```bash\ngh api repos/{owner}/{repo}/pulls/$PR_NUMBER/comments --jq '[.[] | select(.in_reply_to_id == null)] | length'\n```\n\n### 3.5c. Resolution\n\nIf unresolved threads or CHANGES_REQUESTED reviews exist:\n\n1. List each thread with context\n2. Attempt to address each finding (fix code or respond to comment)\n3. If code changes needed: fix, commit, push, loop back to **Step 1**\n4. Request re-review if CHANGES_REQUESTED was present\n\nGate: 0 unresolved conversations, no CHANGES_REQUESTED reviews pending.\n\nIf clean -> proceed to **Step 4** (PR Clean).\n\n---\n\n## Step 4 -- PR Clean\n\nReport: `--- All reviews approved. Cleaning PR ---`\n\n### 4a. Verify PR title (story mode only)\n\nIf `STORY_NUMBER` is available:\n\nFetch story title:\n\n```bash\ngh issue view $STORY_NUMBER --json title --jq '.title'\n```\n\nCompare to PR title. If mismatched:\n\n```bash\ngh pr edit $PR_NUMBER --title \"$STORY_TITLE\"\n```\n\n### 4b. Verify PR body (story mode only)\n\nIf `STORY_NUMBER` is available, PR body must contain:\n\n- `Fixes #$STORY_NUMBER`\n- `Part of Epic #$EPIC_NUMBER` (if `EPIC_NUMBER` available)\n- A summary section\n- A test plan section\n\nIf any missing, update:\n\n```bash\ngh pr edit $PR_NUMBER --body \"$UPDATED_BODY\"\n```\n\nIn PR mode (no story), skip body validation.\n\n### 4c. Verify labels (story mode only)\n\nIf `STORY_NUMBER` is available:\n\n```bash\ngh issue edit $STORY_NUMBER --add-label \"in-review\"\n```\n\n### 4d. Mark PR ready\n\n```bash\ngh pr ready $PR_NUMBER\n```\n\n---\n\n## Step 5 -- Merge\n\nReport: `--- Merging PR #$PR_NUMBER ---`\n\n### 5a. Final pre-flight\n\n```bash\npnpm test && pnpm lint && pnpm typecheck\n```\n\nIf fails, fix and commit (loop back to **Step 1**).\n\n### 5b. Final CI check\n\n```bash\ngh pr checks $PR_NUMBER\n```\n\nIf any check failing, loop back to **Step 1**.\n\n### 5c. Squash merge\n\n```bash\ngh pr merge $PR_NUMBER --squash --delete-branch\n```\n\nIf merge conflict:\n\n```bash\ngit fetch origin main && git rebase origin/main\n```\n\nIf rebase conflicts arise, resolve them, then:\n\n```bash\ngit push --force-with-lease\n```\n\nAppend to `FIX_LOG`: `\"Cycle $CYCLE: Resolved merge conflict via rebase\"`\n\nLoop back to **Step 1**.\n\n### 5d. Confirm story closed (story mode only)\n\nIf `STORY_NUMBER` is available:\n\n```bash\ngh issue view $STORY_NUMBER --json state --jq '.state'\n```\n\nIf not CLOSED:\n\n```bash\ngh issue close $STORY_NUMBER --comment \"Closed by merge of PR #$PR_NUMBER.\"\n```\n\nIf no `STORY_NUMBER` (PR mode), skip this step.\n\n---\n\n## Step 6 -- Epic Rollup (story mode only)\n\nSkip this entire step if `EPIC_NUMBER` is not available (PR mode without epic metadata).\n\n### 6a. Check all stories\n\n```bash\ngh issue list --label \"story\" --search \"Part of Epic #$EPIC_NUMBER\" --json number,state --state all\n```\n\nCount open vs closed stories.\n\n### 6b. If all stories closed\n\n```bash\ngh issue comment $EPIC_NUMBER --body \"All stories merged -- Epic #$EPIC_NUMBER complete.\"\ngh issue close $EPIC_NUMBER\ngh issue edit $EPIC_NUMBER --add-label \"done\"\n```\n\nUpdate `.claude/workflow/STATUS.md`:\n\n- Mark current Epic as DONE in Feature Progress table\n- Advance phase to Phase 4 for next Epic\n\n### 6c. Auto-select next Epic\n\nRead Feature Progress table from STATUS.md. Filter out DONE Epics.\nRespect dependency order (all dependencies must be DONE).\nAmong eligible, pick highest MoSCoW priority (Must > Should > Could).\n\nReport next Epic recommendation.\n\nJump to **Step 8** (DONE).\n\n---\n\n## Step 7 -- STUCK (terminal)\n\n```\nSTUCK on PR #$PR_NUMBER after $CYCLE cycles.\n\nRepeated failure fingerprint:\n CI: $LAST_CI_FINGERPRINT\n Review: $LAST_REVIEW_FINGERPRINT\n\nFix log:\n [full FIX_LOG entries]\n\nSuggested next steps:\n 1. /fix:debug \"[description of repeating failure]\"\n 2. Manual investigation of the failing area\n 3. Re-run after manual fix: /pr:drive --pr $PR_NUMBER\n```\n\nIf processing a multi-PR queue, stop the entire queue (do not continue to next PR).\n\nStop.\n\n---\n\n## Step 8 -- DONE (terminal)\n\nFor each merged PR, report:\n\n```\nPR #$PR_NUMBER merged successfully.\n\nMerge commit: [hash]\nStory #$STORY_NUMBER: CLOSED (or \"N/A -- PR mode\" if no story)\nEpic #$EPIC_NUMBER: [DONE / N stories remaining] (or \"N/A\" if no epic)\n\nCycles: $CYCLE\nFix log:\n [full FIX_LOG entries, or \"No fixes needed\" if empty]\n```\n\nAfter all PRs in the queue are merged, report summary:\n\n```\nAll $QUEUE_SIZE PR(s) merged successfully.\n\n [list each PR # and merge commit]\n\nNext:\n [If Epic done: \"Epic complete. Next Epic: #N -- [Name]. Run /workflow:run [N]\"]\n [If Epic not done / PR mode: \"Done. No further action needed.\"]\n```\n\n---\n\n## Rules (non-negotiable)\n\n1. **Never weaken tests** -- fix implementation to match tests, never modify test expectations\n2. **Never `--no-verify`** -- fix the underlying issue instead of bypassing pre-commit hooks\n3. **New commits only** -- never amend in the loop; each fix cycle gets its own commit\n4. **Force-with-lease only** -- for rebase conflicts, never bare `--force`\n5. **No retry limit** -- loop until merged or stuck; stuck detection is the safety valve\n6. **CI after review fixes** -- always restart from Step 1 after any code change\n7. **Never `--no-gpg-sign`** -- respect signing config\n8. **Conversations resolved** -- never merge with unresolved PR review threads", "variables": [ "QUEUE_INDEX", "QUEUE_SIZE" ], "notes": "Autonomous PR driver. Takes one or more PRs and loops each until merged: CI check -> fix -> review agents -> conversation resolution -> fix blockers -> retry. Stuck detection stops after 2 consecutive identical error fingerprints. Supports --epic flag to drive all PRs for an Epic in dependency order. Usage - /pr:drive [story-#] or /pr:drive --pr N [N...] or /pr:drive --epic [epic-#] Tools: Bash, Read, Edit, Agent, TeamCreate, Skill. Arguments: [story-# or --pr N [N...] or --epic [epic-#]].", "metadata": { "source": { "provider": "github-codex-prompts", "repository": "https://github.com/helalifaker/budfin", "path": ".codex/prompts/pr.drive.md", "ref": "0ae459d12324d9c929baa7b09f783f5bc53911c6", "url": "https://github.com/helalifaker/budfin/blob/0ae459d12324d9c929baa7b09f783f5bc53911c6/.codex/prompts/pr.drive.md", "key": "helalifaker/budfin/.codex/prompts/pr.drive.md" } } }

About

Step 0 -- Initialize

0a. Verify gh auth

0b. Build PR queue

0c. Extract metadata per PR

0d. Process queue

Step 1 -- CI Check (top of loop)

Step 2 -- CI Fix

2a. Pre-flight verification

2b. Commit and push

2c. Wait for CI

Step 3 -- Review

3a. Check for unresolved conversations

3b. Get PR diff

3c. Spawn 3 review agents in parallel

3d. Evaluate results

3e. Fix review blockers

Step 3.5 -- Conversation Resolution

3.5a. Check for CHANGES_REQUESTED reviews

3.5b. Check for unresolved comment threads

3.5c. Resolution

Step 4 -- PR Clean

4a. Verify PR title (story mode only)

4b. Verify PR body (story mode only)

4c. Verify labels (story mode only)

4d. Mark PR ready

Step 5 -- Merge

5a. Final pre-flight

5b. Final CI check

5c. Squash merge

5d. Confirm story closed (story mode only)

Step 6 -- Epic Rollup (story mode only)

6a. Check all stories

6b. If all stories closed

6c. Auto-select next Epic

Step 7 -- STUCK (terminal)

Step 8 -- DONE (terminal)

Rules (non-negotiable)

Install pr:drive and it becomes one more candidate the router can pick - when it fits.

What it costs to adopt - in engineering time.

One base URL

No vendor lock-in

Failover built in

Use it

Manifest

Reviews