vibe-forge 0.3.12 → 0.8.1

package/docs/architecture.md

@@ -0,0 +1,194 @@
+# Vibe Forge Architecture
+
+This document describes the architectural decisions and structure of the Vibe Forge codebase.
+
+## Language Strategy
+
+Vibe Forge uses a **hybrid Bash/Node.js architecture** with the following rationale:
+
+### Bash (Primary for Scripts)
+
+The core CLI and daemon are implemented in Bash because:
+
+1. **Native shell integration** - Vibe Forge orchestrates terminal sessions and Claude Code processes, which are inherently shell operations
+2. **Unix philosophy** - Small composable scripts that can be debugged, piped, and modified easily
+3. **Transparency** - Users can inspect and modify scripts without build steps
+4. **Git Bash compatibility** - Windows users with Git Bash can run the same scripts
+
+Files in Bash:
+- `bin/forge.sh` - Main CLI entry point
+- `bin/forge-setup.sh` - Setup and initialization
+- `bin/forge-spawn.sh` - Terminal spawning orchestration
+- `bin/forge-daemon.sh` - Background daemon for task monitoring
+- `bin/lib/*.sh` - Shared libraries (colors, config, agents, database, json, util)
+
+### Node.js (Cross-Platform Utilities)
+
+Node.js is used where cross-platform compatibility or complex logic is needed:
+
+1. **npx installer** - `bin/cli.js` runs via npx before Vibe Forge is installed
+2. **Terminal detection** - `bin/lib/terminal.js` detects and spawns terminals across Windows/macOS/Linux
+3. **JSON parsing** - All Bash scripts use Node.js for JSON via `bin/lib/json.sh` wrapper
+4. **Claude hooks** - `.claude/hooks/worker-loop.js` runs as Claude Code hook
+5. **Dashboard server** - `bin/dashboard/server.js` provides HTTP + WebSocket for the web UI
+
+### Design Principles
+
+1. **Single Source of Truth** - Configuration in `config/agents.json`, loaded by both languages
+2. **Node.js for JSON** - All JSON parsing uses `bin/lib/json.sh` which calls Node.js (no jq dependency)
+3. **Bash for orchestration** - Process management, file watching, terminal control
+4. **Thin wrappers** - `forge.cmd` on Windows calls Bash via Git Bash
+
+### JSON Handling
+
+All JSON operations use the `json.sh` library which provides:
+
+```bash
+# Reading JSON
+value=$(json_read "$file" "key" "default")
+
+# Reading multiple keys efficiently
+read -r name status task <<< "$(json_read_multi "$file" name status task)"
+
+# Writing JSON
+json_write "$file" "key" "value"
+json_write_bool "$file" "enabled" true
+
+# Pretty printing
+json_pretty "$file"
+
+# Key existence check
+if json_has_key "$file" "key"; then ...
+```
+
+This eliminates the jq dependency while maintaining security (arguments passed to Node.js, not interpolated).
+
+## Directory Structure
+
+```
+vibe-forge/
+├── agents/                    # Agent personality definitions
+│   ├── anvil/
+│   │   └── personality.md
+│   ├── furnace/
+│   └── ...
+├── bin/                       # Executables
+│   ├── cli.js                 # npx entry point (Node.js)
+│   ├── forge.sh               # Main CLI (Bash)
+│   ├── forge.cmd              # Windows wrapper
+│   ├── forge-setup.sh         # Setup script
+│   ├── forge-spawn.sh         # Terminal spawning
+│   ├── forge-daemon.sh        # Background daemon
+│   ├── dashboard/             # Web dashboard (Node.js)
+│   │   ├── server.js          # HTTP + WebSocket server
+│   │   ├── api/               # REST API endpoints
+│   │   │   ├── tasks.js       # Task CRUD
+│   │   │   ├── agents.js      # Agent status
+│   │   │   └── dispatch.js    # Task dispatch
+│   │   └── public/            # Frontend assets
+│   │       ├── index.html     # Dashboard UI
+│   │       ├── style.css      # Styles (dark mode)
+│   │       └── app.js         # Frontend logic
+│   └── lib/                   # Shared libraries
+│       ├── agents.sh          # Agent resolution
+│       ├── colors.sh          # Terminal colors
+│       ├── config.sh          # Configuration loading
+│       ├── constants.sh       # Constants (fallback)
+│       ├── database.sh        # SQLite operations
+│       ├── json.sh            # JSON utilities (Node.js based)
+│       ├── terminal.js        # Terminal detection (Node.js)
+│       └── util.sh            # Utility functions
+├── config/                    # Configuration files
+│   ├── agents.json            # Agent roster (source of truth)
+│   └── agent-manifest.yaml    # Rich documentation (non-normative)
+├── context/                   # Runtime context
+│   ├── agent-status/          # Agent status files
+│   └── forge-state.yaml       # Current forge state
+├── docs/                      # Documentation
+├── tasks/                     # Task lifecycle folders
+│   ├── pending/
+│   ├── in-progress/
+│   ├── completed/
+│   └── ...
+└── tests/                     # Test suites
+    ├── unit/                  # Jest unit tests (shell functions tested via child_process)
+    └── helpers/               # Test utilities
+```
+
+## Data Flow
+
+```
+┌──────────────┐     ┌────────────────┐     ┌──────────────┐
+│  CLI Input   │ --> │   forge.sh     │ --> │   Command    │
+│  (user)      │     │   (dispatch)   │     │   Handler    │
+└──────────────┘     └────────────────┘     └──────────────┘
+                                                   │
+                                                   v
+┌──────────────┐     ┌────────────────┐     ┌──────────────┐
+│   Claude     │ <-- │ forge-spawn.sh │ <-- │  Terminal    │
+│    Code      │     │ + terminal.js  │     │   Spawning   │
+└──────────────┘     └────────────────┘     └──────────────┘
+       │
+       v
+┌──────────────┐     ┌────────────────┐     ┌──────────────┐
+│   Tasks      │ <-> │ forge-daemon   │ <-> │   SQLite     │
+│   (files)    │     │   (monitor)    │     │   Database   │
+└──────────────┘     └────────────────┘     └──────────────┘
+       ^                                           ^
+       │                                           │
+       └─────────────────┬─────────────────────────┘
+                         │
+                         v
+              ┌────────────────────┐
+              │  Dashboard Server  │ <-- Browser (http://localhost:2800)
+              │  (port 2800 🔥)    │
+              │  + WebSocket /ws   │
+              └────────────────────┘
+```
+
+### Dashboard Architecture
+
+The dashboard is a self-contained Node.js server that provides:
+
+1. **Static file serving** - HTML, CSS, JS from `bin/dashboard/public/`
+2. **REST API** - Task management, agent status, dispatch at `/api/*`
+3. **WebSocket** - Real-time updates at `/ws`
+4. **Issue detection** - Stale docs, failing tests, security issues
+
+Port **2800** was chosen as the default because it's the operating temperature of a forge in degrees Fahrenheit. 🔥
+
+## Future Considerations
+
+### Potential Node.js Migration
+
+While Option B (hybrid) is the current strategy, a future Node.js migration could provide:
+
+1. **Better Windows support** - Native Node.js without Git Bash dependency
+2. **Unified codebase** - Single language to maintain
+3. **Type safety** - TypeScript for larger refactors
+4. **npm ecosystem** - Libraries for terminal control, process management
+
+Migration path if pursued:
+1. `src/lib/config.ts` - Configuration management
+2. `src/lib/agents.ts` - Agent resolution
+3. `src/lib/database.ts` - SQLite operations
+4. `src/daemon.ts` - Background daemon
+5. `src/forge.ts` - Main CLI (keeping forge.sh as thin wrapper initially)
+
+### Requirements for Migration
+
+Before pursuing full Node.js migration:
+- Ensure all Bash-specific functionality can be replicated
+- Maintain transparency (scripts users can inspect)
+- Keep startup time fast (current scripts are instant)
+- Preserve Unix composability where valuable
+
+## ADR Summary
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Primary language | Bash | Native shell integration, transparency |
+| JSON parsing | Node.js via json.sh | Security, cross-platform |
+| Terminal detection | Node.js | Cross-platform compatibility |
+| Windows support | Git Bash + forge.cmd | Maintains Unix-like experience |
+| Configuration | JSON (agents.json) | Machine-readable, single source |

