forge-workflow 0.0.1

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

@@ -0,0 +1,240 @@
+#!/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__\//,
+    /^scripts\//, // build/utility scripts (benchmarks, CI tools)
+    /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}`,
+    // Mirror source directory structure (lib/commands/foo.js → test/commands/foo.test.js)
+    sourceFile.replace(/^(lib|src)\//, 'test/').replace(ext, `.test${ext}`),
+    sourceFile.replace(/^(lib|src)\//, 'test/').replace(ext, `.spec${ext}`),
+    sourceFile.replace(/^(lib|src)\//, 'tests/').replace(ext, `.test${ext}`),
+    sourceFile.replace(/^(lib|src)\//, 'tests/').replace(ext, `.spec${ext}`),
+    // bin/ directory (bin/forge-cmd.js → test/cli/forge-cmd.test.js)
+    sourceFile.replace(/^bin\//, 'test/cli/').replace(ext, `.test${ext}`),
+    sourceFile.replace(/^bin\//, 'test/cli/').replace(ext, `.spec${ext}`),
+    sourceFile.replace(/^bin\//, 'test/bin/').replace(ext, `.test${ext}`),
+    sourceFile.replace(/^bin\//, 'test/bin/').replace(ext, `.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/.mcp.json.example

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@2"]
+    },
+    "grep-app": {
+      "command": "npx",
+      "args": ["-y", "@ai-tools-all/grep_app_mcp@1"]
+    }
+  }
+}

package/AGENTS.md

