@sugar-crash-studios/vibe-forge 0.4.0

package/.claude/hooks/worker-loop.js

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+/**
+ * Vibe Forge Worker Loop - Stop Hook (Cross-Platform)
+ *
+ * Implements the Ralph Loop technique for Vibe Forge workers.
+ * When a worker tries to exit, this hook checks if there are pending tasks
+ * and feeds the worker prompt back to continue working.
+ *
+ * Based on the Ralph Loop plugin by Anthropic.
+ *
+ * Activation modes:
+ * 1. Config-based: worker_loop_enabled=true in .forge/config.json
+ * 2. Runtime: State file created by /worker-loop command
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// State file location (runtime toggle)
+const claudeLocalDir = process.env.CLAUDE_LOCAL_DIR || path.join(os.homedir(), '.claude');
+const stateFile = path.join(claudeLocalDir, 'forge-worker-loop.json');
+const forgeRoot = process.env.FORGE_ROOT || process.cwd();
+
+// Helper to safely parse JSON
+function safeJsonParse(filePath, defaultValue = {}) {
+  try {
+    if (fs.existsSync(filePath)) {
+      return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    }
+  } catch (e) {
+    // Ignore parse errors
+  }
+  return defaultValue;
+}
+
+// Helper to count matching files
+function countFiles(dir, pattern = '*.md') {
+  try {
+    if (!fs.existsSync(dir)) return 0;
+    const files = fs.readdirSync(dir);
+    return files.filter(f => f.endsWith('.md')).length;
+  } catch (e) {
+    return 0;
+  }
+}
+
+// Helper to count files with specific content
+function countFilesWithContent(dir, searchPattern) {
+  try {
+    if (!fs.existsSync(dir)) return 0;
+    const files = fs.readdirSync(dir).filter(f => f.endsWith('.md'));
+    let count = 0;
+    for (const file of files) {
+      try {
+        const content = fs.readFileSync(path.join(dir, file), 'utf8');
+        if (content.includes(searchPattern)) {
+          count++;
+        }
+      } catch (e) {
+        // Skip files we can't read
+      }
+    }
+    return count;
+  } catch (e) {
+    return 0;
+  }
+}
+
+// Output result and exit
+function output(result) {
+  console.log(JSON.stringify(result));
+  process.exit(0);
+}
+
+// Main logic
+function main() {
+  let loopActive = false;
+  let workerAgent = '';
+  let maxIdleChecks = 10;
+  let idleCount = 0;
+  let pollInterval = 5;
+
+  // Check for runtime state file first (takes precedence)
+  if (fs.existsSync(stateFile)) {
+    const state = safeJsonParse(stateFile);
+    loopActive = true;
+    workerAgent = state.agent || '';
+    maxIdleChecks = state.max_idle_checks || 10;
+    idleCount = state.idle_count || 0;
+    pollInterval = state.poll_interval || 5;
+  }
+
+  // If no runtime state, check config-based setting
+  if (!loopActive) {
+    const configFile = path.join(forgeRoot, '.forge', 'config.json');
+    const config = safeJsonParse(configFile);
+    if (config.worker_loop_enabled === true) {
+      loopActive = true;
+      workerAgent = 'any';
+    }
+  }
+
+  // Check if worker loop is active
+  if (!loopActive) {
+    return output({ decision: 'approve' });
+  }
+
+  if (!workerAgent) {
+    // Invalid state, clean up and allow exit
+    try { fs.unlinkSync(stateFile); } catch (e) {}
+    return output({ decision: 'approve' });
+  }
+
+  // Determine tasks directory location
+  // When running from vibe-forge repo: tasks are at ./tasks/
+  // When running from a project using vibe-forge as submodule: tasks are at ./_vibe-forge/tasks/
+  let tasksDir = path.join(forgeRoot, 'tasks');
+  if (!fs.existsSync(tasksDir)) {
+    // Fall back to submodule location
+    tasksDir = path.join(forgeRoot, '_vibe-forge', 'tasks');
+  }
+
+  // Check for pending tasks
+  let pendingCount = 0;
+  let needsChangesCount = 0;
+
+  const pendingDir = path.join(tasksDir, 'pending');
+  const needsChangesDir = path.join(tasksDir, 'needs-changes');
+
+  if (workerAgent === 'any') {
+    // Config mode: count all tasks
+    pendingCount = countFiles(pendingDir);
+    needsChangesCount = countFiles(needsChangesDir);
+  } else {
+    // Runtime mode: count only tasks assigned to specific worker
+    const searchPattern = `assigned_to: ${workerAgent}`;
+    pendingCount = countFilesWithContent(pendingDir, searchPattern);
+    needsChangesCount = countFilesWithContent(needsChangesDir, searchPattern);
+  }
+
+  const totalTasks = pendingCount + needsChangesCount;
+
+  // Get relative task path for prompts (relative to forgeRoot)
+  const relativeTasksPath = path.relative(forgeRoot, tasksDir);
+
+  if (totalTasks > 0) {
+    // Tasks found! Reset idle counter and continue
+    if (fs.existsSync(stateFile)) {
+      try {
+        const state = safeJsonParse(stateFile);
+        state.idle_count = 0;
+        fs.writeFileSync(stateFile, JSON.stringify(state, null, 2));
+      } catch (e) {}
+    }
+
+    return output({
+      decision: 'block',
+      message: `[Forge Loop] Found ${totalTasks} pending task(s). Continuing work...`,
+      prompt: `Check ${relativeTasksPath}/pending/ and ${relativeTasksPath}/needs-changes/ for tasks assigned to you and begin working on them immediately.`
+    });
+  }
+
+  // No tasks - handle idle state
+  if (fs.existsSync(stateFile)) {
+    idleCount++;
+
+    try {
+      const state = safeJsonParse(stateFile);
+      state.idle_count = idleCount;
+      fs.writeFileSync(stateFile, JSON.stringify(state, null, 2));
+    } catch (e) {}
+
+    if (idleCount >= maxIdleChecks) {
+      // Max idle checks reached, clean up and allow exit
+      try { fs.unlinkSync(stateFile); } catch (e) {}
+      return output({
+        decision: 'approve',
+        message: `[Forge Loop] No tasks found after ${maxIdleChecks} checks. Exiting.`
+      });
+    }
+
+    // Still within idle limit - wait and check again
+    return output({
+      decision: 'block',
+      message: `[Forge Loop] No tasks available. Idle check ${idleCount}/${maxIdleChecks}. Waiting...`,
+      prompt: `No tasks currently assigned to you. Wait briefly, then check ${relativeTasksPath}/pending/ and ${relativeTasksPath}/needs-changes/ again for new work. If still no tasks, announce you are idle and ready.`
+    });
+  }
+
+  // Config-based mode - no idle tracking, just allow exit when no tasks
+  return output({
+    decision: 'approve',
+    message: '[Forge Loop] No pending tasks. Worker exiting.'
+  });
+}
+
+main();

package/.claude/scripts/setup-worker-loop.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+#
+# Setup Worker Loop
+# Creates state file to enable the worker loop stop hook
+#
+
+set -euo pipefail
+
+AGENT="${1:-}"
+MAX_IDLE="${2:-10}"
+STATE_DIR="${CLAUDE_LOCAL_DIR:-$HOME/.claude}"
+STATE_FILE="$STATE_DIR/forge-worker-loop.json"
+
+if [[ "$AGENT" == "stop" ]]; then
+    if [[ -f "$STATE_FILE" ]]; then
+        rm -f "$STATE_FILE"
+        echo "Worker loop stopped."
+    else
+        echo "No active worker loop."
+    fi
+    exit 0
+fi
+
+if [[ -z "$AGENT" ]]; then
+    echo "Usage: setup-worker-loop.sh <agent> [max-idle-checks]"
+    echo "       setup-worker-loop.sh stop"
+    exit 1
+fi
+
+# Ensure state directory exists
+mkdir -p "$STATE_DIR"
+
+# Create state file
+cat > "$STATE_FILE" << EOF
+{
+  "agent": "$AGENT",
+  "max_idle_checks": $MAX_IDLE,
+  "idle_count": 0,
+  "poll_interval": 5,
+  "started_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+}
+EOF
+
+echo "Worker loop started for $AGENT (max idle: $MAX_IDLE checks)"
+echo "State file: $STATE_FILE"

package/.claude/settings.local.json

@@ -0,0 +1,46 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(ls:*)",
+      "Bash(git pull:*)",
+      "Bash(npm view:*)",
+      "Bash(gh run list:*)",
+      "Bash(gh run view:*)",
+      "Bash(gh secret list:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(gh workflow run:*)",
+      "Bash(gh repo view:*)",
+      "Bash(git push:*)",
+      "Bash(sqlite3:*)",
+      "Bash(npm test)",
+      "Bash(git rm:*)",
+      "Bash(git checkout:*)",
+      "Bash(git switch:*)"
+    ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node G:/dev/vibe-forge/bin/lib/heimdall.js"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node G:/dev/vibe-forge/.claude/hooks/worker-loop.js"
+          }
+        ]
+      }
+    ]
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SpasticPalate
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,238 @@
+# Vibe Forge ⚒️
+
+A multi-agent development orchestration system for terminal-native vibe coding.
+
+## Vision
+
+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, coordinated through a file-based task system.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         PLANNING HUB                            │
+│                  (Your main terminal session)                   │
+│                                                                 │
+│   You + Architect · Aegis · Ember · Pixel · Oracle              │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                        FORGE MASTER ⚒️                          │
+│              Task Distribution & Orchestration                  │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+         ┌────────────┬───────┴───────┬────────────┐
+         ▼            ▼               ▼            ▼
+    ┌─────────┐  ┌─────────┐    ┌─────────┐  ┌─────────┐
+    │ Anvil   │  │ Furnace │    │Crucible │  │Sentinel │
+    │   🔨    │  │   🔥   │    │   🧪    │  │   🛡️   │
+    │Frontend │  │ Backend │    │ Testing │  │ Review  │
+    └─────────┘  └─────────┘    └─────────┘  └─────────┘
+```
+
+## Key Features
+
+- **Personality-driven agents** - Each agent has a distinct voice, expertise, and decision-making style
+- **File-based task coordination** - Reliable, debuggable, no WebSocket complexity
+- **Token-efficient design** - Context stored locally, minimal wire traffic
+- **Terminal-native** - Built for Windows Terminal, works with any terminal supporting tabs
+
+## Agents
+
+### Core Agents (Always Running)
+
+| Agent | Icon | Role |
+|-------|------|------|
+| Forge Master | ⚒️ | Chief Orchestrator - distributes tasks, tracks progress |
+| Sentinel | 🛡️ | Code Reviewer - quality gates, adversarial review |
+
+### Worker Agents (Per-Task)
+
+| Agent | Icon | Role |
+|-------|------|------|
+| Anvil | 🔨 | Frontend Dev - components, UI, styling |
+| Furnace | 🔥 | Backend Dev - APIs, database, services |
+| Crucible | 🧪 | Tester/QA - tests, bug hunting |
+| Scribe | 📜 | Documentation - docs, README, API specs |
+| Herald | 📯 | Release Manager - versioning, deployment |
+
+### Planning Hub Voices (Your Terminal)
+
+The Planning Hub is a **multi-voice planning session** — not separate agents. When you run `forge hub`, these expert voices collaborate in a single session:
+
+| Voice | Icon | Expertise |
+|-------|------|-----------|
+| Forge Master | 🔥 | Orchestration & task coordination |
+| Architect | 🏛️ | Technical design & architecture |
+| Aegis | 🔒 | Security & risk |
+| Ember | ⚙️ | DevOps & infrastructure |
+| Pixel | 🎨 | User experience & design |
+| Oracle | 📊 | Requirements & scope |
+| Crucible | 🧪 | Quality & edge cases |
+
+### Specialists (On-Demand)
+
+| Agent | Icon | Role |
+|-------|------|------|
+| Architect | 🏛️ | System Architect |
+| Ember | ⚙️ | DevOps/Infrastructure |
+| Aegis | 🔒 | Security Specialist |
+
+## Project Structure
+
+```
+vibe-forge/
+├── agents/                    # Agent definitions
+│   ├── forge-master/
+│   │   ├── personality.md     # Identity, voice, principles
+│   │   ├── capabilities.md    # Commands, tools, decisions
+│   │   └── context-template.md # Session startup context
+│   ├── sentinel/
+│   ├── anvil/
+│   ├── furnace/
+│   ├── crucible/
+│   └── ...
+├── tasks/                     # Task lifecycle folders
+│   ├── pending/               # New tasks waiting for pickup
+│   ├── in-progress/           # Currently being worked on
+│   ├── completed/             # Done, ready for review
+│   ├── review/                # Under Sentinel review
+│   ├── approved/              # Passed review
+│   ├── needs-changes/         # Review feedback to address
+│   └── merged/                # Archive
+├── specs/                     # Planning documents
+│   ├── epics/
+│   └── stories/
+├── context/                   # Shared context files
+│   ├── project-context.md     # Tech stack, patterns, rules
+│   └── forge-state.yaml       # Current forge status
+└── config/                    # Configuration
+    ├── agents.json            # Agent roster (source of truth)
+    ├── agent-manifest.yaml    # Agent documentation (non-normative)
+    ├── task-template.md       # Task file template
+    └── task-types.yaml        # Task routing rules
+```
+
+## Task Lifecycle
+
+```
+┌─────────┐    ┌─────────────┐    ┌───────────┐    ┌────────┐
+│ pending │ -> │ in-progress │ -> │ completed │ -> │ review │
+└─────────┘    └─────────────┘    └───────────┘    └────────┘
+                                                        │
+                     ┌──────────────┐                   │
+                     │ needs-changes│ <────────────────┤
+                     └──────────────┘                   │
+                            │                          │
+                            ▼                          ▼
+                     ┌─────────────┐             ┌──────────┐
+                     │ in-progress │             │ approved │
+                     └─────────────┘             └──────────┘
+                                                       │
+                                                       ▼
+                                                 ┌─────────┐
+                                                 │ merged  │
+                                                 └─────────┘
+```
+
+## Getting Started
+
+### Prerequisites
+
+- Claude Code CLI ([install](https://claude.ai/download))
+- Windows Terminal (recommended) or any terminal with tabs
+- Node.js 16+ (for npx installer)
+- Git
+
+### Quick Start
+
+```bash
+# In your project directory
+npx vibe-forge init
+```
+
+This will:
+
+1. Clone Vibe Forge into `_vibe-forge/`
+2. Detect your platform and terminal
+3. Set up the daemon and configuration
+4. Create a project context file
+
+Then start the Planning Hub:
+
+```bash
+cd _vibe-forge
+./bin/forge.sh
+```
+
+### Manual Setup
+
+If you prefer not to use npx:
+
+```bash
+# Clone into your project
+git clone https://github.com/SpasticPalate/vibe-forge.git _vibe-forge
+
+# Run setup
+cd _vibe-forge
+./bin/forge-setup.sh
+
+# Start the Planning Hub
+./bin/forge.sh
+```
+
+### Updating
+
+```bash
+npx vibe-forge update
+```
+
+## Slash Commands
+
+When using Claude Code inside your project, use the `/forge` command:
+
+```
+/forge                  - Start the Planning Hub (default)
+/forge status           - Show status dashboard
+/forge spawn <agent>    - Spawn worker in new terminal
+/forge task [desc]      - Create a new task
+/forge help             - Show available commands
+```
+
+Agents (with aliases):
+
+| Agent | Aliases | Role |
+|-------|---------|------|
+| anvil | frontend, ui, fe | Frontend Developer |
+| furnace | backend, api, be | Backend Developer |
+| crucible | test, testing, qa | Tester / QA |
+| sentinel | review, reviewer, cr | Code Reviewer |
+| scribe | docs, documentation | Documentation |
+| herald | release, deploy | Release Manager |
+| ember | devops, ops, infra | DevOps |
+| aegis | security, sec, appsec | Security |
+
+Use either the forge name or any alias: `/forge spawn frontend` or `/forge spawn anvil`
+
+## Token Efficiency
+
+Vibe Forge is designed for minimal token usage:
+
+1. **Local context** - Agents read from files, not conversation history
+2. **Task files as truth** - Instructions in files, not repeated in chat
+3. **Reference, don't duplicate** - Point to paths, don't paste contents
+4. **Batch updates** - One status report per cycle, not per task
+5. **Exception-based** - Report problems, not smooth operations
+
+## Philosophy
+
+> "A forge is not a factory. Each piece is crafted with intention."
+
+Vibe Forge embraces the craft of software development. Each agent brings expertise and personality to their work. The goal isn't maximum automation - it's maximum collaboration between human and AI.
+
+## Acknowledgments
+
+Inspired by BMAD (Business Model-Agnostic Development) methodology and its multi-agent workflow system.
+
+## License
+
+MIT