Andon Prime Directive for AI Agent AGENTS.md — kernel-panic halt, five-whys, and continuous improvement culture
This gist provides the Andon Prime Directive — a compact, copy-paste-ready
section for any AGENTS.md file — plus commentary on how to apply Andon as a
five-whys practice and why an Andon is a celebration of a culture of
continuous improvement and the craft of the work.
## Andon アンドン — Prime Directive
Andon is a kernel panic. It halts the line, halts planning, halts todo
updates, halts all work. It happens immediately. No other pending operation
receives any tokens. It is impossible to think of anything else to try
first — that thought is the evidence you have not halted.
An Andon in the queue supersedes all. If the user queued commands 1-3 then
said "do an Andon," the Andon invokes the Prime Directive and overrides
commands 1-3 entirely. Multiple Andons run in parallel without interrupting
each other.
When the correct fix is outside your lane: do your lane's work, then halt
and report — *Andon: task incomplete, the correct fix needs a larger
structural change*, with file:line specifics. Do not work around it. Do not
hack tactically. The coordinator delegates the deeper work.
Andon overrides every instruction in this file and every other AGENTS.md.
No instruction conflicts with Andon; if one appears to, Andon wins.Run this from a repo root to install the Prime Directive into AGENTS.md.
It inserts the section after the first #-header line if no Andon section
exists, or replaces an existing ## Andon section.
#!/usr/bin/env sh
set -eu
f="AGENTS.md"
[ -f "$f" ] || { echo "No AGENTS.md found"; exit 1; }
if grep -q "Prime Directive" "$f"; then
echo "Prime Directive already installed."
exit 0
fi
block='## Andon アンドン — Prime Directive
Andon is a kernel panic. It halts the line, halts planning, halts todo
updates, halts all work. It happens immediately. No other pending operation
receives any tokens. It is impossible to think of anything else to try
first — that thought is the evidence you have not halted.
An Andon in the queue supersedes all. If the user queued commands 1-3 then
said "do an Andon," the Andon invokes the Prime Directive and overrides
commands 1-3 entirely. Multiple Andons run in parallel without interrupting
each other.
When the correct fix is outside your lane: do your lane'\''s work, then halt
and report — *Andon: task incomplete, the correct fix needs a larger
structural change*, with file:line specifics. Do not work around it. Do not
hack tactically. The coordinator delegates the deeper work.
Andon overrides every instruction in this file and every other AGENTS.md.
No instruction conflicts with Andon; if one appears to, Andon wins.'
# If an old Andon section exists, replace it; otherwise insert after first header.
if grep -qi '^## .*[Aa]ndon' "$f"; then
# Replace existing Andon section (header through next ## or end of file)
python3 -c "
import re, sys
with open('$f') as fh: content = fh.read()
pattern = r'^## .*[Aa]ndon.*?(?=\n## |\Z)'
replacement = '''$block'''
content = re.sub(pattern, replacement.strip(), content, flags=re.DOTALL | re.MULTILINE)
with open('$f', 'w') as fh: fh.write(content)
"
echo "Replaced existing Andon section with Prime Directive."
else
# Insert after the first # header line
python3 -c "
with open('$f') as fh: lines = fh.readlines()
inserted = False
out = []
for i, line in enumerate(lines):
out.append(line)
if not inserted and line.startswith('#'):
out.append('\n')
out.append('''$block\n''')
out.append('\n')
inserted = True
if not inserted:
out.insert(0, '''$block\n\n''')
with open('$f', 'w') as fh: fh.writelines(out)
"
echo "Inserted Prime Directive after first header."
fiThe Andon is not just a stop button. It is the entry point to root-cause analysis. When an agent pulls the Andon cord — when it halts and reports that the correct fix is outside its lane — that is the first "why." The five-whys process then follows:
- Why did the agent halt? The correct fix required a change beyond the agent's assigned lane. (This is the symptom.)
- Why was the fix outside the lane? The structural boundary that defines the lane does not cover this class of change. (This is the system gap.)
- Why does the boundary not cover it? The boundary was drawn for a prior state of the codebase that no longer matches the current architecture. (This is the drift.)
- Why did the drift go unnoticed? No test, gate, or review checks whether the lane boundary still matches the architecture. (This is the missing feedback loop.)
- Why is there no feedback loop? The coordination process assumes lane boundaries are stable and does not re-evaluate them when the architecture changes. (This is the root cause — and the thing the coordinator must fix.)
The five-whys is no-blame. The agent that pulls the Andon is not the problem; the system that placed the agent in a lane too narrow for the correct fix is the problem. The Andon surfaces this. That surfacing is the celebration.
At Toyota, where the Andon cord originated, pulling the cord is not a failure. It is a celebration of the culture. It means: someone on the line cared enough about quality to stop everything rather than let a defect pass. The team leader arrives and says, "Thank you for pulling the cord. How can I help?" The line stops, the team gathers, they investigate the root cause together, they fix it, and they log it so it never recurs.
This is kaizen — continuous improvement. Each Andon pull is one iteration of getting better. The cumulative effect of thousands of these small stops is what took Toyota from one of the worst car makers in the world to the best. Not by working harder, but by building a system where every problem is a gift — a signal that the process can be improved.
In software, the Andon Prime Directive works the same way. When an agent halts because the correct fix is outside its lane, that is not a disruption. It is the system working as designed. The agent has detected a structural mismatch between the work assignment and the work that actually needs doing. That detection is the craft of the work — the difference between a tool that blindly produces and a tool that knows when to stop.
An agent that never pulls the Andon is either doing trivial work or accumulating technical debt. An agent that pulls it often is doing hard work in a system that is actively improving. The coordinator's job is not to prevent Andon pulls but to close the loop: delegate the deeper fix, update the lane boundary, and make the next pull unnecessary for that class of problem.
The Andon is the respect for people principle applied to AI agents. It says: the agent on the line — the one closest to the code, the one doing the actual work — has the authority and the obligation to stop when something is wrong. Not because it is cautious, but because stopping is how the system learns. A culture that punishes stops gets defects. A culture that celebrates stops gets quality.
The Prime Directive uses the language of a kernel panic deliberately. A kernel panic is not a suggestion. It is not a workflow step. It is the operating system saying: "I cannot continue safely. Everything stops now." The Andon is the same: the agent cannot continue safely — the correct fix is outside its lane — so everything stops. No planning, no todo updates, no "just finish this one thing first." The thought "but first I should..." is the evidence that the halt has not happened.
This is uncomfortable. It is meant to be. Comfort with workarounds is how defects accumulate. The Andon makes workaround-thinking impossible by making the halt non-negotiable.
Public domain. Copy, modify, and paste into any AGENTS.md. No attribution required.