forge-workflow 1.3.0 → 1.3.1

package/.claude/settings.local.json

@@ -15,7 +15,10 @@
       "Bash(\"C:\\\\Program Files\\\\nodejs\\\\npm.cmd\" pkg fix)",
       "WebFetch(domain:www.aihero.dev)",
       "Bash(\"C:\\\\Program Files\\\\nodejs\\\\npm.cmd\" version minor --no-git-tag-version)",
-      "WebFetch(domain:ohmyopencode.com)"
+      "WebFetch(domain:ohmyopencode.com)",
+      "WebFetch(domain:grep.app)",
+      "Bash(test:*)",
+      "Bash(\"C:\\\\Program Files\\\\nodejs\\\\npm.cmd\" publish)"
     ]
   }
 }

package/.mcp.json.example

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

package/AGENTS.md

@@ -1,10 +1,11 @@
-# AGENTS.md
+# Project Instructions
 
 This is a [describe what this project does in one sentence].
 
 **Package manager**: npm (or specify: pnpm/yarn/bun)
 
 **Build commands**:
+
 ```bash
 npm install      # Install dependencies
 npm run dev      # Start development
@@ -12,23 +13,100 @@ npm run build    # Production build
 npm test         # Run tests
 ```
 
-**Workflow**: See [`docs/WORKFLOW.md`](docs/WORKFLOW.md) for the 9-stage TDD workflow.
+---
+
+## Forge Workflow
+
+This project uses the **Forge 9-stage TDD workflow**:
+
+| 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             |
+
+**Flow**: `/status` → `/research` → `/plan` → `/dev` → `/check` → `/ship` → `/review` → `/merge` → `/verify`
+
+See [docs/WORKFLOW.md](docs/WORKFLOW.md) for complete workflow guide.
+
+---
+
+## Core Principles
+
+- **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
+
+---
+
+## 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)
+- **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
+
+**Agent instructions:**
+
+```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"
+```
+
+See [docs/TOOLCHAIN.md](docs/TOOLCHAIN.md) for detailed MCP setup instructions.
+
+---
+
+## Quick Start
 
-**Project-specific conventions**: Add them below as you discover patterns.
+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
 
 ---
 
-<!-- USER:START - Add learnings here as you work -->
+## Toolchain
 
-💡 **Keep this section minimal** - Instruction budget is ~150-200 instructions max.
+- **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
+
+See [docs/TOOLCHAIN.md](docs/TOOLCHAIN.md) for comprehensive tool reference.
+
+---
+
+<!-- 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:
+
 - Coding style preferences
 - Architecture decisions
 - Domain concepts unique to this project
 
 <!-- USER:END -->
-
----
-
-See [`docs/TOOLCHAIN.md`](docs/TOOLCHAIN.md) for comprehensive tool reference.

package/CLAUDE.md

@@ -0,0 +1,108 @@
+# Claude Code - Project Instructions
+
+This is a [describe what this project does in one sentence].
+
+**Package manager**: npm (or specify: pnpm/yarn/bun)
+
+**Build commands**:
+
+```bash
+npm install      # Install dependencies
+npm run dev      # Start development
+npm run build    # Production build
+npm test         # Run tests
+```
+
+---
+
+## Forge Workflow
+
+This project uses the **Forge 9-stage TDD workflow**:
+
+| 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             |
+
+**Flow**: `/status` → `/research` → `/plan` → `/dev` → `/check` → `/ship` → `/review` → `/merge` → `/verify`
+
+See [docs/WORKFLOW.md](docs/WORKFLOW.md) for complete workflow guide.
+
+---
+
+## Core Principles
+
+- **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
+
+---
+
+## MCP Servers
+
+This project uses MCP servers for enhanced capabilities. Copy [.mcp.json.example](.mcp.json.example) to `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"]
+    },
+    "grep-app": {
+      "command": "npx",
+      "args": ["-y", "@ai-tools-all/grep_app_mcp"]
+    }
+  }
+}
+```
+
+**Available MCP servers**:
+
+- **Context7**: Up-to-date library documentation and API reference
+- **grep.app**: Search 1M+ GitHub repos for real-world code examples
+
+See [docs/TOOLCHAIN.md](docs/TOOLCHAIN.md) for complete 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
+
+See [docs/TOOLCHAIN.md](docs/TOOLCHAIN.md) for comprehensive tool reference.
+
+---
+
+<!-- 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:
+
+- Coding style preferences
+- Architecture decisions
+- Domain concepts unique to this project
+
+<!-- USER:END -->

