Volt Framework

Lean agent framework for Claude Code — brownfield-first, inspired by BMAD Method.

Volt installs a team of 7 AI personas into your project. They plan features collaboratively (Party Mode), implement with strict discipline, review adversarially, and document everything — so you can focus on decisions, not process.

Install

npx volt-framework install

Or in a specific directory:

npx volt-framework install --dir ./my-project

Then open Claude Code in your project and run /volt:help.

What Gets Installed

your-project/
├── CLAUDE.md                       ← read automatically by Claude Code
├── .volt/
│   ├── config.yaml                 ← project config (type, integrations)
│   ├── registry.csv                ← command catalog
│   ├── agent-manifest.csv          ← persona metadata
│   ├── docs/                       ← context documents
│   │   ├── architecture.md
│   │   ├── tech-stack.md
│   │   ├── coding-standards.md
│   │   ├── source-tree.md
│   │   └── brownfield.md
│   ├── epics/                      ← epic specs (generated by /volt:new-task)
│   └── tasks/                      ← task breakdowns (generated by /volt:new-task)
└── .claude/commands/volt/          ← agent commands (18 total)

Two Core Flows

Greenfield (new project)

/volt:init-context → /volt:new-task → /volt:dev → /volt:review

Brownfield (existing codebase)

/volt:init-context → /volt:map-brownfield → /volt:new-task → /volt:dev → /volt:review

Each step runs in a fresh chat to avoid context pollution. Every command ends with a ready-to-copy handoff for the next step.

The Flow in Detail

flowchart TD
    START([New project or feature]) --> INIT["/volt:init-context\nFill context docs"]
    INIT --> TYPE{Project type?}

    TYPE -->|Greenfield| PLAN
    TYPE -->|Brownfield| SCAN["/volt:map-brownfield\nScan codebase → generate docs"]
    SCAN --> PLAN

    PLAN["/volt:new-task\nParty Mode planning"] --> PARTY["7 personas discuss:\nStark · Morpheus · Ripley\nWick · Dredd · Max · Jarvis"]

    PARTY --> TASKS["Generates:\n.volt/epics/EPIC-1-*.md\n.volt/tasks/TASK-1.1-*.md"]

    TASKS --> DEV["/volt:dev TASK-1.1\nWick implements"]
    DEV --> REVIEW["/volt:review\nAdversarial 3-layer review"]
    REVIEW --> NEXT{More tasks?}
    NEXT -->|Yes| DEV
    NEXT -->|No| DONE([Epic complete])

    style START fill:#2d6a4f,color:#fff
    style DONE fill:#2d6a4f,color:#fff
    style PARTY fill:#264653,color:#fff
    style DEV fill:#264653,color:#fff

The Quick Flow

For bug fixes and small changes — no planning needed:

flowchart LR
    A["/volt:quick-dev"] --> B["Clarify intent"] --> C["Plan + spec"] --> D["Implement"] --> E["Self-review"] --> F["Present"]

The 7 Personas

Every persona has a cinematic callsign and a distinct voice:

| Persona | Callsign | Role | Style | |---------|----------|------|-------| | PM | Stark | Scope, PRD, epics, stories | "What's the play?" — cuts scope, demands value | | Architect | Morpheus | Architecture, trade-offs, readiness | "I can only show you the door" — calm, pragmatic | | UX | Ripley | User flows, states, accessibility | Tells stories that make you FEEL the problem | | Dev | Wick | Implementation, tests, code | Ultra-precise, file paths and AC IDs only | | QA | Dredd | Tests, risk, regression | "I am the law" — nothing gets past | | DevOps | Max | Deploy, infra, rollback | "What happens when it all burns?" | | Tech Writer | Jarvis | Docs, diagrams, clarity | Translates complexity into simplicity |

Party Mode

When you run /volt:new-task, personas discuss naturally:

STARK (PM):

1. Why Google auth specifically? Apple too?
2. Scope: login only or account linking?
3. AC: user signs in with Google, sees dashboard

MORPHEUS (Architect):

1. Current auth uses JWT — OAuth is additive, not a rewrite
2. Trade-off: passport.js (proven, heavy) vs custom OAuth client (lighter)
3. auth.service.ts is protected — new file only, no modifications

Facilitator: Morpheus, does Wick's migration conflict with the protected zone?

MORPHEUS: No — additive column only. Existing schema untouched.

All Commands

Setup

| Command | What it does | |---------|-------------| | /volt:help | Detects project state, recommends next step | | /volt:init-context | Fill context docs + configure integrations | | /volt:map-brownfield | Scan existing codebase, generate docs automatically |

