Troubleshooting

Troubleshooting

VCP

Skill cannot find config

Run from the project root:

/vcp-init

Codex uses $vcp-init.

Hooks do not seem to run

Confirm Bun is installed and enable debug logging:

/vcp-config global set debug true

Then inspect .vcp/vcp.log.

Security gate false positive

Prefer fixing the code. If the pattern is genuinely not applicable, add the CWE to project ignore:

{ "ignore": ["CWE-798"] }

Codex

Skills are missing

Confirm the repo is installed at:

~/.codex/plugins/vcp

Run bun install in that directory and restart Codex.

MCP server is missing

Run /mcp. If a server is absent, add manual mcp_servers entries to ~/.codex/config.toml using absolute paths. See docs/codex-install.md.

MCP resources are not visible

Use paired tools:

• VCP: get_prompt, resolve_config
• Dev Buddy: get_run_state, get_stage_definition, list_presets
• MCP Doc: get_prompt, get_host_instructions

Dev Buddy

Config validation fails

bun plugins/dev-buddy/scripts/pipeline-config.ts validate --cwd /path/to/project

Common causes:

• missing preset in ~/.vcp/ai-presets.json
• unknown system_prompt
• active pipeline stage has no executor
• multi-executor stage ends with parallel: true

Legacy Ralph run is stale

Legacy stage-skill state lives under .vcp/plan/. Archive or remove the matching plan slug:

.vcp/plan/ralph-{slug}.md
.vcp/plan/ralph/{slug}/
.vcp/plan/.state/ralph-{slug}/

Do not delete unrelated active runs.

MCP Ralph run is stale

MCP skeleton state lives under .vcp/ralph/<run-id>/. Use ralph_list and get_run_state to identify the run before removing it.

Build unit gets stuck

Inspect:

.vcp/plan/.state/ralph-{slug}/units/unit-N.json

Look for repeated mechanical context, review feedback, and attempt count. The unit may need manual intervention when identical failures repeat.

MCP Doc

Generated server is not found

Run /mcp-doc-init or $mcp-doc-init again. It should create .mcp/manifest.yml, .mcp/actions/, and .mcp.json.