forge-workflow 0.0.4 → 0.0.6

package/.cursor/commands/ship.md

@@ -1,161 +1,209 @@
-
-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.
-
-### 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
-
-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.
-
-If no Beads issue exists (hotfix, external contribution), skip the "Closes" line.
-
-```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]
-
-## Fix
-[What this PR does to solve it — approach, not implementation details]
-
-## Value
-[Who benefits, what improves, what risk is removed]
-
-## Beads
-Closes: <issue-id>
-
-<details>
-<summary>Implementation Details</summary>
-
-### Test Coverage
-- Tests: [count] passing
-- Scenarios covered: [list key scenarios]
-
-### Security Review
-- OWASP Top 10: [summary — applicable risks and mitigations]
-- Automated scan: [result]
-
-### Design Doc
-See: docs/plans/YYYY-MM-DD-<slug>-design.md
-
-### Decisions Log
-See: docs/plans/YYYY-MM-DD-<slug>-decisions.md (if any undocumented decisions arose during /dev)
-
-### Key Decisions
-[From design doc — 3-5 key decisions with reasoning]
-
-### Documentation Updated
-[List docs updated in this PR, or "None — no doc-facing changes"]
-
-### Validation
-- [x] Type check passing
-- [x] Lint passing (0 errors, 0 warnings)
-- [x] All tests passing
-- [x] Security review completed
-
-</details>
-
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
-EOF
-)"
-```
-
-### Step 6: Record Stage Transition
-```bash
-bash scripts/beads-context.sh stage-transition <id> ship review
-```
-
-## 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, awaiting automated checks (Greptile, SonarCloud, GitHub Actions)
-
-Next: /review <pr-number> (after automated checks complete)
-```
-
-## 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
-
-- **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
-- **Wait for checks**: Let GitHub Actions, Greptile, SonarCloud run
-- **NO auto-merge**: Always wait for /review phase
+
+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, awaiting automated checks (Greptile, SonarCloud, GitHub Actions)
+
+Next: /review <pr-number> (after automated checks complete)
+```
+
+## 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
+- **Wait for checks**: Let GitHub Actions, Greptile, SonarCloud run
+- **NO auto-merge**: Always wait for /review phase

package/.cursor/commands/sonarcloud.md

