forge-workflow 0.0.8 → 0.0.9

package/.claude/commands/premerge.md

@@ -94,7 +94,7 @@ git commit -m "docs: update documentation for <feature-name>
 git push
 ```
 
-⚠️  **After pushing**: CI will re-trigger (Greptile, SonarCloud, etc.). Wait for checks to pass. If new Greptile comments appear on the doc changes, run `/review <pr-number>` again.
+⚠️  **After pushing**: CI will re-trigger (Greptile, SonarCloud, etc.). Poll for up to 60 seconds. If checks are still pending after that, stop and ask the user to return to `/premerge <pr-number>` later. If new Greptile comments appear on the doc changes, run `/review <pr-number>` again.
 
 ### Step 4: Sync Beads
 
@@ -153,7 +153,7 @@ Do NOT suggest merging.
   - README.md: Features list updated
   - CLAUDE.md: USER section updated with new pattern
   - Committed: docs: update documentation for auth-refresh
-✓ CI re-triggered after doc push — all checks still passing
+✓ CI re-triggered after doc push — checks passed within the 60 second poll window
 ✓ Beads synced
 
 ✅ PR #89 is ready to merge

package/.claude/commands/review.md

@@ -298,10 +298,13 @@ git push
 ### Step 9: Verify ALL Checks Pass
 
 ```bash
-# Wait for checks to complete
+# Check status immediately, then poll for at most 60 seconds
 gh pr checks <pr-number>
 
-# Ensure all status checks are green:
+# If checks are still pending after 60 seconds: STOP and tell the user to return
+# when CI finishes or new review feedback appears.
+#
+# Ensure all completed status checks are green:
 # ✓ GitHub Actions workflows
 # ✓ Greptile review (no unresolved critical comments)
 # ✓ SonarCloud quality gate

package/.claude/commands/ship.md

@@ -184,9 +184,10 @@ bash scripts/forge-team/index.sh verify 2>&1 || true
   - Beads linked: forge-xyz
   - Implementation details in collapsible section
 
-⏸️  PR created, awaiting automated checks (Greptile, SonarCloud, GitHub Actions)
+⏸️  PR created, checks started (Greptile, SonarCloud, GitHub Actions)
+   Poll for up to 60 seconds. If checks are still pending, stop here.
 
-Next: /review <pr-number> (after automated checks complete)
+Next: /review <pr-number> (when automated checks complete or new feedback appears)
 ```
 
 ## Integration with Workflow
@@ -208,5 +209,5 @@ Stage 7: /verify     → Post-merge CI check on main
 - **Fill every section**: Even if "N/A" — empty/missing sections cause review friction
 - **Include "Closes beads-xxx"**: Required for auto-close in /verify
 - **Concrete data only**: Test counts, file paths, commit SHAs — not placeholder text
-- **Wait for checks**: Let GitHub Actions, Greptile, SonarCloud run
+- **Poll briefly, then stop**: Check PR status for up to 60 seconds, then hand off if checks are still pending
 - **NO auto-merge**: Always wait for /review phase

package/.claude/rules/greptile-review-process.md

@@ -131,7 +131,7 @@ bash .claude/scripts/greptile-resolve.sh stats <pr-number>
 
 **Should show**: "✓ All Greptile threads resolved!"
 
-### Step 4: Push Changes & Wait for Re-review
+### Step 4: Push Changes & Poll Briefly for Re-review
 
 ```bash
 git push
@@ -188,7 +188,7 @@ $ git push
 - **Reply to EACH comment thread** using the script (not as separate PR comment)
 - **Mark EACH thread as resolved** after fixing using the script
 - **Track progress** (X of Y fixed) in your notes
-- **Wait for Greptile re-review** after pushing fixes
+- **Poll for Greptile re-review for at most 60 seconds** after pushing fixes, then stop and hand off if it is still pending
 - **Use comment ID for replies**, thread ID for resolving
 - **Commit fixes BEFORE replying** so you can reference commit SHA
 
