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

$3

| Agent | Icon | Role |
|-------|------|------|
| Forge Master | ⚒️ | Chief Orchestrator - distributes tasks, tracks progress |
| Sentinel | 🛡️ | Code Reviewer - quality gates, adversarial review |

$3

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

$3

| Agent | Icon | Role |
|-------|------|------|
| Sage | 🏛️ | System Architect |
| Oracle | 🔮 | Requirements Analyst |
| Quartermaster | 📋 | Product Manager |

$3

| 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

$3

- Claude Code CLI (install)
- Windows Terminal (recommended) or any terminal with tabs
- Node.js 16+ (for npx installer)
- Git

$3

`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
`

$3

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
`

$3

`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 - 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