From Human Gates to AI Referees: The Third Iteration of AI Coding Workflow Design

From serial verification, parallel collaboration, to the respective Referee optimizations for three workflows.

Previous two articles:

• 《AI 编程工作流的设计：串行验证设计》
• 《AI 编程工作流的设计：并行协作设计》

The previous two articles solved two types of problems:

• First article: serial verification. Breaking development into context, solution, implementation, review, and verification, using Gates to guarantee "don't write code before you've thought it through." This structure suits dev-workflow, and was also referenced by bugfix-workflow.
• Second article: parallel collaboration. Turning the serial pipeline into Router + Worker, letting Analyst, Coder, and Reviewer start early and reduce waiting. This structure is dev-workflow-router.

But after running all three routes, new problems appeared:

• Every task stops to wait for a human, making the human the bottleneck; can AI be used to judge instead?
• If AI judges, each of the three routes maintains its own set of judgment rules, which can easily diverge.
• If AI judges, retrospectives become AI self-reviews, and rules may grow and become messier with each iteration.
• The same Skill needs to be maintained as a thin shell in DSH, Claude Code, and Codex, while the core must iterate as one unified set.

So this article does not design a new process, but optimizes the existing three workflows:

Workflow	Main problem solved	Judgment core	Focus of this optimization (Referee independence)
dev-workflow	Feature development, refactoring, UI, build config	Two-axis Gate (shared core with dev-workflow-router)	Independent Referee for requirement/solution two-axis comparison; green/yellow continue, red stops
dev-workflow-router	Complex development requiring parallel collaboration	Two-axis Gate (shared core with dev-workflow)	Independent Referee for comparison/retrospective; shared core and ledger
bugfix-workflow	Faults requiring systematic diagnosis	Independent four-axis traffic light (independent core)	Independent Referee for triage recheck/retrospective; retrospective changed to record/propose

The Referees in all three workflows are independent instances: created fresh each time, not sharing the main session, and not reusing Referees from other workflows. What is shared is the Referee's operating mode (independent, no tools, single turn, fixed input, structured output, rule changes approved by humans), not the judgment criteria.

The judgment criteria are separate:

• dev-workflow and dev-workflow-router share the two-axis Gate and the .gate/v8/ ledger;
• bugfix-workflow uses an independent four-axis traffic light and .bugfix/ ledger, not sharing judgment criteria with development workflows.

In short: The three workflows share the Referee's operating mechanism, but not the judgment criteria; the two development lines share v8, and bugfix is independent.

This article does not discuss "how to make the model write better code," but rather: how to make AI workflows actually run, run for a long time, and improve themselves in real development.

---

1. Introducing the AI Referee: independent judgment layers for each of the three workflows

1.1 All Gates blocking humans is costly

The Gates from the previous two articles are "key decisions released separately":

Gate	When it stops	What the human must confirm
#0 Context	After context is sorted	Whether the scene, goal, and impact scope are understood correctly
#1 Solution	After solution and AC are written	Whether technical trade-offs, scope of changes, and risks are acceptable
#2 Implementation	After code and self-check complete	Actual changes, deviations, and real-device verification results

This mechanism works for "a small number of high-value tasks," but as tasks increase, costs emerge:

Cost	Specific manifestation
Waiting cost	Each task stops at least twice; if a human is absent, it gets stuck
Attention cost	Many card contents repeat; humans tend to only look at conclusions, not evidence
Judgment fatigue	After seeing many, people lean toward "just click confirm," and Gates become formal
Inconsistency	Different times and different people judge the same type of problem differently
Context switching	A human just returning from another task struggles to re-enter the details

More critically: Most tasks do not require a human decision at every Gate.

What truly needs a human is usually only three types:

1. The solution has substantive trade-offs, and AI cannot give a single reasonable answer;
2. The judgment is stuck on a red card, requiring additional information or acceptance of costs;
3. The need to modify the "judgment criteria" itself.

In other cases, AI should first give a checkable judgment, and humans only need to spot-check at key points, not accompany every task from start to finish.

1.2 What is a Referee

A Referee is an independent judgment role in the workflow.

It is not "opening another chat window to ask the model"; rather:

• No tools: does not read files, search code, or check logs;
• Single turn: one input, one output, no agent loop;
• Fixed input: only receives a payload assembled by the main Agent;
• Fixed-length output: only outputs structured JSON, no long analyses.

