forge-workflow 0.0.2 → 0.0.4

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)

package/docs/VALIDATION.md

@@ -70,12 +70,12 @@ LEFTHOOK=0 git push  # Skip all hooks
 
 ## Validation CLI
 
-The `forge-validate` CLI checks prerequisites for each workflow stage.
+The `forge-preflight` CLI checks prerequisites for each workflow stage.
 
 ### Usage
 
 ```bash
-forge-validate <command>
+forge-preflight <command>
 ```
 
 ### Commands
@@ -90,7 +90,7 @@ forge-validate <command>
 
 ## Validators by Stage
 
-### `forge-validate status`
+### `forge-preflight status`
 
 **Purpose**: Check basic project setup
 
@@ -102,7 +102,7 @@ forge-validate <command>
 
 **Example**:
 ```bash
-$ forge-validate status
+$ forge-preflight status
 
 Checking project prerequisites...
 
@@ -118,7 +118,7 @@ Validation Results:
 
 ---
 
-### `forge-validate dev`
+### `forge-preflight dev`
 
 **Purpose**: Validate before starting implementation (`/dev`)
 
@@ -130,7 +130,7 @@ Validation Results:
 
 **Example**:
 ```bash
-$ forge-validate dev
+$ forge-preflight dev
 
 Validating prerequisites for /dev stage...
 
@@ -146,7 +146,7 @@ Validation Results:
 
 **Failed Example**:
 ```bash
-$ forge-validate dev
+$ forge-preflight dev
 
 Validating prerequisites for /dev stage...
 
@@ -163,7 +163,7 @@ Validation Results:
 
 ---
 
-### `forge-validate ship`
+### `forge-preflight ship`
 
 **Purpose**: Validate before creating PR (`/ship`)
 
@@ -175,7 +175,7 @@ Validation Results:
 
 **Example**:
 ```bash
-$ forge-validate ship
+$ forge-preflight ship
 
 Validating prerequisites for /ship stage...
 
