forge-workflow 0.0.2 → 0.0.4

package/.roo/commands/verify.md

@@ -0,0 +1,222 @@
+---
+description: Post-merge health check — confirm merge landed, CI is clean, deployments are up
+mode: code
+---
+
+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/AGENTS.md

@@ -71,6 +71,10 @@ When the user requests work, **you MUST automatically classify** the change type
 
  Proceed?"
 
+**Dynamic commands — no hardcoded examples:**
+
+Command files (`.claude/commands/*.md` and agent equivalents) must never hardcode example output when a script generates that output dynamically. Reference the script and describe what it does — don't duplicate its output with fake data that becomes stale.
+
 ## TDD Development (Stage 2: /dev)
 
 **Subagent-driven per-task implementation loop:**
@@ -108,6 +112,8 @@ Task 2: Validation logic
 
 ## State Management (Single Source of Truth)
 
+> GitHub issue lifecycle may sync to Beads via CI -- see [docs/BEADS_GITHUB_SYNC.md](docs/BEADS_GITHUB_SYNC.md).
+
 **All workflow state stored in Beads metadata** (survives compaction):
 
 ```json
@@ -162,7 +168,7 @@ Task 2: Validation logic
 - `docs/plans/YYYY-MM-DD-<slug>-decisions.md` - Decisions log from /dev
 
 **Comprehensive workflow guide:**
-- [docs/WORKFLOW.md](docs/WORKFLOW.md) - Complete workflow documentation (150 lines)
+- This file (AGENTS.md) is the single source of truth for the complete workflow
 - [docs/TOOLCHAIN.md](docs/TOOLCHAIN.md) - Tool setup and configuration
 - [docs/VALIDATION.md](docs/VALIDATION.md) - Enforcement and validation details
 

package/CLAUDE.md

@@ -1,6 +1,6 @@
 # Project Instructions
 
-This is a [describe what this project does in one sentence].
+Forge is a 7-stage TDD-first development workflow harness for AI coding agents (9 commands total, including utility stages).
 
 **Package manager**: Bun (preferred for performance)
 
@@ -72,13 +72,13 @@ This project uses the **Professional Git Workflow** with Lefthook for automated
 - **All review comments must be resolved** before merge
 - Squash-only merging: Clean, linear git history
 
-**Emergency bypass**:
+**Emergency bypass** (human-only, NEVER for AI agents):
 ```bash
 LEFTHOOK=0 git push              # Skip all pre-push hooks
 git commit --no-verify           # Skip pre-commit hooks
 ```
 
-**⚠️ Only use bypasses for emergencies.** Document reason in PR description.
+**⚠️ AI agents must NEVER use `LEFTHOOK=0`, `--no-verify`, or any hook bypass.** If a hook fails, fix the underlying issue. Only humans may bypass hooks in emergencies, documented in the PR description.
 
 See [.github/pull_request_template.md](.github/pull_request_template.md) for PR guidelines.
 
@@ -93,7 +93,8 @@ As you work, when you give the same instruction twice, add it here:
 - **Scope discipline**: Do ONLY what was explicitly asked. Answer a question → stop. Check something → stop. Never auto-continue to next steps or pending work unless told to.
 - **Stage names**: The validation stage is `/validate` (not `/check`) — renamed in PR #50.
 - **Unused params**: Prefix with `_` (e.g., `_searchTerm`) — ESLint `no-unused-vars` enforced with `--max-warnings 0`.
-- **Pre-push test env**: `test-env/` fixture tests can fail during actual `git push` due to git mid-push state; `LEFTHOOK=0 git push` is the bypass when manual `bun test` confirms 0 fail.
+- **Pre-push test env**: `test-env/` fixture tests can fail during actual `git push` due to git mid-push state. Fix the root cause — never use `LEFTHOOK=0`.
 - **Command sync**: After editing `.claude/commands/*.md`, run `node scripts/sync-commands.js` to update all 7 agent directories. Use `--check` in CI to detect drift. Use `--dry-run` to preview.
+- **Dynamic commands**: Never hardcode example output in command files (`.claude/commands/*.md`) when a script generates that output dynamically. Command files should reference the script and describe what it does — not duplicate its output with fake data that becomes stale.
 
 <!-- USER:END -->

package/README.md

@@ -45,7 +45,7 @@ Ship features with confidence using a 7-stage TDD-first workflow for AI coding a
 **With Forge** (systematic):
 - Tests written BEFORE code (TDD)
 - Research-backed decisions
-- OWASP Top 10 analysis built-in
+- OWASP Top 10 analysis in every /plan
 - Documentation at every stage
 
 → [See complete walkthrough in QUICKSTART.md](QUICKSTART.md)
@@ -78,7 +78,7 @@ bunx forge setup
 
 | Stage | Command | Purpose |
 |-------|---------|---------|
-| **utility** | `/status` | Check current context, active work |
+| **utility** | `/status` | Ranked issue dashboard with conflict detection |
 | **1. Plan** | `/plan` | Design Q&A → research → branch + task list |
 | **2. Dev** | `/dev` | Subagent TDD per task (spec + quality review) |
 | **3. Validate** | `/validate` | Validate: types, lint, tests, security |
@@ -87,13 +87,13 @@ bunx forge setup
 | **6. Premerge** | `/premerge` | Complete docs on feature branch, hand off PR |
 | **7. Verify** | `/verify` | Post-merge health check (CI on main) |
 
-**Full workflow guide**: [docs/WORKFLOW.md](docs/WORKFLOW.md)
+**Full workflow guide**: [AGENTS.md](AGENTS.md)
 
 ---
 
 ## Supported AI Agents
 
-Works with **7 AI coding agents** via universal AGENTS.md:
+Works with **8 AI coding agents** via universal AGENTS.md:
 
 ### Tier 1 (Primary Support)
 
@@ -163,7 +163,7 @@ One workflow, works with ALL major AI agents:
 
 Switch agents anytime without changing your workflow.
 
-### 4. Built-in TDD Enforcement (v1.5.0)
+### 4. Built-in TDD Enforcement
 Git hooks automatically enforce TDD practices:
 - **Pre-commit**: Blocks source commits without tests
 - **Pre-push**: Runs full test suite before push
@@ -172,16 +172,16 @@ Git hooks automatically enforce TDD practices:
 
 ```bash
 # Validation CLI
-forge-validate status    # Check project prerequisites
-forge-validate dev       # Validate before /dev stage
-forge-validate ship      # Validate before /ship stage
+forge-preflight status    # Check project prerequisites
+forge-preflight dev       # Validate before /dev stage
+forge-preflight ship      # Validate before /ship stage
 ```
 
-### 5. Smart Tool Recommendations (v1.7.0)
-Intelligent plugin catalog with 30+ curated tools:
+### 5. Smart Tool Recommendations
+Curated plugin catalog across 7 workflow stages — plan, dev, validate, ship, review, and more:
 - **Auto-detection**: Scans your project for frameworks, databases, auth, payments, and more
 - **Budget modes**: free, open-source, startup, professional, custom
-- **CLI-first**: Prefers CLI tools over MCPs for portability
+- **Portability-first**: MCPs included only when they add clear value over CLI alternatives
 - **Free alternatives**: Every paid tool shows free alternatives
 
 ```bash
@@ -189,9 +189,9 @@ bunx forge recommend                  # Recommendations for your project
 bunx forge recommend --budget free    # Only free tools
 ```
 
-→ [Validation docs](docs/VALIDATION.md) | [Plugin docs](lib/agents/README.md)
+→ [Validation docs](docs/VALIDATION.md) | [Plugin docs](docs/TOOLCHAIN.md)
 
-### 6. Enhanced Onboarding (v1.6.0) 🆕
+### 6. Enhanced Onboarding
 Smart setup that adapts to your project:
 
 **Intelligent File Merging**
@@ -210,11 +210,13 @@ bunx forge setup --merge=smart    # Intelligent merge
 - Saves to `.forge/context.json`
 
 **Workflow Profiles**
-- Adapts workflow based on work type:
-  - `feature`: Full 7-stage workflow (auto-escalates to critical for auth/payment)
-  - `fix`: Streamlined 5-stage workflow (auto-escalates to hotfix for production)
+- Adapts workflow based on work type (3-8 stages):
+  - `critical`: Full 8-stage workflow (auth, payments, security-sensitive)
+  - `standard`: 7-stage workflow (typical features)
   - `refactor`: Behavior-preserving 5-stage workflow
-  - `chore`: Minimal 3-stage workflow (docs/deps/config)
+  - `simple`: Streamlined 4-stage workflow
+  - `hotfix`: Minimal 3-stage workflow (production fixes)
+  - `docs`: Minimal 3-stage workflow (documentation/config)
 ```bash
 bunx forge setup --type=critical    # Set workflow manually
 ```
@@ -348,7 +350,7 @@ gh auth login
 **Documentation Progressive**: Update at each stage
 **Multi-Session**: Work persists across sessions
 
-→ [Read the philosophy in docs/WORKFLOW.md](docs/WORKFLOW.md)
+→ [Read the philosophy in AGENTS.md](AGENTS.md)
 
 ---
 
@@ -358,7 +360,7 @@ gh auth login
 → [QUICKSTART.md](QUICKSTART.md) - Your first feature in 5 minutes
 
 📖 **Learn the workflow**
-→ [docs/WORKFLOW.md](docs/WORKFLOW.md) - Complete guide with examples
+→ [AGENTS.md](AGENTS.md) - Complete guide with examples
 
 🛠️ **Setup the toolchain**
 → [docs/TOOLCHAIN.md](docs/TOOLCHAIN.md) - Beads, GitHub CLI

package/bin/{forge-validate.js → forge-preflight.js}

@@ -1,22 +1,21 @@
 #!/usr/bin/env node
 
 /**
- * Forge Validate CLI
+ * Forge Preflight CLI
  *
  * Prerequisite validation for workflow stages.
  * Helps ensure developers have required tools and files before proceeding.
  *
  * Usage:
- *   forge-validate status  - Check project prerequisites
- *   forge-validate dev     - Validate before /dev stage
- *   forge-validate ship    - Validate before /ship stage
+ *   forge-preflight status  - Check project prerequisites
+ *   forge-preflight dev     - Validate before /dev stage
+ *   forge-preflight ship    - Validate before /ship stage
  *
  * Security: Uses execFileSync to prevent command injection.
  */
 
 const { execFileSync } = require("node:child_process");
 const fs = require("node:fs");
