vibe-forge 0.8.2 → 0.8.5

package/README.md

@@ -1,211 +1,211 @@
-# Vibe Forge
-
-A multi-agent development orchestration system for terminal-native vibe coding.
-
-## What Is This?
-
-Vibe Forge transforms your terminal into a collaborative AI development environment. Multiple Claude agents, each with distinct personalities and specializations, work together to build software. You talk to a Planning Hub that coordinates the team, then spawn workers into separate terminal tabs to execute in parallel.
-
-```
-                         YOU
-                          |
-                    /forge plan
-                          |
-              +-----------+-----------+
-              |     PLANNING HUB     |
-              |  Oracle  Architect   |
-              |  Aegis   Pixel       |
-              |  Ember   Crucible    |
-              +-----------+-----------+
-                          |
-            /forge spawn <agent>
-                          |
-         +--------+-------+-------+--------+
-         |        |       |       |        |
-       Anvil   Furnace Crucible Temper  Scribe
-        FE       BE      QA    Review   Docs
-```
-
-## Install
-
-```bash
-npx vibe-forge init
-```
-
-This sets up Vibe Forge in your project: detects your platform, configures your terminal, creates project context files, and installs the `/forge` slash command into Claude Code.
-
-**Prerequisites:** [Claude Code CLI](https://claude.ai/download), Node.js 18+, Git
-
-## Quick Start
-
-```bash
-# Start the Planning Hub (multi-expert planning session)
-/forge
-
-# Or jump straight to planning a feature
-/forge plan user authentication
-
-# Spawn a worker agent in a new terminal tab
-/forge spawn anvil
-
-# Check what's happening
-/forge status
-
-# See all commands
-/forge help
-```
-
-## Agents
-
-### Planning Hub (Your Terminal)
-
-When you run `/forge`, a multi-voice planning session starts. These expert voices collaborate to help you scope, design, and decompose work:
-
-| Voice | Icon | Speaks When |
-|-------|------|-------------|
-| Forge Master | :fire: | Tasks, assignments, workflow, coordination |
-| Architect | :classical_building: | Architecture, patterns, tech decisions |
-| Aegis | :shield: | Auth, security, vulnerabilities |
-| Ember | :gear: | DevOps, CI/CD, deployment |
-| Pixel | :art: | UX, user flows, accessibility |
-| Oracle | :bar_chart: | Requirements, scope, priorities |
-| Crucible | :test_tube: | Edge cases, test strategy, quality |
-| Loki | :performing_arts: | Challenges assumptions, lateral thinking |
-
-### Worker Agents (Separate Terminals)
-
-Spawn these into new terminal tabs to execute tasks:
-
-| Agent | Aliases | Role |
-|-------|---------|------|
-| anvil | frontend, ui, fe | Frontend Developer |
-| furnace | backend, api, be | Backend Developer |
-| crucible | test, qa | Tester / QA |
-| scribe | docs, documentation | Documentation |
-| herald | release, deploy | Release Manager |
-| ember | devops, infra | DevOps Engineer |
-
-### Review Agents
-
-| Agent | Aliases | Role |
-|-------|---------|------|
-| temper | review, cr | Code Reviewer (compliance + correctness) |
-| crucible-x | adversarial, cx | Adversarial Reviewer (tries to break it) |
-
-### Specialists
-
-| Agent | Aliases | Role |
-|-------|---------|------|
-| architect | arch, sage | System Architect |
-| aegis | security, sec | Security Specialist |
-| pixel | ux, ui-design | UX Designer |
-| oracle | product, po | Product Owner |
-| loki | brainstorm, contrarian | Assumption Challenger |
-
-### Red Team
-
-| Agent | Aliases | Role |
-|-------|---------|------|
-| slag | redteam, pentest | Red Team Lead |
-| flux | infra-sec, chaos | Infrastructure Security |
-
-## How It Works
-
-### Planning Mode
-
-When you describe a goal, the Hub enters a 4-phase planning flow:
-
-1. **Discovery** - Oracle asks clarifying questions about users, goals, constraints
-2. **Decomposition** - Architect breaks the goal into epics with success metrics
-3. **Tasking** - Forge Master creates stories and tasks, assigns to agents
-4. **Commit** - Epic and task files written to disk, ready for workers
-
-### Task System
-
-Tasks flow through folders on disk. No database required.
-
-```
-pending/ -> in-progress/ -> completed/ -> review/ -> approved/ -> merged/
-                                            |
-                                     needs-changes/ (back to worker)
-```
-
-Workers pick up tasks from `pending/` on startup. Temper reviews completed work. The daemon routes tasks automatically.
-
-### Daemon
-
-An optional background daemon monitors the forge:
-
-```bash
-./bin/forge.sh daemon start    # Start background monitoring
-./bin/forge.sh daemon status   # Check what's happening
-./bin/forge.sh daemon stop     # Stop the daemon
-```
-
-The daemon provides:
-- Task routing between folders
-- Agent status tracking
-- Token budget warnings for long-running agents
-- Dependency resolution (respects `blocked_by` in task files)
-- Attention notifications when agents need help
-
-### Dashboard
-
-A web dashboard at `http://localhost:2800` shows:
-- Task counts and status
-- Agent activity feed
-- Issue detection
-- Real-time updates via WebSocket
-
-### Per-Project Customization
-
-Add agent-specific rules for your project in `context/agent-overrides/`:
-
-```markdown
-<!-- context/agent-overrides/anvil.md -->
-- Use Tailwind CSS, no custom CSS files
-- All components in src/components/ with PascalCase
-- Use shadcn/ui for base components
-```
-
-These rules are injected into the agent's system prompt at spawn time.
-
-## Project Structure
-
-```
-your-project/
-  _vibe-forge/
-    agents/           # Agent personalities (16 agents)
-    bin/              # CLI, daemon, dashboard, spawn scripts
-    config/           # agents.json, task templates
-    context/          # Project context, agent overrides
-    specs/            # Epics and stories
-    tasks/            # Task lifecycle folders
-    docs/             # Security, architecture, agent docs
-```
-
-## Commands Reference
-
-| Command | Description |
-|---------|-------------|
-| `/forge` | Start the Planning Hub |
-| `/forge plan <feature>` | Plan a feature with the full team |
-| `/forge status` | Show status dashboard |
-| `/forge spawn <agent>` | Spawn worker in new terminal |
-| `/forge task [desc]` | Create a new task |
-| `/forge redteam [scope]` | Launch red team engagement |
-| `/forge help` | Show all commands |
-
-## Security
-
-Vibe Forge uses a defense-in-depth permission model:
-
-1. **Allowlist** (`.claude/settings.json`) - Pre-approves safe operations
-2. **Heimdall** (pre-tool hook) - Enforces forge policies (branch protection, naming)
-3. **Claude Code prompts** - Anything not allowlisted still requires approval
-
-See [docs/security.md](docs/security.md) for the full security model.
-
-## License
-
-MIT
+# Vibe Forge
+
+A multi-agent development orchestration system for terminal-native vibe coding.
+
+## What Is This?
+
+Vibe Forge transforms your terminal into a collaborative AI development environment. Multiple Claude agents, each with distinct personalities and specializations, work together to build software. You talk to a Planning Hub that coordinates the team, then spawn workers into separate terminal tabs to execute in parallel.
+
+```
+                         YOU
+                          |
+                    /forge plan
+                          |
+              +-----------+-----------+
+              |     PLANNING HUB     |
+              |  Oracle  Architect   |
+              |  Aegis   Pixel       |
+              |  Ember   Crucible    |
+              +-----------+-----------+
+                          |
+            /forge spawn <agent>
+                          |
+         +--------+-------+-------+--------+
+         |        |       |       |        |
+       Anvil   Furnace Crucible Temper  Scribe
+        FE       BE      QA    Review   Docs
+```
+
+## Install
+
+```bash
+npx vibe-forge init
+```
+
+This sets up Vibe Forge in your project: detects your platform, configures your terminal, creates project context files, and installs the `/forge` slash command into Claude Code.
+
+**Prerequisites:** [Claude Code CLI](https://claude.ai/download), Node.js 18+, Git
+
+## Quick Start
+
+```bash
+# Start the Planning Hub (multi-expert planning session)
+/forge
+
+# Or jump straight to planning a feature
+/forge plan user authentication
+
+# Spawn a worker agent in a new terminal tab
+/forge spawn anvil
+
+# Check what's happening
+/forge status
+
+# See all commands
+/forge help
+```
+
+## Agents
+
+### Planning Hub (Your Terminal)
+
+When you run `/forge`, a multi-voice planning session starts. These expert voices collaborate to help you scope, design, and decompose work:
+
+| Voice | Icon | Speaks When |
+|-------|------|-------------|
+| Forge Master | :fire: | Tasks, assignments, workflow, coordination |
+| Architect | :classical_building: | Architecture, patterns, tech decisions |
+| Aegis | :shield: | Auth, security, vulnerabilities |
+| Ember | :gear: | DevOps, CI/CD, deployment |
+| Pixel | :art: | UX, user flows, accessibility |
+| Oracle | :bar_chart: | Requirements, scope, priorities |
+| Crucible | :test_tube: | Edge cases, test strategy, quality |
+| Loki | :performing_arts: | Challenges assumptions, lateral thinking |
+
+### Worker Agents (Separate Terminals)
+
+Spawn these into new terminal tabs to execute tasks:
+
+| Agent | Aliases | Role |
+|-------|---------|------|
+| anvil | frontend, ui, fe | Frontend Developer |
+| furnace | backend, api, be | Backend Developer |
+| crucible | test, qa | Tester / QA |
+| scribe | docs, documentation | Documentation |
+| herald | release, deploy | Release Manager |
+| ember | devops, infra | DevOps Engineer |
+
+### Review Agents
+
+| Agent | Aliases | Role |
+|-------|---------|------|
+| temper | review, cr | Code Reviewer (compliance + correctness) |
+| crucible-x | adversarial, cx | Adversarial Reviewer (tries to break it) |
+
+### Specialists
+
+| Agent | Aliases | Role |
+|-------|---------|------|
+| architect | arch, sage | System Architect |
+| aegis | security, sec | Security Specialist |
+| pixel | ux, ui-design | UX Designer |
+| oracle | product, po | Product Owner |
+| loki | brainstorm, contrarian | Assumption Challenger |
+
+### Red Team
+
+| Agent | Aliases | Role |
+|-------|---------|------|
+| slag | redteam, pentest | Red Team Lead |
+| flux | infra-sec, chaos | Infrastructure Security |
+
+## How It Works
+
+### Planning Mode
+
+When you describe a goal, the Hub enters a 4-phase planning flow:
+
+1. **Discovery** - Oracle asks clarifying questions about users, goals, constraints
+2. **Decomposition** - Architect breaks the goal into epics with success metrics
+3. **Tasking** - Forge Master creates stories and tasks, assigns to agents
+4. **Commit** - Epic and task files written to disk, ready for workers
+
+### Task System
+
+Tasks flow through folders on disk. No database required.
+
+```
+pending/ -> in-progress/ -> completed/ -> review/ -> approved/ -> merged/
+                                            |
+                                     needs-changes/ (back to worker)
+```
+
+Workers pick up tasks from `pending/` on startup. Temper reviews completed work. The daemon routes tasks automatically.
+
+### Daemon
+
+An optional background daemon monitors the forge:
+
+```bash
+./bin/forge.sh daemon start    # Start background monitoring
+./bin/forge.sh daemon status   # Check what's happening
+./bin/forge.sh daemon stop     # Stop the daemon
+```
+
+The daemon provides:
+- Task routing between folders
+- Agent status tracking
+- Token budget warnings for long-running agents
+- Dependency resolution (respects `blocked_by` in task files)
+- Attention notifications when agents need help
+
+### Dashboard
+
+A web dashboard at `http://localhost:2800` shows:
+- Task counts and status
+- Agent activity feed
+- Issue detection
+- Real-time updates via WebSocket
+
+### Per-Project Customization
+
+Add agent-specific rules for your project in `context/agent-overrides/`:
+
+```markdown
+<!-- context/agent-overrides/anvil.md -->
+- Use Tailwind CSS, no custom CSS files
+- All components in src/components/ with PascalCase
+- Use shadcn/ui for base components
+```
+
+These rules are injected into the agent's system prompt at spawn time.
+
+## Project Structure
+
+```
+your-project/
+  _vibe-forge/
+    agents/           # Agent personalities (16 agents)
+    bin/              # CLI, daemon, dashboard, spawn scripts
+    config/           # agents.json, task templates
+    context/          # Project context, agent overrides
+    specs/            # Epics and stories
+    tasks/            # Task lifecycle folders
+    docs/             # Security, architecture, agent docs
+```
+
+## Commands Reference
+
+| Command | Description |
+|---------|-------------|
+| `/forge` | Start the Planning Hub |
+| `/forge plan <feature>` | Plan a feature with the full team |
+| `/forge status` | Show status dashboard |
+| `/forge spawn <agent>` | Spawn worker in new terminal |
+| `/forge task [desc]` | Create a new task |
+| `/forge redteam [scope]` | Launch red team engagement |
+| `/forge help` | Show all commands |
+
+## Security
+
+Vibe Forge uses a defense-in-depth permission model:
+
+1. **Allowlist** (`.claude/settings.json`) - Pre-approves safe operations
+2. **Heimdall** (pre-tool hook) - Enforces forge policies (branch protection, naming)
+3. **Claude Code prompts** - Anything not allowlisted still requires approval
+
+See [docs/security.md](docs/security.md) for the full security model.
+
+## License
+
+MIT

package/bin/cli.js

@@ -9,7 +9,7 @@
  *   npx vibe-forge --help        Show help
  */
 
-const { execSync, spawn } = require('child_process');
+const { execSync, spawn, spawnSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
@@ -20,6 +20,72 @@ const VERSION = packageJson.version;
 const REPO_URL = 'https://github.com/sugar-crash-studios/vibe-forge.git';
 const FORGE_DIR = '_vibe-forge';
 
+// ---------------------------------------------------------------------------
+// Environment allowlist for child processes.
+//
+// forge-setup.sh runs with full user privileges, so we pass only the minimum
+// env it needs instead of the entire parent environment. This keeps ambient
+// secrets (AWS_*, GITHUB_TOKEN, NPM_TOKEN, OPENAI_API_KEY, ANTHROPIC_API_KEY,
+// DATABASE_URL, STRIPE_*, etc.) from leaking into setup scripts if a user's
+// shell happens to have them set at invocation time.
+// ---------------------------------------------------------------------------
+// Frozen so third parties (or a poisoned import chain) cannot push a secret
+// name onto the allowlist at runtime and leak it into the next buildChildEnv
+// call. The whole point of the allowlist is defense-in-depth, so the exported
+// surface is treated as immutable.
+const ENV_ALLOWLIST = Object.freeze([
+  // POSIX basics
+  'PATH', 'HOME', 'USER', 'LOGNAME', 'SHELL', 'TERM', 'TMPDIR',
+  // Locale
+  'LANG', 'LC_ALL', 'LC_CTYPE', 'LC_MESSAGES',
+  // Windows basics
+  'SYSTEMROOT', 'SYSTEMDRIVE', 'COMSPEC', 'USERPROFILE', 'LOCALAPPDATA',
+  'APPDATA', 'TEMP', 'TMP', 'USERNAME', 'PATHEXT', 'WINDIR',
+  'PROGRAMDATA', 'PROGRAMFILES', 'PROGRAMFILES(X86)', 'PROGRAMW6432',
+  'PROCESSOR_ARCHITECTURE', 'PROCESSOR_IDENTIFIER',
+  // Git Bash / MSYS
+  'MSYSTEM', 'MINGW_PREFIX', 'MINGW_CHOST',
+  // Proxies (needed for git/npm in corporate networks)
+  'HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY', 'ALL_PROXY',
+  'http_proxy', 'https_proxy', 'no_proxy',
+  // TLS CA bundles — consistent partner of the proxy vars above. Corporate
+  // networks with intercepting proxies need these or node/git fail TLS.
+  'NODE_EXTRA_CA_CERTS', 'SSL_CERT_FILE', 'SSL_CERT_DIR',
+  'GIT_SSL_CAINFO', 'GIT_SSL_CAPATH',
+  // Claude Code — setup validates `claude --version`, which needs this on Windows
+  'CLAUDE_CODE_GIT_BASH_PATH',
+]);
+
+function buildChildEnv(ambient, extras = {}) {
+  // Reject non-object extras loudly. String/number/boolean extras silently
+  // spread wrong shapes (e.g. Object.assign({}, 'abc') → {0:'a',1:'b',2:'c'}),
+  // which produces a silently-wrong env instead of a caller-visible error.
+  if (extras !== undefined && extras !== null && (typeof extras !== 'object' || Array.isArray(extras))) {
+    throw new TypeError(`buildChildEnv: extras must be a plain object, got ${typeof extras}`);
+  }
+
+  const source = ambient || {};
+  const env = {};
+  for (const key of ENV_ALLOWLIST) {
+    if (source[key] !== undefined) {
+      env[key] = source[key];
+    }
+  }
+
+  // Merge extras, but treat `undefined` as a no-op rather than overwriting the
+  // allowlisted value with an undefined. The source-side loop deliberately
+  // skips undefined keys; extras should follow the same rule for symmetry.
+  if (extras) {
+    for (const key of Object.keys(extras)) {
+      if (extras[key] !== undefined) {
+        env[key] = extras[key];
+      }
+    }
+  }
+
+  return env;
+}
+
 // Colors for terminal output
 // NOTE: Intentionally duplicated from src/lib/colors.sh
 // This is by design: cli.js runs standalone via npx before the rest of Vibe Forge
@@ -170,10 +236,7 @@ function runBashScript(scriptPath, args = []) {
     const child = spawn(bashPath, [scriptPath, ...args], {
       stdio: 'inherit',
       cwd: process.cwd(),
-      env: {
-        ...process.env,
-        CLAUDE_CODE_GIT_BASH_PATH: bashPath,
-      },
+      env: buildChildEnv(process.env, { CLAUDE_CODE_GIT_BASH_PATH: bashPath }),
     });
 
     child.on('close', (code) => {
@@ -209,18 +272,24 @@ async function initCommand() {
   logSuccess('Prerequisites OK');
   log('');
 
-  // Clone the repository
+  // Clone the repository. Uses spawnSync with an arg array rather than
+  // execSync with a template string so there is no shell-injection surface
+  // if REPO_URL or FORGE_DIR are ever derived from untrusted input.
   logInfo(`Cloning Vibe Forge into ${FORGE_DIR}/...`);
-  try {
-    execSync(`git clone --depth 1 ${REPO_URL} ${FORGE_DIR}`, {
+  const cloneResult = spawnSync(
+    'git',
+    ['clone', '--depth', '1', REPO_URL, FORGE_DIR],
+    {
       stdio: 'inherit',
       cwd: process.cwd(),
-    });
-    logSuccess('Clone complete');
-  } catch {
+      env: buildChildEnv(process.env),
+    }
+  );
+  if (cloneResult.status !== 0) {
     logError('Failed to clone repository');
     process.exit(1);
   }
+  logSuccess('Clone complete');
 
   log('');
 
@@ -247,16 +316,26 @@ function validateAgentsConfig(forgeDir) {
   const checkScript = path.join(forgeDir, 'bin', 'lib', 'check-aliases.js');
   if (!fs.existsSync(checkScript)) return;
 
+  const agentsFile = path.join(forgeDir, 'config', 'agents.json');
+  const result = spawnSync('node', [checkScript, agentsFile], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: buildChildEnv(process.env),
+  });
+
+  if (result.status !== 0) {
+    logError('Agent alias collisions detected in config/agents.json');
+    const stderr = result.stderr ? result.stderr.toString().trim() : '';
+    logInfo(stderr || 'Run node src/lib/check-aliases.js for details');
+    logError('Fix collisions before using Vibe Forge.');
+    process.exit(1);
+  }
+
   try {
-    const agentsFile = path.join(forgeDir, 'config', 'agents.json');
-    execSync(`node "${checkScript}" "${agentsFile}"`, { stdio: 'pipe' });
     const config = JSON.parse(fs.readFileSync(agentsFile, 'utf8'));
     const agentCount = Object.keys(config.agents || {}).length;
     logSuccess(`Agent config valid (${agentCount} agents, no alias collisions)`);
-  } catch (err) {
-    logError('Agent alias collisions detected in config/agents.json');
-    logInfo(err.stderr ? err.stderr.toString().trim() : 'Run node src/lib/check-aliases.js for details');
-    logError('Fix collisions before using Vibe Forge.');
+  } catch {
+    logError('Agent config validation passed, but agents.json could not be parsed.');
     process.exit(1);
   }
 }
@@ -320,21 +399,29 @@ async function updateCommand() {
 
   logInfo('Updating Vibe Forge...');
 
-  try {
-    // Fetch and reset to origin/main - works even without tracking branch
-    execSync('git fetch origin', {
-      stdio: 'inherit',
-      cwd: targetDir,
-    });
-    execSync('git reset --hard origin/main', {
-      stdio: 'inherit',
-      cwd: targetDir,
-    });
-    logSuccess('Update complete');
-  } catch {
+  const childEnv = buildChildEnv(process.env);
+
+  const fetchResult = spawnSync('git', ['fetch', 'origin'], {
+    stdio: 'inherit',
+    cwd: targetDir,
+    env: childEnv,
+  });
+  if (fetchResult.status !== 0) {
     logError('Failed to update. Check your network connection or try deleting _vibe-forge and running init again.');
     process.exit(1);
   }
+
+  const resetResult = spawnSync('git', ['reset', '--hard', 'origin/main'], {
+    stdio: 'inherit',
+    cwd: targetDir,
+    env: childEnv,
+  });
+  if (resetResult.status !== 0) {
+    logError('Failed to update. Check your network connection or try deleting _vibe-forge and running init again.');
+    process.exit(1);
+  }
+
+  logSuccess('Update complete');
 }
 
 // Main entry point
@@ -366,7 +453,14 @@ async function main() {
   }
 }
 
-main().catch((err) => {
-  logError(err.message);
-  process.exit(1);
-});
+if (require.main === module) {
+  main().catch((err) => {
+    logError(err.message);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  buildChildEnv,
+  ENV_ALLOWLIST,
+};