guard-agent-work

name	guard-agent-work
description	Auto-guardrail for agent-authored changes. Use at the start of any coding session to prevent the most common agent mistakes in this repo.

Guard Agent Work

Use this skill at the start of every coding session before writing or editing code. It prevents the mistakes that agents make most often in this repo.

Why this exists

~38 of the last 400 commits were codex/* fix branches—agents fixing what previous agents got wrong. The same patterns repeat:

• Touching WebGPU parity code without testing both backends
• Adding path-string assertions that break on the next refactor
• Letting CSS literals slip in without tokens
• Forgetting to update MCP registrations when adding skills/docs
• Changing engine internals without touching the adapter boundary

This skill is a mandatory pre-flight checklist that runs automatically before you edit.

Auto-detect: what are you about to change?

Run this to classify your session:

bun run agent:guard --detect

It reads git status, git diff --name-only, or your stated intent and tells you which guardrails apply:

Detected surfaces:
- milkdrop/parity        → apply parity-guard
- core/renderer          → apply fallback-guard
- frontend/ui            → apply ui-guard
- tests/*                → apply test-guard
- .agent/skills/*        → apply mcp-guard
- docs/*                 → apply docs-guard

Universal hard stops (always apply)

1. Never add @ts-nocheck

If you think you need it, you are wrong. Fix the type error or ask for help.

2. Never import across the engine boundary

src/js/frontend/* must not import from src/js/milkdrop/runtime.ts, vm.ts, or compiler/*. Only milkdrop-engine-adapter.ts is allowed.

3. Never leave console.log in production code

Use the debug snapshot system (stimState.getDebugSnapshot) or the agent API instead.

4. Never change a skill without updating MCP

If you touch .agent/skills/* or .agent/workflows/*, you must update:

• scripts/mcp-shared.ts (import + markdownSources + agentCapabilities)
• docs/agents/custom-capabilities.md
• docs/agents/visualizer-workflows.md

Surface-specific guards

Parity guard (milkdrop/feedback-*, milkdrop/renderer-adapter*, compiler/gpu-descriptor-plan.ts)

Before saving any file in this surface:

• Run bun run test:compat — does it pass?
• Run bun run test tests/milkdrop-renderer-adapter.test.ts — does it pass?
• Did you add a comment explaining any new WebGPU vs. WebGL semantic difference?
• Did you verify against at least one reference preset in the browser?
• If you changed blend alpha order, did you add a regression test?

One-liner: bun run agent:guard --surface parity

Fallback guard (core/renderer-*, core/audio-handler.ts, milkdrop/runtime/backend-fallback.ts)

Before saving any file in this surface:

• Can you draw the fallback state machine on a napkin? If not, refactor first.
• Did you trace renderScale from probe → plan → override → renderer?
• Did you test with ?renderer=webgl forced?
• Did you test audio worklet init on the fallback path?
• Does every new timeout have a matching cleanup?

One-liner: bun run agent:guard --surface fallback

UI guard (frontend/*, assets/css/app-shell.css)

Before saving any file in this surface:

• Did you check all four breakpoints (375/768/1024/1920)?
• Did you run bun run check:quick for CSS token violations?
• Did you verify the change in ?agent=true mode, not just default?
• If you touched adapter interactions, did you check for stale closure / racing unmount?
• Did you avoid hardcoded colors/spacing without tokens?

One-liner: bun run agent:guard --surface ui

Test guard (tests/*, scripts/* that generate fixtures)

Before saving any file in this surface:

• Are assertions behavior-based, not string/path-based?
• If you changed the harness, did you update the contract doc?
• Are fixtures generated by a script, not hand-edited?
• Did you add a regression test for any bug you fixed?
• Does bun run test tests/your-file.test.ts pass in isolation?

One-liner: bun run agent:guard --surface test

MCP guard (.agent/skills/*, .agent/workflows/*)

Before saving any file in this surface:

• Did you import the markdown in scripts/mcp-shared.ts?
• Did you add it to markdownSources?
• Did you add it to agentCapabilities?
• Did you update docs/agents/custom-capabilities.md?
• Did you update docs/agents/visualizer-workflows.md?
• Did you run bun run check:quick to verify the build still compiles?

One-liner: bun run agent:guard --surface mcp

Docs guard (docs/*, AGENTS.md)

Before saving any file in this surface:

• Did you check for broken internal links? (bun run check:seo catches some)
• Did you update docs/DOCS_MAINTENANCE.md if the maintenance contract changed?
• Did you align with docs/README.md if routing/discoverability changed?
• Are code snippets copy-pasteable and use bun run ... not raw bun test?

One-liner: bun run agent:guard --surface docs

The "what could go wrong?" prompt

Before any significant change, ask yourself (or the guard tool):

Given the files I'm about to change, what is the most likely way
this breaks in production? What test or check would catch it?

If you can't answer both parts, do not proceed until you can.

Emergency override

If you genuinely need to bypass a guard (e.g., emergency hotfix):

1. Write the override reason in the commit message
2. File a follow-up issue to remove the override
3. Update the guard if the override reveals a false positive

Integration with session start

Add to your .zshrc or agent bootstrap:

alias codex='bun run agent:guard --detect && bun run session:codex'

Or add to AGENTS.md quick-start:

Before editing, run bun run agent:guard --detect to surface the relevant guardrails.

Related skills

• review-webgpu-parity — deep parity review
• review-renderer-fallback — deep fallback review
• review-test-harness — deep test review
• review-workspace-ui-state — deep UI review
• audit-recurring-fixes — refresh guards from commit history