It solves only the "judgment" problem; it is not responsible for investigation, implementation, or review.

Think of it as three roles:

Role	What it is responsible for	What it is not responsible for
Main Agent	Investigation, breakdown, implementation, orchestration	Does not issue a "pass" to itself
Referee	Independently judges whether requirements/solutions/faults hold	Does not gather evidence, modify code, or set final conclusions
Reviewer	Independently reviews implementation and regression	Does not participate in implementation derivation

The Referee's value is not "smarter than a human," but:

• It is not influenced by the main Agent's implementation approach;
• It starts from zero each time, without historical baggage;
• Its input and output are fixed, so costs are predictable;
• Humans can spot-check, re-compute, and question it at any time.

1.3 Most cases don't need a human

This optimization changes "human must confirm" to "only red cards and standard changes require a human":

Judgment	Who handles	Whether it stops
Green	Directly proceed to implementation	Does not stop
Yellow	Directly proceed to implementation, but with known risk	Does not stop; human can interrupt at any time
Red	Human handles	Stops, waits for additional info or decision
Standard change	Human approval	Stops, waits for explicit approval

Note that this means "no human confirmation needed at every Gate," not "humans have no power."

Humans retain:

• Final authority over goals and trade-offs;
• The power to interrupt, correct, and veto at any time;
• Handling of red cards;
• Approval rights over rule changes;
• Confirmation rights over real-device verification and final delivery.

In short: AI is responsible for keeping the process running; humans are responsible for applying the brakes where it truly matters.

1.4 A self-evolving system

This optimization no longer lets AI "review itself each round and change its own rules." The problems with that approach:

• Retrospectives become AI self-evaluations, which tend to rationalize its own judgments;
• Every round proposes rules, quickly inflating the rule base;
• Humans don't have time to read a flood of low-value proposals;
• After rules change, no one knows whether to roll back.

The new approach is "record signals, propose only when conditions are met":

Human interruption / correction / negative feedback
        |
Referee records human_signal
        |
Accumulate same-type signals by signature
        |
Same type < 2: only record the case (record)
Same type >= 2: generate a rule change proposal (propose)
        |
Human approves -> takes effect next round
Human rejects -> keep the case

Several key points:

• Human judgment has highest priority: human_signal directly records the human's exact words and conclusion; AI does not re-judge it;
• Propose only for similar cases: one signal might be a fluke; only two or more instances justify a rule change;
• Proposals must include five items: which rule to change, why, counter-example, falsification conditions, rollback method;
• Only humans can approve: neither Referee nor main Agent can write to the standards file;
• Takes effect next round: you cannot use newly changed rules to judge the case that just occurred;
• Rollback-able: after a rule takes effect, keep observing; if counter-examples appear, it can be rolled back.

This way the rule base does not "grow a line every round," but rather "only changes when something genuinely recurs."

1.5 Other additions

Auditable. Every judgment has fixed input, fixed output, and a ledger event. Humans can look back at "what was seen, what was judged, and why."

Degradable. If the Referee fails to start, times out, or outputs out of contract, it records n/a; the main Agent continues according to rules and explicitly marks "not independently judged," without pretending it was.

Cost-controlled. The Referee has no tools, single turn, short output; at most 4 calls per task, typically 0-2.

Clear boundaries. Referee does not replace humans, does not replace Reviewer, and does not replace real-device verification. It only does the "judgment" part.

---

2. Traffic light design: turning "can we start" into something decidable

The traffic light was originally designed for bugfix-workflow: in fault fixing, the worst thing is "directly modifying without knowing the cause." Later it was found that this "axis-based judgment + mandatory checks" approach suits real engineering better than a simple "can we start."

2.1 Three light colors

Light	Meaning	Default action
🟢 Green	Expectations clear, cause located, solution determined, scope controllable	Directly enter implementation; no human confirmation required
🟡 Yellow	Has a reasonable hypothesis or candidate solution, but still lacks evidence or authorization	Stop (in dev workflow, pass with risk); human provides evidence, or explicitly authorizes "try to fix based on current hypothesis"
🔴 Red	Goal ambiguous, key evidence missing, neither cause nor solution formed	Stop; can only re-judge after evidence is supplemented; cannot authorize direct fixes

The most easily misunderstood is the yellow light.

Yellow is not "almost green," but "can try, but you need to know what you're trying." So a yellow must state:

• What the hypothesized cause is;
• Supporting evidence and counter-evidence;
• How to verify;
• How to roll back on failure.

If these cannot be written, it's not yellow, it's red.

2.2 Four axes + mandatory checks

The traffic light is not guesswork; it checks four axes first, then mandatory items.

Axis	Value	Meaning
Cause axis	RC1	Located, with static or runtime evidence
	RC2	Evidence-supported, but not fully verified
	RC3	Not located
Solution axis	FX1	Fix solution determined
	FX2	Has candidate solutions, needs selection or verification
	FX3	No technical solution
Evidence axis	EV1	Runtime evidence (logs, screenshots, reproduction)
	EV2	Static evidence (code, config, call chain)
	EV3	User report
	EV4	Inference
Scope axis	SC1	Single point, single page, local
	SC2	Multiple paths, multiple pages
	SC3	Cross-module, involving architecture or shared contracts

Mandatory checks are "veto / stop" checks:

Mandatory	Meaning	Result
H1	Key evidence cannot be gathered	Red
H2	Requires authorization (e.g., verification fix)	Yellow, wait for authorization
H3	Goal not unique; same feature has multiple implementations	Red, have human point out first
H4	Involves dangerous operations, requires separate authorization	Yellow/Red, depending on operation risk

2.3 Composition rules

Judgment order matters; wrong order can downgrade a red light to yellow.

1. H3: goal not unique -> red
2. H1: key evidence cannot be gathered -> red
3. RC3 + FX3: neither cause nor solution -> red
4. H2 / H4 not authorized -> yellow
5. RC1 + FX1 + SC1 + H4 authorized (or not involved) -> green
6. RC2, or RC1 + FX2/FX3, or RC3 + FX2 -> yellow
7. Otherwise -> red

A simpler version to remember:

• Green: know why, know how to fix, scope controllable;
• Yellow: have a reasonable hypothesis or candidate, but still need verification/authorization;
• Red: neither "what to fix" nor "how to fix" has formed yet.

2.4 What cards look like

Different light colors have different information density.

Green card:

【F-20261109-01 · 🟢 Green】

What should be:
What actually is:
Cause and causal chain:
Fix solution:
Scope (IN / OUT):
Verification contract:
Acceptance criteria (AC):
Conclusion:

Green is not "fix casually," but "information is sufficient to start directly."

Yellow card:

【F-20261109-01 · 🟡 Yellow · hypothesis to verify】

Hypothesized cause:
Supporting evidence:
Counter-evidence / explanations not yet excluded:
Verification method:
How to roll back on failure:
What you need to confirm/authorize:

The core of a yellow card is a "verifiable hypothesis," not "I think it might be."

Red card:

【F-20261109-01 · 🔴 Red · cause unknown】

What can be established now:
What is still missing:
Suggested how to supplement:
How to verify after supplementing:
What you need to point out/decide:

Red cards do not give technical solutions; they only provide "reproduction direction" and "what needs to be supplemented."

2.5 Yellow authorization vs. red non-authorization

Yellow can be authorized, but authorization must be explicit:

• "Try to fix based on current hypothesis"
• "Fix this version first and see the result"
• "Authorize verification fix"

A vague "confirm" only means "read", not authorization.

Red cannot be authorized for direct fixes. Red can only:

1. Supplement evidence;
2. Supplement a verifiable hypothesis;
3. After turning yellow or green, enter implementation.

This is not process purism; it's because red means "we don't yet know what we're fixing." Starting under these conditions is likely to create a second problem.

2.6 Difference between traffic light and development Gate

Item	Development Gate (dev-workflow)	Traffic light (bugfix-workflow)
Judgment object	New requirement + solution	Fault cause + fix solution
Main axes	Requirement axis, solution axis	Cause axis, solution axis, evidence axis, scope axis
Green	Requirement clear, solution uniquely feasible	Cause located, solution determined, scope controllable
Yellow	Open risks, but can continue	Has hypothesis/candidate, needs verification or authorization
Red	Requirement or solution fails	Cause/solution/evidence insufficient
Stop point	Red card	Yellow card, red card

Both use "green/yellow/red," but the axes differ. Don't apply the development "requirement clear" to the fault "cause located."

---

3. Referee design: independent, single-turn, verifiable

3.1 Three principles

First, no tools.

Referee does not read files, search code, or check logs. It only receives the payload assembled by the main Agent.

