forge-workflow 0.0.9 → 0.1.0-beta.2

package/.cursor/commands/ship.md

@@ -1,210 +0,0 @@
-
-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/.cursor/commands/sonarcloud.md

@@ -1,146 +0,0 @@
-
-# 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

package/.cursor/commands/status.md

@@ -1,87 +0,0 @@
-
-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>`