vibe-forge 0.8.3 → 0.8.6

package/README.md

@@ -1,211 +1,211 @@
-# Vibe Forge
-
-A multi-agent development orchestration system for terminal-native vibe coding.
-
-## What Is This?
-
-Vibe Forge transforms your terminal into a collaborative AI development environment. Multiple Claude agents, each with distinct personalities and specializations, work together to build software. You talk to a Planning Hub that coordinates the team, then spawn workers into separate terminal tabs to execute in parallel.
-
-```
-                         YOU
-                          |
-                    /forge plan
-                          |
-              +-----------+-----------+
-              |     PLANNING HUB     |
-              |  Oracle  Architect   |
-              |  Aegis   Pixel       |
-              |  Ember   Crucible    |
-              +-----------+-----------+
-                          |
-            /forge spawn <agent>
-                          |
-         +--------+-------+-------+--------+
-         |        |       |       |        |
-       Anvil   Furnace Crucible Temper  Scribe
-        FE       BE      QA    Review   Docs
-```
-
-## Install
-
-```bash
-npx vibe-forge init
-```
-
-This sets up Vibe Forge in your project: detects your platform, configures your terminal, creates project context files, and installs the `/forge` slash command into Claude Code.
-
-**Prerequisites:** [Claude Code CLI](https://claude.ai/download), Node.js 18+, Git
-
-## Quick Start
-
-```bash
-# Start the Planning Hub (multi-expert planning session)
-/forge
-
-# Or jump straight to planning a feature
-/forge plan user authentication
-
-# Spawn a worker agent in a new terminal tab
-/forge spawn anvil
-
-# Check what's happening
-/forge status
-
-# See all commands
-/forge help
-```
-
-## Agents
-
-### Planning Hub (Your Terminal)
-
-When you run `/forge`, a multi-voice planning session starts. These expert voices collaborate to help you scope, design, and decompose work:
-
-| Voice | Icon | Speaks When |
-|-------|------|-------------|
-| Forge Master | :fire: | Tasks, assignments, workflow, coordination |
-| Architect | :classical_building: | Architecture, patterns, tech decisions |
-| Aegis | :shield: | Auth, security, vulnerabilities |
-| Ember | :gear: | DevOps, CI/CD, deployment |
-| Pixel | :art: | UX, user flows, accessibility |
-| Oracle | :bar_chart: | Requirements, scope, priorities |
-| Crucible | :test_tube: | Edge cases, test strategy, quality |
-| Loki | :performing_arts: | Challenges assumptions, lateral thinking |
-
-### Worker Agents (Separate Terminals)
-
-Spawn these into new terminal tabs to execute tasks:
-
-| Agent | Aliases | Role |
-|-------|---------|------|
-| anvil | frontend, ui, fe | Frontend Developer |
-| furnace | backend, api, be | Backend Developer |
-| crucible | test, qa | Tester / QA |
-| scribe | docs, documentation | Documentation |
-| herald | release, deploy | Release Manager |
-| ember | devops, infra | DevOps Engineer |
-
-### Review Agents
-
-| Agent | Aliases | Role |
-|-------|---------|------|
-| temper | review, cr | Code Reviewer (compliance + correctness) |
-| crucible-x | adversarial, cx | Adversarial Reviewer (tries to break it) |
-
-### Specialists
-
-| Agent | Aliases | Role |
-|-------|---------|------|
-| architect | arch, sage | System Architect |
-| aegis | security, sec | Security Specialist |
-| pixel | ux, ui-design | UX Designer |
-| oracle | product, po | Product Owner |
-| loki | brainstorm, contrarian | Assumption Challenger |
-
-### Red Team
-
-| Agent | Aliases | Role |
-|-------|---------|------|
-| slag | redteam, pentest | Red Team Lead |
-| flux | infra-sec, chaos | Infrastructure Security |
-
-## How It Works
-
-### Planning Mode
-
-When you describe a goal, the Hub enters a 4-phase planning flow:
-
-1. **Discovery** - Oracle asks clarifying questions about users, goals, constraints
-2. **Decomposition** - Architect breaks the goal into epics with success metrics
-3. **Tasking** - Forge Master creates stories and tasks, assigns to agents
-4. **Commit** - Epic and task files written to disk, ready for workers
-
-### Task System
-
-Tasks flow through folders on disk. No database required.
-
-```
-pending/ -> in-progress/ -> completed/ -> review/ -> approved/ -> merged/
-                                            |
-                                     needs-changes/ (back to worker)
-```
-
-Workers pick up tasks from `pending/` on startup. Temper reviews completed work. The daemon routes tasks automatically.
-
-### Daemon
-
-An optional background daemon monitors the forge:
-
-```bash
-./bin/forge.sh daemon start    # Start background monitoring
-./bin/forge.sh daemon status   # Check what's happening
-./bin/forge.sh daemon stop     # Stop the daemon
-```
-
-The daemon provides:
-- Task routing between folders
-- Agent status tracking
-- Token budget warnings for long-running agents
-- Dependency resolution (respects `blocked_by` in task files)
-- Attention notifications when agents need help
-
-### Dashboard
-
-A web dashboard at `http://localhost:2800` shows:
-- Task counts and status
-- Agent activity feed
-- Issue detection
-- Real-time updates via WebSocket
-
-### Per-Project Customization
-
-Add agent-specific rules for your project in `context/agent-overrides/`:
-
-```markdown
-<!-- context/agent-overrides/anvil.md -->
-- Use Tailwind CSS, no custom CSS files
-- All components in src/components/ with PascalCase
-- Use shadcn/ui for base components
-```
-
-These rules are injected into the agent's system prompt at spawn time.
-
-## Project Structure
-
-```
-your-project/
-  _vibe-forge/
-    agents/           # Agent personalities (16 agents)
-    bin/              # CLI, daemon, dashboard, spawn scripts
-    config/           # agents.json, task templates
-    context/          # Project context, agent overrides
-    specs/            # Epics and stories
-    tasks/            # Task lifecycle folders
-    docs/             # Security, architecture, agent docs
-```
-
-## Commands Reference
-
-| Command | Description |
-|---------|-------------|
-| `/forge` | Start the Planning Hub |
-| `/forge plan <feature>` | Plan a feature with the full team |
-| `/forge status` | Show status dashboard |
-| `/forge spawn <agent>` | Spawn worker in new terminal |
-| `/forge task [desc]` | Create a new task |
-| `/forge redteam [scope]` | Launch red team engagement |
-| `/forge help` | Show all commands |
-
-## Security
-
-Vibe Forge uses a defense-in-depth permission model:
-
-1. **Allowlist** (`.claude/settings.json`) - Pre-approves safe operations
-2. **Heimdall** (pre-tool hook) - Enforces forge policies (branch protection, naming)
-3. **Claude Code prompts** - Anything not allowlisted still requires approval
-
-See [docs/security.md](docs/security.md) for the full security model.
-
-## License
-
-MIT
+# Vibe Forge
+
+A multi-agent development orchestration system for terminal-native vibe coding.
+
+## What Is This?
+
+Vibe Forge transforms your terminal into a collaborative AI development environment. Multiple Claude agents, each with distinct personalities and specializations, work together to build software. You talk to a Planning Hub that coordinates the team, then spawn workers into separate terminal tabs to execute in parallel.
+
+```
+                         YOU
+                          |
+                    /forge plan
+                          |
+              +-----------+-----------+
+              |     PLANNING HUB     |
+              |  Oracle  Architect   |
+              |  Aegis   Pixel       |
+              |  Ember   Crucible    |
+              +-----------+-----------+
+                          |
+            /forge spawn <agent>
+                          |
+         +--------+-------+-------+--------+
+         |        |       |       |        |
+       Anvil   Furnace Crucible Temper  Scribe
+        FE       BE      QA    Review   Docs
+```
+
+## Install
+
+```bash
+npx vibe-forge init
+```
+
+This sets up Vibe Forge in your project: detects your platform, configures your terminal, creates project context files, and installs the `/forge` slash command into Claude Code.
+
+**Prerequisites:** [Claude Code CLI](https://claude.ai/download), Node.js 18+, Git
+
+## Quick Start
+
+```bash
+# Start the Planning Hub (multi-expert planning session)
+/forge
+
+# Or jump straight to planning a feature
+/forge plan user authentication
+
+# Spawn a worker agent in a new terminal tab
+/forge spawn anvil
+
+# Check what's happening
+/forge status
+
+# See all commands
+/forge help
+```
+
+## Agents
+
+### Planning Hub (Your Terminal)
+
+When you run `/forge`, a multi-voice planning session starts. These expert voices collaborate to help you scope, design, and decompose work:
+
+| Voice | Icon | Speaks When |
+|-------|------|-------------|
+| Forge Master | :fire: | Tasks, assignments, workflow, coordination |
+| Architect | :classical_building: | Architecture, patterns, tech decisions |
+| Aegis | :shield: | Auth, security, vulnerabilities |
+| Ember | :gear: | DevOps, CI/CD, deployment |
+| Pixel | :art: | UX, user flows, accessibility |
+| Oracle | :bar_chart: | Requirements, scope, priorities |
+| Crucible | :test_tube: | Edge cases, test strategy, quality |
+| Loki | :performing_arts: | Challenges assumptions, lateral thinking |
+
+### Worker Agents (Separate Terminals)
+
+Spawn these into new terminal tabs to execute tasks:
+
+| Agent | Aliases | Role |
+|-------|---------|------|
+| anvil | frontend, ui, fe | Frontend Developer |
+| furnace | backend, api, be | Backend Developer |
+| crucible | test, qa | Tester / QA |
+| scribe | docs, documentation | Documentation |
+| herald | release, deploy | Release Manager |
+| ember | devops, infra | DevOps Engineer |
+
+### Review Agents
+
+| Agent | Aliases | Role |
+|-------|---------|------|
+| temper | review, cr | Code Reviewer (compliance + correctness) |
+| crucible-x | adversarial, cx | Adversarial Reviewer (tries to break it) |
+
+### Specialists
+
+| Agent | Aliases | Role |
+|-------|---------|------|
+| architect | arch, sage | System Architect |
+| aegis | security, sec | Security Specialist |
+| pixel | ux, ui-design | UX Designer |
+| oracle | product, po | Product Owner |
+| loki | brainstorm, contrarian | Assumption Challenger |
+
+### Red Team
+
+| Agent | Aliases | Role |
+|-------|---------|------|
+| slag | redteam, pentest | Red Team Lead |
+| flux | infra-sec, chaos | Infrastructure Security |
+
+## How It Works
+
+### Planning Mode
+
+When you describe a goal, the Hub enters a 4-phase planning flow:
+
+1. **Discovery** - Oracle asks clarifying questions about users, goals, constraints
+2. **Decomposition** - Architect breaks the goal into epics with success metrics
+3. **Tasking** - Forge Master creates stories and tasks, assigns to agents
+4. **Commit** - Epic and task files written to disk, ready for workers
+
+### Task System
+
+Tasks flow through folders on disk. No database required.
+
+```
+pending/ -> in-progress/ -> completed/ -> review/ -> approved/ -> merged/
+                                            |
+                                     needs-changes/ (back to worker)
+```
+
+Workers pick up tasks from `pending/` on startup. Temper reviews completed work. The daemon routes tasks automatically.
+
+### Daemon
+
+An optional background daemon monitors the forge:
+
+```bash
+./bin/forge.sh daemon start    # Start background monitoring
+./bin/forge.sh daemon status   # Check what's happening
+./bin/forge.sh daemon stop     # Stop the daemon
+```
+
+The daemon provides:
+- Task routing between folders
+- Agent status tracking
+- Token budget warnings for long-running agents
+- Dependency resolution (respects `blocked_by` in task files)
+- Attention notifications when agents need help
+
+### Dashboard
+
+A web dashboard at `http://localhost:2800` shows:
+- Task counts and status
+- Agent activity feed
+- Issue detection
+- Real-time updates via WebSocket
+
+### Per-Project Customization
+
+Add agent-specific rules for your project in `context/agent-overrides/`:
+
+```markdown
+<!-- context/agent-overrides/anvil.md -->
+- Use Tailwind CSS, no custom CSS files
+- All components in src/components/ with PascalCase
+- Use shadcn/ui for base components
+```
+
+These rules are injected into the agent's system prompt at spawn time.
+
+## Project Structure
+
+```
+your-project/
+  _vibe-forge/
+    agents/           # Agent personalities (16 agents)
+    bin/              # CLI, daemon, dashboard, spawn scripts
+    config/           # agents.json, task templates
+    context/          # Project context, agent overrides
+    specs/            # Epics and stories
+    tasks/            # Task lifecycle folders
+    docs/             # Security, architecture, agent docs
+```
+
+## Commands Reference
+
+| Command | Description |
+|---------|-------------|
+| `/forge` | Start the Planning Hub |
+| `/forge plan <feature>` | Plan a feature with the full team |
+| `/forge status` | Show status dashboard |
+| `/forge spawn <agent>` | Spawn worker in new terminal |
+| `/forge task [desc]` | Create a new task |
+| `/forge redteam [scope]` | Launch red team engagement |
+| `/forge help` | Show all commands |
+
+## Security
+
+Vibe Forge uses a defense-in-depth permission model:
+
+1. **Allowlist** (`.claude/settings.json`) - Pre-approves safe operations
+2. **Heimdall** (pre-tool hook) - Enforces forge policies (branch protection, naming)
+3. **Claude Code prompts** - Anything not allowlisted still requires approval
+
+See [docs/security.md](docs/security.md) for the full security model.
+
+## License
+
+MIT