forge-workflow 0.0.10 → 0.1.0-beta.2

package/.cursor/commands/validate.md

@@ -1,285 +0,0 @@
-
-> **Note:** Three things share the "validate" name in Forge:
-> - `/validate` (this command): Workflow Stage 3 — rebases onto the base branch, then runs type/lint/test/security checks
-> - `forge-preflight` (formerly forge-validate): CLI tool — checks prerequisites before a stage
-> - `bun run check` (scripts/validate.sh): Local quality gate — runs type/lint/test/security checks only (does NOT rebase; assumes branch is already current with the base branch)
-
-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 validation script (checks only — no rebase):
-
-```bash
-bun run check    # Runs lint/test/security checks only. Does NOT rebase onto the base branch.
-                 # Use /validate for the full workflow (rebase + checks).
-```
-
-```
-<HARD-GATE: /validate entry — rebase onto latest base branch>
-Before running ANY validation checks:
-
-0. Resolve the base branch dynamically (do NOT hardcode master or main):
-   BASE=$(git remote show origin 2>/dev/null | grep 'HEAD branch' | awk '{print $NF}')
-   if [ -z "$BASE" ] || [ "$BASE" = "(unknown)" ]; then BASE="master"; fi
-
-   This handles repos using main, master, or any other default branch.
-   Falls back to "master" when HEAD is unresolved (detached remote, empty repo).
-
-1. Fetch latest base branch:
-   git fetch origin "$BASE" || { echo "✗ Fetch failed — cannot verify branch freshness"; exit 1; }
-
-   The `|| { ...; exit 1; }` guard ensures fetch failures are never silently skipped.
-
-2. Check if branch is behind:
-   BEHIND=$(git rev-list --count HEAD..origin/"$BASE")
-
-3. If BEHIND > 0:
-   a. Run: git rebase origin/"$BASE" || REBASE_FAILED=1
-   b. If rebase succeeds (REBASE_FAILED unset): print "✓ Rebased onto latest $BASE ($BEHIND commits integrated)"
-   c. If rebase fails (REBASE_FAILED=1 — conflicts or any other error):
-      - Capture conflicting files BEFORE aborting: git diff --name-only --diff-filter=U
-      - Run: git rebase --abort
-      - Print the captured conflicting file list
-      - Print: "✗ Rebase conflict — resolve manually, then re-run /validate"
-      - STOP. Do NOT proceed to any validation checks.
-
-4. If BEHIND = 0:
-   Print "✓ Branch is up-to-date with $BASE" and continue.
-
-Rationale: Without this step, validation checks run against stale code that doesn't
-include recent base branch changes. Integration issues are only caught after the PR is
-created, wasting CI cycles and review time. Rebasing here ensures /validate results
-reflect the true state of what will be merged.
-</HARD-GATE>
-```
-
-## 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. Context check: Run `bash scripts/beads-context.sh validate <id>` and address any warnings
-6. Stage transition: Run the following → exit 0 confirmed:
-   bash scripts/beads-context.sh stage-transition <id> validate ship \
-     --summary "<all checks pass/fail summary>" \
-     --decisions "<any failures diagnosed and fixed>" \
-     --artifacts "<scripts and commands run>" \
-     --next "<ship readiness notes>"
-</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

package/.cursor/commands/verify.md

