forge-workflow 0.0.9 → 0.1.0-beta.2

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

@@ -1,215 +0,0 @@
----
-name: ship
-description: Create PR with comprehensive documentation
-tools: []
----
-
-Push code and create a pull request with full context and documentation links.
-
-# Ship
-
-This command creates a PR after validation passes.
-
-## Usage
-
-```bash
-/ship
-```
-
-```
-<HARD-GATE: /ship entry>
-Do NOT create PR until:
-1. /validate was run in this session with all four outputs shown (type, lint, tests, security)
-2. All checks confirmed passing — not assumed, not "was passing earlier"
-3. Beads issue is in_progress
-4. git branch --show-current output is NOT main or master
-</HARD-GATE>
-```
-
-## What This Command Does
-
-### Step 1: Verify /validate Passed
-Ensure all four validation checks completed successfully with fresh output in this session.
-
-### Step 2: Freshness Check — Is Branch Still Current?
-
-Even though /validate rebased onto the base branch, time may have passed since then (user reviewed design doc, took a break, etc.). This lightweight check catches staleness before pushing.
-
-```bash
-BASE=$(git remote show origin 2>/dev/null | grep 'HEAD branch' | awk '{print $NF}')
-if [ -z "$BASE" ] || [ "$BASE" = "(unknown)" ]; then BASE="master"; fi
-git fetch origin "$BASE" || { echo "✗ Fetch failed — cannot verify freshness"; exit 1; }
-BEHIND=$(git rev-list --count HEAD..origin/"$BASE")
-```
-
-- If `BEHIND > 0`: **STOP**. Print: "$BASE has advanced since /validate ($BEHIND new commits). Run /validate again to rebase and re-check."
-- If `BEHIND = 0`: Continue to push.
-- If fetch fails: the `|| { ...; exit 1; }` guard catches this — **STOP**. Do NOT push without confirming freshness.
-
-This is NOT a full rebase — just a check. The rebase happens in /validate where the full test suite runs afterward.
-
-### Parallel PR coordination (soft block)
-
-Before creating the PR, check merge readiness:
-
-```bash
-# Run merge simulation against base branch
-bash scripts/pr-coordinator.sh merge-sim "$(git branch --show-current)" 2>&1
-
-# Show recommended merge order
-bash scripts/pr-coordinator.sh merge-order 2>&1 || true
-
-# Auto-label the PR after creation (called after gh pr create below)
-# bash scripts/pr-coordinator.sh auto-label <issue-id>
-```
-
-If merge simulation finds conflicts:
-- Display conflicted files
-- Ask: "Merge conflicts detected with base branch. These PRs should merge first: [list]. Proceed with PR creation anyway? (y/n)"
-- If `n`: exit cleanly
-- If `y`: log override via `bd comments add <id> "Ship override: creating PR despite merge conflicts"`, then continue
-
-After PR creation completes:
-```bash
-# Auto-label the newly created PR
-bash scripts/pr-coordinator.sh auto-label <issue-id>
-
-# Check for stale worktrees (informational)
-bash scripts/pr-coordinator.sh stale-worktrees 2>&1 || true
-```
-
-### Step 3: Update Beads
-```bash
-bd update <id> --status done
-bd sync
-```
-
-### Step 4: Push Branch
-
-Use `--force-with-lease` because `/validate` may have rebased the branch, rewriting history. This is safe: it only forces the push if the remote branch hasn't been updated by someone else since the last fetch.
-
-```bash
-git push --force-with-lease -u origin <branch-name>
-```
-
-### Step 5: Create PR Using Project's PR Template
-
-**CRITICAL**: Always use the project's own PR template. Never use a hardcoded body.
-
-**Step 5a: Locate the PR template**
-
-Check for a PR template in the project (in order of precedence):
-```bash
-# Check standard locations
-PR_TEMPLATE=""
-for path in .github/pull_request_template.md .github/PULL_REQUEST_TEMPLATE.md docs/pull_request_template.md pull_request_template.md; do
-  if [ -f "$path" ]; then
-    PR_TEMPLATE="$path"
-    break
-  fi
-done
-```
-
-**Step 5b: Read and populate the template**
-
-If a PR template exists:
-1. **Read the template file** using the Read tool
-2. **Fill in every section** with actual data from the current PR context:
-   - Replace HTML comments (`<!-- ... -->`) with real content
-   - Check applicable checkboxes (`- [x]`)
-   - Fill in beads issue IDs (replace `beads-xxx` with actual ID)
-   - Fill in test results, validation status, and other concrete data
-   - Reference the design doc: `docs/plans/YYYY-MM-DD-<slug>-design.md`
-3. **Do NOT remove any sections** — fill them all, even if "N/A"
-4. **Do NOT restructure the template** — keep the project's chosen format
-
-If no PR template exists, use this minimal fallback:
-```
-## Summary
-[1-3 sentences: what this PR does and why]
-
-## Changes
-[Bulleted list of key changes]
-
-## Testing
-[How it was tested, test results]
-
-## Beads
-Closes beads-xxx
-
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
-```
-
-**Step 5c: Create the PR**
-
-```bash
-gh pr create --title "<type>: <concise description>" --body "<populated-template-content>"
-```
-
-Rules for the PR body:
-- **Use the project's template structure** — never substitute your own format
-- **Fill in concrete data** — commit counts, test results, actual file paths, real beads IDs
-- **Check applicable checkboxes** — `[x]` for items that apply, `[ ]` for items that don't
-- **Include "Closes beads-xxx"** in the Beads section (required for auto-close in /verify)
-
-### Step 6: Validate Context and Record Stage Transition
-```bash
-bash scripts/beads-context.sh validate <id>
-bash scripts/beads-context.sh stage-transition <id> ship review \
-  --summary "<PR created, checks pending>" \
-  --decisions "<template sections filled, beads linked>" \
-  --artifacts "<PR URL, branch name>" \
-  --next "<review focus areas>"
-```
-
-### Team sync after PR
-
-After PR is created, sync issue state to GitHub and verify 1:1 mapping:
-
-```bash
-# Sync issue state to GitHub
-bash scripts/forge-team/index.sh sync 2>&1 || true
-
-# Verify 1:1 mapping
-bash scripts/forge-team/index.sh verify 2>&1 || true
-```
-
-## Example Output
-
-```
-✓ Validation: /validate passed (all 4 checks — fresh output confirmed)
-✓ Freshness: Branch is up-to-date with master
-✓ Beads: Marked done & synced (forge-xyz)
-✓ Pushed: feat/stripe-billing
-✓ PR created: https://github.com/.../pull/123
-  - PR body: Problem → Root Cause → Fix → Value (narrative format)
-  - Beads linked: forge-xyz
-  - Implementation details in collapsible section
-
-⏸️  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> (when automated checks complete or new feedback appears)
-```
-
-## Integration with Workflow
-
-```
-Utility: /status     → Understand current context before starting
-Stage 1: /plan       → Design intent → research → branch + worktree + task list
-Stage 2: /dev        → Implement each task with subagent-driven TDD
-Stage 3: /validate      → Type check, lint, tests, security — all fresh output
-Stage 4: /ship       → Push + create PR (you are here)
-Stage 5: /review     → Address GitHub Actions, Greptile, SonarCloud
-Stage 6: /premerge   → Update docs, hand off PR to user
-Stage 7: /verify     → Post-merge CI check on main
-```
-
-## Tips
-
-- **Use the project's PR template**: Always read `.github/pull_request_template.md` (or equivalent) and populate it — never substitute your own format
-- **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
-- **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/status.prompt.md

