forge-workflow 1.2.0 → 1.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/.claude/settings.local.json +5 -1
  2. package/.mcp.json.example +12 -0
  3. package/AGENTS.md +73 -178
  4. package/CLAUDE.md +108 -0
  5. package/bin/forge.js +323 -26
  6. package/docs/TOOLCHAIN.md +92 -3
  7. package/package.json +4 -2
package/.claude/settings.local.json CHANGED
@@ -14,7 +14,11 @@
14
14
  "Bash(git push)",
15
15
  "Bash(\"C:\\\\Program Files\\\\nodejs\\\\npm.cmd\" pkg fix)",
16
16
  "WebFetch(domain:www.aihero.dev)",
17
- "Bash(\"C:\\\\Program Files\\\\nodejs\\\\npm.cmd\" version minor --no-git-tag-version)"
17
+ "Bash(\"C:\\\\Program Files\\\\nodejs\\\\npm.cmd\" version minor --no-git-tag-version)",
18
+ "WebFetch(domain:ohmyopencode.com)",
19
+ "WebFetch(domain:grep.app)",
20
+ "Bash(test:*)",
21
+ "Bash(\"C:\\\\Program Files\\\\nodejs\\\\npm.cmd\" publish)"
18
22
  ]
19
23
  }
20
24
  }
package/.mcp.json.example ADDED
@@ -0,0 +1,12 @@
1
+ {
2
+ "mcpServers": {
3
+ "context7": {
4
+ "command": "npx",
5
+ "args": ["-y", "@upstash/context7-mcp@latest"]
6
+ },
7
+ "grep-app": {
8
+ "command": "npx",
9
+ "args": ["-y", "@ai-tools-all/grep_app_mcp"]
10
+ }
11
+ }
12
+ }
package/AGENTS.md CHANGED
@@ -1,217 +1,112 @@
1
- # Forge - 9-Stage TDD Workflow
1
+ # Project Instructions
2
2
 
3
- A TDD-first workflow for AI coding agents. Ship features with confidence.
3
+ This is a [describe what this project does in one sentence].
4
4
 
5
- ## Commands (9 Stages)
5
+ **Package manager**: npm (or specify: pnpm/yarn/bun)
6
6
 
7
- | Stage | Command | Description |
8
- |-------|---------|-------------|
9
- | 1 | `/status` | Check current context, active work, recent completions |
10
- | 2 | `/research` | Deep research with web search, document to docs/research/ |
11
- | 3 | `/plan` | Create implementation plan, branch, OpenSpec if strategic |
12
- | 4 | `/dev` | TDD development (RED-GREEN-REFACTOR cycles) |
13
- | 5 | `/check` | Validation (type/lint/security/tests) |
14
- | 6 | `/ship` | Create PR with full documentation |
15
- | 7 | `/review` | Address ALL PR feedback |
16
- | 8 | `/merge` | Update docs, merge PR, cleanup |
17
- | 9 | `/verify` | Final documentation verification |
7
+ **Build commands**:
18
8
 
19
- ## Workflow Flow
20
-
21
- ```
22
- /status → /research → /plan → /dev → /check → /ship → /review → /merge → /verify
23
- ```
24
-
25
- ## Core Principles
26
-
27
- - **TDD-First**: Write tests BEFORE implementation (RED-GREEN-REFACTOR)
28
- - **Research-First**: Understand before building, document decisions
29
- - **Security Built-In**: OWASP Top 10 analysis for every feature
30
- - **Documentation Progressive**: Update at each stage, verify at end
31
-
32
- ## Prerequisites
33
-
34
- - Git, GitHub CLI (`gh`)
35
- - Beads (recommended): `npm i -g @beads/bd && bd init`
36
- - OpenSpec (optional): `npm i -g @fission-ai/openspec && openspec init`
37
-
38
- ## Toolchain Quick Reference
39
-
40
- ### Beads (Issue Tracking)
41
- ```bash
42
- bd ready # Find unblocked work (start here!)
43
- bd create "Title" -p 2 # Create issue with priority
44
- bd update <id> --status in_progress
45
- bd comments <id> "note" # Add comment
46
- bd close <id> # Complete
47
- bd sync # Git sync (always at session end!)
48
- ```
49
-
50
- ### OpenSpec (Specs - AI Commands)
51
9
  ```bash
52
- /opsx:new # Start change
53
- /opsx:ff # Generate all planning docs
54
- /opsx:apply # Implement tasks
55
- /opsx:verify # Validate
56
- /opsx:archive # Complete
10
+ npm install # Install dependencies
11
+ npm run dev # Start development
12
+ npm run build # Production build
13
+ npm test # Run tests
57
14
  ```
58
15
 
59
- ### GitHub CLI
60
- ```bash
61
- gh pr create --title "..." --body "..."
62
- gh pr view <n>
63
- gh pr merge <n> --squash --delete-branch
64
- ```
16
+ ---
65
17
 
66
- ## Quick Start
18
+ ## Forge Workflow
67
19
 
68
- 1. `/status` - Check where you are
69
- 2. `/research <feature-name>` - Research the feature
70
- 3. `/plan <feature-slug>` - Create formal plan
71
- 4. `/dev` - Implement with TDD
72
- 5. `/check` - Validate everything
73
- 6. `/ship` - Create PR
20
+ This project uses the **Forge 9-stage TDD workflow**:
74
21
 
75
- ## Stage Details
22
+ | Stage | Command | Purpose |
23
+ |-------|-------------|----------------------------------------------|
24
+ | 1 | `/status` | Check current context, active work |
25
+ | 2 | `/research` | Research with web search, document findings |
26
+ | 3 | `/plan` | Create implementation plan, branch, OpenSpec |
27
+ | 4 | `/dev` | TDD development (RED-GREEN-REFACTOR) |
28
+ | 5 | `/check` | Validation (type/lint/security/tests) |
29
+ | 6 | `/ship` | Create PR with documentation |
30
+ | 7 | `/review` | Address ALL PR feedback |
31
+ | 8 | `/merge` | Update docs, merge PR, cleanup |
32
+ | 9 | `/verify` | Final documentation verification |
76
33
 
