🐂 Yoke

1.6.1 1020 34 Claude | Codex | Gemini

One harness, three agents — and zero trust in "done."

Yoke installs one curated canon of skills, mechanical safety gates, and tool wiring into any project — natively for Claude Code, OpenAI Codex CLI, and Gemini CLI. Then, when you want it, an opt-in autonomous loop ships your spec story-by-story: tested, cross-model-reviewed, committed — with a screenshot to prove every story and a video for every failure.

Install: npm i -g @hecer/yoke

TL;DR — yoke setup . asks six questions and installs the native harness for your agent. yoke new my-app --idea="..." bootstraps a project and drafts its story backlog. yoke loop run my-app --isolate --review then implements it behind hard gates: clean tree → acceptance criteria → your real tests green → an independent model approves → commit. Add --parallel=N for dependency-aware workers, or declare a reference and add --quality for a bounded critic/repair gauntlet. If any blocking gate is red, nothing is committed. Proof lives in .yoke/proof/<story>/.

Yoke 1.5 keeps failed gate output compact without throwing evidence away: deterministic previews retain actionable failures and final summaries, while large complete stdout/stderr remains available in private, content-addressed local artifacts. Existing projects keep their serial behavior and use safe 2 KiB preview / 8 KiB artifact defaults unless configured otherwise.

Yoke 1.4 adds opt-in parallel workers and a bounded, reference-driven quality gauntlet without changing existing serial loop defaults. See the 1.4 migration guide for the new flags, configuration, cleanup behavior, and review-verdict contract.

Yoke 1.1 is safe-by-default: provider CLIs use autonomous sandbox profiles unless --unsafe is explicit; reviews require a schema-valid verdict and a different model unless --allow-self-review is explicit; commits enforce the human identity from project config or Git. See the 1.1 migration guide for setup/decision parity and the 1.0 guide for the earlier safety-policy changes.

---

Why Yoke exists

Agentic coding in 2026 fails in four well-documented ways. Yoke answers each one mechanically — in code, not in a prompt the agent can ignore:

The pain	What actually happens	What Yoke does about it
🎭 The verification gap — "agent says done, but it isn't"	Agents submit confidently on 100% of runs while resolving far fewer; "all tests pass" when they were never run (silent-failures research)	The loop trusts your verify command's exit code, never the agent's word. A story is passes: true only after tests are green, the reviewer approved, and the commit landed — atomically. Plus: screenshot proofs per story.
🔀 Three agents, three configs	Teams hand-maintain CLAUDE.md, AGENTS.md, GEMINI.md, skills, and MCP wiring separately — copy-paste drift everywhere	One canon → yoke retrofit generates the idiomatic native artifacts for each agent. Change the canon once, re-retrofit everywhere.
🌀 Overnight loops going off the rails	Raw Ralph-loop users "wake up to broken codebases that don't compile"	Yoke is "Ralph, but with gates": clean-worktree gate, acceptance-criteria gate, green-tests gate, review gate, per-story worktree isolation, idle-timeout watchdog, single-flight lock, commit integrity.
😵 Review fatigue	AI adoption nearly doubles PR volume and review time; humans start skimming	yoke review: a second model writes a schema-validated pass/fail verdict — chainable into verify, pre-push, or CI. Cross-model review catches what self-review misses.

Who it's for: anyone driving Claude Code, Codex CLI, or Gemini CLI on real projects — especially if you use more than one, want autonomous runs you can trust, or are tired of "done" meaning "probably". Greenfield (yoke new) and brownfield (yoke retrofit) both work.

Who it's not for: if you want a chat pair-programmer with no process, you don't need a harness. Yoke is for shipping with discipline.

⏱️ 60 seconds: idea → tested, photographed software

$ yoke new reading-app --idea="a web app that tracks my reading list"
✓ reading-app bootstrapped.        # git repo · harness for all agents · context · PRD drafted from the idea

$ yoke prd check reading-app
✓ PRD valid — 8 stories, 0 pass

$ yoke loop on reading-app
$ yoke loop run reading-app --isolate --review --max=10
▶ STORY-1 (0/8 · 0%) — implementing… · verifying… · reviewing… · committing…
✓ STORY-1 done in 3m12s — 1/8 (13%) · ~22m left
▶ STORY-2 (1/8 · 13%) — implementing… · ~22m left (Ø 3m12s/story)
✓ STORY-2 done in 2m48s — 2/8 (25%) · ~18m left
▶ STORY-3 (2/8 · 25%) — implementing… ✘ blocked: story did not verify (tests red)
                                              # nothing was committed. fix, then re-run.

$ ls reading-app/.yoke/proof/STORY-2/
home.png  list.png                            # photographic evidence, labelled per story

Every claim in that transcript is enforced by code paths with tests behind them — 1020 of them, and this repo was built by its own loop and gates (how it was built).

🚀 Quickstart

npm install -g @hecer/yoke                 # → global `yoke` on your PATH
# (or from source: git clone https://github.com/HECer/yoke.git && cd yoke && npm install && npm run build && npm link)

# Greenfield: idea → loop-ready project in one command
yoke new my-app --idea="a CLI that tracks reading lists"
yoke loop on my-app && yoke loop run my-app --isolate

# — or retrofit an existing project —
yoke setup /path/to/project                                  # interactive: agents, graph, loop, runner, decisions, routing
yoke validate canon                                          # sanity-check the canon
yoke loop run /path/to/project --isolate --parallel=3 --reviewer=codex --max=20

Requires Node ≥ 20 and git. No global install? node /path/to/yoke/dist/cli.js … or npm --prefix /path/to/yoke run yoke -- … work too. The MCP tools (rtk, graphify/Serena, Playwright MCP) are wired by Yoke but installed separately — the generated config is a clearly-labelled, adjustable template.

Skills before the first setup

The canon is also packaged as a Claude Code plugin — the repo is its own marketplace:

/plugin marketplace add HECer/yoke
/plugin install yoke@yoke

That gives you all canon skills under the yoke: namespace (e.g. yoke:tdd, yoke:review) inside Claude Code — no retrofit needed. The yoke CLI (loop, gates, retrofit for Codex/Gemini) still comes from npm i -g @hecer/yoke. Gemini CLI users can likewise gemini extensions install https://github.com/HECer/yoke.