@@ -269,7 +269,7 @@ const testPatterns = [
 
 ### Validation CLI Customization
 
-Edit `bin/forge-validate.js` to add custom validators:
+Edit `bin/forge-preflight.js` to add custom validators:
 
 ```javascript
 function validateCustomStage() {
@@ -358,6 +358,6 @@ git push
 
 ## See Also
 
-- [Workflow Guide](WORKFLOW.md) - Complete 9-stage workflow
+- [Workflow Guide](../AGENTS.md) - Complete 7-stage workflow
 - [TDD Guide](../CLAUDE.md) - TDD principles and practices
 - [Lefthook Docs](https://github.com/evilmartians/lefthook) - Full hook configuration

package/install.sh

@@ -285,7 +285,6 @@ echo -e "  ${GREEN}Created: AGENTS.md${NC}"
 
 # Download documentation
 echo "Downloading documentation..."
-curl -fsSL "$BASE_URL/docs/WORKFLOW.md" -o "docs/WORKFLOW.md" 2>/dev/null || true
 curl -fsSL "$BASE_URL/docs/research/TEMPLATE.md" -o "docs/research/TEMPLATE.md" 2>/dev/null || true
 
 # Create PROGRESS.md if not exists
@@ -342,7 +341,7 @@ create_link() {
 # Universal SKILL.md content
 SKILL_CONTENT='---
 name: forge-workflow
-description: 9-stage TDD-first workflow for feature development. Use when building features, fixing bugs, or shipping PRs.
+description: 7-stage TDD-first workflow for feature development. Use when building features, fixing bugs, or shipping PRs.
 category: Development Workflow
 tags: [tdd, workflow, pr, git, testing]
 tools: [Bash, Read, Write, Edit, Grep, Glob]
@@ -360,24 +359,23 @@ Automatically invoke this skill when the user wants to:
 - Create a pull request
 - Run the development workflow
 
-## 9 Stages
+## 7 Stages
 
 | Stage | Command | Description |
 |-------|---------|-------------|
-| 1 | `/status` | Check current context, active work, recent completions |
-| 2 | `/research` | Deep research with web search, document to docs/research/ |
-| 3 | `/plan` | Create implementation plan, branch, OpenSpec if strategic |
-| 4 | `/dev` | TDD development (RED-GREEN-REFACTOR cycles) |
-| 5 | `/check` | Validation (type/lint/security/tests) |
-| 6 | `/ship` | Create PR with full documentation |
-| 7 | `/review` | Address ALL PR feedback |
-| 8 | `/merge` | Update docs, merge PR, cleanup |
-| 9 | `/verify` | Final documentation verification |
+| utility | `/status` | Check current context, active work, recent completions |
+| 1 | `/plan` | Design intent -> research -> branch + worktree + task list |
+| 2 | `/dev` | TDD development (implementer -> spec review -> quality review) |
+| 3 | `/validate` | Type check, lint, security, tests - all fresh output |
+| 4 | `/ship` | Push branch and create PR with full documentation |
+| 5 | `/review` | Address ALL PR feedback (GitHub Actions, Greptile, SonarCloud) |
+| 6 | `/premerge` | Update docs, hand off PR to user |
+| 7 | `/verify` | Post-merge health check (CI on main, close Beads) |
 
 ## Workflow Flow
 
 ```
-/status -> /research -> /plan -> /dev -> /check -> /ship -> /review -> /merge -> /verify
+/status -> /plan -> /dev -> /validate -> /ship -> /review -> /premerge -> /verify
 ```
 
 ## Core Principles
@@ -398,10 +396,10 @@ if [ "$INSTALL_CLAUDE" = true ]; then
     mkdir -p .claude/commands .claude/rules .claude/skills/forge-workflow .claude/scripts
 
     # Download commands
-    for cmd in status research plan dev check ship review merge verify; do
+    for cmd in status plan dev validate ship review premerge verify research rollback sonarcloud; do
         curl -fsSL "$BASE_URL/.claude/commands/$cmd.md" -o ".claude/commands/$cmd.md" 2>/dev/null || true
     done
-    echo -e "  ${GREEN}Downloaded: 9 workflow commands${NC}"
+    echo -e "  ${GREEN}Downloaded: 11 workflow commands${NC}"
 
     # Download rules
     curl -fsSL "$BASE_URL/.claude/rules/workflow.md" -o ".claude/rules/workflow.md" 2>/dev/null || true
@@ -458,14 +456,13 @@ alwaysApply: true
 Use these commands via `/command-name`:
 
 1. `/status` - Check current context, active work, recent completions
-2. `/research` - Deep research with web search, document to docs/research/
-3. `/plan` - Create implementation plan, branch, tracking
-4. `/dev` - TDD development (RED-GREEN-REFACTOR cycles)
-5. `/check` - Validation (type/lint/security/tests)
-6. `/ship` - Create PR with full documentation
-7. `/review` - Address ALL PR feedback
-8. `/merge` - Update docs, merge PR, cleanup
-9. `/verify` - Final documentation verification
+2. `/plan` - Design intent -> research -> branch + worktree + task list
+3. `/dev` - TDD development (implementer -> spec review -> quality review)
+4. `/validate` - Type check, lint, security, tests - all fresh output
+5. `/ship` - Push branch and create PR with full documentation
+6. `/review` - Address ALL PR feedback (GitHub Actions, Greptile, SonarCloud)
+7. `/premerge` - Update docs, hand off PR to user
+8. `/verify` - Post-merge health check (CI on main, close Beads)
 
 See AGENTS.md for full workflow details.
 MDC_EOF
@@ -495,7 +492,7 @@ if [ "$INSTALL_WINDSURF" = true ]; then
             filename=$(basename "$cmd")
             strip_frontmatter "$cmd" > ".windsurf/workflows/$filename" 2>/dev/null || cp "$cmd" ".windsurf/workflows/$filename"
         done
-        echo -e "  ${GREEN}Converted: 9 workflow commands${NC}"
+        echo -e "  ${GREEN}Converted: 11 workflow commands${NC}"
 
         # Copy rules
         cp .claude/rules/workflow.md .windsurf/rules/workflow.md 2>/dev/null || true
@@ -525,7 +522,7 @@ if [ "$INSTALL_KILOCODE" = true ]; then
             filename=$(basename "$cmd")
             strip_frontmatter "$cmd" > ".kilocode/workflows/$filename" 2>/dev/null || cp "$cmd" ".kilocode/workflows/$filename"
         done
-        echo -e "  ${GREEN}Converted: 9 workflow commands${NC}"
+        echo -e "  ${GREEN}Converted: 11 workflow commands${NC}"
 
         # Copy rules
         cp .claude/rules/workflow.md .kilocode/rules/workflow.md 2>/dev/null || true
@@ -552,7 +549,7 @@ if [ "$INSTALL_ANTIGRAVITY" = true ]; then
             filename=$(basename "$cmd")
             strip_frontmatter "$cmd" > ".agent/workflows/$filename" 2>/dev/null || cp "$cmd" ".agent/workflows/$filename"
         done
-        echo -e "  ${GREEN}Converted: 9 workflow commands${NC}"
+        echo -e "  ${GREEN}Converted: 11 workflow commands${NC}"
 
         # Copy rules
         cp .claude/rules/workflow.md .agent/rules/workflow.md 2>/dev/null || true
@@ -583,7 +580,7 @@ if [ "$INSTALL_COPILOT" = true ]; then
             filename="${basename_noext}.prompt.md"
             strip_frontmatter "$cmd" > ".github/prompts/$filename" 2>/dev/null || cp "$cmd" ".github/prompts/$filename"
         done
-        echo -e "  ${GREEN}Converted: 9 workflow prompts${NC}"
+        echo -e "  ${GREEN}Converted: 11 workflow prompts${NC}"
     fi
 
     # Link copilot-instructions.md -> AGENTS.md
@@ -615,7 +612,7 @@ if [ "$INSTALL_CONTINUE" = true ]; then
                 strip_frontmatter "$cmd" 2>/dev/null || cat "$cmd"
             } > ".continue/prompts/$filename"
         done
-        echo -e "  ${GREEN}Converted: 9 workflow prompts${NC}"
+        echo -e "  ${GREEN}Converted: 11 workflow prompts${NC}"
     fi
 
     # Create SKILL.md
@@ -660,7 +657,7 @@ if [ "$INSTALL_OPENCODE" = true ]; then
     # Copy commands as-is (same YAML format)
     if [ "$INSTALL_CLAUDE" = true ]; then
         cp .claude/commands/*.md .opencode/commands/ 2>/dev/null || true
-        echo -e "  ${GREEN}Copied: 9 workflow commands${NC}"
+        echo -e "  ${GREEN}Copied: 11 workflow commands${NC}"
     fi
 
     # Create SKILL.md
@@ -701,7 +698,7 @@ if [ "$INSTALL_ROO" = true ]; then
             filename=$(basename "$cmd")
             strip_frontmatter "$cmd" > ".roo/commands/$filename" 2>/dev/null || cp "$cmd" ".roo/commands/$filename"
         done
-        echo -e "  ${GREEN}Converted: 9 workflow commands${NC}"
+        echo -e "  ${GREEN}Converted: 11 workflow commands${NC}"
     fi
 
     # Link .roorules -> AGENTS.md
@@ -725,7 +722,6 @@ if [ "$INSTALL_AIDER" = true ]; then
 # Read AGENTS.md for workflow instructions
 read:
   - AGENTS.md
-  - docs/WORKFLOW.md
 EOF
         echo -e "  ${GREEN}Created: .aider.conf.yml${NC}"
     else
@@ -1043,20 +1039,18 @@ echo -e "  GET STARTED"
 echo -e "==============================================${NC}"
 echo ""
 echo "  /status    - Check current context"
-echo "  /research  - Start researching a feature"
-echo "  /plan      - Create implementation plan"
-echo "  /dev       - Start TDD development"
-echo "  /check     - Run validation"
+echo "  /plan      - Design intent, research, branch + task list"
+echo "  /dev       - TDD development"
+echo "  /validate  - Type check, lint, tests, security"
 echo "  /ship      - Create pull request"
 echo "  /review    - Address PR feedback"
-echo "  /merge     - Merge and cleanup"
-echo "  /verify    - Final documentation check"
+echo "  /premerge  - Update docs, hand off PR"
+echo "  /verify    - Post-merge health check"
 echo ""
-echo "  Full guide: docs/WORKFLOW.md"
+echo "  Full guide: AGENTS.md"
 echo ""
 echo "Optional tools:"
 echo "  - Beads: $PKG_MANAGER install -g @beads/bd && bd init"
-echo "  - OpenSpec: $PKG_MANAGER install -g @fission-ai/openspec"
 echo ""
 echo -e "${CYAN}Package manager detected: $PKG_MANAGER${NC}"
 echo ""

package/lib/agents-config.js

@@ -248,7 +248,7 @@ Generate with: \`bunx forge setup --agent=<name>\`
 ## Support
 
 - **Documentation**: \`docs/\` directory
-- **Workflow Guide**: \`docs/WORKFLOW.md\`
+- **Workflow Guide**: \`AGENTS.md\`
 - **Architecture**: \`docs/ARCHITECTURE.md\` (if it exists)
 - **Configuration**: \`docs/CONFIGURATION.md\` (if it exists)
 
@@ -503,7 +503,7 @@ ${meta.language === 'TypeScript' ? `
 
 ## Additional Resources
 
-- **Workflow Guide**: \`docs/WORKFLOW.md\`
+- **Workflow Guide**: \`AGENTS.md\`
 - **Architecture**: \`docs/ARCHITECTURE.md\`
 - **Configuration**: \`docs/CONFIGURATION.md\`
 `;
@@ -1769,7 +1769,7 @@ bunx forge setup --config=.forgerc.ci.json
 
 - [ARCHITECTURE.md](./ARCHITECTURE.md) - How multi-agent support works
 - [MCP_SETUP.md](./MCP_SETUP.md) - MCP server configuration
-- [WORKFLOW.md](./WORKFLOW.md) - Complete workflow guide
+- [AGENTS.md](../AGENTS.md) - Complete workflow guide
 `;
 }