whiteboard AGENTS.md

Project Instructions

Use this repo's standard development loop for every feature, bug fix, or refactor:

1. Start with the smallest failing test at the nearest layer.
2. Make the smallest patch that turns it green.
3. Manually verify the real behavior in a running app or browser.
4. Lock the verified user flow into canvas-viewer-browser/web-browser or a broader E2E test when browser-mode is not enough.

Test Layer Selection

Start with the smallest failing test at the nearest layer, and do not jump to broad E2E when a smaller failing test can isolate the bug. Reach for a property or model-based test (fast-check) over an example-only one when the change touches a parser/serializer, a state machine with time/TTL/revocation semantics, a concurrent store, a CRDT or other mergeable structure, or a rounding/normalization transform with an algebraic invariant. Prefer example and browser tests for UI wiring, one-off integrations, and anything with no clean invariant to state.

Everything that follows from that choice is the test-layer-selection skill: which project serves which layer and the command for each, the per-layer numRuns budget, and the property disciplines — mutation-check every new property, answer a vacuous one with a denser generator rather than more runs, never pin a seed, and never build an oracle out of the code it is judging. Coverage ledgers are .claude/rules/coverage-ledger.md, which is path-scoped and loads itself.

Required Workflow

1. Write the red test first

• Reproduce the bug or target behavior before changing production code.
• Keep the first failing case as small and local as possible.

2. Turn it green locally

Run the narrowest project first:

pnpm test --project mcp-node
pnpm test --project canvas-viewer-jsdom
pnpm test --project canvas-viewer-browser

After the targeted test passes, run the broader suite that covers the touched area.

3. Manually verify the real behavior

• For UI work, open the real screen and confirm the behavior directly.
• Prefer Chrome DevTools MCP or Playwright MCP when available to inspect DOM, console, network, and visible behavior.
• If the changed flow is represented by a project skill under ./skills/*, read the relevant SKILL.md and dogfood the real MCP/skill flow instead of verifying only through mocks.
• While dogfooding, collect friction, awkward prompts, missing affordances, and ideas for follow-up improvements.
• Record every still-open dogfooding finding as a whiteboard document issue (see the ticketing skill). When it is fixed, change it to type: note with a RESOLVED — name and say what fixed it — do not delete it. What the document accumulated is the measurements, and those are what stop it being investigated again.
• If runtime behavior disagrees with the test, treat runtime as the source of truth and fix the test or implementation.