@@ -251,7 +251,7 @@ The `/review` command should now include these steps:
    - Fix each issue
    - Reply and resolve systematically
 3. Verify all threads resolved before declaring review complete
-4. Push changes and wait for Greptile re-review
+4. Push changes and poll briefly for Greptile re-review
 
 ---
 
@@ -271,7 +271,7 @@ The `/review` command should now include these steps:
 
 ### Greptile score not updating after fixes
 **Cause**: Must push commits to trigger re-analysis
-**Solution**: `git push` and wait 2-3 minutes for Greptile re-scan
+**Solution**: `git push`, check once immediately, and poll for up to 60 seconds. If Greptile is still pending after that, stop and wait for the user to resume later.
 
 ---
 

package/.cline/workflows/premerge.md

@@ -91,7 +91,7 @@ git commit -m "docs: update documentation for <feature-name>
 git push
 ```
 
-⚠️  **After pushing**: CI will re-trigger (Greptile, SonarCloud, etc.). Wait for checks to pass. If new Greptile comments appear on the doc changes, run `/review <pr-number>` again.
+⚠️  **After pushing**: CI will re-trigger (Greptile, SonarCloud, etc.). Poll for up to 60 seconds. If checks are still pending after that, stop and ask the user to return to `/premerge <pr-number>` later. If new Greptile comments appear on the doc changes, run `/review <pr-number>` again.
 
 ### Step 4: Sync Beads
 
@@ -150,7 +150,7 @@ Do NOT suggest merging.
   - README.md: Features list updated
   - CLAUDE.md: USER section updated with new pattern
   - Committed: docs: update documentation for auth-refresh
-✓ CI re-triggered after doc push — all checks still passing
+✓ CI re-triggered after doc push — checks passed within the 60 second poll window
 ✓ Beads synced
 
 ✅ PR #89 is ready to merge

package/.cline/workflows/review.md

@@ -295,10 +295,13 @@ git push
 ### Step 9: Verify ALL Checks Pass
 
 ```bash
-# Wait for checks to complete
+# Check status immediately, then poll for at most 60 seconds
 gh pr checks <pr-number>
 
-# Ensure all status checks are green:
+# If checks are still pending after 60 seconds: STOP and tell the user to return
+# when CI finishes or new review feedback appears.
+#
+# Ensure all completed status checks are green:
 # ✓ GitHub Actions workflows
 # ✓ Greptile review (no unresolved critical comments)
 # ✓ SonarCloud quality gate

package/.cline/workflows/ship.md

@@ -181,9 +181,10 @@ bash scripts/forge-team/index.sh verify 2>&1 || true
   - Beads linked: forge-xyz
   - Implementation details in collapsible section
 
-⏸️  PR created, awaiting automated checks (Greptile, SonarCloud, GitHub Actions)
+⏸️  PR created, checks started (Greptile, SonarCloud, GitHub Actions)
+   Poll for up to 60 seconds. If checks are still pending, stop here.
 
-Next: /review <pr-number> (after automated checks complete)
+Next: /review <pr-number> (when automated checks complete or new feedback appears)
 ```
 
 ## Integration with Workflow
@@ -205,5 +206,5 @@ Stage 7: /verify     → Post-merge CI check on main
 - **Fill every section**: Even if "N/A" — empty/missing sections cause review friction
 - **Include "Closes beads-xxx"**: Required for auto-close in /verify
 - **Concrete data only**: Test counts, file paths, commit SHAs — not placeholder text
-- **Wait for checks**: Let GitHub Actions, Greptile, SonarCloud run
+- **Poll briefly, then stop**: Check PR status for up to 60 seconds, then hand off if checks are still pending
 - **NO auto-merge**: Always wait for /review phase

package/.codex/skills/premerge/SKILL.md

@@ -94,7 +94,7 @@ git commit -m "docs: update documentation for <feature-name>
 git push
 ```
 
