forge-workflow 0.0.3 → 0.0.5

package/.cline/workflows/ship.md

@@ -1,131 +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: 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
+
+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/.cline/workflows/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