@@ -1,266 +0,0 @@
-
-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 Issues (if healthy)
-
-If everything is clean, close all Beads issues referenced in the merged PR.
-
-**Auto-detect beads issues from PR body and branch name:**
-
-```bash
-# Get PR body and branch name
-PR_BODY=$(gh pr view <number> --json body --jq '.body')
-PR_BRANCH=$(gh pr view <number> --json headRefName --jq '.headRefName')
-
-# Extract beads IDs from PR body (matches "Closes beads-xxx", "closes forge-xxx", etc.)
-# Patterns: "Closes <prefix>-<id>", "Fixes <prefix>-<id>", "Resolves <prefix>-<id>"
-BEADS_IDS=$(echo "$PR_BODY" | grep -oiE '(closes|fixes|resolves):?\s+[a-z]+-[a-z0-9]+' | grep -oiE '[a-z]+-[a-z0-9]{3,6}$')
-
-# Validate each ID exists in beads
-VALID_IDS=""
-for id in $BEADS_IDS; do
-  if bd show "$id" >/dev/null 2>&1; then
-    VALID_IDS="$VALID_IDS $id"
-  fi
-done
-BEADS_IDS="$VALID_IDS"
-
-# Also check branch name for beads ID — extract segment after last /
-# then validate with bd show to avoid false matches like "pr-templa"
-BRANCH_SLUG=$(echo "$PR_BRANCH" | sed 's|.*/||')
-BRANCH_ID=$(echo "$BRANCH_SLUG" | grep -oE '[a-z]+-[a-z0-9]{3,6}' | head -1)
-if [ -n "$BRANCH_ID" ] && ! bd show "$BRANCH_ID" >/dev/null 2>&1; then
-  BRANCH_ID=""  # Not a valid beads ID — discard
-fi
-```
-
-**Close each matched issue:**
-
-```bash
-# Close issues found in PR body
-for id in $BEADS_IDS; do
-  bd close "$id" --reason="Merged and verified on master (PR #<number>)" 2>&1 || echo "Warning: could not close $id"
-done
-
-# If no issues found in body, try branch name match (skip if already closed above)
-if [ -z "$BEADS_IDS" ] && [ -n "$BRANCH_ID" ]; then
-  bd close "$BRANCH_ID" --reason="Merged and verified on master (PR #<number>)" 2>&1 || echo "Warning: could not close $BRANCH_ID"
-elif [ -n "$BRANCH_ID" ] && ! echo "$BEADS_IDS" | grep -qw "$BRANCH_ID"; then
-  bd close "$BRANCH_ID" --reason="Merged and verified on master (PR #<number>)" 2>&1 || echo "Warning: could not close $BRANCH_ID"
-fi
-```
-
-**If no beads issues detected at all**, prompt the user:
-```
-⚠ No beads issue ID found in PR body or branch name.
-  If this PR closes a beads issue, run: bd close <id> --reason="Merged and verified on master (PR #<number>)"
-```
-
-```
-<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 issues extracted from PR body/branch and closed (bd close run and confirmed)
-   - If no beads ID found: user was warned and given manual close command
-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/.cursorrules

@@ -1,149 +0,0 @@
-# Forge - 7-Stage TDD Workflow
-
-A TDD-first workflow for AI coding agents. Ship features with confidence.
-
-## Commands (7 Stages)
-
-| Stage | Command | Description |
-|-------|---------|-------------|
-| utility | `/status` | Check current context, active work, recent completions |
-| 1 | `/plan` | Design intent Q&A → research → branch + task list |
-| 2 | `/dev` | Subagent-driven TDD per task (spec + quality review) |
-| 3 | `/validate` | Validation (type/lint/security/tests) |
-| 4 | `/ship` | Create PR with full documentation |
-| 5 | `/review` | Address ALL PR feedback |
-| 6 | `/premerge` | Complete docs on feature branch, hand off PR to user |
-| 7 | `/verify` | Post-merge health check (CI on main) |
-
-## Workflow Flow
-
-```
-/plan → /dev → /validate → /ship → /review → /premerge → /verify
-```
-
-## Core Principles
-
-- **TDD-First**: Write tests BEFORE implementation (RED-GREEN-REFACTOR)
-- **Design-First**: One-question-at-a-time Q&A captures design intent upfront
-- **HARD-GATEs**: Every stage exit has explicit pass criteria — run the commands, show the output
-- **Security Built-In**: OWASP Top 10 analysis for every feature
-
-## Prerequisites
-
-- Git, GitHub CLI (`gh`)
-- Beads (recommended): `bun add -g @beads/bd && bd init`
-
-## Quick Start
-
-1. `/status` - Check where you are
-2. `/plan <feature-slug>` - Design intent → research → branch + task list
-3. `/dev` - Implement with TDD
-4. `/validate` - Validate everything
-5. `/ship` - Create PR
-6. `/review <pr-number>` - Address all feedback
-7. `/premerge <pr-number>` - Docs + hand off to user
-
-## Stage Details
-
-### Utility: Status (`/status`)
-
-Check current context before starting work:
-- Active issues (via Beads if installed)
-- Recent completions
-- Current branch state
-
-### 1. Plan (`/plan <feature-slug>`)
-
-Three phases:
-- **Phase 1**: Design intent Q&A (one-question-at-a-time with user)
-- **Phase 2**: Technical research (web + codebase, OWASP Top 10)
-- **Phase 3**: Create branch + task list (TDD-ordered)
-
-### 2. Development (`/dev`)
-
-Subagent-driven TDD per task:
-- Implementer subagent: RED-GREEN-REFACTOR enforced by HARD-GATE
-- Spec compliance reviewer: checks every task
-- Code quality reviewer: checks after spec compliance
-- Decision gate: 7-dimension scoring when spec gap found
-
-### 3. Validate (`/validate`)
-
-Validate everything (HARD-GATE exit — fresh output required):
-- Type checking
-- Linting (0 errors, 0 warnings)
-- All tests passing
-- Security scan (OWASP Top 10)
-
-### 4. Ship (`/ship`)
-
-Create pull request:
-- Push branch
-- Create PR with design doc reference
-- Link to Beads issue
-
-### 5. Review (`/review <pr-number>`)
-
-Address ALL feedback:
-- GitHub Actions failures
-- Greptile inline comments (reply + resolve each)
-- SonarCloud issues
-- Other CI/CD tool feedback
-
-### 6. Premerge (`/premerge <pr-number>`)
-
-Complete docs and hand off (NEVER merges):
-- Update CLAUDE.md, AGENTS.md, GEMINI.md, README as needed
-- Commit docs to feature branch
-- Hand off PR URL to user for merge
-
-### 7. Verify (`/verify`)
-
-Post-merge health check:
-- CI on main: all checks green
-- Close Beads issue
-- Confirm merge landed
-
-## Directory Structure
-
-```
-your-project/
-├── AGENTS.md                    # Universal (Windsurf, Cursor, Kilo, OpenCode, Cline, Roo, Aider)
-├── CLAUDE.md                    # Claude Code
-├── GEMINI.md                    # Google Antigravity
-├── .cursorrules                 # Cursor
-│
-├── .claude/commands/            # Claude Code commands
-└── docs/
-    ├── plans/
-    │   ├── YYYY-MM-DD-<slug>-design.md
-    │   └── YYYY-MM-DD-<slug>-tasks.md
-    └── TOOLCHAIN.md
-```
-
-## Supported Agents
-
-This workflow works with ALL major AI coding agents:
-
-| Agent | Instructions | Commands |
-|-------|-------------|----------|
-| Claude Code | CLAUDE.md | .claude/commands/ |
-| Google Antigravity | GEMINI.md | .agent/workflows/ |
-| Cursor | .cursorrules | .cursor/rules/ |
-| Windsurf | AGENTS.md | .windsurf/workflows/ |
-| Kilo Code | AGENTS.md | .kilocode/workflows/ |
-| OpenCode | AGENTS.md | .opencode/commands/ |
-| Cline | AGENTS.md | - |
-| Roo Code | AGENTS.md | .roo/commands/ |
-| Continue | AGENTS.md | .continue/prompts/ |
-| GitHub Copilot | .github/copilot-instructions.md | .github/prompts/ |
-| Aider | AGENTS.md (via .aider.conf.yml) | In-chat |
-| Codex CLI | AGENTS.md | In-chat |
-
-## License
-
-MIT
-
----
-
-See `AGENTS.md` for the complete workflow guide.