jeff

A model-native quality control plane for agentic software work.

Jeff turns software work by frontier models into an inspectable engineering
process. A thin orchestrator routes atomic tasks through fresh specialist
contexts; builders never approve their own work; evidence survives outside the
chat; and a checked control plane decides whether each task is actually done.

The method is the product. Jeff supplies the quality lifecycle inside the
coding clients, model providers, and runtime systems you already use, while its
plain-file ledger keeps the process inspectable across sessions.

Five invariants carry the system:

1. Fresh context per stage. Planning, implementation, review, verification,
   and audit do not inherit a long, degraded conversation.
2. Builder is not judge. Test author, implementer, reviewer, executor, and
   verifier identities are mechanically separated where their roles conflict.
3. Evidence is durable. Task state, findings, approvals, test results, and
   dispatch provenance live in an inspectable ledger, not only in a transcript.
4. Gates are deterministic. Checked JavaScript validates legal stage graphs,
   identity separation, required evidence, convergence bounds, and completion.
5. Disagreement is bounded. Typed kickbacks, independent refutation, and one
   task-wide council converge without letting the orchestrator waive a failure.

Jeff is a cooperative protocol for one trusted operator and friendly agents,
not a security sandbox or hostile-child containment system. It validates the
method's state and contracts; tool isolation remains a property of each host.

Status

Jeff is finished and no longer under development. The method works, the gates
hold, and the code is stable. What it does not have is a maintainer adding to
it, so read it as a complete system rather than an active project.

What Jeff built records where the method ran, what it
caught, and what it cost. The graph and control-plane track moved to
jeff-control, also frozen.

Architecture

The kitchen is the interface, not the mechanism. You are the Chef. Jeff is the
sous chef that routes the order and holds the pass. The brigade consists of
fresh specialists, one station at a time.

