jediway
Refuse To Improvise

Watch a coding agent long enough and you will see the same failure in two costumes. The first is the taste document: deep modules, thin interfaces, do not abstract too early. Everyone nods at it, nothing enforces it, and the agent quotes it back to you while doing the opposite. The second is the orchestration prompt: spawn a worker, collect a report, ship. It has a process and no opinions at all, so the work is coordinated and mediocre. Separated, both fail the same way. The taste never reaches the code, and the process never asks whether the code is any good.

The failure has one root. Every time a model relays an instruction, it paraphrases, and paraphrase is where drift enters. Ask an orchestrator to "pass the guidelines along" and by the third child the guidelines are a friendly summary. The fix is small and unglamorous, and it is the entire plugin: if a rule must survive contact with a model, do not ask the model to carry it. Make a script paste it.

01 · The pressure

Paraphrase is the enemy

Before the machinery, feel the failure it answers. Nothing here is about models being dumb. It is about what happens to meaning when it is retyped.

An agent under pressure does not defy your standards; it reworders them. "Enforce each invariant once at the write path" becomes "keep validation consistent." "Abstract on the third occurrence" becomes "avoid duplication," which is the opposite advice. Each rewording is defensible on its own. The sum is a team of children each following a slightly different constitution, and an orchestrator confident it passed everything along.

So jediway is built on a division of labor that sounds almost too plain to matter. Judgement lives in Markdown a human wrote. Transport is a 37-line shell script. The model is allowed to exercise judgement exactly where judgement is wanted, and is never trusted with delivery. Four skills carry the opinions: taste holds the universal judgement and its ten-rule Creed, frontend and backend add only what is specific to each side, and way is the workflow that composes them. Roles are skills too. Nothing is a persona; everything is a file.

02 · The part that travels

Ten rules, pasted, never paraphrased

The taste skill is a full document on module depth, invariants, and when an abstraction earns its keep. Most of it stays home with the Master. What travels is the Creed.

1. Judgement over activity. "No change needed" and "this must change now" are both successful outcomes. Report real problems at their true severity; do not invent work.
2. Deep modules, thin interfaces. Pass-through layers, wrappers that only rename, and abstractions with one caller are shallow: inline or remove them.
3. Encapsulation is scope. Private by default, at the narrowest scope that uses it. Promote on the second real consumer, never speculatively.
4. Invariants are the design. Enforce each in exactly one place at the write path, trust it everywhere else. Make illegal states unrepresentable.
5. Validate at the boundary, trust inside. Re-validation mid-flow means a boundary is in the wrong place.
6. Duplication is cheaper than the wrong abstraction. Abstract only what changes together, for the same reason, on the third occurrence.
7. Dependencies point one way, inward or downward, never in cycles.
8. A dependency clears three bars at once. Removing one is a feature.
9. Read before you write, then conform. The repo's convention outranks your preference. Make the smallest diff that fully solves the task.
10. Never claim a check passed unless you ran it. If you could not run it, say so.

Ten rules is deliberate. The Creed rides in every prompt, so its stability is what makes child behavior predictable; the deep material stays in the sections behind it, where the Master reads it once. And the document names no libraries, on principle. Tools rotate; judgement does not.

03 · The contract

One artifact a script can judge

Before any child is spawned, the Master grounds the repo in facts: real gate commands confirmed against CI, baseline results, verbatim snippets with path:line, blast radius, invariants with their enforcement points. Then it writes one file, and everything downstream lives off it.

Two acceptance criteria are always present. Proof of effect: one check that is red before the change and green after, with the baseline recorded so nobody has to revert anything to prove the transition. Scope: git diff --name-only lists only allowed paths. The Spec is the one artifact a model writes freely, so it is the one artifact a script judges: lint-spec.sh checks the shape before compose, and then the Master argues the strongest case that the criteria miss the Mission, and fixes what survives. Walk the real example that ships with the plugin.

04 · The mechanism

