forge-workflow 0.0.2 → 0.0.4

package/bin/forge.js

@@ -47,10 +47,17 @@ const VERSION = packageJson.version;
 
 // Load PluginManager for discoverable agent architecture
 const PluginManager = require('../lib/plugin-manager');
+const { scaffoldGithubBeadsSync } = require('../lib/setup');
 
 // Load enhanced onboarding modules
 const contextMerge = require(path.join(packageDir, 'lib', 'context-merge'));
 const projectDiscovery = require(path.join(packageDir, 'lib', 'project-discovery'));
+
+// Load incremental setup modules
+const { detectEnvironment } = require('../lib/detect-agent');
+const { fileMatchesContent } = require('../lib/file-hash');
+const { SetupActionLog } = require('../lib/setup-action-log');
+const { renderSetupSummary } = require('../lib/setup-summary-renderer');
 // workflowProfiles is loaded but not currently used in the setup flow
 // const _workflowProfiles = require(path.join(packageDir, 'lib', 'workflow-profiles'));
 
@@ -58,6 +65,11 @@ const projectDiscovery = require(path.join(packageDir, 'lib', 'project-discovery
 let projectRoot = process.env.INIT_CWD || process.cwd();
 const args = process.argv.slice(2);
 
+// Incremental setup state (set during main() from parsed flags)
+let FORCE_MODE = false;
+let VERBOSE_MODE = false;
+let actionLog = new SetupActionLog();
+
 // Detected package manager
 let PKG_MANAGER = 'npm';
 
@@ -251,49 +263,26 @@ function _checkWritePermission(filePath) {
   }
 }
 
-const COMMANDS = ['status', 'research', 'plan', 'dev', 'check', 'ship', 'review', 'merge', 'verify', 'rollback'];
-
-// Code review tool options (reserved for future feature)
-const _CODE_REVIEW_TOOLS = {
-  'github-code-quality': {
-    name: 'GitHub Code Quality',
-    description: 'FREE, built-in - Zero setup required',
-    recommended: true
-  },
-  'coderabbit': {
-    name: 'CodeRabbit',
-    description: 'FREE for open source - Install GitHub App at https://coderabbit.ai'
-  },
-  'greptile': {
-    name: 'Greptile',
-    description: 'Paid ($99+/mo) - Enterprise code review',
-    requiresApiKey: true,
-    envVar: 'GREPTILE_API_KEY',
-    getKeyUrl: 'https://greptile.com'
-  }
-};
-
-// Code quality tool options (reserved for future feature)
-const _CODE_QUALITY_TOOLS = {
-  'eslint': {
-    name: 'ESLint only',
-    description: 'FREE, built-in - No external server required',
-    recommended: true
-  },
-  'sonarcloud': {
-    name: 'SonarCloud',
-    description: '50k LoC free, cloud-hosted',
-    requiresApiKey: true,
-    envVars: ['SONAR_TOKEN', 'SONAR_ORGANIZATION', 'SONAR_PROJECT_KEY'],
-    getKeyUrl: 'https://sonarcloud.io/account/security'
-  },
-  'sonarqube': {
-    name: 'SonarQube Community',
-    description: 'FREE, self-hosted, unlimited LoC',
-    envVars: ['SONARQUBE_URL', 'SONARQUBE_TOKEN'],
-    dockerCommand: 'docker run -d --name sonarqube -p 9000:9000 sonarqube:community'
-  }
-};
+/**
+ * Reads workflow command names from .claude/commands/*.md in the package directory.
+ * @returns {string[]} Command names (filenames without .md extension)
+ */
+function getWorkflowCommands() {
+  const commandsDir = path.join(packageDir, '.claude', 'commands');
+  try {
+    return fs.readdirSync(commandsDir)
+      .filter(f => f.endsWith('.md'))
+      .map(f => f.replace(/\.md$/, ''));
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      console.warn(`Warning: .claude/commands directory not found at ${commandsDir}`);
+    } else {
+      console.warn(`Warning: failed to read .claude/commands — ${err.code}: ${err.message}`);
+    }
+    return [];
+  }
+}
+
 
 // Helper function to safely execute commands (no user input)
 function safeExec(cmd) {
@@ -469,24 +458,23 @@ alwaysApply: true
 
 Use these commands via \`/command-name\`:
 
-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, tracking
-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
+- \`/status\` (utility) - Check current context, active work, recent completions
+1. \`/plan\` - Design intent Q&A, research, branch + task list
+2. \`/dev\` - Subagent-driven TDD per task (spec + quality review)
+3. \`/validate\` - Type check, lint, security, tests (HARD-GATE)
+4. \`/ship\` - Push and create PR with design doc reference
+5. \`/review\` - Handle ALL PR issues (Actions, Greptile, SonarCloud)
+6. \`/premerge\` - Complete docs on feature branch, hand off PR to user
+7. \`/verify\` - Post-merge health check (CI on main, close Beads)
 
 See AGENTS.md for full workflow details.
 `;
 
 // Helper functions
-const resolvedProjectRoot = path.resolve(projectRoot);
 
 function ensureDir(dir) {
   const fullPath = path.resolve(projectRoot, dir);
+  const resolvedProjectRoot = path.resolve(projectRoot);
 
   // SECURITY: Prevent path traversal
   if (!fullPath.startsWith(resolvedProjectRoot)) {
@@ -503,6 +491,7 @@ function ensureDir(dir) {
 function writeFile(filePath, content) {
   try {
     const fullPath = path.resolve(projectRoot, filePath);
+    const resolvedProjectRoot = path.resolve(projectRoot);
 
     // SECURITY: Prevent path traversal
     if (!fullPath.startsWith(resolvedProjectRoot)) {
@@ -536,6 +525,7 @@ function readFile(filePath) {
 function copyFile(src, dest) {
   try {
     const destPath = path.resolve(projectRoot, dest);
+    const resolvedProjectRoot = path.resolve(projectRoot);
 
     // SECURITY: Prevent path traversal
     if (!destPath.startsWith(resolvedProjectRoot)) {
@@ -544,13 +534,25 @@ function copyFile(src, dest) {
     }
 
     if (fs.existsSync(src)) {
+      // Content-hash comparison: skip if destination already matches source
+      if (!FORCE_MODE) {
+        const sourceContent = fs.readFileSync(src, 'utf8');
+        if (fileMatchesContent(destPath, sourceContent)) {
+          actionLog.add(dest, 'skipped', 'identical content');
+          return true;
+        }
+      }
+
       const destDir = path.dirname(destPath);
       if (!fs.existsSync(destDir)) {
         fs.mkdirSync(destDir, { recursive: true });
       }
+      const isNew = !fs.existsSync(destPath);
       fs.copyFileSync(src, destPath);
+      const action = FORCE_MODE ? 'force-created' : (isNew ? 'created' : 'updated');
+      actionLog.add(dest, action);
       return true;
-    } else if (process.env.DEBUG) {
+    } else {
       console.warn(`  ⚠ Source file not found: ${src}`);
     }
   } catch (err) {
@@ -766,7 +768,7 @@ function smartMergeAgentsMd(existingContent, newContent) {
   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`;
+  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 \`AGENTS.md\` for complete workflow guide.\nSee \`docs/TOOLCHAIN.md\` for comprehensive tool reference.\n`;
 
   return merged;
 }
@@ -799,7 +801,6 @@ async function detectProjectStatus() {
     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: {},
     agentsMdSize: 0,
     claudeMdSize: 0,
@@ -832,7 +833,7 @@ async function detectProjectStatus() {
   }
 
   // Determine installation type
-  if (status.hasAgentsMd && status.hasClaudeCommands && status.hasDocsWorkflow) {
+  if (status.hasAgentsMd && status.hasClaudeCommands) {
     status.type = 'upgrade'; // Full forge installation exists
   } else if (status.hasClaudeCommands || status.hasEnvLocal) {
     status.type = 'partial'; // Agent-specific files exist (not just base files from postinstall)
@@ -1764,6 +1765,23 @@ async function configureExternalServices(rl, question, selectedAgents = [], proj
   // Write all tokens to .env.local (preserving existing values)
   const { added, preserved } = writeEnvTokens(tokens, true);
   displayEnvTokenResults(added, preserved);
+
+  // GitHub-Beads issue sync setup
+  console.log('');
+  const enableSync = await askYesNo(question, 'Enable GitHub ↔ Beads issue sync?', true);
+  if (enableSync) {
+    try {
+      const result = await scaffoldGithubBeadsSync(projectRoot, packageDir);
+      for (const f of result.created) {
+        console.log(`  Created: ${f}`);
+      }
+      for (const f of result.skipped) {
+        console.log(`  Skipped: ${f} (already exists)`);
+      }
+    } catch (err) {
+      console.error(`  Error scaffolding GitHub-Beads sync: ${err.message}`);
+    }
+  }
 }
 
 // Display the Forge banner
@@ -1782,40 +1800,28 @@ function showBanner(subtitle = 'Universal AI Agent Workflow') {
   }
 }
 
-// Setup core documentation and directories
-function setupCoreDocs() {
-  // Create core directories
-  ensureDir('docs/planning');
-  ensureDir('docs/research');
-
-  // Copy WORKFLOW.md
-  const workflowSrc = path.join(packageDir, 'docs/WORKFLOW.md');
-  if (copyFile(workflowSrc, 'docs/WORKFLOW.md')) {
-    console.log('  Created: docs/WORKFLOW.md');
-  }
-
-  // Copy research TEMPLATE.md
-  const templateSrc = path.join(packageDir, 'docs/research/TEMPLATE.md');
-  if (copyFile(templateSrc, 'docs/research/TEMPLATE.md')) {
-    console.log('  Created: docs/research/TEMPLATE.md');
+/**
+ * Creates a directory on first use and prints a one-time purpose note.
+ * @param {string} dir - Absolute path to the directory to create.
+ * @param {string} purpose - Human-readable purpose description.
+ * @returns {string|null} Purpose message if created, null if already existed.
+ */
+function ensureDirWithNote(dir, purpose) {
+  if (fs.existsSync(dir)) {
+    return null;
   }
+  fs.mkdirSync(dir, { recursive: true });
+  const display = dir.replace(/\\/g, '/');
+  const msg = `Created ${display} for ${purpose}`;
+  console.log(`  ${msg}`);
+  return msg;
+}
 
-  // Create PROGRESS.md if not exists
-  const progressPath = path.join(projectRoot, 'docs/planning/PROGRESS.md');
-  if (!fs.existsSync(progressPath)) {
-    writeFile('docs/planning/PROGRESS.md', `# Project Progress
-
-## Current Focus
-<!-- What you're working on -->
-
-## Completed
-<!-- Completed features -->
-
-## Upcoming
-<!-- Next priorities -->
-`);
-    console.log('  Created: docs/planning/PROGRESS.md');
-  }
+// Setup core documentation and directories
+function setupCoreDocs() {
+  // docs/planning/ and docs/research/ are created lazily on first use
+  // by /plan Phase 1 and Phase 2 respectively, via ensureDirWithNote().
+  // TEMPLATE.md and PROGRESS.md are also deferred to first use.
 }
 
 // Minimal installation (postinstall)
@@ -1881,11 +1887,13 @@ function setupClaudeAgent(skipFiles = {}) {
   if (skipFiles.claudeCommands) {
     console.log('  Skipped: .claude/commands/ (keeping existing)');
   } else {
-    COMMANDS.forEach(cmd => {
+    const cmds = getWorkflowCommands();
+    let copied = 0;
+    cmds.forEach(cmd => {
       const src = path.join(packageDir, `.claude/commands/${cmd}.md`);
-      copyFile(src, `.claude/commands/${cmd}.md`);
+      if (copyFile(src, `.claude/commands/${cmd}.md`)) copied++;
     });
-    console.log('  Copied: 9 workflow commands');
+    console.log(`  Copied: ${copied} workflow commands`);
   }
 
   // Copy rules
@@ -1930,7 +1938,7 @@ function copyAgentCommands(agent, claudeCommands) {
     const targetDir = agent.dirs[0]; // First dir is commands/workflows
     writeFile(`${targetDir}/${targetFile}`, targetContent);
   });
-  console.log('  Converted: 9 workflow commands');
+  console.log(`  Converted: ${Object.keys(claudeCommands).length} workflow commands`);
 }
 
 // Helper: Copy rules for agent
@@ -2052,7 +2060,6 @@ function displayInstallationStatus(projectStatus) {
   if (projectStatus.hasAgentsMd) console.log('  - AGENTS.md');
   if (projectStatus.hasClaudeCommands) console.log('  - .claude/commands/');
   if (projectStatus.hasEnvLocal) console.log('  - .env.local');
-  if (projectStatus.hasDocsWorkflow) console.log('  - docs/WORKFLOW.md');
   console.log('');
 }
 
@@ -2302,7 +2309,7 @@ function loadClaudeCommands(selectedAgents) {
     return claudeCommands;
   }
 
-  COMMANDS.forEach(cmd => {
+  getWorkflowCommands().forEach(cmd => {
     const cmdPath = path.join(projectRoot, `.claude/commands/${cmd}.md`);
     const content = readFile(cmdPath);
     if (content) {
@@ -2332,17 +2339,15 @@ function displaySetupSummary(selectedAgents) {
   console.log('');
   console.log('What\'s installed:');
   console.log('  - AGENTS.md (universal instructions)');
-  console.log('  - docs/WORKFLOW.md (full workflow guide)');
-  console.log('  - docs/research/TEMPLATE.md (research template)');
-  console.log('  - docs/planning/PROGRESS.md (progress tracking)');
 
+  const workflowCount = getWorkflowCommands().length;
   selectedAgents.forEach(key => {
     const agent = AGENTS[key];
     if (agent.linkFile) {
       console.log(`  - ${agent.linkFile} (${agent.name})`);
     }
     if (agent.hasCommands) {
-      console.log(`  - .claude/commands/ (9 workflow commands)`);
+      console.log(`  - .claude/commands/ (${workflowCount} workflow commands)`);
     }
     if (agent.hasSkill) {
       const skillDir = agent.dirs.find(d => d.includes('/skills/'));
@@ -2521,11 +2526,15 @@ function parseFlags() {
     agents: null,
     all: false,
     help: false,
+    version: false,
     path: null,
     merge: null,     // 'smart'|'preserve'|'replace'
     type: null,      // 'critical'|'standard'|'simple'|'hotfix'|'docs'|'refactor'
     interview: false, // Force context interview
     budget: null,     // Budget mode for recommend command
+    yes: false,       // Non-interactive mode (skip prompts, use defaults)
+    force: false,     // Force overwrite even if content is identical
+    verbose: false,   // Show file-by-file detail in setup summary
   };
 
   for (let i = 0; i < args.length;) {
@@ -2543,6 +2552,9 @@ function parseFlags() {
     } else if (arg === '--help' || arg === '-h') {
       flags.help = true;
       i++;
+    } else if (arg === '--version' || arg === '-V') {
+      flags.version = true;
+      i++;
     } else if (arg === '--path' || arg === '-p' || arg.startsWith('--path=')) {
       const result = parsePathFlag(args, i);
       flags.path = result.value;
@@ -2559,6 +2571,15 @@ function parseFlags() {
       const result = parseTypeFlag(args, i);
       flags.type = result.value;
       i = result.nextIndex;
+    } else if (arg === '--yes' || arg === '-y') {
+      flags.yes = true;
+      i++;
+    } else if (arg === '--force') {
+      flags.force = true;
+      i++;
+    } else if (arg === '--verbose') {
+      flags.verbose = true;
+      i++;
     } else if (arg === '--interview') {
       flags.interview = true;
       i++;
@@ -2697,7 +2718,7 @@ function showHelp() {
   console.log('Usage:');
   console.log('  npx forge setup [options]     Interactive agent configuration');
   console.log('  npx forge recommend           Show recommended tools for your project');
-  console.log('  npx forge                     Minimal install (AGENTS.md + docs)');
+  console.log('  npx forge --version              Show version');
   console.log('');
   console.log('Options:');
   console.log('  --path, -p <dir>     Target project directory (default: current directory)');
@@ -2716,6 +2737,9 @@ function showHelp() {
   console.log('                       Options: critical, standard, simple, hotfix, docs, refactor');
   console.log('  --interview          Force context interview (gather project information)');
   console.log('  --budget <mode>      Budget mode for recommend (free, open-source, startup, professional, custom)');
+  console.log('  --yes, -y            Non-interactive setup with sensible defaults');
+  console.log('                       Defaults to claude agent, skips prompts');
+  console.log('  --version, -V        Show version');
   console.log('  --help, -h           Show this help message');
   console.log('');
   console.log('Available agents:');
@@ -2733,6 +2757,8 @@ function showHelp() {
   console.log('  npx forge setup --agents=claude,cursor   # Same, different syntax');
   console.log('  npx forge setup --skip-external          # No service configuration');
   console.log('  npx forge setup --agents claude --quick  # Quick + specific agent');
+  console.log('  npx forge setup --yes                    # Non-interactive, defaults to claude');
+  console.log('  npx forge setup --yes --agents cursor   # Non-interactive, specific agent');
   console.log('  npx forge setup --all --skip-external    # All agents, no services');
   console.log('  npx forge setup --merge=smart            # Use intelligent merge for existing files');
   console.log('  npx forge setup --type=critical          # Set workflow profile manually');
@@ -3314,11 +3340,9 @@ async function quickSetup(selectedAgents, skipExternal) {
   checkPrerequisites();
   console.log('');
 
-  // Copy AGENTS.md
+  // Copy AGENTS.md (actionLog tracks it via copyFile)
   const agentsSrc = path.join(packageDir, 'AGENTS.md');
-  if (copyFile(agentsSrc, 'AGENTS.md')) {
-    console.log('  Created: AGENTS.md (universal standard)');
-  }
+  copyFile(agentsSrc, 'AGENTS.md');
   console.log('');
 
   // Setup core documentation
@@ -3342,17 +3366,9 @@ async function quickSetup(selectedAgents, skipExternal) {
   // Configure external services with defaults (unless skipped)
   configureDefaultExternalServices(skipExternal);
 
-  // Final summary
-  console.log('');
-  console.log('==============================================');
-  console.log(`  Forge v${VERSION} Quick Setup Complete!`);
-  console.log('==============================================');
-  console.log('');
-  console.log('Next steps:');
-  console.log('  1. Start with: /status');
-  console.log('  2. Read the guide: docs/WORKFLOW.md');
+  // Progressive setup summary
   console.log('');
-  console.log('Happy shipping!');
+  console.log(renderSetupSummary(actionLog, selectedAgents, VERBOSE_MODE));
   console.log('');
 }
 
@@ -3460,7 +3476,6 @@ function displayExistingInstallation(projectStatus) {
   if (projectStatus.hasAgentsMd) console.log('  - AGENTS.md');
   if (projectStatus.hasClaudeCommands) console.log('  - .claude/commands/');
   if (projectStatus.hasEnvLocal) console.log('  - .env.local');
-  if (projectStatus.hasDocsWorkflow) console.log('  - docs/WORKFLOW.md');
   console.log('');
 }
 
@@ -3506,7 +3521,7 @@ function loadAndSetupClaudeCommands(selectedAgents, skipFiles) {
   }
 
   // Then load the commands (from existing or newly created)
-  COMMANDS.forEach(cmd => {
+  getWorkflowCommands().forEach(cmd => {
     const cmdPath = path.join(projectRoot, `.claude/commands/${cmd}.md`);
     const content = readFile(cmdPath);
     if (content) {
@@ -3600,6 +3615,15 @@ async function interactiveSetupWithFlags(flags) {
   // Prompt for overwrite decisions
   const skipFiles = await promptForOverwriteDecisions(question, projectStatus);
 
+  // Agent auto-detection (suggests but does not force)
+  const envDetection = detectEnvironment(projectRoot);
+  if (envDetection.activeAgent && envDetection.confidence === 'high') {
+    console.log(`  Detected: ${envDetection.activeAgent} (${envDetection.activeAgentSource})`);
+  }
+  if (envDetection.configuredAgents.length > 0) {
+    console.log(`  Previously configured: ${envDetection.configuredAgents.join(', ')}`);
+  }
+
   // STEP 1: Agent Selection (delegated to helper)
   const agentKeys = Object.keys(AGENTS);
   const selectedAgents = await promptForAgentSelection(question, agentKeys);
@@ -3686,8 +3710,10 @@ function determineSelectedAgents(flags) {
   return [];
 }
 
-// Helper: Handle setup command in non-quick mode
-async function handleSetupCommand(selectedAgents, flags) {
+// Shared setup executor — used by handleSetupCommand
+async function executeSetup(config) {
+  const { agents, skipExternal } = config;
+
   showBanner('Installing for specified agents...');
   console.log('');
 
@@ -3695,10 +3721,13 @@ async function handleSetupCommand(selectedAgents, flags) {
   checkPrerequisites();
   console.log('');
 
-  // Copy AGENTS.md
-  const agentsSrc = path.join(packageDir, 'AGENTS.md');
-  if (copyFile(agentsSrc, 'AGENTS.md')) {
-    console.log('  Created: AGENTS.md (universal standard)');
+  // Copy AGENTS.md (only if not exists — preserve user customizations; actionLog tracks it)
+  const agentsDest = path.join(projectRoot, 'AGENTS.md');
+  if (fs.existsSync(agentsDest)) {
+    actionLog.add('AGENTS.md', 'skipped', 'already exists');
+  } else {
+    const agentsSrc = path.join(packageDir, 'AGENTS.md');
+    copyFile(agentsSrc, 'AGENTS.md');
   }
   console.log('');
 
@@ -3706,28 +3735,35 @@ async function handleSetupCommand(selectedAgents, flags) {
   setupCoreDocs();
   console.log('');
 
-  // Load Claude commands if needed
-  const claudeCommands = loadClaudeCommands(selectedAgents);
+  // Load Claude commands — use loadAndSetupClaudeCommands when claude is selected
+  // so that .claude/commands/ are seeded before reading them
+  const claudeCommands = agents.includes('claude')
+    ? loadAndSetupClaudeCommands(agents)
+    : loadClaudeCommands(agents);
 
-  // Setup agents
-  selectedAgents.forEach(agentKey => {
-    if (agentKey !== 'claude') {
-      setupAgent(agentKey, claudeCommands);
-    }
-  });
-
-  console.log('');
-  console.log('Agent configuration complete!');
+  // Setup agents with progress output (setupSelectedAgents skips claude internally
+  // since loadAndSetupClaudeCommands already handled it above)
+  setupSelectedAgents(agents, claudeCommands);
 
   // Install git hooks for TDD enforcement
   console.log('');
   installGitHooks();
 
   // External services (unless skipped)
-  await handleExternalServices(flags.skipExternal, selectedAgents);
+  await handleExternalServices(skipExternal, agents);
 
+  // Progressive setup summary
+  console.log('');
+  console.log(renderSetupSummary(actionLog, agents, VERBOSE_MODE));
   console.log('');
-  console.log('Done! Get started with: /status');
+}
+
+// Helper: Handle setup command in non-quick mode
+async function handleSetupCommand(selectedAgents, flags) {
+  await executeSetup({
+    agents: selectedAgents,
+    skipExternal: flags.skipExternal,
+  });
 }
 
 // Helper: Handle external services configuration
@@ -3761,33 +3797,66 @@ async function main() {
   const command = args[0];
   const flags = parseFlags();
 
+  // Wire up incremental setup state from parsed flags
+  FORCE_MODE = flags.force;
+  VERBOSE_MODE = flags.verbose;
+  actionLog = new SetupActionLog();
+
   // Show help
   if (flags.help) {
     showHelp();
     return;
   }
 
+  // Show version
+  if (flags.version) {
+    console.log(`Forge v${VERSION}`);
+    return;
+  }
+
   // Handle --path option: change to target directory
   if (flags.path) {
     // Update projectRoot after changing directory to maintain state consistency
     projectRoot = handlePathSetup(flags.path);
   }
 
+  // First-run detection: check if Forge is configured in this project
+  // Skip for: setup (needs to run to configure), recommend (read-only)
+  // Note: help and version already returned above, so no need to check here
+  if (command !== 'setup' && command !== 'recommend') {
+    const agentsMdPath = path.join(projectRoot, 'AGENTS.md');
+    if (!fs.existsSync(agentsMdPath)) {
+      console.error('[FORGE_SETUP_REQUIRED] Forge is not configured in this project.\n');
+      console.error('  Run:  npx forge setup');
+      console.error('  Or:   npx forge setup --yes  (non-interactive)\n');
+      process.exit(1);
+    }
+  }
+
   if (command === 'setup') {
     // Determine agents to install
     let selectedAgents = determineSelectedAgents(flags);
 
+    // Non-interactive mode: --yes defaults to claude agent, skips prompts
+    // Applied before --quick so --quick --yes works correctly
+    if (flags.yes && selectedAgents.length === 0) {
+      selectedAgents = ['claude'];
+    }
+    if (flags.yes) {
+      flags.skipExternal = true;
+    }
+
     // Quick mode
     if (flags.quick) {
-      // If no agents specified in quick mode, use all
-      if (selectedAgents.length === 0) {
+      // If no explicit agents specified, use all (--yes default doesn't count)
+      if (selectedAgents.length === 0 || (flags.yes && !flags.agents)) {
         selectedAgents = Object.keys(AGENTS);
       }
       await quickSetup(selectedAgents, flags.skipExternal);
       return;
     }
 
-    // Agents specified via flag (non-quick mode)
+    // Agents specified via flag or --yes default (non-quick mode)
     if (selectedAgents.length > 0) {
       await handleSetupCommand(selectedAgents, flags);
       return;
@@ -4230,3 +4299,5 @@ if (require.main === module) {
     }
   })();
 }
+
+module.exports = { getWorkflowCommands, ensureDirWithNote };

package/docs/AGENT_INSTALL_PROMPT.md

@@ -201,7 +201,7 @@ Summarize what was completed for the user:
 - `/plan <feature-slug>` - Design + research + implementation plan
 - `/dev` - Start TDD development
 
-**Need help?** Check docs/WORKFLOW.md for full guide
+**Need help?** Check AGENTS.md for full guide
 ```
 
 ---