forge-workflow 1.4.9 → 1.5.0

package/docs/SETUP.md

@@ -27,6 +27,12 @@ npm install forge-workflow
 npx forge setup
 ```
 
+**Interactive prompts**:
+1. Which agents do you use?
+2. Install Beads? (y/n) - Git-backed issue tracking
+3. Install OpenSpec? (y/n) - Spec-driven development
+4. Configure external services? (optional)
+
 **What gets created**:
 - `AGENTS.md` - Universal instructions (always)
 - Agent-specific files based on your selection

package/docs/TOOLCHAIN.md

@@ -47,11 +47,24 @@ Complete reference for all tools integrated with the Forge workflow.
 
 ### Installation
 
+**Auto-installation** (Recommended):
 ```bash
-# npm (recommended)
+npx forge setup
+# Prompts: "Install Beads? (y/n)"
+# Automatically installs and initializes
+```
+
+**Manual installation**:
+```bash
+# npm (global)
 npm install -g @beads/bd
+bd init
+
+# npm (local)
+npm install -D @beads/bd
+npx bd init
 
-# Or with bunx (no global install)
+# Or with bunx (no install needed)
 bunx @beads/bd init
 ```
 
@@ -216,11 +229,24 @@ bd sync                     # Always sync at end!
 
 ### Installation
 
+**Auto-installation** (Recommended):
 ```bash
-# npm (requires Node.js 20.19+)
+npx forge setup
+# Prompts: "Install OpenSpec? (y/n)"
+# Automatically installs and initializes (if selected)
+```
+
+**Manual installation**:
+```bash
+# npm (global - requires Node.js 20.19+)
 npm install -g @fission-ai/openspec
+openspec init
+
+# npm (local)
+npm install -D @fission-ai/openspec
+npx openspec init
 