Planning

| Command | What it does | |---------|-------------| | /volt:new-task [#ID] | Party mode: 7 personas plan → epics + tasks | | /volt:quick-spec | Plan only — produce spec, don't implement |

Implementation

| Command | What it does | |---------|-------------| | /volt:dev [task] | Execute task with full discipline (Wick) | | /volt:quick-dev | Lightweight: clarify → implement → review → present | | /volt:review | Adversarial 3-layer code review |

Day-to-day

| Command | What it does | |---------|-------------| | /volt:standup | Daily briefing: task status, risks, priorities | | /volt:ask | Quick question from project context | | /volt:debug | Evidence-based bug investigation | | /volt:correct-course | Adjust tasks when requirements change |

Expert Personas (standalone)

| Command | Persona | Specialty | |---------|---------|-----------| | /volt:architect | Morpheus | Architecture, readiness, trade-offs | | /volt:pm | Stark | PRD, epics, stories, scope | | /volt:ux | Ripley | UX design, flows, accessibility | | /volt:qa | Dredd | Test generation, risk assessment | | /volt:devops | Max | Deploy, infra, observability | | /volt:tech-writer | Jarvis | Docs, validation, Mermaid diagrams |

How /volt:dev Works

Wick (the dev agent) follows strict execution discipline:

1. Read everything — task file + all context docs before touching code
2. Confirm patterns — brownfield: show coding standards, ask if exceptions apply
3. Present plan — files to create/modify, risks, order. Wait for approval
4. Implement — Red-Green-Refactor per task. Tests after each step. Mark [x] only when passing
5. Self-review — adversarial review of own code (blind + edge case + acceptance)
6. Dev Agent Record — document what was done, decisions, deviations, learnings
7. QA Risk Assessment — regression probability, affected systems, rollback complexity
8. Handoff — recommend next command for a fresh chat

Invariants:

• NEVER proceed with failing tests
• NEVER lie about test results
• NEVER touch files in "What NOT to change" without explicit confirmation
• NEVER skip tasks or reorder them

Greenfield vs Brownfield

| Behavior | Greenfield | Brownfield | |----------|-----------|------------| | Load brownfield.md | No | Yes, mandatory | | Pattern confirmation in /dev | Light | Mandatory + blocking | | QA risk assessment | Optional | Mandatory on completion | | Stop before touching risky file | No | Yes, blocking | | QA in party mode roster | Manual | Auto-joins medium+ | | /map-brownfield | N/A | Run first |

Task Lifecycle

stateDiagram-v2
    [*] --> draft: /volt:new-task creates epic
    draft --> ready: /volt:new-task expands task
    ready --> in_progress: /volt:dev starts
    in_progress --> done: /volt:dev completes
    done --> [*]: next task auto-expands

    in_progress --> blocked: blocker found
    blocked --> in_progress: blocker resolved

Tasks are .md files in .volt/tasks/ with tracked status, acceptance criteria, implementation plan, and dev agent record. Epics live in .volt/epics/ with progressive story expansion — only the next task gets expanded when the previous one is done.

Elicitation System

Party mode includes 50 advanced elicitation techniques across 10 categories:

• Risk: Pre-mortem, Red Team, Failure Mode Analysis, Chaos Monkey
• Exploration: First Principles, SCAMPER, Constraint Removal, What-If Scenarios
• Collaboration: Expert Panel, Debate Club, Cross-Functional War Room
• Technical: Architecture Decision Records, Rubber Duck Debugging, Algorithm Olympics
• Core: Socratic Questioning, 5 Whys, Critique & Refine

Presented as contextual options during planning — always opt-in, never forced.

Adaptive Interaction

Volt is efficient by default — proceeds without asking unless genuine input is needed. When you want to go deeper on any point, just say so and the agent shifts to interactive mode for that specific topic, then returns to efficient execution.

Genuine HALT points (varies per agent):

• Ambiguity that can't be safely resolved
• Conflicts with protected brownfield zones
• Test failures
• Scope changes affecting other tasks

Not a HALT point:

• Routine confirmations
• Intermediate results
• Standard workflow transitions

Tech Stack

• Runtime: Node.js 20+
• Language: TypeScript (strict)
• CLI: Commander
• Interactive UI: @clack/prompts
• Filesystem: fs-extra
• Config: js-yaml (YAML)

Update

npx volt-framework update

Updates commands and templates without overwriting your customized docs.

License

MIT