forge-workflow 0.0.5 → 0.0.7

package/bin/forge.js

@@ -48,6 +48,12 @@ const VERSION = packageJson.version;
 // Load PluginManager for discoverable agent architecture
 const PluginManager = require('../lib/plugin-manager');
 const { scaffoldGithubBeadsSync } = require('../lib/setup');
+const { copyEssentialDocs } = require('../lib/docs-copy');
+const { listTopics, getTopicContent } = require('../lib/docs-command');
+const { resetSoft, resetHard, reinstall } = require('../lib/reset');
+const { loadCommands, executeCommand } = require('../lib/commands/_registry');
+const { enforceStageEntry } = require('../lib/workflow/enforce-stage');
+const { normalizeStageId } = require('../lib/workflow/stages');
 
 // Load enhanced onboarding modules
 const contextMerge = require(path.join(packageDir, 'lib', 'context-merge'));
@@ -69,8 +75,9 @@ const { renderSetupSummary } = require('../lib/setup-summary-renderer');
 const { smartMergeAgentsMd } = require('../lib/smart-merge');
 const { checkLefthookStatus } = require('../lib/lefthook-check');
 const { detectHusky, migrateHusky } = require('../lib/husky-migration');
-// workflowProfiles is loaded but not currently used in the setup flow
-// const _workflowProfiles = require(path.join(packageDir, 'lib', 'workflow-profiles'));
+// workflowProfiles: module exists and is tested but not yet wired into setup flow
+// Will be activated when workflow profile selection is added to interactive setup
+// See: lib/workflow-profiles.js, test/workflow-profiles.test.js
 
 // Get the project root (let allows reassignment after --path flag handling)
 let projectRoot = process.env.INIT_CWD || process.cwd();
@@ -1803,6 +1810,17 @@ 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.
+
+  // Copy essential docs (TOOLCHAIN.md, VALIDATION.md) to consumer's docs/forge/
+  const result = copyEssentialDocs(projectRoot, packageDir);
+  for (const f of result.created) {
+    console.log(`  Created: ${f}`);
+  }
+  for (const f of result.skipped) {
+    if (VERBOSE_MODE) {
+      console.log(`  Skipped: ${f} (already exists)`);
+    }
+  }
 }
 
 // Minimal installation (postinstall)
@@ -2766,6 +2784,15 @@ function showHelp() {
   console.log('Also works with bun:');
   console.log('  bunx forge setup --quick');
   console.log('');
+
+  // Append auto-discovered registry commands
+  const helpRegistry = loadCommands(path.join(__dirname, '..', 'lib', 'commands'));
+  const registryHelp = helpRegistry.getHelp();
+  if (registryHelp) {
+    console.log('Additional commands:');
+    console.log(registryHelp);
+    console.log('');
+  }
 }
 
 // Detect Husky and offer migration to Lefthook
