forge-workflow 0.0.5 → 0.0.7

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

@@ -46,6 +46,36 @@ BEHIND=$(git rev-list --count HEAD..origin/"$BASE")
 
 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
@@ -60,68 +90,86 @@ Use `--force-with-lease` because `/validate` may have rebased the branch, rewrit
 git push --force-with-lease -u origin <branch-name>
 ```
 
-### Step 5: Create PR
+### Step 5: Create PR Using Project's PR Template
 
-Use the narrative PR template below. Lead with WHY (Problem/Root Cause/Fix/Value) — this is what reviewers need to understand first. Keep implementation details (test coverage, security review, design doc) in a collapsible section so they're available but don't clutter the summary.
+**CRITICAL**: Always use the project's own PR template. Never use a hardcoded body.
 
-If no Beads issue exists (hotfix, external contribution), skip the "Closes" line.
+**Step 5a: Locate the PR template**
 
+Check for a PR template in the project (in order of precedence):
 ```bash
-gh pr create --title "<type>: <concise description>" --body "$(cat <<'EOF'
-## Problem
-[What was broken, what need existed, or what user pain this addresses]
-
-## Root Cause
-[Why it happened, why it was missing, or what gap existed]
+# 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
+```
 
-## Fix
-[What this PR does to solve it — approach, not implementation details]
+**Step 5b: Read and populate the template**
 
-## Value
-[Who benefits, what improves, what risk is removed]
+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
 
-## Beads
-Closes: <issue-id>
+If no PR template exists, use this minimal fallback:
+```
+## Summary
+[1-3 sentences: what this PR does and why]
 
-<details>
-<summary>Implementation Details</summary>
+## Changes
+[Bulleted list of key changes]
 
-### Test Coverage
-- Tests: [count] passing
-- Scenarios covered: [list key scenarios]
+## Testing
+[How it was tested, test results]
 
-### Security Review
-- OWASP Top 10: [summary — applicable risks and mitigations]
-- Automated scan: [result]
+## Beads
+Closes beads-xxx
 
-### Design Doc
-See: docs/plans/YYYY-MM-DD-<slug>-design.md
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+```
 
-### Decisions Log
-See: docs/plans/YYYY-MM-DD-<slug>-decisions.md (if any undocumented decisions arose during /dev)
+**Step 5c: Create the PR**
 
-### Key Decisions
-[From design doc — 3-5 key decisions with reasoning]
+```bash
+gh pr create --title "<type>: <concise description>" --body "<populated-template-content>"
+```
 
-### Documentation Updated
-[List docs updated in this PR, or "None — no doc-facing changes"]
+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)
 
-### Validation
-- [x] Type check passing
-- [x] Lint passing (0 errors, 0 warnings)
-- [x] All tests passing
-- [x] Security review completed
+### 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>"
+```
 
-</details>
+### Team sync after PR
 
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
-EOF
-)"
-```
+After PR is created, sync issue state to GitHub and verify 1:1 mapping:
 
-### Step 6: Record Stage Transition
 ```bash
-bash scripts/beads-context.sh stage-transition <id> ship review
+# 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
@@ -156,9 +204,9 @@ Stage 7: /verify     → Post-merge CI check on main
 
 ## Tips
 
-- **Lead with why**: Problem → Root Cause → Fix → Value is what reviewers need first
-- **Collapsible details**: Design doc, decisions log, test coverage go in `<details>` — available but not in the way
-- **Document security**: OWASP Top 10 review in collapsible section
-- **Test coverage**: Show all test scenarios passing
+- **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
 - **Wait for checks**: Let GitHub Actions, Greptile, SonarCloud run
 - **NO auto-merge**: Always wait for /review phase

package/.codex/skills/status/SKILL.md

@@ -24,6 +24,7 @@ bash scripts/sync-utils.sh auto-sync
 ```
 
 ### Step 1: Smart Status (ranked issues with conflict detection)
+
 ```bash
 bash scripts/smart-status.sh
 ```
@@ -31,6 +32,35 @@ This script dynamically computes and displays all issues ranked by composite sco
 
 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
@@ -41,6 +71,18 @@ git log --oneline -10
 - **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>`

package/.codex/skills/validate/SKILL.md

@@ -228,7 +228,13 @@ until ALL FOUR show fresh output in this session:
 "Should pass", "was passing earlier", and "I'm confident" are not evidence.
 Run the commands. Show the output. THEN declare done.
 
