Better WorkflowsRC1
5.0.0-rc.1V5.0 RC1 is publicly available. GA remains pending.

Done means proven.
Unclear means stop.

Better Workflows is an open-source QA engineer and delivery gatekeeper for AI engineering — a demanding senior reviewer for every agent hand-off. A stage passes only when its evidence belongs to the current repository, revision, scope, and target, and can be checked again.

  • Goal-first
  • Evidence-driven
  • Fail-closed
  • Risk-adaptive
Install See the gate at work GitHub

gate-demo · gate walkthrough

Illustrative walkthrough, not a live run
  1. $better-workflows:auto <describe the outcome you need>
  2. routeevidence-required · policy dev-publish-v1
  3. goalFreeze goal, scope, acceptance, and authority bound
  4. sourceBind the current repository and revision; take a source sentinel fresh
  5. worktreeCreate a task-owned branch and worktree; your checkout is untouched isolated
  6. executeRun bounded work inside the bound scope done
  7. verifyTyped evidence bound to the current source; review receipt present passed
  8. authorityThis target is authorized for a single side effect granted
  9. actPerform ONE external side effect sent
  10. reconcileReconcile provider state: returned outcome unknown unknownReconcile provider and repository state consistent
  11. completeNo retry, no completion claim not reachedRe-take the sentinel, re-verify acceptance, clean task-owned resources complete

STOPPED SAFELYProvider outcome unknown: no retry, no completion claim. The run stops and waits for your decision.

COMPLETETerminal provider and repository evidence is in place; the task-owned branch and worktree are cleaned up.

GATE STATE

STOPPED AT 08 / 09
  1. Goal frozenGOALPASS
  2. Source boundSOURCEPASS
  3. Worktree isolatedWORKTREEPASS
  4. Bounded executionEXECUTEPASS
  5. Fresh, reviewed evidenceVERIFY · GATEPASS
  6. Target authorizedAUTHORITY · GATEPASS
  7. Single side effectACTPASS
  8. Provider state reconciledRECONCILE · GATEBLOCKED
  9. Complete and clean upCOMPLETENOT REACHED
PROVIDER OUTCOME

This is an illustrative walkthrough. Fields and states only show where gates pass and where the run stops; the alternative ending confirms the provider outcome and the run completes.

01PrinciplesPRINCIPLES

A prompt can describe intent.
It never grants authority.

A stage passes only when its evidence belongs to the current repository, revision, scope, and target, and can be checked again. If evidence is missing, stale, conflicting, or the outcome is unknown, the workflow stops and asks you to decide instead of pretending the task is done.

WITHOUT vs WITHWithout governance vs. with Better Workflows

AspectWithout governanceWith Better Workflows
AuthorityIntent and authority are conflatedGoal, scope, and authority are separate records
FreshnessA passing check may belong to an old revisionEvidence is bound to the current source and target
RetriesA retry may duplicate an external actionAttempts are bounded and unknown outcomes are reconciled
Done“Done” can mean “the command returned”Completion requires terminal provider and repository evidence
IsolationTwo tasks edit one checkoutMutating Git tasks use separately owned branches and worktrees

AUTHORITY LAYERSAuthority layers

  1. L1
    Prompt

    Records the outcome you want

    Grants no authority
  2. L2
    Context

    Binds current facts

  3. L3
    Harness

    Limits who may act and where

  4. L4
    Loop

    Bounds retries and reconciliation

  5. L5
    Graph

    Projects admitted state; never a scheduler, policy input, or authority source

    Projection only

02WorkflowWORKFLOW

Risk sets the verification,
not ceremony.

A clear, reversible, low-risk change may use Auto's fast path with a small targeted check. Everything else is promoted to the evidence workflow, with verification strength matched to the risk.

AUTO FLOWAuto in five steps

  1. Check the repository, goal, scope, and source branch
  2. Choose Auto fast path or evidence-required
  3. Read-only work stays in place; Git changes create or reuse an isolated task worktree
  4. Validate the result; integrate changes only when authorized
  5. Clean only task-owned branches and worktrees

ROUTINGFast path or evidence workflow

ENTRYPOINT$better-workflows:auto
BINDS ONE POLICYread-only-v1code-change-v1dev-publish-v1
AUTO DECIDESVerification strength follows the task and its risk
FAST PATH

Auto fast path

Clear, reversible, low-risk changes

A small, focused targeted check instead of the full evidence workflow.