-⚠️  **After pushing**: CI will re-trigger (Greptile, SonarCloud, etc.). Wait for checks to pass. If new Greptile comments appear on the doc changes, run `/review <pr-number>` again.
+⚠️  **After pushing**: CI will re-trigger (Greptile, SonarCloud, etc.). Poll for up to 60 seconds. If checks are still pending after that, stop and ask the user to return to `/premerge <pr-number>` later. If new Greptile comments appear on the doc changes, run `/review <pr-number>` again.
 
 ### Step 4: Sync Beads
 
@@ -153,7 +153,7 @@ Do NOT suggest merging.
   - README.md: Features list updated
   - CLAUDE.md: USER section updated with new pattern
   - Committed: docs: update documentation for auth-refresh
-✓ CI re-triggered after doc push — all checks still passing
+✓ CI re-triggered after doc push — checks passed within the 60 second poll window
 ✓ Beads synced
 
 ✅ PR #89 is ready to merge

package/.codex/skills/review/SKILL.md

@@ -298,10 +298,13 @@ git push
 ### Step 9: Verify ALL Checks Pass
 
 ```bash
-# Wait for checks to complete
+# Check status immediately, then poll for at most 60 seconds
 gh pr checks <pr-number>
 
-# Ensure all status checks are green:
+# If checks are still pending after 60 seconds: STOP and tell the user to return
+# when CI finishes or new review feedback appears.
+#
+# Ensure all completed status checks are green:
 # ✓ GitHub Actions workflows
 # ✓ Greptile review (no unresolved critical comments)
 # ✓ SonarCloud quality gate

package/.codex/skills/ship/SKILL.md

@@ -184,9 +184,10 @@ bash scripts/forge-team/index.sh verify 2>&1 || true
   - Beads linked: forge-xyz
   - Implementation details in collapsible section
 
-⏸️  PR created, awaiting automated checks (Greptile, SonarCloud, GitHub Actions)
+⏸️  PR created, checks started (Greptile, SonarCloud, GitHub Actions)
+   Poll for up to 60 seconds. If checks are still pending, stop here.
 
-Next: /review <pr-number> (after automated checks complete)
+Next: /review <pr-number> (when automated checks complete or new feedback appears)
 ```
 
 ## Integration with Workflow
@@ -208,5 +209,5 @@ Stage 7: /verify     → Post-merge CI check on main
 - **Fill every section**: Even if "N/A" — empty/missing sections cause review friction
 - **Include "Closes beads-xxx"**: Required for auto-close in /verify
 - **Concrete data only**: Test counts, file paths, commit SHAs — not placeholder text
-- **Wait for checks**: Let GitHub Actions, Greptile, SonarCloud run
+- **Poll briefly, then stop**: Check PR status for up to 60 seconds, then hand off if checks are still pending
 - **NO auto-merge**: Always wait for /review phase

package/.cursor/commands/premerge.md

@@ -91,7 +91,7 @@ git commit -m "docs: update documentation for <feature-name>
 git push
 ```
 
-⚠️  **After pushing**: CI will re-trigger (Greptile, SonarCloud, etc.). Wait for checks to pass. If new Greptile comments appear on the doc changes, run `/review <pr-number>` again.
+⚠️  **After pushing**: CI will re-trigger (Greptile, SonarCloud, etc.). Poll for up to 60 seconds. If checks are still pending after that, stop and ask the user to return to `/premerge <pr-number>` later. If new Greptile comments appear on the doc changes, run `/review <pr-number>` again.
 
 ### Step 4: Sync Beads
 
@@ -150,7 +150,7 @@ Do NOT suggest merging.
   - README.md: Features list updated
   - CLAUDE.md: USER section updated with new pattern
   - Committed: docs: update documentation for auth-refresh
-✓ CI re-triggered after doc push — all checks still passing
+✓ CI re-triggered after doc push — checks passed within the 60 second poll window
 ✓ Beads synced
 
 ✅ PR #89 is ready to merge

package/.cursor/commands/review.md

@@ -295,10 +295,13 @@ git push
 ### Step 9: Verify ALL Checks Pass
 
 ```bash
