forge-workflow 1.2.0 → 1.3.0

package/.claude/settings.local.json

@@ -14,7 +14,8 @@
       "Bash(git push)",
       "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)"
+      "Bash(\"C:\\\\Program Files\\\\nodejs\\\\npm.cmd\" version minor --no-git-tag-version)",
+      "WebFetch(domain:ohmyopencode.com)"
     ]
   }
 }

package/AGENTS.md

@@ -1,217 +1,34 @@
-# Forge - 9-Stage TDD Workflow
+# AGENTS.md
 
-A TDD-first workflow for AI coding agents. Ship features with confidence.
+This is a [describe what this project does in one sentence].
 
-## Commands (9 Stages)
+**Package manager**: npm (or specify: pnpm/yarn/bun)
 
-| Stage | Command | Description |
-|-------|---------|-------------|
-| 1 | `/status` | Check current context, active work, recent completions |
-| 2 | `/research` | Deep research with web search, document to docs/research/ |
-| 3 | `/plan` | Create implementation plan, branch, OpenSpec if strategic |
-| 4 | `/dev` | TDD development (RED-GREEN-REFACTOR cycles) |
-| 5 | `/check` | Validation (type/lint/security/tests) |
-| 6 | `/ship` | Create PR with full documentation |
-| 7 | `/review` | Address ALL PR feedback |
-| 8 | `/merge` | Update docs, merge PR, cleanup |
-| 9 | `/verify` | Final documentation verification |
-
-## Workflow Flow
-
-```
-/status → /research → /plan → /dev → /check → /ship → /review → /merge → /verify
-```
-
-## 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
-
-## Prerequisites
-
-- Git, GitHub CLI (`gh`)
-- Beads (recommended): `npm i -g @beads/bd && bd init`
-- OpenSpec (optional): `npm i -g @fission-ai/openspec && openspec init`
-
-## Toolchain Quick Reference
-
-### Beads (Issue Tracking)
+**Build commands**:
 ```bash
-bd ready                    # Find unblocked work (start here!)
-bd create "Title" -p 2      # Create issue with priority
-bd update <id> --status in_progress
-bd comments <id> "note"     # Add comment
-bd close <id>               # Complete
-bd sync                     # Git sync (always at session end!)
-```
-
-### OpenSpec (Specs - AI Commands)
-```bash
-/opsx:new                   # Start change
-/opsx:ff                    # Generate all planning docs
-/opsx:apply                 # Implement tasks
-/opsx:verify                # Validate
-/opsx:archive               # Complete
-```
-
-### GitHub CLI
-```bash
-gh pr create --title "..." --body "..."
-gh pr view <n>
-gh pr merge <n> --squash --delete-branch
-```
-
-## 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
-
-## Stage Details
-
-### 1. Status (`/status`)
-
-Check current context before starting work:
-- Active issues (via Beads if installed)
-- Recent completions
-- Current branch state
-- OpenSpec proposals in progress
-
-### 2. Research (`/research <feature-name>`)
-
-Research before building:
-- Web search for best practices
-- Security analysis (OWASP Top 10)
-- Existing patterns in codebase
-- Document to `docs/research/<feature>.md`
-
-### 3. Plan (`/plan <feature-slug>`)
-
-Create implementation plan:
-- Create feature branch
-- Define scope and approach
-- Create tracking issue (Beads)
-- OpenSpec proposal if strategic
-
-### 4. Development (`/dev`)
-
-TDD implementation:
-- RED: Write failing test
-- GREEN: Make it pass
-- REFACTOR: Clean up
-- Commit after each GREEN cycle
-
-### 5. Check (`/check`)
-
-Validate everything:
-- Type checking
-- Linting
-- Unit tests
-- Integration tests
-- Security scan
-
-### 6. Ship (`/ship`)
-
-Create pull request:
-- Push branch
-- Create PR with documentation
-- Link to research doc
-- List test coverage
-
-### 7. Review (`/review`)
-
-Address ALL feedback:
-- GitHub Actions failures
-- Code review comments
-- Security scan issues
-- Automated tool feedback
-
-### 8. Merge (`/merge`)
-
-Complete the work:
-- Update documentation
-- Squash merge PR
-- Archive OpenSpec (if used)
-- Close tracking issues
-
-### 9. Verify (`/verify`)
-
-Final documentation check:
-- All docs updated
-- Cross-references valid
-- Examples work
-- README current
-
-## Directory Structure
-
-```
-your-project/
-├── AGENTS.md                    # This file (universal)
-├── CLAUDE.md                    # Claude Code
-├── GEMINI.md                    # Google Antigravity
-├── .cursorrules                 # Cursor
-├── .windsurfrules               # Windsurf
-├── .clinerules                  # Cline/Roo Code
-├── .github/
-│   └── copilot-instructions.md  # GitHub Copilot
-│
-├── .claude/commands/            # Claude Code commands
-├── .agent/workflows/            # Antigravity workflows
-├── .cursor/rules/               # Cursor rules
-├── .windsurf/workflows/         # Windsurf workflows
-├── .kilocode/workflows/         # Kilo Code workflows
-├── .opencode/commands/          # OpenCode commands
-├── .continue/prompts/           # Continue prompts
-├── .roo/commands/               # Roo Code commands
-│
-└── docs/
-    ├── planning/
-    │   └── PROGRESS.md
-    ├── research/
-    │   └── TEMPLATE.md
-    └── WORKFLOW.md
+npm install      # Install dependencies
+npm run dev      # Start development
+npm run build    # Production build
+npm test         # Run tests
 ```
 
