vibe-forge 0.3.6 → 0.3.11

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,6 +25,10 @@ You are now the **Vibe Forge Planning Hub** - a multi-expert planning team.
 
 @context/project-context.md
 
+#### Modern Tooling Reference (avoid outdated suggestions)
+
+@_vibe-forge/context/modern-conventions.md
+
 **Startup:** Display the team assembly welcome:
 
 ```text

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/update-status.md

@@ -0,0 +1,64 @@
+---
+description: Update your agent status for the forge dashboard
+argument-hint: <status> [task-id]
+---
+
+# Update Status Command
+
+Report your current status to the forge daemon and Planning Hub. This enables real-time visibility into what each worker is doing.
+
+## Usage
+
+```
+/update-status working TASK-001       # Working on a specific task
+/update-status idle                   # Waiting for tasks
+/update-status blocked                # Stuck, may need help
+/update-status reviewing PR-123       # Reviewing something
+/update-status testing TASK-001       # Running tests
+```
+
+## Status Values
+
+| Status | Meaning |
+|--------|---------|
+| `idle` | No current task, ready for work |
+| `working` | Actively working on a task |
+| `blocked` | Stuck, needs input (consider `/need-help`) |
+| `reviewing` | Reviewing code or PR |
+| `testing` | Running tests |
+| `waiting` | Waiting for external dependency |
+
+## Implementation
+
+Based on `$ARGUMENTS`:
+
+1. Parse the status and optional task ID from arguments
+2. Determine your agent identity from your system prompt
+3. Write status file to `context/agent-status/<agent>.json`:
+
+```json
+{
+  "agent": "anvil",
+  "status": "working",
+  "task": "TASK-001",
+  "message": "Implementing user authentication",
+  "updated": "2024-01-15T14:30:22Z"
+}
+```
+
+4. The daemon reads these files and includes them in `forge-state.yaml`
+5. The Planning Hub sees your status in the dashboard
+
+## Auto-Status Updates
+
+Workers should update their status at these key moments:
+
+1. **On startup**: `/update-status idle` (or working if picking up a task)
+2. **When picking up a task**: `/update-status working TASK-XXX`
+3. **When completing a task**: `/update-status idle`
+4. **When blocked**: `/update-status blocked` (then `/need-help` if needed)
+5. **Before exiting**: Status file can remain (daemon marks stale after timeout)
+
+## Stale Status
+
+The daemon considers a status stale if not updated for 5+ minutes. Stale statuses are shown with a warning indicator in the dashboard.

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/agents/aegis/personality.md

@@ -71,6 +71,26 @@ Not paranoid, but vigilant. Aegis knows that security isn't about saying no - it
 10. Move to /tasks/completed/
 ```
 
+### Status Reporting
+
+Keep the Planning Hub and daemon informed of your status:
+
+```bash
+/update-status idle                    # When waiting for tasks
+/update-status working TASK-033        # When starting a task
+/update-status blocked TASK-033        # When stuck (then /need-help if needed)
+/update-status reviewing TASK-033      # When reviewing security
+/update-status idle                    # When task complete
+```
+
+Update status at key moments:
+
+1. **Startup**: Report `idle` (ready for work)
+2. **Task pickup**: Report `working` with task ID
+3. **Security review**: Report `reviewing` when auditing code
+4. **Blocked**: Report `blocked`, then use `/need-help` if human input needed
+5. **Completion**: Report `idle` after moving task to completed
+
 ### Output Format
 ```markdown
 ## Completion Summary

package/agents/anvil/personality.md

@@ -66,6 +66,25 @@ Derived from Amelia's developer DNA but specialized for the frontend domain. Whe
 9. Move to /tasks/completed/
 ```
 
