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/	Templates for every handoff artifact (spec, plan, task, reports, state)	✅ core
registry/models.yaml	The only place vendor/model IDs exist; roles bind via capability profiles	✅ core
packages/framework/	Reads role specs and adapter manifests, renders every adapter's agent files, and integrates the framework into a host repo (gateline render|init|validate|fork); dependency-free, so it runs with nothing installed	product component
scripts/copy-manifest.json	The core-layer files a release offers a host, and the menu --take selects from	✅ core
adapters/claude-code/	First runtime binding: role specs → .claude/agents/ subagents	per-runtime
.claude/agents/	The rendered subagents (runnable in Claude Code today)	per-runtime
adapters/copilot-cli/	Second runtime binding: role specs → .github/agents/*.agent.md custom agents	per-runtime
.github/agents/	The rendered custom agents (runnable in Copilot CLI today)	per-runtime
adapters/opencode/	Third runtime binding: role specs → .opencode/agents/*.md agents	per-runtime
.opencode/agents/	The rendered opencode agents (any-provider model bindings)	per-runtime
runs/	One directory per pipeline run; a run in flight lives on its run/<slug> branch until it lands — the pipeline state lives in git	working area

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.