-# Wait for checks to complete
+# Check status immediately, then poll for at most 60 seconds
 gh pr checks <pr-number>
 
-# Ensure all status checks are green:
+# If checks are still pending after 60 seconds: STOP and tell the user to return
+# when CI finishes or new review feedback appears.
+#
+# Ensure all completed status checks are green:
 # ✓ GitHub Actions workflows
 # ✓ Greptile review (no unresolved critical comments)
 # ✓ SonarCloud quality gate

package/.cursor/commands/ship.md

@@ -181,9 +181,10 @@ bash scripts/forge-team/index.sh verify 2>&1 || true
   - Beads linked: forge-xyz
   - Implementation details in collapsible section
 
-⏸️  PR created, awaiting automated checks (Greptile, SonarCloud, GitHub Actions)
+⏸️  PR created, checks started (Greptile, SonarCloud, GitHub Actions)
+   Poll for up to 60 seconds. If checks are still pending, stop here.
 
-Next: /review <pr-number> (after automated checks complete)
+Next: /review <pr-number> (when automated checks complete or new feedback appears)
 ```
 
 ## Integration with Workflow
@@ -205,5 +206,5 @@ Stage 7: /verify     → Post-merge CI check on main
 - **Fill every section**: Even if "N/A" — empty/missing sections cause review friction
 - **Include "Closes beads-xxx"**: Required for auto-close in /verify
 - **Concrete data only**: Test counts, file paths, commit SHAs — not placeholder text
-- **Wait for checks**: Let GitHub Actions, Greptile, SonarCloud run
+- **Poll briefly, then stop**: Check PR status for up to 60 seconds, then hand off if checks are still pending
 - **NO auto-merge**: Always wait for /review phase

package/.github/prompts/premerge.prompt.md

@@ -96,7 +96,7 @@ git commit -m "docs: update documentation for <feature-name>
 git push
 ```
 
-⚠️  **After pushing**: CI will re-trigger (Greptile, SonarCloud, etc.). Wait for checks to pass. If new Greptile comments appear on the doc changes, run `/review <pr-number>` again.
+⚠️  **After pushing**: CI will re-trigger (Greptile, SonarCloud, etc.). Poll for up to 60 seconds. If checks are still pending after that, stop and ask the user to return to `/premerge <pr-number>` later. If new Greptile comments appear on the doc changes, run `/review <pr-number>` again.
 
 ### Step 4: Sync Beads
 
@@ -155,7 +155,7 @@ Do NOT suggest merging.
   - README.md: Features list updated
   - CLAUDE.md: USER section updated with new pattern
   - Committed: docs: update documentation for auth-refresh
-✓ CI re-triggered after doc push — all checks still passing
+✓ CI re-triggered after doc push — checks passed within the 60 second poll window
 ✓ Beads synced
 
 ✅ PR #89 is ready to merge

package/.github/prompts/review.prompt.md

@@ -300,10 +300,13 @@ git push
 ### Step 9: Verify ALL Checks Pass
 
 ```bash
-# Wait for checks to complete
+# Check status immediately, then poll for at most 60 seconds
 gh pr checks <pr-number>
 
-# Ensure all status checks are green:
+# If checks are still pending after 60 seconds: STOP and tell the user to return
+# when CI finishes or new review feedback appears.
+#
+# Ensure all completed status checks are green:
 # ✓ GitHub Actions workflows
 # ✓ Greptile review (no unresolved critical comments)
 # ✓ SonarCloud quality gate

package/.github/prompts/ship.prompt.md

@@ -186,9 +186,10 @@ bash scripts/forge-team/index.sh verify 2>&1 || true
   - Beads linked: forge-xyz
   - Implementation details in collapsible section
 
-⏸️  PR created, awaiting automated checks (Greptile, SonarCloud, GitHub Actions)
+⏸️  PR created, checks started (Greptile, SonarCloud, GitHub Actions)
+   Poll for up to 60 seconds. If checks are still pending, stop here.
 
-Next: /review <pr-number> (after automated checks complete)
+Next: /review <pr-number> (when automated checks complete or new feedback appears)
 ```
 
 ## Integration with Workflow
