Audit Program

Audit an existing Foldkit program against the same bar generate-program targets: this code should be indistinguishable in quality from hand-written code in packages/typing-game/client/src/ or packages/website/src/. Not "works." Not "structurally valid." Typing-game quality.

Recommended setup: the audit is dramatically higher fidelity when repos/foldkit/ is vendored as a git subtree in the audited project. Without it, you grade against the snapshots in generate-program/architecture.md and conventions.md. With it, you grade against the live exemplars (examples/, packages/typing-game/, packages/website/), which is what those snapshots are summarizing in the first place. If the subtree is missing, recommend adding it before the audit begins, pinned to the release git tag matching the installed foldkit package so the exemplars match the APIs the project compiles against: git subtree add --prefix=repos/foldkit https://github.com/foldkit/foldkit.git "foldkit@$(node -p "require('./node_modules/foldkit/package.json').version")" --squash. For a canary install, whose version (x.y.z-canary.<commit>) has no tag, pin to the full hash of the commit it names instead, which GitHub expands at https://github.com/foldkit/foldkit/commit/<commit>.

Operating principle: report first, change nothing without consent

The audit is read-only through Phase 6. The output is a structured report. Never edit a file before the user has seen the report and explicitly approved fixes, no matter how unambiguous a finding seems, no matter how trivial the change, no matter how confident you are. Phase 7 (Offer fixes) is opt-in and gated on user consent per item or per batch.

Concretely, this means:

• Phases 1 to 6 are pure investigation: read code, run greps, spawn review subagents, synthesize findings. No Edit, no Write, no Bash commands that modify files.
• After delivering the report at the end of Phase 6, stop and wait. Ask whether to apply fixes. Don't bundle a fix into the same response as the report.
• Even after the user invites fixes, structural and semantic changes still need confirmation per item. Mechanical fixes can batch only if the user explicitly accepts the batch.
• If the user says "fix it" or "make the changes" early (before seeing findings), surface the report first anyway. The report is the value the audit provides; jumping to edits skips the consultation that lets the user prioritize and reject items.

The audit's job is to surface findings the user can act on, not to act on them silently.

Resolve $ARGUMENTS:

• Empty → audit src/ end-to-end against every dimension
• A path (file or directory) → narrow to that path, every dimension
• A focus area (a11y, effects, naming, decomposition, forms, routing, subscriptions, submodels, types, testing) → audit src/ along that dimension only
• A path AND a focus → narrow on both axes

If the argument is ambiguous (could be a path OR a focus), ask which. Don't guess.

Phase 1: Scope the audit

Sketch the audit plan in one sentence and confirm before reading code:

"I'll audit src/page/room/ for naming, decomposition, and Effect-TS idiom consistency, comparing against typing-game's room page. Sound right?"

Skip this confirmation only when the scope is unambiguous (single file, single focus). For everything else, the sketch is cheap and the user can redirect before you spend cycles on the wrong target.

Phase 2: Read the canonical references

Read these in order. Every audit, no shortcuts. They're the spec the audit grades against.

1. Architecture guide: TEA invariants, Submodel and OutMessage pattern, Flags, Subscriptions, Mount / Command / ManagedResource / CustomElement selection
2. Conventions guide: naming, Effect-TS idioms, Schema patterns, view conventions
3. Verification checklist: the canonical mechanical-check + quality-bar reference
4. Blind spots: the failure modes that survive typecheck, lint, and tests

These four files are a snapshot. When the audited project vendors repos/foldkit/, the live source wins over anything here: read the .d.ts or the example rather than grading against a remembered signature.

Do not skim. The audit's signal-to-noise depends on the auditor having internalized the bar before reading the audited code.

Phase 3: Map the project

Before deep review, build a model of the audited code:

1. File tree. Every file in scope, with a one-line description (update.ts: handlers for ClickedSubmit, UpdatedEmail, ...).
2. Tier. Match against the generate-program tier ladder:
   • Tier 1: single page, no async, single file
   • Tier 2: timers, subscriptions, simple stateful
   • Tier 3: async, loading/error, forms
   • Tier 4: routing, multiple pages
   • Tier 5: nested domain, CRUD
   • Tier 6: Submodels, OutMessage, multi-step flows
   • Tier 7: real-time, WebSocket, ManagedResources
3. Foldkit modules used. Grep imports for AsyncData, Calendar, File, Http, Update, Port, Subscription, Command, Mount, ManagedResource, CustomElement, Dom from foldkit, plus foldkit/fieldValidation and any component imported from @foldkit/ui. HTTP usage shows up as HttpClient / HttpClientRequest imported from effect/http, not as a foldkit import, so grep for those separately; Http from foldkit is only the layer that provides the client. Tells you which checklist sections apply.
4. Tier-matching exemplar. Pick at least one to read alongside the audited code:
   • Tier 1-2 → ${CLAUDE_SKILL_DIR}/../../examples/counter/src/main.ts, ${CLAUDE_SKILL_DIR}/../../examples/stopwatch/src/main.ts
   • Tier 3 → ${CLAUDE_SKILL_DIR}/../../examples/weather/src/main.ts, ${CLAUDE_SKILL_DIR}/../../examples/form/src/main.ts
   • Tier 4 → ${CLAUDE_SKILL_DIR}/../../examples/routing/src/main.ts
   • Tier 5 → ${CLAUDE_SKILL_DIR}/../../examples/kanban/src/
   • Tier 6 → ${CLAUDE_SKILL_DIR}/../../examples/auth/src/, ${CLAUDE_SKILL_DIR}/../../examples/job-application/src/
   • Tier 7 → ${CLAUDE_SKILL_DIR}/../../packages/typing-game/client/src/page/room/