77
- ### 1. Status (`/status`)
34
+ **Flow**: `/status` → `/research` → `/plan` → `/dev` → `/check` → `/ship` → `/review` → `/merge` → `/verify`
78
35
 
79
- Check current context before starting work:
80
- - Active issues (via Beads if installed)
81
- - Recent completions
82
- - Current branch state
83
- - OpenSpec proposals in progress
36
+ See [docs/WORKFLOW.md](docs/WORKFLOW.md) for complete workflow guide.
84
37
 
85
- ### 2. Research (`/research <feature-name>`)
38
+ ---
86
39
 
87
- Research before building:
88
- - Web search for best practices
89
- - Security analysis (OWASP Top 10)
90
- - Existing patterns in codebase
91
- - Document to `docs/research/<feature>.md`
40
+ ## Core Principles
92
41
 
93
- ### 3. Plan (`/plan <feature-slug>`)
42
+ - **TDD-First**: Write tests BEFORE implementation (RED-GREEN-REFACTOR)
43
+ - **Research-First**: Understand before building, document decisions
44
+ - **Security Built-In**: OWASP Top 10 analysis for every feature
45
+ - **Documentation Progressive**: Update at each stage, verify at end
94
46
 
95
- Create implementation plan:
96
- - Create feature branch
97
- - Define scope and approach
98
- - Create tracking issue (Beads)
99
- - OpenSpec proposal if strategic
47
+ ---
100
48
 
101
- ### 4. Development (`/dev`)
49
+ ## MCP Servers (Enhanced Capabilities)
102
50
 
103
- TDD implementation:
104
- - RED: Write failing test
105
- - GREEN: Make it pass
106
- - REFACTOR: Clean up
107
- - Commit after each GREEN cycle
51
+ This project uses MCP (Model Context Protocol) servers for enhanced capabilities. If your AI agent supports MCP, set up these servers:
108
52
 
109
- ### 5. Check (`/check`)
53
+ **Available MCP servers:**
110
54
 
111
- Validate everything:
112
- - Type checking
113
- - Linting
114
- - Unit tests
115
- - Integration tests
116
- - Security scan
55
+ - **Context7**: Up-to-date library documentation and API reference
56
+ - **grep.app**: Search 1M+ GitHub repos for real-world code examples
117
57
 
118
- ### 6. Ship (`/ship`)
58
+ **Setup for your agent:**
119
59
 
120
- Create pull request:
121
- - Push branch
122
- - Create PR with documentation
123
- - Link to research doc
124
- - List test coverage
60
+ See [.mcp.json.example](.mcp.json.example) for configuration. Setup varies by agent:
125
61
 
126
- ### 7. Review (`/review`)
62
+ - **Claude Code**: Copy `.mcp.json.example` to `.mcp.json` in project root
63
+ - **Cline**: Add MCP servers in VSCode settings (Extensions > Cline > MCP Servers)
64
+ - **Continue**: Add to `.continue/config.json` under `mcpServers`
65
+ - **Cursor**: Check Cursor Settings > MCP for setup
66
+ - **Your agent**: If MCP-capable, configure using the example file
127
67
 
128
- Address ALL feedback:
129
- - GitHub Actions failures
130
- - Code review comments
131
- - Security scan issues
132
- - Automated tool feedback
68
+ **Agent instructions:**
133
69
 
134
- ### 8. Merge (`/merge`)
70
+ ```text
71
+ If you support MCP and don't have these servers configured:
72
+ 1. Read .mcp.json.example to see the configuration
73
+ 2. Set up Context7 and grep.app based on your MCP implementation
74
+ 3. Verify by testing: "Search grep.app for React hooks examples"
75
+ ```
135
76
 
136
- Complete the work:
137
- - Update documentation
138
- - Squash merge PR
139
- - Archive OpenSpec (if used)
140
- - Close tracking issues
77
+ See [docs/TOOLCHAIN.md](docs/TOOLCHAIN.md) for detailed MCP setup instructions.
141
78
 
142
- ### 9. Verify (`/verify`)
79
+ ---
143
80
 
144
- Final documentation check:
145
- - All docs updated
146
- - Cross-references valid
147
- - Examples work
148
- - README current
81
+ ## Quick Start
149
82
 
150
- ## Directory Structure
83
+ 1. `/status` - Check where you are
84
+ 2. `/research <feature-name>` - Research the feature
85
+ 3. `/plan <feature-slug>` - Create formal plan
86
+ 4. `/dev` - Implement with TDD
87
+ 5. `/check` - Validate everything
88
+ 6. `/ship` - Create PR
151
89
 
152
- ```
153
- your-project/
154
- ├── AGENTS.md # This file (universal)
155
- ├── CLAUDE.md # Claude Code
156
- ├── GEMINI.md # Google Antigravity
157
- ├── .cursorrules # Cursor
158
- ├── .windsurfrules # Windsurf
159
- ├── .clinerules # Cline/Roo Code
160
- ├── .github/
161
- │ └── copilot-instructions.md # GitHub Copilot
162
- │
163
- ├── .claude/commands/ # Claude Code commands
164
- ├── .agent/workflows/ # Antigravity workflows
165
- ├── .cursor/rules/ # Cursor rules
166
- ├── .windsurf/workflows/ # Windsurf workflows
167
- ├── .kilocode/workflows/ # Kilo Code workflows
168
- ├── .opencode/commands/ # OpenCode commands
169
- ├── .continue/prompts/ # Continue prompts
170
- ├── .roo/commands/ # Roo Code commands
171
- │
172
- └── docs/
173
- ├── planning/
174
- │ └── PROGRESS.md
175
- ├── research/
176
- │ └── TEMPLATE.md
177
- └── WORKFLOW.md
178
- ```
90
+ ---
179
91
 