This is not to save money, but to prevent it from sliding from "judgment" to "exploration":

Ask it to judge, and it starts reading ten files to confirm; after reading ten files, it starts changing code.

Second, single turn.

One input, one output. No multi-turn follow-up questions, no tool calls, no "let me take another look."

This makes costs predictable, output recomputable, and avoids carrying over the main session's history.

Third, fixed input.

Each call only provides:

• The structured facts needed for this judgment;
• The current standards;
• On-request retrieved similar cases (at most 5).

No full chat history, no implementation process, no hints like "I already think it should be green."

3.2 Three forms

The Referee does different things at different stages, but the underlying mechanism is the same.

Form	When used	Input	Output
Approve	When a human states "what the old behavior is"	text + as_is + source location	premise: ok / mismatch / missing
Compare	Dev Gate step 3-4	standards + outputs of steps 0-2 + capability domain/candidates + L1 results	two axes + domains + causes + risks + suggestions
Review	Phase 4 triggers retrospective	original judgment card + human's exact words/conclusion/evidence + same-case count + standards	human_signal + same_case_count + action + case_record + proposal

Commonalities of the three forms:

• All output JSON only;
• None read files;
• None make final decisions for humans;
• All have explicit output contracts.

3.3 What retrospective output looks like

Retrospective is not "judging again," but "recording human signals and deciding whether to change rules."

{
  "human_signal": {
    "target": "F-20261109-01",
    "quote": "This copy says it will disconnect for all devices, but WiFi cameras may not",
    "verdict": "yellow",
    "evidence": ["WiFi cameras do not necessarily disconnect due to this operation"],
    "signature": "copy_assert_disconnect_unverified_device_scope"
  },
  "same_case_count": 2,
  "action": "propose",
  "case_record": {
    "id": "C-20261109-01",
    "signature": "copy_assert_disconnect_unverified_device_scope",
    "verdict": "yellow",
    "human_said": "This copy says it will disconnect for all devices, but WiFi cameras may not",
    "cause": "Copy assertion scope exceeds verified device behavior",
    "signal": "human_negative_feedback",
    "source": "F-20261109-01",
    "status": "observing"
  },
  "proposal": {
    "id": "P-20261109-01",
    "clause": "Connection status copy assertion constraint",
    "change": "Before asserting connection/disconnection results, confirm behavior by device type and connection method",
    "evidence": ["F-20261109-01", "K2"],
    "counter_example": "WiFi cameras rely on LAN/cloud; BLE disconnection does not necessarily disconnect them",
    "falsify": "If the implementation already branches by connection method, or product confirms behavior is consistent, withdraw",
    "rollback": "Delete the newly added entry, restore the original standard"
  }
}

Meaning of some fields:

Field	Meaning
human_signal	Human's exact words, conclusion, evidence, same-type signature
same_case_count	Accumulated count of same-type signals (including this one), counted by main Agent, Referee only rechecks
action	none no signal / record only record / propose propose rule change
case_record	Case trace for later retrieval
proposal	Rule change proposal; only allowed when all five items are present

3.4 Human judgment has highest priority

This is one of the most important changes in this optimization.

Early versions had B1 blind re-judgment + B2 attribution:

• B1: hide the original judgment card, let another Referee re-judge;
• B2: compare "blind judgment result" with "original judgment" and attribute A/B/C.

The original intention was to measure "rule stability." But in real scenarios, it easily became:

The human has clearly said "this judgment is wrong," and AI still has to re-judge blindly, then tell the human "you should change your mind."

This is misplaced.

Human judgment is the highest priority:

• The human says "this copy is wrong," record "copy is wrong";
• The human says "this yellow card is too conservative," record "yellow card too conservative";
• The human says "should be red," record "should be red."

The Referee no longer reviews the human; it only does two things:

1. Record the human's signal clearly;
2. Determine whether the same-type signal has reached the count that justifies a rule change.

So the process becomes:

Human points out problem
   -> Referee records (human_signal)
   -> same type < 2: keep case only (record)
   -> same type >= 2: issue rule change proposal (propose)
   -> human approves: takes effect next round
   -> human rejects: keep case, don't change rule

This preserves "rules can evolve" without letting AI review humans in reverse.

3.5 Output contract and failure degradation

The Referee's output must be verifiable:

• human_signal field type is correct;
• same_case_count is a non-negative integer;
• action only takes none / record / propose;
• record / propose must have case_record;
• propose must have same_case_count >= 2 and include proposal, falsify, rollback;
• Field names are fixed; no aliases.

When out of contract:

• Record referee_contract: miss;
• Main Agent corrects according to schema;
• Do not change the Referee's original conclusion;
• At most one re-run for the same judgment.

When the independent context cannot start:

• Record n/a;
• Main Agent continues according to rules;
• Explicitly mark "not independently judged";
• Do not substitute with main Agent self-evaluation, do not fabricate Referee output.

3.6 Cost

The Referee's cost advantage comes from "no tools + single turn + short output":

Form	Trigger rate	Input	Output
Approve	Only when human states old behavior	~0.3k	≤80 tokens
Compare	Non-L2 tasks	~2.4k	≤150 tokens
Red card suggestion	When needed	+0.6k	≤500 tokens
Review	When trigger events occur	~2.8k	≤400 tokens

At most 4 calls per task, typically 0-2.

In comparison, if every task requires a human to fully read three cards, the cost is not just tokens, but also human attention and waiting time.

---

4. Full process and role definitions: how the three routes land

4.1 Three workflows correspond to three routes

All three share the idea of "phase + gate + judgment," but are organized differently.

Route	Use case	Organization	Main roles
Serial dev-workflow	Feature development, refactoring, UI, build config	Main Agent serial progression	Main Agent + Referee + Reviewer
Router route	Complex development requiring parallel collaboration	Router dispatches multiple Workers	Router + Analyst + Coder + Reviewer + Referee
bugfix-workflow	Faults requiring systematic diagnosis	Main Agent serial, traffic light judgment	Main Agent + Investigator + Referee + Reviewer

Common points of the three workflows:

• Phase 0 judges first, does not write code directly;
• After implementation there is Checkpoint #1;
• Phase 2 is independent review;
• Phase 3 is verification;
• Phase 4 is retrospective + documentation + delivery;
• Judgment is done independently by Referee; humans do not confirm each card.

4.2 Phase overview table

Phase	Goal	Serial route	Router route	Referee	Main artifacts	Human gate
Phase 0	Judge "should we do it, how to do it"	Main Agent investigates, breaks down, plans	Analyst delivers background/plan/payload	Compare/recheck	Judgment card, plan, AC	Red card stops; green/yellow continue
Phase 1	Implement within boundaries	Main Agent implements	Coder implements (can run ahead)	Not involved	Code, diff, self-check	Checkpoint #1 real-device verification
Phase 2	Independent review	Independent Reviewer	Reviewer A	Not involved	Review report	Failure #2
Phase 3	Verify AC	Main Agent / Reviewer	Reviewer A	Not involved	Verification report	Failure #3
Phase 4	Retrospective, docs, delivery	Main Agent + Referee review	Router + Referee review	Record/propose	Retrospective JSON, docs, delivery	Final acceptance

4.3 Serial route roles

Role	Responsibility	Write permission	Main outputs
Main Agent	Investigate, break down, plan, implement, verify, summarize	Only one writing business code	Solution, code, verification report, delivery
Referee	Independent judgment/recording	No writing code or standards	Judgment JSON, review JSON
Reviewer	Independent review of implementation	No writing business code	Review report
Human	Goals, trade-offs, red cards, standard approval, real-device verification	Final decision authority	Confirm/deny/authorize

4.4 Router route roles

The Router route splits responsibilities more finely, but still "one main brain + multiple independent roles."

Role	Responsibility	Write permission	Input	Output
Router	Orchestration, dispatch, snapshots, release registration, ledger writing, display	Does not write plan or code	User requirement, Worker receipts	Task ledger, cards, delivery
Analyst	Background, breakdown, solution, candidates, L1/L2	Only writes its own artifacts	Startup baseline, requirement	background.md / plan.md / payload.md
Coder	Only source code writer	Business code, resources, config	Confirmed contract	Code, coder.md
Reviewer	Independent review, verification, summary	Does not write business code	diff, AC, evidence	review.md / verification.md / summary.md
Referee (compare)	Phase 0 compare/recheck	None	payload	Two axes/suggestions
Referee (review)	Phase 4 record/propose	None	Original card, human signal, same-case count	review JSON

Instance constraints:

• The five Agent IDs analyst, coder, reviewer, referee_compare, referee_review must all be distinct;
• Referee is created fresh each time, not reusing the main session;
• Coder is the only source code writer;
• Reviewer does not participate in implementation;
• Router does not substitute for Referee/Reviewer in making conclusions.

