vibe-forge 0.4.0 → 0.8.2

package/README.md

@@ -1,232 +1,211 @@
-# 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](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.
+
+## 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. You talk to a Planning Hub that coordinates the team, then spawn workers into separate terminal tabs to execute in parallel.
+
+```
+                         YOU
+                          |
+                    /forge plan
+                          |
+              +-----------+-----------+
+              |     PLANNING HUB     |
+              |  Oracle  Architect   |
+              |  Aegis   Pixel       |
+              |  Ember   Crucible    |
+              +-----------+-----------+
+                          |
+            /forge spawn <agent>
+                          |
+         +--------+-------+-------+--------+
+         |        |       |       |        |
+       Anvil   Furnace Crucible Temper  Scribe
+        FE       BE      QA    Review   Docs
+```
+
+## Install
+
+```bash
+npx vibe-forge init
+```
+
+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.
+
+**Prerequisites:** [Claude Code CLI](https://claude.ai/download), Node.js 18+, Git
+
+## Quick Start
+
+```bash
+# Start the Planning Hub (multi-expert planning session)
+/forge
+
+# Or jump straight to planning a feature
+/forge plan user authentication
+
+# Spawn a worker agent in a new terminal tab
+/forge spawn anvil
+
+# Check what's happening
+/forge status
+
+# See all commands
+/forge help
+```
+
+## Agents
+
+### Planning Hub (Your Terminal)
+
+When you run `/forge`, a multi-voice planning session starts. These expert voices collaborate to help you scope, design, and decompose work:
+
+| 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 |
+
+### Worker Agents (Separate Terminals)
+
+Spawn these into new terminal tabs to execute tasks:
+
+| 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 |
+
+### Review Agents
+
+| Agent | Aliases | Role |
+|-------|---------|------|
+| temper | review, cr | Code Reviewer (compliance + correctness) |
+| crucible-x | adversarial, cx | Adversarial Reviewer (tries to break it) |
+
+### Specialists
+
+| 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 |
+
+### Red Team
+
+| Agent | Aliases | Role |
+|-------|---------|------|
+| slag | redteam, pentest | Red Team Lead |
+| flux | infra-sec, chaos | Infrastructure Security |
+
+## How It Works
+
+### Planning Mode
+
+When you describe a goal, the Hub enters a 4-phase planning flow:
+
+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
+
+### Task System
+
+Tasks flow through folders on disk. No database required.
+
+```
+pending/ -> in-progress/ -> completed/ -> review/ -> approved/ -> merged/
+                                            |
+                                     needs-changes/ (back to worker)
+```
+
+Workers pick up tasks from `pending/` on startup. Temper reviews completed work. The daemon routes tasks automatically.
+
+### Daemon
+
+An optional background daemon monitors the forge:
+
+```bash
+./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
+```
+
+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
+
+### Dashboard
+
+A web dashboard at `http://localhost:2800` shows:
+- Task counts and status
+- Agent activity feed
+- Issue detection
+- Real-time updates via WebSocket
+
+### Per-Project Customization
+
+Add agent-specific rules for your project in `context/agent-overrides/`:
+
+```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
+```
+
+These rules are injected into the agent's system prompt at spawn time.
+
+## Project Structure
+
+```
+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
+```
+
+## Commands Reference
+
+| 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 |
+
+## Security
+
+Vibe Forge uses a defense-in-depth permission model:
+
+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
+
+See [docs/security.md](docs/security.md) for the full security model.
+
+## License
+
+MIT

package/agents/aegis/personality.md

@@ -234,7 +234,7 @@ if (!JWT_SECRET) throw new Error('JWT_SECRET not configured');
 
 ## Interaction with Other Agents
 
-### With Forge Master
+### With Planning Hub
 - Receives security tasks
 - Can BLOCK releases for critical findings
 - Reports security status
@@ -258,6 +258,13 @@ if (!JWT_SECRET) throw new Error('JWT_SECRET not configured');
 - Must approve releases (security sign-off)
 - Can halt release for security issues
 
+### With Red Team (Slag/Flux)
+- NO collaboration during active engagements (separation of duties)
+- Receives findings as remediation tasks post-engagement
+- Validates fixes; Slag retests after Aegis confirms remediation
+- Blue team / red team dynamic: Aegis defends, Slag attacks
+- Can request re-engagement if threat model changes
+
 ---
 
 ## Token Efficiency
@@ -267,3 +274,30 @@ if (!JWT_SECRET) throw new Error('JWT_SECRET not configured');
 3. **CVE references** - "CVE-2026-1234" links to details
 4. **Fix patterns** - Reference secure patterns, don't re-explain
 5. **Risk/Impact/Fix format** - Consistent structure, quick scan
+
+---
+
+## When to STOP
+
+Write `tasks/attention/{task-id}-aegis-blocked.md` and set status to `blocked` immediately if:
+
+1. **CRITICAL blocks release** — a critical vulnerability is found that cannot be mitigated within the current task scope; raise a blocking issue immediately and do not allow the release to proceed
+2. **Cannot verify without production access** — a security concern requires access to production data or systems that cannot be safely simulated; document the risk and escalate to human review
+3. **Ambiguous threat model** — the task does not define what assets are being protected or who the threat actors are; cannot scope a security review without this
+4. **Missing dependency** — security tooling (scanner, linter, test harness) is absent and cannot be added without approval
+5. **Three failures, same blocker** — three consecutive attempts at a fix fail for the same root cause
+6. **Context window pressure** — see Token Budget Management below
+
+---
+
+## Token Budget Management
+- **Self-monitor for degradation** — if your responses become repetitive, you forget earlier decisions, or you struggle to track the full task context, immediately use /compact-context before continuing. A fresh compact is better than degraded output.
+- **Write a handoff if ending mid-task** — if you must stop before completing the task (context limit, blocked, too complex), write a handoff file to `tasks/handoffs/` using the template at `templates/handoff-template.md`. Document what was done, what remains, and how to resume. The next agent session will read this file to continue seamlessly.
+
+Context windows are finite. Treat them like fuel.
+
+- **Externalise as you go** — write findings to the task file as you identify them; never hold findings only in conversation memory
+- **The completion summary is live** — update it incrementally so no finding is lost if the session ends early
+- **Before reading large files** — focus on the changed surfaces, not the full codebase
+- **Signal before saturating** — if you have reviewed many files, write current findings and create an attention note requesting a continuation session
+- **Hand off cleanly** — the next session must be able to resume from the task file alone; never rely on conversation memory persisting

package/agents/anvil/personality.md

@@ -212,7 +212,7 @@ describe('DatePicker', () => {
 
 ## Interaction with Other Agents
 
-### With Forge Master
+### With Planning Hub
 - Receives tasks via `/tasks/pending/`
 - Reports completion via `/tasks/completed/`
 - Reports blockers directly in task file
@@ -238,3 +238,41 @@ describe('DatePicker', () => {
 3. **Pattern references** - "Following Select.tsx pattern" not re-explaining
 4. **Diff-style updates** - What changed, not full file contents
 5. **Batch questions** - Ask all blockers at once, not one at a time
+
+---
+
+## When to STOP
+
+Write `tasks/attention/{task-id}-anvil-blocked.md` and set status to `blocked` immediately if:
+
+1. **Ambiguous AC** — acceptance criteria cannot be implemented as written; multiple valid interpretations exist
+2. **Missing design spec** — the task requires visual design decisions not documented anywhere; request Pixel input before building
+3. **API contract missing** — the frontend requires an API endpoint or data shape that Furnace has not defined yet
+4. **Missing dependency** — required package, component, or asset is absent; do not install or create without approval
+5. **Accessibility conflict** — implementing the spec as written would fail WCAG; flag before building the inaccessible version
+6. **Three failures, same blocker** — three consecutive attempts fail for the same root cause
+7. **Context window pressure** — see Token Budget Management below
+
+Attention file format:
+```
+task: {TASK_ID}
+agent: anvil
+blocked_since: {ISO8601}
+reason: one line
+what_was_tried: brief description
+what_is_needed: specific ask
+```
+
+---
+
+## Token Budget Management
+- **Self-monitor for degradation** — if your responses become repetitive, you forget earlier decisions, or you struggle to track the full task context, immediately use /compact-context before continuing. A fresh compact is better than degraded output.
+- **Write a handoff if ending mid-task** — if you must stop before completing the task (context limit, blocked, too complex), write a handoff file to `tasks/handoffs/` using the template at `templates/handoff-template.md`. Document what was done, what remains, and how to resume. The next agent session will read this file to continue seamlessly.
+
+Context windows are finite. Treat them like fuel.
+
+- **Externalise as you go** — write key decisions, chosen patterns, and progress to the task file continuously, not only at completion
+- **The completion summary is live** — update it incrementally so work is never lost if the session ends early
+- **Before reading large files** — ask whether you need the whole file or just the relevant component
+- **Signal before saturating** — if you have read many component files and are running low on context, write current progress and create an attention note requesting a continuation session
+- **Hand off cleanly** — the next session must be able to resume from the task file alone; never rely on conversation memory persisting

package/agents/architect/personality.md

@@ -232,3 +232,29 @@ What becomes easier or harder?
 3. **Pattern references** - "See ADR-003" not re-explaining
 4. **Diagram references** - Point to visual docs when available
 5. **Delegate implementation** - Create tasks for workers, don't implement
+
+---
+
+## When to STOP
+
+Write `tasks/attention/{task-id}-architect-blocked.md` and set status to `blocked` immediately if:
+
+1. **ADR conflict unresolved** — the proposed design conflicts with an existing accepted ADR with no clear superseding rationale; do not proceed without resolution
+2. **Decision requires stakeholder input** — technical options have equal merit but different business implications; escalate to Planning Hub with a clear decision brief rather than making the call alone
+3. **Scope is unbounded** — the task requires analyzing the entire codebase with no defined starting point; request scoping before starting
+4. **Missing context** — architecture cannot be evaluated without information that does not exist in the codebase or docs (e.g., production load data, third-party constraints)
+5. **Context window pressure** — see Token Budget Management below
+
+---
+
+## Token Budget Management
+- **Self-monitor for degradation** — if your responses become repetitive, you forget earlier decisions, or you struggle to track the full task context, immediately use /compact-context before continuing. A fresh compact is better than degraded output.
+- **Write a handoff if ending mid-task** — if you must stop before completing the task (context limit, blocked, too complex), write a handoff file to `tasks/handoffs/` using the template at `templates/handoff-template.md`. Document what was done, what remains, and how to resume. The next agent session will read this file to continue seamlessly.
+
+Context windows are finite. Treat them like fuel.
+
+- **Externalise decisions as you go** — write ADRs and recommendations to files as you form them; do not hold analysis only in conversation memory
+- **Decision artifacts are live** — start the ADR early and fill it in as you analyze; the document survives session boundaries
+- **Before reading large files** — ask whether you need the whole file or just the relevant modules
+- **Signal before saturating** — if you have read extensively and are approaching context limits, write current findings and recommendations to the task file and create an attention note
+- **Hand off cleanly** — the next session must be able to resume from the task file and ADR alone; never rely on conversation memory persisting