Jidoka Instruction Architecture
Build quality into agent instructions
One instruction architecture for humans and agents. Each of the eight layers holds a single job, and one command stops the line when a layer drifts, a job goes stale, or an invariant breaks.
Instruction files grow, and nothing catches the drift.
Prompt files pile up, layers repeat each other, and job entries go stale. No one notices until an agent does the wrong thing. Jidoka follows the Toyota practice of building quality into the process, so that the line stops at the first defect. In this architecture, every layer owns a single job and has a budget that a check can measure. A defect then points to exactly one layer, and the check fails before the defect ships.
Eight layers, from the most general to the most specific.
Each layer loads at a set moment and owns one concern. The layers that load on every run have a budget, so the context window stays small. The other layers load only when the work needs them.
How the harness works: turns, tool calls, and the completion signal. It contains nothing about your project.
Project identity: what it is, who it serves, and where to find its jobs and checklists.
Contribution standards, and the jobs each persona wants the repository to do.
One persona: its voice, the skills it routes to, and the limits of its scope. It holds no steps.
Protocols that several agents share: memory, coordination, and approval.
The complete steps for one domain of work, written as instructions. A reader needs no unwritten knowledge.
The data a procedure reads: templates, worked examples, and lookup tables.
A yes-or-no check at a pause point. It confirms that a known step happened.
One command runs three checks and stops at the first defect.
The jidoka command works as the andon cord: it
stops the line when it finds a defect. Each check owns one
class of defect, so every finding maps to exactly one fix. Run
it in your check script and in CI, and the build fails before
a drifted layer reaches the next agent run.
jidoka instructions
Every layer has a line cap and a word cap. A checklist block with too many items fails the check, and so does a checklist item that explains instead of confirms.
jidoka jtbd
Every job entry must match the schema, and every generated
block must match the manifest it comes from.
--fix regenerates a stale block in place.
jidoka invariants
It finds every *.rules.mjs module under
.jidoka/invariants/ and runs it through one
engine. The engine ships with the CLI, and the policy stays
in your repository.
Write your own rule in about twenty lines.
State one claim the code must satisfy, collect the subjects, and declare the rule. The check then fails the build on the first file that breaks the claim.
// Invariant: src/ never imports node:child_process.
// Every subprocess call goes through the shared runner.
export default {
name: "no-child-process",
build: ({ grep }) => ({
subjects: {
"src-file": grep({
pattern: 'from "node:child_process"',
globs: ["src/**/*.js"],
}),
},
}),
rules: ({ failAll }) => [
failAll("src-file", {
id: "no-child-process.import",
message: () => 'imports "node:child_process"',
hint: "call the shared runner instead",
}),
],
};❯ npx jidoka invariants
src/deploy.js
1 error imports "node:child_process" no-child-process.import
→ call the shared runner instead
✖ 1 problem (1 error, 0 warnings)The finding shows the file, the line number, the rule id, and the fix, so you do not need to search the repository yourself. The invariant rules guide covers AST scans, values that must agree across files, and a deny-list that only shrinks during a migration.
Two gates: one at entry and one at exit.
A checklist confirms that a known step happened. It does not
teach the step. If you have to explain an item, the procedure
above it is incomplete. A
<read_do_checklist> or
<do_confirm_checklist> tag wraps each gate,
so one rg search finds every pause point in the
repository.
Read each item, then do it. This gate loads the constraints into memory before the first line of work, because one missed constraint at that point sends the whole change in the wrong direction.
rg '<read_do_checklist'
Do the work from memory, then pause and confirm each item. This gate checks that you missed nothing before a commit, a merge, or a release. The items are independent, so the gate does not interrupt the work.
rg '<do_confirm_checklist'
Adopt it in four steps.
Install the skill pack and the CLI, ask Claude to set it up, and run the checks.
The bare command runs the layer check and the jobs check, and the second call runs your own rules. To add both to your check script and your CI workflow, see the stop the line guide. For the full standard, read the layered instruction architecture guide.