package/bin/forge.js

@@ -659,12 +659,34 @@ function detectProjectStatus() {
   const status = {
     type: 'fresh', // 'fresh', 'upgrade', or 'partial'
     hasAgentsMd: fs.existsSync(path.join(projectRoot, 'AGENTS.md')),
+    hasClaudeMd: fs.existsSync(path.join(projectRoot, 'CLAUDE.md')),
     hasClaudeCommands: fs.existsSync(path.join(projectRoot, '.claude/commands')),
     hasEnvLocal: fs.existsSync(path.join(projectRoot, '.env.local')),
     hasDocsWorkflow: fs.existsSync(path.join(projectRoot, 'docs/WORKFLOW.md')),
-    existingEnvVars: {}
+    existingEnvVars: {},
+    agentsMdSize: 0,
+    claudeMdSize: 0,
+    agentsMdLines: 0,
+    claudeMdLines: 0
   };
 
+  // Get file sizes and line counts for context warnings
+  if (status.hasAgentsMd) {
+    const agentsPath = path.join(projectRoot, 'AGENTS.md');
+    const stats = fs.statSync(agentsPath);
+    const content = fs.readFileSync(agentsPath, 'utf8');
+    status.agentsMdSize = stats.size;
+    status.agentsMdLines = content.split('\n').length;
+  }
+
+  if (status.hasClaudeMd) {
+    const claudePath = path.join(projectRoot, 'CLAUDE.md');
+    const stats = fs.statSync(claudePath);
+    const content = fs.readFileSync(claudePath, 'utf8');
+    status.claudeMdSize = stats.size;
+    status.claudeMdLines = content.split('\n').length;
+  }
+
   // Determine installation type
   if (status.hasAgentsMd && status.hasClaudeCommands && status.hasDocsWorkflow) {
     status.type = 'upgrade'; // Full forge installation exists
@@ -681,6 +703,164 @@ function detectProjectStatus() {
   return status;
 }
 
+// Smart file selection with context warnings
+async function handleInstructionFiles(rl, question, selectedAgents, projectStatus) {
+  const hasClaude = selectedAgents.some(a => a.key === 'claude');
+  const hasOtherAgents = selectedAgents.some(a => a.key !== 'claude');
+
+  // Calculate estimated tokens (rough: ~4 chars per token)
+  const estimateTokens = (bytes) => Math.ceil(bytes / 4);
+
+  const result = {
+    createAgentsMd: false,
+    createClaudeMd: false,
+    skipAgentsMd: false,
+    skipClaudeMd: false
+  };
+
+  // Scenario 1: Both files exist (potential context bloat)
+  if (projectStatus.hasAgentsMd && projectStatus.hasClaudeMd) {
+    const totalLines = projectStatus.agentsMdLines + projectStatus.claudeMdLines;
+    const totalTokens = estimateTokens(projectStatus.agentsMdSize + projectStatus.claudeMdSize);
+
+    console.log('');
+    console.log('⚠️  WARNING: Multiple Instruction Files Detected');
+    console.log('='.repeat(60));
+    console.log(`  AGENTS.md:  ${projectStatus.agentsMdLines} lines (~${estimateTokens(projectStatus.agentsMdSize)} tokens)`);
+    console.log(`  CLAUDE.md:  ${projectStatus.claudeMdLines} lines (~${estimateTokens(projectStatus.claudeMdSize)} tokens)`);
+    console.log(`  Total:      ${totalLines} lines (~${totalTokens} tokens)`);
+    console.log('');
+    console.log('  ⚠️  Claude Code reads BOTH files on every request');
+    console.log('  ⚠️  This increases context usage and costs');
+    console.log('');
+    console.log('  Options:');
+    console.log('  1) Keep CLAUDE.md only (recommended for Claude Code only)');
+    console.log('  2) Keep AGENTS.md only (recommended for multi-agent users)');
+    console.log('  3) Keep both (higher context usage)');
+    console.log('');
+
+    while (true) {
+      const choice = await question('Your choice (1/2/3) [2]: ');
+      const normalized = choice.trim() || '2';
+
+      if (normalized === '1') {
+        result.skipAgentsMd = true;
+        result.createClaudeMd = false; // Keep existing
+        console.log('  ✓ Will keep CLAUDE.md, remove AGENTS.md');
+        break;
+      } else if (normalized === '2') {
+        result.skipClaudeMd = true;
+        result.createAgentsMd = false; // Keep existing
+        console.log('  ✓ Will keep AGENTS.md, remove CLAUDE.md');
+        break;
+      } else if (normalized === '3') {
+        result.createAgentsMd = false; // Keep existing
+        result.createClaudeMd = false; // Keep existing
+        console.log('  ✓ Will keep both files (context: ~' + totalTokens + ' tokens)');
+        break;
+      } else {
+        console.log('  Please enter 1, 2, or 3');
+      }
+    }
+
+    return result;
+  }
+
+  // Scenario 2: Only CLAUDE.md exists
+  if (projectStatus.hasClaudeMd && !projectStatus.hasAgentsMd) {
+    if (hasOtherAgents) {
+      console.log('');
+      console.log('📋 Found existing CLAUDE.md (' + projectStatus.claudeMdLines + ' lines)');
+      console.log('   You selected multiple agents. Recommendation:');
+      console.log('   → Migrate to AGENTS.md (works with all agents)');
+      console.log('');
+
+      const migrate = await askYesNo(question, 'Migrate CLAUDE.md to AGENTS.md?', false);
+      if (migrate) {
+        result.createAgentsMd = true;
+        result.skipClaudeMd = true;
+        console.log('  ✓ Will migrate content to AGENTS.md');
+      } else {
+        result.createAgentsMd = true;
+        result.createClaudeMd = false; // Keep existing
+        console.log('  ✓ Will keep CLAUDE.md and create AGENTS.md');
+      }
+    } else {
+      // Claude Code only - keep CLAUDE.md
+      result.createClaudeMd = false; // Keep existing
+      console.log('  ✓ Keeping existing CLAUDE.md');
+    }
+
+    return result;
+  }
+
+  // Scenario 3: Only AGENTS.md exists
+  if (projectStatus.hasAgentsMd && !projectStatus.hasClaudeMd) {
+    if (hasClaude && !hasOtherAgents) {
+      console.log('');
+      console.log('📋 Found existing AGENTS.md (' + projectStatus.agentsMdLines + ' lines)');
+      console.log('   You selected Claude Code only. Options:');
+      console.log('   1) Keep AGENTS.md (works fine)');
+      console.log('   2) Rename to CLAUDE.md (Claude-specific naming)');
+      console.log('');
+
+      const rename = await askYesNo(question, 'Rename to CLAUDE.md?', true);
+      if (rename) {
+        result.createClaudeMd = true;
+        result.skipAgentsMd = true;
+        console.log('  ✓ Will rename to CLAUDE.md');
+      } else {
+        result.createAgentsMd = false; // Keep existing
+        console.log('  ✓ Keeping AGENTS.md');
+      }
+    } else {
+      // Multi-agent or other agents - keep AGENTS.md
+      result.createAgentsMd = false; // Keep existing
+      console.log('  ✓ Keeping existing AGENTS.md');
+    }
+
+    return result;
+  }
+
+  // Scenario 4: Neither file exists (fresh install)
+  if (hasClaude && !hasOtherAgents) {
+    // Claude Code only → create CLAUDE.md
+    result.createClaudeMd = true;
+    console.log('  ✓ Will create CLAUDE.md (Claude Code specific)');
+  } else if (!hasClaude && hasOtherAgents) {
+    // Other agents only → create AGENTS.md
+    result.createAgentsMd = true;
+    console.log('  ✓ Will create AGENTS.md (universal)');
+  } else {
+    // Multiple agents including Claude → create AGENTS.md + reference CLAUDE.md
+    result.createAgentsMd = true;
+    result.createClaudeMd = true; // Will be minimal reference
+    console.log('  ✓ Will create AGENTS.md (main) + CLAUDE.md (reference)');
+  }
+
+  return result;
+}
+
+// Create minimal CLAUDE.md that references AGENTS.md
+function createClaudeReference(destPath) {
+  const content = `# Claude Code Instructions
+
+See [AGENTS.md](AGENTS.md) for all project instructions.
+
+This file exists to avoid Claude Code reading both CLAUDE.md and AGENTS.md (which doubles context usage). Keep project-level instructions in AGENTS.md.
+
+---
+
+<!-- Add Claude Code-specific instructions below (if needed) -->
+<!-- Examples: MCP server setup, custom commands, Claude-only workflows -->
+
+💡 **Keep this minimal** - Main instructions are in AGENTS.md
+`;
+
+  fs.writeFileSync(destPath, content, 'utf8');
+  return true;
+}
+
 // Configure external services interactively
 async function configureExternalServices(rl, question, selectedAgents = [], projectStatus = null) {
   console.log('');

package/docs/TOOLCHAIN.md

@@ -393,9 +393,10 @@ The system SHALL support optional 2FA
 
 Context7 provides current documentation that may be more recent than the AI's training data.
 
-**Installation (Claude Code)**:
+**Installation**:
+
+**Claude Code**: Add to `.mcp.json` in your project root:
 
-Add to `.mcp.json` in your project root:
 
 ```json
 {
@@ -420,6 +421,28 @@ Add to `.mcp.json` in your project root:
 }
 ```
 
+**Cline (VSCode)**:
+1. Open VSCode Settings
+2. Search for "Cline MCP"
+3. Add Context7 server configuration
+
+**Continue**: Add to `.continue/config.json`:
+
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"]
+    }
+  }
+}
+```
+
+**Cursor**: Check Cursor Settings → MCP Servers for configuration options
+
+**Other agents**: If your agent supports MCP, configure using the JSON format above
+
 **Usage**:
 ```
 # The AI will automatically use Context7 when you ask about libraries
