Throughline Build

Throughline Build is deterministic orchestration for agent-assisted software delivery. It is a .NET 10 Native AOT CLI named build that coordinates Plane tickets, isolated git worktrees, automated gates, independent review, and selectable coding-agent CLIs.

The core design decision is a hard boundary between deterministic control and agentic judgment:

• C# owns workflow state, ticket writes, git topology, gates, retries, evidence, and exit codes.
• Worker agents own bounded planning, implementation, review, decomposition, and scaffold tasks.
• Every supported worker (claude-code, codex, gemini, and copilot) crosses the same typed brief and result contracts.

The point is not merely to launch an agent. It is to make the surrounding process inspectable, resumable, and able to fail for deterministic reasons. The repository dogfoods that model on its own development.

Start here

• State of the system is the current architecture and implementation authority.
• Operator user guide covers installation, repository readiness, and the first end-to-end ticket.
• Building from source has contributor build, test, and Native AOT publish commands.
• Documentation map separates current references from historical analysis and research.

Requirements

• The .NET 10 SDK selected by global.json, plus a native toolchain for Native AOT publish: MSVC on Windows, Xcode command line tools on macOS, clang or gcc on Linux.
• git on PATH.
• A Plane workspace, project, and API token. Plane is the system of record for ticket state; build init connects a repository to a project.
• At least one coding-agent CLI on PATH, named by an executable key under [workers.<name>] in .build/config.toml. Phases that need judgment (plan, implement, review, decompose, and free-form build new) spawn that CLI. Deterministic verbs such as list, get, comment, transition, gate, and waves need no worker.

Build

This is currently a source-distributed project; no prebuilt release is published.

dotnet build throughline-build.sln --nologo -v q
dotnet test --nologo -v q
./build.sh

./build.sh publishes the Native AOT binary for the host platform, copies it to bin/, and installs it to $HOME/.local/bin. Override the destination with INSTALL_DIR=... and cross-target with RID=osx-arm64.

First ticket

build init writes .build/config.toml and connects the repository to a Plane project. build setup provisions the states and labels the workflow expects, adds the managed ignore rules, and preflights the configured worker.

build init
build setup

Then describe the change you want. Free-form text is handed to the configured worker, which drafts a titled body with acceptance criteria and files it in Backlog:

build new "Rate-limit /search to 60 requests per minute per API key, 429 on overage"

Ticket size is what makes the rest of the workflow work. Aim for one shippable behavior change stated so that a reviewer can fail it: a specific surface, a specific rule, an observable result. A request larger than that is still worth filing - run build decompose <ticket-id> to split it into independently shippable children.

To control the body exactly, or to file from a script, skip the drafter:

build new --print-template > draft.md
build new draft.md
build new - --json

--print-template emits the headings the validator expects. build new - --json reads a strict JSON draft from stdin and creates the ticket deterministically, with no worker involved.

Running a ticket

Use the ID that build new printed:

build chain TLB-12

chain cuts an isolated git worktree for the ticket, then runs plan, implement, gate, and independent review, retrying implementation while review returns Rework, and shipping once review passes. The Plane ticket moves through its states as the phases complete, and every phase is recorded in the event log.

Each phase also runs on its own - build plan, build implement, build review, build ship - and build gate runs the configured checks with no worker at all. A failure stops the run with a distinct exit code naming the phase that stopped it, rather than reporting a partial success.

Worker-spawning verbs (chain, plan, implement, review, decompose) launch an agent CLI and refuse to start inside an existing agent session. Run them from a plain terminal.

Run build help or build help <topic> for the authoritative command reference generated by the binary.

Project

• Contributing has the required checks and code conventions.
• Security policy covers private vulnerability reporting.
• Licensed under the MIT License; see LICENSE.