Even on the fast path, it still

  • never bypasses a protected branch
  • never widens the scope
  • never installs tools
  • never skips the task-owned worktree
EVIDENCE WORKFLOW

Evidence workflow

Everything else

Verification strength matches the risk; evidence must belong to the current source and target.

These checks promote to evidence mode immediately

  • package-manager
  • network
  • child-process
  • native
  • checkout-external

LIFECYCLEFour questions replace “done”

  1. 01

    Define

    TaskContract

    Are the goal, scope, acceptance, authority, and route frozen?

    1. State the goal
    2. Bind scope and current context
    3. Git mutation?Yes ⇒ create or reuse a task-owned worktree
  2. 02

    Verify

    Evidence

    Is the evidence bound to the current source?

    1. Execute bounded work
    2. Review and validate fresh evidencesource sentinel · typed evidence · graph and review receipts
  3. 03

    Reconcile

    Provider truth

    Is the outcome of the external side effect confirmed?

    1. Authorized for this target?No / unknown ⇒ stop safely
    2. Perform ONE side effectsingle-use authority
    3. Reconcile provider and repository stateUnknown ⇒ investigate, never blindly retry; stop safely
  4. 04

    Complete

    Terminal decision

    After re-sampling, does acceptance still hold?

    1. Re-take the sentinel; re-verify acceptance, ledger, review, and remote result
    2. Complete and clean owned resources

Replay repeats the decision over the recorded evidence; it never repeats push, merge, deploy, or release.

GIT SAFETYGit boundaries

Git boundary diagram Your checkout stays untouched; changes happen in a task-owned branch and worktree and are integrated from a checked candidate with compare-and-swap. your checkout (read-only work stays here)task branch + task-owned worktreeCAS
Changes happen in an owned worktree; integration uses a checked candidate and compare-and-swap.
  • G1

    Read-only work stays in place.

  • G2

    Mutating Git work always uses its own task branch and task-owned worktree — never your checkout.

  • G3

    Integration uses a checked candidate and a compare-and-swap update.

  • G4

    Only task-owned branches and worktrees are cleaned, and only with proof.

  • G5

    Dirty state is never stashed or hidden.

  • G6

    A clean, exclusive worktree created by the host is adopted instead of nesting another one.

03HostsHOSTS & PLATFORMS

Exactly where RC1 runs,
stated plainly.

V5.0 RC1 covers Codex, Gemini CLI, and Qwen Code on macOS × Node.js 22/24 only. Claude Code, Linux, and Windows qualification is deferred to V5.1 and is not support today.

V5.0 RC1 public scope: hosts and operating systems
HostmacOSLinuxWindows
CodexRecommendedRC1 publicV5.1 deferredV5.1 deferred
Gemini CLIRC1 publicV5.1 deferredV5.1 deferred
Qwen CodeRC1 publicV5.1 deferredV5.1 deferred
Claude CodeV5.1 deferredV5.1 deferredV5.1 deferred

NODE.JS 22/24 · bundled helper needs ≥ 22.14.0V5.1 deferred = qualification not finished; not support

Technical details: V4 historical support matrix (reference only)HOST-SUPPORT-V1

The V4 matrices below are historical. Current RC1 supports macOS with Codex, Gemini CLI and Qwen Code on Node 22/24; GA remains pending.

V4 · HOST-SUPPORT-V1

V4 AI / OS capability matrix

Evidence-first AI engineering QA and delivery gatekeeper.

Let AI agents choose verification strength by risk and finish work safely in an isolated environment.

Simple changes move fast; important work uses evidence gates; Git changes use a dedicated worktree by default.

AI hostSupportOS coverageIntegration
Codex Recommended on macOStier1macos: tier1 · linux: tier1 · windows: previewCodex plugin
Claude Codetier1macos: tier1 · linux: tier1 · windows: previewClaude Code plugin
Gemini CLItier1macos: tier1 · linux: tier1 · windows: previewGemini CLI extension
Qwen Codetier1macos: tier1 · linux: tier1 · windows: previewQwen Code extension
Kimi Code CLIpreviewmacos: preview · linux: preview · windows: previewCompatibility pack
Kiropreviewmacos: preview · linux: preview · windows: previewCompatibility pack
Grok Buildpreviewmacos: preview · linux: preview · windows: previewCompatibility pack
Cursorpreviewmacos: preview · linux: preview · windows: previewCompatibility pack
GitHub Copilotpreviewmacos: preview · linux: preview · windows: previewCompatibility pack

