forge-workflow 0.0.1

package/.claude/commands/ship.md

@@ -0,0 +1,134 @@
+---
+description: Create PR with comprehensive documentation
+---
+
+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: Update Beads
+```bash
+bd update <id> --status done
+bd sync
+```
+
+### Step 3: Push Branch
+```bash
+git push -u origin <branch-name>
+```
+
+### Step 4: Create PR
+
+```bash
+gh pr create --title "feat: <feature-name>" --body "$(cat <<'EOF'
+## Summary
+[Auto-generated from commits and design doc]
+
+## 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)
+
+## Beads Issue
+Closes: <issue-id>
+
+## Key Decisions
+[From design doc - 3-5 key decisions with reasoning]
+
+## TDD Test Coverage
+- Unit tests: [count] tests, [X] scenarios
+- Integration tests: [count] tests
+- E2E tests: [count] tests
+- All tests passing ✓
+
+## Security Review
+- OWASP Top 10: All mitigations implemented
+- Security tests: [count] scenarios passing
+- Automated scan: No vulnerabilities
+
+## Test Plan
+- [x] Type check passing
+- [x] Lint passing
+- [x] Code review passing
+- [x] E2E tests passing
+- [x] Security review completed
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+### Step 5: 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)
+✓ Beads: Marked done & synced (forge-xyz)
+✓ Pushed: feat/stripe-billing
+✓ PR created: https://github.com/.../pull/123
+  - Beads linked: forge-xyz
+  - Design doc linked: docs/plans/2026-02-26-stripe-billing-design.md
+  - Decisions log linked: docs/plans/2026-02-26-stripe-billing-decisions.md
+  - Test coverage documented
+  - Security review documented
+
+PR Summary:
+  - 12 commits
+  - 18 test cases, all passing
+  - OWASP Top 10 security review completed
+  - 3 key architectural decisions documented
+
+⏸️  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
+
+- **Complete PR body**: Include design doc, decisions log, and test coverage
+- **Link everything**: Design doc, decisions log, Beads issue
+- **Document security**: OWASP Top 10 review in PR body
+- **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/.claude/commands/sonarcloud.md

@@ -0,0 +1,152 @@
+---
+name: SonarCloud Query
+description: Pull issues, metrics, quality gates, and analysis data from SonarCloud
+category: Code Quality
+tags: [sonarcloud, issues, metrics, quality]
+---
+
+# 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/.claude/commands/status.md

@@ -0,0 +1,77 @@
+---
+description: Check current stage and context
+---
+
+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 1: Check Project Health
+```bash
+bd stats
+```
+- How many open / in-progress / completed issues?
+- Any blocked issues?
+
+### Step 2: Check Active Work
+```bash
+# Active Beads issues
+bd list --status in_progress
+```
+
+For each in-progress issue, show compact progress:
+```bash
+bash scripts/beads-context.sh parse-progress <issue-id>
+```
+Display the compact output (e.g., "3/7 tasks done | Last: Validation logic (def5678)")
+
+Hint: `bd show <id>` for full context on any issue.
+
+### Step 3: Review Recent Work
+```bash
+# Recent commits
+git log --oneline -10
+
+# Recently completed Beads
+bd list --status completed --limit 5
+```
+
+### Step 4: 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
+
+## Example Output
+
+```
+✓ Project Health: 3 open, 1 in-progress, 12 completed
+
+Active Work:
+  - forge-ctc: Clean up stale workflow refs (in_progress)
+    3/7 tasks done | Last: Validation logic (def5678)
+    → bd show forge-ctc for full context
+
+Recent Completions:
+  - forge-uto: Sync AGENTS.md with agent cleanup (closed 2 days ago)
+  - forge-abc: Auth refresh tokens (closed 5 days ago)
+
+Context: Continuing work
+
+Next: Resume with /dev or /validate (check issue status)
+```
+
+## 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/.claude/commands/validate.md

@@ -0,0 +1,237 @@
+---
+description: Complete validation (type/lint/tests/security)
+---
+
+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 unified validation script:
+
+```bash
+bun run check    # Runs all validation steps automatically (check is the npm script name; /validate is the workflow command)
+```
+
+## 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