Skip to content

Parallel build

The docs site run, as its plan drew it. Six tasks have no incoming edge, so they start together.

flowchart LR
  T1["T1 skeleton"]
  T2["T2 facts: start, flows"]
  T3["T3 facts: run, sessions"]
  T4["T4 facts: reference"]
  T5["T5 style guide"]
  T6["T6 check_pages"]
  T7["T7 start pages"]
  T8["T8 flow pages"]
  T9["T9 run pages"]
  T10["T10 sessions pages"]
  T11["T11 reference pages"]
  T12["T12 publish"]
  T1 --> T7 & T8 & T9 & T10 & T11
  T2 --> T7 & T8
  T3 --> T9 & T10
  T4 --> T11
  T5 --> T7 & T8 & T9 & T10 & T11
  T6 --> T12
  T7 & T8 & T9 & T10 & T11 --> T12

Picture a kitchen. Several cooks start dishes that do not need each other. Only the plating waits for the dishes it plates.

Waves and the task graph. The machine plan draws an edge Tn --> Tm when Tm’s tests execute Tn’s code, or when Tm must read what Tn writes. Tasks with no incoming edges form the first wave and run together. A task that merely uses another’s interface does not wait. It builds against a stub and the e.g. examples in the plan. Waves are a planning view. The scheduler sends a task the moment its dependencies are checkpointed, with no barrier between waves.

Wave 0 holds the manifest, package inits, test config, shared error types and a stub for every interface another task consumes. implementer-haiku builds it. Tasks never wait for its checkpoint, because they build against the stubs.

Tiers. Lint picks the agent from config/routing.json, and nothing overrides it.

Tier Agent Gets Context limit
Sonnet (default) implementer every task that is not mechanical 80k
Haiku implementer-haiku Kind: mechanical tasks off the critical path 60k

The critical path is the longest chain of waiting tasks, so a slow task on it delays the run. It never gets Haiku. A task goes only to an idle agent of its own tier, and nothing queues behind a busy one.

  1. You watch. Nothing to answer. Open the agent map to see tasks and agents.

    Claude Code · ~/superlite
    ❯ /superlite:agents

    Wave 1 is six tasks at once: T1 skeleton, T2, T3 and T4 (three fact sheets), T5 style guide and T6 check_pages. superlite-cli dispatch packs every ready task into one message. They share no edge and own different files, so they cannot collide. The report later shows peak 6 at once, which is this wave.

    The dispatch command output: wave 0 for the Haiku task, then T6 and T5 and four more tasks fresh on Sonnet, followed by the ledger line “dispatched T1 T2 T3 T4 T5 T6”

    Real output: the dispatch lines that start the wave.

    The agent tail: five implementers and one researcher START within seconds of each other, then DONE lines follow

    Real output: six agents start together, and finish a few seconds apart.

  2. Wave 2 starts task by task. T7 to T11 are the page tasks. Each waits for T1, T5 and the facts file it writes from. This is the edge list the plan holds for T9, the run pages.

    docs/plans/2026-11-12-docs-site.md
    T1 --> T9
    T3 --> T9
    T5 --> T9

    These are content edges, the ruling from the orchestrator page: a page writer cannot guess the facts. T10 needed only T1, T3 and T5, so it could start before T4 finished. There is no barrier between waves.

  3. Each agent builds one task. It first reads a shared prime: rules, the plan header, global constraints and each stable task’s title, files and interfaces. Then it fetches its own task.

    agent for T9
    $ superlite-cli task T9 --plan docs/plans/2026-11-12-docs-site.md

    The prime is the same for every agent, so the shared part is cached and each task brief stays short. The agent writes a failing test, runs it, implements, runs again, and replies DONE, DONE_WITH_CONCERNS, NEEDS_CONTEXT or BLOCKED in at most 200 words.

  4. The tiers split the work. Eleven tasks went to Sonnet implementer. T12 is a workflow file and a README line with exact steps, so the plan marks it for implementer-haiku.

    docs/plans/2026-11-12-docs-site.md
    ### T12 publish · Complexity 2 · Est. context 25k
    **Owns:** site/.github/workflows/deploy.yml, site/README.md, README.md
    **Kind:** mechanical
    **Model:** haiku

    Haiku costs less, and a mechanical task has little to get wrong. The report shows T12’s model as ?, so treat that one as unmeasured.

  5. The coordinator checkpoints each result with superlite-cli checkpoint Tn. The task’s own files are saved under refs/superlite/*, a hidden ref, not a commit on your branch. Tn FAILED means it touched files it does not own, or has syntax or import problems, and it goes back to its agent.

  6. Wave 3: T12 publish waits for all five page tasks and for T6, the check script, because it adds the deploy workflow that runs that check. Then you read how it went.

    docs/plans/2026-11-12-docs-site.report.md
    concurrency: peak 6 at once (projected 6); critical path actual T4 T11; projected T1 > T8 > T12 (6.8 min)

    The actual critical path was T4 then T11: the reference facts took 3.3 minutes and the reference pages waited for them. The twelve tasks added up to 23.4 task-minutes inside 6.3 minutes of wall-clock, about 3.7 tasks running at any moment.

What you end up with: twelve checkpointed tasks, none committed, and tests that ran in the background the whole time. The reviews come next.

  • Tests never block the build. run_tests writes .superlite/test-summary.json in the background, and a raw pytest is rewritten into it. A hidden wait is denied.
  • No agent spawns agents. The coordinator is the only dispatcher.
  • Cost caps warn at 70% of the cap. Over the cap, optional work stops.
  • /superlite:status shows state. /superlite:stop halts dispatching cleanly, and /superlite:resume continues from the last checkpointed, tested wave.

Reviews and fixes covers what happens to the checkpointed work.