stageway
GitHub

OPEN SOURCE · MIT · CLAUDE CODE · CODEX · CURSOR

Agents write the code. Stageway makes them prove it.

One confirmed plan becomes a staged run: tests that fail for the right reason, an implementation checked against real command output, an optional independent review, and a guarded draft PR. Every stage starts a fresh agent session. Every check that counts is one the runner ran itself.

Install View on GitHub See how it works
INSTALL 
curl -fsSL https://raw.githubusercontent.com/MarkoArsov/agent-workflow/v0.1.0/install.sh | sh -s -- --global

Requires the matching published tag. Review the pinned script first if that is your policy.

MIT · zero runtime dependencies · runs locally · no account · no telemetry

csv-exportRUNNING
$ stageway status csv-export
stagereviewgreen evidence bound to diff c0045111…
  1. 01Planconfirmed
  2. 02Testsred → frozen
  3. 03Implementgreen
  4. 04Reviewfresh session
  5. 05Deliverqueued

Example run. Checks, attempts, and evidence stay on disk with the project.

THE VERIFICATION GAP

Passing tests is not a merge signal.

≈ 1 in 2

test-passing AI pull requests that the project's own maintainers would not merge

METR, March 2026: 296 AI-generated PRs reviewed by maintainers of 3 SWE-bench Verified repositories

≈ 24 pts

average gap between the automated grader and the maintainers' merge decisions

METR, March 2026

46%

of agent-proposed fixes from Copilot, Devin, Cursor, and Claude rejected

AIDev study, 2026

Writing code stopped being the hard part. Proving a change is right is the new bottleneck, and Stageway is built around it. Read the research

HOW IT WORKS

Five stages. Each one has to show its work.

Fresh horses at every stage: each stage starts a new session with only the plan, the project's rules, and the repository, so no chat history or bias carries over.

01 · specify

Specify

Research first, questions second. One complete plan in which every outcome maps to a named check.

Four plan files plus a validated pipeline.json

02 · optional

Tests

Written before the code. They must fail on an assertion, not a setup error. Then they're frozen.

Red proof and test-file hashes

03 · always

Implement

Build, run every named check, fix, repeat. The runner then runs the checks itself.

Parsed green output bound to the current diff fingerprint

04 · optional

Review

A fresh session with the requirements and the actual diff. It never sees the implementation's reasoning.

Findings, and checks re-run after any correction

05 · optional

Deliver

Runner-owned commit, push, and draft PR. Refuses base branches; never force-pushes.

A delivery record per repository

MANUAL LANE

Small change? Run specify, then implement, in one session: the same plan and named checks, no detached run.

Choose a lane

BOUNDED AUTONOMY

Runs unattended. Stops only for what matters.

Recorded, run continues

  • Review findings, which are advisory
  • Advisory rule findings
  • One route for every stage
  • Usage the provider didn't report, kept as unknown

Blocks completion

  • Secret material or a blocking rule finding
  • Edits outside the declared paths, or to a read-only repository
  • A named check fails, or red or green evidence is missing
  • A frozen test changed, or your pre-existing changes were touched
  • Stale green evidence fails its re-run before delivery
  • A delivery guard trips: base branch, unrelated staged changes, a moved HEAD
  • Configured attempts or time limits run out

Scope and guard violations stop the run at once. Failing checks go back to the agent as feedback first. Advisory findings never turn into babysitting, and a failed safety check never turns into a success summary.

THE SCORECARD

Measured against 36 checkpoints. Gaps included.

Most tools tell you they're safe. Stageway publishes the scorecard: what the runner enforces, what's partial, what belongs to your organization, and what's still open.

Intake

IN-1 Spec has a start locus and a completion artifact, ImplementedIN-2 Ambiguity surfaced before the first write, ImplementedIN-3 Task prioritized before assignment, ExternalIN-4 Task size bounded, Partial

Context

CTX-1 Agent instruction file at the repository root, in version control, ImplementedCTX-2 Instruction file pruned, not just grown, PartialCTX-3 Environment declarative and snapshotted, PartialCTX-4 Docs and architecture layers machine-checked, PartialCTX-5 Agent discoveries captured as skills and scripts, Implemented

Planning

PLN-1 Read-only explore phase before execution, ImplementedPLN-2 Plan reviewed by a non-author, ImplementedPLN-3 Planning and implementation contexts separated, ImplementedPLN-4 Vertical slices, each independently testable, Partial

Execution

EXE-1 Unattended runs inside an isolation boundary, PartialEXE-2 Network egress allowlisted, GapEXE-3 Untrusted content sanitized before the model, PartialEXE-4 Risk tiers gate what runs automatically, PartialEXE-5 Parallel agents in isolated checkouts, Policy choice