For Codex, no preinstalled skill is required: run npx @hecer/yoke setup . in a terminal, or ask Codex to run the six-question Yoke setup flow. The retrofit writes native skills to .agents/skills/, including yoke-retrofit and yoke-workflow; start a fresh Codex task if an already-open task does not discover newly installed skills. The npm package also contains .codex-plugin/plugin.json for Codex plugin hosts.

Staying up to date

Yoke checks for new releases npm/gh-style: a non-blocking background check (at most once a day, detached, offline-safe) prints a one-line hint when a newer version exists — upgrading itself is always an explicit act:

yoke upgrade                    # npm install -g @hecer/yoke@latest

Disable the check with YOKE_NO_UPDATE_CHECK=1 (it is also silent in CI, --json runs, and piped output). Projects that want the loop to self-update can opt in via .yoke/config.yaml:

update:
  auto: true   # upgrade at loop START only — never mid-run; applies from the next invocation

Auto-upgrade is deliberately not the default: a gate harness shouldn't change itself mid-project, and unreviewed auto-installs are a supply-chain hazard.

🤖 Driving it through an agent

Yoke is meant to be operated by your coding agent — after a retrofit, the agent has the skills, the safety policy, and the routing, so it knows the methodology. Copy-paste prompts (identical wording works for Claude Code, Codex CLI, and Gemini CLI):

Set it up — "Set up Yoke in this project. Ask me the Yoke setup questions one at a time with your recommendation, then run yoke setup . --yes with the selected host, agents, code graph, loop, runner, and decision policy. Commit in my configured identity."

Work the disciplined way — "From now on follow the Yoke skills you just installed: brainstorm → spec → plan → TDD → review before merging. Use the review skill before any merge."

Plan, then run autonomously — "Use the yoke-workflow skill. Ask only the planning questions that materially change the product, write the approved plan and loop-ready stories, then execute every approved story without routine follow-ups. Follow the configured auto or critical decision policy."

Watch / unblock — "Run yoke loop status .. If it says BLOCKED, run the project's verify command, find the root cause, fix it without weakening tests, then continue the loop."