@@ -210,5 +211,5 @@ Stage 7: /verify     → Post-merge CI check on main
 - **Fill every section**: Even if "N/A" — empty/missing sections cause review friction
 - **Include "Closes beads-xxx"**: Required for auto-close in /verify
 - **Concrete data only**: Test counts, file paths, commit SHAs — not placeholder text
-- **Wait for checks**: Let GitHub Actions, Greptile, SonarCloud run
+- **Poll briefly, then stop**: Check PR status for up to 60 seconds, then hand off if checks are still pending
 - **NO auto-merge**: Always wait for /review phase

package/.github/workflows/beads-to-github.yml

@@ -30,7 +30,7 @@ jobs:
 
       - name: Checkout current
         if: env.SKIP != 'true'
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4
         with:
           fetch-depth: 0
 

package/.github/workflows/github-to-beads.yml

@@ -20,7 +20,7 @@ jobs:
     if: github.actor != 'github-actions[bot]'
     steps:
       - name: Checkout code
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4
         with:
           # Need full history for push
           fetch-depth: 0

package/.kilocode/workflows/premerge.md

@@ -95,7 +95,7 @@ git commit -m "docs: update documentation for <feature-name>
 git push
 ```
 
-⚠️  **After pushing**: CI will re-trigger (Greptile, SonarCloud, etc.). Wait for checks to pass. If new Greptile comments appear on the doc changes, run `/review <pr-number>` again.
+⚠️  **After pushing**: CI will re-trigger (Greptile, SonarCloud, etc.). Poll for up to 60 seconds. If checks are still pending after that, stop and ask the user to return to `/premerge <pr-number>` later. If new Greptile comments appear on the doc changes, run `/review <pr-number>` again.
 
 ### Step 4: Sync Beads
 
@@ -154,7 +154,7 @@ Do NOT suggest merging.
   - README.md: Features list updated
   - CLAUDE.md: USER section updated with new pattern
   - Committed: docs: update documentation for auth-refresh
-✓ CI re-triggered after doc push — all checks still passing
+✓ CI re-triggered after doc push — checks passed within the 60 second poll window
 ✓ Beads synced
 
 ✅ PR #89 is ready to merge

package/.kilocode/workflows/review.md

@@ -299,10 +299,13 @@ git push
 ### Step 9: Verify ALL Checks Pass
 
 ```bash
-# Wait for checks to complete
+# Check status immediately, then poll for at most 60 seconds
 gh pr checks <pr-number>
 
-# Ensure all status checks are green:
+# If checks are still pending after 60 seconds: STOP and tell the user to return
+# when CI finishes or new review feedback appears.
+#
+# Ensure all completed status checks are green:
 # ✓ GitHub Actions workflows
 # ✓ Greptile review (no unresolved critical comments)
 # ✓ SonarCloud quality gate

package/.kilocode/workflows/ship.md

@@ -185,9 +185,10 @@ bash scripts/forge-team/index.sh verify 2>&1 || true
   - Beads linked: forge-xyz
   - Implementation details in collapsible section
 
-⏸️  PR created, awaiting automated checks (Greptile, SonarCloud, GitHub Actions)
+⏸️  PR created, checks started (Greptile, SonarCloud, GitHub Actions)
+   Poll for up to 60 seconds. If checks are still pending, stop here.
 
