forge-workflow 0.0.1

package/.claude/commands/verify.md

@@ -0,0 +1,221 @@
+---
+description: Post-merge health check — confirm merge landed, CI is clean, deployments are up
+---
+
+Verify that the merge landed correctly and everything is running properly after merge.
+
+# Verify
+
+This command runs AFTER the user has merged the PR. It checks system health — not documentation (that was handled in `/premerge`).
+
+## Usage
+
+```bash
+/verify
+```
+
+## What This Command Does
+
+### Step 1: Switch to Main and Pull
+
+```bash
+git checkout master
+git pull
+```
+
+Confirm the merge actually landed on main. If the PR isn't merged yet, stop and tell the user to merge first.
+
+### Step 2: Confirm PR Is Merged
+
+Detect the most recently merged PR from the current HEAD commit:
+
+```bash
+gh pr list --state merged --base master --limit 1 --json number,state,mergedAt,mergedBy
+```
+
+- `state` should be `MERGED`
+- If no PR found: the merge may not have landed yet — stop and tell the user to merge first
+- If the wrong PR appears: user can specify the number directly with `gh pr view <number> --json state,mergedAt,mergedBy`
+
+### Step 3: Check CI on Main After Merge
+
+```bash
+gh run list --branch master --limit 5
+```
+
+Check the most recent workflow runs on `master`:
+- All should be passing or in progress
+- If any failed: identify which workflow and what failed
+- Failed CI on main after merge may need a hotfix PR
+
+### Step 4: Check Deployments (if applicable)
+
+Check if the project has a deployment target:
+
+```bash
+# Check deployment status from latest run
+gh run list --branch master --limit 1
+
+# Check Vercel deployments for the merged PR (use number from Step 2)
+gh pr view <number> --json deployments
+```
+
+If deployments exist:
+- Are they showing as successful?
+- Is the production/preview URL responding?
+
+### Step 5: Report Status
+
+**If everything is clean**:
+```
+✅ Merge verified — everything is healthy
+
+  PR: #<number> merged by <user> at <time>
+  CI on master: ✓ All passing
+  Deployments: ✓ Up (if applicable)
+
+  Ready for next feature → run /status
+```
+
+**If issues found**:
+```
+⚠️  Post-merge issues detected
+
+  PR: #<number> merged ✓
+  CI on master: ✗ <workflow-name> failing
+    - Error: <description>
+    - Action needed: <hotfix or investigation>
+
+  Deployments: ✗ <deployment> not responding
+
+  Next: Create hotfix branch or investigate root cause
+```
+
+### Step 6: Clean Up Worktree and Branch
+
+Only run this step after CI is confirmed healthy (Step 3 passed).
+
+Get the merged branch name:
+
+```bash
+gh pr view <number> --json headRefName --jq '.headRefName'
+```
+
+If the branch name cannot be determined (empty output or error), skip cleanup and tell the user to run `git worktree list` and clean up manually.
+
+Find and remove the matching worktree (if it exists):
+
+```bash
+# Get the worktree path for this exact branch
+WORKTREE_PATH=$(git worktree list --porcelain \
+  | awk -v branch="refs/heads/<branch>" '
+      /^worktree / { path=substr($0, 10) }
+      $0 == "branch " branch { print path }
+    ')
+
+if [ -n "$WORKTREE_PATH" ]; then
+  git worktree remove "$WORKTREE_PATH" --force
+  echo "Worktree: removed ✓ ($WORKTREE_PATH)"
+else
+  echo "Worktree: not found (already removed or never created) — skipping"
+fi
+```
+
+If no worktree is found for that branch, skip gracefully with a note: "Worktree: not found (already removed or never created)".
+
+Delete the local branch (safe delete only):
+
+```bash
+git branch -d <branch> 2>/dev/null || echo "Branch: already deleted — skipping"
+```
+
+The `|| echo` fallback handles the case where the branch is already gone (e.g., deleted by a previous run or the remote), so the command never fails the verify step.
+
+Report cleanup in output:
+```
+Worktree: removed ✓
+Branch: <branch-name> deleted ✓
+```
+
+### Step 7: If Issues Found — Create Beads Issue
+
+**Never commit inline.** If something is wrong, create a tracking issue:
+
+```bash
+bd create --title="Post-merge: <description of issue>" --type=bug --priority=1
+```
+
+### Step 8: Close Beads Issue (if healthy)
+
+If everything is clean, close the Beads issue:
+
+```bash
+bd close <id> --reason="Merged and verified on master"
+```
+
+```
+<HARD-GATE: /verify exit>
+Do NOT declare /verify complete until:
+1. gh run list --branch master --limit 3 shows actual CI output (not "should be fine")
+2. If healthy: Beads issue is closed (bd close <id> run and confirmed)
+3. If issues found: Beads tracking issue created for every problem
+4. Worktree removed (or confirmed already gone) — OR Step 6 was intentionally skipped because CI was unhealthy; if skipped, state explicitly: "cleanup deferred, CI was not healthy"
+"It should be fine" is not evidence. Run the command. Show the output.
+</HARD-GATE>
+```
+
+## Rules
+
+- **Never commits** — this command is read-only
+- **Never creates PRs** — if fixes are needed, that's a new /dev cycle
+- **Runs after user confirms merge** — not before
+- **Reports honestly** — if CI is broken on main, say so clearly
+
+## Example Output (Healthy)
+
+```
+✅ Merge verified — everything is healthy
+
+  PR: #89 merged by harshanandak at 2026-02-24T14:30:00Z
+  Branch: feat/auth-refresh deleted ✓
+  CI on master:
+    ✓ Test Suite (ubuntu, node 20): passing
+    ✓ Test Suite (windows, node 22): passing
+    ✓ ESLint: passing
+    ✓ SonarCloud: passing
+    ✓ CodeQL: passing
+  Deployments: N/A (no deployment configured)
+
+  Ready for next feature → run /status
+```
+
+## Example Output (Issues Found)
+
+```
+⚠️  Post-merge issues detected
+
+  PR: #89 merged ✓
+  CI on master:
+    ✓ Test Suite: passing
+    ✗ SonarCloud: quality gate failing
+      - 2 new code smells introduced
+      - Action: investigate or create hotfix
+
+  Created Beads issue: forge-xyz
+  "Post-merge: SonarCloud quality gate failing on master after PR #89"
+
+  Run /status to assess next steps
+```
+
+## 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
+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 (you are here) ✓
+```

package/.claude/rules/greptile-review-process.md

@@ -0,0 +1,285 @@
+# Greptile Review Handling Process
+
+**Purpose**: Standardized process for AI agents to systematically handle Greptile review comments.
+
+**Critical**: This process has been problematic for days. AI agents MUST follow these exact steps for EVERY Greptile comment.
+
+---
+
+## Problem Background
+
+**Previous Issues:**
+- ❌ AI agents replied to PR with general comments instead of replying directly to each Greptile review thread
+- ❌ AI agents didn't mark conversation threads as "resolved" after fixing issues
+- ❌ No systematic process for tracking which Greptile comments are addressed vs pending
+- ❌ Caused confusion and manual tracking overhead for maintainers
+
+**Why This Matters:**
+- Branch protection blocks merge when threads are unresolved
+- Maintainers must manually verify all issues are addressed
+- Inconsistent handling across different AI sessions
+
+---
+
+## Critical Distinction
+
+**Replying vs Resolving:**
+
+1. **Replying** = Adding a comment to the review thread
+   - Uses REST API: `/repos/{owner}/{repo}/pulls/{pr}/comments/{comment_id}/replies`
+   - Creates a threaded response within the review comment
+   - Does NOT change the thread's resolved status
+
+2. **Resolving** = Marking the thread as complete
+   - Uses GraphQL API: `resolveReviewThread` mutation
+   - Changes thread status to "Resolved"
+   - Shows who resolved it and when
+
+**Both are required** by this project's workflow:
+- Reply explains what was fixed and why
+- Resolve marks the thread as addressed
+
+---
+
+## For AI Agents: Mandatory Steps
+
+When Greptile Quality Gate fails (score < 4/5) or when review comments exist:
+
+### Step 1: List ALL Greptile Feedback (Inline + Direct Comments)
+
+Greptile posts feedback in **two places**:
+1. **Inline review threads** — attached to specific code lines (resolvable via GraphQL)
+2. **Direct PR issue comments** — "Additional Comments (N)" posted as regular PR comments (reply with `gh pr comment`)
+
+Always run `list-all` to see both:
+
+```bash
+bash .claude/scripts/greptile-resolve.sh list-all <pr-number>
+```
+
+Or just inline threads (unresolved only):
+
+```bash
+bash .claude/scripts/greptile-resolve.sh list <pr-number> --unresolved
+```
+
+**Output shows:**
+- Thread ID (for resolving inline threads)
+- Comment ID (for replying to inline threads)
+- File path and line number
+- Issue description
+- Direct PR comment IDs and previews (reply with `gh pr comment`)
+
+**Example:**
+```
+✗ UNRESOLVED | docs/ROADMAP.md:282
+  Thread ID: PRRT_kwDORErEU85tuh6I
+  Comment ID: 2787717459
+  Author: greptile-apps
+  Issue: Leaking local Windows paths
+```
+
+### Step 2: For EACH Unresolved Thread (Systematic)
+
+**Process each thread one at a time:**
+
+1. **Read the comment** and understand the issue
+   - Use the file path and line number to locate the code
+   - Understand what Greptile is flagging
+
+2. **Fix the issue** if the comment is valid
+   - Make the necessary code changes
+   - Commit the fix with a clear message
+
+3. **Reply to the thread** with explanation
+   ```bash
+   bash .claude/scripts/greptile-resolve.sh reply <pr-number> <comment-id> "✅ Fixed: [description]
+
+   Changed: [what was changed]
+   Reason: [why this fixes the issue]
+   Commit: [commit-sha]"
+   ```
+
+4. **Resolve the thread**
+   ```bash
+   bash .claude/scripts/greptile-resolve.sh resolve <pr-number> <thread-id>
+   ```
+
+5. **Track progress**: Mark comment as addressed in your notes
+
+**Alternative (all-in-one):**
+```bash
+bash .claude/scripts/greptile-resolve.sh reply-and-resolve <pr-number> <comment-id> <thread-id> "✅ Fixed: [description]
+
+Changed: [what was changed]
+Reason: [why this fixes the issue]
+Commit: [commit-sha]"
+```
+
+### Step 3: Verify All Threads Resolved
+
+```bash
+bash .claude/scripts/greptile-resolve.sh list <pr-number> --unresolved
+```
+
+**Should show**: "No unresolved comments" or empty list
+
+**Confirm with stats:**
+```bash
+bash .claude/scripts/greptile-resolve.sh stats <pr-number>
+```
+
+**Should show**: "✓ All Greptile threads resolved!"
+
+### Step 4: Push Changes & Wait for Re-review
+
+```bash
+git push
+```
+
+**Greptile will automatically:**
+- Re-analyze the PR
+- Update the confidence score
+- Re-run the Quality Gate check
+
+---
+
+## Example Workflow
+
+```bash
+# 1. List unresolved threads
+$ bash .claude/scripts/greptile-resolve.sh list 24 --unresolved
+
+✗ UNRESOLVED | docs/ROADMAP.md:280
+  Thread ID: PRRT_kwDORErEU85tuh6I
+  Comment ID: 2787717459
+  Issue: Leaking local Windows paths
+
+# 2. Fix the issue (edit files, commit changes)
+$ git add docs/ROADMAP.md
+$ git commit -m "fix: replace Windows absolute paths with relative paths"
+
+# 3. Reply and resolve in one step
+$ bash .claude/scripts/greptile-resolve.sh reply-and-resolve 24 2787717459 PRRT_kwDORErEU85tuh6I \
+  "✅ Fixed: Replaced Windows absolute paths with repo-relative paths
+
+Changed: C:\\Users\\...\\plans\\... → .claude/plans/*.md
+Reason: Absolute paths don't exist for other contributors
+Commit: abc123"
+
+✅ Reply posted successfully
+✅ Thread resolved successfully
+
+# 4. Verify all resolved
+$ bash .claude/scripts/greptile-resolve.sh stats 24
+
+Greptile unresolved: 0
+✓ All Greptile threads resolved!
+
+# 5. Push changes
+$ git push
+```
+
+---
+
+## Critical Rules
+
+### ✅ DO:
+- **Reply to EACH comment thread** using the script (not as separate PR comment)
+- **Mark EACH thread as resolved** after fixing using the script
+- **Track progress** (X of Y fixed) in your notes
+- **Wait for Greptile re-review** after pushing fixes
+- **Use comment ID for replies**, thread ID for resolving
+- **Commit fixes BEFORE replying** so you can reference commit SHA
+
+### ❌ DON'T:
+- Post general PR comments about fixes (use threaded replies)
+- Assume threads are auto-resolved (they're not)
+- Skip replying to threads (explain what you fixed)
+- Make multiple commits without resolving threads between them
+- Reply without actually fixing the issue
+- Resolve threads that haven't been fixed yet
+
+---
+
+## Script Commands Reference
+
+### List Threads
+```bash
+# All threads
+bash .claude/scripts/greptile-resolve.sh list <pr-number>
+
+# Only unresolved
+bash .claude/scripts/greptile-resolve.sh list <pr-number> --unresolved
+```
+
+### Reply to Thread
+```bash
+bash .claude/scripts/greptile-resolve.sh reply <pr-number> <comment-id> "<message>"
+```
+
+### Resolve Thread
+```bash
+bash .claude/scripts/greptile-resolve.sh resolve <pr-number> <thread-id>
+```
+
+### Reply and Resolve (Recommended)
+```bash
+bash .claude/scripts/greptile-resolve.sh reply-and-resolve <pr-number> <comment-id> <thread-id> "<message>"
+```
+
+### Batch Resolve (After all issues fixed)
+```bash
+bash .claude/scripts/greptile-resolve.sh resolve-all <pr-number>
+```
+**⚠️ Warning**: Only use after ALL issues are fixed and replied to
+
+### Statistics
+```bash
+bash .claude/scripts/greptile-resolve.sh stats <pr-number>
+```
+
+---
+
+## Integration with `/review` Command
+
+The `/review` command should now include these steps:
+
+1. Run `/review` as usual to analyze PR feedback
+2. For Greptile comments, use the script to:
+   - List unresolved threads
+   - Fix each issue
+   - Reply and resolve systematically
+3. Verify all threads resolved before declaring review complete
+4. Push changes and wait for Greptile re-review
+
+---
+
+## Troubleshooting
+
+### Script fails with "404 Not Found"
+**Cause**: Comment ID or thread ID is incorrect
+**Solution**: Re-run `list` command to get correct IDs
+
+### Reply appears as separate PR comment
+**Cause**: Using wrong API endpoint
+**Solution**: Script handles this automatically, don't manually comment
+
+### Thread not showing as resolved after script
+**Cause**: GitHub UI caching
+**Solution**: Refresh page, or check with GraphQL query
+
+### Greptile score not updating after fixes
+**Cause**: Must push commits to trigger re-analysis
+**Solution**: `git push` and wait 2-3 minutes for Greptile re-scan
+
+---
+
+## Success Criteria
+
+**A review is complete when:**
+- ✅ All Greptile threads are resolved (verified with `stats` command)
+- ✅ All threads have replies explaining fixes
+- ✅ Greptile Quality Gate passes (≥4/5 score)
+- ✅ Branch protection allows merge
+- ✅ No manual tracking needed by maintainers

package/.claude/rules/workflow.md

@@ -0,0 +1,105 @@
+# Forge Workflow Rules
+
+7-stage TDD-first development workflow for any project.
+
+## Workflow Commands
+
+| Stage | Command | Purpose |
+|-------|---------|---------|
+| utility | `/status` | Check current stage, active work, recent completions |
+| 1 | `/plan` | Design intent (brainstorm) → research → branch + worktree + task list |
+| 2 | `/dev` | Subagent-driven TDD per task: implementer → spec review → quality review |
+| 3 | `/validate` | Type check, lint, code review, security, tests — all fresh output |
+| 4 | `/ship` | Push and create PR with design doc reference |
+| 5 | `/review` | Handle ALL PR issues (GitHub Actions, Greptile, SonarCloud) |
+| 6 | `/premerge` | Complete docs on feature branch, hand off PR to user |
+| 7 | `/verify` | Post-merge health check (CI on main, close Beads) |
+
+## Core Principles
+
+### Design-First Planning
+- All features start with Phase 1: one-question-at-a-time Q&A to capture design intent
+- Design doc saved to `docs/plans/YYYY-MM-DD-<slug>-design.md`
+- Research (Phase 2) and task list (Phase 3) follow design approval
+- Phase 1 quality directly determines /dev autonomy — resolve ambiguity upfront
+
+### TDD-First Development
+- Task list pre-made in /plan Phase 3; /dev reads and executes it
+- Each task: implementer subagent → spec compliance reviewer → code quality reviewer
+- RED-GREEN-REFACTOR enforced inside implementer via HARD-GATE
+- Decision gate (7-dimension scoring) fires when spec gap found mid-task
+
+### HARD-GATES at Stage Exits
+- Structural enforcement — not soft instructions
+- Every stage exit has explicit conditions that must be met
+- "Should be fine" and "was passing earlier" are never evidence
+- Run the command, show the output, THEN declare done
+
+### Security Built-In
+- OWASP Top 10 analysis documented in design doc (Phase 2)
+- Security test scenarios identified before /dev
+- Automated scans + manual review at /validate
+
+## Issue Tracking
+
+Use Beads for persistent tracking across sessions:
+```bash
+bd create --title="Feature name" --type=feature   # Create issue
+bd update <id> --status=in_progress               # Claim work
+bd update <id> --comment "Progress"               # Add notes
+bd close <id>                                     # Complete
+bd sync                                           # Sync with git
+```
+
+## Git Workflow
+
+```bash
+# Branch naming
+feat/<feature-slug>
+fix/<bug-slug>
+docs/<doc-slug>
+
+# Commit pattern
+git commit -m "test: add validation tests"     # RED
+git commit -m "feat: implement validation"     # GREEN
+git commit -m "refactor: extract helpers"      # REFACTOR
+
+# Worktrees (required for /dev)
+git worktree add .worktrees/<slug> feat/<slug>
+# .worktrees/ is gitignored
+```
+
+## Configuration
+
+Customize these commands for your stack:
+
+```bash
+# In your project's CLAUDE.md or .claude/rules/
+TYPE_CHECK_COMMAND="bun run typecheck"   # or: npm run typecheck, tsc, etc.
+LINT_COMMAND="bun run lint"               # or: npm run lint, eslint, etc.
+TEST_COMMAND="bun test"                   # or: npm run test, jest, etc.
+SECURITY_SCAN="bunx npm audit"            # or: npm audit, snyk test, etc.
+```
+
+## Skills Integration
+
+### Parallel AI (MANDATORY for Phase 2 web research)
+Use focused skills from `skills/` directory:
+```bash
+Skill("parallel-deep-research")  # Deep analysis, market reports, web research
+```
+
+### sonarcloud (Code quality)
+```bash
+/sonarcloud  # Query PR-specific issues
+```
+
+## Flow Visualization
+
+```
+/plan → /dev → /validate → /ship → /review → /premerge → /verify
+  ↓        ↓        ↓        ↓        ↓          ↓         ↓
+Design   Task-by  Validate   PR      Address    Merge    Verify
++Research  task    +GATE    create   feedback    +docs    CI on
++Tasks    TDD                                   GATE     master
+```