⚠️ Long runs from inside an agent session: yoke loop run has no story cap by default; it continues until every planned story passes or a gate blocks. A multi-story run can therefore outlive most agents' shell-tool timeouts (Claude Code's Bash tool defaults to 2 minutes). If the outer tool call is killed mid-run, you get a stale lock and possibly half-finished state — which looks like a hang. Run the loop in the background (e.g. Claude Code's run_in_background), use --max=3..5 only when you intentionally want a bounded batch, poll with yoke loop status, and after any interrupted run do yoke loop cleanup before the next one. A running status with no update for 20+ minutes on a claude runner is worth checking — since 0.5.0 the runner streams continuously, so prolonged true silence is no longer normal.

⚠️ Never kill agent processes by name or command-line pattern (e.g. every process matching dangerously-skip-permissions): on a machine running several yoke projects, that takes down the healthy runners of the other projects mid-story — they stall and their loops block. yoke loop cleanup is the scoped alternative: each watchdog records its pids in the project's .yoke/runner.pid, and cleanup kills exactly those recorded trees — nothing else on the machine.

Agent cheat sheet — every command is an exit-code contract

Yoke's CLI is deterministic and chainable by design: an agent (or a shell &&) can branch on exit codes without parsing prose.

Command	What it does	Exit codes
yoke setup [dir] [--yes] [--host=] [--agent=] [--runner=] [--code-graph=] [--decision-policy=] [--loop|--no-loop] [--routing|--no-routing]	Shared six-question setup for Claude, Codex, and Gemini; adaptive routing is always an explicit opt-in	0 · 1 invalid setup
yoke validate [canonDir]	Validate the canon (schema, frontmatter, templates)	0 valid · 1 errors
yoke new <dir> [--idea=] [--agent=] [--runner=] [--loop]	Greenfield bootstrap: git init → scaffold → retrofit → context → PRD (drafted from --idea) → committed	0 · 1 usage / non-empty dir / draft failed (scaffold survives) · 2 draft agent unavailable
yoke retrofit [dir] [--agent=claude,codex,gemini|all] [--code-graph=graphify|serena] [--loop]	Install/update the harness, non-destructively	0
yoke prd draft [dir] --idea= [--runner=] [--force]	Idea → 5–12 stories with testable acceptance criteria	0 · 1 invalid/guarded · 2 agent unavailable
yoke prd check [dir]	PRD lint gate (schema, dependencies, cycles, duplicate ids, acceptance)	0 valid · 1 violations
yoke change add|status [dir] [--idea=]	Queue a change at any time; the loop turns it into append-only stories at the next safe boundary	0 · 1 invalid inbox/request
yoke context init|status [dir]	Durable context layer (PROJECT/DECISIONS/KNOWLEDGE/GLOSSARY.md, optional CONTEXT-MAP.md)	0
yoke loop on|off|status|decision|answer|resume|run|cleanup [dir]	Autonomous loop; run supports --parallel=N, bounded reference-driven --quality, and blind --candidates=N selection; --max=N creates an intentional batch cap; cleanup retains worktrees unless --remove-worktrees is explicit	run: 0 complete · 1 blocked/cap · 2 not runnable / already locked · 3 paused
yoke review [dir] [--reviewer=] [--base=] [--focus=] [--json] [--allow-self-review]	An independent model writes a schema-valid verdict	0 approved · 1 findings/invalid verdict · 2 no independent reviewer
yoke audit [dir] [--json]	Dependency, high-confidence secret, and sensitive-change audit	0 green · 1 blocking findings · 2 not runnable
yoke design-scan [dir] [--max=N] [--report]	Static AI-slop design gate	0 within budget · 1 over
yoke flow-smoke [dir] [--url=] [--label=]	Browser gate with screenshot/video proofs	0 green · 1 failures · 2 not runnable

A genuinely hung agent self-terminates after the idle timeout (default 20 min; --timeout), and yoke loop status shows the live phase or a ⚠ possibly stuck hint — an autonomous run is never a black box.

⚖️ How it compares — superpowers · gstack · Yoke

Three excellent projects, three different jobs. Honest version:

	superpowers (obra)	gstack (Garry Tan)	Yoke
What it is	The canonical skills methodology: brainstorm → plan → TDD → review as composable skills	A software factory for Claude Code: ~40 role skills (QA, CSO, ship…) + a real Chromium browser layer	A cross-agent harness: one canon → native installs, plus a gated autonomous loop
Agents	Claude Code first	Claude Code + hosts like Codex/Cursor/Kiro — no Gemini CLI	Claude Code, Codex CLI, Gemini CLI from one source of truth
Enforcement	Advisory — skills describe the discipline; following them is up to the agent	Skill-driven; browser QA is genuinely real	Mechanical — gates live in code: clean tree, acceptance criteria, green tests, review verdict, commit integrity
Autonomy	Interactive sessions	Interactive slash-commands (/qa, /ship, …)	Opt-in Ralph loop with watchdog, worktree isolation, single-flight lock, per-story proofs
Visual QA	—	Best-in-class: live browser daemon (Chromium/CDP) with deep interactive QA	Built-in flow-smoke gate: screenshots always, video on failure, labelled per story — lighter, but enforced and cross-agent
Cross-model review	—	/codex second opinion (Codex-only direction)	yoke review — resolves an independent provider and validates a structured verdict, inside or outside the loop
Footprint	Markdown skills (plugin)	~230 MB with browser runtime; hourly auto-update	Node CLI + markdown canon; Playwright only if you use flow-smoke, resolved from your project
License	MIT	MIT	MIT

They compose — use all three where they're strongest. Yoke's canon ships the superpowers methodology natively for all three agents (13 skills, attributed). And if gstack is installed, yoke retrofit detects it and adds a routing note to CLAUDE.md telling Claude to prefer gstack's live-browser /qa, /cso, and ship pipeline for what Yoke deliberately doesn't bundle — no dependency, no conflict, and Codex/Gemini artifacts stay uniform.

Choose Yoke when you run more than one agent, want autonomy you can audit (gates + proofs + logs), or want one place to maintain your team's methodology. Choose gstack when you live 100% in Claude Code and want the deepest interactive browser QA. Choose superpowers when you want the methodology alone, interactively, in Claude Code — or just use it through Yoke.

🏗️ Architecture

You curate one source of truth — skills, policy, and tool wiring. Yoke generates the idiomatic, native artifacts each agent expects, non-destructively, into any repo:

flowchart TD
    Canon["📦 CANON — single source of truth<br/>skills · policy · loop spec · tool wiring"]
    Skill["🛠️ yoke retrofit<br/>detect → plan → apply (backup) → report"]
    Canon --> Skill
    Skill --> Claude["Claude Code<br/>.claude/skills · .mcp.json · hook"]
    Skill --> Codex["Codex CLI<br/>AGENTS.md · config.toml · RTK.md"]
    Skill --> Gemini["Gemini CLI<br/>GEMINI.md · commands · settings.json"]
    Loop["🤖 yoke loop — autonomous Ralph loop<br/>gates · verify · review · isolation · proofs"]
    Claude -. drives .-> Loop
    Codex -. drives .-> Loop
    Gemini -. drives .-> Loop

Loading

Three layers — Canon (yoke validate) → Retrofit (yoke retrofit) → Loop (yoke loop) — on top of a durable Context layer (yoke context).

What gets generated per agent

Agent	Artifacts
Claude	Complete skill packages under .claude/skills/ (including referenced resources), AGENTS.md, CLAUDE.md, .mcp.json (code-graph + Playwright), and an rtk PreToolUse hook when WSL is available
Codex	Complete skill packages under .agents/skills/, per-skill implicit-invocation policy, AGENTS.md, RTK.md, .codex/config.toml, native hooks, reusable .codex/agents/*.toml, and package plugin metadata
Gemini	Complete skill packages under .gemini/skills/, an auto-invocation index, GEMINI.md, .gemini/commands/*.toml, and .gemini/settings.json (MCP + AGENTS.md context)

rtk integration: Claude receives its PreToolUse hook; Codex receives a native hook adapter around rtk hook check; Gemini retains instruction-mode fallback where its CLI has no equivalent command-rewrite lifecycle.

Composes with gstack: if gstack is installed (repo-local or global), yoke retrofit adds a short "Composed tools" routing note to CLAUDE.md only — telling Claude to prefer gstack's skills for capabilities Yoke doesn't ship (live-browser QA /qa, security audit /cso, ship/deploy /ship). No bundling, no dependency; the note is never written to the Codex or Gemini artifacts.

Your content survives re-retrofits — preserve blocks: anything you put between <!-- yoke:preserve:start --> and <!-- yoke:preserve:end --> in a generated file is carried into the regenerated version on every future yoke retrofit. The generated CLAUDE.md and GEMINI.md ship an empty preserve block scaffold — put your project-specific instructions (tech stack, workflow, @-includes) inside it. Works in any yoke-written file; content outside the markers is still replaced (and backed up under .yoke/backup/).

🧰 What's in the canon — 34 skills

yoke retrofit installs all of these into each agent natively. Provenance is credited in canon/skills/ATTRIBUTION.md.

To stop overlapping skills from auto-invoking against each other, canon/AGENTS.md carries a skill routing & precedence block (methodology before role; one canonical entrypoint per concern — e.g. pre-merge code review is always review), emitted into all three agents.

Each manifest entry also declares invocation: auto|manual. Retrofit translates that intent into the provider's native controls: Claude disables model invocation for manual skills, Codex writes agents/openai.yaml, and Gemini lists only automatic skills in its generated index. Validation rejects conflicting package metadata and broken local Markdown links before anything is installed.

Process / methodology — superpowers-derived discipline (13)

Skill	What it does
brainstorming	Explore intent, requirements & design before any creative work
writing-plans	Turn a spec into a bite-sized, TDD implementation plan
executing-plans	Execute a written plan in a separate session with review checkpoints
subagent-driven-development	Run a plan task-by-task: fresh subagent + two-stage review each
tdd	Write the test first, watch it fail, write minimal code, refactor
systematic-debugging	Root-cause first — no fix without a confirmed cause
verification-before-completion	Prove it actually works before claiming done
using-git-worktrees	Isolated worktrees for safe / parallel work
requesting-code-review	Request a structured review before merging
receiving-code-review	Handle review feedback with rigor, not blind agreement
dispatching-parallel-agents	Fan out 2+ independent tasks concurrently
finishing-a-development-branch	Merge / PR / cleanup a finished branch
writing-skills	Author and verify new skills

Roles — gstack-derived, de-gstacked to be harness-agnostic (7)

Skill	What it does
plan-eng-review	Architecture / edge-case review of a plan
plan-ceo-review	Founder-mode scope & ambition review of a plan
review	Single canonical pre-merge code review — diff safety + engineering quality (architecture, edge cases, tests, performance)
ship	Ship workflow: tests → review → version → changelog → PR
health	Code-quality dashboard with a composite score
retro	Engineering retrospective from commit history
document-release	Post-ship documentation sync (README / CHANGELOG / …)

Yoke-native — authored or adapted for this harness (14)

Skill	What it does
yoke-retrofit	Set up the Yoke harness in a project (detect → plan → apply)
yoke-workflow	Provider-neutral planning questions → approved PRD → autonomous stories → critical-decision resume
authoring-prd	Slice a product idea into loop-ready stories with testable acceptance criteria
minimal-code	Write the least code that solves the task (YAGNI; ponytail-derived)
performance	Efficiency as a measured requirement: benchmarks as tests, budgets as gates, optimizations local + documented
maintaining-context	Keep .yoke/context/ the durable source of truth (the Context layer)
workflow	The default order of operations, from idea to deploy
unslop-ui	Detect & remove AI-slop design tells (purple gradients, neon glow, emoji-icons…)
visual-verification	Widen verify to design-scan + the built-in yoke flow-smoke gate (screenshot proofs; video on failure)
no-ai-slop	Detect and edit generic AI prose while preserving the author's voice; includes its evaluation rubric
domain-modeling	Model boundaries, invariants, vocabulary, context maps, and decision records before implementation
codebase-design	Explore architecture, deepen a chosen design, and compare two viable approaches when tradeoffs matter
resolving-merge-conflicts	Resolve conflicts by reconstructing intent, then verify the integrated result
writing-for-agents	Write compact agent instructions with explicit triggers, constraints, resources, and checks

🌱 Zero to 100: yoke new + yoke prd

Yoke's greenfield entrypoint — one command from idea to loop-ready project:

yoke new my-app --idea="a CLI that tracks reading lists"   # scaffold + retrofit + context + PRD
yoke loop on my-app && yoke loop run my-app --isolate      # hand it to the loop

yoke new <dir> refuses a non-empty directory (greenfield-only — use yoke retrofit for existing projects), then: creates and git inits the directory, writes a minimal scaffold (README.md, .gitignore), runs the full retrofit (--agent= as usual), initialises the context layer (with --idea seeded into PROJECT.md as the north star), writes a commented PRD template to .yoke/prd.yaml, and makes the initial commit — so --isolate works from iteration 1. With --idea, it then drafts the PRD from your idea via an agent (--runner=, the configured runner or active host) and commits it as a second commit (docs: draft PRD from idea).

• Exit codes — 0 success; 1 usage / non-empty dir / draft failure (the scaffold survives — retry with yoke prd draft); 2 requested draft agent unavailable.

yoke prd draft [dir] --idea="..." turns an idea into 5–12 small, independently shippable stories with testable behavioral acceptance criteria (greenfield STORY-1 scaffolds the project skeleton + test suite and wires verify.command). An existing PRD with stories is never overwritten without --force; the untouched template doesn't trigger the guard. Runs through the same idle-timeout watchdog as the loop (--timeout). If .yoke/plan.md exists, its approved goals, non-goals, constraints, and decisions are injected as settled context instead of being reopened by the drafting agent.

yoke prd check [dir] is the chainable pre-loop lint gate: schema validation plus duplicate-id, empty-acceptance, unresolved-placeholder, and zero-stories checks. Exits 0 with ✓ PRD valid — N stories, M pass, 1 on any violation. The authoring-prd canon skill teaches interactive sessions the same story-slicing discipline.

🤖 The autonomous loop

Opt-in; yoke setup recommends enabling it for new installs, while retrofit alone keeps it off unless requested. Each iteration starts a fresh agent and passes through hard gates before anything is committed:

flowchart LR
    I[consume queued change<br/>as new stories] --> A[pick next PRD story]
    A --> B{clean worktree?}
    B -- no --> X[blocked]
    B -- yes --> C{acceptance<br/>criteria?}
    C -- no --> X
    C -- yes --> D[agent implements<br/>one story]
    D --> E{suite + criterion<br/>proof green?}
    E -- no --> X
    E -- yes --> V{UI design<br/>within budget?}
    V -- no --> X
    V -- yes --> F{reviewer<br/>approves?}
    F -- no --> X
    F -- yes --> G[commit + mark passes:true<br/>+ proof in .yoke/proof/]
    G --> I
    I --> H{all stories pass?}
    H -- yes --> J{integrated system<br/>gate green?}
    J -- no --> X
    J -- yes --> K[current backlog ready]

Loading

yoke loop on  .                 # enable (recorded in .yoke/config.yaml)
yoke loop status .              # show state + PRD progress
yoke change add . --idea="Add passkey login"  # safe while the loop runs
yoke loop run . \
  --runner=codex \               # implement with Codex…
  --reviewer=claude \            # …review with Claude (role separation)
  --isolate \                    # each story in a throwaway git worktree
  --parallel=3 \                  # run dependency-ready, non-colliding stories concurrently
  --decision-policy=critical     # pause only for high-impact decisions; routine choices stay autonomous
# Optional: add --max=20 only when this run should stop after a bounded batch.
yoke loop off .                 # disable

PRD format (.yoke/prd.yaml):

- id: STORY-1
  title: Add a health endpoint
  priority: 1                    # lower = higher priority
  acceptance:                    # Definition of Done (required, else blocked)
    - id: health-returns-200
      text: GET /health returns 200
      verify: [npm run test:health-returns-200]
    - id: health-rejects-post
      text: POST /health returns 405
      verify: [npm run test:health-rejects-post]
  passes: false                  # the loop sets this true only on green tests

New projects default to verify.requireCriteria: true: every story has 2–5 behavioral criteria. Each criterion ID must occur in its single, approved test command; shell operators and broad, untargeted suites are rejected. Yoke records each result in .yoke/proof/<story>/evidence.json. Configure optional completion.command for integrated journeys such as purchase → entitlement → relaunch or magic-link → callback → authenticated app. It runs whenever the current backlog has no open stories; this is readiness, not a release.

No generic tool can infer whether arbitrary test code perfectly represents product meaning. Yoke closes the mechanical false-done paths—targeted evidence, coverage review, clean committed state, and integrated journeys—while the project still owns the correctness of its tests and production observability.

Parallel workers and the quality gauntlet

--parallel=N dispatches dependency-ready stories concurrently. Claims carry leases, workers use isolated worktrees, collision areas are serialized, and only a mechanically green candidate enters the FIFO integration queue. Integration repeats the project gates against the merged tree; a worker success can never bypass a red integrated result. yoke loop status reports the dispatcher, workers, providers, worktrees, lifecycle, queue, integrations, and reopened stories.

Quality is reference-driven and opt-in. Declare what one story should match:

quality:
  reference: { name: approved-home, source: design/home.png, kind: file }
  candidate: { kind: screenshots, paths: [.yoke/proof/STORY-1/home.png] }
  rubric: Match the approved layout, hierarchy, spacing, and states.
  policy: blocking                 # or advisory

Configure project defaults, then enable the gauntlet for a run:

quality:
  enabled: false                   # keep opt-in, or make it the project default
  policy: blocking
  maxRounds: 3
  maxMinutes: 60
  consistencyChecks: 2
  maxParallelCandidates: 2
  critic: { agent: codex, model: gpt-5.6-sol }  # model required for --candidates
  repair: { agent: claude }

yoke loop run . --quality --quality-rounds=3 --quality-minutes=60
yoke loop run . --quality --candidates=2   # blind pairwise selection; stories need quality declarations

The critic compares opaque candidate/reference labels, writes schema-validated provenance, and cannot modify the project. Blocking findings enter a bounded repair loop and rerun every mechanical gate; advisory findings are retained without blocking. --quality-policy=, --no-quality, and --quality-unbounded override defaults for one run. Unbounded mode is explicit and warned because it removes repair limits, not Yoke's watchdog, isolation, verification, or commit safety.

State lives outside the model context — the PRD file plus git — so each iteration is fresh. Use yoke change add at any time. Its ignored append-only inbox is consumed at the next story boundary. A separate coverage pass must confirm that every requested outcome maps to behavioral criteria before Yoke appends and commits the new stories; existing stories are never rewritten and no restart is needed.

Watching a run

Every iteration emits token-free, harness-side feedback (Node console + local files — zero agent tokens):

• Live console with progress + ETA — ▶ S6 (19/45 · 42%) — implementing… · ~1h44m left (Ø 4m/story) … ✓ S6 done in 4m28s — 20/45 (44%) · ~1h40m left. The estimate uses the average duration of stories completed in this run (current velocity); before the first story lands it falls back to the recorded history of previous runs (.yoke/story-durations.json, last 50 stories, gitignored). No data yet → no estimate, never a made-up one.
• .yoke/loop-status.json — the current state (now including percent and an eta block); read it any time with yoke loop status:

  Loop: RUNNING on S6 "Weekly digest"
    implementing · iteration 20 · 19/45 (42%) · updated 30s ago
    ~1h44m remaining (Ø 4m/story)
  

• Parallel + quality detail — active workers include provider, candidate ID, worktree, lifecycle, phase, quality round, and repair budget; the integrator is shown separately.
• .yoke/loop.log — an append-only timeline of every phase transition.
• --json — machine mode for supervisors: every status write is also emitted as one NDJSON line on stdout ({"type":"status","state":"running","phase":"verifying",…} — the same shape as loop-status.json), the human narrative moves off stdout (the final summary goes to stderr), and a consumer can follow the stream line by line instead of polling the file. Provider JSON streams are also accounted: statuses (file + stream) carry cumulative input and output tokens for the whole run plus provider-reported cache-read, cache-write, reasoning, model, and cost fields when available. Missing values stay absent—Yoke does not estimate them.

Pausing a run

Drop a .yoke/loop.pause file (contents irrelevant) while the loop is running and it stops at the next story boundary — the running story still finishes, verifies, and commits; no story is ever cut off mid-flight. The loop consumes the pause file, writes state: "paused" to loop-status.json (log label paused), releases the lock, and exits with code 3. Resume by simply running yoke loop run again.

A per-iteration idle timeout guards against a genuinely hung agent: if the agent produces no output at all for --timeout minutes (default 20; 0 disables), the loop kills it (SIGTERM→SIGKILL) and marks the story blocked. A slow-but-working agent that keeps streaming output is never killed — the output stream is the liveness signal. Set a project default with loop.timeoutMinutes in .yoke/config.yaml.

Decision policy: autonomous by default, interrupt only when configured

Planning questions happen before the loop. The provider-neutral yoke-workflow skill asks only questions whose answer materially changes product behavior, scope, architecture, security, data ownership, external cost, or an irreversible choice. It saves the approved brief in .yoke/plan.md; yoke prd draft consumes it, and yoke prd check rejects explicit unresolved placeholders such as TBD.

The unattended loop then follows loop.decisionPolicy:

loop:
  enabled: true
  decisionPolicy: critical  # or auto
runner:
  agent: codex              # setup chooses the current host by default

• auto (default): routine ambiguity and implementation details are resolved using the approved plan, acceptance criteria, current code, and project conventions. The loop does not ask follow-up questions.
• critical: routine choices are still resolved automatically. Only high-impact decisions involving public architecture, security/privacy, destructive migration or data loss, material external cost, legal/compliance exposure, or another irreversible choice may pause the story. The agent writes a schema-validated request; the loop blocks before verify and preserves it as .yoke/pending-decision.yaml.

Inspect and answer a critical stop:

yoke loop decision .
yoke loop answer . --choice=A --rationale="Matches the existing identity model"

answer validates the choice against the still-open story, appends it to .yoke/context/DECISIONS.md, commits only that file using the configured human identity, clears the pending request, and resumes the same story with the original runner, isolation, review, permission, timeout, JSON, decision-policy, and iteration settings intact. Add --no-resume when a supervisor should restart the loop separately. If the automatic restart cannot begin because a provider/reviewer is unavailable or another process owns the lock, run yoke loop resume .; its request-bound options are retained under Git's private state directory until a loop actually runs. To intentionally abandon an orphaned or stale private resume state, use yoke loop resume . --discard; pending decisions are never deleted by that command. Existing loop.onAmbiguity: resolve|abort and --on-ambiguity= remain supported as compatibility aliases; new projects should use decisionPolicy: auto|critical.

Adaptive model routing (explicit opt-in)

yoke setup asks before enabling routing; the default is off. When enabled, the selected parent remains the strong planner/controller. Before each bounded story it receives only the story, acceptance criteria, and at most three eligible worker profiles, then returns one machine-readable choice. The worker can be a cheaper/faster Claude, Codex, or Gemini profile; SELF keeps difficult work on the parent. Provider-native subagents are disabled for these runs so Yoke does not pay for two orchestration layers.

Provider support: adaptive routing uses Yoke's shared provider adapter and works with Claude Code, Codex CLI, and Gemini CLI, including mixed-provider worker lists. Internal contract tests cover invocation and routing behavior for all three providers. The measured performance evidence below is intentionally Codex-only; it does not claim equivalent Claude or Gemini savings until authenticated, repeated in-the-wild runs exist for those providers.

runner:
  agent: codex
  model: gpt-5.6-sol       # optional; provider model strings stay opaque to Yoke
  reasoningEffort: high
routing:
  enabled: true            # setup defaults false; setup --routing opts in
  strategy: balanced       # balanced | cost | speed | quality
  maxCandidates: 3
  workers:
    - id: codex-light
      agent: codex
      reasoningEffort: low
      costTier: medium
      capabilities: [exploration, implementation, tests]
    - id: claude-fast
      agent: claude
      model: haiku         # rolling alias; omit to use the provider's current default
      reasoningEffort: low
      costTier: low
      capabilities: [mechanical-edits, tests]
    - id: gemini-auto
      agent: gemini        # omitted model means the account's current Auto/default route
      costTier: low
      capabilities: [large-context, implementation]

Use yoke loop run . --routing for a one-run opt-in or --no-routing for a controlled baseline. Routing control calls are read-only and deliberately tiny; malformed output or no eligible worker falls back to SELF. Yoke does not ship a universal, fast-aging "intelligence score". Candidate model IDs come from project configuration while setup defaults prefer rolling aliases or provider Auto/defaults. A per-user registry learns only from Yoke's independent verify/performance/audit/review gates, keyed by worker + provider + model/effort and expired after 30 days. It stores no prompts, source, or project paths—only a project hash and aggregate time/token/outcome evidence. Writes are immutable one-event files, so concurrent Yoke instances cannot overwrite a shared registry file.

Routing is not free: it adds one controller call per story. It is most promising when a bounded worker saves more than that call costs; tiny stories may be slower. Keep it opt-in and measure it on your own backlog rather than assuming a win.

Performance budgets: efficiency as a gate, not a style

Clean code is the default (the minimal-code skill) — but when efficiency matters, "should be fast" is a vibe the loop cannot enforce. Yoke makes it mechanical, at two levels:

• Per story: write the requirement as a measurable acceptance criterion ("imports 1M rows in < 2s, asserted by the bench test") and let your verify tests measure it — no new machinery needed.

• Per project: wire a benchmark as a standing perf gate in .yoke/config.yaml:

  perf:
    command: node bench/check-budget.mjs   # exit 0 = within budget
    retries: 1                             # benchmarks are noisy; same retry logic as verify

  The loop runs it after verify on every story (phase perf, with YOKE_STORY set); a red benchmark blocks the story — story S6 exceeded its performance budget: p95 62ms > budget 50ms — no matter how clean the diff was. The implementer prompt names the budget command, so the agent knows not to trade hot-path efficiency for style and never "simplifies away" an optimization without re-running the benchmark. The performance canon skill carries the method: profile first, optimize leaves not boundaries, commit benchmarks as tests, version the why of every optimization in context/DECISIONS.md.

Artifact-backed gate output: compact context, complete local evidence

Failed verify, executable-criterion, performance, configured custom-audit, and completion commands can emit thousands of low-signal lines. Yoke keeps the model-visible failure summary deterministic and bounded while preserving large raw stdout/stderr below .yoke/artifacts/:

output:
  previewBytes: 2048             # default: maximum compact preview bytes
  artifactThresholdBytes: 8192   # default: persist raw output only above this size

The preview prioritizes errors, warnings, adjacent context, and final test summaries. Above the artifact threshold it also includes a project-relative path, byte count, and full SHA-256 digest, for example:

[full output: .yoke/artifacts/STORY-4/verify-0123abcd4567.log | 42810 bytes | sha256:0123...]

An agent can read that ordinary file when the preview is insufficient; nothing is injected into later stories automatically. Repeated identical failures reuse the same content-addressed path. Successful gate output is discarded as before. This affects only commands executed by Yoke's own gates. It does not intercept tool output generated internally by Claude Code, Codex, or Gemini, so benchmark ratios for this feature are not provider-token or billing claims.

Command capture is capped at 16 MiB per stdout/stderr stream. Exceeding that quota fails the gate closed and stores the captured prefix with a [truncated output: ...] marker; Yoke never labels partial evidence as full output.

Yoke treats .yoke/artifacts/ as local, non-committable runtime state and excludes it from its clean-tree and story-commit operations; yoke retrofit also adds it to .gitignore. Raw command output is intentionally stored without redaction so it remains valid evidence and may therefore contain credentials, personal data, or other sensitive text emitted by project commands. Inspect artifacts before sharing them.

The loop trusts verify, not the agent's exit code: a story whose tests are green is committed even if the agent process exited non-zero (a common Windows .cmd-wrapper ghost). A failing verify is retried up to verify.retries times (default 1) so a transient flake self-heals while a real failure still blocks. Structured acceptance criteria are then verified individually; an unrelated green suite cannot satisfy a criterion without its proof command.

.yoke/loop-status.json, .yoke/loop.log, .yoke/loop.lock, its takeover/recovery leases, lock/decision temp files, .yoke/story-durations.json, .yoke/ambiguity.md, .yoke/artifacts/, and the critical-decision request/answering files are runtime artifacts; yoke retrofit gitignores them (along with .yoke/worktrees/, .yoke/backup/, .yoke/proof/, and .yoke/changes/) so they never trip the clean-tree gate.

Single-flight guard + cleanup

Two concurrent yoke loop runs would race on the PRD and status files, so the loop takes a lock (.yoke/loop.lock) for the duration of a run. Complete lock metadata is published atomically; stale takeover is serialized by .yoke/loop.lock.takeover. A second invocation exits 2 with Another loop is already running here (pid …). If that is wrong, run: yoke loop cleanup. A lock whose holder process is dead is taken over automatically (with a warning).

yoke loop cleanup [dir] reaps only runner process trees recorded by this project and removes a stale lock. Yoke-created worktrees are retained by default and listed in the output; pass --remove-worktrees to remove .yoke/worktrees/* with git worktree remove --force + prune. User-created worktrees are never touched. A live lock is reported and left alone. Exits 0 when cleanup succeeds, 1 if any requested removal fails. If a machine/process crash leaves the cleanup recovery lease itself behind, an operator can run yoke loop cleanup . --discard-stale-recovery; Yoke refuses while its recorded PID is alive, and the force flag must not be run concurrently.

🔍 Cross-model review (yoke review)

Outside the loop, yoke review has a second model review your current diff as a pass/fail gate — the interactive counterpart to the loop's --review/--reviewer.

yoke review .                       # review the uncommitted working tree
yoke review . --base=main           # review the range main..HEAD instead
yoke review . --reviewer=codex      # force a specific reviewer
yoke review . --focus="the auth layer"   # steer what it scrutinises

• Reviewer resolution — picks the first available of codex → gemini → claude, preferring a model other than the one you drive so the review is genuinely cross-model. On a Claude-only machine it degrades to a self-review (and says so).
• Scope — the uncommitted working tree by default, or a commit range with --base=<ref>.
• Exit-code gate — exits 0 when the reviewer approves, 1 when it finds a blocking issue, 2 when no (or an unavailable) reviewer CLI is found. Chain it: ... && yoke review, or wire it into a pre-push hook.
• Runs through the same idle-timeout watchdog as the loop (--timeout, default 20 min).

🎨 Visual & design verification — done, with a photo

Unit tests don't catch a blank page, an unwired route, or generic AI-slop design. Yoke adds three things:

• yoke design-scan [dir] — a static scanner for the visual tells of AI-generated UIs (AI-purple gradients, gradient hero text, neon glow, emoji-as-icons, gradient overload). It scores findings and exits non-zero over budget (--max, default 4; --report to list only), so it drops straight into your verify pipeline.
• yoke flow-smoke [dir] — a built-in browser gate with proof artifacts (below).
• unslop-ui + visual-verification skills — the design rubric, plus how to compose a verify pipeline (types → units → design-scan → flow-smoke).

Retrofit adds design: { mode: auto, max: 4 } when it detects UI dependencies, UI source files, or configured smoke flows. In auto mode the loop runs the design scan after functional verify and before performance/audit; on forces it for any project and off disables it. Existing explicit settings are preserved. flow-smoke remains an explicit project verify step because Yoke cannot infer how to start each application's server.

unslop-ui is the visual-design skill. no-ai-slop is separate: it reviews prose for generic AI patterns and edits only confirmed problems while preserving meaning and voice.

Tell set informed by the MIT-licensed vibecoded-design-tells research.

yoke flow-smoke [dir] [--url=<baseUrl>] [--label=<name>]

Configure your key user flows once in .yoke/config.yaml:

smoke:
  baseUrl: http://localhost:3000
  flows:
    - name: home
      path: /
      landmark: "main h1"   # optional CSS selector to wait for
    - name: login
      path: /login

For every flow, yoke flow-smoke loads the route against the running dev server, waits for the landmark, and fails on a non-OK response or any console/page error. The proof contract:

• Screenshots always — every flow (pass or fail) saves .yoke/proof/<label>/<flow>.png; the failure screenshot is the evidence.
• Video only on failure — each flow is recorded, but the clip is kept only when the flow goes red (<flow>.webm); green runs delete it.
• Labelled per story — inside the loop, verify runs with YOKE_STORY=<story-id>, so proofs land in .yoke/proof/<story-id>/ automatically. Standalone runs use latest, or pass --label=. The label dir is wiped per run — evidence is always from the latest run.
• Exit codes — 0 all flows green (chain it: ... && yoke design-scan . && yoke flow-smoke .), 1 any flow failed, 2 not runnable (no smoke: config, or Playwright missing).
• Playwright comes from the target project, never Yoke — npm i -D playwright && npx playwright install chromium there. Start the dev server before verify (e.g. via start-server-and-test); --url= overrides baseUrl.

.yoke/proof/ is gitignored by the retrofit — proofs are runtime artifacts and never break the loop's clean-tree gate.

🧠 Context layer (.yoke/context/)

Yoke keeps durable, cross-session context so a fresh-context agent is never blind:

• PROJECT.md — the north star (goal, constraints, non-goals, success criteria).
• DECISIONS.md — an append-only ledger. The loop adds an entry per completed story; you and agents add the why.
• KNOWLEDGE.md — reusable gotchas and conventions.
• GLOSSARY.md — the project's canonical terms, meanings, and aliases.
• CONTEXT-MAP.md — optional bounded-context relationships for projects that need domain mapping.

yoke retrofit scaffolds the four core files non-destructively; your edits are never overwritten. It reports CONTEXT-MAP.md when the optional file already exists. The loop reads them into every agent + reviewer prompt and logs decisions back on each story's commit. Decision history is explicitly delimited as untrusted reference data, so stored text is never treated as fresh instructions. Manage the files directly with yoke context init and yoke context status. The maintaining-context skill teaches agents to honour the same files during interactive work.

Commit .yoke/context/ to git. The --isolate loop runs each iteration in a worktree checked out from HEAD, so it only sees committed context.

🛡️ Safety model

Yoke's guardrails are mechanical, not advisory — the loop blocks on a dirty worktree, missing acceptance criteria, red tests, or a reviewer rejection, and none of them rely on the agent choosing to behave.

• Commit integrity — a story is never recorded passes: true without a corresponding commit; a failed commit reverts the PRD.
• Role separation — the implementer never reviews its own work; --reviewer can even be a different agent.
• Isolation — with --isolate, failed or partial work is discarded with the worktree and never reaches your main tree.
• Non-destructive retrofit — existing files are backed up before any change; settings are merged, not replaced.
• Independent verification — "done" means your test command exits 0, not "the agent said so".
• Single-flight — a lock prevents two loops from racing the same repo; yoke loop cleanup recovers after crashes.

🧠 Choose your code-graph

yoke retrofit --code-graph=graphify|serena (default graphify, remembered per project). The yoke-retrofit skill asks and recommends based on the project.

	graphify	Serena
Engine	tree-sitter AST + graph	real language servers (LSP)
Strength	fast, multimodal (code + PDFs + images)	symbol-exact cross-file refactoring
Token efficiency	~70× reduction on large mixed repos	standard, no index to go stale
Best for	rapid exploration / migration / onboarding	systematic refactoring in typed codebases
Caveat	heuristic edges; static index can go stale	one language server per language

🪙 Token efficiency

Yoke attacks tokens on two complementary surfaces:

• rtk compresses noisy command/tool output before it enters context (wired as a hook/instruction per agent).
• The minimal-code skill installs a YAGNI / "lazy senior dev" ladder so agents write the least code that solves the task — fewer output tokens, smaller review surface. (Adapted from the MIT-licensed ponytail ruleset.)

A Codex-only full-repository study ran three alternating-order pairs per arm. The same Sol parent completed all 12 stories and all 36/36 hidden acceptance checks; with routing enabled, a Sol controller selected Luna for every bounded implementation story. Including controller overhead, the routed median used 33.8% less wall time, 11.0% less fresh input, 49.5% fewer output tokens, and 78.2% fewer reasoning tokens. All three pairs improved wall time and fresh input.

The boundary matters: an earlier architecture/privacy task correctly stayed on SELF and paid controller overhead, so routing is an explicit opt-in rather than a universal win. Codex did not emit dollar cost for these plan-backed runs; Yoke reports the measured token breakdown instead of inventing a price. Method, ranges, controller cost, caveats, analyzer, and six raw JSON rows are in bench/RESULTS.md.

🧩 Optional companions

Two external tools pair well with Yoke and are documented (not bundled) in canon/tools/ — each has its own installer and update cadence, so Yoke wires the boundary instead of vendoring a copy:

• claude-mem — persistent cross-session memory for interactive work. Deliberate boundary: the autonomous loop keeps its memory explicit and versioned (context/*.md + PRD, fresh context per story), so claude-mem's automatic injection stays out of loop runs.
• ui-ux-pro-max — data-driven design intelligence (styles, palettes, industry rules) for the generation side. Yoke's unslop-ui, design-scan, and visual-verification remain the verification side: generate with pro-max, gate with Yoke.

🌱 Why & how it was built

The problem. Coding agents are powerful, but each speaks its own dialect — Claude has skills and hooks, Codex reads AGENTS.md and a TOML config, Gemini wants commands and a settings file. Keeping the same skills, safety policy, and tool wiring consistent across all of them means copy-paste drift and three things to maintain. Yoke exists to keep one source of truth, generate the right native artifacts for each agent, and let that harness run autonomously and safely when you want to hand it a spec and walk away.

The inspiration. Yoke is a synthesis of ideas already proven across the ecosystem: composable-skills methodology (superpowers, gstack); the portable AGENTS.md standard; the "one source-of-truth → idiomatic per-harness artifacts" generation pattern (wshobson/agents); spec-driven autonomous orchestration (GSD); mechanical safety gates and role separation (safe-agentic-workflow); and the Ralph loop (Geoff Huntley) — keep handing a fresh agent the next task until the spec is done. Token efficiency comes from rtk and the write-less-code idea behind ponytail.

How it was built. Yoke was built the way it's meant to be used — agent-driven, incremental, and test-first. The stack was chosen by researching alternatives first (which is how jcodemunch was dropped for its license and Serena was added as an option). Then every component shipped one small piece at a time through a disciplined loop: brainstorm → spec → plan → TDD implementation → an independent two-stage review (does it match the spec? is it well-built?) → merge. Those reviews caught real bugs before they shipped — a Windows .cmd spawn failure, a commit-integrity hole, a path-traversal that could delete project data, a resolution bug that broke the CLI's default invocation, a TOML-escaping bug. Yoke was even dogfooded on its own repo, which surfaced (and fixed) a genuine Windows bug. Every spec and plan lives in docs/superpowers/.

🗂️ Project layout

canon/            # the source of truth — harness-agnostic
  AGENTS.md  skills/  policy/  loop/  tools/  manifest.yaml
src/
  canon/          # manifest schema + validator (yoke validate)
  change/         # append-only change inbox · planning · independent coverage review
  retrofit/       # detect · plan · apply · planners (claude/codex/gemini) · tools
  loop/           # prd · gates · runner · verify · git/worktree · loop · run-command · lock · cleanup
  quality/        # reference collection · blind critic · bounded repair · candidate comparison
  new/            # yoke new — greenfield bootstrap
  prd/            # yoke prd draft|check — idea → stories + lint gate
  review/         # yoke review — cross-model diff gate
  smoke/          # yoke flow-smoke — browser gate with screenshot/video proofs
  scan/           # yoke design-scan — AI-slop design gate
  context/        # the durable context layer
docs/superpowers/ # the spec and every component's implementation plan

🗺️ Roadmap

Completed release work lives in the changelog. Remaining, explicitly scoped work is tracked in TODOS.md, including broader benchmark samples, native output schemas, and signed release provenance.

🧪 Development

npm test          # vitest (1020 tests)
npm run build     # tsc, no emit errors
npm run yoke -- validate canon

🙏 Credits & inspiration

Yoke stands on the shoulders of a great ecosystem: methodology ideas from superpowers and gstack; the AGENTS.md standard; the generator pattern from wshobson/agents; the Ralph autonomous-loop pattern; safety-gate thinking from safe-agentic-workflow; and the wired tools rtk, graphify, Serena, and Playwright MCP. The minimal-code skill adapts the MIT-licensed ponytail ruleset.

📄 License

MIT — see LICENSE.

_{Built with a disciplined loop: brainstorm → spec → plan → TDD → two-stage review → merge — and reviewed by a second model, because we don't trust "done" either.}