package/docs/commands.md

@@ -0,0 +1,451 @@
+# Command Reference
+
+This document covers all Vibe Forge commands available in Claude Code.
+
+## CLI Commands
+
+These commands are run from your terminal.
+
+### vibe-forge init
+
+Initialize Vibe Forge in your project.
+
+```bash
+npx @sugar-crash-studios/vibe-forge init
+```
+
+**What it does:**
+- Clones Vibe Forge into `_vibe-forge/`
+- Detects your platform (Windows, macOS, Linux)
+- Finds Git Bash on Windows
+- Validates Claude Code installation
+- Configures terminal preferences
+- Optionally starts the daemon
+- Installs the `/forge` slash command
+- Creates project context file
+
+**Options:**
+- `--non-interactive` - Skip prompts, use defaults
+
+### vibe-forge update
+
+Update Vibe Forge to the latest version.
+
+```bash
+npx @sugar-crash-studios/vibe-forge update
+```
+
+**What it does:**
+- Fetches latest changes from GitHub
+- Preserves your tasks and context files
+- Updates scripts and agent configurations
+
+### vibe-forge version
+
+Show the installed version.
+
+```bash
+npx @sugar-crash-studios/vibe-forge version
+npx @sugar-crash-studios/vibe-forge --version
+npx @sugar-crash-studios/vibe-forge -v
+```
+
+### vibe-forge help
+
+Show help information.
+
+```bash
+npx @sugar-crash-studios/vibe-forge help
+npx @sugar-crash-studios/vibe-forge --help
+npx @sugar-crash-studios/vibe-forge -h
+```
+
+---
+
+## Slash Commands
+
+These commands are used inside Claude Code sessions.
+
+### /forge
+
+Start the Planning Hub (default command).
+
+```
+/forge
+```
+
+**What it does:**
+- Activates the multi-expert planning team
+- Displays the forge council welcome message
+- Prepares for planning and coordination tasks
+
+**Output:**
+```
+VIBE FORGE - Planning Hub
+-----------------------------------------------
+
+The forge council assembles...
+
+  Planning Hub  - Orchestration & Tasks
+  Architect     - Technical Design
+  Aegis         - Security
+  Ember         - DevOps & Infrastructure
+  Pixel         - User Experience
+  Oracle        - Product & Requirements
+  Crucible      - Quality & Testing
+
+Ready to plan, review, or coordinate.
+Use /forge status to check current tasks.
+
+What's on the anvil today?
+-----------------------------------------------
+```
+
+You can also explicitly start the hub with:
+```
+/forge plan
+```
+
+### /forge status
+
+Display the status dashboard.
+
+```
+/forge status
+```
+
+**What it does:**
+- Reads the current forge state
+- Counts tasks in each status folder
+- Shows active agent statuses
+- Displays attention signals
+
+**Output:**
+```
+VIBE FORGE - Status Dashboard
+-----------------------------------------------
+Pending:       3 tasks
+In Progress:   2 tasks
+In Review:     1 task
+Completed:     12 tasks
+
+Active Agents:
+  Anvil     - working on TASK-015
+  Furnace   - idle
+  Crucible  - testing TASK-014
+-----------------------------------------------
+```
+
+### /forge spawn
+
+Spawn a worker agent in a new terminal.
+
+```
+/forge spawn <agent>
+```
+
+**Arguments:**
+- `<agent>` - Agent name or alias (see table below)
+
+**Examples:**
+```
+/forge spawn anvil
+/forge spawn frontend    # Alias for anvil
+/forge spawn furnace
+/forge spawn backend     # Alias for furnace
+```
+
+**Available Agents:**
+
+| 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           |
+
+**Behavior by terminal type:**
+- **Windows Terminal** - Opens a new tab with the agent
+- **Manual mode** - Prints instructions to start the agent
+
+### /forge task
+
+Create a new task.
+
+```
+/forge task [description]
+```
+
+**Arguments:**
+- `[description]` - Optional task description
+
+**Examples:**
+```
+/forge task
+/forge task Add user authentication
+/forge task Fix the login button styling
+```
+
+**Interactive mode (no description):**
+- Prompts for task description
+- Asks which agent should handle it
+- Requests priority level (high, medium, low)
+
+**Task file location:**
+`tasks/pending/task-XXX.md`
+
+### /forge help
+
+Show available commands.
+
+```
+/forge help
+```
+
+**Output:**
+```
+VIBE FORGE - Commands
+-----------------------------------------------
+
+/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 this help
+
+Agents (with aliases):
+  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
+
+-----------------------------------------------
+```
+
+---
+
+## Worker Commands
+
+These commands are used by spawned worker agents.
+
+### /worker-loop
+
+Start a persistent worker loop.
+
+```
+/worker-loop <agent>
+/worker-loop <agent> --max-idle 20
+/worker-loop stop
+```
+
+**Arguments:**
+- `<agent>` - Agent name to run as
+- `--max-idle N` - Exit after N checks with no tasks (default: 10)
+- `stop` - Stop the current worker loop
+
+**What it does:**
+- Puts the worker in persistent mode
+- Worker checks for tasks, completes them, loops back
+- Only exits after max idle checks with no work found
+
+**Example:**
+```
+/worker-loop anvil              # Start Anvil in persistent loop
+/worker-loop furnace --max-idle 20  # Custom idle limit
+/worker-loop stop               # Stop the current loop
+```
+
+### /update-status
+
+Report current status to the dashboard.
+
+```
+/update-status <status> [task-id]
+```
+
+**Status values:**
+
+| Status    | Meaning                              |
+|-----------|--------------------------------------|
+| idle      | No current task, ready for work      |
+| working   | Actively working on a task           |
+| blocked   | Stuck, needs input                   |
+| reviewing | Reviewing code or PR                 |
+| testing   | Running tests                        |
+| waiting   | Waiting for external dependency      |
+
+**Examples:**
+```
+/update-status working TASK-001
+/update-status idle
+/update-status blocked
+/update-status reviewing PR-123
+/update-status testing TASK-001
+```
+
+### /need-help
+
+Signal that human attention is needed.
+
+```
+/need-help <reason>
+```
+
+**What it does:**
+- Creates an attention file in `tasks/attention/`
+- Rings the terminal bell
+- Shows in the Planning Hub status
+- Triggers toast notification (if daemon running)
+
+**Examples:**
+```
+/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
+```
+
+### /clear-attention
+
+Clear an attention signal after the issue is resolved.
+
+```
+/clear-attention <agent>
+```
+
+**What it does:**
+- Removes the attention file for the specified agent
+- Updates the dashboard to reflect resolution
+
+---
+
+## Dashboard Commands
+
+The Vibe Forge Dashboard provides a web-based UI for monitoring and managing your forge.
+
+### Dashboard Port: 2800
+
+The dashboard runs on port **2800** by default - the operating temperature of a forge in degrees Fahrenheit. 🔥
+
+This port was chosen because:
+- It's thematic (forges operate at around 2800°F)
+- It doesn't collide with common development ports (3000, 8080, 5000)
+- It doesn't collide with database ports (3306, 5432, 27017)
+- It doesn't collide with other tooling ports (5555, 9000, etc.)
+
+### Starting the Dashboard
+
+```bash
+# Start the dashboard server
+node bin/dashboard/server.js
+
+# Custom port
+node bin/dashboard/server.js --port 3000
+DASHBOARD_PORT=3000 node bin/dashboard/server.js
+
+# Custom host (for network access)
+node bin/dashboard/server.js --host 0.0.0.0
+```
+
+### Dashboard URL
+
+Once running, access the dashboard at:
+- **URL:** `http://localhost:2800`
+- **API:** `http://localhost:2800/api/`
+- **WebSocket:** `ws://localhost:2800/ws`
+
+### Dashboard API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/health` | GET | Server health check |
+| `/api/tasks` | GET | List all tasks by status |
+| `/api/tasks/:id` | GET | Get single task details |
+| `/api/tasks` | POST | Create new task |
+| `/api/agents` | GET | List agents with status |
+| `/api/dispatch` | POST | Dispatch agent for an issue |
+
+### Configuration
+
+Add to `.forge/config.json` (coming soon):
+
+```json
+{
+  "dashboard": {
+    "enabled": true,
+    "port": 2800,
+    "auto_open": true,
+    "host": "localhost"
+  }
+}
+```
+
+---
+
+## Daemon Commands
+
+Control the background daemon process.
+
+### forge daemon start
+
+Start the daemon.
+
+```bash
+./bin/forge-daemon.sh start
+```
+
+### forge daemon stop
+
+Stop the daemon.
+
+```bash
+./bin/forge-daemon.sh stop
+```
+
+### forge daemon status
+
+Check daemon status.
+
+```bash
+./bin/forge-daemon.sh status
+```
+
+---
+
+## Configuration Commands
+
+Manage Vibe Forge settings.
+
+### forge config worker-loop
+
+Toggle persistent worker mode.
+
+```bash
+forge config worker-loop on     # Enable for all workers
+forge config worker-loop off    # Disable
+forge config worker-loop        # Check current status
+```
+
+---
+
+## Shell Scripts
+
+Low-level scripts in `_vibe-forge/bin/`.
+
+| Script            | Purpose                           |
+|-------------------|-----------------------------------|
+| cli.js            | Main entry point for npx commands |
+| forge.sh          | Core forge command router         |
+| forge-setup.sh    | Setup wizard                      |
+| forge-spawn.sh    | Spawn agents in terminals         |
+| forge-daemon.sh   | Background daemon                 |
+| forge.cmd         | Windows batch wrapper             |
+
+These are typically not called directly - use the commands above instead.