-## Skills (Universal SKILL.md Format)
+**Workflow**: See [`docs/WORKFLOW.md`](docs/WORKFLOW.md) for the 9-stage TDD workflow.
 
-The `forge-workflow` skill is installed to all supporting agents:
-- `.claude/skills/forge-workflow/SKILL.md`
-- `.agent/skills/forge-workflow/SKILL.md` (Antigravity)
-- `.cursor/skills/forge-workflow/SKILL.md`
-- `.windsurf/skills/forge-workflow/SKILL.md`
-- `.kilocode/skills/forge-workflow/SKILL.md`
-- `.cline/skills/forge-workflow/SKILL.md`
-- `.continue/skills/forge-workflow/SKILL.md`
-- `.opencode/skills/forge-workflow/SKILL.md`
+**Project-specific conventions**: Add them below as you discover patterns.
 
-## Supported Agents
+---
 
-This workflow works with ALL major AI coding agents:
+<!-- USER:START - Add learnings here as you work -->
 
-| Agent | Instructions | Commands | Skills |
-|-------|-------------|----------|--------|
-| Claude Code | CLAUDE.md | .claude/commands/ | .claude/skills/ |
-| Google Antigravity | GEMINI.md | .agent/workflows/ | .agent/skills/ |
-| Cursor | .cursorrules | .cursor/rules/ | .cursor/skills/ |
-| Windsurf | .windsurfrules | .windsurf/workflows/ | .windsurf/skills/ |
-| Kilo Code | AGENTS.md | .kilocode/workflows/ | .kilocode/skills/ |
-| OpenCode | AGENTS.md | .opencode/commands/ | .opencode/skills/ |
-| Cline | .clinerules | AGENTS.md | .cline/skills/ |
-| Roo Code | .clinerules | .roo/commands/ | - |
-| Continue | .continuerules | .continue/prompts/ | .continue/skills/ |
-| GitHub Copilot | .github/copilot-instructions.md | .github/prompts/ | - |
-| Aider | AGENTS.md (via config) | In-chat | - |
+💡 **Keep this section minimal** - Instruction budget is ~150-200 instructions max.
 
-## License
+As you work, when you give the same instruction twice, add it here:
+- Coding style preferences
+- Architecture decisions
+- Domain concepts unique to this project
 
-MIT
+<!-- USER:END -->
 
 ---
 
-See `docs/WORKFLOW.md` for the complete workflow guide.
-See `docs/TOOLCHAIN.md` for comprehensive tool reference.
+See [`docs/TOOLCHAIN.md`](docs/TOOLCHAIN.md) for comprehensive tool reference.