The control plane is deliberately boring. src/cli/cook.js is the sole
operational entry point. The authoritative validator imports only Node's
standard library and src/core/*; there is no build step or runtime package
dependency inside the validation boundary. Models supply judgment. Checked
code supplies legality.

Two closed completion graphs

Capture interviews one question at a time. It records the destination, then
locks only the confirmed now increment and the task's primary outcome.
Inspired by Matt Pocock (MIT; see NOTICE).
The bundled YAGNI ladder is adapted from ponytail (MIT; see NOTICE). Loading the ponytail plugin beside Jeff is recommended; Jeff does not require it.
Code and operations then follow different graphs:

code       capture → plan + tests → implement → conditional refactor
                                      → review + conditional audit → done

operation  capture → plan → execute → verify + conditional audit → done

Code planning owns the proof and starts RED when behavior changes. A separate
implementer makes it green. Jeff then binds one full-suite run to an immutable
checkpoint before independent judgment. Operation planning instead defines a
bounded runbook, recovery boundary, exact approval boundary when needed, and
deterministic postconditions. A separate verifier observes every postcondition
in order. Executor evidence never substitutes for verification.

No active specialist can declare the whole task done. The validator derives
that result from the ledger.

Graph Engineering

Jeff 6.0 applied graph-engineering semantics to the work itself without
adopting a graph runtime or weakening a quality gate:

independently shippable outcomes into atomic tasks. deps alone schedules;

• Expose real width. Capture applies a fake-edge test and splits
  discoveredFrom records provenance without inventing dependencies.
• Drain the task DAG. cook ready, claim, claims, and release provide
  deterministic ready-set and atomic-claim primitives. Full-mode cook all
  runs independent lanes in isolated worktrees, then serializes integration
  against a gated checkpoint with an expected-old ref update.
• Remove false serialization. Independent judgments and source-bound
  refutations fan out concurrently.
• Carry facts, not conclusions. An optional facts-only context.md gives
  each cold specialist a verified repository map while keeping judgment
  independent.
• Make resume deterministic. An append-only journal.jsonl writes intent
  before specialist dispatches and external effects, so interruption does not
  become ambiguous replay.
• Repair the failed node. Typed findings identify the exact file and stage
  owed. A file-confined repair can retain an independently passing sibling
  judgment, while the full-suite gate always reruns.
• Scale escalation with evidence. A shrinking, confined blocker set can
  earn one bounded bonus cycle. Divergence still reaches a three-member
  council, and the validator re-derives the bound.
• Project state safely. cook snapshot --json exposes an additive,
  versioned, read-only machine projection for graph clients and other
  observers, even when the underlying store is invalid.

Bounded convergence

At the cap, Jeff dispatches three fresh, mutually blind inquiry specialists and deterministically derives each finding's vote result. A fourth fresh synthesis specialist selects one typed recovery route. The one bounded recovery episode preserves the original lineage, runs the applicable fresh gate and judgment round, then either completes the task or returns it to the Chef.

The detailed contracts and tradeoffs are recorded in the
6.0 Graph Engineering slate. The
machine projection
is also the boundary jeff-control
reads through, keeping schema knowledge in this repository.

Position in the ecosystem

Jeff is designed to sit beside existing clients and orchestration systems. Each
keeps ownership of the layer it is built to solve.

The mid-2026 field survey positioned Jeff around one specific combination:
fresh-context judgment, mechanically enforced builder/judge separation, durable
task evidence, and a deterministic completion gate. Adjacent systems lead in
execution, durability, observability, and throughput. See the
survey and design record.

What Jeff built

Jeff ran the task flow on three private applications through July and August
2026: a subscription strength-training app for iPhone and Apple Watch, a
transcription tool, and a native macOS dashcam footage manager. Between them
they carry a few thousand commits, and the shape Jeff imposes is visible in
their history: one issue per branch, a failing test committed before the fix
that turns it green, and independent review before a merge.

The clearest single record is issue
#234, observed on the
training app on 2026-08-11. Six tasks implemented by an external agent passed
three distinct reviewer agents, with every red case either traced or proven by
a constructed vacuous mutation, one task additionally security-audited, zero
blocking findings, and a green full-suite gate. They still could not reach
done, because the test author and the implementer were the same identity and
the invariant refuses that with no recorded escape. The operator had to ratify
a disclosed deviation by hand.

That episode is the method working and the method costing something at the same
time. Review caught what the invariant existed to catch, and the invariant
still blocked. It is a real limit rather than a bug: the gates are mechanical,
so work whose shape the pipeline did not anticipate needs an operator to
adjudicate. A typed waiver carrying the verifying reviewer's identity was
designed and never built.

The identity check had a second, quieter cost. Specialists cannot observe their
own dispatch id, so the first cook record of every stage failed and had to be
retried, which added six extra dispatches to a single task during the
context-engineering arc.

All three projects removed Jeff on 2026-08-29 and now track work with GitHub
issues and in-repo documentation. Their agent instructions say not to recreate
a .jeff/ store.

The tradeoff is the part worth taking. Jeff buys a completion proof and
evidence that outlives the transcript, and charges a round trip per stage to
do it. That is a fair price where someone may later ask what happened and the
answer has to be checkable rather than remembered. It is a poor price when the
work is moving quickly and the operator is the only reader it will ever have.
Fast-moving work is better served by lighter, prompt-level tooling, and that
is where this author's went:
pstack.

The invariants held, the evidence survived outside the transcript, and three
applications shipped under the method. Jeff is what taking the strict position
seriously enough to find where it binds actually produces.

Hosts and models

Claude Code, Codex, Cursor, Grok Build, and Pi are first-class Jeff hosts. Oh My Pi
installs the Pi package and uses its dispatch bridge. Grok Build consumes
Jeff's Claude Code-compatible plugin surface, including its agents, skills,
hooks, and marketplace metadata. A Grok Bot loads Jeff through the shipped
Cursor plugin. The adapters differ; the method, specialist contracts,
checked core, and evidence model remain shared.

Grok Build and Grok models occupy different layers. Grok Build is the coding
client; Grok 4.5 is a peer model-family design target alongside Claude Opus 5
and GPT-5.6 Sol. Jeff defaults specialist model selection to the orchestrator's
active provider and model and records the actual provider, model, and effort as
execution evidence.

Current dogfood is stamped GPT-5.6 Sol, July 2026. The stamp records operating
experience while compatibility remains host-neutral and model-open.

Host-native effort behavior remains explicit:

• Pi and Claude Code apply role-frontmatter effort where supported.
• Grok Build consumes the Claude Code-compatible agent definitions through its
  native subagent runtime.
• Codex specialists inherit orchestrator effort.

Install

Jeff is one versioned package with first-class install surfaces for each host.
Node.js >=22.19.0 is required by the Pi dispatch SDK.

Claude Code

claude plugin marketplace add johanthoren/jeff
claude plugin install jeff@jeff

Update the plugin, then restart Claude Code:

claude plugin update jeff@jeff

Codex

codex plugin marketplace add johanthoren/jeff
codex plugin add jeff@jeff

Refresh the marketplace snapshot and reinstall to update:

codex plugin marketplace upgrade jeff
codex plugin add jeff@jeff

Restart Codex Desktop and begin a new task so it loads the updated skills.

Cursor

Install from Customize, add the git marketplace, or load a local checkout
from ~/.cursor/plugins/local:

agent plugin marketplace add https://github.com/johanthoren/jeff

Update the marketplace snapshot:

agent plugin marketplace update jeff

Grok Build

Grok Build supports Claude Code-compatible plugins and can install Jeff
directly from GitHub. Git installs require an explicit trust decision. Review
the repository, then:

grok plugin install johanthoren/jeff --trust

Update Jeff:

grok plugin update jeff

An already up to date response means no change was needed.

Grok Bot

A Grok Bot loads Jeff through the shipped Cursor plugin on the Cursor
account that owns the Bot. Install that plugin from Customize, or load a
local checkout from ~/.cursor/plugins/local. Do not copy skills/ onto
the Bot computer.

Native specialist dispatch on that Bot's computer is Grok Build plus cook,
using the existing grok plugin and cook commands. There is no Grok Bot
CLI.

Do not paste credentials into chat or ordinary files. Use the Grok Bot
secrets card.

Pi

Install the stable npm release:

pi install npm:@johanthoren/jeff

Update or pin it:

pi update npm:@johanthoren/jeff
pi install npm:@johanthoren/[email protected]

For deliberate development installs from the live repository:

pi install git:github.com/johanthoren/jeff

Oh My Pi

Install the stable npm release:

omp plugin install @johanthoren/jeff

Re-run the same command to update an npm-installed copy. omp plugin upgrade
is for name@marketplace installations.

OMP specialists do not inherit orchestration extensions, custom or MCP tools,
advisor behavior, memory/autolearn, or model fallback. Applicable user and
project SYSTEM.md instructions still tighten or specialize Jeff's bundled
standards floor.

Verify installation

After an update, start a new host session, then inspect the loaded package with
the host's read-only inventory command:

Plain npm install @johanthoren/jeff downloads the package into
node_modules; it does not activate Jeff in any host.

Set up

Activate Jeff once per repository:

• Full mode: for a repository whose task registry Jeff owns. Ask to set up
  Jeff, or run cook init. The committed .jeff/ store carries the registry
  and full dependency graph.
• Lite mode: for a shared repository whose team already owns planning and
  integration. Ask to set up Jeff Lite, or run cook lite. The local ledger is
  git-excluded and the configured issue or plan store remains authoritative.

Use

Describe the work normally. In an active project, the host first assesses it
without making a durable change.

• Explore: disposable experiments and local evidence stay ad hoc.
• Remember: an explicit Remember request is the consent to write durable memory without creating work.
  Full mode uses .jeff/memory/; elsewhere Jeff
  prefers a suitable tracked memory, decisions, learnings, or handoff file and
  preserves its purpose and format, then falls back to local .jeff/memory/.
  Without explicit Remember or another persistence request, ordinary work does not write durable memory.
  AGENTS.md, READMEs, and product documentation are not memory stores.
• Record: create pending future work without starting it.
• Start: cook <id> and cook on <ref> are equivalent forms to start or resume a recorded task through the quality pipeline.

Before the first durable write on consequential work, Jeff offers a clear
choice: ad-hoc local ship, record pending, or record and start capture. Risky
production, data, security, accessibility, release, and shared-state work
always restores that boundary.

Once tracked work starts, Jeff becomes the thin orchestrator. It routes and
records. Fresh specialists plan, build, simplify, judge, and audit. The
mechanical gate, not momentum in the conversation, decides done.

Re-fire until it's worthy.

Read deeper

• Design rationale: system boundaries, invariants,
  pipeline graphs, and checked control plane.
• 6.0 Graph Engineering slate: field survey,
  throughput mechanisms, targeted repair, DAG drain, and projection contracts.
• Visual system atlas: Architecture, Graph
  Engineering, and bounded convergence from three mutually blind inquiry specialists through a fourth fresh synthesis specialist in one sheet
  (dark theme).
• State schema: persisted records
  and validator-derived invariants.
• Operational method: the complete orchestration loop.
• Maintenance stance: pace layers, model drift, and
  design for deletion.
• Kitchen voice: the persona as a render layer over a fixed
  technical substrate.
• jeff-control: the Rust
  projection daemon and graph client, split out and likewise frozen.

Prefer plain talk? Set JEFF_FLAVOR=plain. A per-repository "flavor" value
in .jeff/config.json overrides the environment, and a live conversation
choice overrides both. The work and evidence are identical.