-Next: /review <pr-number> (after automated checks complete)
+Next: /review <pr-number> (when automated checks complete or new feedback appears)
 ```
 
 ## Integration with Workflow
@@ -209,5 +210,5 @@ Stage 7: /verify     → Post-merge CI check on main
 - **Fill every section**: Even if "N/A" — empty/missing sections cause review friction
 - **Include "Closes beads-xxx"**: Required for auto-close in /verify
 - **Concrete data only**: Test counts, file paths, commit SHAs — not placeholder text
-- **Wait for checks**: Let GitHub Actions, Greptile, SonarCloud run
+- **Poll briefly, then stop**: Check PR status for up to 60 seconds, then hand off if checks are still pending
 - **NO auto-merge**: Always wait for /review phase

package/.opencode/commands/premerge.md

@@ -94,7 +94,7 @@ git commit -m "docs: update documentation for <feature-name>
 git push
 ```
 
-⚠️  **After pushing**: CI will re-trigger (Greptile, SonarCloud, etc.). Wait for checks to pass. If new Greptile comments appear on the doc changes, run `/review <pr-number>` again.
+⚠️  **After pushing**: CI will re-trigger (Greptile, SonarCloud, etc.). Poll for up to 60 seconds. If checks are still pending after that, stop and ask the user to return to `/premerge <pr-number>` later. If new Greptile comments appear on the doc changes, run `/review <pr-number>` again.
 
 ### Step 4: Sync Beads
 
@@ -153,7 +153,7 @@ Do NOT suggest merging.
   - README.md: Features list updated
   - CLAUDE.md: USER section updated with new pattern
   - Committed: docs: update documentation for auth-refresh
-✓ CI re-triggered after doc push — all checks still passing
+✓ CI re-triggered after doc push — checks passed within the 60 second poll window
 ✓ Beads synced
 
 ✅ PR #89 is ready to merge

package/.opencode/commands/review.md

@@ -298,10 +298,13 @@ git push
 ### Step 9: Verify ALL Checks Pass
 
 ```bash
-# Wait for checks to complete
+# Check status immediately, then poll for at most 60 seconds
 gh pr checks <pr-number>
 
-# Ensure all status checks are green:
+# If checks are still pending after 60 seconds: STOP and tell the user to return
+# when CI finishes or new review feedback appears.
+#
+# Ensure all completed status checks are green:
 # ✓ GitHub Actions workflows
 # ✓ Greptile review (no unresolved critical comments)
 # ✓ SonarCloud quality gate

package/.opencode/commands/ship.md

@@ -184,9 +184,10 @@ bash scripts/forge-team/index.sh verify 2>&1 || true
   - Beads linked: forge-xyz
   - Implementation details in collapsible section
 
-⏸️  PR created, awaiting automated checks (Greptile, SonarCloud, GitHub Actions)
+⏸️  PR created, checks started (Greptile, SonarCloud, GitHub Actions)
+   Poll for up to 60 seconds. If checks are still pending, stop here.
 
-Next: /review <pr-number> (after automated checks complete)
+Next: /review <pr-number> (when automated checks complete or new feedback appears)
 ```
 
 ## Integration with Workflow
@@ -208,5 +209,5 @@ Stage 7: /verify     → Post-merge CI check on main
 - **Fill every section**: Even if "N/A" — empty/missing sections cause review friction
 - **Include "Closes beads-xxx"**: Required for auto-close in /verify
 - **Concrete data only**: Test counts, file paths, commit SHAs — not placeholder text
-- **Wait for checks**: Let GitHub Actions, Greptile, SonarCloud run
+- **Poll briefly, then stop**: Check PR status for up to 60 seconds, then hand off if checks are still pending
 - **NO auto-merge**: Always wait for /review phase

package/.roo/commands/premerge.md