-# Or with bunx
+# Or with bunx (no install needed)
 bunx @fission-ai/openspec init
 ```
 

package/docs/VALIDATION.md

@@ -0,0 +1,363 @@
+# Validation & Enforcement
+
+Forge includes built-in validation and TDD enforcement to ensure quality and consistency.
+
+## Table of Contents
+
+- [Git Hooks](#git-hooks)
+- [Validation CLI](#validation-cli)
+- [Validators by Stage](#validators-by-stage)
+- [Override Mechanisms](#override-mechanisms)
+- [Configuration](#configuration)
+
+---
+
+## Git Hooks
+
+Forge uses [Lefthook](https://github.com/evilmartians/lefthook) for fast, language-agnostic git hooks.
+
+### Pre-Commit Hook
+
+**Purpose**: Enforce TDD by blocking commits of source code without tests.
+
+**Trigger**: Before every commit
+
+**Checks**:
+- Detects staged source files (`.js`, `.ts`, `.py`, `.go`, `.java`, `.rb`, etc.)
+- Verifies corresponding test files exist (`.test.js`, `.spec.ts`, etc.)
+- Excludes config files, test files, and documentation
+
+**Behavior**:
+When source code lacks tests, offers guided recovery:
+
+```
+⚠️  Looks like you're committing source code without tests:
+
+  - src/user-service.js
+
+📋 TDD Reminder:
+  Write tests BEFORE implementation (RED-GREEN-REFACTOR)
+
+What would you like to do?
+  1. Unstage source files (keep tests staged)
+  2. Continue anyway (I have a good reason)
+  3. Abort commit (let me add tests)
+
+Your choice (1-3):
+```
+
+**Override**:
+```bash
+git commit --no-verify  # Skip in emergencies
+```
+
+### Pre-Push Hook
+
+**Purpose**: Ensure all tests pass before pushing to remote.
+
+**Trigger**: Before every push
+
+**Checks**:
+- Runs `npm test`
+- Verifies all tests pass
+
+**Override**:
+```bash
+LEFTHOOK=0 git push  # Skip all hooks
+```
+
+---
+
+## Validation CLI
+
+The `forge-validate` CLI checks prerequisites for each workflow stage.
+
+### Usage
+
+```bash
+forge-validate <command>
+```
+
+### Commands
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `status` | Check project prerequisites | Setup, onboarding |
+| `dev` | Validate before `/dev` | Before implementation |
+| `ship` | Validate before `/ship` | Before creating PR |
+
+---
+
+## Validators by Stage
+
+### `forge-validate status`
+
+**Purpose**: Check basic project setup
+
+**Checks**:
+- ✓ Git repository initialized
+- ✓ `package.json` exists
+- ✓ Test framework configured (`npm test` script)
+- ✓ Node.js installed
+
+**Example**:
+```bash
+$ forge-validate status
+
+Checking project prerequisites...
+
+Validation Results:
+
+  ✓ Git repository
+  ✓ package.json exists
+  ✓ Test framework configured
+  ✓ Node.js installed
+
+✅ All checks passed!
+```
+
+---
+
+### `forge-validate dev`
+
+**Purpose**: Validate before starting implementation (`/dev`)
+
+**Checks**:
+- ✓ On feature branch (`feat/*`, `fix/*`, `docs/*`)
+- ✓ Plan file exists (`.claude/plans/*.md`)
+- ✓ Research file exists (`docs/research/*.md`)
+- ✓ Test directory exists
+
+**Example**:
+```bash
+$ forge-validate dev
+
+Validating prerequisites for /dev stage...
+
+Validation Results:
+
+  ✓ On feature branch
+  ✓ Plan file exists
+  ✓ Research file exists
+  ✓ Test directory exists
+
+✅ All checks passed!
+```
+
+**Failed Example**:
+```bash
+$ forge-validate dev
+
+Validating prerequisites for /dev stage...
+
+Validation Results:
+
+  ✗ On feature branch
+    Not on a feature branch. Create one: git checkout -b feat/your-feature
+  ✓ Plan file exists
+  ✗ Research file exists
+    No research file found in docs/research/. Run: /research
+
+❌ Some checks failed. Please fix the issues above.
+```
+
+---
+
+### `forge-validate ship`
+
+**Purpose**: Validate before creating PR (`/ship`)
+
+**Checks**:
+- ✓ Tests exist (`.test.js`, `.spec.ts` files)
+- ✓ Tests pass (`npm test` succeeds)
+- ✓ Documentation updated (`README.md` or `docs/`)
+- ✓ No uncommitted changes
+
+**Example**:
+```bash
+$ forge-validate ship
+
+Validating prerequisites for /ship stage...
+
+Validation Results:
+
+  ✓ Tests exist
+  ✓ Tests pass
+  ✓ Documentation updated
+  ✓ No uncommitted changes
+
+✅ All checks passed!
+```
+
+---
+
+## Override Mechanisms
+
+### Git Hooks
+
+**Emergency Override** (use sparingly):
+
+```bash
+# Skip pre-commit hook
+git commit --no-verify -m "Emergency hotfix"
+
+# Skip pre-push hook
+LEFTHOOK=0 git push
+```
+
+**When to use**:
+- Emergency hotfixes
+- Work-in-progress commits (before pushing)
+- Non-code commits (docs, config)
+
+**When NOT to use**:
+- Regular development
+- Public repositories
+- Production deployments
+
+### Validation CLI
+
+The CLI provides guidance but doesn't block actions. You can proceed manually if checks fail.
+
+---
+
+## Configuration
+
+### Lefthook Configuration
+
+Edit `lefthook.yml` to customize hooks:
+
+```yaml
+pre-commit:
+  commands:
+    tdd-check:
+      run: node .forge/hooks/check-tdd.js
+      stage_fixed: false
+      tags: tdd
+      glob: "*.{js,ts,jsx,tsx,py,go,java,rb}"
+
+pre-push:
+  commands:
+    tests:
+      run: npm test
+      tags: tests
+```
+
+**Options**:
+- `run`: Command to execute
+- `stage_fixed`: Auto-stage modified files (false = safer)
+- `tags`: Categorize hooks
+- `glob`: File patterns to trigger hook
+
+### Custom Test Patterns
+
+Edit `.forge/hooks/check-tdd.js` to add custom test patterns:
+
+```javascript
+// Around line 72
+const testPatterns = [
+  `${basename}.test${ext}`,
+  `${basename}.spec${ext}`,
+  `test/${basename}.test${ext}`,
+  `tests/${basename}.test${ext}`,
+  `__tests__/${basename}.test${ext}`,
+  // Add custom patterns here
+  `${dir}/__tests__/${basename}${ext}`,
+  `spec/${basename}_spec${ext}`,  // RSpec style
+];
+```
+
+### Validation CLI Customization
+
+Edit `bin/forge-validate.js` to add custom validators:
+
+```javascript
+function validateCustomStage() {
+  console.log('Validating custom stage...\n');
+
+  check('Custom check', () => {
+    // Your validation logic
+    return true;
+  }, 'Custom error message');
+
+  return printResults();
+}
+```
+
+---
+
+## Installation
+
+Hooks are automatically installed when you run:
+
+```bash
+# Install lefthook (one-time)
+npm install -D lefthook
+
+# Set up Forge
+npx forge setup
+```
+
+The hooks will be automatically installed in your project's `.git/hooks/` directory.
+
+**Manual installation** (if needed):
+
+```bash
+# If you prefer global installation
+npm install -g lefthook
+
+# Install hooks
+lefthook install
+```
+
+---
+
+## Troubleshooting
+
+### Hooks not running
+
+```bash
+# Check lefthook installation
+lefthook version
+
+# Reinstall hooks
+lefthook install
+
+# Check git hooks directory
+ls -la .git/hooks/
+```
+
+### False positives
+
+If the hook incorrectly flags a file:
+
+1. **Short-term**: Use `--no-verify` to skip
+2. **Long-term**: Update exclusion patterns in `.forge/hooks/check-tdd.js`
+
+### Tests failing on push
+
+```bash
+# Run tests locally
+npm test
+
+# Fix failures, then
+git push
+```
+
+---
+
+## Best Practices
+
+1. **Write tests first**: Let the hooks guide you to TDD
+2. **Don't abuse overrides**: Only use `--no-verify` in emergencies
+3. **Keep tests fast**: Pre-push hooks run on every push
+4. **Document exceptions**: If you override, explain why in commit message
+5. **Update validators**: Customize for your project's needs
+
+---
+
+## See Also
+
+- [Workflow Guide](WORKFLOW.md) - Complete 9-stage workflow
+- [TDD Guide](../CLAUDE.md) - TDD principles and practices
+- [Lefthook Docs](https://github.com/evilmartians/lefthook) - Full hook configuration

package/lefthook.yml

@@ -0,0 +1,30 @@
+# Lefthook Git Hooks Configuration
+# TDD Enforcement for Forge Workflow
+#
+# To skip hooks in emergencies:
+#   git commit --no-verify  (skip pre-commit)
+#   LEFTHOOK=0 git push     (skip pre-push)
+
+pre-commit:
+  commands:
+    tdd-check:
+      run: node .forge/hooks/check-tdd.js
+      stage_fixed: false
+      tags: tdd
+      glob: "*.{js,ts,jsx,tsx,py,go,java,rb}"
+
+pre-push:
+  commands:
+    tests:
+      # Detect package manager: bun > pnpm > yarn > npm
+      run: |
+        if command -v bun >/dev/null 2>&1 && [ -f "bun.lockb" ]; then
+          bun test
+        elif command -v pnpm >/dev/null 2>&1 && [ -f "pnpm-lock.yaml" ]; then
+          pnpm test
+        elif command -v yarn >/dev/null 2>&1 && [ -f "yarn.lock" ]; then
+          yarn test
+        else
+          npm test
+        fi
+      tags: tests

package/lib/agents/README.md

@@ -0,0 +1,202 @@
+# Agent Plugins
+
+This directory contains plugin definitions for all supported AI coding agents.
+
+## Plugin Architecture
+
+Each agent is defined by a JSON file following the plugin schema. This allows:
+- **Discoverability**: New agents can be added without modifying core code
+- **Community contributions**: Anyone can add support for new agents
+- **Backwards compatibility**: Existing functionality remains unchanged
+- **Maintainability**: Agent configurations are separated from business logic
+
+## Plugin Schema
+
+Each plugin file must follow this structure:
+
+```json
+{
+  "id": "agent-id",           // REQUIRED: Unique identifier (lowercase, alphanumeric, hyphens)
+  "name": "Agent Name",       // REQUIRED: Human-readable name
+  "version": "1.0.0",         // REQUIRED: Semantic version (x.y.z)
+  "description": "...",       // OPTIONAL: Brief description
+  "homepage": "https://...",  // OPTIONAL: Agent's homepage URL
+  "capabilities": {           // OPTIONAL: Agent capabilities
+    "commands": true,         // Supports commands
+    "skills": true,           // Supports skills
+    "hooks": false            // Supports git hooks
+  },
+  "directories": {            // REQUIRED: Directory structure (at least one)
+    "commands": ".agent/commands",
+    "rules": ".agent/rules",
+    "skills": ".agent/skills/forge-workflow",
+    "scripts": ".agent/scripts"
+  },
+  "files": {                  // OPTIONAL: Important file paths
+    "rootConfig": "AGENT.md",
+    "skillDefinition": ".agent/skills/forge-workflow/SKILL.md"
+  },
+  "setup": {                  // OPTIONAL: Setup instructions
+    "copyCommands": true,
+    "copyRules": true,
+    "createSkill": true,
+    "customSetup": "agent-name",
+    "needsConversion": false
+  }
+}
+```
+
+### Required Fields
+
+- **id**: Unique identifier for the agent (must match filename without `.plugin.json`)
+- **name**: Display name shown to users
+- **version**: Semantic version number (major.minor.patch)
+- **directories**: Object with at least one directory path
+
+### Optional Fields
+
+- **description**: Short description of the agent
+- **homepage**: URL to agent's official website
+- **capabilities**: Object defining what the agent supports
+- **files**: Important configuration file paths
+- **setup**: Installation and setup instructions
+
+## Supported Agents
+
+Currently supported AI coding agents:
+
+| Agent | ID | Description |
+|-------|----|-----------|
+| Claude Code | `claude` | Anthropic's CLI agent |
+| Cursor | `cursor` | AI-first code editor |
+| Windsurf | `windsurf` | Codeium's agentic IDE |
+| Kilo Code | `kilocode` | VS Code extension |
+| Google Antigravity | `antigravity` | Google's agent IDE |
+| GitHub Copilot | `copilot` | GitHub's AI assistant |
+| Continue | `continue` | Open-source AI assistant |
+| OpenCode | `opencode` | Open-source agent |
+| Cline | `cline` | VS Code agent extension |
+| Roo Code | `roo` | Cline fork with modes |
+| Aider | `aider` | Terminal-based agent |
+
+## Adding a New Agent
+
+To add support for a new AI coding agent:
+
+1. **Create plugin file**: `lib/agents/your-agent.plugin.json`
+2. **Follow schema**: Use the template below or copy an existing plugin
+3. **Validate**: Run tests to ensure your plugin is valid
+4. **Test**: Run `npx forge setup --agents your-agent` to verify
+5. **Submit PR**: Contribute back to the community!
+
+### Plugin Template
+
+See `.github/PLUGIN_TEMPLATE.json` for a ready-to-use template.
+
+```json
+{
+  "id": "your-agent",
+  "name": "Your Agent Name",
+  "version": "1.0.0",
+  "description": "Brief description of your agent",
+  "homepage": "https://your-agent.example.com",
+  "capabilities": {
+    "commands": true,
+    "skills": true,
+    "hooks": false
+  },
+  "directories": {
+    "rules": ".your-agent/rules",
+    "skills": ".your-agent/skills/forge-workflow"
+  },
+  "files": {
+    "rootConfig": ".your-agent-rules"
+  },
+  "setup": {
+    "createSkill": true
+  }
+}
+```
+
+## Validation
+
+The PluginManager automatically validates all plugins on load:
+
+- **Schema validation**: Required fields must be present
+- **Type checking**: Fields must have correct types
+- **Unique IDs**: No duplicate plugin IDs allowed
+- **JSON syntax**: Files must be valid JSON
+
+Run tests to validate your plugin:
+
+```bash
+npm test test/plugins/
+```
+
+## Community Contributions
+
+We welcome community contributions for new AI coding agents!
+
+**Before submitting:**
+1. Ensure your plugin passes all validation tests
+2. Test the agent setup with `npx forge setup --agents your-agent`
+3. Document any special setup requirements
+4. Follow the existing plugin structure
+
+**PR Guidelines:**
+- One plugin per PR
+- Include plugin JSON file only (no code changes needed)
+- Update this README with agent information
+- Test that all existing tests still pass
+
+## Technical Details
+
+### Plugin Loading
+
+The `PluginManager` class (`lib/plugin-manager.js`) handles:
+- Auto-discovery of `.plugin.json` files in this directory
+- Schema validation for each plugin
+- Conversion to internal AGENTS format (backwards compatibility)
+- Error handling for invalid plugins
+
+### Backwards Compatibility
+
+Plugins are automatically converted to the legacy AGENTS object structure:
+
+```javascript
+{
+  name: plugin.name,
+  description: plugin.description,
+  dirs: Object.values(plugin.directories),
+  hasCommands: plugin.capabilities?.commands,
+  hasSkill: plugin.capabilities?.skills,
+  // ... other fields
+}
+```
+
+This ensures existing code continues to work without modifications.
+
+## Troubleshooting
+
+### Plugin Not Loading
+
+If your plugin isn't appearing in `npx forge setup`:
+
+1. **Check filename**: Must end with `.plugin.json`
+2. **Validate JSON**: Ensure file is valid JSON (no trailing commas, quotes correct)
+3. **Check required fields**: id, name, version, directories must be present
+4. **Run tests**: `npm test test/plugins/` will show specific errors
+5. **Check logs**: Any loading errors will be displayed
+
+### Schema Validation Errors
+
+Common validation errors:
+
+- `missing required field "id"`: Add the id field
+- `"directories" must be an object`: Ensure directories is an object, not array
+- `"version" must be a string`: Version must be in "x.y.z" format
+- `Plugin with ID "x" already exists`: Choose a unique ID
+
+## License
+
+All plugin definitions in this directory are MIT licensed, same as the Forge project.

package/lib/agents/aider.plugin.json

@@ -0,0 +1,16 @@
+{
+  "id": "aider",
+  "name": "Aider",
+  "version": "1.0.0",
+  "description": "Terminal-based agent",
+  "homepage": "https://aider.chat",
+  "capabilities": {
+    "commands": false,
+    "skills": false,
+    "hooks": false
+  },
+  "directories": {},
+  "setup": {
+    "customSetup": "aider"
+  }
+}

package/lib/agents/antigravity.plugin.json

@@ -0,0 +1,25 @@
+{
+  "id": "antigravity",
+  "name": "Google Antigravity",
+  "version": "1.0.0",
+  "description": "Google's agent IDE",
+  "homepage": "https://developers.google.com/ai",
+  "capabilities": {
+    "commands": false,
+    "skills": true,
+    "hooks": false
+  },
+  "directories": {
+    "workflows": ".agent/workflows",
+    "rules": ".agent/rules",
+    "skills": ".agent/skills/forge-workflow"
+  },
+  "files": {
+    "rootConfig": "GEMINI.md"
+  },
+  "setup": {
+    "copyRules": true,
+    "createSkill": true,
+    "needsConversion": true
+  }
+}