gateline
Run the software development lifecycle as a team of agents that hand off
typed artifacts in git, not chat — roles defined as portable contracts,
models and runtimes attached as swappable bindings, and a human approving at
each phase gate from a cockpit that reads nothing but the repository. Built for
senior engineers moving from single-conversation AI pair-programming to
multi-agent development.
Current state: The frontend, CLI, and orchestrator are fully operable and run as one unit via gateline up. Gate approvals are a convention, not evidence, until #129 lands.
The one idea
Agents never share a conversation; they share typed artifacts in git. A role
consumes files, produces files, and a human approves at up to four gates (spec, plan,
change, release — how many depends on the run's profile). Because roles are contracts
over files, any agent can be replaced mid-run, models swap via a one-file registry
edit, and new runtimes attach by writing a thin adapter — which is how the
cross-vendor requirement and "flexibility over customizability" are both satisfied by
the same mechanism.
What falls out of it
- The repo is the only database. Every view in the cockpit is recomputed
from git; delete the app and nothing is lost. There is exactly one write
path — a compare-and-swap commit to one run's
state.yaml — and a malformed
packet never renders as approvable, in the web, the CLI or the API.
- Humans approve at gates, and only at gates — plus escalations, when an
agent is stuck. The cockpit's other writes are the run's own switches (arm,
pause, resume, close); it does not dispatch, steer or chat, and that stays in
the harness you already use.
- Money is metered per run. By default a run with no cost ceiling gets no
dispatch; every run shows what it has spent against its limit, and one that
crosses it is marked over, on its page and in the ledger.
- The gates measure themselves. Approval rates, burden mix and review
rounds are computed from the state history, and a gate with sustained
approval above 90% is flagged as over-triggering — the signal to move its
scope down the tier ladder.
Every screenshot is Gatehouse, the cockpit, over this repository's own runs —
gateline develops itself through its own gates — captured with the
orchestrator stopped and its "not running" banner hidden.
Start here → docs/DESIGN.md · then drive the toy
pipeline by hand: docs/WALKTHROUGH.md · then put it
over a real repository: Setup, below.
Repo map
| Path | What it is | Portable? |
|---|
docs/DESIGN.md | The architecture: principles, roles, gates, failure modes | — |
docs/TOPOLOGY.md | Control-plane topology: one engine per repository, origin as linearization point | — |
docs/FRONTEND.md | Design for the gate frontend — the human interfaces to the pipeline (plan: FRONTEND-PLAN.md) | — |
docs/INTEGRATION.md | Design (draft) for the workflow that imports the framework into a host repo | — |
docs/ORCHESTRATOR.md | Design for the v1 agent-orchestrated operating mode (implemented in packages/orchestrator) | — |
packages/ | The gate frontend (web, CLI, server over @gateline/core) and the v1 orchestrator (packages/orchestrator) | product component |
roles/ | Runtime-neutral role specs (mission, instructions, escalation triggers) | ✅ core |
contracts/ |
Setup
The shortest path from nothing to a working install: vendor the framework into a
host repo with gateline init, then run the cockpit over it with gateline up.
Every step below is rehearsed against the current tree. No tagged release exists
yet, so the source is a clone of main; once the first release tags, a pinned
release replaces the clone as the canonical source
(INTEGRATION.md §3).
Prerequisites: git; Node ≥ 24; and an agent runner logged in on your
machine (Claude Code in the examples — the Copilot CLI and opencode adapters
render the same agents). The integration tooling has no dependencies of its own,
so it runs from a bare checkout before anything is installed.
1. Install
git clone https://github.com/nathancrtr/gateline.git
cd gateline/packages
npm install && npm run build # builds the Gatehouse SPA once
(cd cli && npm link) # global `gateline`, linked to this checkout
The linked CLI runs from this tree — keep the checkout on main (it is the
operator's instrument; the host repo does not depend on it).
2. Integrate into an existing codebase
gateline init ~/repos/my-app --provenance private
One command: it detects the runners present in the host, vendors the portable
core under .gateline/, seeds the model registry and policy overlays, renders
the agents, writes the lockfile, and adds a CI check that fails on stale renders.
--provenance has no default on purpose — state the host's posture: private
for a closed host, redistribute for an open-source one.
What lands in the host is content only — role specs, contracts, templates.
No framework executable is vendored, so there is nothing in the host to keep in
step with this checkout. The tooling runs from the checkout the lock pins, and
the CI check init writes pins the same ref
(INTEGRATION.md §3). Before you have installed the
cockpit, the same command is
node <checkout>/packages/framework/src/main.ts init ~/repos/my-app --provenance private.
init prints the one dispatch that remains: open your runner in the host repo
and ask it to use the integrator subagent for run runs/000-integration,
producing integration-profile.md per contracts/integration-profile.md.
Review what it produces — the environment probe and the drafted overlays are
the "how should agents behave in this house" decision (gate GI) — then
prove the result:
gateline validate ~/repos/my-app # checksums, renders, provenance
3. Spin up
Two things gate real dispatch: bind real model IDs in
.gateline/registry/models.yaml (the seeded values are illustrative
placeholders), and give each run a budget.cost_limit_usd — no ceiling, no
dispatch. Then:
gateline up --repo ~/repos/my-app --spend-limit-usd 20
That serves Gatehouse on 127.0.0.1:4310 and runs the orchestrator engine over
the same clone — dispatch bills through whatever harness CLI is logged in
locally, orchestrator commits push to origin by default (--no-push to keep
them local), and gates remain named-human decisions in the UI or via
gateline approve. To look before anything dispatches:
gateline status --repo ~/repos/my-app renders the same state read-only.
The browser is optional. The whole gate workflow is terminal-native —
gateline inbox, approve, decline, resolve-escalation — and the engine
runs headless without Gatehouse: gateline-orchestrator watch (resident) or
tick (one reconcile pass, with --dry-run to derive and print next actions
while writing and dispatching nothing). Common terminal workflows and their
pitfalls: packages/cli/README.md.
Before the first real dispatch, read ORCHESTRATOR.md §10
(the autonomy ladder — first live work is a toy run with humans at every gate).
To drive the pipeline by hand instead — no Node, no orchestrator, just the
rendered agents and git — start at WALKTHROUGH.md.
INTEGRATION.md has the knobs this section skips
(--take partial adoption, --layout root, forks and upgrades);
DEPLOY.md hosts the same pair on a single-user instance.
Status
v0.3 — the design has been exercised end-to-end by three human-orchestrated G0→G3
runs (runs/wordfreq/, runs/mdtoc/, runs/dupefind/, each with adversarial review
cycles and independent verification — the shadow-agreement evidence for the v1 trust
ladder), and since then by orchestrator-driven runs against this repository itself;
retro findings fold back into roles, contracts, and all three adapters. Runs now
declare a profile — patch | standard | full (DESIGN.md §4.1)
— that scales which roles run and which gates exist to the size of the change, so a
bug fix no longer pays for the full ceremony. The gate frontend (web, CLI, server)
and the v1 orchestrator are implemented in packages/ and run as one co-located unit
(gateline up), with one engine for each repository it dispatches in
(TOPOLOGY.md); a single-user hosting recipe lives in
deploy/. Autonomy stays gated on the DESIGN.md §7 promotion criterion.
Next: live cross-vendor dispatch and verifiable run record (#129), then the integration workflow
(INTEGRATION.md) and a first tagged release.
License
Copyright © 2026 Nathan Carter. Licensed under the Apache License 2.0;
see NOTICE.md for provenance.
