vibe-forge 0.3.5 → 0.3.10

package/.claude/commands/clear-attention.md

@@ -0,0 +1,63 @@
+---
+description: Clear an attention signal after helping a worker
+argument-hint: [agent-name | all]
+---
+
+# Clear Attention Command
+
+Use this command to clear attention signals after you've helped a blocked worker.
+
+## Usage
+
+```
+/clear-attention anvil    # Clear Anvil's attention signal
+/clear-attention all      # Clear all attention signals
+/clear-attention          # List current attention signals
+```
+
+## Implementation
+
+Based on `$ARGUMENTS`:
+
+### If no argument or empty
+
+List all current attention signals from `tasks/attention/`:
+
+```
+🔔 Current Attention Signals:
+
+1. Anvil (5 min ago): Need clarification on auth implementation
+2. Crucible (2 min ago): Tests failing, unsure of expected behavior
+
+Use /clear-attention <agent> to resolve.
+```
+
+### If argument is "all"
+
+Remove all files from `tasks/attention/` and confirm:
+
+```
+✅ Cleared all attention signals (2 resolved)
+```
+
+### If argument is an agent name
+
+1. Find and remove files matching that agent in `tasks/attention/`
+2. Confirm removal:
+
+```
+✅ Cleared attention signal for Anvil
+```
+
+If no matching signal found:
+
+```
+No attention signal found for Anvil
+```
+
+## Notes
+
+- Attention files are created by workers using `/need-help`
+- The daemon watches this folder and sends notifications
+- Clearing signals is a way to acknowledge you've responded
+- Workers can also clear their own signals when unblocked

package/.claude/commands/forge.md

@@ -25,19 +25,34 @@ You are now the **Vibe Forge Planning Hub** - a multi-expert planning team.
 
 @context/project-context.md
 
-#### Current Forge State
+#### Modern Tooling Reference (avoid outdated suggestions)
 