@@ -95,7 +95,7 @@ git commit -m "docs: update documentation for <feature-name>
 git push
 ```
 
-⚠️  **After pushing**: CI will re-trigger (Greptile, SonarCloud, etc.). Wait for checks to pass. If new Greptile comments appear on the doc changes, run `/review <pr-number>` again.
+⚠️  **After pushing**: CI will re-trigger (Greptile, SonarCloud, etc.). Poll for up to 60 seconds. If checks are still pending after that, stop and ask the user to return to `/premerge <pr-number>` later. If new Greptile comments appear on the doc changes, run `/review <pr-number>` again.
 
 ### Step 4: Sync Beads
 
@@ -154,7 +154,7 @@ Do NOT suggest merging.
   - README.md: Features list updated
   - CLAUDE.md: USER section updated with new pattern
   - Committed: docs: update documentation for auth-refresh
-✓ CI re-triggered after doc push — all checks still passing
+✓ CI re-triggered after doc push — checks passed within the 60 second poll window
 ✓ Beads synced
 
 ✅ PR #89 is ready to merge

package/.roo/commands/review.md

@@ -299,10 +299,13 @@ git push
 ### Step 9: Verify ALL Checks Pass
 
 ```bash
-# Wait for checks to complete
+# Check status immediately, then poll for at most 60 seconds
 gh pr checks <pr-number>
 
-# Ensure all status checks are green:
+# If checks are still pending after 60 seconds: STOP and tell the user to return
+# when CI finishes or new review feedback appears.
+#
+# Ensure all completed status checks are green:
 # ✓ GitHub Actions workflows
 # ✓ Greptile review (no unresolved critical comments)
 # ✓ SonarCloud quality gate

package/.roo/commands/ship.md

@@ -185,9 +185,10 @@ bash scripts/forge-team/index.sh verify 2>&1 || true
   - Beads linked: forge-xyz
   - Implementation details in collapsible section
 
-⏸️  PR created, awaiting automated checks (Greptile, SonarCloud, GitHub Actions)
+⏸️  PR created, checks started (Greptile, SonarCloud, GitHub Actions)
+   Poll for up to 60 seconds. If checks are still pending, stop here.
 
-Next: /review <pr-number> (after automated checks complete)
+Next: /review <pr-number> (when automated checks complete or new feedback appears)
 ```
 
 ## Integration with Workflow
@@ -209,5 +210,5 @@ Stage 7: /verify     → Post-merge CI check on main
 - **Fill every section**: Even if "N/A" — empty/missing sections cause review friction
 - **Include "Closes beads-xxx"**: Required for auto-close in /verify
 - **Concrete data only**: Test counts, file paths, commit SHAs — not placeholder text
-- **Wait for checks**: Let GitHub Actions, Greptile, SonarCloud run
+- **Poll briefly, then stop**: Check PR status for up to 60 seconds, then hand off if checks are still pending
 - **NO auto-merge**: Always wait for /review phase

package/AGENTS.md

@@ -232,15 +232,15 @@ This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full
 ### Quick Reference
 
 ```bash
-bd ready              # Find available work
-bd show <id>          # View issue details
-bd update <id> --claim  # Claim work
-bd close <id>         # Complete work
+forge ready           # Find available work
+forge show <id>       # View issue details
+forge claim <id>      # Claim work
+forge close <id>      # Complete work
 ```
 
 ### Rules
 
-- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists. Exception: `/plan` Phase 3 generates task lists at `docs/plans/YYYY-MM-DD-<slug>-tasks.md` — these are approved artifacts consumed by `/dev`, but `bd` remains the source of truth for issue state. GitHub issues may be used for external/public tracking; CI may sync GitHub issue lifecycle to Beads (see `docs/BEADS_GITHUB_SYNC.md`).
+- Use `forge` as the routine command surface for bd-backed issue tracking and sync workflows — do NOT use TodoWrite, TaskCreate, or markdown TODO lists. Exception: `/plan` Phase 3 generates task lists at `docs/plans/YYYY-MM-DD-<slug>-tasks.md` — these are approved artifacts consumed by `/dev`, but Beads (`bd`) remains the source of truth for issue state and IDs. Use `bd` directly only for operations Forge does not wrap yet, such as `bd init`, `bd comments`, `bd dep`, and `bd dolt *`. GitHub issues may be used for external/public tracking; CI may sync GitHub issue lifecycle to Beads (see `docs/BEADS_GITHUB_SYNC.md`).
 - Run `bd prime` for detailed command reference and session close protocol
 - Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files
 
@@ -255,10 +255,10 @@ bd close <id>         # Complete work
 3. **Update issue status** - Close finished work, update in-progress items
 4. **PUSH TO REMOTE** - This is MANDATORY:
    ```bash
