@sugar-crash-studios/vibe-forge 0.4.0

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 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 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 vibe-forge version
+npx vibe-forge --version
+npx vibe-forge -v
+```
+
+### vibe-forge help
+
+Show help information.
+
+```bash
+npx vibe-forge help
+npx vibe-forge --help
+npx 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...
+
+  Forge Master  - 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.