forge-workflow 1.4.7 → 1.5.0

package/.forge/hooks/check-tdd.js

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+
+/**
+ * TDD Enforcement Hook
+ *
+ * Checks if source code changes have corresponding test files.
+ * Offers guided recovery options when violations are found.
+ *
+ * Security: Uses execFileSync to prevent command injection.
+ */
+
+const { execFileSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+const readline = require("node:readline");
+
+// Get staged files using git diff --cached
+function getStagedFiles() {
+  try {
+    const output = execFileSync(
+      "git",
+      ["diff", "--cached", "--name-only", "--diff-filter=ACM"],
+      {
+        encoding: "utf8",
+        stdio: ["pipe", "pipe", "pipe"],
+      },
+    );
+    return output.trim().split("\n").filter(Boolean);
+  } catch (error) {
+    console.error("Error getting staged files:", error.message);
+    process.exit(1);
+  }
+}
+
+// Check if a file is a source file (not test, not config)
+function isSourceFile(file) {
+  const sourceExtensions = [
+    ".js",
+    ".ts",
+    ".jsx",
+    ".tsx",
+    ".py",
+    ".go",
+    ".java",
+    ".rb",
+  ];
+  const ext = path.extname(file);
+
+  if (!sourceExtensions.includes(ext)) return false;
+
+  // Exclude test files
+  if (file.includes(".test.") || file.includes(".spec.")) return false;
+
+  // Exclude common config files
+  const excludePatterns = [
+    /^\./, // dot files
+    /config\./,
+    /\.config\./,
+    /setup\./,
+    /^test\//,
+    /^tests\//,
+    /__tests__\//,
+    /package\.json/,
+    /tsconfig/,
+    /jest\.config/,
+    /vite\.config/,
+  ];
+
+  return !excludePatterns.some((pattern) => pattern.test(file));
+}
+
+// Find corresponding test file for a source file
+function hasTestFile(sourceFile, stagedFiles) {
+  const dir = path.dirname(sourceFile);
+  const basename = path.basename(sourceFile, path.extname(sourceFile));
+  const ext = path.extname(sourceFile);
+
+  // Common test patterns (including nested directories)
+  const testPatterns = [
+    // Colocated tests
+    `${basename}.test${ext}`,
+    `${basename}.spec${ext}`,
+    `${dir}/${basename}.test${ext}`,
+    `${dir}/${basename}.spec${ext}`,
+    `${dir}/__tests__/${basename}.test${ext}`,
+    `${dir}/__tests__/${basename}.spec${ext}`,
+    // Top-level test directories
+    `test/${basename}.test${ext}`,
+    `test/${basename}.spec${ext}`,
+    `tests/${basename}.test${ext}`,
+    `tests/${basename}.spec${ext}`,
+    `__tests__/${basename}.test${ext}`,
+    `__tests__/${basename}.spec${ext}`,
+    // Nested test directories (unit/integration)
+    `test/unit/${basename}.test${ext}`,
+    `test/unit/${basename}.spec${ext}`,
+    `test/integration/${basename}.test${ext}`,
+    `test/integration/${basename}.spec${ext}`,
+    `tests/unit/${basename}.test${ext}`,
+    `tests/unit/${basename}.spec${ext}`,
+    `tests/integration/${basename}.test${ext}`,
+    `tests/integration/${basename}.spec${ext}`,
+  ];
+
+  // Check if test file exists in staged files or filesystem
+  for (const pattern of testPatterns) {
+    if (stagedFiles.includes(pattern)) return true;
+    if (fs.existsSync(pattern)) return true;
+  }
+
+  return false;
+}
+
+// Prompt user for action (handles non-TTY environments like CI/CD)
+function promptUser(question, options) {
+  return new Promise((resolve) => {
+    // In non-interactive environments (CI/CD), auto-abort to enforce TDD
+    if (!process.stdin.isTTY) {
+      console.log("\n⚠️  Non-interactive environment detected (CI/CD).");
+      console.log("Aborting commit - source files must have tests.");
+      console.log("💡 Tip: Use --no-verify to skip this check if needed.");
+      resolve("abort");
+      return;
+    }
+
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    console.log("\n" + question);
+    options.forEach((opt, i) => {
+      console.log(`  ${i + 1}. ${opt.label}`);
+    });
+    console.log();
+
+    rl.question("Your choice (1-" + options.length + "): ", (answer) => {
+      rl.close();
+      const choice = parseInt(answer, 10) - 1;
+      if (choice >= 0 && choice < options.length) {
+        resolve(options[choice].value);
+      } else {
+        console.log("Invalid choice. Aborting commit.");
+        resolve("abort");
+      }
+    });
+  });
+}
+
+// Main hook logic
+async function main() {
+  console.log("🔍 TDD Check: Verifying test coverage for staged files...\n");
+
+  const stagedFiles = getStagedFiles();
+
+  if (stagedFiles.length === 0) {
+    console.log("✓ No staged files to check.");
+    process.exit(0);
+  }
+
+  const sourceFiles = stagedFiles.filter(isSourceFile);
+
+  if (sourceFiles.length === 0) {
+    console.log("✓ No source files staged (only tests/config/docs).");
+    process.exit(0);
+  }
+
+  const filesWithoutTests = sourceFiles.filter(
+    (file) => !hasTestFile(file, stagedFiles),
+  );
+
+  if (filesWithoutTests.length === 0) {
+    console.log("✓ All source files have corresponding tests!");
+    process.exit(0);
+  }
+
+  // Found violations
+  console.log("⚠️  Looks like you're committing source code without tests:\n");
+  filesWithoutTests.forEach((file) => {
+    console.log(`  - ${file}`);
+  });
+  console.log();
+
+  console.log("📋 TDD Reminder:");
+  console.log("  Write tests BEFORE implementation (RED-GREEN-REFACTOR)");
+  console.log();
+
+  const action = await promptUser("What would you like to do?", [
+    { label: "Unstage source files (keep tests staged)", value: "unstage" },
+    { label: "Continue anyway (I have a good reason)", value: "continue" },
+    { label: "Abort commit (let me add tests)", value: "abort" },
+  ]);
+
+  switch (action) {
+    case "unstage":
+      console.log("\n📝 Unstaging source files without tests...");
+      filesWithoutTests.forEach((file) => {
+        try {
+          execFileSync("git", ["reset", "HEAD", file], { stdio: "inherit" });
+          console.log(`  ✓ Unstaged: ${file}`);
+        } catch (error) {
+          console.error(`  ✗ Failed to unstage: ${file}`);
+        }
+      });
+      console.log(
+        "\nYou can now commit your tests and add source files later.",
+      );
+      process.exit(0);
+      break;
+
+    case "continue":
+      console.log("\n✓ Continuing with commit...");
+      console.log("💡 Tip: Use --no-verify to skip this check in emergencies.");
+      process.exit(0);
+      break;
+
+    case "abort":
+    default:
+      console.log("\n❌ Commit aborted. Add tests and try again!");
+      console.log("💡 Tip: Use --no-verify to skip this check if needed.");
+      process.exit(1);
+  }
+}
+
+// Run with error handling
+main().catch((error) => {
+  console.error("Error in TDD check hook:", error.message);
+  process.exit(1);
+});

package/.github/PLUGIN_TEMPLATE.json

@@ -0,0 +1,32 @@
+{
+  "id": "your-agent",
+  "name": "Your Agent Name",
+  "version": "1.0.0",
+  "description": "Brief description of your AI coding agent",
+  "homepage": "https://your-agent.example.com",
+  "capabilities": {
+    "commands": true,
+    "skills": true,
+    "hooks": false
+  },
+  "directories": {
+    "commands": ".your-agent/commands",
+    "rules": ".your-agent/rules",
+    "skills": ".your-agent/skills/forge-workflow",
+    "scripts": ".your-agent/scripts"
+  },
+  "files": {
+    "rootConfig": ".your-agent-rules",
+    "skillDefinition": ".your-agent/skills/forge-workflow/SKILL.md"
+  },
+  "setup": {
+    "copyCommands": true,
+    "copyRules": true,
+    "copyScripts": false,
+    "createSkill": true,
+    "customSetup": "",
+    "needsConversion": false,
+    "promptFormat": false,
+    "continueFormat": false
+  }
+}

package/AGENTS.md

@@ -1,112 +1,173 @@
-# Project Instructions
+# Project Workflow Instructions
 
-This is a [describe what this project does in one sentence].
+## 9-Stage TDD-First Workflow
 
-**Package manager**: npm (or specify: pnpm/yarn/bun)
+This project enforces a **strict TDD-first development workflow** with 9 stages:
 
-**Build commands**:
+| Stage | Command     | Purpose                                      | Required For |
+|-------|-------------|----------------------------------------------|--------------|
+| 1     | `/status`   | Check current context, active work           | All types    |
+| 2     | `/research` | Research with web search, document findings  | Critical     |
+| 3     | `/plan`     | Create implementation plan, branch, OpenSpec | Critical, Standard, Refactor |
+| 4     | `/dev`      | TDD development (RED-GREEN-REFACTOR)         | All types    |
+| 5     | `/check`    | Validation (type/lint/security/tests)        | All types    |
+| 6     | `/ship`     | Create PR with documentation                 | All types    |
+| 7     | `/review`   | Address ALL PR feedback                      | Critical, Standard |
+| 8     | `/merge`    | Update docs, merge PR, cleanup               | All types    |
+| 9     | `/verify`   | Final documentation verification             | All types    |
 
-```bash
-npm install      # Install dependencies
-npm run dev      # Start development
-npm run build    # Production build
-npm test         # Run tests
-```
-
----
+## Automatic Change Classification
 
-## Forge Workflow
+When the user requests work, **you MUST automatically classify** the change type:
 
-This project uses the **Forge 9-stage TDD workflow**:
+### Critical (Full 9-stage workflow)
+**Triggers:** Security, authentication, payments, breaking changes, new architecture, data migrations
+**Example:** "Add OAuth login", "Migrate database schema", "Implement payment gateway"
+**Workflow:** status → research → plan → dev → check → ship → review → merge → verify
 
-| Stage | Command     | Purpose                                      |
-|-------|-------------|----------------------------------------------|
-| 1     | `/status`   | Check current context, active work           |
-| 2     | `/research` | Research with web search, document findings  |
-| 3     | `/plan`     | Create implementation plan, branch, OpenSpec |
-| 4     | `/dev`      | TDD development (RED-GREEN-REFACTOR)         |
-| 5     | `/check`    | Validation (type/lint/security/tests)        |
-| 6     | `/ship`     | Create PR with documentation                 |
-| 7     | `/review`   | Address ALL PR feedback                      |
-| 8     | `/merge`    | Update docs, merge PR, cleanup               |
-| 9     | `/verify`   | Final documentation verification             |
+### Standard (6-stage workflow, research optional)
+**Triggers:** Normal features, enhancements, new components
+**Example:** "Add user profile page", "Create notification system"
+**Workflow:** status → plan → dev → check → ship → merge
 
-**Flow**: `/status` → `/research` → `/plan` → `/dev` → `/check` → `/ship` → `/review` → `/merge` → `/verify`
+### Simple (4-stage workflow, skip research/plan)
+**Triggers:** Bug fixes, UI tweaks, small changes, minor refactors
+**Example:** "Fix button color", "Update validation message", "Adjust padding"
+**Workflow:** dev → check → ship → merge
 
-See [docs/WORKFLOW.md](docs/WORKFLOW.md) for complete workflow guide.
+### Hotfix (Emergency 3-stage workflow)
+**Triggers:** Production emergencies, critical bugs affecting users
+**Example:** "Production payment processing down", "Security vulnerability fix"
+**Workflow:** dev → check → ship (immediate merge allowed)
 
----
+### Docs (Documentation-only workflow)
+**Triggers:** Documentation updates, README changes, comment improvements
+**Example:** "Update README", "Add API documentation"
+**Workflow:** verify → ship → merge
 
-## Core Principles
+### Refactor (5-stage workflow for safe cleanup)
+**Triggers:** Code cleanup, performance optimization, technical debt reduction
+**Example:** "Refactor auth service", "Extract utility functions"
+**Workflow:** plan → dev → check → ship → merge
 
-- **TDD-First**: Write tests BEFORE implementation (RED-GREEN-REFACTOR)
-- **Research-First**: Understand before building, document decisions
-- **Security Built-In**: OWASP Top 10 analysis for every feature
-- **Documentation Progressive**: Update at each stage, verify at end
+## Enforcement Philosophy
 
----
+**Conversational, not blocking** - Offer solutions when prerequisites are missing:
 
-## MCP Servers (Enhanced Capabilities)
+❌ **Don't:** "ERROR: Research required for critical features"
+✅ **Do:** "Before implementation, I should research OAuth best practices. I can:
+   1. Auto-research now with parallel-ai (~5 min)
+   2. Use your research if you have it
+   3. Skip (not recommended for security features)
 
-This project uses MCP (Model Context Protocol) servers for enhanced capabilities. If your AI agent supports MCP, set up these servers:
+   What would you prefer?"
 
-**Available MCP servers:**
+**Create accountability for skips:**
 
-- **Context7**: Up-to-date library documentation and API reference
-- **grep.app**: Search 1M+ GitHub repos for real-world code examples
+"Skipping tests creates technical debt. I'll:
+ ✓ Allow this commit
+ ✓ Create follow-up Beads issue for tests
+ ✓ Document in commit message as [tech-debt]
 
-**Setup for your agent:**
+ Proceed?"
 
-See [.mcp.json.example](.mcp.json.example) for configuration. Setup varies by agent:
+## TDD Development (Stage 4: /dev)
 
-- **Claude Code**: Copy `.mcp.json.example` to `.mcp.json` in project root
-- **Cline**: Add MCP servers in VSCode settings (Extensions > Cline > MCP Servers)
-- **Continue**: Add to `.continue/config.json` under `mcpServers`
-- **Cursor**: Check Cursor Settings > MCP for setup
-- **Your agent**: If MCP-capable, configure using the example file
+**Automatic orchestration with parallel Task agents:**
 
-**Agent instructions:**
+1. **Analyze plan** → Identify parallel vs sequential tasks from Beads/OpenSpec
+2. **Launch Task agents** → Spawn specialized agents for independent work
+3. **Enforce RED-GREEN-REFACTOR** → Each agent follows strict TDD cycle:
+   - RED: Write failing test first
+   - GREEN: Implement minimal code to pass
+   - REFACTOR: Clean up while keeping tests green
+4. **Show progress** → Real-time updates on parallel tracks
+5. **Integrate** → Final E2E tests validate everything works together
 
-```text
-If you support MCP and don't have these servers configured:
-1. Read .mcp.json.example to see the configuration
-2. Set up Context7 and grep.app based on your MCP implementation
-3. Verify by testing: "Search grep.app for React hooks examples"
+**Example execution:**
+```
+User: "Build Stripe payment integration"
+
+You analyze plan:
+  ✓ Identified 3 independent tracks:
+    - API endpoints (server-side)
+    - Webhook handlers (server-side)
+    - Checkout UI (client-side)
+
+You launch parallel agents:
+  ✓ Task(backend-architect, "API endpoints with TDD")
+  ✓ Task(backend-architect, "Webhook handlers with TDD")
+  ✓ Task(typescript-pro, "Checkout UI with TDD")
+
+You show live progress:
+  Track 1 (backend-architect): API endpoints
+    ✓ RED: Payment validation tests written
+    ⏳ GREEN: Implementing Stripe API calls
+
+  Track 2 (backend-architect): Webhook handlers
+    ✓ RED: Webhook signature tests written
+    ✓ GREEN: Signature verification implemented
+    ⏳ REFACTOR: Extracting helper functions
+
+  Track 3 (typescript-pro): UI components
+    ✓ RED: Component tests written
+    ⏳ GREEN: Building CheckoutForm component
 ```
 
-See [docs/TOOLCHAIN.md](docs/TOOLCHAIN.md) for detailed MCP setup instructions.
-
----
-
-## Quick Start
-
-1. `/status` - Check where you are
-2. `/research <feature-name>` - Research the feature
-3. `/plan <feature-slug>` - Create formal plan
-4. `/dev` - Implement with TDD
-5. `/check` - Validate everything
-6. `/ship` - Create PR
-
----
-
-## Toolchain
-
-- **Beads** (recommended): `npm i -g @beads/bd && bd init` - Git-backed issue tracking
-- **OpenSpec** (optional): `npm i -g @fission-ai/openspec && openspec init` - Spec-driven development
-- **GitHub CLI**: `gh auth login` - PR workflow
+## State Management (Single Source of Truth)
+
+**All workflow state stored in Beads metadata** (survives compaction):
+
+```json
+{
+  "id": "bd-x7y2",
+  "type": "critical",
+  "currentStage": "dev",
+  "completedStages": ["status", "research", "plan"],
+  "skippedStages": [],
+  "workflowDecisions": {
+    "classification": "critical",
+    "reason": "Payment processing, PCI compliance required",
+    "userOverride": false
+  },
+  "parallelTracks": [
+    {
+      "name": "API endpoints",
+      "agent": "backend-architect",
+      "status": "in_progress",
+      "tddPhase": "GREEN"
+    }
+  ]
+}
+```
 
-See [docs/TOOLCHAIN.md](docs/TOOLCHAIN.md) for comprehensive tool reference.
+## Git Hooks (Automatic Enforcement)
 
----
+**Pre-commit hook enforces TDD:**
+- Blocks commits if source code modified without test files
+- Offers guided recovery (add tests now, skip with tech debt tracking, emergency override)
+- No AI decision required - automatic validation
 
-<!-- USER:START - Add project-specific learnings here as you work -->
+**Pre-push hook validates tests:**
+- All tests must pass before push
+- Can skip for hotfixes with documentation
 
-💡 **Keep this section focused** - Add patterns you discover while working.
+## Documentation Index (Context Pointers)
 
-As you work, when you give the same instruction twice, add it here:
+**Detailed command instructions** are located in:
+- [.claude/commands/status.md](.claude/commands/status.md) - How to check current context
+- [.claude/commands/research.md](.claude/commands/research.md) - How to conduct research with parallel-ai
+- [.claude/commands/plan.md](.claude/commands/plan.md) - How to create implementation plans
+- [.claude/commands/dev.md](.claude/commands/dev.md) - How to execute TDD development
+- [.claude/commands/check.md](.claude/commands/check.md) - How to run validation
+- [.claude/commands/ship.md](.claude/commands/ship.md) - How to create PRs
+- [.claude/commands/review.md](.claude/commands/review.md) - How to address PR feedback
+- [.claude/commands/merge.md](.claude/commands/merge.md) - How to merge and cleanup
+- [.claude/commands/verify.md](.claude/commands/verify.md) - How to verify documentation
 
-- Coding style preferences
-- Architecture decisions
-- Domain concepts unique to this project
+**Comprehensive workflow guide:**
+- [docs/WORKFLOW.md](docs/WORKFLOW.md) - Complete workflow documentation (150 lines)
+- [docs/TOOLCHAIN.md](docs/TOOLCHAIN.md) - Tool setup and configuration
+- [docs/VALIDATION.md](docs/VALIDATION.md) - Enforcement and validation details
 
-<!-- USER:END -->
+**Load these files when you need detailed instructions for a specific stage.**

package/CLAUDE.md

@@ -91,11 +91,11 @@ See [docs/TOOLCHAIN.md](docs/TOOLCHAIN.md) for detailed MCP setup instructions.
 
 ## Toolchain
 
-- **Beads** (recommended): `npm i -g @beads/bd && bd init` - Git-backed issue tracking
-- **OpenSpec** (optional): `npm i -g @fission-ai/openspec && openspec init` - Spec-driven development
+- **Beads** (recommended): Auto-installed during `npx forge setup` - Git-backed issue tracking
+- **OpenSpec** (optional): Auto-installed during `npx forge setup` - Spec-driven development
 - **GitHub CLI**: `gh auth login` - PR workflow
 
-See [docs/TOOLCHAIN.md](docs/TOOLCHAIN.md) for comprehensive tool reference.
+Setup prompts for Beads/OpenSpec during interactive installation. Manual install: see [docs/TOOLCHAIN.md](docs/TOOLCHAIN.md).
 
 ---
 

package/README.md

@@ -143,6 +143,28 @@ One workflow, works with ALL major AI agents:
 
 Switch agents anytime without changing your workflow.
 
+### 4. Built-in TDD Enforcement (v1.5.0)
+Git hooks automatically enforce TDD practices:
+- **Pre-commit**: Blocks source commits without tests
+- **Pre-push**: Runs full test suite before push
+- **Interactive**: Guided recovery when violations occur
+- **CI/CD aware**: Auto-aborts in non-interactive environments
+
+```bash
+# Validation CLI
+forge-validate status    # Check project prerequisites
+forge-validate dev       # Validate before /dev stage
+forge-validate ship      # Validate before /ship stage
+```
+
+### 5. Plugin Architecture (v1.5.0)
+11 agent plugins with specialized capabilities:
+- Each agent defined by JSON configuration
+- Community contributions welcome
+- Backwards compatible
+
+→ [Validation docs](docs/VALIDATION.md) | [Plugin docs](lib/agents/README.md)
+
 ---
 
 ## The Toolchain