Verification

VER-1 Agent-runnable check per task, ImplementedVER-2 Completion gated deterministically, ImplementedVER-3 Fresh-context reviewer on the diff, ConditionalVER-4 Behavioral verification for user-facing changes, ConditionalVER-5 Agent-written tests reviewed adversarially, ImplementedVER-6 SAST, secret, and dependency scans before review, Partial

Review and merge

REV-1 Named human approver, no self-merge, ExternalREV-2 PR carries evidence, not assertions, PartialREV-3 Review capacity tracked as a constraint, ExternalREV-4 Auto-fix loops bounded, Implemented

Post-merge

PST-1 Agent authorship labeled, Policy choicePST-2 Sessions instrumented end to end, PartialPST-3 Failures feed back into instructions, Partial

Organization

ORG-1 Stability metrics segmented by provenance, ExternalORG-2 Spend monitored, not incentivized, PartialORG-3 Agent credentials scoped and audited, GapORG-4 Production access gated in multiple layers, ExternalORG-5 Skills inventoried and evaluated, Partial

Beyond the rubric

Plan binding and rebindDiff fingerprintFrozen testsAssertion-level redNo silent skipsNo implicit fallbackExact-session answersFresh sessionsReview without the reasoningPartial work preservedChecks may not edit sourceYour changes stay yoursApproval-digest setupConfiguration snapshotted per runOne runner per projectGuarded multi-repository deliveryRead-only companion repositoriesRedacted questions and outputUnknown cost stays unknown

Read the scorecard

OPEN SOURCE

Open source, all the way down.

A verification layer you can't inspect is just another claim to trust. Every line that decides whether your agents' work passes is in the public repository.

MIT-licensed

Use it at work, change it, ship it.

Read the runner

Standard-library Python with zero runtime dependencies. The runner, parsers, and guards are ordinary code, not a hidden service.

Runs on your machine

Your agent CLIs, your logins, your repositories. No Stageway account, server, or telemetry.

Built in the open

Public CI on Linux and macOS, public tests, public scorecard, gaps included.

Read the code How to contribute

DESIGN

Every decision answers a failure mode.

Research before planning

Agents guess, or ask questions the repository can answer.

specify reads instructions and working examples first, then asks only what is missing.

Tests first, red on an assertion

A test written after the code can prove the code instead of the requirement.

The red stage must fail on assertions, not setup errors. Then the tests are frozen.

A fresh session per stage

Shared chat history biases later judgment.

Every stage and retry starts from the plan and the repository, not the previous conversation.

Mechanical verification

A confident report can still be wrong.

An agent's response is a proposal, not a completion. The runner runs the checks.

Stop only on safety

Treating every finding as a stop turns automation into babysitting.

Scope, secrets, frozen tests, failed checks, and delivery guards block. Review notes don't.

Open and local

A closed verification layer is one more claim to trust.

The whole verification layer is public code that runs on your machine.

All design decisions

COST AND MODELS

Scripts own the process. Models own the judgement.

Cost and models

REVIEW

Review is the new bottleneck. Stageway treats it that way.

Agents produce diffs faster than anyone can responsibly merge them. Use AI to understand a change before you judge it, keep your own queue short, and spend the waits reviewing. A named human still approves.

understandreview-guidepeer-pr-reviewaddress-pr-commentspr-preflight

One runner per project, and a short queue beats a pile of draft PRs. Review and everyday use

YOURS TO CHANGE

The workflow adapts to the repository, not the other way around.

Setup records commands, branches, agents, models, permissions, and delivery choices. Copy skills, capture rules, and add connectors and stages without touching installed defaults. Change it per project without forking, or fork the whole thing: it's MIT.

CHANGE WHAT YOUR AGENTS KNOW

stageway skill copy review
stageway skill new release-notes --description "Draft release notes from verified changes."
stageway refresh
Customize skills and stages

KEEP EXTENSIONS WITH THE PROJECT

.stageway/
├── skills/
├── rules/
├── references/
├── connectors/
└── stages.json
See the project layout

PICK YOUR PATH

Start where you are.

First time here

  1. The verification gap
  2. Design principles
  3. Your first task

Running tasks

  1. Task lifecycle
  2. Review and everyday use
  3. When a task stops

Adopting it for a team

  1. Set up your project
  2. Skills and stages
  3. Checkpoint scorecard
  4. Security boundary

Contributing

  1. Open source
  2. Code map
  3. Contribute and develop

Maintaining your setup

  1. Keep the workflow clear
  2. Update and remove

READY TO START

Give your agents a route. Make every stage prove itself.

Install Your first task Star on GitHub

Open source under the MIT license. Contributions welcome.