vibe-forge 0.8.1 → 0.8.2

package/README.md

@@ -1,252 +1,210 @@
-# Vibe Forge ⚒️
+# Vibe Forge
 
 A multi-agent development orchestration system for terminal-native vibe coding.
 
-## Vision
+## 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, coordinated through a file-based task system.
+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.
 
 ```
-┌─────────────────────────────────────────────────────────────────┐
-│                         PLANNING HUB                            │
-│                  (Your main terminal session)                   │
-│                                                                 │
-│   You + Architect · Aegis · Ember · Pixel · Oracle              │
-└─────────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                       PLANNING HUB 🔥                          │
-│              Task Distribution & Orchestration                  │
-└─────────────────────────────────────────────────────────────────┘
-                              │
-         ┌────────────┬───────┴───────┬────────────┐
-         ▼            ▼               ▼            ▼
-    ┌─────────┐  ┌─────────┐    ┌─────────┐  ┌─────────┐
-    │ Anvil   │  │ Furnace │    │Crucible │  │Sentinel │
-    │   🔨    │  │   🔥   │    │   🧪    │  │   🛡️   │
-    │Frontend │  │ Backend │    │ Testing │  │ Review  │
-    └─────────┘  └─────────┘    └─────────┘  └─────────┘
+                         YOU
+                          |
+                    /forge plan
+                          |
+              +-----------+-----------+
+              |     PLANNING HUB     |
+              |  Oracle  Architect   |
+              |  Aegis   Pixel       |
+              |  Ember   Crucible    |
+              +-----------+-----------+
+                          |
+            /forge spawn <agent>
+                          |
+         +--------+-------+-------+--------+
+         |        |       |       |        |
+       Anvil   Furnace Crucible Temper  Scribe
+        FE       BE      QA    Review   Docs
 ```
 
-## Key Features
+## Install
 
-- **Personality-driven agents** - Each agent has a distinct voice, expertise, and decision-making style
-- **File-based task coordination** - Reliable, debuggable, no WebSocket complexity
-- **Token-efficient design** - Context stored locally, minimal wire traffic
-- **Terminal-native** - Built for Windows Terminal, works with any terminal supporting tabs
+```bash
+npx vibe-forge init
+```
 
-## Agents
+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.
 