-   git pull --rebase
-   bd dolt push   # requires Dolt-backed Beads — run 'bd init' if missing
-   git push
-   git status  # MUST show "up to date with origin"
+    git pull --rebase
+    forge sync     # wraps the supported Beads sync flow when Beads is configured
+    git push
+    git status  # MUST show "up to date with origin"
    ```
 5. **Clean up** - Clear stashes, prune remote branches
 6. **Verify** - All changes committed AND pushed

package/README.md

@@ -402,14 +402,20 @@ gh auth login
 /premerge <pr>             # Complete docs, hand off PR
 /verify                    # Post-merge health check
 
-# Beads commands (optional)
-bd init                    # Initialize tracking
-bd ready                   # Find ready work
-bd create "title"          # Create issue
-bd update <id> --status X  # Update status
-bd sync                    # Sync with git
+# Issue commands (via Forge)
+bd init                    # Initialize Beads tracking
+forge ready                # Find ready work
+forge create "title"       # Create issue
+forge update <id> --status X  # Update status
+forge sync                 # Sync Beads state
 ```
 
+For advanced Beads operations that Forge does not wrap yet, use `bd` directly for
+`bd comments`, `bd dep`, and `bd dolt`.
+
+Forge is the preferred command surface for routine workflows, but Beads (`bd`)
+remains the underlying source of truth for issue state and IDs.
+
 ---
 
 ## License

package/bin/forge.js

@@ -139,7 +139,7 @@ function loadAgentsFromPlugins() {
     agents[id] = {
       name: plugin.name,
       description: plugin.description || '',
-      dirs: Object.values(plugin.directories || {}),
+      dirs: getRepoRelativePluginDirectories(plugin),
       hasCommands: plugin.capabilities?.commands || plugin.setup?.copyCommands || false,
       hasSkill: plugin.capabilities?.skills || plugin.setup?.createSkill || false,
       linkFile: plugin.files?.rootConfig || '',
@@ -153,6 +153,17 @@ function loadAgentsFromPlugins() {
   return agents;
 }
 
+function isRepoRelativePluginPath(candidate) {
+  return typeof candidate === 'string'
+    && candidate.length > 0
+    && !path.isAbsolute(candidate)
+    && !/^[~$%]/.test(candidate);
+}
+
+function getRepoRelativePluginDirectories(plugin) {
+  return Object.values(plugin.directories || {}).filter(isRepoRelativePluginPath);
+}
+
 // Agent definitions - loaded from plugin system
 const AGENTS = loadAgentsFromPlugins();
 
@@ -2383,7 +2394,7 @@ function displaySetupSummary(selectedAgents) {
 
   // Beads status
   if (isBeadsInitialized()) {
-    console.log('  ✓ Beads initialized - Track work: bd ready');
+    console.log('  ✓ Beads initialized - Track work: forge ready');
   } else if (checkForBeads()) {
     console.log('  ! Beads available - Run: bd init');
   } else {
@@ -3336,7 +3347,7 @@ async function setupProjectTools(rl, question) {
   console.log('');
   console.log('• Beads - Git-backed issue tracking');
   console.log('  Persists tasks across sessions, tracks dependencies.');
-  console.log('  Command: bd ready, bd create, bd close');
+  console.log('  Command: forge ready, forge create, forge close');
   console.log('');
   console.log('• Skills - Universal SKILL.md management');
   console.log('  Manage AI agent skills across all agents.');