@@ -0,0 +1,169 @@
+# Project Workflow Instructions
+
+## 7-Stage TDD-First Workflow
+
+This project enforces a **strict TDD-first development workflow** with 7 stages:
+
+| Stage | Command     | Purpose                                                   | Required For |
+|-------|-------------|-----------------------------------------------------------|--------------|
+| 1     | `/plan`     | Design intent → research → branch + worktree + task list | Critical, Standard, Refactor |
+| 2     | `/dev`      | Subagent-driven TDD per task (spec + quality review)     | All types    |
+| 3     | `/validate`    | Validate + 4-phase debug mode on failure                    | All types    |
+| 4     | `/ship`     | Create PR with documentation                             | All types    |
+| 5     | `/review`   | Address ALL PR feedback                                  | Critical, Standard |
+| 6     | `/premerge` | Complete docs on feature branch, hand off PR             | All types    |
+| 7     | `/verify`   | Post-merge health check (CI, deployments)                | All types    |
+
+**Utility**: `/status` — Context check before starting work (not a numbered stage)
+
+## Automatic Change Classification
+
+When the user requests work, **you MUST automatically classify** the change type:
+
+### Critical (Full 7-stage workflow)
+**Triggers:** Security, authentication, payments, breaking changes, new architecture, data migrations
+**Example:** "Add OAuth login", "Migrate database schema", "Implement payment gateway"
+**Workflow:** plan → dev → validate → ship → review → premerge → verify
+
+### Standard (6-stage workflow)
+**Triggers:** Normal features, enhancements, new components
+**Example:** "Add user profile page", "Create notification system"
+**Workflow:** plan → dev → validate → ship → review → premerge
+
+### Simple (3-stage workflow, skip plan)
+**Triggers:** Bug fixes, UI tweaks, small changes, minor refactors
+**Example:** "Fix button color", "Update validation message", "Adjust padding"
+**Workflow:** dev → validate → ship
+
+### Hotfix (Emergency 3-stage workflow)
+**Triggers:** Production emergencies, critical bugs affecting users
+**Example:** "Production payment processing down", "Security vulnerability fix"
+**Workflow:** dev → validate → ship (immediate merge allowed)
+
+### Docs (Documentation-only workflow)
+**Triggers:** Documentation updates, README changes, comment improvements
+**Example:** "Update README", "Add API documentation"
+**Workflow:** verify → ship
+
+### 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 → validate → ship → premerge
+
+## Enforcement Philosophy
+
+**Conversational, not blocking** - Offer solutions when prerequisites are missing:
+
+❌ **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-deep-research (~5 min)
+   2. Use your research if you have it
+   3. Skip (not recommended for security features)
+
+   What would you prefer?"
+
+**Create accountability for skips:**
+
+"Skipping tests creates technical debt. I'll:
+ ✓ Allow this commit
+ ✓ Create follow-up Beads issue for tests
+ ✓ Document in commit message as [tech-debt]
+
+ Proceed?"
+
+## TDD Development (Stage 2: /dev)
+
+**Subagent-driven per-task implementation loop:**
+
+1. **Read task list** → Pre-made task list from `/plan` Phase 3 at `docs/plans/YYYY-MM-DD-<slug>-tasks.md`
+2. **Dispatch implementer subagent per task** → Fresh context, complete task text, relevant design doc sections
+3. **TDD inside implementer** → RED-GREEN-REFACTOR enforced by HARD-GATE:
+   - RED: Write failing test first (must run test and show failing output)
+   - GREEN: Implement minimal code to pass (must show passing output)
+   - REFACTOR: Clean up while keeping tests green
+4. **Spec compliance review** → Spec reviewer checks every task before quality review
+5. **Code quality review** → Quality reviewer checks after spec compliance ✅
+6. **Decision gate** → 7-dimension impact scoring when spec gap found; score routes to PROCEED/SPEC-REVIEWER/BLOCKED
+
+**Example execution:**
+```
+/dev starts:
+  ✓ Read task list: docs/plans/2026-02-26-stripe-billing-tasks.md (8 tasks)
+  ✓ Created decisions log: docs/plans/2026-02-26-stripe-billing-decisions.md
+
+Task 1: Types and interfaces
+  ✓ Implementer: test written → failing → implementation → passing → committed
+  ✓ Spec review: ✅
+  ✓ Quality review: ✅
+  Decision gates: 0
+
+Task 2: Validation logic
+  ✓ Implementer: test written → failing → implementation → passing
+  ⚠️  Decision gate fired (score: 2/14 — PROCEED)
+     Gap: Error message format not specified in design doc
+     Choice: Use { code, message } object (conservative, documented)
+  ✓ Spec review: ✅
+  ✓ Quality review: ✅
+```
+
+## State Management (Single Source of Truth)
+
+**All workflow state stored in Beads metadata** (survives compaction):
+
+```json
+{
+  "id": "bd-x7y2",
+  "type": "critical",
+  "currentStage": "dev",
+  "completedStages": ["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"
+    }
+  ]
+}
+```
+
+## 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
+
+**Pre-push hook validates tests:**
+- All tests must pass before push
+- Can skip for hotfixes with documentation
+
+## Documentation Index (Context Pointers)
+
+**Detailed command instructions** are located in:
+- [.claude/commands/status.md](.claude/commands/status.md) - How to check current context (utility)
+- [.claude/commands/plan.md](.claude/commands/plan.md) - How to plan features (3 phases: design intent + research + branch/worktree/tasks)
+- [.claude/commands/dev.md](.claude/commands/dev.md) - How to implement with subagent-driven TDD and decision gate
+- [.claude/commands/validate.md](.claude/commands/validate.md) - How to run validation (with HARD-GATE exit)
+- [.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 (with HARD-GATE exit)
+- [.claude/commands/premerge.md](.claude/commands/premerge.md) - How to complete docs and hand off PR for merge
+- [.claude/commands/verify.md](.claude/commands/verify.md) - How to verify post-merge health
+
+**Planning documents** (created by `/plan`, consumed by `/dev`):
+- `docs/plans/YYYY-MM-DD-<slug>-design.md` - Design intent + technical research
+- `docs/plans/YYYY-MM-DD-<slug>-tasks.md` - Task list with TDD steps
+- `docs/plans/YYYY-MM-DD-<slug>-decisions.md` - Decisions log from /dev
+
+**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
+
+**Load these files when you need detailed instructions for a specific stage.**

package/CLAUDE.md

@@ -0,0 +1,99 @@
+# Project Instructions
+
+This is a [describe what this project does in one sentence].
+
+**Package manager**: Bun (preferred for performance)
+
+**Build commands**:
+
+```bash
+bun install      # Install dependencies
+bun run dev      # Start development
+bun run build    # Production build
+bun test         # Run tests
+```
+
+---
+
+## Workflow
+
+> **IMPORTANT**: Read [AGENTS.md](AGENTS.md) using the Read tool at the start of every session to load the complete Forge 7-stage workflow, change classification, and detailed stage instructions. AGENTS.md is the single source of truth for the workflow.
+
+---
+
+## MCP Servers (Enhanced Capabilities)
+
+This project uses MCP (Model Context Protocol) servers for enhanced capabilities. If your AI agent supports MCP, set up these servers:
+
+**Available MCP servers:**
+
+- **Context7**: Up-to-date library documentation and API reference
+- **grep.app**: Search 1M+ GitHub repos for real-world code examples
+
+**Setup for your agent:**
+
+See [.mcp.json.example](.mcp.json.example) for configuration. Setup varies by agent:
+
+- **Claude Code**: Copy `.mcp.json.example` to `.mcp.json` in project root
+- **Cline**: Add MCP servers in VSCode settings (Extensions > Cline > MCP Servers)
+- **Cursor**: Check Cursor Settings > MCP for setup
+- **Your agent**: If MCP-capable, configure using the example file
+
+See [docs/TOOLCHAIN.md](docs/TOOLCHAIN.md) for detailed MCP setup instructions.
+
+---
+
+## Toolchain
+
+- **Beads** (recommended): Auto-installed during `bunx forge setup` - Git-backed issue tracking
+- **GitHub CLI**: `gh auth login` - PR workflow
+
+Setup prompts for Beads during interactive installation. Manual install: see [docs/TOOLCHAIN.md](docs/TOOLCHAIN.md).
+
+---
+
+## Git Workflow
+
+This project uses the **Professional Git Workflow** with Lefthook for automated quality gates:
+
+**Pre-commit hooks** (automatic):
+- TDD enforcement: Source files must have corresponding tests
+- Interactive prompts: Option to unstage, continue, or abort
+
+**Pre-push hooks** (automatic):
+- Branch protection: Blocks direct push to main/master
+- ESLint check: Blocks on errors and warnings (strict mode, `--max-warnings 0`)
+- Test suite: All tests must pass
+
+**Pull Request workflow**:
+- PR template auto-fills with standardized format
+- Self-review checklist catches 80% of bugs before review
+- Beads integration: Reference issues with `Closes beads-xxx`
+- **All review comments must be resolved** before merge
+- Squash-only merging: Clean, linear git history
+
+**Emergency bypass**:
+```bash
+LEFTHOOK=0 git push              # Skip all pre-push hooks
+git commit --no-verify           # Skip pre-commit hooks
+```
+
+**⚠️ Only use bypasses for emergencies.** Document reason in PR description.
+
+See [.github/pull_request_template.md](.github/pull_request_template.md) for PR guidelines.
+
+---
+
+<!-- USER:START - Add project-specific learnings here as you work -->
+
+💡 **Keep this section focused** - Add patterns you discover while working.
+
+As you work, when you give the same instruction twice, add it here:
+
+- **Scope discipline**: Do ONLY what was explicitly asked. Answer a question → stop. Check something → stop. Never auto-continue to next steps or pending work unless told to.
+- **Stage names**: The validation stage is `/validate` (not `/check`) — renamed in PR #50.
+- **Unused params**: Prefix with `_` (e.g., `_searchTerm`) — ESLint `no-unused-vars` enforced with `--max-warnings 0`.
+- **Pre-push test env**: `test-env/` fixture tests can fail during actual `git push` due to git mid-push state; `LEFTHOOK=0 git push` is the bypass when manual `bun test` confirms 0 fail.
+- **Command sync**: After editing `.claude/commands/*.md`, run `node scripts/sync-commands.js` to update all 7 agent directories. Use `--check` in CI to detect drift. Use `--dry-run` to preview.
+
+<!-- USER:END -->

package/LICENSE

@@ -0,0 +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.