-### Core Agents (Always Running)
+**Prerequisites:** [Claude Code CLI](https://claude.ai/download), Node.js 18+, Git
 
-| Agent | Icon | Role |
-|-------|------|------|
-| Planning Hub | 🔥 | Chief Orchestrator - distributes tasks, tracks progress |
-| Sentinel | 🛡️ | Code Reviewer - quality gates, adversarial review |
+## Quick Start
 
-### Worker Agents (Per-Task)
+```bash
+# Start the Planning Hub (multi-expert planning session)
+/forge
 
-| Agent | Icon | Role |
-|-------|------|------|
-| Anvil | 🔨 | Frontend Dev - components, UI, styling |
-| Furnace | 🔥 | Backend Dev - APIs, database, services |
-| Crucible | 🧪 | Tester/QA - tests, bug hunting |
-| Scribe | 📜 | Documentation - docs, README, API specs |
-| Herald | 📯 | Release Manager - versioning, deployment |
+# Or jump straight to planning a feature
+/forge plan user authentication
 
-### Planning Hub Voices (Your Terminal)
+# Spawn a worker agent in a new terminal tab
+/forge spawn anvil
 
-The Planning Hub is a **multi-voice planning session** -- not separate agents. When you run `/forge`, these expert voices collaborate in a single session:
+# Check what's happening
+/forge status
 
-| Voice | Icon | Expertise |
-|-------|------|-----------|
-| Forge Master | 🔥 | Orchestration & task coordination |
-| Architect | 🏛️ | Technical design & architecture |
-| Aegis | 🔒 | Security & risk |
-| Ember | ⚙️ | DevOps & infrastructure |
-| Pixel | 🎨 | User experience & design |
-| Oracle | 📊 | Requirements & scope |
-| Crucible | 🧪 | Quality & edge cases |
+# See all commands
+/forge help
+```
 
-### Specialists (On-Demand)
+## Agents
 
-| Agent | Icon | Role |
-|-------|------|------|
-| Architect | 🏛️ | System Architect |
-| Ember | ⚙️ | DevOps/Infrastructure |
-| Aegis | 🔒 | Security Specialist |
-| Pixel | 🎨 | UX Designer |
-| Oracle | 🔮 | Product Owner / Requirements |
-| Loki | 🎭 | Lateral Thinker, Assumption Challenger |
+### Planning Hub (Your Terminal)
 
-### Red Team (On-Demand)
+When you run `/forge`, a multi-voice planning session starts. These expert voices collaborate to help you scope, design, and decompose work:
 
-| Agent | Icon | Role |
-|-------|------|------|
-| Slag | 💀 | Red Team Lead - OWASP, auth attacks, engagement reporting |
-| Flux | ⚡ | Red Team Operator - dependency CVEs, CI/CD, supply chain |
+| 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 |
 
-## Project Structure
+### Worker Agents (Separate Terminals)
 
-```
-vibe-forge/
-├── agents/                    # Agent definitions
-│   ├── planning-hub/
-│   │   ├── personality.md     # Identity, voice, principles
-│   │   ├── capabilities.md    # Commands, tools, decisions
-│   │   └── context-template.md # Session startup context
-│   ├── sentinel/
-│   ├── anvil/
-│   ├── furnace/
-│   ├── crucible/
-│   └── ...
-├── tasks/                     # Task lifecycle folders
-│   ├── pending/               # New tasks waiting for pickup
-│   ├── in-progress/           # Currently being worked on
-│   ├── completed/             # Done, ready for review
-│   ├── review/                # Under Sentinel review
-│   ├── approved/              # Passed review
-│   ├── needs-changes/         # Review feedback to address
-│   └── merged/                # Archive
-├── specs/                     # Planning documents
-│   ├── epics/
-│   └── stories/
-├── context/                   # Shared context files
-│   ├── project-context.md     # Tech stack, patterns, rules
-│   └── forge-state.yaml       # Current forge status
-└── config/                    # Configuration
-    ├── agents.json            # Agent roster (source of truth)
-    ├── agent-manifest.yaml    # Agent documentation (non-normative)
-    ├── task-template.md       # Task file template
-    └── task-types.yaml        # Task routing rules
-```
+Spawn these into new terminal tabs to execute tasks:
 
-## Task Lifecycle
+| 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 |
 
-```
-┌─────────┐    ┌─────────────┐    ┌───────────┐    ┌────────┐
-│ pending │ -> │ in-progress │ -> │ completed │ -> │ review │
-└─────────┘    └─────────────┘    └───────────┘    └────────┘
-                                                        │
-                     ┌──────────────┐                   │
-                     │ needs-changes│ <────────────────┤
-                     └──────────────┘                   │
-                            │                          │
-                            ▼                          ▼
-                     ┌─────────────┐             ┌──────────┐
-                     │ in-progress │             │ approved │
-                     └─────────────┘             └──────────┘
-                                                       │
-                                                       ▼
-                                                 ┌─────────┐
-                                                 │ merged  │
-                                                 └─────────┘
-```
+### Review Agents
 
-## Getting Started
+| Agent | Aliases | Role |
+|-------|---------|------|
+| temper | review, cr | Code Reviewer (compliance + correctness) |
+| crucible-x | adversarial, cx | Adversarial Reviewer (tries to break it) |
 
-### Prerequisites
+### Specialists
 
-- Claude Code CLI ([install](https://claude.ai/download))
-- Windows Terminal (recommended) or any terminal with tabs
-- Node.js 16+ (for npx installer)
-- Git
+| 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 |
 
-### Quick Start
+### Red Team
 
-```bash
-# In your project directory
-npx vibe-forge init
-```
+| Agent | Aliases | Role |
+|-------|---------|------|
+| slag | redteam, pentest | Red Team Lead |
+| flux | infra-sec, chaos | Infrastructure Security |
 
-This will:
+## How It Works
 
-1. Clone Vibe Forge into `_vibe-forge/`
-2. Detect your platform and terminal
-3. Set up the daemon and configuration
-4. Create a project context file
+### Planning Mode
 
-Then start the Planning Hub:
+When you describe a goal, the Hub enters a 4-phase planning flow:
 
-```bash
-cd _vibe-forge
-./bin/forge.sh
-```
+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
 
-### Manual Setup
+### Task System
 
-If you prefer not to use npx:
+Tasks flow through folders on disk. No database required.
 
-```bash
-# Clone into your project
-git clone https://github.com/sugar-crash-studios/vibe-forge.git _vibe-forge
+```
+pending/ -> in-progress/ -> completed/ -> review/ -> approved/ -> merged/
+                                            |
+                                     needs-changes/ (back to worker)
+```
 
-# Run setup
-cd _vibe-forge
-./bin/forge-setup.sh
+Workers pick up tasks from `pending/` on startup. Temper reviews completed work. The daemon routes tasks automatically.
 
-# Start the Planning Hub
-./bin/forge.sh
-```
+### Daemon
 
-### Updating
+An optional background daemon monitors the forge:
 
 ```bash
-npx vibe-forge update
+./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
 ```
 
-## Slash Commands
+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
 
-When using Claude Code inside your project, use the `/forge` command:
+### Dashboard
 
-```
-/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 redteam [scope]  - Launch red team engagement
-/forge help             - Show available commands
-```
+A web dashboard at `http://localhost:2800` shows:
+- Task counts and status
+- Agent activity feed
+- Issue detection
+- Real-time updates via WebSocket
 
-Agents (with aliases):
+### Per-Project Customization
 
-| 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 |
-| slag | redteam, pentest | Red Team Lead |
-| flux | infra-sec, chaos | Red Team Operator |
+Add agent-specific rules for your project in `context/agent-overrides/`:
 
-Use either the forge name or any alias: `/forge spawn frontend` or `/forge spawn anvil`
+```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
+```
 
-Red team engagements: `/forge redteam [scope]`
+These rules are injected into the agent's system prompt at spawn time.
 
-## Token Efficiency
+## Project Structure
 
-Vibe Forge is designed for minimal token usage:
+```
+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
+```
 
-1. **Local context** - Agents read from files, not conversation history
-2. **Task files as truth** - Instructions in files, not repeated in chat
-3. **Reference, don't duplicate** - Point to paths, don't paste contents
-4. **Batch updates** - One status report per cycle, not per task
-5. **Exception-based** - Report problems, not smooth operations
+## Commands Reference
 
-## Philosophy
+| 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 |
 
-> "A forge is not a factory. Each piece is crafted with intention."
+## Security
 
-Vibe Forge embraces the craft of software development. Each agent brings expertise and personality to their work. The goal isn't maximum automation - it's maximum collaboration between human and AI.
+Vibe Forge uses a defense-in-depth permission model:
 
-## Acknowledgments
+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
 
-Inspired by BMAD (Business Model-Agnostic Development) methodology and its multi-agent workflow system.
+See [docs/security.md](docs/security.md) for the full security model.
 
 ## License