4.5 Artifacts and ledgers

Route	Artifact root	Ledger	Description
Serial dev-workflow	Convention per task in project	.gate/v8/	Gate events, standards, cases, retrospectives
Router	.dsh-workflow-router/<task>/ etc.	.gate/v8/	Task ledger, snapshots, receipts
bugfix-workflow	Per fault record in project	.bugfix/	Traffic light events, derived rules, retrospectives

Ledgers are append-only, never retroactively changed; full reports live in artifacts, ledgers only store events and summaries.

5. Workflow process details

5.1 dev-workflow details

---

5.2 bugfix-workflow details

---

5.3 dev-workflow-router details

5.4 Some workflow detail supplements

1. In development-type workflows, a strong validation of the original requirement was added, because sometimes we describe in the prompt "originally it was xxx, now change to yyy"; if the original requirement is wrong, the new requirement built on it is likely wrong too, and the whole task may be flawed. But if the prompt does not describe the original requirement, this step is skipped and we go directly to new requirement breakdown.
2. In bugfix-type workflows, strong validation of the original requirement was not added, because this type is not development but fixing bugs based on existing facts; so in bugfix workflows we only prompt the user for the real original requirement.
3. How to ensure quality and iteration in breaking down new requirements? This step relies on an encapsulated new-requirement-breakdown skill, maintained to ensure the breakdown and iteration of new requirements.
4. In development workflows, some parts will be judged yellow and default to pass, because passing with risk can be corrected later; the cost of interrupting the workflow is too high. Engineers must control risk descriptions closely.
5. In bugfix workflows, yellow lights are blocked. Yellow means evidence is not fully sufficient; blocking yellow is because you cannot fix bugs based on partial hypotheses. After users evaluate the yellow risk, they can explicitly release it.
6. What if the user modifies the requirement after the light is judged? There are now A/B/C three axes to re-plan the guidance (see the three images in 5.3);

6. Multi-platform packaging: thin shell layer and core layer

6.1 Problem: three copies of rules will eventually drift

All three workflows need to run on DSH, Claude Code, and Codex, so the problem shifts from "designing the process" to "maintaining three platform wrappers simultaneously." The most direct approach:

• Copy SKILL.md for each platform;
• Copy gate.md / triage.md / agent-delegation.md for each platform;
• When changing rules, change all three.

Short term works, long term problems surface:

• Change one, forget the other two;
• The three platforms' judgment criteria, thresholds, and event fields gradually diverge;
• New platform requires copying again;
• When issues arise, can't tell whether "rules are wrong" or "shell is wrong."

6.2 Thin shell + core layer

This optimization splits the workflow into two layers:

Layer	What it holds	Who maintains	Platform-specific?
Core layer	Specifications, execution details, phase rules, judgment axes, templates, ledger structure	Workflow maintainer	No
Thin shell layer	Platform tool names, file paths, ledger paths, context directories, platform constraints	Each platform	Yes

The core layer is the single source of truth. The shell only does three things:

1. Tell AI which tools to use on the current platform;
2. Tell AI where files/ledger/context are;
3. Isolate platform differences to the smallest scope.

A qualified shell should be very thin:

Claude platform shell

Item	Claude
Worker start	Agent / Task
Ledger	.gate/v8/
Context directory	.claude/contexts/
Retrospective	Referee review

It should not contain:

• Judgment criteria text;
• Threshold values;
• Path lists;
• Event field tables;
• Card templates;
• Phase rules.

Anything like this in the shell becomes a "second set of rules," which will eventually diverge from the core.

6.3 Directory layout

For three platforms, a structure like this can be used:

docs/workflow/v8/                 # Core layer: specs, runbooks, Phase 0/4
  gate-0-1-spec-v8.md
  gate-runbook.md
  phase0.md
  phase4.md
  README.md

docs/bugfix/core/                 # bugfix independent core
  bugfix-workflow.md
  triage-runbook.md
  retro-runbook.md
  referee-runbook.md

.claude/skills/dev-workflow/      # Claude thin shell
  SKILL.md
  references/gate.md
  references/workflow-core.md
  references/agent-delegation.md

.codex/skills/dev-workflow/       # Codex thin shell
.dsh/skills/dev-workflow/         # DSH thin shell