native = host-native · core-bridge = shared control layer · unverified/unavailable are explicit limits.

AI hosttask-contracttyped-evidencereplayaction-gatetask-worktreenative-pickernative-subagents
Codexnativenativenativenativecore-bridgenativenative
Claude Codecore-bridgecore-bridgecore-bridgecore-bridgecore-bridgeunavailableunverified
Gemini CLIcore-bridgecore-bridgecore-bridgecore-bridgecore-bridgeunavailableunverified
Qwen Codecore-bridgecore-bridgecore-bridgecore-bridgecore-bridgeunavailableunverified
Kimi Code CLIcore-bridgecore-bridgecore-bridgeunverifiedcore-bridgeunavailableunverified
Kirocore-bridgecore-bridgecore-bridgeunverifiedcore-bridgeunavailableunverified
Grok Buildcore-bridgecore-bridgecore-bridgeunverifiedcore-bridgeunavailableunverified
Cursorcore-bridgecore-bridgecore-bridgeunverifiedcore-bridgeunavailableunverified
GitHub Copilotcore-bridgecore-bridgecore-bridgeunverifiedcore-bridgeunavailableunverified

Official recommendation: macOS + Codex — the deepest native integration and complete reference experience.

Site source revision：16690d7c323e204b98efd3c3675e7933a66531e1

04InstallINSTALL

Pick your host.
Paste the commands.

RC1 ships install paths for Codex, Gemini CLI, and Qwen Code on macOS. The bundled helper needs Node.js 22.14.0 or newer. Use a repository you trust; Better Workflows does not claim to sandbox malicious repository code.

  1. 1

    Install

    Choose your host and run the commands in a terminal. The official recommendation is macOS + Codex.

  2. 2

    Reload

    Codex: open a new task so the skill list refreshes. Gemini CLI and Qwen Code: restart the session after installing.

  3. 3

    Make a first request

    Type $better-workflows:auto, then describe the outcome you need.

  4. RC1 is not GA. For every install step, see Quick start

Codex

codex plugin marketplace add stephen-taipei/better-workflows
codex plugin add better-workflows@better-workflows

Then open a new Codex task so its skill list refreshes.

Gemini CLI

gemini extensions install https://github.com/stephen-taipei/better-workflows --ref V5.0.rc1

Restart the session after installing.

Qwen Code

git clone --branch V5.0.rc1 --depth 1 https://github.com/stephen-taipei/better-workflows.git
qwen extensions install ./better-workflows

Restart the session after installing.

FIRST REQUEST

$better-workflows:auto Review this repository and fix verified defects.
$better-workflows:auto Review this repository and summarize its main parts. Do not change files.

The first request fixes verified defects; the second is read-only.

05Proof boundaryPROOF BOUNDARY

What it proves, and what it doesn't —
written down.

Up front: the errors it can block, what has not been proven yet, and what it is not.

Detects and blocks

Observable errors

  • The wrong repository or revision
  • Stale evidence
  • A false completion claim
  • An unauthorized side effect
  • An unknown provider outcome
  • Premature cleanup

Not proven yet

Long-term outcomes

  • Not statistically proven to lower scope drift, rework, or decision-error rates in multi-turn agent work
  • Cannot prove that your original goal was the right product decision

It is not

Outside the boundary

  • Not a sandbox: it does not claim to isolate malicious repository code — use a repository you trust
  • Not an unlimited agent runtime
  • It never harvests sensitive or private history
Better Workflows can block observable errors such as the wrong repository or revision, stale evidence, unauthorized side effects, and premature cleanup. It has not yet statistically proven lower long-term scope drift, rework, or decision-error rates.
  1. B1Auto fast path still runs targeted checks and never bypasses protected branches
  2. B2Protected or remote targets use governed PRs, fresh checks, and merge authority
  3. B3Replay re-evaluates recorded evidence; it does not merge, push, or deploy again

06Status & licenseSTATUS & LICENSE

V5.0 RC1 is publicly available. GA remains pending.

RC1 is a controlled prerelease with Auto as the only public entrypoint. The GA conditions and deferred items are listed below — nothing is claimed early.

  1. NOW Public since 2026-10-03

    V5.0 RC1

    5.0.0-rc.1 · V5.0.rc1

    Codex, Gemini CLI, and Qwen Code on macOS × Node.js 22/24. Auto is the only public entrypoint.

  2. PENDING Not released

    GA 5.0.0

    Requires all of

    • At least 30 natural canary days
    • 20 consecutive eligible starts
    • Three distinct repositories

  3. DEFERRED Deferred to V5.1

    V5.1

    Claude Code · Linux · Windows

    Qualification for these hosts and operating systems is deferred to V5.1 and not yet released.

