Reference

Architecture.

Três planos e uma invariante. O control plane decide, o worker executa onde o código está, o cockpit observa — e nenhum CLI de agente toca o checkout principal, nunca. Esta página é o resumo; a referência completa é docs/ARCHITECTURE.md.

The three planes

Control plane

Keeps tasks, runs, events, artifacts and leases in Postgres, and exposes REST and SSE. It is what knows the state machine and what issues the leases workers claim. No agent runs here: this process decides, it doesn't build.

Worker

Runs on the host where your code lives. It claims a lease, creates the task's worktree, invokes the agent CLI and returns the result. The credential lives in FACTORY_WORKER_CREDENTIAL, an environment variable, never t25.yaml. An expired lease is reclaimed on the next cycle, and a completion that arrives after the lease expired is rejected instead of quietly accepted.

Mission Control

The cockpit at localhost:4173: board, per-run log, approvals, retries, cost, per-project policies and agent profiles, with progress events arriving over SSE while the task moves.

The state machine

RECEIVED → SPEC → PLAN → AWAITING_APPROVAL → IMPLEMENTING
         → QA → REVIEW → PR_OPEN → DOCS → DONE

fuga: NEEDS_INPUT · FAILED · CANCELLED
loop: QA and REVIEW can send it back to IMPLEMENTING

Legal transitions are declared in one place and checked before any state change; no part of the pipeline writes the state directly. Every change emits an event, and that is what the cockpit sees arriving.

Mission names exist only where there is a real operational counterpart; the cockpit still shows the technical state, not the nickname.

Isolation by worktree

This is the deliberately paranoid part of the system, and the one you don't touch without reading the module's security comments:

• Every task gets a worktree of its own, on a branch named after the task type (feat/<id>, fix/<id> and so on), created from the repository's default branch.
• Every call to git runs with an argument list, never through a shell, so a branch name or a path is never interpolated into a command string.
• Every worktree path is verified to resolve inside the configured root, against escapes through a symbolic link or ...
• T25 only adopts a worktree if the ownership metadata matches and the path is still registered in git worktree list. A directory that merely happens to sit at the right path is not adopted.
• Cleanup refuses a tree with uncommitted changes and never removes by force.

Agent adapters

An adapter is the smallest possible thing: the binary name and how to assemble the arguments. All the process machinery (finding out whether the CLI exists, reading its version, streaming output, killing it on timeout) is shared. Adding a new CLI means declaring an adapter, not reimplementing process handling.

Two choices are worth recording: execution uses an argument list, with no shell in between; and a very large prompt goes to a temporary file instead of an argument, because the command line has a size limit in the operating system.

Role routing is a preference chain, not a fixed CLI: T25 uses the first available item in the list. See configuration.

Durable execution

Execution isn't a function call that has to survive the process: it is a queue of leases. The task is enqueued, a worker claims it with a deadline, and on finishing either confirms or hands it back. If the worker dies halfway through, the lease expires and the work returns to the queue. That is the crash recovery, and it doesn't depend on anyone remembering to clean up state.

Where the code is

Next Configuration: the t25.yaml sections →