forge-workflow 0.0.2 → 0.0.3

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/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Harsha Nandak
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Harsha Nandak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/docs/ENHANCED_ONBOARDING.md

@@ -333,10 +333,10 @@ git checkout -b feat/user-authentication
 bunx forge setup --type=critical
 
 # Auto-escalates to Critical profile:
-# - 9-stage workflow
+# - 7-stage workflow
 # - Research required
 # - OWASP analysis
-# - OpenSpec for strategic changes
+# - Design docs for strategic changes
 ```
 
 ### Scenario 4: Production Hotfix

package/docs/TOOLCHAIN.md

@@ -9,20 +9,20 @@ Complete reference for all tools integrated with the Forge workflow.
 │                        FORGE TOOLCHAIN                          │
 ├─────────────────────────────────────────────────────────────────┤
 │                                                                 │
-│  ┌─────────────┐   ┌─────────────┐   ┌─────────────────────┐   │
-│  │   BEADS     │   │  OPENSPEC   │   │  EXTERNAL SERVICES  │   │
-│  │   (bd)      │   │  (opsx)     │   │                     │   │
-│  │             │   │             │   │  Parallel AI        │   │
-│  │ Git-backed  │   │ Spec-driven │   │  Greptile           │   │
-│  │ Issue       │   │ Development │   │  SonarCloud         │   │
-│  │ Tracking    │   │             │   │  GitHub CLI         │   │
-│  └─────────────┘   └─────────────┘   └─────────────────────┘   │
-│        │                 │                     │                │
-│        └─────────────────┴─────────────────────┘                │
+│  ┌─────────────┐   ┌─────────────────────┐                     │
+│  │   BEADS     │   │  EXTERNAL SERVICES  │                     │
+│  │   (bd)      │   │                     │                     │
+│  │             │   │  Parallel AI        │                     │
+│  │ Git-backed  │   │  Greptile           │                     │
+│  │ Issue       │   │  SonarCloud         │                     │
+│  │ Tracking    │   │  GitHub CLI         │                     │
+│  └─────────────┘   └─────────────────────┘                     │
+│        │                     │                                 │
+│        └─────────────────────┘                                 │
 │                          │                                      │
 │                    ┌─────▼─────┐                                │
 │                    │   FORGE   │                                │
-│                    │  9-Stage  │                                │
+│                    │  7-Stage  │                                │
 │                    │  Workflow │                                │
 │                    └───────────┘                                │
 │                                                                 │
@@ -219,200 +219,6 @@ bd sync                     # Always sync at end!
 
 ---
 
-## OpenSpec - Spec-Driven Development
-
-**Package**: `@fission-ai/openspec`
-**Repository**: [github.com/Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec)
-**Website**: [openspec.dev](https://openspec.dev)
-**Purpose**: Structured specifications for AI-assisted development
-
-### Why OpenSpec?
-
-- **Specs before code** - AI reads requirements, not just vibes
-- **Non-linear workflow** - Commands execute in any order
-- **Git-native** - Specs versioned like code
-- **Multi-agent** - Works with 21+ AI tools
-- **Zero dependencies** - No API keys, no external services
-
-### Installation
-
-**Auto-installation** (Recommended):
-```bash
-bunx forge setup
-# Prompts: "Install OpenSpec? (y/n)"
-# Automatically installs and initializes (if selected)
-```
-
-**Manual installation**:
-```bash
-# bun (global - requires Node.js 20.19+)
-bun add -g @fission-ai/openspec
-openspec init
-
-# bun (local)
-bun add -d @fission-ai/openspec
-bunx openspec init
-
-# Or with bunx (no install needed)
-bunx @fission-ai/openspec init
-```
-
-### File Structure
-
-After `openspec init`:
-
-```
-openspec/
-├── specs/
-│   └── [domain]/
-│       └── spec.md           # Source of truth for each domain
-│
-├── changes/
-│   ├── [change-name]/
-│   │   ├── proposal.md       # Intent, scope, rationale
-│   │   ├── design.md         # Technical approach
-│   │   ├── tasks.md          # Implementation checklist
-│   │   └── specs/
-│   │       └── [domain]/
-│   │           └── spec.md   # Delta specifications
-│   └── archive/              # Completed changes
-│
-├── schemas/
-│   └── default.yaml          # Workflow schema
-│
-└── config.yaml               # Project configuration
-```
-
-### CLI Commands
-
-```bash
-# Setup
-openspec init [path]          # Initialize OpenSpec
-openspec update               # Update after CLI upgrade
-
-# Browse
-openspec list                 # Display changes/specs
-openspec view                 # Interactive terminal dashboard
-openspec show [name]          # Show detailed content
-openspec status               # Artifact completion progress
-
-# Validation
-openspec validate [name]      # Check structural integrity
-openspec validate --strict    # Strict validation
-
-# Lifecycle
-openspec sync                 # Merge delta specs into main specs
-openspec archive [name]       # Finalize completed changes
-
-# Schema
-openspec schema init          # Create new schema
-openspec schema fork          # Fork existing schema
-openspec schema validate      # Validate schema
-openspec schemas              # List available schemas
-```
-
-### AI Slash Commands (Claude Code, Cursor)
-
-```bash
-/opsx:explore     # Think through ideas, investigate
-/opsx:new         # Start a new change initiative
-/opsx:continue    # Create next artifact (incremental)
-/opsx:ff          # Fast-forward: generate all planning artifacts
-/opsx:apply       # Implement tasks
-/opsx:sync        # Merge delta specs into main specs
-/opsx:archive     # Mark change complete
-/opsx:verify      # Validate implementation matches specs
-/opsx:onboard     # Interactive tutorial
-```
-
-### Spec Format
-
-OpenSpec uses structured markdown with normative language:
-
-```markdown
-# Authentication Specification
-
-## Purpose
-Enable secure user identity verification and session management
-
-## Requirements
-
-### Requirement: Session Token Validation
-The system SHALL validate session tokens on every request
-
-#### Scenario: Valid Session
-- **GIVEN** user has authenticated
-- **WHEN** request includes valid session token
-- **THEN** process the request
-- **AND** update token expiration time
-
-#### Scenario: Expired Session
-- **GIVEN** user had authenticated but 24 hours have passed
-- **WHEN** request includes expired session token
-- **THEN** invalidate the token
-- **AND** redirect to login
-```
-
-### Delta Format
-
-Changes use ADDED/MODIFIED/REMOVED notation:
-
-```markdown
-# Delta for Authentication
-
-## ADDED Requirements
-### Requirement: Two-Factor Authentication
-The system SHALL support optional 2FA
-
-#### Scenario: 2FA Enrollment
-- **GIVEN** user enables 2FA in settings
-- **WHEN** they scan QR code with authenticator app
-- **THEN** 2FA is activated for their account
-
-## MODIFIED Requirements
-### Requirement: Session Token Validation
-[Updated content here]
-
-## REMOVED Requirements
-### Requirement: Remember Me Cookie
-```
-
-### When to Use OpenSpec
-
-| Scope | Use OpenSpec? | Example |
-|-------|---------------|---------|
-| **Tactical** (< 1 day) | No | Bug fix, small feature |
-| **Strategic** (architecture) | Yes | New service, API redesign |
-| **Breaking changes** | Yes | Schema migrations |
-| **Multi-session work** | Yes | Large features |
-
-### Workflow Example
-
-```bash
-# 1. Start new change
-/opsx:new
-# Describe: "Add payment processing with Stripe"
-# Select schema: default
-
-# 2. Generate all planning docs
-/opsx:ff
-# Creates: proposal.md, design.md, tasks.md, specs/
-
-# 3. Implement
-/opsx:apply
-# AI writes code following tasks.md
-
-# 4. Verify
-/opsx:verify
-# Confirms implementation matches specs
-
-# 5. Finalize
-/opsx:sync     # Merge deltas into main specs
-/opsx:archive  # Move to archive
-```
-
----
-
 ## MCP Servers
 
 ### Context7 - Library Documentation
@@ -710,7 +516,7 @@ volumes:
 ### GitHub CLI - PR Workflow
 
 **Installation**: [cli.github.com](https://cli.github.com)
-**Used in**: `/ship`, `/review`, `/merge` stages
+**Used in**: `/ship`, `/review`, `/premerge` stages
 
 ```bash
 # Install
