forge-workflow 0.0.1

package/.claude/commands/premerge.md

@@ -0,0 +1,179 @@
+---
+description: Complete all doc updates on feature branch, then hand off PR to user for merge
+---
+
+Prepare the pull request for merge by completing ALL documentation updates on the feature branch, then hand off to the user.
+
+# Premerge
+
+**The actual merge is always done by the user in the GitHub UI — never by this command.**
+
+This command makes the PR 100% complete: code + tests + docs in one unit. After this, the user merges once and there are no follow-up doc PRs needed.
+
+## Usage
+
+```bash
+/premerge <pr-number>
+```
+
+## What This Command Does
+
+### Step 1: Verify All CI Checks Pass
+
+```bash
+gh pr checks <pr-number>
+```
+
+All checks must be green before proceeding. If any fail, run `/review <pr-number>` first.
+
+### Step 2: Warn If Branch Is Behind Master
+
+```bash
+gh pr view <pr-number> --json baseRefName,headRefName
+git fetch origin master
+git status
+```
+
+If the feature branch is behind `master`, tell the user to rebase first:
+
+```
+⚠️  Branch is behind master — rebase before updating docs to avoid conflicts:
+    git rebase origin/master
+    git push --force-with-lease
+```
+
+### Step 3: Update ALL Relevant Documentation (on feature branch)
+
+Check each of the following and update if the feature affects it. Be selective — only update what genuinely changed.
+
+**A. `CHANGELOG.md`** (always):
+- Add entry under `## [Unreleased]` heading (create heading if not present)
+- Use [Keep a Changelog](https://keepachangelog.com/) categories:
+  - **Added**: New features
+  - **Changed**: Changes to existing functionality
+  - **Fixed**: Bug fixes
+  - **Removed**: Removed features
+- Include: feature name, PR number, Beads ID
+- Example:
+  ```markdown
+  ## [Unreleased]
+
+  ### Added
+  - Authentication refresh tokens (PR #89, forge-a3f8)
+  ```
+
+**B. `README.md`** (if user-facing changes):
+- Features list, configuration options, usage examples
+
+**C. `docs/reference/API_REFERENCE.md`** (if API changes):
+- New endpoints, request/response schemas, authentication
+
+**D. Architecture docs** (if structural changes):
+- `docs/architecture/` diagrams, decision records (ADRs)
+
+**E. `CLAUDE.md` — USER section only** (if project conventions changed):
+```
+<!-- USER:START - Add project-specific learnings here as you work -->
+...update only between these markers...
+<!-- USER:END -->
+```
+⚠️  NEVER touch other managed blocks (e.g., `<!-- AGENT:START/END -->`).
+
+**F. `AGENTS.md`** (if agent config, skills, or cross-agent workflow changed):
+- Update relevant sections describing agent capabilities or workflow
+
+**G. `docs/WORKFLOW.md`** (if the workflow itself changed):
+- Update stage descriptions or workflow tables
+
+**Commit doc updates to feature branch**:
+
+```bash
+git add CHANGELOG.md README.md docs/ AGENTS.md CLAUDE.md
+git commit -m "docs: update documentation for <feature-name>
+
+- Updated: [list files changed]
+- Reason: [brief explanation]"
+
+git push
+```
+
+⚠️  **After pushing**: CI will re-trigger (Greptile, SonarCloud, etc.). Wait for checks to pass. If new Greptile comments appear on the doc changes, run `/review <pr-number>` again.
+
+### Step 4: Sync Beads
+
+```bash
+bd sync
+```
+
+### Step 5: Hand Off — STOP HERE
+
+**DO NOT run `gh pr merge`.** Present the PR and wait for the user to merge.
+
+Output:
+
+```
+✅ PR #<number> is ready to merge
+
+  All checks: ✓ passing
+  Documentation: ✓ updated on feature branch
+  Beads: ✓ synced
+
+  👉 Please merge in the GitHub UI:
+     https://github.com/<owner>/<repo>/pull/<number>
+
+  Recommended: Squash and merge (keeps main history clean)
+
+After you merge, run /verify to confirm everything landed correctly.
+```
+
+```
+<HARD-GATE: /premerge exit>
+Do NOT run gh pr merge.
+Do NOT suggest merging.
+/premerge ends here. Output the PR URL and status. Wait for user.
+
+"After you merge, run /verify to confirm everything landed correctly."
+</HARD-GATE>
+```
+
+## Example Output
+
+```
+✓ CI checks: All passing
+✓ Branch: Up to date with master
+✓ Documentation updated:
+  - CHANGELOG.md: Entry added under [Unreleased]
+  - README.md: Features list updated
+  - CLAUDE.md: USER section updated with new pattern
+  - Committed: docs: update documentation for auth-refresh
+✓ CI re-triggered after doc push — all checks still passing
+✓ Beads synced
+
+✅ PR #89 is ready to merge
+
+  👉 Please merge in the GitHub UI:
+     https://github.com/harshanandak/forge/pull/89
+
+After you merge, run /verify
+```
+
+## Rules
+
+- **NEVER run `gh pr merge`** — blocked by PreToolUse hook in `.claude/settings.json`
+- **CLAUDE.md USER section only** — never touch other managed blocks
+- **Warn if branch is behind** — tell user to rebase before doc updates
+- **Re-check CI after doc push** — doc commits re-trigger full CI pipeline
+- **One PR, complete** — code + tests + docs merged together, no follow-up doc PRs
+
+## 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 (you are here)
+Stage 7: /verify     → Post-merge CI check on main
+```

package/.claude/commands/research.md

@@ -0,0 +1,42 @@
+---
+description: Deep research with parallel-deep-research, document findings
+---
+
+> **Note**: `/research` is now Phase 2 of `/plan`.
+>
+> The research phase has been absorbed into the `/plan` command, which runs a full 3-phase workflow:
+> - **Phase 1**: Brainstorming — design intent, constraints, success criteria
+> - **Phase 2**: Technical research — web search, OWASP, codebase exploration, TDD scenarios
+> - **Phase 3**: Setup — branch, worktree, Beads issue, task list
+>
+> Run `/plan <feature-slug>` to start the complete planning workflow.
+
+# Research (Legacy Alias)
+
+This command previously ran a standalone research phase. It is now embedded in `/plan` as Phase 2.
+
+## If you want to run just the research phase
+
+Jump to Phase 2 of `/plan` manually:
+
+1. Read or create the design doc at `docs/plans/YYYY-MM-DD-<slug>-design.md`
+2. Run parallel web search using the `parallel-deep-research` skill
+3. Run OWASP Top 10 analysis for the feature
+4. Use the Explore agent for codebase exploration
+5. Identify at least 3 TDD test scenarios
+6. Append findings under `## Technical Research` in the design doc
+
+Then continue with `/plan <slug> --continue` to run Phase 3 (setup + task list).
+
+## 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
+```

package/.claude/commands/review.md

@@ -0,0 +1,442 @@
+---
+description: Address ALL PR issues (GitHub Actions, Greptile, SonarCloud, CI/CD)
+---
+
+Process ALL pull request issues including GitHub Actions failures, Greptile inline comments, SonarCloud analysis, and other CI/CD checks.
+
+# Review
+
+This command handles ALL issues that arise after creating a pull request.
+
+## Usage
+
+```bash
+/review <pr-number>
+```
+
+## What This Command Does
+
+### Step 1: Fetch Complete PR Status
+```bash
+# Get full PR details including all checks
+gh pr view <pr-number> --json number,url,isDraft,reviews,statusCheckRollup,comments
+
+# Check individual status checks
+gh pr checks <pr-number>
+```
+
+Review ALL status checks:
+- GitHub Actions workflows
+- Greptile code review (inline comments + summary)
+- SonarCloud quality gate
+- Any other CI/CD integrations
+- Vercel deployments
+- Security scanners
+
+### Step 2: Address GitHub Actions Failures
+
+If any GitHub Actions workflows fail:
+
+```bash
+# View failed workflow logs
+gh run view <run-id> --log-failed
+
+# Identify failure cause:
+# - Build failures
+# - Test failures
+# - Lint/type check failures
+# - Deployment failures
+# - Security scan failures
+```
+
+**For each failure**:
+1. **Analyze the error**: Read logs to understand root cause
+2. **Fix the issue**: Make necessary code changes
+3. **Re-run checks**: GitHub Actions will auto-rerun on push
+4. **Document fix**: Note what was fixed in commit message
+
+**Common GitHub Actions Issues**:
+- Build failures: Missing dependencies, compilation errors
+- Test failures: Failing test cases (should not happen if /validate passed)
+- Lint failures: Code style violations
+- Type failures: TypeScript type errors
+- Deployment failures: Env vars, configuration issues
+
+### Step 3: Process Greptile Review
+
+Greptile provides TWO types of feedback:
+1. **Inline comments** on specific code lines
+2. **Summary** with overall recommendations
+
+**IMPORTANT**: Use the **systematic Greptile resolution process** documented in `.claude/rules/greptile-review-process.md`. This process has been standardized to ensure:
+- All threads are replied to directly (not as separate PR comments)
+- All threads are marked as resolved after fixing
+- No manual tracking overhead for maintainers
+
+#### 3A. Check Greptile Inline Comments (Use Systematic Process)
+
+**Step 1: List all unresolved threads**
+```bash
+bash .claude/scripts/greptile-resolve.sh list <pr-number> --unresolved
+```
+
+This shows:
+- Thread ID (for resolving)
+- Comment ID (for replying)
+- File path and line number
+- Issue description
+
+**Step 2: For EACH unresolved thread:**
+
+1. **Understand the issue**
+   - Read the comment carefully
+   - Check the file and line number
+
+2. **Categorize the comment**:
+   - **Valid**: Should be implemented (security issue, bug, clear improvement)
+   - **Invalid**: Greptile misunderstood context
+   - **Conflicting**: Contradicts research decisions with good reason
+   - **Out of scope**: Valid but not for this PR
+
+3. **Fix the issue** (if valid)
+   - Make code changes
+   - Commit with clear message
+
+4. **Reply and resolve** (for ALL comments, even invalid ones)
+   ```bash
+   # For valid issues (fixed):
+   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]"
+
+   # For invalid/conflicting issues:
+   bash .claude/scripts/greptile-resolve.sh reply-and-resolve <pr-number> <comment-id> <thread-id> \
+     "This approach is correct because:
+     - Reasoning: [from design doc]
+     - Evidence: [link to source]
+     - Alternative considered: [what Greptile suggested]
+     - Why rejected: [specific reason]
+
+     See: docs/plans/YYYY-MM-DD-<slug>-design.md (Decision #X)"
+   ```
+
+**Step 3: Verify all resolved**
+```bash
+bash .claude/scripts/greptile-resolve.sh stats <pr-number>
+```
+Should show: "✓ All Greptile threads resolved!"
+
+**See complete process**: `.claude/rules/greptile-review-process.md`
+
+#### 3B. Check Greptile Summary
+```bash
+# Greptile usually posts a summary comment on the PR
+# Review the overall assessment and recommendations
+```
+
+The summary typically includes:
+- Overall code quality assessment
+- Key issues to address
+- Security concerns
+- Performance considerations
+- Best practice violations
+
+### Step 4: Analyze SonarCloud (via sonarcloud skill)
+
+```bash
+# Use sonarcloud skill to query PR-specific issues
+/sonarcloud
+```
+
+**What SonarCloud does**: Static code analysis for quality, security, and maintainability
+
+**How it helps**:
+- Identifies code smells and technical debt
+- Finds security vulnerabilities (complementing OWASP Top 10)
+- Calculates code coverage
+- Tracks code duplication
+- Assesses maintainability
+
+**Query PR-specific data**:
+- Quality gate status (pass/fail)
+- New issues introduced in this PR
+- Security hotspots
+- Code coverage changes
+- Technical debt added
+
+**Prioritize issues**:
+1. **Blocker/Critical**: Must fix before merge
+2. **Major**: Should fix if valid
+3. **Minor/Info**: Optional improvements
+
+### Step 5: Check Other CI/CD Tools
+
+Review any other automated checks:
+- **Vercel**: Preview deployment successful?
+- **Security scanners**: Any vulnerabilities detected?
+- **Custom scripts**: Any failures?
+- **Dependency checks**: Outdated or vulnerable packages?
+
+### Step 6: Categorize and Prioritize ALL Issues
+
+Create a master list of all issues from:
+- GitHub Actions failures
+- Greptile inline comments
+- Greptile summary recommendations
+- SonarCloud issues
+- Other CI/CD tool failures
+
+Prioritize by:
+1. **Critical**: Blocks merge (failing tests, security vulnerabilities, build failures)
+2. **High**: Should address (valid bugs, important improvements)
+3. **Medium**: Optional but valuable (code quality, best practices)
+4. **Low**: Nice to have (minor refactorings, style suggestions)
+
+### Step 7: Address Issues Systematically
+
+For **GitHub Actions failures** (Critical):
+```bash
+# Fix the issue
+# Commit with clear description
+git add .
+git commit -m "fix: resolve GitHub Actions failure in <workflow-name>
+
+- Fixed: [specific issue]
+- Root cause: [explanation]
+- Solution: [what was changed]"
+
+git push
+# Actions will auto-rerun
+```
+
+For **Greptile inline comments** (Use Systematic Script):
+```bash
+# Use the standardized Greptile resolution script
+# See .claude/rules/greptile-review-process.md for complete process
+
+# For valid comments (fixed):
+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]"
+
+# For invalid/conflicting comments:
+bash .claude/scripts/greptile-resolve.sh reply-and-resolve <pr-number> <comment-id> <thread-id> \
+  "This approach is correct because:
+  - Reasoning: [from design doc]
+  - Evidence: [link to source]
+  - Alternative considered: [what Greptile suggested]
+  - Why rejected: [specific reason]
+
+  See: docs/plans/YYYY-MM-DD-<slug>-design.md (Decision #X)"
+
+# Verify all threads resolved:
+bash .claude/scripts/greptile-resolve.sh stats <pr-number>
+```
+
+For **Greptile summary recommendations**:
+```bash
+# Add a PR comment addressing the summary
+gh pr comment <pr-number> --body "## Greptile Summary Response
+
+Addressed all key recommendations:
+- [Recommendation 1]: ✓ Fixed in commit <sha>
+- [Recommendation 2]: ✓ Explained (see inline response)
+- [Recommendation 3]: ⏭️ Out of scope for this PR (created issue bd-xxx)
+
+All critical and high-priority items resolved."
+```
+
+For **SonarCloud issues** (via sonarcloud skill):
+```bash
+# For critical/blocker issues: Fix immediately
+# For security vulnerabilities: Fix immediately
+# For code smells: Fix if valid, justify if not
+
+# After fixes, SonarCloud will re-analyze on next push
+```
+
+For **other CI/CD failures**:
+```bash
+# Debug the specific tool's logs
+# Fix the underlying issue
+# Commit and push
+# Verify the check passes
+```
+
+### Step 8: Commit ALL Fixes
+
+```bash
+git add .
+git commit -m "fix: address ALL PR review feedback
+
+GitHub Actions:
+- Fixed: [list of workflow failures resolved]
+
+Greptile:
+- Fixed: [list of valid inline comments addressed]
+- Explained: [list of invalid comments with reasoning]
+- Summary: [key recommendations addressed]
+
+SonarCloud:
+- Fixed: [security vulnerabilities and critical issues]
+- Justified: [code smells that are intentional]
+
+Other CI/CD:
+- Fixed: [any other tool failures]
+
+All review feedback resolved, all checks passing."
+
+git push
+```
+
+### Step 9: Verify ALL Checks Pass
+
+```bash
+# Wait for checks to complete
+gh pr checks <pr-number>
+
+# Ensure all status checks are green:
+# ✓ GitHub Actions workflows
+# ✓ Greptile review (no unresolved critical comments)
+# ✓ SonarCloud quality gate
+# ✓ Other CI/CD checks
+```
+
+### Step 10: Update Beads
+
+```bash
+bd update <id> --comment "PR review complete: all issues addressed, all checks passing"
+bd sync
+```
+
+## Example Output
+
+```
+✓ GitHub Actions: 3 workflows
+  - Build: ✓ Passing (was failing, fixed missing dependency)
+  - Tests: ✓ Passing
+  - Deploy Preview: ✓ Passing
+
+✓ Greptile Review:
+  Inline Comments: 8 total
+  - Valid: 5 → Fixed & replied inline
+  - Invalid: 2 → Explained with research evidence & replied inline
+  - Out of scope: 1 → Noted for future work & replied inline
+  - All marked resolved ✓
+
+  Summary:
+  - Key recommendations: 3/3 addressed
+  - Overall assessment: Ready for merge
+  - Posted summary response comment ✓
+
+✓ SonarCloud (via sonarcloud skill):
+  Quality Gate: ✓ Passing
+  Issues: 3 total
+  - Security: 1 → Fixed (SQL injection risk)
+  - Code smells: 2 → 1 fixed, 1 justified
+  - Coverage: Maintained at 85%
+
+✓ Vercel Preview: ✓ Deployed successfully
+✓ Security Scan: ✓ No vulnerabilities
+
+✓ All Issues Addressed:
+  - Critical: 2/2 fixed (GitHub Actions build, SonarCloud security)
+  - High: 5/5 fixed (Greptile valid comments)
+  - Medium: 3/3 addressed (1 fixed, 2 explained)
+  - Low: 0 (none found)
+
+✓ Fixes committed: 3c4d5e6
+✓ All checks passing: ✓
+✓ Beads updated: Ready for merge
+
+Next: /premerge <pr-number>
+```
+
+```
+<HARD-GATE: /review exit>
+Do NOT declare /review complete until:
+1. bash .claude/scripts/greptile-resolve.sh stats <pr-number> shows "All Greptile threads resolved"
+2. ALL human reviewer comments are either resolved or have a reply with explanation
+3. gh pr checks <pr-number> shows all checks passing
+4. Stage transition: Run `bash scripts/beads-context.sh stage-transition <id> review premerge` → exit 0 confirmed
+</HARD-GATE>
+```
+
+## 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 (you are here)
+Stage 6: /premerge   → Update docs, hand off PR to user
+Stage 7: /verify     → Post-merge CI check on main
+```
+
+## Understanding the Tools
+
+### Greptile
+- **What it is**: AI-powered code review bot
+- **How it helps**:
+  - Context-aware code analysis
+  - Catches bugs and security issues
+  - Suggests improvements and best practices
+  - Provides inline comments and summary
+- **How to use feedback**:
+  - Inline comments: Address specific code issues
+  - Summary: Get overall assessment and key recommendations
+  - Reply directly to each comment (not separate)
+  - Mark resolved after addressing
+
+### SonarCloud (via sonarcloud skill)
+- **What it is**: Static code analysis platform
+- **How it helps**:
+  - Quality gate enforcement
+  - Security vulnerability detection
+  - Code smell identification
+  - Technical debt tracking
+  - Test coverage analysis
+- **How to use the skill**:
+  - Query PR-specific issues
+  - Get quality metrics
+  - Identify security hotspots
+  - Track code coverage changes
+- **Prioritization**:
+  - Blocker/Critical: Must fix
+  - Major: Should fix if valid
+  - Minor/Info: Optional
+
+### GitHub Actions
+- **What it is**: CI/CD automation platform
+- **How it helps**:
+  - Automated testing
+  - Build verification
+  - Deployment automation
+  - Security scanning
+  - Quality checks
+- **Common failures**:
+  - Build: Dependencies, compilation
+  - Tests: Failing test cases
+  - Lint: Code style violations
+  - Deploy: Configuration issues
+
+## Tips
+
+- **Address ALL issues**: Not just Greptile and SonarCloud
+- **Prioritize critical**: Fix blockers first (GitHub Actions failures, security issues)
+- **Reply inline to Greptile**: Respond to each comment directly
+- **Post summary response**: Address Greptile's overall assessment
+- **Use sonarcloud skill**: Don't just check the web UI
+- **Verify all checks**: Ensure everything is green before /premerge
+- **Update Beads**: Keep issue status current
+- **Research if needed**: Use WebSearch for unclear suggestions
+- **Document fixes**: Clear commit messages for all fixes
+- **Don't leave unresolved**: Address every comment and check