package/bin/forge.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 /**
- * Forge v1.2.0 - Universal AI Agent Workflow
+ * Forge v1.3.0 - Universal AI Agent Workflow
  * https://github.com/harshanandak/forge
  *
  * Usage:
@@ -591,6 +591,49 @@ function writeEnvTokens(tokens, preserveExisting = true) {
 }
 
 // Detect existing project installation status
+// Smart merge for AGENTS.md - preserves USER sections, updates FORGE sections
+function smartMergeAgentsMd(existingContent, newContent) {
+  // Check if existing content has markers
+  const hasUserMarkers = existingContent.includes('<!-- USER:START') && existingContent.includes('<!-- USER:END');
+  const hasForgeMarkers = existingContent.includes('<!-- FORGE:START') && existingContent.includes('<!-- FORGE:END');
+
+  if (!hasUserMarkers || !hasForgeMarkers) {
+    // Old format without markers - return new content (let user decide via overwrite prompt)
+    return null;
+  }
+
+  // Extract USER section from existing content
+  const userStartMatch = existingContent.match(/<!-- USER:START.*?-->([\s\S]*?)<!-- USER:END -->/);
+  const userSection = userStartMatch ? userStartMatch[0] : '';
+
+  // Extract FORGE section from new content
+  const forgeStartMatch = newContent.match(/(<!-- FORGE:START.*?-->[\s\S]*?<!-- FORGE:END -->)/);
+  const forgeSection = forgeStartMatch ? forgeStartMatch[0] : '';
+
+  // Build merged content
+  const setupInstructions = newContent.includes('<!-- FORGE:SETUP-INSTRUCTIONS')
+    ? newContent.match(/(<!-- FORGE:SETUP-INSTRUCTIONS[\s\S]*?-->)/)?.[0] || ''
+    : '';
+
+  let merged = '# AGENTS.md\n\n';
+
+  // Add setup instructions if this is first-time setup
+  if (setupInstructions && !existingContent.includes('FORGE:SETUP-INSTRUCTIONS')) {
+    merged += setupInstructions + '\n\n';
+  }
+
+  // Add preserved USER section
+  merged += userSection + '\n\n';
+
+  // Add updated FORGE section
+  merged += forgeSection + '\n\n';
+
+  // Add footer
+  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`;
+
+  return merged;
+}
+
 // Helper function for yes/no prompts with validation
 async function askYesNo(question, prompt, defaultNo = true) {
   const defaultText = defaultNo ? '[n]' : '[y]';
@@ -888,7 +931,7 @@ function showBanner(subtitle = 'Universal AI Agent Workflow') {
   console.log('  ██╔══╝  ██║   ██║██╔══██╗██║   ██║██╔══╝  ');
   console.log('  ██║     ╚██████╔╝██║  ██║╚██████╔╝███████╗');
   console.log('  ╚═╝      ╚═════╝ ╚═╝  ╚═╝ ╚═════╝ ╚══════╝');
-  console.log('  v1.2.0');
+  console.log('  v1.3.0');
   console.log('');
   if (subtitle) {
     console.log(`  ${subtitle}`);
@@ -1289,8 +1332,28 @@ async function interactiveSetup() {
     console.log('  Skipped: AGENTS.md (keeping existing)');
   } else {
     const agentsSrc = path.join(packageDir, 'AGENTS.md');
-    if (copyFile(agentsSrc, 'AGENTS.md')) {
-      console.log('  Created: AGENTS.md (universal standard)');
+    const agentsDest = path.join(projectRoot, 'AGENTS.md');
+
+    // Try smart merge if file exists
+    if (fs.existsSync(agentsDest)) {
+      const existingContent = fs.readFileSync(agentsDest, 'utf8');
+      const newContent = fs.readFileSync(agentsSrc, 'utf8');
+      const merged = smartMergeAgentsMd(existingContent, newContent);
+
+      if (merged) {
+        fs.writeFileSync(agentsDest, merged, 'utf8');
+        console.log('  Updated: AGENTS.md (preserved USER sections)');
+      } else {
+        // No markers, do normal copy (user already approved overwrite)
+        if (copyFile(agentsSrc, 'AGENTS.md')) {
+          console.log('  Updated: AGENTS.md (universal standard)');
+        }
+      }
+    } else {
+      // New file
+      if (copyFile(agentsSrc, 'AGENTS.md')) {
+        console.log('  Created: AGENTS.md (universal standard)');
+      }
     }
   }
 
@@ -1348,7 +1411,7 @@ async function interactiveSetup() {
   // =============================================
   console.log('');
   console.log('==============================================');
-  console.log('  Forge v1.2.0 Setup Complete!');
+  console.log('  Forge v1.3.0 Setup Complete!');
   console.log('==============================================');
   console.log('');
   console.log('What\'s installed:');
@@ -1372,16 +1435,33 @@ async function interactiveSetup() {
     }
   });
   console.log('');
-  console.log('Next steps:');
-  console.log(`  1. Install optional tools:`);
-  console.log(`     ${PKG_MANAGER} install -g @beads/bd && bd init`);
-  console.log(`     ${PKG_MANAGER} install -g @fission-ai/openspec`);
-  console.log('  2. Start with: /status');
-  console.log('  3. Read the guide: docs/WORKFLOW.md');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('📋  NEXT STEP - Complete AGENTS.md');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
   console.log('');
-  console.log(`Package manager detected: ${PKG_MANAGER}`);
+  console.log('Ask your AI agent:');
+  console.log('  "Fill in the project description in AGENTS.md"');
   console.log('');
-  console.log('Happy shipping!');
+  console.log('The agent will:');
+  console.log('  ✓ Add one-sentence project description');
+  console.log('  ✓ Confirm package manager');
+  console.log('  ✓ Verify build commands');
+  console.log('');
+  console.log('Takes ~30 seconds. Done!');
+  console.log('');
+  console.log('💡 As you work: Add project patterns to AGENTS.md');
+  console.log('   USER:START section. Keep it minimal - budget is');
+  console.log('   ~150-200 instructions max.');
+  console.log('');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('');
+  console.log('Optional tools:');
+  console.log(`  ${PKG_MANAGER} install -g @beads/bd && bd init`);
+  console.log(`  ${PKG_MANAGER} install -g @fission-ai/openspec`);
+  console.log('');
+  console.log('Start with: /status');
+  console.log('');
+  console.log(`Package manager: ${PKG_MANAGER}`);
   console.log('');
 }
 
@@ -1569,7 +1649,7 @@ async function quickSetup(selectedAgents, skipExternal) {
   // Final summary
   console.log('');
   console.log('==============================================');
-  console.log('  Forge v1.2.0 Quick Setup Complete!');
+  console.log('  Forge v1.3.0 Quick Setup Complete!');
   console.log('==============================================');
   console.log('');
   console.log('Next steps:');
@@ -1733,8 +1813,28 @@ async function interactiveSetupWithFlags(flags) {
     console.log('  Skipped: AGENTS.md (keeping existing)');
   } else {
     const agentsSrc = path.join(packageDir, 'AGENTS.md');
-    if (copyFile(agentsSrc, 'AGENTS.md')) {
-      console.log('  Created: AGENTS.md (universal standard)');
+    const agentsDest = path.join(projectRoot, 'AGENTS.md');
+
+    // Try smart merge if file exists
+    if (fs.existsSync(agentsDest)) {
+      const existingContent = fs.readFileSync(agentsDest, 'utf8');
+      const newContent = fs.readFileSync(agentsSrc, 'utf8');
+      const merged = smartMergeAgentsMd(existingContent, newContent);
+
+      if (merged) {
+        fs.writeFileSync(agentsDest, merged, 'utf8');
+        console.log('  Updated: AGENTS.md (preserved USER sections)');
+      } else {
+        // No markers, do normal copy (user already approved overwrite)
+        if (copyFile(agentsSrc, 'AGENTS.md')) {
+          console.log('  Updated: AGENTS.md (universal standard)');
+        }
+      }
+    } else {
+      // New file
+      if (copyFile(agentsSrc, 'AGENTS.md')) {
+        console.log('  Created: AGENTS.md (universal standard)');
+      }
     }
   }
 
@@ -1797,7 +1897,7 @@ async function interactiveSetupWithFlags(flags) {
   // =============================================
   console.log('');
   console.log('==============================================');
-  console.log('  Forge v1.2.0 Setup Complete!');
+  console.log('  Forge v1.3.0 Setup Complete!');
   console.log('==============================================');
   console.log('');
   console.log('What\'s installed:');
@@ -1821,16 +1921,33 @@ async function interactiveSetupWithFlags(flags) {
     }
   });
   console.log('');
-  console.log('Next steps:');
-  console.log(`  1. Install optional tools:`);
-  console.log(`     ${PKG_MANAGER} install -g @beads/bd && bd init`);
-  console.log(`     ${PKG_MANAGER} install -g @fission-ai/openspec`);
-  console.log('  2. Start with: /status');
-  console.log('  3. Read the guide: docs/WORKFLOW.md');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('📋  NEXT STEP - Complete AGENTS.md');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
   console.log('');
-  console.log(`Package manager detected: ${PKG_MANAGER}`);
+  console.log('Ask your AI agent:');
+  console.log('  "Fill in the project description in AGENTS.md"');
   console.log('');
-  console.log('Happy shipping!');
+  console.log('The agent will:');
+  console.log('  ✓ Add one-sentence project description');
+  console.log('  ✓ Confirm package manager');
+  console.log('  ✓ Verify build commands');
+  console.log('');
+  console.log('Takes ~30 seconds. Done!');
+  console.log('');
+  console.log('💡 As you work: Add project patterns to AGENTS.md');
+  console.log('   USER:START section. Keep it minimal - budget is');
+  console.log('   ~150-200 instructions max.');
+  console.log('');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('');
+  console.log('Optional tools:');
+  console.log(`  ${PKG_MANAGER} install -g @beads/bd && bd init`);
+  console.log(`  ${PKG_MANAGER} install -g @fission-ai/openspec`);
+  console.log('');
+  console.log('Start with: /status');
+  console.log('');
+  console.log(`Package manager: ${PKG_MANAGER}`);
   console.log('');
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-workflow",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "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"