180
- ## Skills (Universal SKILL.md Format)
92
+ ## Toolchain
181
93
 
182
- The `forge-workflow` skill is installed to all supporting agents:
183
- - `.claude/skills/forge-workflow/SKILL.md`
184
- - `.agent/skills/forge-workflow/SKILL.md` (Antigravity)
185
- - `.cursor/skills/forge-workflow/SKILL.md`
186
- - `.windsurf/skills/forge-workflow/SKILL.md`
187
- - `.kilocode/skills/forge-workflow/SKILL.md`
188
- - `.cline/skills/forge-workflow/SKILL.md`
189
- - `.continue/skills/forge-workflow/SKILL.md`
190
- - `.opencode/skills/forge-workflow/SKILL.md`
94
+ - **Beads** (recommended): `npm i -g @beads/bd && bd init` - Git-backed issue tracking
95
+ - **OpenSpec** (optional): `npm i -g @fission-ai/openspec && openspec init` - Spec-driven development
96
+ - **GitHub CLI**: `gh auth login` - PR workflow
191
97
 
192
- ## Supported Agents
98
+ See [docs/TOOLCHAIN.md](docs/TOOLCHAIN.md) for comprehensive tool reference.
193
99
 
194
- This workflow works with ALL major AI coding agents:
100
+ ---
195
101
 
196
- | Agent | Instructions | Commands | Skills |
197
- |-------|-------------|----------|--------|
198
- | Claude Code | CLAUDE.md | .claude/commands/ | .claude/skills/ |
199
- | Google Antigravity | GEMINI.md | .agent/workflows/ | .agent/skills/ |
200
- | Cursor | .cursorrules | .cursor/rules/ | .cursor/skills/ |
201
- | Windsurf | .windsurfrules | .windsurf/workflows/ | .windsurf/skills/ |
202
- | Kilo Code | AGENTS.md | .kilocode/workflows/ | .kilocode/skills/ |
203
- | OpenCode | AGENTS.md | .opencode/commands/ | .opencode/skills/ |
204
- | Cline | .clinerules | AGENTS.md | .cline/skills/ |
205
- | Roo Code | .clinerules | .roo/commands/ | - |
206
- | Continue | .continuerules | .continue/prompts/ | .continue/skills/ |
207
- | GitHub Copilot | .github/copilot-instructions.md | .github/prompts/ | - |
208
- | Aider | AGENTS.md (via config) | In-chat | - |
102
+ <!-- USER:START - Add project-specific learnings here as you work -->
209
103
 
210
- ## License
104
+ 💡 **Keep this section focused** - Add patterns you discover while working.
211
105
 
212
- MIT
106
+ As you work, when you give the same instruction twice, add it here:
213
107
 
214
- ---
108
+ - Coding style preferences
109
+ - Architecture decisions
110
+ - Domain concepts unique to this project
215
111
 
216
- See `docs/WORKFLOW.md` for the complete workflow guide.
217
- See `docs/TOOLCHAIN.md` for comprehensive tool reference.
112
+ <!-- USER:END -->
package/CLAUDE.md ADDED
@@ -0,0 +1,108 @@
1
+ # Claude Code - Project Instructions
2
+
3
+ This is a [describe what this project does in one sentence].
4
+
5
+ **Package manager**: npm (or specify: pnpm/yarn/bun)
6
+
7
+ **Build commands**:
8
+
9
+ ```bash
10
+ npm install # Install dependencies
11
+ npm run dev # Start development
12
+ npm run build # Production build
13
+ npm test # Run tests
14
+ ```
15
+
16
+ ---
17
+
18
+ ## Forge Workflow
19
+
20
+ This project uses the **Forge 9-stage TDD workflow**:
21
+
22
+ | Stage | Command | Purpose |
23
+ |-------|-------------|----------------------------------------------|
24
+ | 1 | `/status` | Check current context, active work |
25
+ | 2 | `/research` | Research with web search, document findings |
26
+ | 3 | `/plan` | Create implementation plan, branch, OpenSpec |
27
+ | 4 | `/dev` | TDD development (RED-GREEN-REFACTOR) |
28
+ | 5 | `/check` | Validation (type/lint/security/tests) |
29
+ | 6 | `/ship` | Create PR with documentation |
30
+ | 7 | `/review` | Address ALL PR feedback |
31
+ | 8 | `/merge` | Update docs, merge PR, cleanup |
32
+ | 9 | `/verify` | Final documentation verification |
33
+
34
+ **Flow**: `/status` → `/research` → `/plan` → `/dev` → `/check` → `/ship` → `/review` → `/merge` → `/verify`
35
+
36
+ See [docs/WORKFLOW.md](docs/WORKFLOW.md) for complete workflow guide.
37
+
38
+ ---
39
+
40
+ ## Core Principles
41
+
42
+ - **TDD-First**: Write tests BEFORE implementation (RED-GREEN-REFACTOR)
43
+ - **Research-First**: Understand before building, document decisions
44
+ - **Security Built-In**: OWASP Top 10 analysis for every feature
45
+ - **Documentation Progressive**: Update at each stage, verify at end
46
+
47
+ ---
48
+
49
+ ## MCP Servers
50
+
51
+ This project uses MCP servers for enhanced capabilities. Copy [.mcp.json.example](.mcp.json.example) to `.mcp.json`:
52
+
53
+ ```json
54
+ {
55
+ "mcpServers": {
56
+ "context7": {
57
+ "command": "npx",
58
+ "args": ["-y", "@upstash/context7-mcp@latest"]
59
+ },
60
+ "grep-app": {
61
+ "command": "npx",
62
+ "args": ["-y", "@ai-tools-all/grep_app_mcp"]
63
+ }
64
+ }
65
+ }
66
+ ```
67
+
68
+ **Available MCP servers**:
69
+
70
+ - **Context7**: Up-to-date library documentation and API reference
71
+ - **grep.app**: Search 1M+ GitHub repos for real-world code examples
72
+
73
+ See [docs/TOOLCHAIN.md](docs/TOOLCHAIN.md) for complete setup instructions.
74
+
75
+ ---
76
+
77
+ ## Quick Start
78
+
79
+ 1. `/status` - Check where you are
80
+ 2. `/research <feature-name>` - Research the feature
81
+ 3. `/plan <feature-slug>` - Create formal plan
82
+ 4. `/dev` - Implement with TDD
83
+ 5. `/check` - Validate everything
84
+ 6. `/ship` - Create PR
85
+
86
+ ---
87
+
88
+ ## Toolchain
89
+
90
+ - **Beads** (recommended): `npm i -g @beads/bd && bd init` - Git-backed issue tracking
91
+ - **OpenSpec** (optional): `npm i -g @fission-ai/openspec && openspec init` - Spec-driven development
92
+ - **GitHub CLI**: `gh auth login` - PR workflow
93
+
94
+ See [docs/TOOLCHAIN.md](docs/TOOLCHAIN.md) for comprehensive tool reference.
95
+
96
+ ---
97
+
98
+ <!-- USER:START - Add project-specific learnings here as you work -->
99
+
100
+ 💡 **Keep this section focused** - Add patterns you discover while working.
101
+
102
+ As you work, when you give the same instruction twice, add it here:
103
+
104
+ - Coding style preferences
105
+ - Architecture decisions
106
+ - Domain concepts unique to this project
107
+
108
+ <!-- USER:END -->
package/bin/forge.js CHANGED
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
 
