vibe-forge 0.3.12 → 0.8.1

package/README.md

@@ -1,230 +1,253 @@
-# Vibe Forge ⚒️
-
-A multi-agent development orchestration system for terminal-native vibe coding.
-
-## Vision
-
-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.
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                         PLANNING HUB                            │
-│                  (Your main terminal session)                   │
-│                                                                 │
-│   You + Sage (Architect) + Oracle (Analyst) + Quartermaster (PM)│
-└─────────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                        FORGE MASTER ⚒️                          │
-│              Task Distribution & Orchestration                  │
-└─────────────────────────────────────────────────────────────────┘
-                              │
-         ┌────────────┬───────┴───────┬────────────┐
-         ▼            ▼               ▼            ▼
-    ┌─────────┐  ┌─────────┐    ┌─────────┐  ┌─────────┐
-    │ Anvil   │  │ Furnace │    │Crucible │  │Sentinel │
-    │   🔨    │  │   🔥   │    │   🧪    │  │   🛡️   │
-    │Frontend │  │ Backend │    │ Testing │  │ Review  │
-    └─────────┘  └─────────┘    └─────────┘  └─────────┘
-```
-
-## Key Features
-
-- **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
-
-## Agents
-
-### Core Agents (Always Running)
-
-| Agent | Icon | Role |
-|-------|------|------|
-| Forge Master | ⚒️ | Chief Orchestrator - distributes tasks, tracks progress |
-| Sentinel | 🛡️ | Code Reviewer - quality gates, adversarial review |
-
-### Worker Agents (Per-Task)
-
-| 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 |
-
-### Planning Hub Agents (Your Terminal)
-
-| Agent | Icon | Role |
-|-------|------|------|
-| Sage | 🏛️ | System Architect |
-| Oracle | 🔮 | Requirements Analyst |
-| Quartermaster | 📋 | Product Manager |
-
-### Specialists (On-Demand)
-
-| Agent | Icon | Role |
-|-------|------|------|
-| Ember | ⚙️ | DevOps/Infrastructure |
-| Aegis | 🔒 | Security Specialist |
-
-## Project Structure
-
-```
-vibe-forge/
-├── agents/                    # Agent definitions
-│   ├── forge-master/
-│   │   ├── 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
-    ├── agent-manifest.yaml    # Agent roster
-    ├── task-template.md       # Task file template
-    └── task-types.yaml        # Task routing rules
-```
-
-## Task Lifecycle
-
-```
-┌─────────┐    ┌─────────────┐    ┌───────────┐    ┌────────┐
-│ pending │ -> │ in-progress │ -> │ completed │ -> │ review │
-└─────────┘    └─────────────┘    └───────────┘    └────────┘
-                                                        │
-                     ┌──────────────┐                   │
-                     │ needs-changes│ <────────────────┤
-                     └──────────────┘                   │
-                            │                          │
-                            ▼                          ▼
-                     ┌─────────────┐             ┌──────────┐
-                     │ in-progress │             │ approved │
-                     └─────────────┘             └──────────┘
-                                                       │
-                                                       ▼
-                                                 ┌─────────┐
-                                                 │ merged  │
-                                                 └─────────┘
-```
-
-## Getting Started
-
-### Prerequisites
-
-- Claude Code CLI ([install](https://claude.ai/download))
-- Windows Terminal (recommended) or any terminal with tabs
-- Node.js 16+ (for npx installer)
-- Git
-
-### Quick Start
-
-```bash
-# In your project directory
-npx vibe-forge init
-```
-
-This will:
-
-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
-
-Then start the Planning Hub:
-
-```bash
-cd _vibe-forge
-./bin/forge.sh
-```
-
-### Manual Setup
-
-If you prefer not to use npx:
-
-```bash
-# Clone into your project
-git clone https://github.com/SpasticPalate/vibe-forge.git _vibe-forge
-
-# Run setup
-cd _vibe-forge
-./bin/forge-setup.sh
-
-# Start the Planning Hub
-./bin/forge.sh
-```
-
-### Updating
-
-```bash
-npx vibe-forge update
-```
-
-## Slash Commands
-
-When using Claude Code inside your project, use the `/forge` command:
-
-```
-/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 available commands
-```
-
-Agents (with aliases):
-
-| 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 |
-
-Use either the forge name or any alias: `/forge spawn frontend` or `/forge spawn anvil`
-
-## Token Efficiency
-
-Vibe Forge is designed for minimal token usage:
-
-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
-
-## Philosophy
-
-> "A forge is not a factory. Each piece is crafted with intention."
-
-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.
-
-## Acknowledgments
-
-Inspired by BMAD (Business Model-Agnostic Development) methodology and its multi-agent workflow system.
-
-## License
-
-MIT
+# Vibe Forge ⚒️
+
+A multi-agent development orchestration system for terminal-native vibe coding.
+
+## Vision
+
+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.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         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  │
+    └─────────┘  └─────────┘    └─────────┘  └─────────┘
+```
+
+## Key Features
+
+- **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
+
+## Agents
+
+### Core Agents (Always Running)
+
+| Agent | Icon | Role |
+|-------|------|------|
+| Planning Hub | 🔥 | Chief Orchestrator - distributes tasks, tracks progress |
+| Sentinel | 🛡️ | Code Reviewer - quality gates, adversarial review |
+
+### Worker Agents (Per-Task)
+
+| 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 |
+
+### Planning Hub Voices (Your Terminal)
+
+The Planning Hub is a **multi-voice planning session** -- not separate agents. When you run `/forge`, these expert voices collaborate in a single session:
+
+| 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 |
+
+### Specialists (On-Demand)
+
+| Agent | Icon | Role |
+|-------|------|------|
+| Architect | 🏛️ | System Architect |
+| Ember | ⚙️ | DevOps/Infrastructure |
+| Aegis | 🔒 | Security Specialist |
+| Pixel | 🎨 | UX Designer |
+| Oracle | 🔮 | Product Owner / Requirements |
+| Loki | 🎭 | Lateral Thinker, Assumption Challenger |
+
+### Red Team (On-Demand)
+
+| Agent | Icon | Role |
+|-------|------|------|
+| Slag | 💀 | Red Team Lead - OWASP, auth attacks, engagement reporting |
+| Flux | ⚡ | Red Team Operator - dependency CVEs, CI/CD, supply chain |
+
+## Project Structure
+
+```
+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
+```
+
+## Task Lifecycle
+
+```
+┌─────────┐    ┌─────────────┐    ┌───────────┐    ┌────────┐
+│ pending │ -> │ in-progress │ -> │ completed │ -> │ review │
+└─────────┘    └─────────────┘    └───────────┘    └────────┘
+                                                        │
+                     ┌──────────────┐                   │
+                     │ needs-changes│ <────────────────┤
+                     └──────────────┘                   │
+                            │                          │
+                            ▼                          ▼
+                     ┌─────────────┐             ┌──────────┐
+                     │ in-progress │             │ approved │
+                     └─────────────┘             └──────────┘
+                                                       │
+                                                       ▼
+                                                 ┌─────────┐
+                                                 │ merged  │
+                                                 └─────────┘
+```
+
+## Getting Started
+
+### Prerequisites
+
+- Claude Code CLI ([install](https://claude.ai/download))
+- Windows Terminal (recommended) or any terminal with tabs
+- Node.js 16+ (for npx installer)
+- Git
+
+### Quick Start
+
+```bash
+# In your project directory
+npx vibe-forge init
+```
+
+This will:
+
+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
+
+Then start the Planning Hub:
+
+```bash
+cd _vibe-forge
+./bin/forge.sh
+```
+
+### Manual Setup
+
+If you prefer not to use npx:
+
+```bash
+# Clone into your project
+git clone https://github.com/sugar-crash-studios/vibe-forge.git _vibe-forge
+
+# Run setup
+cd _vibe-forge
+./bin/forge-setup.sh
+
+# Start the Planning Hub
+./bin/forge.sh
+```
+
+### Updating
+
+```bash
+npx vibe-forge update
+```
+
+## Slash Commands
+
+When using Claude Code inside your project, use the `/forge` command:
+
+```
+/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
+```
+
+Agents (with aliases):
+
+| 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 |
+
+Use either the forge name or any alias: `/forge spawn frontend` or `/forge spawn anvil`
+
+Red team engagements: `/forge redteam [scope]`
+
+## Token Efficiency
+
+Vibe Forge is designed for minimal token usage:
+
+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
+
+## Philosophy
+
+> "A forge is not a factory. Each piece is crafted with intention."
+
+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.
+
+## Acknowledgments
+
+Inspired by BMAD (Business Model-Agnostic Development) methodology and its multi-agent workflow system.
+
+## License
+
+MIT