forge-workflow 0.0.2 → 0.0.4

package/.cursor/commands/ship.md

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

package/.cursor/commands/sonarcloud.md

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

package/.cursor/commands/status.md

@@ -0,0 +1,45 @@
+
+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 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
+
+## 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/.cursor/commands/validate.md

@@ -0,0 +1,279 @@
+
+> **Note:** Three things share the "validate" name in Forge:
+> - `/validate` (this command): Workflow Stage 3 — rebases onto the base branch, then runs type/lint/test/security checks
+> - `forge-preflight` (formerly forge-validate): CLI tool — checks prerequisites before a stage
+> - `bun run check` (scripts/validate.sh): Local quality gate — runs type/lint/test/security checks only (does NOT rebase; assumes branch is already current with the base branch)
+
+Run comprehensive validation including type checking, linting, code review, security review, and tests.
+
+# Validate
+
+This command validates all code before creating a pull request.
+
+## Usage
+
+```bash
+/validate
+```
+
+Or use the validation script (checks only — no rebase):
+
+```bash
+bun run check    # Runs lint/test/security checks only. Does NOT rebase onto the base branch.
+                 # Use /validate for the full workflow (rebase + checks).
+```
+
+```
+<HARD-GATE: /validate entry — rebase onto latest base branch>
+Before running ANY validation checks:
+
+0. Resolve the base branch dynamically (do NOT hardcode master or main):
+   BASE=$(git remote show origin 2>/dev/null | grep 'HEAD branch' | awk '{print $NF}')
+   if [ -z "$BASE" ] || [ "$BASE" = "(unknown)" ]; then BASE="master"; fi
+
+   This handles repos using main, master, or any other default branch.
+   Falls back to "master" when HEAD is unresolved (detached remote, empty repo).
+
+1. Fetch latest base branch:
+   git fetch origin "$BASE" || { echo "✗ Fetch failed — cannot verify branch freshness"; exit 1; }
+
+   The `|| { ...; exit 1; }` guard ensures fetch failures are never silently skipped.
+
+2. Check if branch is behind:
+   BEHIND=$(git rev-list --count HEAD..origin/"$BASE")
+
+3. If BEHIND > 0:
+   a. Run: git rebase origin/"$BASE" || REBASE_FAILED=1
+   b. If rebase succeeds (REBASE_FAILED unset): print "✓ Rebased onto latest $BASE ($BEHIND commits integrated)"
+   c. If rebase fails (REBASE_FAILED=1 — conflicts or any other error):
+      - Capture conflicting files BEFORE aborting: git diff --name-only --diff-filter=U
+      - Run: git rebase --abort
+      - Print the captured conflicting file list
+      - Print: "✗ Rebase conflict — resolve manually, then re-run /validate"
+      - STOP. Do NOT proceed to any validation checks.
+
+4. If BEHIND = 0:
+   Print "✓ Branch is up-to-date with $BASE" and continue.
+
+Rationale: Without this step, validation checks run against stale code that doesn't
+include recent base branch changes. Integration issues are only caught after the PR is
+created, wasting CI cycles and review time. Rebasing here ensures /validate results
+reflect the true state of what will be merged.
+</HARD-GATE>
+```
+
+## What This Command Does
+
+**Quick Start**: Run `bun run check` to execute the full validation pipeline (implemented in `scripts/validate.sh`). The npm script is named `check`; the workflow command is `/validate`. See individual steps below for details.
+
+### Step 1: Type Check
+```bash
+# Run your project's type check command
+bun run typecheck    # or: npm run typecheck, tsc, etc.
+```
+- Verify all TypeScript types are valid
+- No `any` types allowed
+- Strict mode enforcement
+
+### Step 2: Lint
+```bash
+# Run your project's lint command
+bun run lint    # or: npm run lint, eslint ., etc.
+```
+- Linting rules
+- Code style consistency
+- Best practices compliance
+
+### Step 3: Code Review (if available)
+```bash
+/code-review:code-review
+```
+- Static code analysis
+- Code quality check
+- Potential issues flagged
+
+### Step 4: Security Review
+
+**OWASP Top 10 Checklist**:
+- A01: Broken Access Control
+- A02: Cryptographic Failures
+- A03: Injection
+- A04: Insecure Design
+- A05: Security Misconfiguration
+- A06: Vulnerable Components
+- A07: Authentication Failures
+- A08: Data Integrity Failures
+- A09: Logging & Monitoring Failures
+- A10: Server-Side Request Forgery
+
+**Automated Security Scan**:
+```bash
+# Run your project's security scan
+npm audit    # or: bun audit, snyk test, etc.
+```
+
+**Manual Review**:
+- Review security test scenarios (from design doc — `## Technical Research` section)
+- Verify security mitigations implemented
+- Check for sensitive data exposure
+
+### Step 5: Tests
+```bash
+# Run your project's test command
+bun test    # or: npm run test, jest, vitest, etc.
+```
+- All tests passing
+- Includes security test scenarios
+- TDD tests from /dev phase
+
+> **💭 Plan-Act-Reflect Checkpoint**
+> Before declaring validation complete:
+> - Are all security test scenarios from your design doc actually implemented and passing?
+> - Did you verify OWASP Top 10 mitigations, not just check a box?
+> - Are there edge cases or integration scenarios you haven't tested?
+>
+> **If unsure**: Re-read the `## Technical Research` section in `docs/plans/YYYY-MM-DD-<slug>-design.md`
+
+## On Validation Failure: 4-Phase Debug Mode
+
+> **Iron Law: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST**
+>
+> Every fix attempt without a diagnosed root cause wastes time and masks the real problem.
+
+### Phase D1: Reproduce
+
+Confirm the failure is deterministic. Capture the exact error.
+
+- Run the failing command fresh — do not rely on cached output
+- Record: exact command, exact error message, exact line number
+- If intermittent: run 3 times, document frequency
+
+### Phase D2: Root-Cause Trace
+
+Trace to the source, not the symptom. **Fix at source, not at symptom.**
+
+- Read the stack trace — where does it originate?
+- Is it a test bug, an implementation bug, or a config bug?
+- What changed recently that could have caused this?
+- Read the actual failing line and surrounding context
+
+### Phase D3: Fix
+
+ONE minimal fix. ONE change at a time.
+
+1. Write the failing test FIRST (if not already a test failure)
+2. Make the smallest possible change to fix the root cause
+3. Do not fix multiple things in one commit
+4. Do not "also improve" unrelated code while fixing
+
+### Phase D4: Verify
+
+Re-run full validation from the beginning.
+
+- Do not declare fixed until you have run the full validate suite
+- Show fresh output — not "it should be fine now"
+- All checks must pass, not just the one that was failing
+
+<HARD-GATE: 3+ fix attempts>
+STOP. Question architecture before Fix #4.
+
+If you have attempted 3+ fixes without resolution:
+1. Step back — is the approach fundamentally wrong?
+2. Read the original spec/design doc
+3. Ask: "Am I fixing symptoms or the real problem?"
+4. Consider: revert all changes and start fresh with better understanding
+
+"Quick fix for now" is not a valid fix strategy.
+</HARD-GATE>
+
+### Red Flags — STOP if you hear yourself saying:
+
+- "Quick fix for now"
+- "It's probably X"
+- "I don't fully understand but this might work"
+- "Should be fixed now"
+- "It was passing earlier"
+- "I'm confident this is right"
+
+**None of these are evidence. Run the command. Show the output.**
+
+### Step 6: Handle Failures
+
+If any check fails:
+```bash
+# Create Beads issue for problems
+bd create "Fix <issue-description>"
+
+# Mark current issue as blocked
+bd update <current-id> --status blocked --comment "Blocked by <new-issue-id>"
+
+# Output what needs fixing
+```
+
+If all pass:
+
+```
+<HARD-GATE: /validate exit>
+Do NOT output any variation of "check complete", "ready to ship", or proceed to /ship
+until ALL FOUR show fresh output in this session:
+
+1. Type check: [command run] → [actual output] → exit 0 confirmed
+2. Lint: [command run] → [actual output] → 0 errors, 0 warnings confirmed
+3. Tests: [command run] → [actual output] → N/N passing confirmed
+4. Security scan: [command run] → [actual output] → no critical issues confirmed
+
+"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
+</HARD-GATE>
+```
+
+## Example Output (Success)
+
+```
+✓ Type check: Passed
+✓ Lint: Passed
+✓ Code review: No issues
+✓ Security Review:
+  - OWASP Top 10: All mitigations verified
+  - Automated scan: No vulnerabilities
+  - Manual review: Security tests passing
+✓ Tests: 15/15 passing (TDD complete)
+
+Ready for /ship
+```
+
+## Example Output (Failure)
+
+```
+✗ Tests: 2/15 failing
+  - validation.test.ts: Assertion failed
+  - auth.test.ts: Timeout exceeded
+
+✓ Beads issue created: bd-k8m3 "Fix validation test"
+✓ Current issue marked: Blocked by bd-k8m3
+
+Fix issues then re-run /validate
+```
+
+## 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 (you are here)
+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
+```
+
+## Tips
+
+- **All checks must pass**: Don't proceed to /ship with failures
+- **Security is mandatory**: OWASP Top 10 review required for all features
+- **Create issues for failures**: Track problems in Beads
+- **TDD helps**: Tests should already pass from /dev phase
+- **Fix before shipping**: Resolve all issues before creating PR