codecartographer

Driving CodeCartographer

CodeCartographer is a pipeline state machine, not an agent. It hands you a phase prompt, checks the artifact you produce against that phase's criteria, and gates completion. It never reads your repository and never writes your findings — you do that.

Three roles, and you hold two of them:

Role	Who	Does
State machine	the MCP server	phase order, prompts, validation parsing, completion gate, canonical state
Orchestrator	you	pick the pipeline, drive the loop, choose an executor, verify, and hold the cross-phase duties (references/orchestration.md)
Executor	you, or a model you delegate to	read the repo, write the phase artifact

Being the orchestrator does not preclude executing phases yourself — a single chat driving these tools inline is the normal case, and it holds both the Orchestrator and Executor rows. What makes a run orchestrated is performing the phase-boundary duties (convention promotion, open-question re-triage, contradiction sweeps, gap routing), not delegating the work. If the workspace GUIDE.md predates this contract and says the orchestrator must not execute phases, trust this guide.

The drive loop

codecarto_status  →  codecarto_init (first time only)
                          ↓
        ┌──────── codecarto_next ────────┐
        │              ↓                  │
        │         execute the phase       │
        │       (write primary output)    │
        │              ↓                  │
        │      write the phase handoff    │
        │              ↓                  │
        │       codecarto_validate        │
        │              ↓                  │
        │       codecarto_complete        │
        └───────── repeat until ──────────┘
             status reports "complete"

1. codecarto_status — always start here. It reports the active pipeline, progress, next action, and any scaffold-staleness warning. Every tool takes an absolute cwd pointing at the target repository.
2. codecarto_init — only when no .codecarto/ exists. Choose the pipeline deliberately (see references/pipeline-selection.md). Never pass force: true without the user's explicit approval; it moves an existing workspace, findings and all, to a backup directory.
3. codecarto_next — returns the prompt for the next eligible phase. It returns text; it does not execute anything. Use codecarto_phase only to force a specific phase out of order, and only when the user asked for that.
4. Execute — see "Executing a phase" below.
5. Write the handoff — see "The handoff contract" below. This is the step integrations most often miss, and completion now refuses without it.
6. codecarto_validate — parses the validation block you appended to the primary output. Returns PASS, PASS WITH GAPS, FAIL, or MISSING.
7. codecarto_complete — marks the phase done, applies your handoff to canonical state, and writes the closeout and THREAD_LOG.md entry. It refuses anything worse than PASS WITH GAPS.