@@ -1,92 +0,0 @@
----
-name: status
-description: Check current stage and context
-tools: []
----
-
-Check where you are in the project and what work is in progress.
-
-# Status Check
-
-This command helps you understand the current state of the project before starting new work.
-
-## Usage
-
-```bash
-/status
-```
-
-## What This Command Does
-
-## Step 0: Sync team state
-
-```bash
-# Sync team state before showing status
-bash scripts/sync-utils.sh auto-sync
-```
-
-### Step 1: Smart Status (ranked issues with conflict detection)
-
-```bash
-bash scripts/smart-status.sh
-```
-This script dynamically computes and displays all issues ranked by composite score (priority, dependency impact, type, staleness, epic proximity). Output includes active sessions, conflict risk annotations, and grouped categories. No manual querying needed — the script handles everything.
-
-For full context on any issue: `bd show <id>`
-
-### Step 1b: Reconcile stale in-progress issues
-
-Check if any in-progress issues were already merged but not closed (can happen if `/verify` was skipped or backup was restored from stale snapshot):
-
-```bash
-# Detect default branch dynamically (prefer main over master)
-DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||')
-if [ -z "$DEFAULT_BRANCH" ]; then
-  if git rev-parse --verify main >/dev/null 2>&1; then DEFAULT_BRANCH="main"
-  elif git rev-parse --verify master >/dev/null 2>&1; then DEFAULT_BRANCH="master"
-  else echo "ERROR: No main or master branch found — skipping stale reconciliation" >&2; DEFAULT_BRANCH=""; fi
-fi
-
-# For each in_progress issue, check if its PR was already merged
-if [ -n "$DEFAULT_BRANCH" ]; then
-  bd list --status=in_progress --json 2>/dev/null | jq -r '.[].id' | while read id; do
-    # Search git log for the issue ID in commit messages (fixed-strings for literal match)
-    if git log --oneline --first-parent "$DEFAULT_BRANCH" --fixed-strings --grep="$id" | grep -q .; then
-      echo "STALE: $id — found in git history, likely already merged"
-    fi
-  done
-fi
-```
-
-If stale issues are found, close them:
-```bash
-bd close <id> --force --reason="Already merged — detected during status reconciliation"
-```
-
-### Step 2: Review Recent Commits
-```bash
-git log --oneline -10
-```
-
-### Step 3: Determine Context
-- **New feature**: No active work, ready to start fresh
-- **Continuing work**: In-progress issues found, resume where left off
-- **Review needed**: Work marked complete, needs review/merge
-
-### Team context
-
-Show current developer's active work and team overview:
-
-```bash
-# Show my active issues
-bash scripts/forge-team/index.sh workload --me 2>&1 || true
-
-# One-line team summary
-bash scripts/forge-team/index.sh dashboard 2>&1 | head -5 || true
-```
-
-## Next Steps
-
-- **If starting new work**: Run `/plan <feature-name>`
-- **If continuing work**: Resume with appropriate phase command
-- **If reviewing**: Run `/review <pr-number>` or `/premerge <pr-number>`