@@ -4029,10 +4056,19 @@ async function handleSyncScaffold() {
 
 // Helper: Handle setup command in non-quick mode
 async function handleSetupCommand(selectedAgents, flags) {
-  await executeSetup({
-    agents: selectedAgents,
-    skipExternal: flags.skipExternal,
-  });
+  // Allow callers (e.g. reinstall) to override projectRoot without process.chdir()
+  const savedRoot = projectRoot;
+  if (flags.projectRoot) {
+    projectRoot = flags.projectRoot;
+  }
+  try {
+    await executeSetup({
+      agents: selectedAgents,
+      skipExternal: flags.skipExternal,
+    });
+  } finally {
+    projectRoot = savedRoot;
+  }
 }
 
 // Helper: Handle external services configuration
@@ -4103,10 +4139,17 @@ async function main() {
     projectRoot = handlePathSetup(flags.path);
   }
 
+  // Load command registry (auto-discovered commands from lib/commands/)
+  const registry = loadCommands(path.join(__dirname, '..', 'lib', 'commands'));
+
   // First-run detection: check if Forge is configured in this project
-  // Skip for: setup (needs to run to configure), recommend (read-only)
+  // Skip for: setup (needs to run), recommend (read-only), docs (read-only),
+  //           postinstall (fresh install), registry commands (handle own requirements)
   // Note: help and version already returned above, so no need to check here
-  if (command !== 'setup' && command !== 'recommend') {
+  if (command !== 'setup' && command !== 'recommend' && command !== 'docs'
+      && command !== 'reset' && command !== 'reinstall'
+      && !registry.commands.has(command)
+      && process.env.npm_lifecycle_event !== 'postinstall') {
     const agentsMdPath = path.join(projectRoot, 'AGENTS.md');
     if (!fs.existsSync(agentsMdPath)) {
       console.error('[FORGE_SETUP_REQUIRED] Forge is not configured in this project.\n');
@@ -4116,6 +4159,53 @@ async function main() {
     }
   }
 
+  // Registry command dispatch — auto-discovered commands take priority
+  if (registry.commands.has(command)) {
+    try {
+      const result = await executeCommand(
+        registry.commands,
+        command,
+        args.slice(1),
+        flags,
+        projectRoot,
+        {
+          enforceStage: (context) => enforceStageEntry({
+            commandName: context.commandName,
+            args: context.args,
+            flags: context.flags,
+            projectRoot: context.projectRoot,
+          }),
+        }
+      );
+      if (result && !result.success) {
+        console.error(result.error || result.message || 'Command failed');
+        process.exit(1);
+      }
+      if (result && typeof result.output === 'string' && result.output.length > 0) {
+        process.stdout.write(result.output.endsWith('\n') ? result.output : `${result.output}\n`);
+      }
+    } catch (err) {
+      console.error(`Error running '${command}':`, err.message);
+      process.exit(1);
+    }
+    return;
+  }
+
+  const stageId = normalizeStageId(command);
+  if (stageId) {
+    try {
+      await enforceStageEntry({
+        commandName: stageId,
+        args: args.slice(1),
+        flags,
+        projectRoot,
+      });
+    } catch (err) {
+      console.error(`Error running '${command}':`, err.message);
+      process.exit(1);
+    }
+  }
+
   if (command === 'setup') {
     // Determine agents to install
     let selectedAgents = determineSelectedAgents(flags);
@@ -4166,11 +4256,123 @@ async function main() {
       return;
     }
     console.log(formatRecommendations(result.recommendations));
+  } else if (command === 'docs') {
+    const topic = args[1];
+    if (!topic) {
+      console.log('');
+      console.log('  Available documentation topics:');
+      console.log('');
+      for (const t of listTopics()) {
+        console.log(`    - ${t}`);
+      }
+      console.log('');
+      console.log('  Usage: forge docs <topic>');
+      console.log('');
+    } else {
+      const result = getTopicContent(topic, packageDir);
+      if (result.error) {
+        console.error(`  Error: ${result.error}`);
+        process.exitCode = 1;
+      } else {
+        console.log(result.content);
+      }
+    }
+  } else if (command === 'reset') {
+    const isSoft = args.includes('--soft');
+    const isHard = args.includes('--hard');
+    const isForce = args.includes('--force');
+
+    if (isSoft && isHard) {
+      console.error('  Error: --soft and --hard are mutually exclusive. Specify one.');
+      process.exitCode = 1;
+    } else if (!isSoft && !isHard) {
+      console.log('');
+      console.log('  Forge Reset');
+      console.log('');
+      console.log('  Usage:');
+      console.log('    forge reset --soft --force    Remove .forge/ config only');
+      console.log('    forge reset --hard --force    Remove ALL forge-managed files');
+      console.log('');
+      console.log('  Flags:');
+      console.log('    --soft     Remove only .forge/ directory (preserves commands, rules, agents)');
+      console.log('    --hard     Remove all forge files (preserves user-created files)');
+      console.log('    --force    Required safety flag to confirm destructive operation');
+      console.log('');
+    } else if (isSoft) {
+      try {
+        const result = resetSoft(projectRoot, { force: isForce });
+        console.log('');
+        console.log('  Soft reset complete.');
+        for (const f of result.removed) {
+          console.log(`    Removed: ${f}`);
+        }
+        console.log('');
+      } catch (error) {
+        console.error(`  Error: ${error.message}`);
+        process.exitCode = 1;
+      }
+    } else if (isHard) {
+      try {
+        const result = resetHard(projectRoot, { force: isForce });
+        console.log('');
+        console.log('  Hard reset complete.');
+        for (const f of result.removed) {
+          console.log(`    Removed: ${f}`);
+        }
+        console.log('');
+      } catch (error) {
+        console.error(`  Error: ${error.message}`);
+        process.exitCode = 1;
+      }
+    }
+  } else if (command === 'reinstall') {
+    const isForce = args.includes('--force');
+    try {
+      const result = await reinstall(projectRoot, {
+        force: isForce,
+        setupFn: async (root) => {
+          // Re-run default setup (claude agent, skip external prompts)
+          const agents = ['claude'];
+          await handleSetupCommand(agents, { skipExternal: true, yes: true, projectRoot: root });
+          return { agents };
+        },
+      });
+      console.log('');
+      console.log('  Reinstall complete.');
+      for (const f of result.resetResult.removed) {
+        console.log(`    Removed: ${f}`);
+      }
+      if (result.setupResult) {
+        console.log('');
+        console.log('  Setup re-run automatically.');
+      }
+      console.log('');
+    } catch (error) {
+      console.error(`  Error: ${error.message}`);
+      process.exitCode = 1;
+    }
   } else if (command === 'rollback') {
     // Execute rollback menu
     await showRollbackMenu();
+  } else if (command === 'team') {
+    const { handleTeam } = require('../lib/commands/team.js');
+    handleTeam(process.argv.slice(3));
+  } else if (process.env.npm_lifecycle_event === 'postinstall') {
+    // Postinstall: show success message only, no file changes
+    // Surprising file modifications during npm/bun install break user expectations
+    // Detect package manager from lock files for accurate setup instruction
+    let runCmd = 'npx';
+    if (fs.existsSync(path.join(projectRoot, 'bun.lockb')) || fs.existsSync(path.join(projectRoot, 'bun.lock'))) runCmd = 'bunx';
+    else if (fs.existsSync(path.join(projectRoot, 'pnpm-lock.yaml'))) runCmd = 'pnpm dlx';
+    else if (fs.existsSync(path.join(projectRoot, 'yarn.lock'))) runCmd = 'yarn dlx';
+    console.log('');
+    console.log('  \u2705 Forge installed successfully!');
+    console.log('');
+    console.log('  To set up in your project:');
+    console.log(`    ${runCmd} forge setup`);
+    console.log('');
   } else {
-    // Default: minimal install (postinstall behavior)
+    // Explicit invocation with no command: run minimal install
     minimalInstall();
   }
 }

package/docs/ENHANCED_ONBOARDING.md

@@ -1,12 +1,12 @@
 # Enhanced Onboarding Guide
 
-Version 1.6.0 introduces intelligent onboarding that adapts to your project and preserves existing content.
+Intelligent onboarding that adapts to your project and preserves existing content.
 
 ---
 
-## What's New in v1.6.0
+## Key Features
 
-### 🎯 Key Features
+### Key Features
 
 1. **Intelligent File Merging** - Preserves your existing AGENTS.md content
 2. **Auto-Detection** - Automatically detects framework, language, and project stage
@@ -35,7 +35,7 @@ bunx forge setup --merge=smart
 - Tech stack details
 
 **What gets updated:**
-- Workflow instructions (9-stage TDD process)
+- Workflow instructions (7-stage TDD process)
 - TDD principles
 - Git conventions
 
@@ -65,9 +65,9 @@ E-commerce platform for selling widgets.
 - 80% test coverage
 
 ## Workflow Configuration
-Use the 9-stage TDD workflow:
-1. /status - Check current context
-2. /research - Research with web search
+Use the 7-stage TDD workflow:
+1. /plan - Design intent, research, branch + worktree + task list
+2. /dev - Subagent-driven TDD per task
 ...
 ```
 
@@ -163,96 +163,117 @@ bunx forge setup --interview
 
 Forge adapts its workflow based on the type of work you're doing.
 
-### Four User-Facing Types
+### Six Change Classifications
 
-#### 1. Feature (Default)
-**Use for:** New functionality, enhancements
+#### 1. Critical (7 stages)
+**Use for:** Security, auth, payments, breaking changes
 
 ```bash
-bunx forge setup --type=feature
-# Or create branch: feat/user-dashboard
+bunx forge setup --type=critical
+# Or create branch: feat/user-authentication
 ```
 
 **Workflow:**
-- Full 9-stage workflow
-- Auto-escalates to **Critical** if keywords detected:
-  - auth, security, payment, crypto, password, token, session, migration, breaking
-
-**Critical Workflow (9 stages):**
 ```
-/status → /research → /plan → /dev → /validate → /ship → /review → /premerge → /verify
+/plan -> /dev -> /validate -> /ship -> /review -> /premerge -> /verify
 ```
 
-**Standard Workflow (6 stages):**
+- Full 7-stage workflow with all gates
+- OWASP analysis required
+- Design docs for strategic changes
+
+#### 2. Standard (6 stages)
+**Use for:** Normal features, enhancements
+
+```bash
+bunx forge setup --type=standard
+# Or create branch: feat/user-dashboard
 ```
-/status → /plan → /dev → /validate → /ship → /premerge
+
+**Workflow:**
+```
+/plan -> /dev -> /validate -> /ship -> /review -> /premerge
 ```
 
-#### 2. Fix
-**Use for:** Bug fixes, corrections
+- Default for most feature work
+- Auto-escalates to **Critical** if keywords detected:
+  - auth, security, payment, crypto, password, token, session, migration, breaking
+
+#### 3. Simple (3 stages)
+**Use for:** Bug fixes, small changes
 
 ```bash
-bunx forge setup --type=fix
+bunx forge setup --type=simple
 # Or create branch: fix/login-validation
 ```
 
 **Workflow:**
-- Streamlined 5-stage workflow
-- Auto-escalates to **Hotfix** if keywords detected:
-  - urgent, production, emergency, hotfix, critical
-
-**Hotfix Workflow (3 stages):**
 ```
-/dev → /validate → /ship
+/dev -> /validate -> /ship
 ```
 
-**Simple Workflow (4 stages):**
+- Streamlined for quick fixes
+- TDD to reproduce bug, then fix
+
+#### 4. Hotfix (3 stages)
+**Use for:** Production emergencies
+
+```bash
+bunx forge setup --type=hotfix
+# Or create branch: hotfix/payment-crash
 ```
-/dev → /validate → /ship → /premerge
+
+**Workflow:**
+```
+/dev -> /validate -> /ship
 ```
 
-#### 3. Refactor
-**Use for:** Code cleanup, optimization
+- Emergency fast path (immediate merge)
+- Skip planning and research
+- TDD to reproduce, then fix
+
+#### 5. Docs (2 stages)
+**Use for:** Documentation only
 
 ```bash
-bunx forge setup --type=refactor
-# Or create branch: refactor/extract-payment-service
+bunx forge setup --type=docs
+# Or create branch: docs/update-readme
 ```
 
-**Workflow (5 stages):**
+**Workflow:**
 ```
-/plan → /dev → /validate → /ship → /premerge
+/verify -> /ship
 ```
 
-- Strict TDD to preserve behavior
-- Optional research for architectural changes
+- Minimal workflow for documentation changes
+- No TDD required
 
-#### 4. Chore
-**Use for:** Documentation, dependencies, configuration
+#### 6. Refactor (5 stages)
+**Use for:** Code cleanup, optimization
 
 ```bash
-bunx forge setup --type=chore
-# Or create branch: docs/update-readme
+bunx forge setup --type=refactor
+# Or create branch: refactor/extract-payment-service
 ```
 
-**Workflow (3 stages):**
+**Workflow:**
 ```
-/verify → /ship → /premerge
+/plan -> /dev -> /validate -> /ship -> /premerge
 ```
 
-- Minimal workflow for maintenance tasks
-- Auto-detects if only markdown files changed → uses Docs profile
+- Strict TDD to preserve behavior
+- Planning phase for architectural changes
 
 ### Workflow Mapping
 
-| User Type | Keywords Detected | Internal Profile | Stages |
-|-----------|------------------|------------------|--------|
-| Feature | auth, security, payment | Critical | 9 |
-| Feature | (none) | Standard | 6 |
-| Fix | urgent, production | Hotfix | 3 |
-| Fix | (none) | Simple | 4 |
-| Refactor | (always) | Refactor | 5 |
-| Chore | only .md files | Docs | 3 |
+| Classification | Use Case | Stages | Workflow |
+|----------------|----------|--------|---------|
+| Critical | Security, auth, payments, breaking changes | 7 | plan, dev, validate, ship, review, premerge, verify |
+| Standard | Normal features, enhancements | 6 | plan, dev, validate, ship, review, premerge |
+| Simple | Bug fixes, small changes | 3 | dev, validate, ship |
+| Hotfix | Production emergencies | 3 | dev, validate, ship (immediate merge) |
+| Docs | Documentation only | 2 | verify, ship |
+| Refactor | Code cleanup, optimization | 5 | plan, dev, validate, ship, premerge |
 
 ---
 
@@ -282,9 +303,9 @@ bunx forge setup --merge=smart --type=critical --interview
 --skip-external         Skip external services
 --agents <list>         Specify agents (--agents claude cursor)
 --all                   Install for all agents
---merge <mode>          Merge strategy (v1.6.0)
---type <type>           Workflow profile (v1.6.0)
---interview             Context interview (v1.6.0)
+--merge <mode>          Merge strategy
+--type <type>           Workflow profile
+--interview             Context interview
 --help, -h              Show help
 ```
 
@@ -332,10 +353,9 @@ git checkout -b feat/user-authentication
 
 bunx forge setup --type=critical
 
-# Auto-escalates to Critical profile:
-# - 7-stage workflow
-# - Research required
-# - OWASP analysis
+# Uses Critical profile:
+# - Full 7-stage workflow
+# - OWASP analysis required
 # - Design docs for strategic changes
 ```
 
@@ -350,7 +370,7 @@ bunx forge setup --type=hotfix
 # Uses Hotfix profile:
 # - 3-stage emergency workflow
 # - TDD to reproduce bug
-# - Skip research and planning
+# - Skip planning and research
 # - Fast path to production
 ```
 
@@ -360,29 +380,21 @@ bunx forge setup --type=hotfix
 # Update README
 git checkout -b docs/update-installation-guide
 
-# Forge auto-detects chore → docs profile:
-# - 3-stage minimal workflow
+bunx forge setup --type=docs
+
+# Uses Docs profile:
+# - 2-stage minimal workflow
 # - No TDD required
-# - Just verify, ship, merge
+# - Just verify and ship
 ```
 
 ---
 
 ## Migration Guide
 
-### Upgrading from v1.5.0 to v1.6.0
-
-**No breaking changes!** Enhanced onboarding is backwards compatible.
-
-**What's new:**
-1. Enhanced file merging options
-2. Auto-detection and context storage
-3. Workflow profiles with auto-escalation
+### Upgrading
 
-**What stays the same:**
-- Existing marker-based merge (USER:START/END) still works
-- All CLI flags from v1.5.0 remain functional
-- AGENTS.md format unchanged
+Enhanced onboarding is backwards compatible.
 
 **Recommended steps:**
 ```bash
@@ -507,7 +519,7 @@ Edit `.forge/context.json` to add custom fields:
 Override specific stages:
 
 ```bash
-# Feature workflow but skip research
+# Standard workflow for a feature
 bunx forge setup --type=standard
 
 # Then manually edit AGENTS.md to customize workflow
@@ -552,10 +564,10 @@ When upgrading existing projects:
 ### 3. Set Workflow Type Per Branch
 
 Different branches, different workflows:
-- `feat/auth-*` → critical
-- `feat/ui-*` → standard
-- `fix/*` → simple
-- `docs/*` → chore
+- `feat/auth-*` -> critical
+- `feat/ui-*` -> standard
+- `fix/*` -> simple
+- `docs/*` -> docs
 
 ### 4. Review Context Regularly
 
@@ -597,6 +609,4 @@ Found an issue or have a suggestion?
 
 ---
 
-**Version**: 1.6.0
-**Last Updated**: 2026-02-06
-**Stability**: Stable
+**Last Updated**: 2026-03-24

package/docs/ROADMAP.md

@@ -308,7 +308,7 @@ Each PR follows the Forge workflow:
 
 ### Plan Files
 
-- **Master Plan**: `.claude/plans/*.md` (global, tracked by Claude Code)
+- **Master Plan**: `docs/plans/*.md` (global, tracked by Claude Code)
 - **Roadmap**: `docs/ROADMAP.md` (repository, git-tracked)
 - **Beads Tracking**: `.beads/issues.jsonl` (git-tracked)
 
@@ -347,7 +347,7 @@ Each PR is self-contained and can be rolled back independently:
 
 ## Resources
 
-- **Master Plan**: `.claude/plans/*.md`
+- **Master Plan**: `docs/plans/*.md`
 - **Beads Issues**: `bd list` or `bd show <issue-id>`
 - **Workflow Guide**: [AGENTS.md](../AGENTS.md)
 - **Architecture Docs**: Coming in PR0 - [ARCHITECTURE.md](./ARCHITECTURE.md)

package/docs/TOOLCHAIN.md

@@ -537,6 +537,29 @@ gh issue create --title "..." --body "..."
 
 ---
 
+## Global CLI Tools
+
+### Beads (`bd`) — Minimum Version
+
+**Minimum version**: v0.49.x
+**Check installed version**:
+```bash
+bd --version
+```
+
+**Install / Update**:
+```bash
+# macOS / Linux
+bun add -g @beads/bd
+
+# Windows — use PowerShell installer (npm has EPERM bug)
+irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iex
+```
+
+> **Why v0.49.x?** Earlier versions lack the `bd ready` dependency-aware query, `bd sync --status`, and the dual-database (JSONL + SQLite) architecture that Forge relies on.
+
+---
+
 ## Integration with Forge Stages
 
 | Stage | Tools Used |

package/docs/VALIDATION.md

@@ -124,7 +124,7 @@ Validation Results:
 
 **Checks**:
 - ✓ On feature branch (`feat/*`, `fix/*`, `docs/*`)
-- ✓ Plan file exists (`.claude/plans/*.md`)
+- ✓ Plan file exists (`docs/plans/*.md`)
 - ✓ Research file exists (`docs/research/*.md`)
 - ✓ Test directory exists
 

package/lefthook.yml

@@ -26,14 +26,25 @@ pre-push:
     branch-protection:
       run: node scripts/branch-protection.js
       tags: protection
+      skip:
+        - run: node scripts/check-forge-token.js
 
     # 2. ESLint check (strict mode: blocks on errors and warnings)
     # Uses Node.js script for cross-platform compatibility
     lint:
       run: node scripts/lint.js
       tags: lint
+      skip:
+        - run: node scripts/check-forge-token.js
 
     # 3. Test suite (cross-platform Node.js script detects package manager)
     tests:
       run: node scripts/test.js
       tags: tests
+      skip:
+        - run: node scripts/check-forge-token.js
+
+    # 4. Team sync — push Beads status to GitHub (non-blocking)
+    team-sync:
+      run: bash scripts/forge-team/lib/hooks.sh sync --quiet || true
+      tags: team