Dev Buddy Configuration

Dev Buddy Configuration

Config File

Location: ~/.vcp/dev-buddy.json

Format: v5 (Ralph loop architecture). Auto-migrated from v4/v3/v2 on first load with backup.

Management: Use /dev-buddy-config web portal or edit JSON directly.

v5 Config Schema

{
  "version": "5.0",
  "stages": {
    "discovery": {
      "executors": [{ "system_prompt": "discoverer", "preset": "anthropic-subscription", "model": "sonnet" }]
    },
    "ralph-requirements": {
      "executors": [{ "system_prompt": "ralph-requirements-analyst", "preset": "anthropic-subscription", "model": "opus" }]
    },
    "decomposition": {
      "executors": [{ "system_prompt": "decomposer", "preset": "anthropic-subscription", "model": "opus" }]
    },
    "ralph-build": {
      "executors": [{ "system_prompt": "unit-builder", "preset": "anthropic-subscription", "model": "sonnet" }]
    },
    "ralph-code-review": {
      "executors": [{ "system_prompt": "ralph-code-reviewer", "preset": "anthropic-subscription", "model": "sonnet" }]
    },
    "ralph-uat": {
      "executors": [{ "system_prompt": "uat-evaluator", "preset": "anthropic-subscription", "model": "sonnet" }]
    },
    "unit-review": { "executors": [] }
  },
  "pipelines": {
    "ralph": ["discovery", "ralph-requirements", "decomposition", "ralph-build", "ralph-code-review", "ralph-uat"]
  },
  "max_iterations": 10,
  "max_build_attempts": 3,
  "max_outer_iterations": 3
}

Config Sections

Stages

7 stage types for the Ralph loop (6 pipeline + 1 optional), each with an ordered list of inline executor definitions:

Stage Type	Purpose	Default Role Prompt	Default Model
discovery	Explore codebase and running app	discoverer	sonnet
ralph-requirements	Define ACs + design UAT scenarios	ralph-requirements-analyst	opus
decomposition	Break feature into testable units	decomposer	opus
ralph-build	Implement one unit at a time	unit-builder	sonnet
ralph-code-review	Multi-AI semantic drift detection	ralph-code-reviewer	sonnet
ralph-uat	Execute UAT + mechanical backpressure	uat-evaluator	sonnet
unit-review (optional)	Per-unit AC verification after backpressure	unit-reviewer	— (empty = disabled)

Executor Format

Executors are defined inline within each stage (not as top-level named objects):

{
  "system_prompt": "ralph-code-reviewer",
  "preset": "anthropic-subscription",
  "model": "sonnet",
  "parallel": true
}

Field	Required	Description
system_prompt	Yes	Name of the role prompt (from system-prompts/built-in/ or ~/.vcp/system-prompts/)
preset	Yes	AI preset name (from ~/.vcp/ai-presets.json)
model	Yes	Model identifier (validated against preset's models list)
parallel	No	Adjacent parallel executors run simultaneously (default: sequential)

Validation Rules

• Singleton stages: ralph-build and ralph-uat allow maximum 1 executor. These stages require single-executor dispatch for deterministic builds and evaluation.
• Synthesizer rule: If a stage has more than 1 executor, the last executor must have parallel: false (or omit parallel). It acts as the synthesizer.
• Active pipeline stages: Every stage referenced in the pipeline must have at least 1 executor.
• Parallel field: Must be boolean when present.

Pipeline

v5 has a single ralph pipeline defining the stage execution order:

{
  "pipelines": {
    "ralph": ["discovery", "ralph-requirements", "decomposition", "ralph-build", "ralph-code-review", "ralph-uat"]
  }
}

The Ralph orchestrator (/dev-buddy-ralph) manages the loop logic (per-unit build retries + outer UAT loop) — the pipeline array defines the linear stage sequence, and the orchestrator handles branching based on review/UAT verdicts. Per-unit retries are fully mechanical via build-loop-runner.ts --unit N — the orchestrator calls it once per unit, and the runner handles internal retries: dispatches the executor via stage-runner.ts, runs backpressure, optionally runs per-unit semantic review (if unit-review is configured), and writes unit status to disk.

Settings

Field	Default	Description
max_iterations	10	Maximum fix/re-review iterations across all stages
max_build_attempts	3	Maximum retry attempts per unit in the build stage
max_outer_iterations	3	Maximum UAT -> BUILD -> CODE REVIEW -> UAT outer loop cycles

Other Config Files

File	Purpose
~/.vcp/ai-presets.json	AI provider presets (subscription, API, CLI)
~/.vcp/system-prompts/*.md	Custom system prompts
~/.vcp/dev-buddy-chatroom.json	Chatroom participant config
.vcp/plan/ralph-{slug}.md	Master plan — status, discovery, requirements, units table
.vcp/plan/ralph/{slug}/unit-{N}.md	Per-unit plan — static LLM-authored spec + runner tail (status, attempts, review feedback, latest build attempt)

Migration

From v4

If your config has "version": "4.0", it auto-migrates on first load:

1. Old stage types (requirements, planning, plan-review, implementation, code-review, rca) are mapped to Ralph types
2. Named executor definitions are inlined into stages
3. Custom pipelines are replaced with the single ralph pipeline
4. max_tdd_iterations becomes max_build_attempts
5. v4 config backed up to ~/.vcp/dev-buddy.json.v4.backup

From v3

If your config has "version": "3.0", it auto-migrates through v4 to v5:

1. feature_pipeline and bugfix_pipeline are consolidated
2. v3 config backed up to ~/.vcp/dev-buddy.json.v3.backup

From v2

If your config lacks a "version" field, it auto-migrates through v3 and v4 to v5:

1. v2 config backed up to ~/.vcp/dev-buddy.json.v2.backup

No manual action needed for any migration.

CLI Commands

bun pipeline-config.ts validate-v4   # Validate current config
bun pipeline-config.ts migrate       # Explicitly trigger migration
bun system-prompts.ts list           # List all system prompts