npm package: @sugar-crash-studios/vibe-forge
Description: Multi-agent development orchestration system for terminal-native vibe coding
Author: sugar-crash-studios
Latest version: 0.8.0

# 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 @sugar-crash-studios/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 @sugar-crash-studios/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