-5. Stage transition: Run `bash scripts/beads-context.sh stage-transition <id> validate ship` → exit 0 confirmed
+5. Context check: Run `bash scripts/beads-context.sh validate <id>` and address any warnings
+6. Stage transition: Run the following → exit 0 confirmed:
+   bash scripts/beads-context.sh stage-transition <id> validate ship \
+     --summary "<all checks pass/fail summary>" \
+     --decisions "<any failures diagnosed and fixed>" \
+     --artifacts "<scripts and commands run>" \
+     --next "<ship readiness notes>"
 </HARD-GATE>
 ```
 

package/.codex/skills/verify/SKILL.md

@@ -145,19 +145,67 @@ Branch: <branch-name> deleted ✓
 bd create --title="Post-merge: <description of issue>" --type=bug --priority=1
 ```
 
-### Step 8: Close Beads Issue (if healthy)
+### Step 8: Close Beads Issues (if healthy)
 
-If everything is clean, close the Beads issue:
+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
-bd close <id> --reason="Merged and verified on master"
+# 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 issue is closed (bd close <id> run and confirmed)
+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.

package/.cursor/commands/dev.md

@@ -272,7 +272,12 @@ Do NOT declare /dev complete until:
 ### Beads update
 
 ```bash
-bash scripts/beads-context.sh stage-transition <id> dev validate
+bash scripts/beads-context.sh validate <id>
+bash scripts/beads-context.sh stage-transition <id> dev validate \
+  --summary "<N tasks done, M decision gates fired>" \
+  --decisions "<key spec gaps and how they were resolved>" \
+  --artifacts "<changed source files and test files>" \
+  --next "<validation priorities — lint issues, type concerns>"
 ```
 
 ---

package/.cursor/commands/plan.md

@@ -73,6 +73,44 @@ If exit code 0: proceed silently to Phase 1.
 
 ---
 
+### Parallel PR coordination check (soft block)
+
+Before proceeding to Phase 1, check for merge conflicts and dependency issues with in-flight PRs:
+
+```bash
+# Run merge simulation if on a feature branch
+current_branch="$(git branch --show-current)"
+if [[ "$current_branch" != "master" ]] && [[ "$current_branch" != "main" ]]; then
+  bash scripts/pr-coordinator.sh merge-sim "$current_branch" 2>&1 || true
+fi
+
+# Show current merge queue
+bash scripts/pr-coordinator.sh merge-order 2>&1 || true
+
+# Check for stale worktrees (informational)
+bash scripts/pr-coordinator.sh stale-worktrees 2>&1 || true
+```
+
+If merge conflicts or unmet dependencies are found:
+- Display the findings to the developer
+- Ask: "In-flight PRs have potential conflicts. Proceed with planning anyway? (y/n)"
+- If `n`: exit cleanly, no side effects
+- If `y`: log override via `bd comments add <id> "PR coordination override: proceeding despite in-flight conflicts"`, then continue to Phase 1
+
+---
+
+### Team identity verification
+
+Before starting planning, verify team identity is mapped:
+
+```bash
+bash scripts/forge-team/index.sh verify 2>&1 || true
+```
+
+If verify reports issues, address them before proceeding (the output will include `FORGE_AGENT_7f3a:PROMPT:` directives with exact commands to run).
+
+---
+
 ## Phase 1: Design Intent (Brainstorming)
 
 **Goal**: Capture WHAT to build — purpose, constraints, success criteria, edge cases, approach.