3
3
  /**
4
- * Forge v1.2.0 - Universal AI Agent Workflow
4
+ * Forge v1.3.0 - Universal AI Agent Workflow
5
5
  * https://github.com/harshanandak/forge
6
6
  *
7
7
  * Usage:
@@ -591,6 +591,49 @@ function writeEnvTokens(tokens, preserveExisting = true) {
591
591
  }
592
592
 
593
593
  // Detect existing project installation status
594
+ // Smart merge for AGENTS.md - preserves USER sections, updates FORGE sections
595
+ function smartMergeAgentsMd(existingContent, newContent) {
596
+ // Check if existing content has markers
597
+ const hasUserMarkers = existingContent.includes('<!-- USER:START') && existingContent.includes('<!-- USER:END');
598
+ const hasForgeMarkers = existingContent.includes('<!-- FORGE:START') && existingContent.includes('<!-- FORGE:END');
599
+
600
+ if (!hasUserMarkers || !hasForgeMarkers) {
601
+ // Old format without markers - return new content (let user decide via overwrite prompt)
602
+ return null;
603
+ }
604
+
605
+ // Extract USER section from existing content
606
+ const userStartMatch = existingContent.match(/<!-- USER:START.*?-->([\s\S]*?)<!-- USER:END -->/);
607
+ const userSection = userStartMatch ? userStartMatch[0] : '';
608
+
609
+ // Extract FORGE section from new content
610
+ const forgeStartMatch = newContent.match(/(<!-- FORGE:START.*?-->[\s\S]*?<!-- FORGE:END -->)/);
611
+ const forgeSection = forgeStartMatch ? forgeStartMatch[0] : '';
612
+
613
+ // Build merged content
614
+ const setupInstructions = newContent.includes('<!-- FORGE:SETUP-INSTRUCTIONS')
615
+ ? newContent.match(/(<!-- FORGE:SETUP-INSTRUCTIONS[\s\S]*?-->)/)?.[0] || ''
616
+ : '';
617
+
618
+ let merged = '# AGENTS.md\n\n';
619
+
620
+ // Add setup instructions if this is first-time setup
621
+ if (setupInstructions && !existingContent.includes('FORGE:SETUP-INSTRUCTIONS')) {
622
+ merged += setupInstructions + '\n\n';
623
+ }
624
+
625
+ // Add preserved USER section
626
+ merged += userSection + '\n\n';
627
+
628
+ // Add updated FORGE section
629
+ merged += forgeSection + '\n\n';
630
+
631
+ // Add footer
632
+ merged += `---\n\n## 💡 Improving This Workflow\n\nEvery time you give the same instruction twice, add it to this file:\n1. User-specific rules → Add to USER:START section above\n2. Forge workflow improvements → Suggest to forge maintainers\n\n**Keep this file updated as you learn about the project.**\n\n---\n\nSee \`docs/WORKFLOW.md\` for complete workflow guide.\nSee \`docs/TOOLCHAIN.md\` for comprehensive tool reference.\n`;
633
+
634
+ return merged;
635
+ }
636
+
594
637
  // Helper function for yes/no prompts with validation
595
638
  async function askYesNo(question, prompt, defaultNo = true) {
596
639
  const defaultText = defaultNo ? '[n]' : '[y]';
@@ -616,12 +659,34 @@ function detectProjectStatus() {
616
659
  const status = {
617
660
  type: 'fresh', // 'fresh', 'upgrade', or 'partial'
618
661
  hasAgentsMd: fs.existsSync(path.join(projectRoot, 'AGENTS.md')),
662
+ hasClaudeMd: fs.existsSync(path.join(projectRoot, 'CLAUDE.md')),
619
663
  hasClaudeCommands: fs.existsSync(path.join(projectRoot, '.claude/commands')),
620
664
  hasEnvLocal: fs.existsSync(path.join(projectRoot, '.env.local')),
621
665
  hasDocsWorkflow: fs.existsSync(path.join(projectRoot, 'docs/WORKFLOW.md')),
622
- existingEnvVars: {}
666
+ existingEnvVars: {},
667
+ agentsMdSize: 0,
668
+ claudeMdSize: 0,
669
+ agentsMdLines: 0,
670
+ claudeMdLines: 0
623
671
  };
624
672
 
673
+ // Get file sizes and line counts for context warnings
674
+ if (status.hasAgentsMd) {
675
+ const agentsPath = path.join(projectRoot, 'AGENTS.md');
676
+ const stats = fs.statSync(agentsPath);
677
+ const content = fs.readFileSync(agentsPath, 'utf8');
678
+ status.agentsMdSize = stats.size;
679
+ status.agentsMdLines = content.split('\n').length;
680
+ }
681
+
682
+ if (status.hasClaudeMd) {
683
+ const claudePath = path.join(projectRoot, 'CLAUDE.md');
684
+ const stats = fs.statSync(claudePath);
685
+ const content = fs.readFileSync(claudePath, 'utf8');
686
+ status.claudeMdSize = stats.size;
687
+ status.claudeMdLines = content.split('\n').length;
688
+ }
689
+
625
690
  // Determine installation type
626
691
  if (status.hasAgentsMd && status.hasClaudeCommands && status.hasDocsWorkflow) {
627
692
  status.type = 'upgrade'; // Full forge installation exists
@@ -638,6 +703,164 @@ function detectProjectStatus() {
638
703
  return status;
639
704
  }
640
705
 
706
+ // Smart file selection with context warnings
707
+ async function handleInstructionFiles(rl, question, selectedAgents, projectStatus) {
708
+ const hasClaude = selectedAgents.some(a => a.key === 'claude');
709
+ const hasOtherAgents = selectedAgents.some(a => a.key !== 'claude');
710
+
711
+ // Calculate estimated tokens (rough: ~4 chars per token)
712
+ const estimateTokens = (bytes) => Math.ceil(bytes / 4);
713
+
714
+ const result = {
715
+ createAgentsMd: false,
716
+ createClaudeMd: false,
717
+ skipAgentsMd: false,
718
+ skipClaudeMd: false
719
+ };
720
+
721
+ // Scenario 1: Both files exist (potential context bloat)
722
+ if (projectStatus.hasAgentsMd && projectStatus.hasClaudeMd) {
723
+ const totalLines = projectStatus.agentsMdLines + projectStatus.claudeMdLines;
724
+ const totalTokens = estimateTokens(projectStatus.agentsMdSize + projectStatus.claudeMdSize);
725
+
726
+ console.log('');
727
+ console.log('⚠️ WARNING: Multiple Instruction Files Detected');
728
+ console.log('='.repeat(60));
729
+ console.log(` AGENTS.md: ${projectStatus.agentsMdLines} lines (~${estimateTokens(projectStatus.agentsMdSize)} tokens)`);
730
+ console.log(` CLAUDE.md: ${projectStatus.claudeMdLines} lines (~${estimateTokens(projectStatus.claudeMdSize)} tokens)`);
731
+ console.log(` Total: ${totalLines} lines (~${totalTokens} tokens)`);
732
+ console.log('');
733
+ console.log(' ⚠️ Claude Code reads BOTH files on every request');
734
+ console.log(' ⚠️ This increases context usage and costs');
735
+ console.log('');
736
+ console.log(' Options:');
737
+ console.log(' 1) Keep CLAUDE.md only (recommended for Claude Code only)');
738
+ console.log(' 2) Keep AGENTS.md only (recommended for multi-agent users)');
739
+ console.log(' 3) Keep both (higher context usage)');
740
+ console.log('');
741
+
742
+ while (true) {
743
+ const choice = await question('Your choice (1/2/3) [2]: ');
744
+ const normalized = choice.trim() || '2';
745
+
746
+ if (normalized === '1') {
747
+ result.skipAgentsMd = true;
748
+ result.createClaudeMd = false; // Keep existing
749
+ console.log(' ✓ Will keep CLAUDE.md, remove AGENTS.md');
750
+ break;
751
+ } else if (normalized === '2') {
752
+ result.skipClaudeMd = true;
753
+ result.createAgentsMd = false; // Keep existing
754
+ console.log(' ✓ Will keep AGENTS.md, remove CLAUDE.md');
755
+ break;
756
+ } else if (normalized === '3') {
757
+ result.createAgentsMd = false; // Keep existing
758
+ result.createClaudeMd = false; // Keep existing
759
+ console.log(' ✓ Will keep both files (context: ~' + totalTokens + ' tokens)');
760
+ break;
761
+ } else {
762
+ console.log(' Please enter 1, 2, or 3');
763
+ }
764
+ }
765
+
766
+ return result;
767
+ }
768
+
769
+ // Scenario 2: Only CLAUDE.md exists
770
+ if (projectStatus.hasClaudeMd && !projectStatus.hasAgentsMd) {
771
+ if (hasOtherAgents) {
772
+ console.log('');
773
+ console.log('📋 Found existing CLAUDE.md (' + projectStatus.claudeMdLines + ' lines)');
774
+ console.log(' You selected multiple agents. Recommendation:');
775
+ console.log(' → Migrate to AGENTS.md (works with all agents)');
776
+ console.log('');
777
+
778
+ const migrate = await askYesNo(question, 'Migrate CLAUDE.md to AGENTS.md?', false);
779
+ if (migrate) {
780
+ result.createAgentsMd = true;
781
+ result.skipClaudeMd = true;
782
+ console.log(' ✓ Will migrate content to AGENTS.md');
783
+ } else {
784
+ result.createAgentsMd = true;
785
+ result.createClaudeMd = false; // Keep existing
786
+ console.log(' ✓ Will keep CLAUDE.md and create AGENTS.md');
787
+ }
788
+ } else {
789
+ // Claude Code only - keep CLAUDE.md
790
+ result.createClaudeMd = false; // Keep existing
791
+ console.log(' ✓ Keeping existing CLAUDE.md');
792
+ }
793
+
794
+ return result;
795
+ }
796
+
797
+ // Scenario 3: Only AGENTS.md exists
798
+ if (projectStatus.hasAgentsMd && !projectStatus.hasClaudeMd) {
799
+ if (hasClaude && !hasOtherAgents) {
800
+ console.log('');
801
+ console.log('📋 Found existing AGENTS.md (' + projectStatus.agentsMdLines + ' lines)');
802
+ console.log(' You selected Claude Code only. Options:');
803
+ console.log(' 1) Keep AGENTS.md (works fine)');
804
+ console.log(' 2) Rename to CLAUDE.md (Claude-specific naming)');
805
+ console.log('');
806
+
807
+ const rename = await askYesNo(question, 'Rename to CLAUDE.md?', true);
808
+ if (rename) {
809
+ result.createClaudeMd = true;
810
+ result.skipAgentsMd = true;
811
+ console.log(' ✓ Will rename to CLAUDE.md');
812
+ } else {
813
+ result.createAgentsMd = false; // Keep existing
814
+ console.log(' ✓ Keeping AGENTS.md');
815
+ }
816
+ } else {
817
+ // Multi-agent or other agents - keep AGENTS.md
818
+ result.createAgentsMd = false; // Keep existing
819
+ console.log(' ✓ Keeping existing AGENTS.md');
820
+ }
821
+
822
+ return result;
823
+ }
824
+
825
+ // Scenario 4: Neither file exists (fresh install)
826
+ if (hasClaude && !hasOtherAgents) {
827
+ // Claude Code only → create CLAUDE.md
828
+ result.createClaudeMd = true;
829
+ console.log(' ✓ Will create CLAUDE.md (Claude Code specific)');
830
+ } else if (!hasClaude && hasOtherAgents) {
831
+ // Other agents only → create AGENTS.md
832
+ result.createAgentsMd = true;
833
+ console.log(' ✓ Will create AGENTS.md (universal)');
834
+ } else {
835
+ // Multiple agents including Claude → create AGENTS.md + reference CLAUDE.md
836
+ result.createAgentsMd = true;
837
+ result.createClaudeMd = true; // Will be minimal reference
838
+ console.log(' ✓ Will create AGENTS.md (main) + CLAUDE.md (reference)');
839
+ }
840
+
841
+ return result;
842
+ }
843
+
844
+ // Create minimal CLAUDE.md that references AGENTS.md
845
+ function createClaudeReference(destPath) {
846
+ const content = `# Claude Code Instructions
847
+
848
+ See [AGENTS.md](AGENTS.md) for all project instructions.
849
+
850
+ 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.
851
+
852
+ ---
853
+
854
+ <!-- Add Claude Code-specific instructions below (if needed) -->
855
+ <!-- Examples: MCP server setup, custom commands, Claude-only workflows -->
856
+
857
+ 💡 **Keep this minimal** - Main instructions are in AGENTS.md
858
+ `;
859
+
860
+ fs.writeFileSync(destPath, content, 'utf8');
861
+ return true;
862
+ }
863
+
641
864
  // Configure external services interactively
642
865
  async function configureExternalServices(rl, question, selectedAgents = [], projectStatus = null) {
643
866
  console.log('');
@@ -888,7 +1111,7 @@ function showBanner(subtitle = 'Universal AI Agent Workflow') {
888
1111
  console.log(' ██╔══╝ ██║ ██║██╔══██╗██║ ██║██╔══╝ ');
889
1112
  console.log(' ██║ ╚██████╔╝██║ ██║╚██████╔╝███████╗');
890
1113
  console.log(' ╚═╝ ╚═════╝ ╚═╝ ╚═╝ ╚═════╝ ╚══════╝');
891
- console.log(' v1.2.0');
1114
+ console.log(' v1.3.0');
892
1115
  console.log('');
893
1116
  if (subtitle) {
894
1117
  console.log(` ${subtitle}`);
@@ -1289,8 +1512,28 @@ async function interactiveSetup() {
1289
1512
  console.log(' Skipped: AGENTS.md (keeping existing)');
1290
1513
  } else {
1291
1514
  const agentsSrc = path.join(packageDir, 'AGENTS.md');
1292
- if (copyFile(agentsSrc, 'AGENTS.md')) {
1293
- console.log(' Created: AGENTS.md (universal standard)');
1515
+ const agentsDest = path.join(projectRoot, 'AGENTS.md');
1516
+
1517
+ // Try smart merge if file exists
1518
+ if (fs.existsSync(agentsDest)) {
1519
+ const existingContent = fs.readFileSync(agentsDest, 'utf8');
1520
+ const newContent = fs.readFileSync(agentsSrc, 'utf8');
1521
+ const merged = smartMergeAgentsMd(existingContent, newContent);
1522
+
1523
+ if (merged) {
1524
+ fs.writeFileSync(agentsDest, merged, 'utf8');
1525
+ console.log(' Updated: AGENTS.md (preserved USER sections)');
1526
+ } else {
1527
+ // No markers, do normal copy (user already approved overwrite)
1528
+ if (copyFile(agentsSrc, 'AGENTS.md')) {
1529
+ console.log(' Updated: AGENTS.md (universal standard)');
1530
+ }
1531
+ }
1532
+ } else {
1533
+ // New file
1534
+ if (copyFile(agentsSrc, 'AGENTS.md')) {
1535
+ console.log(' Created: AGENTS.md (universal standard)');
1536
+ }
1294
1537
  }
1295
1538
  }
1296
1539
 
@@ -1348,7 +1591,7 @@ async function interactiveSetup() {
1348
1591
  // =============================================
1349
1592
  console.log('');
1350
1593
  console.log('==============================================');
1351
- console.log(' Forge v1.2.0 Setup Complete!');
1594
+ console.log(' Forge v1.3.0 Setup Complete!');
1352
1595
  console.log('==============================================');
1353
1596
  console.log('');
1354
1597
  console.log('What\'s installed:');
@@ -1372,16 +1615,33 @@ async function interactiveSetup() {
1372
1615
  }
1373
1616
  });
1374
1617
  console.log('');
1375
- console.log('Next steps:');
1376
- console.log(` 1. Install optional tools:`);
1377
- console.log(` ${PKG_MANAGER} install -g @beads/bd && bd init`);
1378
- console.log(` ${PKG_MANAGER} install -g @fission-ai/openspec`);
1379
- console.log(' 2. Start with: /status');
1380
- console.log(' 3. Read the guide: docs/WORKFLOW.md');
1618
+ console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
1619
+ console.log('📋 NEXT STEP - Complete AGENTS.md');
1620
+ console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
1381
1621
  console.log('');
1382
- console.log(`Package manager detected: ${PKG_MANAGER}`);
1622
+ console.log('Ask your AI agent:');
1623
+ console.log(' "Fill in the project description in AGENTS.md"');
1383
1624
  console.log('');
1384
- console.log('Happy shipping!');
1625
+ console.log('The agent will:');
1626
+ console.log(' ✓ Add one-sentence project description');
1627
+ console.log(' ✓ Confirm package manager');
1628
+ console.log(' ✓ Verify build commands');
1629
+ console.log('');
1630
+ console.log('Takes ~30 seconds. Done!');
1631
+ console.log('');
1632
+ console.log('💡 As you work: Add project patterns to AGENTS.md');
1633
+ console.log(' USER:START section. Keep it minimal - budget is');
1634
+ console.log(' ~150-200 instructions max.');
1635
+ console.log('');
1636
+ console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
1637
+ console.log('');
1638
+ console.log('Optional tools:');
1639
+ console.log(` ${PKG_MANAGER} install -g @beads/bd && bd init`);
1640
+ console.log(` ${PKG_MANAGER} install -g @fission-ai/openspec`);
1641
+ console.log('');
1642
+ console.log('Start with: /status');
1643
+ console.log('');
1644
+ console.log(`Package manager: ${PKG_MANAGER}`);
1385
1645
  console.log('');
1386
1646
  }
1387
1647
 
@@ -1569,7 +1829,7 @@ async function quickSetup(selectedAgents, skipExternal) {
1569
1829
  // Final summary
1570
1830
  console.log('');
1571
1831
  console.log('==============================================');
1572
- console.log(' Forge v1.2.0 Quick Setup Complete!');
1832
+ console.log(' Forge v1.3.0 Quick Setup Complete!');
1573
1833
  console.log('==============================================');
1574
1834
  console.log('');
1575
1835
  console.log('Next steps:');
@@ -1733,8 +1993,28 @@ async function interactiveSetupWithFlags(flags) {
1733
1993
  console.log(' Skipped: AGENTS.md (keeping existing)');
1734
1994
  } else {
1735
1995
  const agentsSrc = path.join(packageDir, 'AGENTS.md');
1736
- if (copyFile(agentsSrc, 'AGENTS.md')) {
1737
- console.log(' Created: AGENTS.md (universal standard)');
1996
+ const agentsDest = path.join(projectRoot, 'AGENTS.md');
1997
+
1998
+ // Try smart merge if file exists
1999
+ if (fs.existsSync(agentsDest)) {
2000
+ const existingContent = fs.readFileSync(agentsDest, 'utf8');
2001
+ const newContent = fs.readFileSync(agentsSrc, 'utf8');
2002
+ const merged = smartMergeAgentsMd(existingContent, newContent);
2003
+
2004
+ if (merged) {
2005
+ fs.writeFileSync(agentsDest, merged, 'utf8');
2006
+ console.log(' Updated: AGENTS.md (preserved USER sections)');
2007
+ } else {
2008
+ // No markers, do normal copy (user already approved overwrite)
2009
+ if (copyFile(agentsSrc, 'AGENTS.md')) {
2010
+ console.log(' Updated: AGENTS.md (universal standard)');
2011
+ }
2012
+ }
2013
+ } else {
2014
+ // New file
2015
+ if (copyFile(agentsSrc, 'AGENTS.md')) {
2016
+ console.log(' Created: AGENTS.md (universal standard)');
2017
+ }
1738
2018
  }
1739
2019
  }
1740
2020
 
@@ -1797,7 +2077,7 @@ async function interactiveSetupWithFlags(flags) {
1797
2077
  // =============================================
1798
2078
  console.log('');
1799
2079
  console.log('==============================================');
1800
- console.log(' Forge v1.2.0 Setup Complete!');
2080
+ console.log(' Forge v1.3.0 Setup Complete!');
1801
2081
  console.log('==============================================');
1802
2082
  console.log('');
1803
2083
  console.log('What\'s installed:');
@@ -1821,16 +2101,33 @@ async function interactiveSetupWithFlags(flags) {
1821
2101
  }
1822
2102
  });
1823
2103
  console.log('');
1824
- console.log('Next steps:');
1825
- console.log(` 1. Install optional tools:`);
1826
- console.log(` ${PKG_MANAGER} install -g @beads/bd && bd init`);
1827
- console.log(` ${PKG_MANAGER} install -g @fission-ai/openspec`);
1828
- console.log(' 2. Start with: /status');
1829
- console.log(' 3. Read the guide: docs/WORKFLOW.md');
2104
+ console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
2105
+ console.log('📋 NEXT STEP - Complete AGENTS.md');
2106
+ console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
1830
2107
  console.log('');
1831
- console.log(`Package manager detected: ${PKG_MANAGER}`);
2108
+ console.log('Ask your AI agent:');
2109
+ console.log(' "Fill in the project description in AGENTS.md"');
1832
2110
  console.log('');
1833
- console.log('Happy shipping!');
2111
+ console.log('The agent will:');
2112
+ console.log(' ✓ Add one-sentence project description');
2113
+ console.log(' ✓ Confirm package manager');
2114
+ console.log(' ✓ Verify build commands');
2115
+ console.log('');
2116
+ console.log('Takes ~30 seconds. Done!');
2117
+ console.log('');
2118
+ console.log('💡 As you work: Add project patterns to AGENTS.md');
2119
+ console.log(' USER:START section. Keep it minimal - budget is');
2120
+ console.log(' ~150-200 instructions max.');
2121
+ console.log('');
2122
+ console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
2123
+ console.log('');
2124
+ console.log('Optional tools:');
2125
+ console.log(` ${PKG_MANAGER} install -g @beads/bd && bd init`);
2126
+ console.log(` ${PKG_MANAGER} install -g @fission-ai/openspec`);
2127
+ console.log('');
2128
+ console.log('Start with: /status');
2129
+ console.log('');
2130
+ console.log(`Package manager: ${PKG_MANAGER}`);
1834
2131
  console.log('');
1835
2132
  }
1836
2133
 
package/docs/TOOLCHAIN.md CHANGED
@@ -393,9 +393,10 @@ The system SHALL support optional 2FA
393
393
 
394
394
  Context7 provides current documentation that may be more recent than the AI's training data.
395
395
 
396
- **Installation (Claude Code)**:
396
+ **Installation**:
397
+
398
+ **Claude Code**: Add to `.mcp.json` in your project root:
397
399
 
398
- Add to `.mcp.json` in your project root:
399
400
 
400
401
  ```json
401
402
  {
@@ -420,6 +421,28 @@ Add to `.mcp.json` in your project root:
420
421
  }
421
422
  ```
422
423
 
424
+ **Cline (VSCode)**:
425
+ 1. Open VSCode Settings
426
+ 2. Search for "Cline MCP"
427
+ 3. Add Context7 server configuration
428
+
429
+ **Continue**: Add to `.continue/config.json`:
430
+
431
+ ```json
432
+ {
433
+ "mcpServers": {
434
+ "context7": {
435
+ "command": "npx",
436
+ "args": ["-y", "@upstash/context7-mcp@latest"]
437
+ }
438
+ }
439
+ }
440
+ ```
441
+
442
+ **Cursor**: Check Cursor Settings → MCP Servers for configuration options
443
+
444
+ **Other agents**: If your agent supports MCP, configure using the JSON format above
445
+
423
446
  **Usage**:
424
447
  ```
425
448
  # The AI will automatically use Context7 when you ask about libraries
@@ -434,6 +457,72 @@ Add to `.mcp.json` in your project root:
434
457
  - To verify API signatures and patterns
435
458
  - For current best practices
436
459
 
460
+ ### grep.app - Code Search
461
+
462
+ **Package**: `@ai-tools-all/grep_app_mcp` (recommended) or `@galprz/grep-mcp`
463
+ **Website**: [grep.app](https://grep.app)
464
+ **Purpose**: Search across 1M+ public GitHub repositories for real-world code examples
465
+ **Used in**: `/research` stage, finding implementation patterns
466
+
467
+ grep.app provides code search across public GitHub repositories to find real-world examples and patterns.
468
+
469
+ **Installation (Claude Code)**:
470
+
471
+ Add to `.mcp.json` in your project root:
472
+
473
+ ```json
474
+ {
475
+ "mcpServers": {
476
+ "context7": {
477
+ "command": "npx",
478
+ "args": ["-y", "@upstash/context7-mcp@latest"]
479
+ },
480
+ "grep-app": {
481
+ "command": "npx",
482
+ "args": ["-y", "@ai-tools-all/grep_app_mcp"]
483
+ }
484
+ }
485
+ }
486
+ ```
487
+
488
+ **Or with bunx**:
489
+ ```json
490
+ {
491
+ "mcpServers": {
492
+ "context7": {
493
+ "command": "bunx",
494
+ "args": ["--bun", "@upstash/context7-mcp@latest"]
495
+ },
496
+ "grep-app": {
497
+ "command": "bunx",
498
+ "args": ["--bun", "@ai-tools-all/grep_app_mcp"]
499
+ }
500
+ }
501
+ }
502
+ ```
503
+
504
+ **Usage**:
505
+ ```
506
+ # The AI will use grep.app when you need real-world examples
507
+ "Find examples of React useEffect cleanup patterns"
508
+ "Show me how others implement JWT authentication in Express"
509
+ "Search for rate limiting implementations in Node.js"
510
+ ```
511
+
512
+ **When to use grep.app**:
513
+
514
+ - Finding real-world implementation examples
515
+ - Discovering coding patterns in production code
516
+ - Validating implementation approaches
517
+ - Learning from open source projects
518
+
519
+ **Context7 vs grep.app**:
520
+
521
+ | Tool | Purpose | Use When |
522
+ |----------------|--------------------------------|-------------------------------------------|
523
+ | **Context7** | Official library documentation | You need API reference, official patterns |
524
+ | **grep.app** | Real code in the wild | You want to see how others solve problems |
525
+
437
526
  ---
438
527
 
439
528
  ## External Services
@@ -658,7 +747,7 @@ gh issue create --title "..." --body "..."
658
747
  | Stage | Tools Used |
659
748
  |-------|------------|
660
749
  | `/status` | `bd ready`, `bd list`, `git status`, `openspec list` |
661
- | `/research` | Parallel AI, codebase exploration |
750
+ | `/research` | Parallel AI, Context7, grep.app, codebase exploration |
662
751
  | `/plan` | `bd create`, `openspec` (if strategic), `git checkout -b` |
663
752
  | `/dev` | Tests, code, `bd update`, `/tasks save` |
664
753
  | `/check` | Type check, lint, tests, SonarCloud |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "forge-workflow",
3
- "version": "1.2.0",
3
+ "version": "1.3.1",
4
4
  "description": "9-stage TDD workflow for ALL AI coding agents (Claude, Cursor, Windsurf, Kilo, OpenCode, Copilot, Cline, Roo, Aider, Continue, Antigravity)",
5
5
  "bin": {
6
6
  "forge": "bin/forge.js"
@@ -44,6 +44,8 @@
44
44
  ".claude/",
45
45
  "docs/",
46
46
  "install.sh",
47
- "AGENTS.md"
47
+ "AGENTS.md",
48
+ "CLAUDE.md",
49
+ ".mcp.json.example"
48
50
  ]
49
51
  }