Composition is a script, not an instruction

This is the load-bearing decision. Every child prompt is assembled by 37 lines of shell from four sources: the Creed, the Spec file, the previous round's handoff, and the role's fenced block. No model retypes anything.

The consequence is worth sitting with. Every child working a task receives a byte-identical Creed and Spec, and only its own role. There is no second instruction source for children, so there is nothing to drift from. If the Spec is defective, a child reports BLOCKED and does not repair it. If compose fails, the Master fixes the Spec or the skill it names, and never hand-writes the prompt. Switch roles below and watch what moves and what refuses to.

05 · The pipeline

One chain, cut at different points

The Master is the only role in the main session. It grounds, specs, plans, composes, dispatches, and judges. It never writes code. Children are created from one template with one role block swapped in, then discarded.

Build, review, and audit are not three workflows. They are one chain entered at different points, and the chain never shrinks: a small task shrinks the Spec, never the ceremony around it. Isolation is spent deliberately too. Verification is isolated and implementation is isolated, because a fresh context buys fresh eyes and those two roles are where fresh eyes pay. Planning is not isolated: the Master already read the files in Ground, and a Planner child would re-read them and lose the context.

06 · The judgement

A report is a claim until reproduced

Reports come back in one fixed shape: a result, per-criterion evidence with exact commands and exit codes, an invariants table, deviations, and a handoff of at most five lines. The Master takes none of it on faith, and re-runs none of it blindly either.

Reproduction is targeted. The Master re-runs the two criteria that decide the task, Scope and proof of effect, reads the diff rather than the summary, and re-runs the full gates only when the Implementer and the Verifier disagree. Three full gate runs per round was cost without information. The judgement also cuts both ways: existing tests and lockfiles are read-only for children, a weakened assertion is a High finding regardless of what else passes, and the Verifier must argue against each of its own findings before reporting them; the ones where the counter-argument wins ship under Rejected, with the argument attached.

Three rounds maximum, then escalate with the evidence so far. And the whole task's state is two files, .jediway/spec.md and .jediway/handoff.md: a fresh session resumes from them and nothing else, because no transcript ever carries forward.

07 · The honest part

What it refuses to promise

A tool sold as more than it is gets abandoned the first time the ceremony costs more than the task. So here is the fair read, straight from the README.

In Claude Code, read-only roles are genuinely locked out of edit tools by the plugin's agent wrappers. In Codex there is no equivalent, so read-only there is convention, and when the guarantee matters you run those roles in a read-only sandbox. That limit is printed in the README rather than discovered in production, because pretending otherwise is the kind of lie the Creed forbids.

• It is ceremony for small edits, and it says so. For a one-line fix the chain is overhead; the workflow's own advice is to say "inline" and skip it.
• It does not make a model smarter. It makes failure legible. A drifted child cannot hide behind a paraphrase, because there is none; a false "it passes" cannot survive a Judge that re-runs the command.
• Nothing enforces the discipline but the harness and the text. The whole plugin is Markdown and a few small shell scripts. That is a boast and a confession at once.
• The Spec is only as good as the Ground. A Master that grounds carelessly writes confident Specs about a repo that does not exist. The lint checks shape, not truth.

08 · The verdict

Markdown, shell, and one idea held all the way down

Strip the vocabulary away and jediway is one idea applied without exception: judgement is authored once by a human, and everything that must not drift is moved out of the model's hands and into a script's. The Creed travels by copy. The Spec is judged by a linter. The prompts are assembled by shell. The reports are reproduced by command. At every hop where a paraphrase could enter, the design replaces the model with something that cannot have an opinion, and at every hop where judgement is wanted, it hands the model a fixed contract and full freedom inside it.

That is a bounded promise, and it is enough. It will not make an agent brilliant. It makes an agent's work arguable: every claim has a command, every command has a baseline, and every finding carries the strongest case against itself. On a long enough run of agent work, that is most of the battle.

Take it for a run