forge-workflow 0.0.9 → 0.1.0-beta.2

package/docs/VALIDATION.md

@@ -1,363 +0,0 @@
-# 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 `bun test`
-- Verifies all tests pass
-
-**Override**:
-```bash
-LEFTHOOK=0 git push  # Skip all hooks
-```
-
----
-
-## Validation CLI
-
-The `forge-preflight` CLI checks prerequisites for each workflow stage.
-
-### Usage
-
-```bash
-forge-preflight <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-preflight status`
-
-**Purpose**: Check basic project setup
-
-**Checks**:
-- ✓ Git repository initialized
-- ✓ `package.json` exists
-- ✓ Test framework configured (`bun test` script)
-- ✓ Node.js installed
-
-**Example**:
-```bash
-$ forge-preflight status
-
-Checking project prerequisites...
-
-Validation Results:
-
-  ✓ Git repository
-  ✓ package.json exists
-  ✓ Test framework configured
-  ✓ Node.js installed
-
-✅ All checks passed!
-```
-
----
-
-### `forge-preflight dev`
-
-**Purpose**: Validate before starting implementation (`/dev`)
-
-**Checks**:
-- ✓ On feature branch (`feat/*`, `fix/*`, `docs/*`)
-- ✓ Plan file exists (`docs/plans/*.md`)
-- ✓ Research file exists (`docs/research/*.md`)
-- ✓ Test directory exists
-
-**Example**:
-```bash
-$ forge-preflight 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-preflight 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-preflight ship`
-
-**Purpose**: Validate before creating PR (`/ship`)
-
-**Checks**:
-- ✓ Tests exist (`.test.js`, `.spec.ts` files)
-- ✓ Tests pass (`bun test` succeeds)
-- ✓ Documentation updated (`README.md` or `docs/`)
-- ✓ No uncommitted changes
-
-**Example**:
-```bash
-$ forge-preflight 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: bun 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-preflight.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)
-bun add -d lefthook
-
-# Set up Forge
-bunx 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
-bun 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
-bun 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](../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/lib/agents/cline.plugin.json

@@ -1,29 +0,0 @@
-{
-  "id": "cline",
-  "name": "Cline",
-  "version": "1.0.0",
-  "description": "VS Code agent extension",
-  "homepage": "https://github.com/cline/cline",
-  "capabilities": {
-    "commands": true,
-    "skills": false,
-    "hooks": false
-  },
-  "directories": {
-    "workflows": ".cline/workflows"
-  },
-  "files": {
-    "rootConfig": ".clinerules"
-  },
-  "support": {
-    "status": "deprecated",
-    "surface": "editor-native",
-    "install": {
-      "required": false,
-      "repairRequired": false
-    }
-  },
-  "setup": {
-    "copyCommands": true
-  }
-}

package/lib/agents/copilot.plugin.json

@@ -1,24 +0,0 @@
-{
-  "id": "copilot",
-  "name": "GitHub Copilot",
-  "version": "1.0.0",
-  "description": "GitHub's AI assistant with native instructions and prompts",
-  "homepage": "https://github.com/features/copilot",
-  "capabilities": {
-    "commands": true,
-    "skills": false,
-    "hooks": false
-  },
-  "directories": {
-    "prompts": ".github/prompts",
-    "instructions": ".github/instructions"
-  },
-  "files": {
-    "rootConfig": ".github/copilot-instructions.md"
-  },
-  "setup": {
-    "needsConversion": true,
-    "promptFormat": true,
-    "customSetup": "copilot"
-  }
-}

package/lib/agents/kilocode.plugin.json

@@ -1,22 +0,0 @@
-{
-  "id": "kilocode",
-  "name": "Kilo Code",
-  "version": "1.0.0",
-  "description": "VS Code extension with native workflows, rules, and skills",
-  "homepage": "https://marketplace.visualstudio.com/items?itemName=kilo-code",
-  "capabilities": {
-    "commands": true,
-    "skills": true,
-    "hooks": false
-  },
-  "directories": {
-    "workflows": ".kilocode/workflows",
-    "rules": ".kilocode/rules",
-    "skills": ".kilocode/skills/forge-workflow"
-  },
-  "setup": {
-    "copyRules": true,
-    "createSkill": true,
-    "needsConversion": true
-  }
-}

package/lib/agents/opencode.plugin.json

@@ -1,23 +0,0 @@
-{
-  "id": "opencode",
-  "name": "OpenCode",
-  "version": "1.0.0",
-  "description": "Open-source agent with native config and agent definitions",
-  "homepage": "https://opencode.ai",
-  "capabilities": {
-    "commands": true,
-    "skills": false,
-    "hooks": false
-  },
-  "directories": {
-    "commands": ".opencode/commands",
-    "agents": ".opencode/agents"
-  },
-  "files": {
-    "rootConfig": "opencode.json"
-  },
-  "setup": {
-    "copyCommands": true,
-    "customSetup": "opencode"
-  }
-}

package/lib/agents/roo.plugin.json

@@ -1,30 +0,0 @@
-{
-  "id": "roo",
-  "name": "Roo Code",
-  "version": "1.0.0",
-  "description": "Cline fork with modes",
-  "homepage": "https://github.com/roocode/roo",
-  "capabilities": {
-    "commands": true,
-    "skills": false,
-    "hooks": false
-  },
-  "directories": {
-    "commands": ".roo/commands"
-  },
-  "files": {
-    "rootConfig": ".roorules"
-  },
-  "support": {
-    "status": "deprecated",
-    "surface": "editor-native",
-    "install": {
-      "required": false,
-      "repairRequired": false
-    }
-  },
-  "setup": {
-    "copyCommands": true,
-    "needsConversion": true
-  }
-}

package/lib/beads-health-check.js

@@ -1,143 +0,0 @@
-/**
- * Beads health check smoke test.
- *
- * After Beads init, runs a quick create/close/sync/cleanup cycle to verify
- * the installation is functional.
- *
- * @module beads-health-check
- */
-
-const { execFileSync } = require('node:child_process');
-const fs = require('node:fs');
-const path = require('node:path');
-
-/**
- * @typedef {Object} HealthCheckResult
- * @property {boolean} healthy - Whether Beads is operational
- * @property {string|null} failedStep - Which step failed: 'create'|'close'|'sync'|'cleanup', or null
- * @property {string|null} error - Error message if unhealthy, null otherwise
- * @property {string} [warning] - Non-fatal warning message (e.g. sync or cleanup issues)
- */
-
-/**
- * Parse the issue ID from `bd create` stdout.
- *
- * Expects output like "Created issue: forge-xxxx".
- *
- * @param {string} output - stdout from `bd create`
- * @returns {string|null} The issue ID, or null if not found
- */
-function parseIssueId(output) {
-  const match = /Created\s+issue:\s*([\w-]+)/i.exec(output);
-  return match ? match[1].trim() : null;
-}
-
-/**
- * Remove a test issue from the JSONL file by its ID.
- * Silently ignores errors (file missing, locked, malformed lines).
- *
- * @param {string} jsonlPath - Absolute path to the issues.jsonl file
- * @param {string|null} issueId - The issue ID to remove
- */
-function cleanupTestIssue(jsonlPath, issueId) {
-  if (!issueId) return;
-  const raw = fs.readFileSync(jsonlPath, 'utf8');
-  const lines = raw.split('\n').filter(Boolean);
-  const filtered = lines.filter((line) => {
-    try { return JSON.parse(line).id !== issueId; } catch (_e) { /* Expected: malformed JSONL line — keep it as-is */ return true; }
-  });
-  fs.writeFileSync(jsonlPath, filtered.length > 0 ? filtered.join('\n') + '\n' : '');
-}
-
-/**
- * Run a Beads health check smoke test.
- *
- * Creates a temporary issue, closes it, syncs, then cleans up the JSONL file.
- * Uses dependency injection for the exec function to support testing.
- *
- * @param {string} projectRoot - Absolute path to the project root
- * @param {Object} [options={}] - Options
- * @param {Function} [options._exec] - Injectable exec function (defaults to execFileSync)
- * @returns {HealthCheckResult}
- */
-function beadsHealthCheck(projectRoot, options = {}) {
-  const exec = options._exec || execFileSync;
-  const execOpts = { cwd: projectRoot, encoding: 'utf8' };
-
-  /** @type {string|undefined} */
-  let warning;
-
-  // Step a: Create a test issue
-  /** @type {string|null} */
-  let issueId;
-  try {
-    const createOutput = exec('bd', [
-      'create',
-      '--title=Setup verification',
-      '--type=task',
-      '--priority=4'
-    ], execOpts);
-
-    issueId = parseIssueId(createOutput);
-    if (!issueId) {
-      return {
-        healthy: false,
-        failedStep: 'create',
-        error: 'Could not parse issue ID from bd create output'
-      };
-    }
-  } catch (err) {
-    return {
-      healthy: false,
-      failedStep: 'create',
-      error: err.message
-    };
-  }
-
-  // Step b: Close the test issue
-  try {
-    exec('bd', [
-      'close',
-      issueId,
-      '--reason=Setup smoke test'
-    ], execOpts);
-  } catch (err) {
-    // Best-effort cleanup: remove the test issue from JSONL so it doesn't leak
-    try {
-      cleanupTestIssue(path.join(projectRoot, '.beads', 'issues.jsonl'), issueId);
-    } catch (_cleanupErr) {
-      // Expected: JSONL cleanup may fail if file is locked or missing — nothing more we can do
-    }
-    return {
-      healthy: false,
-      failedStep: 'close',
-      error: err.message
-    };
-  }
-
-  // Step c: Sync (may fail without a remote -- that's OK)
-  try {
-    exec('bd', ['sync'], execOpts);
-  } catch (syncErr) {
-    // Sync failure is non-fatal (no remote configured is common)
-    warning = `bd sync warning: ${syncErr.message}`;
-  }
-
-  // Step d: Remove the test issue from JSONL
-  try {
-    cleanupTestIssue(path.join(projectRoot, '.beads', 'issues.jsonl'), issueId);
-  } catch (cleanupErr) {
-    // Cleanup failure is non-fatal
-    const cleanupWarning = `cleanup warning: ${cleanupErr.message}`;
-    warning = warning ? `${warning}; ${cleanupWarning}` : cleanupWarning;
-  }
-
-  return {
-    healthy: true,
-    failedStep: null,
-    error: null,
-    ...(warning ? { warning } : {})
-  };
-}
-
-module.exports = { beadsHealthCheck, parseIssueId };