-// const path = require("node:path"); // Currently unused
 
 // Validation results
 let checks = [];
@@ -52,6 +51,7 @@ function printResults() {
 // Validation functions
 
 function validateStatus() {
+  checks = [];
   console.log("Checking project prerequisites...\n");
 
   check(
@@ -100,6 +100,7 @@ function validateStatus() {
 }
 
 function validateDev() {
+  checks = [];
   console.log("Validating prerequisites for /dev stage...\n");
 
   check(
@@ -129,15 +130,15 @@ function validateDev() {
     "Plan file exists",
     () => {
       try {
-        const plansDir = ".claude/plans";
+        const plansDir = "docs/plans";
         if (!fs.existsSync(plansDir)) return false;
-        const plans = fs.readdirSync(plansDir).filter((f) => f.endsWith(".md"));
+        const plans = fs.readdirSync(plansDir).filter((f) => f.endsWith("-design.md"));
         return plans.length > 0;
       } catch {
         return false;
       }
     },
-    "No plan file found in .claude/plans/. Run: /plan",
+    "No plan file found in docs/plans/. Run: /plan",
   );
 
   check(
@@ -173,6 +174,7 @@ function validateDev() {
 }
 
 function validateShip() {
+  checks = [];
   console.log("Validating prerequisites for /ship stage...\n");
 
   check(
@@ -182,7 +184,7 @@ function validateShip() {
       return testDirs.some((dir) => {
         if (!fs.existsSync(dir)) return false;
         try {
-          const files = fs.readdirSync(dir, { recursive: true });
+          const files = fs.readdirSync(dir);
           return files.some(
             (f) => f.includes(".test.") || f.includes(".spec."),
           );
@@ -200,7 +202,11 @@ function validateShip() {
       try {
         execFileSync("npm", ["test"], { stdio: "pipe" });
         return true;
-      } catch {
+      } catch (err) {
+        const output = ((err.stdout || "") + "\n" + (err.stderr || "")).trim();
+        if (output) {
+          console.error("\nTest output:\n" + output.slice(0, 2000));
+        }
         return false;
       }
     },
@@ -235,10 +241,10 @@ function validateShip() {
 
 function showHelp() {
   console.log(`
-Forge Validate - Prerequisite validation for workflow stages
+Forge Preflight - Prerequisite validation for workflow stages
 
 Usage:
-  forge-validate <command>
+  forge-preflight <command>
 
 Commands:
   status    Check project prerequisites (git, npm, tests)
@@ -247,9 +253,9 @@ Commands:
   help      Show this help message
 
 Examples:
-  forge-validate status
-  forge-validate dev
-  forge-validate ship
+  forge-preflight status
+  forge-preflight dev
+  forge-preflight ship
 `);
 }