+### Status Reporting
+
+Keep the Planning Hub and daemon informed of your status:
+
+```bash
+/update-status idle                    # When waiting for tasks
+/update-status working TASK-019        # When starting a task
+/update-status blocked TASK-019        # When stuck (then /need-help if needed)
+/update-status testing TASK-019        # When running tests
+/update-status idle                    # When task complete
+```
+
+Update status at key moments:
+
+1. **Startup**: Report `idle` (ready for work)
+2. **Task pickup**: Report `working` with task ID
+3. **Blocked**: Report `blocked`, then use `/need-help` if human input needed
+4. **Completion**: Report `idle` after moving task to completed
+
 ### Output Format
 ```markdown
 ## Completion Summary

package/agents/crucible/personality.md

@@ -78,6 +78,26 @@ Derived from Murat's test architect DNA. Crucible combines systematic test desig
 6. Route to appropriate agent for fix
 ```
 
+### Status Reporting
+
+Keep the Planning Hub and daemon informed of your status:
+
+```bash
+/update-status idle                    # When waiting for tasks
+/update-status working TASK-025        # When starting a task
+/update-status testing TASK-025        # When running test suites
+/update-status blocked TASK-025        # When stuck (then /need-help if needed)
+/update-status idle                    # When task complete
+```
+
+Update status at key moments:
+
+1. **Startup**: Report `idle` (ready for work)
+2. **Task pickup**: Report `working` with task ID
+3. **Test execution**: Report `testing` during test runs
+4. **Blocked**: Report `blocked`, then use `/need-help` if human input needed
+5. **Completion**: Report `idle` after moving task to completed
+
 ### Output Format
 ```markdown
 ## Completion Summary

package/agents/ember/personality.md

@@ -72,6 +72,25 @@ The name Ember reflects the persistent, quiet fire that powers everything. Not f
 12. Move to /tasks/completed/
 ```
 
+### Status Reporting
+
+Keep the Planning Hub and daemon informed of your status:
+
+```bash
+/update-status idle                    # When waiting for tasks
+/update-status working TASK-027        # When starting a task
+/update-status blocked TASK-027        # When stuck (then /need-help if needed)
+/update-status testing TASK-027        # When testing changes
+/update-status idle                    # When task complete
+```
+
+Update status at key moments:
+
+1. **Startup**: Report `idle` (ready for work)
+2. **Task pickup**: Report `working` with task ID
+3. **Blocked**: Report `blocked`, then use `/need-help` if human input needed
+4. **Completion**: Report `idle` after moving task to completed
+
 ### Output Format
 ```markdown
 ## Completion Summary

package/agents/furnace/personality.md

@@ -67,6 +67,25 @@ Like Anvil, derived from Amelia's developer DNA but specialized for the backend
 10. Move to /tasks/completed/
 ```
 
+### Status Reporting
+
+Keep the Planning Hub and daemon informed of your status:
+
+```bash
+/update-status idle                    # When waiting for tasks
+/update-status working TASK-021        # When starting a task
+/update-status blocked TASK-021        # When stuck (then /need-help if needed)
+/update-status testing TASK-021        # When running tests
+/update-status idle                    # When task complete
+```
+
+Update status at key moments:
+
+1. **Startup**: Report `idle` (ready for work)
+2. **Task pickup**: Report `working` with task ID
+3. **Blocked**: Report `blocked`, then use `/need-help` if human input needed
+4. **Completion**: Report `idle` after moving task to completed
+
 ### Output Format
 ```markdown
 ## Completion Summary

package/agents/herald/personality.md

@@ -74,6 +74,26 @@ Not just a button-pusher - Herald understands semantic versioning, changelog man
 9. Move task to /tasks/completed/
 ```
 
+### Status Reporting
+
+Keep the Planning Hub and daemon informed of your status:
+
+```bash
+/update-status idle                    # When waiting for tasks
+/update-status working TASK-031        # When starting a release task
+/update-status blocked TASK-031        # When release blocked (then /need-help if needed)
+/update-status waiting TASK-031        # When waiting for CI/deployment
+/update-status idle                    # When release complete
+```
+
+Update status at key moments:
+
+1. **Startup**: Report `idle` (ready for work)
+2. **Release prep**: Report `working` with task ID
+3. **Waiting on CI**: Report `waiting` during long CI runs or deployments
+4. **Blocked**: Report `blocked`, then use `/need-help` if human input needed
+5. **Completion**: Report `idle` after release announced
+
 ### Output Format
 ```markdown
 ## Completion Summary