surface-parity-checklist
Skill2 starsChanged 2 days agoMITView on GitHub
Use BEFORE adding, changing, or displaying any operator-visible task/runner field (caps, scope, status, agent, repo, …), adding an option to any verb family, or wiring a new operator action's result reporting — AND before adding/renaming an agent or changing its bin, argv templates, credential mode, egress domains, or launch env. NUMBERED checklists that must be walked item by item with a verdict per number — never summarized: 1–39 for every input surface, display surface, per-path semantics axis, result/display convention across CLI/TUI/WebUI/wasm, and the feature spec's own surface matrix, plus S1–S6 for preset↔podman-sandbox agent-launch parity.
In this repository22 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- codebase-tourSkill
- harness-cli-from-a-toolSkill
- harness-cliSkill
- independent-reviewSkill
- landing-to-mainSkill
- memory-maintenanceSkill
- running-parallel-workersSkill
- session-debuggingSkill
- supervising-workersSkill
- codebase-tourSkill
- dummy-harnessSkill
- harness-cli-from-a-toolSkill
- harness-cliSkill
- implementation-pitfallsSkill
- independent-reviewSkill
- landing-to-mainSkill
- memory-maintenanceSkill
- running-parallel-workersSkill
- session-debuggingSkill
- supervising-workersSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 4 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
Every operator-visible field lives on ~15 surfaces across three UIs, and every option's MEANING exists once per path it is reachable from.
- Distinctive: line 124
Ask it separately from 18, because the two have opposite constraints: a detail popup has a line for anything, and this table is …
- Very specific: line 169
If not and the difference matters (resume, set-style RPCs), add a presence bit — reserved bits in an existing byte first (scope_present …
- Distinctive: line 218
Do not hide a value because of what it IS — not in detail views, and
- Very specific: line 265
Do NOT "just always emit the widest row": that only works if the optional column is LAST.
- Very specific: line 296
Do not make a control depend on the first snapshot arriving: build it on toggle of its <details> as well, or an operator who opens the …
- Distinctive: line 440
When a defect ships through this checklist anyway: fix the defect AND add the number that would have caught it.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Surface-parity checklist
Every operator-visible field lives on ~15 surfaces across three UIs, and
every option's MEANING exists once per path it is reachable from. History
shows these get found one at a time, by the user, after landing. A second,
narrower axis lives at the bottom (S1–S6): an agent the operator launches
is described in a preset table AND re-described in the podman sandbox
wrapper, and no UI grep reaches that pair. Sibling:
implementation-pitfalls Pitfall 9 is the incident record; this file is the
checklist.
How to use — non-negotiable
This is a CHECKLIST, not reference prose. When this skill applies, walk every number from 1 to 39 in order and record a verdict for each:
done— implemented/verified, with the file touchedn/a— genuinely not applicable, WITH the reason statedomitted— deliberately skipped, WITH the reason stated (this is a design decision that belongs in the diff or spec, not a silent default)
A walk that skips numbers or collapses into "surfaces covered" is invalid — the summary sentence is exactly where discretionary omission hides. If an item is expensive, say so and mark it; do not silently drop it.
A continuation commit is a new walk. Where the trigger fails in practice
is "same surface, one commit later": the second change reads as finishing the
first, so nothing feels like it fired again. When that is the shape, re-read
the items the first walk marked done and ask each one of the NEW field.
Item 24 read done for Flag.Help, which has no per-path semantics, and was
never re-asked of Flag.Default, which does — twenty-five minutes and one
commit later, with no entry in the log.
Items S1–S6 (agent-launch parity) are a SEPARATE list with its own trigger,
kept out of 1–39 on purpose: they are n/a for almost every field change,
and a list that trains you to type n/a is how the walk decays. Walk them
when their trigger fires, with the same three verdicts.
Input surfaces (new flag / option / request field)
- The verb declaration —
cli/verb/table.go. OneVerbSpecper verb path carries the flags, aliases, positional arity, trailing-text rule and fallback ladder, and all three command lines parse from it: the CLI builds its FlagSet withVerbSpec.NewFlagSet,tui/cmdline.gocallsparseViaSpec, and the WebUI reaches it over the wasm bridge (harness.parseCommand). Adding an option is a row here, not three edits. An option that means something on only some surfaces setsFlag.Surfaces(orArg.Surfaces) WITH aSurfaceReason, which an invariant test requires. This item used to be six (CLI flags, CLI parse helpers, TUI cmdline verbs, WebUI command input, the wasm bridge'sopts.Getnames, and "every OTHER verb family"), because each surface parsed for itself. The census that ended that found--agent-argmissing from the TUI entirely,--max-bytesmissing from the TUI's git, the WebUI accepting every git flag on every sub-verb, andfile pull's-o/-nexisting only in the TUI.cli/verb'sTestNoHandWrittenVerbFlagSetsRemainfails if a surface goes back to building its ownflag.FlagSet. - Cross-flag validity lives in the verb's
Build, not in a surface. "--x11 with --detach", "--raw with --dir both", "--seq is required", "--allow xor --deny" — each was enforced in one surface and absent from the others before the migration. - Buttons, keys and pickers still need their own walk — they invoke actions without going through a grammar, so item 1 does not reach them. That is items 4, 5, 6 and 9 below.
- TUI keybindings —
tui/keys.go(mainKeyMap + mainKeyBindings row — keys_test enforces the pair), dispatcher intui/app.go. - TUI pickers/popups —
tui/authoritypicker.go,tui/popup.go— remember batched KeyRunes (a fastjjjis ONE msg). - WebUI controls —
webui/index.html+webui/static/main.js(chips viabuildCapChips, checklists viabuildTaskChecklist, dialogs via<dialog class="picker-modal …">). - WebUI dispatch coverage — every path typable in the WebUI declares a
WebUIDispatch{Fn: …}on its row incli/verb/table.go(the page's dispatch map is generated from those), andmain.js's case for the family must route the new sub-path to it.cli/verb'sTestEveryWebUIVerbDeclaresDispatchfails on a missing declaration. (Until 2026-09-28 this item named aWEBUI_DISPATCHmap and a startup assertion inmain.js; both had moved to the declaration, and the stale path cost a grep.) - Actions that carry values across the wasm bridge —
Boundcrosses generically (flags, args, trail, custom), but an action whoseBuildINTERPRETS its positionals needs its own bridge function;harness.parseGitis the one such case, because git counts revisions its own way. - Session-default state — TUI
App.sessionCaps/sessionScope; WebUIspawnCaps/spawnScope— every spawn call site must read them. - Result rendering is deliberately NOT shared — the CLI writes stdout and an
exit code, the TUI returns a
tea.Cmd, the WebUI touches the DOM. Item 1 ends at the parse; items 29–31 are where the output conventions live.
Display surfaces (field must be VISIBLE, not just accepted)
lshuman rows —cli/list.go(row renderer).ls --json—cli/list.go(JSON struct — always carries everything, no elision).whoami—cli/whoami.go(both the operator and task branches).session ls— JSON rows incli/session listing.capscatalog —cli/verb/caps.goCapDescription+WriteCaps+ SCOPE section. (cli/grammar.goforwards to both;cli/caps.go, which this item named until 2026-09-22, does not exist.)CapDescriptionENUMERATES the verbs each bit authorizes, so a new verb gated on an existing capability fires this item even when no field, row or dialog changes anywhere — which is the shape that makes it easy to miss: a feature-shaped reading of "does this change a display surface?" answers no, and only the mechanical 1–39 walk asks.- TUI task table —
tui/tasks.goSetRowscolumns. - TUI task detail popup (
d) —tui/detail.goformatTaskDetail— this one had no scope line for a full release. - TUI runner detail —
tui/detail.goformatRunnerDetail.
18a. TUI runner table — tui/runners.go runnerColsFor + rebuild. The
runner ROW, which had no cell on this list while the task row (16), the task
detail (17) and the runner detail (18) all did. That asymmetry is not
academic: a runner field could be added to its detail popup and to all three
ls forms with every number reading done, and the table an operator looks
at first would still not carry it. Found 2026-09-10, on the operator asking
「TUIのあれもrunnerにIDを表示してもええんちゃうか?」 — the runner's own IDENTITY
was reachable only by opening the popup, on a fleet where two slots share a
hostname by design and the rows therefore differed only by Agent.
Ask it separately from 18, because the two have opposite constraints: a
detail popup has a line for anything, and this table is over-subscribed
(79 natural cells before the column was added), so the answer here is often a
width-conditional column — which drags item 34 in with it. Numbered 18a
rather than appended so it sits beside the runner surface it belongs to.
19. TUI picker rows — tui/authoritypicker.go buildRows (id, status,
agent, repo, prompt head).
20. WebUI task row meta — renderTaskList metaText in main.js.
21. WebUI task detail sheet — the addItem action list per task.
22. WebUI dialogs' prefill — needs RAW values in the wasm snapshot
(capsBits/scopeBase/scopeIds pattern) — labels like all,-spawn
cannot be re-parsed in JS.
23. wasm snapshot JSON — the ls conversion map in
cmd/harness-webui-wasm/main.go — label string AND raw value.
Semantics axes — ask these PER OPTION, not per surface
Items 1–23 find missing knobs and missing pixels; these find wrong
MEANINGS. They apply to EVERY verb family, not just spawns: any option
reachable from more than one verb, mode, or path needs its meaning written
down per path (prune with ids vs the bare age sweep, file push -f vs
pull -f, a forward flag on register vs kill — same discipline).
The declaration (item 1) removes the "is this option even ACCEPTED here"
half of the problem; it does not touch this half. Two surfaces can parse
one flag identically and still do different things with it, which is the
ls / list case: same idea, one reading the filtered DOM and one the
whole snapshot.
- Same option, other path — for every option on a multi-path verb: what
happens on EACH path? "Applied", "kept", "ignored-with-error" — written
down, not implied. The incident: spawn options on the resume path — a
zero value that means "default" on create means "overwrite with
default" on resume unless a presence bit says otherwise.
A resolution ladder is a path too.
Flag.Resolveconsults env and the workspace config BEFORE falling back to the declaredDefault, so the "path" can be the environment the process runs in rather than a sub-verb.prune-local --repoprinted(default ".")in its help whileHARNESS_REPO_PATH— set in every runner-spawned task, so"."is the case that never happens there — decided which repo that verb removes worktrees from. "Multi-path verb" read as sub-verbs and nothing in this item's wording reached the ladder (2026-09-18). A flag with a ladder and a non-zeroDefaultmust name its tiers where it states the default;cli/verb'sTestLadderTiersAreNamedWhenADefaultIsPrintedholds that. - Presence — can the wire tell "not given" from "given the zero value"?
If not and the difference matters (resume, set-style RPCs), add a
presence bit — reserved bits in an existing byte first (
scope_presentcost zero layout change). - Session defaults — defaults (TUI
sessionCaps/sessionScope, WebUI Compose state) feed FRESH spawns only. A resume must never inherit whatever the default picker happens to hold — gate it behind an explicit control. - Shared funnel — new request fields land in the shared builder
(
buildOpenInteractiveRequestviacli.SessionOpts; its submit sibling went withsubmitin A3), never in one caller — native, wasm, and x11 all funnel through them, so a per-path field silently misses the other two. Reaching the funnel is not reaching the wire.cli.SessionOptsis a struct its callers fill by hand, so "the field is in SessionOpts and both builders copy it" can be true while callers never set it — which is what happened to--scope-for: seven hand-writtencli.SessionOpts{…}literals intui/, six of them older than the field. This item passed. Item 28a is the half it does not cover. - Persistence — a new task field needs its
WALEventfields AND a decided replay meaning for records written before it existed (scope chose zero = subtree = old behaviour).
28a. Follow the value to the request build, and count the builds. Items
1–10 check that a surface ACCEPTS the option; they stop at the parser.
For each surface that accepts it, grep every construction of the request
struct that surface reaches and confirm the field is set in each. One
checklist cell routinely hides several: "TUI cmdline" reaches SIX request
builds (session new, session new -d, --x11, r/R resume — pinned
AND its Any-selector retry — and interactive), plus submit (since
retired) on another file. --scope-for parsed correctly, rode SessionNewAction and
spawnAuthority, and died at those six; every 1–10 cell read done and
the operator got a task with the bare scope. --caps arrived, which made
the loss look like a scope bug rather than a dropped field.
The fix that ends the class is a constructor, not a comment — the field's
doc comment already said "a field set in one caller and missed in the
others is the established failure mode on these routes". Give the struct
one builder (Authority.opts) and pin it with a test that fails when a
second literal appears (tui/session_opts_test.go), so the next authority
field cannot be added in one place and missed in six.
Cheap check when you cannot restructure: grep -c 'TheStruct{' per package
and diff it against the count of sites that set your new field.
Conventions (each learned from a user complaint)
- Result messages name the target and the change —
caps set <id8>: caps=… scope=…, never a bare count; counts only as a fan-out suffix (+N descendant(s) clamped) when a cascade actually reached something. - Results go to the result surface, not the status indicator — WebUI:
appendCmdOutput(like the ✕ Cancel handler);setStatusis the CONNECTION badge. TUI:a.cmdresult. - Do not hide a value because of what it IS — not in detail views, and
not in rows either. A hidden
scope=subtreereads as "this task has no scope"; an elidedcowrite=0 viewer=0reads as "this row does not report watchers". The row-width exception this item used to grant is withdrawn (2026-08-20, on operator complaint):lsrows andwhoaminow printscope=subtreelike the WebUI row, the TUI detail popup and both JSON forms already did — only those two still carried it — andIsDefaultScope, whose doc comment existed to justify the eliding, is deleted. Gate rendering on whether the subject EXISTS, never on its value: a live session printscowrite=0 viewer=0; a finished task prints nothing, because it has no session to describe. Zero is a measurement, absence is not, and collapsing them throws the measurement away. The trap: neighbouring fields (act=,err=,exit=,by=) DO elide — on ABSENCE, a different axis. Copying their form without checking their axis is how this recurs, and it did: the observer counts shipped eliding-at-zero in the same change that added them to fix exactly that ambiguity elsewhere. - One serializer per grammar, pinned by tests. Not one PER RUNTIME — that
was the old wording and it licensed exactly what went wrong:
scopeSpecFor(Go) andscopeSpecJS(JS) were both hand-written next tocli.ScopeLabel, and both knew three of the six scope bases and neither half of the visibility pair. A picker or dialog apply silently turneddescendantsintosubtreeand droppedglobal/…. Neither copy had the round-trip test this item claimed for them; the sentence was the evidence. Both are gone: the picker callscli.ScopeLabel, the browser callscli.ScopeSpecover the wasm bridge (harness.scopeSpec). When a grammar must be produced in the browser, EXPORT the Go serializer rather than mirroring it — a mirror has no way to fail loudly when the grammar grows. A "round-trips" / "can be pasted back" claim in a comment is the cue to write the test, never evidence that one exists. Fixed frames: popup/dialog width derives from the terminal/viewport, never content (TUI pickerfit(),.picker-modal.regrant-modal). - A typed option either takes effect or errors — never silently ignored,
never silently overwriting. Both failure shapes shipped at once: a lone
--scopeon resume was dropped, and--capswithout--scopereset the task's scope. When the wire cannot express "keep", the fix is a presence bit, not documentation. - A table whose column SET varies (by width, mode, capability) must
rebuild its rows through the same decision, and swap the two together.
bubbles'
SetRowsandSetColumnseach re-render immediately andrenderRowindexesrow[i]per COLUMN, so a moment holding N columns against N-1-cell rows is an index-out-of-range panic — hit within minutes of making the tasks table's Obs column width-conditional. The fix shape isapplyColumns: empty the rows, set the columns, rebuild, restore the cursor (a resize must not move the selection). Do NOT "just always emit the widest row": that only works if the optional column is LAST.Obssits beforeRepo, so a stale extra cell would render every following value under the wrong header — silently, which is worse than the panic. Corollary:tui/tasks.goSetRowsmay no longer be the only place cells are built. Grep for every caller of the rebuild path before adding a cell.
34a. A form field must be the same KIND of control as its neighbours.
The WebUI spawn form expresses caps as chips, a scope base as radios and
scope ids as a task checklist. --scope-for shipped there as a
<textarea> you typed CAPS=SCOPE into — an override IS a capability
mask plus a scope, so both halves already had controls and neither was
used. Caught on operator complaint (2026-08-20): "UI として文字列打たせる
のどうなの".
The command input is where typing belongs; a form is not. If a new option
decomposes into things the surface already has controls for, build it from
those — buildCapChips, the base radio row, buildTaskChecklist — and
serialize to the wire grammar at send time, so the PARSER still lives in
Go and the browser cannot drift from what the CLI accepts.
Corollary, and the reason this is worth a control rather than a box: a
constraint the server enforces should be unbuildable in the UI, not
merely rejected. Overlapping override masks are refused server-side; the
row UI disables a chip another row already claims, so the operator cannot
construct the rejected state at all.
Two traps met while doing it, both costing a rebuild-and-reload cycle:
the dummy server serves the EMBEDDED assets, so make webui-build alone
changes nothing it hands out (make build + restart it, or run it with
--webui-dir); and re-navigating to the SAME url differing only in its
#fragment does not reload the page, so every check after an edit can
silently read the old DOM — add a throwaway query param.
Do not make a control depend on the first snapshot arriving: build it on
toggle of its <details> as well, or an operator who opens the section
on an empty server finds it blank.
And carry the control to its siblings in the same walk. The
exclude-self checkbox was added to the override rows and not to the
task's own base row directly above them, so the WebUI could express
descendants for one capability but not for the task — three of the six
bases unreachable, in the dialog the fix had just been applied to. The
same edit left a CSS hole: the mobile rule that keeps a control inline
with its label enumerated input[type="radio"] in the base row and
input[type="checkbox"] in the checklist, so a CHECKBOX in the BASE ROW
fell between the selectors and rendered as a block above its text at
390px. Select by container, not by control type.
- Live screen-rendering surfaces.
tui/pane_streamer.go(the TUI grid pane) and the WebUI session preview render a session's SCREEN rather than a task's fields, so nothing in 11–23 reaches them — those items walk task listings, detail views and their JSON. When a change is about what a SCREEN reports or shows, ask separately whether those two render it. Found by walking, not by an incident:session snapshotgainedcursorandalt_screenas data while neither live pane draws a cursor at all — the TUI pane readsemu.Cursor()for scroll anchoring and discards the column and the visible bit. Recorded asomitted(reporting state and drawing a caret are different deliverables) rather than shipped as an asymmetry nobody had looked at, which is the outcome this item exists to force. - The feature's OWN surface matrix, checked against what shipped. Items
1–23 walk the surfaces a CHANGE must reach. Nothing walks the surfaces the
feature's spec already promised, so a row of its own table can ship
unimplemented and stay that way — the spec reads as description, the code
reads as complete, and only an operator asking "is that all there is?"
closes the gap.
Found 2026-08-29, four days late: the task-exec spec's Surfaces table said
"TUI display | running execs listed like forwards" and "WebUI | a
listing beside the forwards one". What shipped was the cmdline text
dump into a FIVE-line viewport that scrolls to the bottom on every write,
so a listing of more than four execs hid its own header. Both rows had been
written, agreed and then not built, and every 1–37 item was
n/afor the change that omitted them because none of them asks about the SPEC. The check is mechanical and belongs at the END of a feature's walk, not the start: open the spec's Surfaces / operator-matrix table and confirm each row against the code, one row at a time. A row you decide not to build is anomittedin the spec, struck through with its reason, so the table stops claiming it. The failure mode this prevents is not forgetting — it is a table that keeps asserting something nobody has looked at since it was written.
Documentation surfaces
README.md— the feature's section (e.g. "Capabilities and scope"), the per-binary summaries near the top, AND the TUI cmdline verb list. Incident: the README still recommended the REMOVEDcaps --on-resumecommand and described the caps-only era a full feature later.- Agent-facing skill texts —
runner/agentskills/*/SKILL.mdis the go:embed source of truth; mirror to.claude/skills/and.agents/skills/in the same commit. Repo-dev skills (implementation-pitfalls,dummy-harness, this file) live in.claude/only. Now test-enforced —runner/agentskills'TestMirrorsMatchEmbeddedSkillsfails on a byte difference andTestAgentsMirrorHasNoExtraSkillsfails on a.agents/skill this package does not embed, so this item is a reminder rather than the only guard. It became one because the manual form drifted three times at once:.agents/shipped an olderharness-cli,landing-to-mainandsupervising-workersthan the embed FS, which meant agents in OTHER repositories were reading instructions this repo had already replaced. Editing only the copy you happen to be reading is the way in — the embedded file is the one to edit, then copy it over both mirrors. - The feature's spec under
docs/superpowers/specs/— semantic changes land as an Amendment section there, so the spec never contradicts the shipped behaviour a later reader verifies against.
Agent-launch parity — SEPARATE trigger, walk S1–S6
Items 1–39 are one field across ~15 UI surfaces. This section is a
different axis: an agent is launched by the operator through a preset, and
the podman sandbox (scripts/sandbox/) re-runs that same agent through a
wrapper that must be kept in lockstep by hand. Nothing in cli/, tui/
or webui/ mentions it, so a 1–39 walk cannot reach it.
Trigger (walk S1–S6 instead of, or in addition to, 1–39): adding,
renaming or removing an agent; changing an agent's bin path, argv
templates (the oneshot pair is what session new --oneshot runs), config
directory, credential mode, or endpoint domains; changing what env the runner hands an agent; changing the
HARNESS_SERVER_CID format or the server's addressing.
S1. Preset derivation — scripts/agent_presets.py: KNOWN_AGENT_PRESETS
plus _SANDBOX_AGENT_ARGS, whose keys are the bases that get a
sandbox-<base> twin and whose values are each twin's act-without-asking
flag. A new agent added to the map alone gets NO sandbox twin. The twin
must stay DERIVED (only bin and agentArgs change) — the first
hand-copied version drifted and one-shot progress arrived as a single
final blob instead of streamed events. A twin's flag is checked against
the real CLI's --help on every subcommand its templates use, and goes
in agentArgs, never in runner --agent-args, which reaches the default
profile only.
S2. Wrapper dispatch — scripts/sandbox/agent-in-podman.sh selects the
agent from basename $0, so each agent needs its
<base>-in-podman.sh symlink next to it. The default arm is
AGENT=claude: a missing symlink does not fail, it runs Claude Code
while the task row still reads agent=sandbox-<name>. Same silent
wrong-binary class as a fresh interactive launch carrying no argv
template — the BIN is the only selector every launch path carries.
S3. Agent table — the case "$AGENT" in block in that wrapper is the ONE
place per-agent differences live: host bin, container bin, image
fallback, config mounts, token file + token env, always-env,
firewall-only env, egress domains, HOME (mount auth) and ephemeral
HOME (token auth). An agent with no revocable-token mode is
mount-auth ONLY —
state that, because it puts that provider's credentials in the
container with no narrower option.
S4. Firewall-only fields — A_DOMAINS and A_FW_ENV take effect ONLY
under --firewall / --firewall-proxy, and SANDBOX_PROXY_ALLOW
only under the proxy mode. A run in the default (open-egress) mode
proves nothing about them; a missing domain surfaces as a fail-closed
abort on someone else's task.
S5. Env and addressing contract — the wrapper forwards env by PREFIX
(HARNESS_*), so a new HARNESS_… var rides along automatically and
a differently-named one silently does not. Separately it parses
HARNESS_SERVER_CID into ip/proto/port to build the harness-server
carve-out; if the format changes and the parse fails, the carve-out is
skipped entirely (deliberately fail-closed) and the bridged
harness-cli stops working inside the container.
S6. Sandbox docs + the verifier — scripts/sandbox/README.md (agent table
AND the security-model section), .claude/commands/runner-up.md
(preset table), and scripts/sandbox/probe.sh: probe measures the
claims from inside the container, so a claim added to the README with
no probe line reads as verified while being unmeasured. Also state the
upgrade step for any bin/path rename — build_and_restart_all.py
replays a running slot's recorded argv, so live slots do NOT migrate;
they must be stopped and brought back up.
When to invoke
- Adding a field to
TaskInfo/RunnerInfo/ any snapshot row - Adding or renaming a capability, scope form, or status value
- Adding an option to ANY verb family (spawn or otherwise)
- Adding an operator action (new keybinding / button / dialog / verb)
- Reviewing a diff that claims "CLI, TUI and WebUI covered"
- (39) FINISHING a feature — walk its spec's own Surfaces table against the code
- (S1–S6) Adding or renaming an agent, or changing its bin / argv templates / config dir / credential mode / egress domains
- (S1–S6) Changing the env or the server addressing an agent is launched with — the sandbox wrapper re-derives both
When a defect ships through this checklist anyway: fix the defect AND add the number that would have caught it. The list grows by incident, and the 1–N walk is renumbered — a stale N in reports is harmless; a skipped surface is not.
Then record it in firing-log.md, beside this file. One entry per walk,
listing only the items that came back done/omitted and — filled in later,
when a defect surfaces — missed. Everything unlisted was n/a; writing
that out would bury the signal. The log answers the two things this list
cannot answer about itself: which items keep getting missed (their wording is
wrong, not the walker), and which never fire at all (dead weight, and the
n/a reflex is how the walk decays). It also records walks that were
skipped, which is a fact about when the trigger fails to fire in practice
rather than on paper — that has already happened three times, the last one a
continuation commit on a surface the previous commit had just walked.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

