vibe-forge 0.3.12 → 0.8.1

package/bin/forge.sh

@@ -1,393 +1,566 @@
-#!/usr/bin/env bash
-#
-# Vibe Forge - Main Launcher
-# Starts the Planning Hub or specific worker agents
-#
-# Usage:
-#   forge              - Start Planning Hub (main session)
-#   forge init         - Initialize Vibe Forge
-#   forge start <agent> - Start a specific worker agent
-#   forge spawn <agent> - Spawn agent in new terminal window/tab
-#   forge status       - Show forge status
-#   forge test         - Validate setup
-#   forge daemon       - Start/stop the background daemon
-#   forge help         - Show help
-#
-# Security Note:
-#   This script uses --dangerously-skip-permissions for Claude Code to enable
-#   seamless agent startup. This is intentional for the forge workflow.
-#   See docs/security.md for details.
-#
-
-set -e
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-FORGE_ROOT="$(dirname "$SCRIPT_DIR")"
-CONFIG_FILE="$FORGE_ROOT/.forge/config.json"
-
-# =============================================================================
-# Load Shared Libraries
-# =============================================================================
-
-# shellcheck source=lib/colors.sh
-source "$SCRIPT_DIR/lib/colors.sh"
-# shellcheck source=lib/constants.sh
-source "$SCRIPT_DIR/lib/constants.sh"
-# shellcheck source=lib/config.sh
-source "$SCRIPT_DIR/lib/config.sh"
-# shellcheck source=lib/agents.sh
-source "$SCRIPT_DIR/lib/agents.sh"
-
-# Load agent configuration from JSON if available
-# This overwrites the fallback values in constants.sh
-if [[ -f "$FORGE_ROOT/$AGENTS_CONFIG" ]]; then
-    if ! load_agents_from_json "$FORGE_ROOT/$AGENTS_CONFIG" 2>/dev/null; then
-        log_warn "Failed to load agents.json, using fallback defaults"
-    fi
-fi
-
-# =============================================================================
-# Commands
-# =============================================================================
-
-cmd_init() {
-    "$SCRIPT_DIR/forge-setup.sh" "$@"
-}
-
-cmd_start() {
-    local agent="${1:-hub}"
-
-    # Load and validate config
-    require_forge_config "$FORGE_ROOT"
-
-    # Validate and resolve agent name (SECURITY: whitelist validation)
-    local resolved
-    resolved=$(resolve_agent "$agent") || {
-        log_error "Unknown agent: $agent"
-        echo ""
-        show_available_agents
-        exit 1
-    }
-
-    # Get personality path (SECURITY: path traversal protection)
-    local personality_path
-    personality_path=$(get_agent_personality_path "$FORGE_ROOT" "$resolved") || {
-        log_error "Personality file not found for agent: $resolved"
-        exit 1
-    }
-
-    # Get display name
-    local agent_name
-    agent_name=$(get_agent_display_name "$resolved")
-
-    log_header "🔥 Starting $agent_name..."
-    echo ""
-
-    # Build the system prompt from personality file
-    local system_prompt
-    system_prompt=$(cat "$personality_path")
-
-    # Add project context if it exists
-    local project_context="$FORGE_ROOT/$CONTEXT_DIR/project-context.md"
-    if [[ -f "$project_context" ]]; then
-        system_prompt="$system_prompt
-
----
-
-# Project Context
-
-$(cat "$project_context")"
-    fi
-
-    # Add startup instructions based on agent type
-    if [[ "$resolved" == "hub" ]]; then
-        # Planning Hub startup - Party Mode Team
-        system_prompt="$system_prompt
-
----
-
-# Startup Instructions
-
-On startup, you MUST immediately display the team assembly welcome as shown in the Startup Behavior section of your personality. Show the forge council members assembling with their icons and roles. Then check for any current work status.
-"
-    else
-        # Worker agent startup
-        system_prompt="$system_prompt
-
----
-
-# Startup Instructions
-
-On startup:
-1. Announce yourself briefly (icon, name, role)
-2. Check tasks/pending/ and tasks/needs-changes/ for tasks assigned to you
-3. If you find assigned tasks, IMMEDIATELY begin working on them (no confirmation needed)
-4. If no tasks found, announce you're idle and ready for work
-
-You are autonomous - when assigned work exists, start it without asking permission.
-"
-    fi
-
-    # Launch Claude Code with the personality
-    # --dangerously-skip-permissions avoids repeated prompts when starting agents
-    # This is documented in docs/security.md
-    if [[ "$resolved" == "hub" ]]; then
-        claude --dangerously-skip-permissions --system-prompt "$system_prompt" "begin"
-    else
-        claude --dangerously-skip-permissions --system-prompt "$system_prompt" "startup"
-    fi
-}
-
-cmd_status() {
-    require_forge_config "$FORGE_ROOT"
-
-    local state_file="$FORGE_ROOT/$CONTEXT_DIR/forge-state.yaml"
-
-    echo ""
-    log_header "🔥 Forge Status"
-
-    if [[ -f "$state_file" ]]; then
-        cat "$state_file"
-    else
-        echo "No active forge state."
-        echo ""
-        echo "Start the forge with: forge"
-    fi
-
-    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-    echo ""
-}
-
-cmd_test() {
-    require_forge_config "$FORGE_ROOT"
-
-    echo ""
-    log_header "🧪 Testing Vibe Forge setup..."
-    echo ""
-
-    # Test Claude Code
-    echo "Testing Claude Code..."
-    if claude --version &> /dev/null; then
-        log_success "Claude Code working"
-    else
-        log_error "Claude Code not working"
-        exit 1
-    fi
-
-    # Test personality loading
-    echo ""
-    echo "Testing personality loading..."
-    local test_output
-    test_output=$(claude --system-prompt "You are a test. Respond with only: FORGE_TEST_OK" --print "test" 2>&1 | head -1)
-
-    if [[ "$test_output" == *"FORGE_TEST_OK"* || "$test_output" == *"test"* ]]; then
-        log_success "Personality loading working"
-    else
-        log_warn "Personality loading may have issues"
-        echo "   Output: $test_output"
-    fi
-
-    echo ""
-    log_success "🔥 Setup validated!"
-}
-
-cmd_spawn() {
-    local agent="${1:-}"
-
-    if [[ -z "$agent" ]]; then
-        log_error "No agent specified."
-        echo "Usage: forge spawn <agent>"
-        echo ""
-        show_available_agents
-        exit 1
-    fi
-
-    # Validate agent before passing to spawn script (SECURITY: whitelist check)
-    if ! is_valid_agent "$agent"; then
-        log_error "Unknown agent: $agent"
-        echo ""
-        show_available_agents
-        exit 1
-    fi
-
-    "$SCRIPT_DIR/forge-spawn.sh" "$agent"
-}
-
-cmd_daemon() {
-    local action="${1:-status}"
-
-    case "$action" in
-        "start")
-            echo "Starting forge daemon..."
-            "$SCRIPT_DIR/forge-daemon.sh" start
-            ;;
-        "stop")
-            echo "Stopping forge daemon..."
-            "$SCRIPT_DIR/forge-daemon.sh" stop
-            ;;
-        "status")
-            "$SCRIPT_DIR/forge-daemon.sh" status
-            ;;
-        "notifications"|"notify")
-            shift
-            "$SCRIPT_DIR/forge-daemon.sh" notifications "$@"
-            ;;
-        "clear")
-            "$SCRIPT_DIR/forge-daemon.sh" clear
-            ;;
-        *)
-            echo "Usage: forge daemon [start|stop|status|notifications|clear]"
-            ;;
-    esac
-}
-
-cmd_config() {
-    local setting="${1:-}"
-    local value="${2:-}"
-    local config_file="$FORGE_ROOT/.forge/config.json"
-
-    if [[ ! -f "$config_file" ]]; then
-        log_error "Forge not initialized. Run 'forge init' first."
-        exit 1
-    fi
-
-    case "$setting" in
-        "worker-loop"|"loop")
-            case "$value" in
-                "on"|"true"|"1"|"enable"|"enabled")
-                    # Enable worker loop
-                    if jq -e '.worker_loop_enabled' "$config_file" > /dev/null 2>&1; then
-                        jq '.worker_loop_enabled = true' "$config_file" > "$config_file.tmp" && mv "$config_file.tmp" "$config_file"
-                    else
-                        jq '. + {worker_loop_enabled: true}' "$config_file" > "$config_file.tmp" && mv "$config_file.tmp" "$config_file"
-                    fi
-                    log_success "Worker Loop enabled"
-                    echo "Workers will now keep running to check for new tasks."
-                    ;;
-                "off"|"false"|"0"|"disable"|"disabled")
-                    # Disable worker loop
-                    if jq -e '.worker_loop_enabled' "$config_file" > /dev/null 2>&1; then
-                        jq '.worker_loop_enabled = false' "$config_file" > "$config_file.tmp" && mv "$config_file.tmp" "$config_file"
-                    else
-                        jq '. + {worker_loop_enabled: false}' "$config_file" > "$config_file.tmp" && mv "$config_file.tmp" "$config_file"
-                    fi
-                    log_success "Worker Loop disabled"
-                    echo "Workers will exit after completing their tasks."
-                    ;;
-                ""|"status")
-                    # Show current status
-                    local current
-                    current=$(jq -r '.worker_loop_enabled // false' "$config_file")
-                    if [[ "$current" == "true" ]]; then
-                        echo "Worker Loop: enabled"
-                    else
-                        echo "Worker Loop: disabled"
-                    fi
-                    ;;
-                *)
-                    echo "Usage: forge config worker-loop [on|off|status]"
-                    ;;
-            esac
-            ;;
-        "")
-            # Show all config
-            echo ""
-            log_header "Forge Configuration"
-            echo ""
-            jq '.' "$config_file"
-            echo ""
-            ;;
-        *)
-            log_error "Unknown setting: $setting"
-            echo ""
-            echo "Available settings:"
-            echo "  worker-loop    Toggle persistent worker mode (on/off)"
-            echo ""
-            echo "Usage: forge config <setting> [value]"
-            ;;
-    esac
-}
-
-cmd_help() {
-    echo ""
-    log_header "🔥 Vibe Forge"
-    echo ""
-    echo "Usage: forge [command] [options]"
-    echo ""
-    echo "Commands:"
-    echo "  (none)              Start the Planning Hub (main session)"
-    echo "  init                Initialize Vibe Forge for this project"
-    echo "  start <agent>       Start a specific worker agent (in current terminal)"
-    echo "  spawn <agent>       Spawn agent in new terminal window/tab"
-    echo "  status              Show current forge status"
-    echo "  test                Validate setup is working"
-    echo "  daemon <action>     Manage background daemon (start|stop|status|notifications|clear)"
-    echo "  config <setting>    View or change configuration settings"
-    echo "  help                Show this help message"
-    echo ""
-    show_available_agents
-    echo ""
-    echo "Configuration:"
-    echo "  forge config                    Show all settings"
-    echo "  forge config worker-loop on     Enable persistent worker mode"
-    echo "  forge config worker-loop off    Disable persistent worker mode"
-    echo ""
-    echo "Examples:"
-    echo "  forge               Start Planning Hub"
-    echo "  forge init          Initialize for new project"
-    echo "  forge start anvil   Start Anvil (frontend) agent"
-    echo "  forge spawn fe      Spawn frontend agent in new terminal"
-    echo "  forge status        Check current status"
-    echo ""
-}
-
-# =============================================================================
-# Main
-# =============================================================================
-
-main() {
-    local command="${1:-}"
-
-    case "$command" in
-        "init")
-            shift
-            cmd_init "$@"
-            ;;
-        "start")
-            shift
-            cmd_start "$@"
-            ;;
-        "spawn")
-            shift
-            cmd_spawn "$@"
-            ;;
-        "status")
-            cmd_status
-            ;;
-        "test")
-            cmd_test
-            ;;
-        "daemon")
-            shift
-            cmd_daemon "$@"
-            ;;
-        "config")
-            shift
-            cmd_config "$@"
-            ;;
-        "help"|"--help"|"-h")
-            cmd_help
-            ;;
-        "")
-            # Default: start Planning Hub
-            cmd_start "hub"
-            ;;
-        *)
-            log_error "Unknown command: $command"
-            echo "Run 'forge help' for usage."
-            exit 1
-            ;;
-    esac
-}
-
-main "$@"
+#!/usr/bin/env bash
+#
+# Vibe Forge - Main Launcher
+# Starts the Planning Hub or specific worker agents
+#
+# Usage:
+#   forge              - Start Planning Hub (main session)
+#   forge init         - Initialize Vibe Forge
+#   forge start <agent> - Start a specific worker agent
+#   forge spawn <agent> - Spawn agent in new terminal window/tab
+#   forge status       - Show forge status
+#   forge doctor       - Full environment diagnostics (alias: test)
+#   forge daemon       - Start/stop the background daemon
+#   forge help         - Show help
+#
+# Security Note:
+#   Agents use allowlist-based permissions (.claude/settings.json) plus
+#   Heimdall pre-tool hooks instead of --dangerously-skip-permissions.
+#   See docs/security.md for the trust model.
+#
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+FORGE_ROOT="$(dirname "$SCRIPT_DIR")"
+CONFIG_FILE="$FORGE_ROOT/.forge/config.json"
+
+# =============================================================================
+# Load Shared Libraries
+# =============================================================================
+
+# shellcheck source=lib/colors.sh
+source "$SCRIPT_DIR/lib/colors.sh"
+# shellcheck source=lib/constants.sh
+source "$SCRIPT_DIR/lib/constants.sh"
+# shellcheck source=lib/config.sh
+source "$SCRIPT_DIR/lib/config.sh"
+# shellcheck source=lib/json.sh
+source "$SCRIPT_DIR/lib/json.sh"
+# shellcheck source=lib/agents.sh
+source "$SCRIPT_DIR/lib/agents.sh"
+
+# Load agent configuration from JSON if available
+# This overwrites the fallback values in constants.sh
+if [[ -f "$FORGE_ROOT/$AGENTS_CONFIG" ]]; then
+    if ! load_agents_from_json "$FORGE_ROOT/$AGENTS_CONFIG" 2>/dev/null; then
+        log_warn "Failed to load agents.json, using fallback defaults"
+    fi
+fi
+
+# =============================================================================
+# Commands
+# =============================================================================
+
+cmd_init() {
+    "$SCRIPT_DIR/forge-setup.sh" "$@"
+}
+
+cmd_start() {
+    local agent="${1:-hub}"
+
+    # Load and validate config
+    require_forge_config "$FORGE_ROOT"
+
+    # Validate and resolve agent name (SECURITY: whitelist validation)
+    local resolved
+    resolved=$(resolve_agent "$agent") || {
+        log_error "Unknown agent: $agent"
+        echo ""
+        show_available_agents
+        exit $EXIT_INVALID_ARGUMENT
+    }
+
+    # Get personality path (SECURITY: path traversal protection)
+    local personality_path
+    personality_path=$(get_agent_personality_path "$FORGE_ROOT" "$resolved") || {
+        log_error "Personality file not found for agent: $resolved"
+        exit $EXIT_CONFIG_ERROR
+    }
+
+    # Get display name
+    local agent_name
+    agent_name=$(get_agent_display_name "$resolved")
+
+    log_header "🔥 Starting $agent_name..."
+    echo ""
+
+    # Build the system prompt from personality file
+    local system_prompt
+    system_prompt=$(cat "$personality_path")
+
+    # Add project context if it exists
+    local project_context="$FORGE_ROOT/$CONTEXT_DIR/project-context.md"
+    if [[ -f "$project_context" ]]; then
+        system_prompt="$system_prompt
+
+---
+
+# Project Context
+
+$(cat "$project_context")"
+    fi
+
+    # Add per-project agent overrides if they exist (T2-E3)
+    local agent_override="$FORGE_ROOT/$CONTEXT_DIR/agent-overrides/${resolved}.md"
+    if [[ -f "$agent_override" ]]; then
+        system_prompt="$system_prompt
+
+---
+
+# Project-Specific Rules for $agent_name
+
+$(cat "$agent_override")"
+    fi
+
+    # Check for handoff files from previous sessions (T2-F2)
+    local handoff_dir="$FORGE_ROOT/tasks/handoffs"
+    if [[ -d "$handoff_dir" ]]; then
+        for handoff in "$handoff_dir"/*-"${resolved}"-*.md "$handoff_dir"/*-handoff.md; do
+            if [[ -f "$handoff" ]]; then
+                local handoff_agent
+                handoff_agent=$(node "$SCRIPT_DIR/lib/frontmatter.js" "$handoff" "agent" 2>/dev/null | sed -n 's/^agent=//p')
+                if [[ "$handoff_agent" == "$resolved" ]]; then
+                    system_prompt="$system_prompt
+
+---
+
+# Session Handoff (from previous session)
+
+$(cat "$handoff")"
+                    break
+                fi
+            fi
+        done
+    fi
+
+    # Add startup instructions based on agent type
+    if [[ "$resolved" == "hub" ]]; then
+        # Planning Hub startup - Party Mode Team
+        system_prompt="$system_prompt
+
+---
+
+# Startup Instructions
+
+On startup, you MUST immediately display the team assembly welcome as shown in the Startup Behavior section of your personality. Show the forge council members assembling with their icons and roles. Then check for any current work status.
+"
+    else
+        # Worker agent startup
+        system_prompt="$system_prompt
+
+---
+
+# Startup Instructions
+
+On startup:
+1. Announce yourself briefly (icon, name, role)
+2. Check tasks/pending/ and tasks/needs-changes/ for tasks assigned to you
+3. If you find assigned tasks, IMMEDIATELY begin working on them (no confirmation needed)
+4. If no tasks found, announce you're idle and ready for work
+
+You are autonomous - when assigned work exists, start it without asking permission.
+"
+    fi
+
+    # Launch Claude Code with the personality
+    # Agents use project-level .claude/settings.json for permissions (allowlist + Heimdall hooks)
+    # instead of --dangerously-skip-permissions. See docs/security.md.
+    if [[ "$resolved" == "hub" ]]; then
+        claude --system-prompt "$system_prompt" "begin"
+    else
+        claude --system-prompt "$system_prompt" "startup"
+    fi
+}
+
+cmd_status() {
+    require_forge_config "$FORGE_ROOT"
+
+    local state_file="$FORGE_ROOT/$CONTEXT_DIR/forge-state.yaml"
+
+    echo ""
+    log_header "🔥 Forge Status"
+
+    if [[ -f "$state_file" ]]; then
+        cat "$state_file"
+    else
+        echo "No active forge state."
+        echo ""
+        echo "Start the forge with: forge"
+    fi
+
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo ""
+}
+
+cmd_test() {
+    # Alias for doctor
+    cmd_doctor
+}
+
+cmd_doctor() {
+    echo ""
+    log_header "🩺 Forge Doctor"
+    echo ""
+
+    local issues=0
+
+    # --- Dependencies ---
+    echo "Dependencies"
+    echo "────────────────────────────────────────────────"
+
+    if claude --version &> /dev/null; then
+        local claude_ver
+        claude_ver=$(claude --version 2>&1 | head -1)
+        log_success "Claude Code: $claude_ver"
+    else
+        log_error "Claude Code: not found"
+        echo "   Install from: https://claude.ai/download"
+        issues=$((issues + 1))
+    fi
+
+    if command -v node &> /dev/null; then
+        local node_ver
+        node_ver=$(node --version 2>&1)
+        log_success "Node.js: $node_ver"
+        # Warn if below Node 18
+        local node_major
+        node_major=$(node --version | sed 's/v\([0-9]*\).*/\1/')
+        if [[ "$node_major" -lt 18 ]]; then
+            log_warn "Node.js $node_ver is below recommended v18+"
+        fi
+    else
+        log_error "Node.js: not found"
+        issues=$((issues + 1))
+    fi
+
+    if command -v git &> /dev/null; then
+        local git_ver
+        git_ver=$(git --version 2>&1)
+        log_success "Git: $git_ver"
+    else
+        log_error "Git: not found"
+        issues=$((issues + 1))
+    fi
+
+    if command -v sqlite3 &> /dev/null; then
+        local sq_ver
+        sq_ver=$(sqlite3 --version 2>&1 | head -1)
+        log_success "SQLite3: $sq_ver"
+    else
+        log_warn "SQLite3: not found (daemon metrics disabled)"
+    fi
+
+    # --- Forge Config ---
+    echo ""
+    echo "Configuration"
+    echo "────────────────────────────────────────────────"
+
+    local config_file="$FORGE_ROOT/.forge/config.json"
+    local local_config_file="$FORGE_ROOT/.forge/config.local.json"
+
+    if [[ -f "$config_file" ]]; then
+        log_success "config.json: found"
+        local platform terminal
+        platform=$(json_get_string "$config_file" "platform" 2>/dev/null || echo "unknown")
+        terminal=$(json_get_string "$config_file" "terminal_type" 2>/dev/null || echo "unknown")
+        echo "   Platform: $platform | Terminal: $terminal"
+    else
+        log_error "config.json: not found — run 'forge init'"
+        issues=$((issues + 1))
+    fi
+
+    if [[ -f "$local_config_file" ]]; then
+        log_success "config.local.json: found (local overrides active)"
+    fi
+
+    # --- agents.json sync check ---
+    local agents_file="$FORGE_ROOT/config/agents.json"
+    if [[ -f "$agents_file" ]]; then
+        log_success "agents.json: found"
+        local agent_count
+        agent_count=$(node -e "const a=require('$agents_file'); console.log(Object.keys(a.agents||{}).length)" 2>/dev/null || echo "?")
+        echo "   Agents defined: $agent_count"
+    else
+        log_error "agents.json: not found"
+        issues=$((issues + 1))
+    fi
+
+    # --- Alias collision check ---
+    if [[ -f "$agents_file" ]]; then
+        local collisions
+        collisions=$(node -e "
+const a = require('$agents_file').agents || {};
+const seen = {};
+const dupes = [];
+for (const [name, info] of Object.entries(a)) {
+    const aliases = [name, ...(info.aliases || [])];
+    for (const alias of aliases) {
+        if (seen[alias] && seen[alias] !== name) {
+            dupes.push(alias + ' (' + seen[alias] + ' vs ' + name + ')');
+        }
+        seen[alias] = name;
+    }
+}
+if (dupes.length) console.log('COLLISION: ' + dupes.join(', '));
+" 2>/dev/null || true)
+        if [[ -n "$collisions" ]]; then
+            log_error "Alias collision detected: $collisions"
+            issues=$((issues + 1))
+        else
+            log_success "No alias collisions"
+        fi
+    fi
+
+    # --- Task directories ---
+    echo ""
+    echo "Task System"
+    echo "────────────────────────────────────────────────"
+
+    local tasks_dir="$FORGE_ROOT/tasks"
+    local required_dirs=("pending" "in-progress" "completed" "review" "approved" "merged" "needs-changes" "attention" "bugs")
+    for dir in "${required_dirs[@]}"; do
+        if [[ -d "$tasks_dir/$dir" ]]; then
+            local count
+            count=$(ls "$tasks_dir/$dir/"*.md 2>/dev/null | wc -l | tr -d ' ')
+            log_success "$dir/: $count task(s)"
+        else
+            log_warn "$dir/: missing (will be created by daemon)"
+        fi
+    done
+
+    # --- Daemon ---
+    echo ""
+    echo "Daemon"
+    echo "────────────────────────────────────────────────"
+
+    local pid_file="$FORGE_ROOT/.forge/daemon.pid"
+    if [[ -f "$pid_file" ]]; then
+        local pid
+        pid=$(cat "$pid_file" 2>/dev/null)
+        if kill -0 "$pid" 2>/dev/null; then
+            log_success "Daemon running (PID $pid)"
+        else
+            log_warn "Daemon PID file exists but process is dead — run 'forge daemon start'"
+        fi
+    else
+        log_warn "Daemon not running — run 'forge daemon start' for automated task routing"
+    fi
+
+    # --- Claude Code test ---
+    echo ""
+    echo "Claude Code Integration"
+    echo "────────────────────────────────────────────────"
+
+    local test_output
+    test_output=$(claude --system-prompt "You are a test. Reply only: FORGE_TEST_OK" --print "test" 2>&1 | head -1)
+    if [[ "$test_output" == *"FORGE_TEST_OK"* || "$test_output" == *"test"* ]]; then
+        log_success "Personality injection: working"
+    else
+        log_warn "Personality injection: response unexpected"
+        echo "   Output: $test_output"
+    fi
+
+    # --- Summary ---
+    echo ""
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    if [[ $issues -eq 0 ]]; then
+        log_success "🔥 Forge looks healthy"
+    else
+        log_error "Found $issues issue(s) — resolve the errors above before starting"
+    fi
+    echo ""
+}
+
+cmd_spawn() {
+    local agent="${1:-}"
+
+    if [[ -z "$agent" ]]; then
+        log_error "No agent specified."
+        echo "Usage: forge spawn <agent>"
+        echo ""
+        show_available_agents
+        exit $EXIT_INVALID_ARGUMENT
+    fi
+
+    # Validate agent before passing to spawn script (SECURITY: whitelist check)
+    if ! is_valid_agent "$agent"; then
+        log_error "Unknown agent: $agent"
+        echo ""
+        show_available_agents
+        exit $EXIT_INVALID_ARGUMENT
+    fi
+
+    "$SCRIPT_DIR/forge-spawn.sh" "$agent"
+}
+
+cmd_daemon() {
+    local action="${1:-status}"
+
+    case "$action" in
+        "start")
+            echo "Starting forge daemon..."
+            "$SCRIPT_DIR/forge-daemon.sh" start
+            ;;
+        "stop")
+            echo "Stopping forge daemon..."
+            "$SCRIPT_DIR/forge-daemon.sh" stop
+            ;;
+        "status")
+            "$SCRIPT_DIR/forge-daemon.sh" status
+            ;;
+        "notifications"|"notify")
+            shift
+            "$SCRIPT_DIR/forge-daemon.sh" notifications "$@"
+            ;;
+        "clear")
+            "$SCRIPT_DIR/forge-daemon.sh" clear
+            ;;
+        *)
+            echo "Usage: forge daemon [start|stop|status|notifications|clear]"
+            ;;
+    esac
+}
+
+cmd_config() {
+    local setting="${1:-}"
+    local value="${2:-}"
+    local config_file="$FORGE_ROOT/.forge/config.json"
+
+    if [[ ! -f "$config_file" ]]; then
+        log_error "Forge not initialized. Run 'forge init' first."
+        exit $EXIT_CONFIG_ERROR
+    fi
+
+    case "$setting" in
+        "worker-loop"|"loop")
+            case "$value" in
+                "on"|"true"|"1"|"enable"|"enabled")
+                    # Enable worker loop
+                    json_write_bool "$config_file" "worker_loop_enabled" true
+                    log_success "Worker Loop enabled"
+                    echo "Workers will now keep running to check for new tasks."
+                    ;;
+                "off"|"false"|"0"|"disable"|"disabled")
+                    # Disable worker loop
+                    json_write_bool "$config_file" "worker_loop_enabled" false
+                    log_success "Worker Loop disabled"
+                    echo "Workers will exit after completing their tasks."
+                    ;;
+                ""|"status")
+                    # Show current status
+                    local current
+                    current=$(json_read "$config_file" "worker_loop_enabled" "false")
+                    if [[ "$current" == "true" ]]; then
+                        echo "Worker Loop: enabled"
+                    else
+                        echo "Worker Loop: disabled"
+                    fi
+                    ;;
+                *)
+                    echo "Usage: forge config worker-loop [on|off|status]"
+                    ;;
+            esac
+            ;;
+        "")
+            # Show all config
+            echo ""
+            log_header "Forge Configuration"
+            echo ""
+            json_pretty "$config_file"
+            echo ""
+            ;;
+        *)
+            log_error "Unknown setting: $setting"
+            echo ""
+            echo "Available settings:"
+            echo "  worker-loop    Toggle persistent worker mode (on/off)"
+            echo ""
+            echo "Usage: forge config <setting> [value]"
+            ;;
+    esac
+}
+
+cmd_help() {
+    echo ""
+    log_header "🔥 Vibe Forge"
+    echo ""
+    echo "Usage: forge [command] [options]"
+    echo ""
+    echo "Commands:"
+    echo "  (none)              Start the Planning Hub (main session)"
+    echo "  init                Initialize Vibe Forge for this project"
+    echo "  start <agent>       Start a specific worker agent (in current terminal)"
+    echo "  spawn <agent>       Spawn agent in new terminal window/tab"
+    echo "  status              Show current forge status"
+    echo "  doctor              Full environment diagnostics (alias: test)"
+    echo "  daemon <action>     Manage background daemon (start|stop|status|notifications|clear)"
+    echo "  config <setting>    View or change configuration settings"
+    echo "  help                Show this help message"
+    echo ""
+    show_available_agents
+    echo ""
+    echo "Configuration:"
+    echo "  forge config                    Show all settings"
+    echo "  forge config worker-loop on     Enable persistent worker mode"
+    echo "  forge config worker-loop off    Disable persistent worker mode"
+    echo ""
+    echo "Examples:"
+    echo "  forge               Start Planning Hub"
+    echo "  forge init          Initialize for new project"
+    echo "  forge start anvil   Start Anvil (frontend) agent"
+    echo "  forge spawn fe      Spawn frontend agent in new terminal"
+    echo "  forge status        Check current status"
+    echo ""
+}
+
+# =============================================================================
+# Main
+# =============================================================================
+
+main() {
+    local command="${1:-}"
+
+    case "$command" in
+        "init")
+            shift
+            cmd_init "$@"
+            ;;
+        "start")
+            shift
+            cmd_start "$@"
+            ;;
+        "spawn")
+            shift
+            cmd_spawn "$@"
+            ;;
+        "status")
+            cmd_status
+            ;;
+        "test"|"doctor")
+            cmd_doctor
+            ;;
+        "daemon")
+            shift
+            cmd_daemon "$@"
+            ;;
+        "config")
+            shift
+            cmd_config "$@"
+            ;;
+        "help"|"--help"|"-h")
+            cmd_help
+            ;;
+        "")
+            # Default: start Planning Hub
+            cmd_start "hub"
+            ;;
+        *)
+            log_error "Unknown command: $command"
+            echo "Run 'forge help' for usage."
+            exit $EXIT_INVALID_ARGUMENT
+            ;;
+    esac
+}
+
+main "$@"