@@ -434,6 +457,72 @@ Add to `.mcp.json` in your project root:
 - To verify API signatures and patterns
 - For current best practices
 
+### grep.app - Code Search
+
+**Package**: `@ai-tools-all/grep_app_mcp` (recommended) or `@galprz/grep-mcp`
+**Website**: [grep.app](https://grep.app)
+**Purpose**: Search across 1M+ public GitHub repositories for real-world code examples
+**Used in**: `/research` stage, finding implementation patterns
+
+grep.app provides code search across public GitHub repositories to find real-world examples and patterns.
+
+**Installation (Claude Code)**:
+
+Add to `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"]
+    },
+    "grep-app": {
+      "command": "npx",
+      "args": ["-y", "@ai-tools-all/grep_app_mcp"]
+    }
+  }
+}
+```
+
+**Or with bunx**:
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "bunx",
+      "args": ["--bun", "@upstash/context7-mcp@latest"]
+    },
+    "grep-app": {
+      "command": "bunx",
+      "args": ["--bun", "@ai-tools-all/grep_app_mcp"]
+    }
+  }
+}
+```
+
+**Usage**:
+```
+# The AI will use grep.app when you need real-world examples
+"Find examples of React useEffect cleanup patterns"
+"Show me how others implement JWT authentication in Express"
+"Search for rate limiting implementations in Node.js"
+```
+
+**When to use grep.app**:
+
+- Finding real-world implementation examples
+- Discovering coding patterns in production code
+- Validating implementation approaches
+- Learning from open source projects
+
+**Context7 vs grep.app**:
+
+| Tool           | Purpose                        | Use When                                  |
+|----------------|--------------------------------|-------------------------------------------|
+| **Context7**   | Official library documentation | You need API reference, official patterns |
+| **grep.app**   | Real code in the wild          | You want to see how others solve problems |
+
 ---
 
 ## External Services
@@ -658,7 +747,7 @@ gh issue create --title "..." --body "..."
 | Stage | Tools Used |
 |-------|------------|
 | `/status` | `bd ready`, `bd list`, `git status`, `openspec list` |
-| `/research` | Parallel AI, codebase exploration |
+| `/research` | Parallel AI, Context7, grep.app, codebase exploration |
 | `/plan` | `bd create`, `openspec` (if strategic), `git checkout -b` |
 | `/dev` | Tests, code, `bd update`, `/tasks save` |
 | `/check` | Type check, lint, tests, SonarCloud |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-workflow",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "9-stage TDD workflow for ALL AI coding agents (Claude, Cursor, Windsurf, Kilo, OpenCode, Copilot, Cline, Roo, Aider, Continue, Antigravity)",
   "bin": {
     "forge": "bin/forge.js"
@@ -44,6 +44,8 @@
     ".claude/",
     "docs/",
     "install.sh",
-    "AGENTS.md"
+    "AGENTS.md",
+    "CLAUDE.md",
+    ".mcp.json.example"
   ]
 }