5. Foldkit UI integration. If anything is imported from @foldkit/ui, also read ${CLAUDE_SKILL_DIR}/../../examples/ui-showcase/src/main.ts and ${CLAUDE_SKILL_DIR}/../../examples/ui-showcase/src/ui/ for the wiring pattern.

The exemplar is the comparison target. When you find a pattern that smells off, ask: does the exemplar do this differently? If yes, flag it.

Phase 4: Run the linter, then the mechanical scans

The linter first

@foldkit/oxlint-plugin ships 24 AST rules covering much of what this audit grades: keyed mapped rows, no array-index keys, hard-coded route strings, empty-object tagged calls, Rel on external links, spread inside modifyFields, Got* wrapping of child output, PascalCase Command.define bindings, Mounts whose execute ignores its element, module-level mutable state, and NoOp Messages. They parse the code, so they catch what a grep misses.

Establish whether the rules are actually active, which is not the same as finding the package name. The config is the authority here, not the lint output. Locate the config before reading anything out of it. A lint script may name one with --config, and in a workspace the config usually sits above the app rather than beside it:

grep -n '"lint"' package.json
find . .. ../.. -maxdepth 1 -name '.oxlintrc.json' 2>/dev/null

Finding no config is a different outcome from finding one without Foldkit in it, and the two look identical if you only read stdout. A grep against a missing file and a grep against a config that doesn't mention Foldkit both print nothing. Branch on whether the find located a file at all:

• No config located: the outcome is Undetermined, never Not active. The project may well be linted from a parent workspace this audit didn't reach.
• Config located: grep it for foldkit. A hit under extends pointing at the plugin's recommended.json, which is what the scaffold writes, or a jsPlugins entry naming the plugin by path specifier, which is how a monorepo or vendored setup wires it and how the Foldkit repo itself does it, means the rules are Active. No hit, but the config has an extends entry pointing somewhere else, means follow that file and repeat: a shared internal config can wire the plugin one level up. No hit and nothing left to follow is Not active.

Lint output can confirm activation but can never rule it out. Diagnostics are labelled foldkit(rule-name), so seeing foldkit( proves the rules ran, and grepping for foldkit/ finds nothing even when every rule is running. Zero foldkit( matches proves nothing at all: that is what a passing project looks like. Never infer "not active" from a quiet lint run.

• Active: run the project's lint script. Every foldkit(...) diagnostic is a finding, reported like any other, and it outranks a grep hit on the same subject because the rule actually parsed the code. Do not re-derive those findings by hand.
• Not active: report it as the first QUALITY item, worded as tooling. Don't file it as a BLOCKER: that bucket is defined for code that is structurally wrong and its item format requires a file:line, which a missing devDependency doesn't have. Filing it there would also fail every hand-written app on tooling grounds alone. It is still usually the highest-leverage fix in the audit, so lead the QUALITY list with it: one devDependency and one extends line buy continuous enforcement of two dozen invariants, where this audit is a snapshot. Then fall back to the greps, and say in the report that they are a weaker substitute, since they miss wrapped calls and renamed helpers. A clean grep run on an unlinted project is weak evidence, not a pass.
• Undetermined: run the lint script anyway and treat any foldkit(...) diagnostic as the Active case, since one diagnostic settles the question. With no diagnostics, fall back to the greps as above, but say the wiring was undetermined rather than missing, and name the paths you searched. Do not recommend installing a plugin that may already be enforcing these rules.

A project scaffolded by create-foldkit-app has the plugin installed and wired by default, so an audited project lacking it usually predates the scaffold or dropped the config.

Then the scans

Run the canonical greps from the Mechanical scans block in ../generate-program/checklist.md. That checklist is the source of truth. It covers ground no rule touches (API drift, @foldkit/ui adoption, Effect idiom, a11y detail, test shape) plus the deliberate edges of rules that are narrow by design; each such grep names the rule it complements and where that rule stops. Don't duplicate the commands here, and don't delete a scan just because a rule shares its subject: check whether the rule actually covers the case. Note too that recommended.json disables every rule for **/*.test.ts and **/*.test.tsx, so the linter contributes nothing to the test-shape checks in Subagent E. Each hit is either a finding or a // NOTE: justification. Silent hits aren't allowed.

For every hit, decide:

• Is there a // NOTE: above it justifying the deviation?
• If yes, evaluate the justification. Is it real, or defensive rationalization? Common false-justifications: "would require duplicate state" (most @foldkit/ui components have small inline-constructable models, and the controlled render helpers have none at all), "the interaction is too custom" (the toView callback handles arbitrary HTML), "we don't want to wire toParentMessage" (that's the unavoidable cost of a11y-correct interactive widgets, paid once per use).
• If no NOTE, it's a finding.

Mechanical scans catch the cheap stuff. They're the floor of the audit, not the ceiling.

Phase 5: Structural review

Walk every category in ../generate-program/checklist.md against the code. Every category, every item, against the actual files.