@@ -150,7 +188,6 @@ Questions to cover (adapt to feature, don't ask mechanical copies):
 3. **Success criteria** — How will we know it's done? What is the minimum viable result?
 4. **Edge cases** — What happens when [key dependency] fails / [input] is missing / [state] is ambiguous?
 5. **Technical preferences** — Library A or B? Pattern X or Y? (when real options exist)
-6. **Ambiguity policy** — If a spec gap is found mid-dev, should the agent: (a) make a reasonable choice and document it, or (b) pause and wait for input?
 
 ### Step 3: Propose approaches
 
@@ -169,7 +206,7 @@ Save to `docs/plans/YYYY-MM-DD-<slug>-design.md` with these sections:
 - **Approach selected**: which option and why
 - **Constraints**: hard limits
 - **Edge cases**: decisions made during Q&A
-- **Ambiguity policy**: agent's fallback when spec gaps arise mid-dev
+- **Ambiguity policy**: Use 7-dimension rubric scoring per /dev decision gate. >= 80% confidence: proceed and document. < 80%: stop and ask.
 
 Commit the design doc:
 ```bash
@@ -383,6 +420,9 @@ Expected output: <what running the test/code produces when done>
 - Feature logic SECOND
 - Integration/wiring THIRD
 - Uncertain/ambiguous tasks LAST (so they can be deferred if blocked)
+- **File ownership**: Each task MUST include an `OWNS:` line listing files it will modify
+- No two tasks in the same wave can own the same file
+- Cross-wave ownership is allowed (sequential execution prevents conflicts)
 
 **YAGNI filter** (after initial task draft, before saving):
 
@@ -464,10 +504,15 @@ Do NOT proceed to /dev until ALL are confirmed:
 </HARD-GATE>
 ```
 
-After all HARD-GATE items pass, record the stage transition on the Beads issue:
+After all HARD-GATE items pass, validate context and record the stage transition:
 
 ```bash
-bash scripts/beads-context.sh stage-transition <id> plan dev
+bash scripts/beads-context.sh validate <id>
+bash scripts/beads-context.sh stage-transition <id> plan dev \
+  --summary "<design approach chosen, task count>" \
+  --decisions "<key trade-offs resolved during Q&A>" \
+  --artifacts "docs/plans/YYYY-MM-DD-<slug>-design.md docs/plans/YYYY-MM-DD-<slug>-tasks.md" \
+  --next "<first dev task focus area>"
 ```
 
 ---
@@ -476,20 +521,20 @@ bash scripts/beads-context.sh stage-transition <id> plan dev
 
 ```
 ✓ Phase 1: Design intent captured
-  - Design doc: docs/plans/2026-02-26-stripe-billing-design.md
-  - Approach: Stripe SDK v4 (selected over v3)
-  - Ambiguity policy: Make conservative choice + document in decisions log
+  - Design doc: docs/plans/<date>-<slug>-design.md
+  - Approach: <selected approach> (selected over <alternatives>)
+  - Ambiguity policy: Rubric scoring (>= 80% proceed, < 80% ask)
 
 ✓ Phase 2: Technical research complete
-  - OWASP Top 10: 3 risks identified, 3 mitigations planned
-  - TDD scenarios: 5 identified
-  - Sources: 8 references
+  - OWASP Top 10: <N> risks identified, <N> mitigations planned
+  - TDD scenarios: <N> identified
+  - Sources: <N> references
 
 ✓ Phase 3: Setup complete
-  - Beads: forge-xyz (in_progress)
-  - Branch: feat/stripe-billing
-  - Worktree: .worktrees/stripe-billing (baseline: 24/24 tests passing)
-  - Task list: docs/plans/2026-02-26-stripe-billing-tasks.md (8 tasks)
+  - Beads: <issue-id> (in_progress)
+  - Branch: feat/<slug>
+  - Worktree: .worktrees/<slug> (baseline: <N>/<N> tests passing)
+  - Task list: docs/plans/<date>-<slug>-tasks.md (<N> tasks)
 
 ⏸️  Task list ready for review. Confirm to proceed.
 

package/.cursor/commands/premerge.md

@@ -120,6 +120,16 @@ Output:
 After you merge, run /verify to confirm everything landed correctly.
 ```
 
+### Step 6: Validate Context and Record Stage Transition
+
+```bash
+bash scripts/beads-context.sh validate <id>
+bash scripts/beads-context.sh stage-transition <id> premerge verify \
+  --summary "<docs updated, CI green, PR ready>" \
+  --artifacts "<updated doc files, PR URL>" \
+  --next "<merge instructions for user>"
+```
+
 ```
 <HARD-GATE: /premerge exit>
 Do NOT run gh pr merge.

package/.cursor/commands/review.md

@@ -361,7 +361,13 @@ Do NOT declare /review complete until:
 1. bash .claude/scripts/greptile-resolve.sh stats <pr-number> shows "All Greptile threads resolved"
 2. ALL human reviewer comments are either resolved or have a reply with explanation
 3. gh pr checks <pr-number> shows all checks passing
-4. Stage transition: Run `bash scripts/beads-context.sh stage-transition <id> review premerge` → exit 0 confirmed
+4. Context check: Run `bash scripts/beads-context.sh validate <id>` and address any warnings
+5. Stage transition: Run the following → exit 0 confirmed:
+   bash scripts/beads-context.sh stage-transition <id> review premerge \
+     --summary "<all feedback addressed summary>" \
+     --decisions "<comment resolutions — valid fixes and justified rejections>" \
+     --artifacts "<fixed files, commit SHAs>" \
+     --next "<doc update needs for premerge>"
 </HARD-GATE>
 ```