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 | |-------|------|------| | Architect | 🏛️ | System Architect | | 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
    ├── 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)
• Windows Terminal (recommended) or any terminal with tabs
• Node.js 16+ (for npx installer)
• Git

Quick Start

# 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:

cd _vibe-forge
./bin/forge.sh

Manual Setup

If you prefer not to use npx:

# 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

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