@@ -735,14 +541,14 @@ gh issue create --title "..." --body "..."
 
 | Stage | Tools Used |
 |-------|------------|
-| `/status` | `bd ready`, `bd list`, `git status`, `openspec list` |
+| `/status` | `bd ready`, `bd list`, `git status` |
 | `/plan` (Phase 2) | Parallel AI, Context7, grep.app, codebase exploration |
-| `/plan` | `bd create`, `openspec` (if strategic), `git checkout -b` |
+| `/plan` | `bd create`, `git checkout -b` |
 | `/dev` | Tests, code, `bd update`, `/tasks save` |
 | `/validate` | Type check, lint, tests, SonarCloud |
 | `/ship` | `bd update --status done`, `gh pr create` |
 | `/review` | `gh pr view`, Greptile, SonarCloud |
-| `/merge` | `gh pr merge`, `openspec archive`, `bd sync` |
+| `/premerge` | `bd sync`, doc updates, hand off PR |
 | `/verify` | Documentation cross-check |
 
 ---
@@ -762,17 +568,6 @@ bd close <id>               # Complete
 bd sync                     # Git sync
 ```
 
-### OpenSpec (Specifications)
-
-```bash
-openspec init               # Initialize
-/opsx:new                   # Start change (AI)
-/opsx:ff                    # Generate all docs (AI)
-/opsx:apply                 # Implement (AI)
-openspec validate <name>    # Validate
-openspec archive <name>     # Complete
-```
-
 ### GitHub CLI
 
 ```bash
@@ -816,19 +611,6 @@ bd sync --force
 bd sync  # Re-imports from JSONL
 ```
 
-### OpenSpec
-
-**"openspec: command not found"**
-```bash
-bun add -g @fission-ai/openspec
-# Or use bunx @fission-ai/openspec <command>
-```
-
-**Validation errors**
-```bash
-openspec validate <name> --verbose
-```
-
 ### GitHub CLI
 
 **"gh: not authenticated"**
@@ -842,7 +624,6 @@ gh auth status
 ## Resources
 
 - **Beads**: [github.com/steveyegge/beads](https://github.com/steveyegge/beads)
-- **OpenSpec**: [openspec.dev](https://openspec.dev) | [github.com/Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec)
 - **Parallel AI**: [platform.parallel.ai](https://platform.parallel.ai)
 - **Greptile**: [greptile.com](https://greptile.com)
 - **SonarCloud**: [sonarcloud.io](https://sonarcloud.io)