v0.4 migration¶

Ploidy 0.3 exposed a 12-tool MCP surface that mirrored the research protocol's phase state machine (independent → position → challenge → convergence → complete). That surface is great for context-asymmetry experiments where you need strict per-phase control. For everyday service use it generated a lot of "failed" responses — every sequencing mistake, stale session id, or skipped phase surfaced as a tool error.

v0.4 keeps the research protocol intact but introduces a single service entry point: debate(prompt, mode="auto" | "solo", ...).

Quick start¶

From a Claude Code slash command (recommended)¶

/ploidy Should we rewrite the ingestion pipeline in Rust?

The /ploidy command writes your deep-context analysis, spawns a fresh subagent for the zero-context side, calls debate(mode="solo"), and renders the synthesis. Nothing to install beyond the repo.

Calling the MCP tool directly¶

await debate(
    prompt="Should we rewrite the ingestion pipeline in Rust?",
    mode="auto",
    context_documents=["… project context …"],
)

For mode="auto" set PLOIDY_API_BASE_URL / PLOIDY_API_KEY so the server can generate both sides. For mode="solo" you supply both positions (and optionally both challenges) and no external API is needed:

await debate(
    prompt="…",
    mode="solo",
    deep_position="…",
    fresh_position="…",
)

Mapping from legacy tools¶

Legacy flow	v0.4 equivalent
`debate_start` → `debate_join` → `debate_position` × 2 → `debate_challenge` × 2 → `debate_converge`	single call to `debate(mode="auto")` or `debate(mode="solo")`
`debate_auto(...)`	`debate(mode="auto", ...)`
`debate_solo(...)`	`debate(mode="solo", ...)`
`debate_auto(..., pause_at="challenge")` → `debate_review(...)`	`debate(mode="auto", ..., pause_at="challenge")` → `debate_review(...)` (unchanged)

What remains on the legacy surface¶

Keep using the legacy tools when you need:

Two-terminal isolation — two independent MCP client sessions sharing a debate via debate_start / debate_join. Still the only option if you want strictly independent context windows (no shared process, no shared memory).
Research experiments — the phase state machine is exactly what experiments/run_experiment.py exercises. Keep those callers on the legacy tools; no changes needed.
Manual history/status inspection — debate_status, debate_history, debate_delete, debate_cancel continue to work for admin flows and the dashboard's read path.

Deprecation policy¶

v0.4 (this release): legacy tools keep working unchanged. Their docstrings carry a DEPRECATED (v0.4) marker so LLM callers pick debate when both are available.
v0.5: we will drop the pure MCP-tool variants that debate already covers (debate_auto, debate_solo). Two-terminal tools (debate_start / debate_join / debate_position / debate_challenge / debate_converge) and HITL (debate_review) stay indefinitely — they cover scenarios debate cannot.