STATEMENTStatement of record

V5.0 RC1 · Public release and licensing

V5.0 RC1 (5.0.0-rc.1, tag V5.0.rc1) is a controlled prerelease with one public Auto entrypoint. The V4 support matrix remains historical; RC1 does not establish GA acceptance or V5 completion.

V5.0 RC1 covers Codex, Gemini CLI, and Qwen Code on macOS × Node 22/24. Claude Code, Linux, and Windows qualification is deferred to V5.1. GA requires at least 30 natural canary days, 20 consecutive eligible starts, and three distinct repositories.

The first-party Better Workflows core is AGPL-3.0-only. The physically separate minimal wire package is Apache-2.0; its LICENSE and NOTICE apply to that package.

The basic product is free. Professional Pack is planned as a proprietary product, and Cloud is a separate product planned for later; neither is currently available.

LICENSINGLicensing and availability

Licensing and availability
ItemLicense or formStatus
First-party coreAGPL-3.0-onlyPublic in RC1
Minimal wire packageApache-2.0Physically separate; its LICENSE and NOTICE apply to that packagePublic in RC1
Basic productFreePublic in RC1
Professional PackPlanned as proprietaryNot available
CloudSeparate later productNot available

07DocsDOCS

Read for your next step.

Five documentation pages in English and Traditional Chinese. To see the whole process first, start with Evidence Cinema.

Cartoon scene: a blue fox shows a glowing token to an amber tortoise who raises a hand to stop it, while a teal robot waits nearby.INTERACTIVE DEMO

EVIDENCE CINEMA

Evidence isn't a subtitle. It decides the ending.

An eight-scene original cartoon replay from intent to provable completion. Pause, rewind, and switch between the “evidence complete” and “provider outcome unknown” endings.

  • Captain Root
  • Scout Pixel
  • Ledger
  • Vera
  • Sentinel
  • Echo
Six original characters · a sanitized teaching replay, not a live run
Enter Evidence Cinema

08FAQFAQ

Common questions,
straight answers.

Still unsure? Ask on GitHub or visit the support page.

What is Better Workflows?

An open-source QA engineer and delivery gatekeeper for AI engineering — a demanding senior reviewer for AI agents. A stage passes only when its evidence belongs to the current repository, revision, scope, and target and can be checked again; when evidence is missing, stale, conflicting, or unknown, the workflow stops and asks you to decide instead of pretending it is done.

Will it push, merge, or deploy on its own?

Not because a prompt said so. A prompt describes intent; it never grants authority. Only Root may edit, integrate, deploy, accept risk, or declare completion, and every side effect needs fresh evidence, provenance, and an action bound to the intended target — one side effect at a time.

Does every small change run the full process?

No. A clear, reversible, low-risk change can use Auto's fast path with a small focused check; everything else is promoted to the evidence workflow. Even the fast path never bypasses a protected branch, widens scope, installs tools, or skips the task-owned worktree.

Will it touch my current checkout?

Read-only work stays in place. Mutating Git work always uses its own task branch and task-owned worktree, never your checkout, and dirty state is never stashed or hidden.

What does RC1 support? What about Claude Code, Linux, and Windows?

The V5.0 RC1 public scope is macOS × Node.js 22/24 with Codex, Gemini CLI, or Qwen Code; the official recommendation is macOS + Codex. Claude Code, Linux, and Windows qualification is deferred to V5.1 and not yet released.

Does it guarantee bug-free code?

No. It can block observable errors such as the wrong repository or revision, stale evidence, unauthorized side effects, and premature cleanup, but it has not been statistically proven to lower scope drift, rework, or decision-error rates in long-running tasks, and it cannot prove your original goal was the right product decision.

Is it a sandbox?

No. It does not claim to isolate malicious repository code, so use a repository you trust. It is not an unlimited agent runtime, and it never harvests sensitive or private history.

What does it cost, and how is it licensed?

The first-party core is AGPL-3.0-only; the physically separate minimal wire package is Apache-2.0. The basic product is free. Professional Pack is planned as proprietary and Cloud is a separate later product; neither is available yet.

V5.0 RC1 · publicly available

Make the next “done”
something you can check.

Install the public RC1 and start with $better-workflows:auto. GA is still pending, and we will keep saying so up front.

InstallRC1 release notes