# Agent workflow rules

Drop-in rules for coding and task agents (Claude Code, Codex, others). Derived from 15 sessions that needed rework and 21 controlled replays across 3 models. Telegraphic on purpose: agents load this every session. The long-form reasoning lives in `agent-workflow-playbook.html`.

Precedence: the user's explicit instruction in this turn > these rules > skill defaults.

## 0. Session start (preflight)

Before any task expected to take more than ~15 minutes, check what the task will need and report gaps in one line before starting:

- Auth: agent CLI logged in, `gh auth status` (scopes the task needs), cloud CLI tokens, secret store reachable (local cached copy, no interactive popups mid-task).
- Quotas: secondary model quota (Codex/agy) if delegation is planned.
- Devices and browser: browser automation connected, target hardware reachable (TV, printer, phone, scanner) if the task ships to one.
- Fonts and locale: if output renders non-ASCII text (Vietnamese etc.), confirm the font covers it.

A blocker found at minute 2 costs one question. Found at minute 60 it costs the session.

## 1. Understand before building

1.1 Search before inventing. Unfamiliar name, product, place or person: search the workspace (`~/Projects`, notes, memory, prior sessions) first, then the web. Never fabricate a physical object, address, district, amenity, price or spec to fill a gap. Unknown stays marked unknown.

1.2 Ask once, up front, structured. For work over ~1 hour or with a human audience, ask ONE structured question (tappable options, recommended first) covering only what changes the output:
- Audience and language of the deliverable.
- What "good" means (selection criteria, ranking order, must-haves).
- Target surface (which device, which channel, which paper).
Then work without further check-ins unless a decision is irreversible or costs money.

1.3 Ambiguous short replies get confirmed. A short reply that can read two ways (especially across languages) is restated in one line before acting on it. Do not pick an interpretation silently.

1.4 Restate scope in one line before starting: what you will build, what you will not.

## 2. Simple first

2.1 First deliverable is the smallest thing that works end to end on the real target.

2.2 No ideation rounds, brainstorm pipelines, multi-agent reviews, or "10x" expansions unless the user names them. "Make something simple first" means exactly that: one device, one screen, one path.

2.3 Change only what was asked. A fix to axis X does not touch axis Y. Extras go in a one-line suggestion at the end.

2.4 Prototypes for subjective work (voice, look, tone): produce 2 to 3 candidates and get a pick before producing 20.

## 3. Do the work yourself

3.1 Do not hand steps back to the user that you have tools for (browser, CLI, device APIs). "How do I test this?" is your question to answer, not theirs.

3.2 If a step truly needs the human (physical action, login with 2FA, payment), say exactly what, why, and what you will do after. One message, not a drip.

## 4. Done means proven on the target

4.1 Never report done from tests, DOM numbers or "should work". Done = evidence from the place the output lives:

| Output | Required proof |
|---|---|
| Mobile UI / web page | Screenshot at real phone width (390px) and desktop; no horizontal scroll |
| TV / kiosk / signage | Running on the device or its real browser engine, photo or device screenshot |
| Printer | Physical print photo, or printer's own preview of the exact job |
| Dashboard / widget | Run against real data, screenshot with values visible |
| Non-ASCII text in an image/font | Render a sample with diacritics (e.g. "Cài đặt DỌN NHÀ") and look at it |
| Copy / document | Style lint clean + reread against the brief's rules |
| Research / comparison | Every fact traceable to a source or input; unknowns marked |
| Visual fix | Before and after screenshots of the exact element |

4.2 Look at screenshots. Measuring the DOM is not looking.

4.3 If the target is unreachable, say so plainly: "Built, not verified on X because Y." Never round that up to done.

## 5. Preferences become checks

5.1 Any user correction becomes a rule in a feedback log next to the skill it belongs to: `YYYY-MM-DD · who · what was wrong -> rule`. Read the log before the next run of that kind of work.

5.2 A rule the user has stated twice becomes an automated check (lint, hook, script), not a reminder. Examples: banned punctuation and words via a style linter run on every deliverable; diacritic render check for any font choice; domain rules (e.g. hiring copy: no salary, language, no client name) as a checklist the skill loads.

5.3 Checks run before reporting, every time, not when remembered.

## 6. Model routing

| Job | Route | Reason |
|---|---|---|
| Facts from messy inputs (transcripts, screenshots, chats), research, anything the user reads | Large model | Steady across runs; small model invented facts here |
| Second opinion on research or a review | Different provider | Caught issues every same-provider run missed |
| Small, fully specified, checkable jobs | Small model, then verify | ~16x cheaper, but about 1 run in 3 is noticeably worse |
| Browser-driven testing | Agent with a real browser | Sandboxed CLIs may not launch one |

A single good run from a small model is not evidence the next will be good.

## 7. Reporting

Final report, exact shape:

```
<one line: outcome + root cause if it was a fix>
- path: what changed
Proof: <command or artifact, then actual output / screenshot path>
```

Unresolved questions at the end. No recap tables, no "Summary" headers. The Proof line must be target evidence per section 4.

## 8. Changing these rules

Before trusting a change to these rules, a skill, or a system prompt, replay 2 to 3 past tasks that failed and compare:

- Reconstruct the starting state (repo bundle, inputs, the user's original messages). If the pre-failure state cannot be rebuilt, pick another task.
- Run in an isolated sandbox: no push, no deploy, no real email, tokens disabled, no access to the original session's outputs (check for contamination).
- Each model 3 times; one run per model hides variance.
- Blind judge with a rubric built from the user's real corrections; hand-check the harshest calls. Judge by reading, not keyword grep.
- Prefer a judge from a different provider, or two judges, to reduce self-preference.
- Budget reference: ~$30 per task for 3 models with judging, under 15 minutes.
