Orchestrator¶

The conductor of the pipeline. It sequences the phases, remembers where a run is, and asks you before anything moves forward.

What it is¶

The orchestrator is not a subagent. It is the main Claude Code session itself, driven by the project's CLAUDE.md. It invokes one phase agent at a time, waits for it to finish, then decides what happens next.

Its work splits into two halves, and each half lives in a different place:

Neither half can replace the other. A skill cannot invoke a subagent or ask you a question. And state transitions should not be re-derived from prose every turn, where they can drift, so they are encoded once as a lookup table in a read-only script.

The pipeline¶

flowchart TD
    OA(["orchestrator"])
    OA -->|" 1. calls "| DA["discover-agent"]
    DA -->|" produces "| DR[("discover-report.md")]
    DR -->|" reviewed by "| OA
    OA -.->|" rejected → revise "| DA
    OA -->|" 2. approved → calls "| DETA["determine-agent"]
    DETA -->|" produces "| DETR[("modernization-plan.md")]
    DETR -->|" reviewed by "| OA
    OA -.->|" rejected → revise "| DETA
    OA -->|" 3. testability < 80% → calls "| TA["test-agent"]
    TA -->|" produces "| TR[("tests + testability-report.md")]
    TR -->|" reviewed by "| OA
    OA -.->|" rejected → revise "| TA
    OA -->|" 4. testability ≥ 80% → calls "| CA["coding-agent"]
    CA -->|" once the build passes "| MP[("upgrade + modernization-summary-report.md")]

You approve each phase's report before the next one starts. Test runs only when the testability score is below the threshold. Code ends with a branch ready for your review.

Checkpoints¶

Building blocks¶

Every agent also uses the orchestrator skill to read and write its own state file.

Who does what¶

Scripts write full output to log files and return a single status line. Agents read finished summaries, never raw build output, so their context stays small.

How a turn works¶

sequenceDiagram
    actor You
    participant O as Orchestrator (CLAUDE.md)
    participant T as orchestrator-turn.sh
    participant A as Phase agent
    participant S as .modernization/

    You->>O: "Start the modernization pipeline."
    O->>S: state-init.sh (first run only)
    loop until DONE or stopped
        O->>T: What next?
        T->>S: read current_state (+ score or attempts)
        T-->>O: one action
        alt RUN_AGENT
            O->>S: set phase to RUNNING
            O->>A: invoke (with rejection reason or retry context)
            A->>S: write artifacts and phase state.json
            A-->>O: short conclusion
            O->>S: append session record, set next state
        else AWAIT_APPROVAL
            O->>You: report summary: approve or reject?
            You-->>O: decision (+ reason if rejected)
            O->>S: record decision, set next state
        else AWAIT_MITIGATION
            O->>You: the error: retry or abort?
        end
    end

orchestrator-turn.sh is read-only and returns exactly one of four actions:

The state machine is a lookup table, so the running pipeline cannot drift from the designed flow.

Configuration¶

All configuration lives in .claude/settings.json, in two blocks:

Pipeline settings¶

Discover also accepts a few advanced variables (scanner choice, task timeouts). See Discover.

Permissions¶

Least privilege: agents build, test and commit freely inside their own worktrees, and nowhere else.

Extending the pipeline with a new script? Add its exact path to allow, rather than broadening an existing pattern.

Changing configuration safely¶

State¶

The pipeline's memory lives in files, not in the chat. Close the session any time, resume later, and see exactly what happened.

Each phase records which steps it has finished. The orchestrator records which phase the run is in and what you have approved.

Where state lives¶

.modernization/
├── state.json                      Top-level run state (orchestrator)
├── discover/
│   ├── state.json                  Discover step progress
│   ├── discover-report.md          ► Report you approve
│   ├── summary.md                  Scan task table (state, duration)
│   ├── bom-catalog/                Reference BOM data for Determine
│   └── <task>/                     One folder per scan task, each with logs/
├── determine/
│   ├── state.json                  Includes outputs.testability_score
│   ├── modernization-plan.md       ► Report you approve
│   ├── dependency-report.md
│   ├── plugin-report.md
│   ├── testability-report.md
│   ├── testability-data.csv
│   ├── dependency-analysis/logs/
│   └── test-analysis/logs/
├── test/                           Only if the test phase runs
│   ├── state.json
│   ├── testability-report.md       ► Report you approve
│   ├── iterations/<n>/             Measurements per round
│   └── worktree/                   Git worktree with the new tests
├── code/
│   ├── state.json
│   ├── worktree/                   Git worktree with the upgrade
│   ├── upgrade-worklist.csv        Per-dependency status
│   ├── dependency-report.md        Refreshed after the upgrade
│   ├── change-log.md
│   └── build-report.md
└── modernization-summary-report.md ► Final summary

► marks the files written for people. Everything else is machine state, intermediate data or logs.

The state machine¶

stateDiagram-v2
    [*] --> INIT
    INIT --> DISCOVER_RUNNING
    DISCOVER_RUNNING --> DISCOVER_AWAITING_APPROVAL: report written
    DISCOVER_AWAITING_APPROVAL --> DETERMINE_RUNNING: approved
    DISCOVER_AWAITING_APPROVAL --> DISCOVER_RUNNING: rejected
    DETERMINE_RUNNING --> DETERMINE_AWAITING_APPROVAL: plan written
    DETERMINE_AWAITING_APPROVAL --> TEST_GATE_CHECK: approved
    DETERMINE_AWAITING_APPROVAL --> DETERMINE_RUNNING: rejected
    TEST_GATE_CHECK --> CODING_RUNNING: score ≥ threshold
    TEST_GATE_CHECK --> TEST_RUNNING: score below threshold
    TEST_RUNNING --> TEST_AWAITING_APPROVAL: threshold reached or cap hit
    TEST_AWAITING_APPROVAL --> CODING_RUNNING: approved
    TEST_AWAITING_APPROVAL --> TEST_RUNNING: rejected
    CODING_RUNNING --> DONE: build green
    CODING_RUNNING --> CODING_RUNNING: failed, attempts left
    CODING_RUNNING --> MITIGATION: failed, no attempts left
    DISCOVER_RUNNING --> FAILED: phase failed
    DETERMINE_RUNNING --> FAILED: phase failed
    TEST_RUNNING --> FAILED: phase failed
    FAILED --> MITIGATION
    state "FAILED / MITIGATION_WAIT" as MITIGATION
    DONE --> [*]

Who writes what¶

All writes go through state-set.sh or state-append-session.sh: write to a temp file, then rename. A killed process can never leave a half-written state file.

To watch these during a run, see monitoring.