package/.github/prompts/verify.prompt.md

@@ -1,271 +0,0 @@
----
-name: verify
-description: Post-merge health check — confirm merge landed, CI is clean, deployments are up
-tools: []
----
-
-Verify that the merge landed correctly and everything is running properly after merge.
-
-# Verify
-
-This command runs AFTER the user has merged the PR. It checks system health — not documentation (that was handled in `/premerge`).
-
-## Usage
-
-```bash
-/verify
-```
-
-## What This Command Does
-
-### Step 1: Switch to Main and Pull
-
-```bash
-git checkout master
-git pull
-```
-
-Confirm the merge actually landed on main. If the PR isn't merged yet, stop and tell the user to merge first.
-
-### Step 2: Confirm PR Is Merged
-
-Detect the most recently merged PR from the current HEAD commit:
-
-```bash
-gh pr list --state merged --base master --limit 1 --json number,state,mergedAt,mergedBy
-```
-
-- `state` should be `MERGED`
-- If no PR found: the merge may not have landed yet — stop and tell the user to merge first
-- If the wrong PR appears: user can specify the number directly with `gh pr view <number> --json state,mergedAt,mergedBy`
-
-### Step 3: Check CI on Main After Merge
-
-```bash
-gh run list --branch master --limit 5
-```
-
-Check the most recent workflow runs on `master`:
-- All should be passing or in progress
-- If any failed: identify which workflow and what failed
-- Failed CI on main after merge may need a hotfix PR
-
-### Step 4: Check Deployments (if applicable)
-
-Check if the project has a deployment target:
-
-```bash
-# Check deployment status from latest run
-gh run list --branch master --limit 1
-
-# Check Vercel deployments for the merged PR (use number from Step 2)
-gh pr view <number> --json deployments
-```
-
-If deployments exist:
-- Are they showing as successful?
-- Is the production/preview URL responding?
-
-### Step 5: Report Status
-
-**If everything is clean**:
-```
-✅ Merge verified — everything is healthy
-
-  PR: #<number> merged by <user> at <time>
-  CI on master: ✓ All passing
-  Deployments: ✓ Up (if applicable)
-
-  Ready for next feature → run /status
-```
-
-**If issues found**:
-```
-⚠️  Post-merge issues detected
-
-  PR: #<number> merged ✓
-  CI on master: ✗ <workflow-name> failing
-    - Error: <description>
-    - Action needed: <hotfix or investigation>
-
-  Deployments: ✗ <deployment> not responding
-
-  Next: Create hotfix branch or investigate root cause
-```
-
-### Step 6: Clean Up Worktree and Branch
-
-Only run this step after CI is confirmed healthy (Step 3 passed).
-
-Get the merged branch name:
-
-```bash
-gh pr view <number> --json headRefName --jq '.headRefName'
-```
-
-If the branch name cannot be determined (empty output or error), skip cleanup and tell the user to run `git worktree list` and clean up manually.
-
-Find and remove the matching worktree (if it exists):
-
-```bash
-# Get the worktree path for this exact branch
-WORKTREE_PATH=$(git worktree list --porcelain \
-  | awk -v branch="refs/heads/<branch>" '
-      /^worktree / { path=substr($0, 10) }
-      $0 == "branch " branch { print path }
-    ')
-
-if [ -n "$WORKTREE_PATH" ]; then
-  git worktree remove "$WORKTREE_PATH" --force
-  echo "Worktree: removed ✓ ($WORKTREE_PATH)"
-else
-  echo "Worktree: not found (already removed or never created) — skipping"
-fi
-```
-
-If no worktree is found for that branch, skip gracefully with a note: "Worktree: not found (already removed or never created)".
-
-Delete the local branch (safe delete only):
-
-```bash
-git branch -d <branch> 2>/dev/null || echo "Branch: already deleted — skipping"
-```
-
-The `|| echo` fallback handles the case where the branch is already gone (e.g., deleted by a previous run or the remote), so the command never fails the verify step.
-
-Report cleanup in output:
-```
-Worktree: removed ✓
-Branch: <branch-name> deleted ✓
-```
-
-### Step 7: If Issues Found — Create Beads Issue
-
-**Never commit inline.** If something is wrong, create a tracking issue:
-
-```bash
-bd create --title="Post-merge: <description of issue>" --type=bug --priority=1
-```
-
-### Step 8: Close Beads Issues (if healthy)
-
-If everything is clean, close all Beads issues referenced in the merged PR.
-
-**Auto-detect beads issues from PR body and branch name:**
-
-```bash
-# Get PR body and branch name
-PR_BODY=$(gh pr view <number> --json body --jq '.body')
-PR_BRANCH=$(gh pr view <number> --json headRefName --jq '.headRefName')
-
-# Extract beads IDs from PR body (matches "Closes beads-xxx", "closes forge-xxx", etc.)
-# Patterns: "Closes <prefix>-<id>", "Fixes <prefix>-<id>", "Resolves <prefix>-<id>"
-BEADS_IDS=$(echo "$PR_BODY" | grep -oiE '(closes|fixes|resolves):?\s+[a-z]+-[a-z0-9]+' | grep -oiE '[a-z]+-[a-z0-9]{3,6}$')
-
-# Validate each ID exists in beads
-VALID_IDS=""
-for id in $BEADS_IDS; do
-  if bd show "$id" >/dev/null 2>&1; then
-    VALID_IDS="$VALID_IDS $id"
-  fi
-done
-BEADS_IDS="$VALID_IDS"
-
-# Also check branch name for beads ID — extract segment after last /
-# then validate with bd show to avoid false matches like "pr-templa"
-BRANCH_SLUG=$(echo "$PR_BRANCH" | sed 's|.*/||')
-BRANCH_ID=$(echo "$BRANCH_SLUG" | grep -oE '[a-z]+-[a-z0-9]{3,6}' | head -1)
-if [ -n "$BRANCH_ID" ] && ! bd show "$BRANCH_ID" >/dev/null 2>&1; then
-  BRANCH_ID=""  # Not a valid beads ID — discard
-fi
-```
-
-**Close each matched issue:**
-
-```bash
-# Close issues found in PR body
-for id in $BEADS_IDS; do
-  bd close "$id" --reason="Merged and verified on master (PR #<number>)" 2>&1 || echo "Warning: could not close $id"
-done
-
-# If no issues found in body, try branch name match (skip if already closed above)
-if [ -z "$BEADS_IDS" ] && [ -n "$BRANCH_ID" ]; then
-  bd close "$BRANCH_ID" --reason="Merged and verified on master (PR #<number>)" 2>&1 || echo "Warning: could not close $BRANCH_ID"
-elif [ -n "$BRANCH_ID" ] && ! echo "$BEADS_IDS" | grep -qw "$BRANCH_ID"; then
-  bd close "$BRANCH_ID" --reason="Merged and verified on master (PR #<number>)" 2>&1 || echo "Warning: could not close $BRANCH_ID"
-fi
-```
-
-**If no beads issues detected at all**, prompt the user:
-```
-⚠ No beads issue ID found in PR body or branch name.
-  If this PR closes a beads issue, run: bd close <id> --reason="Merged and verified on master (PR #<number>)"
-```
-
-```
-<HARD-GATE: /verify exit>
-Do NOT declare /verify complete until:
-1. gh run list --branch master --limit 3 shows actual CI output (not "should be fine")
-2. If healthy: Beads issues extracted from PR body/branch and closed (bd close run and confirmed)
-   - If no beads ID found: user was warned and given manual close command
-3. If issues found: Beads tracking issue created for every problem
-4. Worktree removed (or confirmed already gone) — OR Step 6 was intentionally skipped because CI was unhealthy; if skipped, state explicitly: "cleanup deferred, CI was not healthy"
-"It should be fine" is not evidence. Run the command. Show the output.
-</HARD-GATE>
-```
-
-## Rules
-
-- **Never commits** — this command is read-only
-- **Never creates PRs** — if fixes are needed, that's a new /dev cycle
-- **Runs after user confirms merge** — not before
-- **Reports honestly** — if CI is broken on main, say so clearly
-
-## Example Output (Healthy)
-
-```
-✅ Merge verified — everything is healthy
-
-  PR: #89 merged by harshanandak at 2026-02-24T14:30:00Z
-  Branch: feat/auth-refresh deleted ✓
-  CI on master:
-    ✓ Test Suite (ubuntu, node 20): passing
-    ✓ Test Suite (windows, node 22): passing
-    ✓ ESLint: passing
-    ✓ SonarCloud: passing
-    ✓ CodeQL: passing
-  Deployments: N/A (no deployment configured)
-
-  Ready for next feature → run /status
-```
-
-## Example Output (Issues Found)
-
-```
-⚠️  Post-merge issues detected
-
-  PR: #89 merged ✓
-  CI on master:
-    ✓ Test Suite: passing
-    ✗ SonarCloud: quality gate failing
-      - 2 new code smells introduced
-      - Action: investigate or create hotfix
-
-  Created Beads issue: forge-xyz
-  "Post-merge: SonarCloud quality gate failing on master after PR #89"
-
-  Run /status to assess next steps
-```
-
-## Integration with Workflow
-
-```
-Utility: /status     → Understand current context before starting
-Stage 1: /plan       → Design intent → research → branch + worktree + task list
-Stage 2: /dev        → Implement each task with subagent-driven TDD
-Stage 3: /validate      → Type check, lint, tests, security — all fresh output
-Stage 4: /ship       → Push + create PR
-Stage 5: /review     → Address GitHub Actions, Greptile, SonarCloud
-Stage 6: /premerge   → Update docs, hand off PR to user
-Stage 7: /verify     → Post-merge CI check on main (you are here) ✓
-```

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

