forge-workflow 0.0.9 → 0.1.0-beta.2

package/.cursor/commands/premerge.md

@@ -1,183 +0,0 @@
-
-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
-
-**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.). Poll for up to 60 seconds. If checks are still pending after that, stop and ask the user to return to `/premerge <pr-number>` later. 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.
-```
-
-### Step 6: Validate Context and Record Stage Transition
-
-```bash
-bash scripts/beads-context.sh validate <id>
-bash scripts/beads-context.sh stage-transition <id> premerge verify \
-  --summary "<docs updated, CI green, PR ready>" \
-  --artifacts "<updated doc files, PR URL>" \
-  --next "<merge instructions for user>"
-```
-
-```
-<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 — checks passed within the 60 second poll window
-✓ 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/.cursor/commands/research.md

@@ -1,39 +0,0 @@
-
-> **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/.cursor/commands/review.md

@@ -1,448 +0,0 @@
-
-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
-# Check status immediately, then poll for at most 60 seconds
-gh pr checks <pr-number>
-
-# If checks are still pending after 60 seconds: STOP and tell the user to return
-# when CI finishes or new review feedback appears.
-#
-# Ensure all completed 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. Context check: Run `bash scripts/beads-context.sh validate <id>` and address any warnings
-5. Stage transition: Run the following → exit 0 confirmed:
-   bash scripts/beads-context.sh stage-transition <id> review premerge \
-     --summary "<all feedback addressed summary>" \
-     --decisions "<comment resolutions — valid fixes and justified rejections>" \
-     --artifacts "<fixed files, commit SHAs>" \
-     --next "<doc update needs for premerge>"
-</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