The three routes each have a core, but share a single principle:

Rules are written once; platform differences are written one layer.

6.4 How to prevent the shell from growing thick

Relying on "remember not to write" is not enough; mechanisms are needed.

This optimization adds a check-drift.py drift-check script that does two things:

1. Check if the shell copied judgment criteria: if the shell includes threshold constants, path lists, or event field tables, report an out-of-bounds violation;
2. Check if the shell forwards to the core: the shell must reference core files, not write its own set.

If the check fails, merging is not allowed.

Additional conventions:

• The shell only allows "platform facts": tool names, paths, ledger locations, context directories;
• If a platform difference requires a rule, first change the core, then reference it in the shell;
• The same core is shared by the three platforms; shell differences are only allowed to be platform facts;
• When adding a new platform, only write the shell, do not copy the core.

6.5 Multi-platform packaging benefits

Benefit	Description
Upgrade once, take effect on all ends	Change core, no need to change three copies
Differences explainable	Platform differences concentrated in shell; when troubleshooting, look at shell first
Checkable	Drift script can find "copied criteria / missed forwarding"
Extensible	New platform only writes shell, doesn't change rules
Auditable	Core is the only rule source, version clear

The cost is:

• Core layer must be stable enough, cannot change every day;
• Shell must be restrained, cannot stuff everything in;
• Scripts and conventions are needed to maintain the boundary.

But compared to "three copies of rules written separately," this cost is worthwhile.

---

7. Context and cost

Multi-agent workflows most easily lose control not due to model capability, but context.

What this optimization does:

7.1 Referee only receives payload

Referee does not read files, code, or logs. The main Agent compresses facts into fixed fields, and Referee only looks at those fields.

Benefits:

• Cost predictable;
• Output recomputable;
• Not biased by irrelevant context;
• Does not slide from "judgment" to "exploration."

7.2 Read by phase, not pre-load

• Phase 0 reads only Phase 0 related;
• Phase 1 reads only implementation related;
• Phase 2 reads only review related;
• Phase 4 reads only retrospective related.

No requirement for AI to read all rules at once.

7.3 Artifacts only pass summaries

Handoff passes:

• Path;
• Summary;
• Key conclusions;
• Necessary diff/evidence.

Does not copy full chat, full logs, or full implementation process to the next Agent.

7.4 L2 fast path

Some tasks don't need full comparison:

• Pure documentation/copy;
• Single-file, single-point changes;
• Existing clear precedent.

When matched, Referee comparison is not called, directly judged green; but gate_payload + judgment are still written, and a card is still produced.

8. Landing checklist

If you want to land this in your own project, follow this order:

1. Set the three colors first: meaning of green/yellow/red, default actions, who handles;
2. Then set axes: cause, solution, evidence, scope, and mandatory items;
3. Write Referee contract: input fields, output JSON, failure degradation;
4. Build ledger: events, cases, proposals, standards;
5. Set self-evolution rules: same case count >= 2 to propose, human approval to take effect, rollback supported;
6. Split thin shell: core writes rules, shell only writes platform facts;
7. Add drift check: prevent shell from copying criteria, missing forwarding;
8. Run real tasks: first validate with 5-10 tasks, then expand.

Don't chase "full automation" from the start. First get the "judge-record-propose-approve" loop running, then gradually reduce human intervention.

---

9. Summary

This optimization's changes can be summarized in four sentences:

1. Judgment shifts from human to AI Referee: green/yellow continue, red stops; humans handle exceptions, not accompany every Gate.
2. Traffic light uses axis-based judgment instead of guesswork: cause, solution, evidence, scope + mandatory checks; yellow can be authorized, red cannot.
3. Retrospective changes from "AI re-judges" to "record human signals, propose when conditions are met": human judgment has highest priority, rule evolution is approved by humans.
4. Multi-platform uses thin shell + core layer: rules written once, platform differences one layer, drift check holds the boundary.

This system cannot guarantee AI won't make mistakes, but it makes mistakes surface earlier, makes judgment more recomputable, lets rules improve slowly, and frees engineers from repeating the same judgments at every Gate.

This article is organized from project practice and thinking, AI-assisted in drafting, with the author responsible for quality control. Comments and corrections are welcome.

Engineering design articles:

《AI编程工作流的设计：串行验证设计》

《AI编程工作流的设计：并行协作设计》

《AI编程工作流的设计：从人工判断到AI裁判》