@@ -1,56 +0,0 @@
-name: Beads → GitHub Issue Sync
-
-on:
-  push:
-    branches: [master]
-    paths:
-      - '.beads/**'
-
-# Serialize with forward-sync to prevent race conditions
-concurrency:
-  group: beads-sync
-  cancel-in-progress: false
-
-permissions:
-  contents: read
-  issues: write
-
-jobs:
-  reverse-sync:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Guard — skip loop commits
-        env:
-          COMMIT_MSG: ${{ github.event.head_commit.message }}
-        run: |
-          if [[ "$COMMIT_MSG" == chore\(beads\):* ]]; then
-            echo "Loop guard: skipping chore(beads): commit"
-            echo "SKIP=true" >> "$GITHUB_ENV"
-          fi
-
-      - name: Checkout current
-        if: env.SKIP != 'true'
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4
-        with:
-          fetch-depth: 0
-
-      - name: Detect and close
-        if: env.SKIP != 'true'
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          BEFORE_SHA: ${{ github.event.before }}
-        run: |
-          # Get old and new versions of .beads/issues.jsonl
-          # Use github.event.before (pre-push SHA) to catch multi-commit pushes
-          if [ "$BEFORE_SHA" = "0000000000000000000000000000000000000000" ] || [ -z "$BEFORE_SHA" ]; then
-            OLD_CONTENT=""
-          else
-            OLD_CONTENT=$(git show "$BEFORE_SHA":.beads/issues.jsonl 2>/dev/null || echo "")
-          fi
-          NEW_CONTENT=$(cat .beads/issues.jsonl 2>/dev/null || echo "")
-
-          # Export via temp files to avoid shell injection
-          printf '%s' "$OLD_CONTENT" > /tmp/old-issues.jsonl
-          printf '%s' "$NEW_CONTENT" > /tmp/new-issues.jsonl
-
-          node scripts/github-beads-sync/reverse-sync-cli.mjs /tmp/old-issues.jsonl /tmp/new-issues.jsonl