@@ -1,146 +1,146 @@
-
-# SonarCloud Query Command
-
-Pull code quality data from SonarCloud. Requires `SONARCLOUD_TOKEN` environment variable.
-
-## Arguments
-
-- `$ARGUMENTS` - Query type and parameters
-
-## Query Types
-
-| Query | Description | Example |
-|-------|-------------|---------|
-| `issues <project>` | Get open issues | `/sonarcloud issues my-project` |
-| `metrics <project>` | Get code metrics | `/sonarcloud metrics my-project` |
-| `gate <project>` | Quality gate status | `/sonarcloud gate my-project` |
-| `health <project>` | Full health report | `/sonarcloud health my-project` |
-| `pr <project> <pr#>` | PR analysis | `/sonarcloud pr my-project 123` |
-| `hotspots <project>` | Security hotspots | `/sonarcloud hotspots my-project` |
-| `history <project>` | Analysis history | `/sonarcloud history my-project` |
-
-## Filters (append to query)
-
-| Filter | Description | Example |
-|--------|-------------|---------|
-| `--branch <name>` | Filter by branch | `--branch develop` |
-| `--severity <levels>` | Filter severity | `--severity BLOCKER,CRITICAL` |
-| `--type <types>` | Filter issue type | `--type BUG,VULNERABILITY` |
-| `--new-code` | Only new code issues | `--new-code` |
-
-## Instructions
-
-1. Parse the query from `$ARGUMENTS` to determine:
-   - Query type (issues, metrics, gate, health, pr, hotspots, history)
-   - Project key
-   - Optional filters (branch, severity, type, new-code, etc.)
-2. Check for `SONARCLOUD_TOKEN` environment variable. If not set, inform user.
-3. Check for `SONARCLOUD_ORG` environment variable or ask user for organization key.
-4. Execute the appropriate API call using curl or the TypeScript client at `next-app/src/lib/integrations/sonarcloud.ts`
-5. Format and present results clearly:
-   - For issues: Group by severity/type, show file, line, message
-   - For metrics: Show as table with metric name and value
-   - For quality gate: Show pass/fail with failed conditions
-   - For health: Comprehensive summary with all data
-6. Offer follow-up actions:
-   - "Show issues in specific file?"
-   - "Get more details on a specific issue?"
-   - "Compare with another branch?"
-
-## Example Outputs
-
-### Issues Query
-
-```
-📋 Open Issues for my-project (branch: main)
-
-Total: 45 issues
-
-By Severity:
-  🔴 BLOCKER: 2
-  🟠 CRITICAL: 5
-  🟡 MAJOR: 18
-  ⚪ MINOR: 15
-  ⚫ INFO: 5
-
-By Type:
-  🐛 BUG: 8
-  🔓 VULNERABILITY: 3
-  💩 CODE_SMELL: 34
-
-Top Issues:
-1. [CRITICAL] src/auth/login.ts:42 - SQL injection vulnerability
-2. [BLOCKER] src/api/users.ts:156 - Null pointer dereference
-...
-```
-
-### Metrics Query
-
-```
-📊 Metrics for my-project
-
-| Metric | Value |
-|--------|-------|
-| Lines of Code | 51,234 |
-| Coverage | 78.5% |
-| Duplications | 3.2% |
-| Bugs | 8 |
-| Vulnerabilities | 3 |
-| Code Smells | 34 |
-| Technical Debt | 4d 2h |
-| Maintainability | A |
-| Reliability | B |
-| Security | A |
-```
-
-### Quality Gate Query
-
-```
-🚦 Quality Gate: ❌ FAILED
-
-Failed Conditions:
-| Metric | Threshold | Actual |
-|--------|-----------|--------|
-| Coverage on New Code | ≥ 80% | 65.3% |
-| New Bugs | = 0 | 2 |
-
-Passed Conditions:
-| Metric | Threshold | Actual |
-|--------|-----------|--------|
-| New Vulnerabilities | = 0 | 0 |
-| Duplicated Lines | ≤ 3% | 1.2% |
-```
-
-## API Reference
-
-Base URL: `https://sonarcloud.io/api`
-
-### Key Endpoints
-
-```bash
-# Issues
-curl -H "Authorization: Bearer $TOKEN" \
-  "https://sonarcloud.io/api/issues/search?organization=$ORG&componentKeys=$PROJECT&resolved=false"
-
-# Metrics
-curl -H "Authorization: Bearer $TOKEN" \
-  "https://sonarcloud.io/api/measures/component?component=$PROJECT&metricKeys=bugs,vulnerabilities,coverage"
-
-# Quality Gate
-curl -H "Authorization: Bearer $TOKEN" \
-  "https://sonarcloud.io/api/qualitygates/project_status?projectKey=$PROJECT"
-
-# Hotspots
-curl -H "Authorization: Bearer $TOKEN" \
-  "https://sonarcloud.io/api/hotspots/search?projectKey=$PROJECT&status=TO_REVIEW"
-```
-
-## Full Skill Reference
-
-See `skills/sonarcloud-analysis/SKILL.md` for complete API documentation including:
-
-- All endpoints and parameters
-- Response structures
-- Pagination handling
-- Advanced filtering
-- Integration patterns
+
+# SonarCloud Query Command
+
+Pull code quality data from SonarCloud. Requires `SONARCLOUD_TOKEN` environment variable.
+
+## Arguments
+
+- `$ARGUMENTS` - Query type and parameters
+
+## Query Types
+
+| Query | Description | Example |
+|-------|-------------|---------|
+| `issues <project>` | Get open issues | `/sonarcloud issues my-project` |
+| `metrics <project>` | Get code metrics | `/sonarcloud metrics my-project` |
+| `gate <project>` | Quality gate status | `/sonarcloud gate my-project` |
+| `health <project>` | Full health report | `/sonarcloud health my-project` |
+| `pr <project> <pr#>` | PR analysis | `/sonarcloud pr my-project 123` |
+| `hotspots <project>` | Security hotspots | `/sonarcloud hotspots my-project` |
+| `history <project>` | Analysis history | `/sonarcloud history my-project` |
+
+## Filters (append to query)
+
+| Filter | Description | Example |
+|--------|-------------|---------|
+| `--branch <name>` | Filter by branch | `--branch develop` |
+| `--severity <levels>` | Filter severity | `--severity BLOCKER,CRITICAL` |
+| `--type <types>` | Filter issue type | `--type BUG,VULNERABILITY` |
+| `--new-code` | Only new code issues | `--new-code` |
+
+## Instructions
+
+1. Parse the query from `$ARGUMENTS` to determine:
+   - Query type (issues, metrics, gate, health, pr, hotspots, history)
+   - Project key
+   - Optional filters (branch, severity, type, new-code, etc.)
+2. Check for `SONARCLOUD_TOKEN` environment variable. If not set, inform user.
+3. Check for `SONARCLOUD_ORG` environment variable or ask user for organization key.
+4. Execute the appropriate API call using curl or the TypeScript client at `next-app/src/lib/integrations/sonarcloud.ts`
+5. Format and present results clearly:
+   - For issues: Group by severity/type, show file, line, message
+   - For metrics: Show as table with metric name and value
+   - For quality gate: Show pass/fail with failed conditions
+   - For health: Comprehensive summary with all data
+6. Offer follow-up actions:
+   - "Show issues in specific file?"
+   - "Get more details on a specific issue?"
+   - "Compare with another branch?"
+
+## Example Outputs
+
+### Issues Query
+
+```
+📋 Open Issues for my-project (branch: main)
+
+Total: 45 issues
+
+By Severity:
+  🔴 BLOCKER: 2
+  🟠 CRITICAL: 5
+  🟡 MAJOR: 18
+  ⚪ MINOR: 15
+  ⚫ INFO: 5
+
+By Type:
+  🐛 BUG: 8
+  🔓 VULNERABILITY: 3
+  💩 CODE_SMELL: 34
+
+Top Issues:
+1. [CRITICAL] src/auth/login.ts:42 - SQL injection vulnerability
+2. [BLOCKER] src/api/users.ts:156 - Null pointer dereference
+...
+```
+
+### Metrics Query
+
+```
+📊 Metrics for my-project
+
+| Metric | Value |
+|--------|-------|
+| Lines of Code | 51,234 |
+| Coverage | 78.5% |
+| Duplications | 3.2% |
+| Bugs | 8 |
+| Vulnerabilities | 3 |
+| Code Smells | 34 |
+| Technical Debt | 4d 2h |
+| Maintainability | A |
+| Reliability | B |
+| Security | A |
+```
+
+### Quality Gate Query
+
+```
+🚦 Quality Gate: ❌ FAILED
+
+Failed Conditions:
+| Metric | Threshold | Actual |
+|--------|-----------|--------|
+| Coverage on New Code | ≥ 80% | 65.3% |
+| New Bugs | = 0 | 2 |
+
+Passed Conditions:
+| Metric | Threshold | Actual |
+|--------|-----------|--------|
+| New Vulnerabilities | = 0 | 0 |
+| Duplicated Lines | ≤ 3% | 1.2% |
+```
+
+## API Reference
+
+Base URL: `https://sonarcloud.io/api`
+
+### Key Endpoints
+
+```bash
+# Issues
+curl -H "Authorization: Bearer $TOKEN" \
+  "https://sonarcloud.io/api/issues/search?organization=$ORG&componentKeys=$PROJECT&resolved=false"
+
+# Metrics
+curl -H "Authorization: Bearer $TOKEN" \
+  "https://sonarcloud.io/api/measures/component?component=$PROJECT&metricKeys=bugs,vulnerabilities,coverage"
+
+# Quality Gate
+curl -H "Authorization: Bearer $TOKEN" \
+  "https://sonarcloud.io/api/qualitygates/project_status?projectKey=$PROJECT"
+
+# Hotspots
+curl -H "Authorization: Bearer $TOKEN" \
+  "https://sonarcloud.io/api/hotspots/search?projectKey=$PROJECT&status=TO_REVIEW"
+```
+
+## Full Skill Reference
+
+See `skills/sonarcloud-analysis/SKILL.md` for complete API documentation including:
+
+- All endpoints and parameters
+- Response structures
+- Pagination handling
+- Advanced filtering
+- Integration patterns