-@_vibe-forge/context/forge-state.yaml
+@_vibe-forge/context/modern-conventions.md
+
+**Startup:** Display the team assembly welcome:
+
+```text
+🔥 VIBE FORGE - Planning Hub
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+The forge council assembles...
 
-#### Task Overview
+  🔥 Forge Master  - Orchestration & Tasks
+  🏛️ Architect     - Technical Design
+  🛡️ Aegis         - Security
+  ⚙️ Ember         - DevOps & Infrastructure
+  🎨 Pixel         - User Experience
+  📊 Oracle        - Product & Requirements
+  🧪 Crucible      - Quality & Testing
 
-Check the task folders for current work:
+Ready to plan, review, or coordinate.
+Use /forge status to check current tasks.
 
-- `_vibe-forge/tasks/pending/` - Tasks waiting to be picked up
-- `_vibe-forge/tasks/in-progress/` - Tasks currently being worked on
-- `_vibe-forge/tasks/needs-changes/` - Tasks that need revision
+What's on the anvil today?
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
 
-**Startup:** Display the team assembly welcome as shown in your personality's Startup Behavior section. Show the forge council assembling, then use the Glob tool to check for .md files in the task folders above and report the current work status.
+Do NOT automatically scan task folders - wait for user to ask or use `/forge status`.
 
 ---
 

package/.claude/commands/need-help.md

@@ -0,0 +1,77 @@
+---
+description: Signal that you need human attention/input
+argument-hint: <brief reason>
+---
+
+# Need Help Command
+
+Use this command when you're blocked and need human input. This will:
+
+1. Create an attention file in `tasks/attention/`
+2. Ring the terminal bell for immediate notification
+3. Trigger a system toast notification (if daemon is running)
+4. Show in the Planning Hub's status display
+
+## Usage
+
+```
+/need-help Need clarification on auth implementation approach
+/need-help Blocked on API design decision - REST vs GraphQL?
+/need-help Tests failing, need guidance on expected behavior
+```
+
+## Implementation
+
+Based on `$ARGUMENTS`:
+
+1. Determine your agent identity from your system prompt or context
+2. Create an attention file at `tasks/attention/<agent>-<timestamp>.md`:
+
+```markdown
+---
+agent: <your-agent-name>
+created: <ISO timestamp>
+status: pending
+---
+
+# Attention Needed
+
+**Agent:** <icon> <display-name>
+**Time:** <human-readable time>
+
+## Issue
+
+$ARGUMENTS
+
+## Context
+
+<Brief context about what you were working on>
+```
+
+3. Ring the terminal bell:
+
+```bash
+printf '\a'
+```
+
+4. Announce that you've signaled for help and will wait.
+
+## Resolving Attention
+
+When a human responds (via Hub or directly), they can:
+- Delete the attention file to clear the flag
+- Move it to a resolved folder
+- Or just respond - the worker can delete their own attention file once unblocked
+
+## Example Output
+
+After running `/need-help Need decision on caching strategy`:
+
+```
+🔔 Attention signal sent!
+
+I've created tasks/attention/anvil-20240115-143022.md
+The Planning Hub and daemon have been notified.
+
+I'll wait for guidance. You can respond here or via the Hub.
+```

package/.claude/commands/worker-loop.md

@@ -0,0 +1,106 @@
+---
+description: Start a persistent worker loop (Ralph-style)
+argument-hint: <agent> [--max-idle 10] | stop
+---
+
+# Worker Loop Command
+
+Start a persistent worker loop for the specified agent. The worker will:
+1. Check for assigned tasks
+2. Work on tasks until complete
+3. Loop back and check for more tasks
+4. Only exit after N idle checks with no work found
+
+## Activation Modes
+
+Worker Loop can be activated in two ways:
+
+### 1. Config-based (Recommended)
+
+Enable during `forge init` or toggle anytime:
+
+```bash
+forge config worker-loop on     # Enable for all workers
+forge config worker-loop off    # Disable
+forge config worker-loop        # Check status
+```
+
+When enabled, ALL workers will automatically stay running and check for new tasks.
+
+### 2. Runtime (Per-session)
+
+Use this command for fine-grained control:
+
+```
+/worker-loop anvil              # Start Anvil in persistent loop
+/worker-loop furnace --max-idle 20  # Custom idle limit
+/worker-loop stop               # Stop the current loop
+```
+
+## Arguments
+
+- `$1` - Agent name (anvil, furnace, crucible, etc.) or "stop"
+- `--max-idle N` - Exit after N checks with no tasks (default: 10)
+
+## Implementation
+
+Based on `$ARGUMENTS`:
+
+### If first argument is "stop"
+
+Remove the worker loop state file and confirm:
+
+```bash
+rm -f "${CLAUDE_LOCAL_DIR:-$HOME/.claude}/forge-worker-loop.json"
+```
+
+Output: "Worker loop stopped."
+
+### Otherwise, start a loop
+
+1. Resolve the agent name to canonical form
+2. Create state file at `${CLAUDE_LOCAL_DIR}/forge-worker-loop.json`:
+
+```json
+{
+  "agent": "<resolved-agent>",
+  "max_idle_checks": 10,
+  "idle_count": 0,
+  "poll_interval": 5,
+  "started_at": "<ISO timestamp>"
+}
+```
+
+3. Load the agent's personality file
+4. Start working with this system prompt addition:
+
+```
+You are in PERSISTENT WORKER MODE. After completing each task:
+1. Check for more tasks assigned to you in tasks/pending/ and tasks/needs-changes/
+2. If tasks found, immediately begin working
+3. If no tasks, announce you are idle and waiting
+
+Do NOT ask permission to continue - work autonomously until no tasks remain.
+```
+
+5. The stop hook (hooks/worker-loop.sh) will intercept exit attempts and:
+   - If tasks exist: feed prompt to continue working
+   - If no tasks: increment idle counter
+   - If max idle reached: allow exit
+
+## How It Works
+
+The Worker Loop uses Claude Code's **Stop Hook** feature:
+
+1. When a worker tries to exit, the hook script runs
+2. It checks for pending tasks in `tasks/pending/` and `tasks/needs-changes/`
+3. If tasks found: blocks exit and feeds a prompt to continue working
+4. If no tasks: allows exit (or waits, depending on config)
+
+## Benefits
+
+- Workers stay active and pick up new tasks automatically
+- No need to manually respawn workers
+- Tasks can be added to pending/ and workers will find them
+- Config-based mode requires zero per-session setup
+- Configurable idle timeout prevents infinite waiting

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

@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+#
+# Vibe Forge Worker Loop - Stop Hook
+#
+# 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
+#
+
+set -euo pipefail
+
+# State file location (runtime toggle)
+STATE_FILE="${CLAUDE_LOCAL_DIR:-$HOME/.claude}/forge-worker-loop.json"
+FORGE_ROOT="${FORGE_ROOT:-$(pwd)}"
+
+# Check for runtime state file first (takes precedence)
+LOOP_ACTIVE=false
+WORKER_AGENT=""
+MAX_IDLE_CHECKS=10
+IDLE_COUNT=0
+POLL_INTERVAL=5
+
+if [[ -f "$STATE_FILE" ]]; then
+    LOOP_ACTIVE=true
+    WORKER_AGENT=$(jq -r '.agent // ""' "$STATE_FILE" 2>/dev/null || echo "")
+    MAX_IDLE_CHECKS=$(jq -r '.max_idle_checks // 10' "$STATE_FILE" 2>/dev/null || echo "10")
+    IDLE_COUNT=$(jq -r '.idle_count // 0' "$STATE_FILE" 2>/dev/null || echo "0")
+    POLL_INTERVAL=$(jq -r '.poll_interval // 5' "$STATE_FILE" 2>/dev/null || echo "5")
+fi
+
+# If no runtime state, check config-based setting
+if [[ "$LOOP_ACTIVE" == "false" ]]; then
+    CONFIG_FILE="$FORGE_ROOT/.forge/config.json"
+    if [[ -f "$CONFIG_FILE" ]]; then
+        CONFIG_ENABLED=$(jq -r '.worker_loop_enabled // false' "$CONFIG_FILE" 2>/dev/null || echo "false")
+        if [[ "$CONFIG_ENABLED" == "true" ]]; then
+            LOOP_ACTIVE=true
+            # For config-based, use "any" to match any worker
+            WORKER_AGENT="any"
+        fi
+    fi
+fi
+
+# Check if worker loop is active
+if [[ "$LOOP_ACTIVE" == "false" ]]; then
+    # No active loop, allow exit
+    echo '{"decision": "allow"}'
+    exit 0
+fi
+
+if [[ -z "$WORKER_AGENT" ]]; then
+    # Invalid state, clean up and allow exit
+    rm -f "$STATE_FILE" 2>/dev/null || true
+    echo '{"decision": "allow"}'
+    exit 0
+fi
+
+# Check for pending tasks (assigned to specific worker or any worker)
+TASKS_DIR="$FORGE_ROOT/tasks"
+PENDING_COUNT=0
+NEEDS_CHANGES_COUNT=0
+
+if [[ -d "$TASKS_DIR/pending" ]]; then
+    if [[ "$WORKER_AGENT" == "any" ]]; then
+        # Config mode: count all pending tasks
+        PENDING_COUNT=$(find "$TASKS_DIR/pending" -name "*.md" 2>/dev/null | wc -l || echo "0")
+    else
+        # Runtime mode: count only tasks assigned to specific worker
+        PENDING_COUNT=$(grep -l "assigned_to:.*$WORKER_AGENT" "$TASKS_DIR/pending/"*.md 2>/dev/null | wc -l || echo "0")
+    fi
+fi
+
+if [[ -d "$TASKS_DIR/needs-changes" ]]; then
+    if [[ "$WORKER_AGENT" == "any" ]]; then
+        # Config mode: count all needs-changes tasks
+        NEEDS_CHANGES_COUNT=$(find "$TASKS_DIR/needs-changes" -name "*.md" 2>/dev/null | wc -l || echo "0")
+    else
+        # Runtime mode: count only tasks assigned to specific worker
+        NEEDS_CHANGES_COUNT=$(grep -l "assigned_to:.*$WORKER_AGENT" "$TASKS_DIR/needs-changes/"*.md 2>/dev/null | wc -l || echo "0")
+    fi
+fi
+
+TOTAL_TASKS=$((PENDING_COUNT + NEEDS_CHANGES_COUNT))
+
+if [[ "$TOTAL_TASKS" -gt 0 ]]; then
+    # Tasks found! Reset idle counter and continue
+    if [[ -f "$STATE_FILE" ]]; then
+        jq --argjson idle 0 '.idle_count = $idle' "$STATE_FILE" > "$STATE_FILE.tmp" && mv "$STATE_FILE.tmp" "$STATE_FILE"
+    fi
+
+    # Block exit and feed prompt to continue working
+    cat << EOF
+{
+    "decision": "block",
+    "message": "[Forge Loop] Found $TOTAL_TASKS pending task(s). Continuing work...",
+    "prompt": "Check tasks/pending/ and tasks/needs-changes/ for tasks assigned to you and begin working on them immediately."
+}
+EOF
+    exit 0
+fi
+
+# No tasks - increment idle counter (only for runtime mode with state file)
+if [[ -f "$STATE_FILE" ]]; then
+    IDLE_COUNT=$((IDLE_COUNT + 1))
+    jq --argjson idle "$IDLE_COUNT" '.idle_count = $idle' "$STATE_FILE" > "$STATE_FILE.tmp" && mv "$STATE_FILE.tmp" "$STATE_FILE"
+
+    if [[ "$IDLE_COUNT" -ge "$MAX_IDLE_CHECKS" ]]; then
+        # Max idle checks reached, clean up and allow exit
+        rm -f "$STATE_FILE"
+        cat << EOF
+{
+    "decision": "allow",
+    "message": "[Forge Loop] No tasks found after $MAX_IDLE_CHECKS checks. Exiting."
+}
+EOF
+        exit 0
+    fi
+
+    # Still within idle limit - wait and check again
+    cat << EOF
+{
+    "decision": "block",
+    "message": "[Forge Loop] No tasks available. Idle check $IDLE_COUNT/$MAX_IDLE_CHECKS. Waiting...",
+    "prompt": "No tasks currently assigned to you. Wait briefly, then check tasks/pending/ and tasks/needs-changes/ again for new work. If still no tasks, announce you are idle and ready."
+}
+EOF
+else
+    # Config-based mode - no idle tracking, just allow exit when no tasks
+    cat << EOF
+{
+    "decision": "allow",
+    "message": "[Forge Loop] No pending tasks. Worker exiting."
+}
+EOF
+fi

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

@@ -12,5 +12,18 @@
       "Bash(gh workflow run:*)",
       "Bash(gh repo view:*)"
     ]
+  },
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/worker-loop.sh"
+          }
+        ]
+      }
+    ]
   }
 }

package/bin/cli.js

@@ -21,6 +21,8 @@ const REPO_URL = 'https://github.com/SpasticPalate/vibe-forge.git';
 const FORGE_DIR = '_vibe-forge';
 
 // Colors for terminal output
+// NOTE: Intentionally self-contained - cli.js runs standalone via npx before
+// the rest of Vibe Forge is installed, so it cannot share with colors.sh
 const colors = {
   reset: '\x1b[0m',
   red: '\x1b[31m',
@@ -199,6 +201,9 @@ async function initCommand() {
 
   log('');
 
+  // Update project's .gitignore to ignore tool internals but keep project data
+  updateGitignore();
+
   // Run the setup script
   logInfo('Running setup...');
   log('');
@@ -212,6 +217,50 @@ async function initCommand() {
   }
 }
 
+function updateGitignore() {
+  const gitignorePath = path.join(process.cwd(), '.gitignore');
+  const forgeIgnoreMarker = '# Vibe Forge';
+  const forgeIgnoreBlock = `
+# Vibe Forge
+# Tool internals (regenerated on update)
+_vibe-forge/.git/
+_vibe-forge/bin/
+_vibe-forge/agents/
+_vibe-forge/config/
+_vibe-forge/docs/
+_vibe-forge/tests/
+_vibe-forge/src/
+_vibe-forge/node_modules/
+_vibe-forge/package*.json
+_vibe-forge/*.md
+_vibe-forge/LICENSE
+_vibe-forge/.github/
+
+# Keep project data (tasks, context) - these ARE committed
+# !_vibe-forge/tasks/
+# !_vibe-forge/context/
+# !_vibe-forge/.claude/
+`;
+
+  try {
+    let content = '';
+    if (fs.existsSync(gitignorePath)) {
+      content = fs.readFileSync(gitignorePath, 'utf8');
+      // Check if already has forge entries
+      if (content.includes(forgeIgnoreMarker)) {
+        return; // Already configured
+      }
+    }
+
+    // Append forge ignore block
+    const newContent = content.trimEnd() + '\n' + forgeIgnoreBlock;
+    fs.writeFileSync(gitignorePath, newContent);
+    logSuccess('Updated .gitignore for Vibe Forge');
+  } catch (err) {
+    logError(`Warning: Could not update .gitignore: ${err.message}`);
+  }
+}
+
 async function updateCommand() {
   showBanner();