flightdeck / dashboard
CLAUDE.md30 starsChanged yesterdayApache-2.0View on GitHub
Component-specific rules moved out of the root CLAUDE.md so they load only when working under dashboard/. All root CLAUDE.md rules still apply; the numbering below keeps the original rule numbers. 11. Frontend unit tests: Vitest + React Testing Library. Every component that handles data or state must have unit tests. 14. Both themes must work at all times. After any frontend change, verify both neon dark and clean light render correctly. Breaking one theme is an incomplete task. 15. Never…
In this repository3 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- sensor/CLAUDE.mdCLAUDE.md
- docs/llms.txtllms.txt
The file
We split this CLAUDE.md into the rules it gives an agent
5 rules. About 0 are common, 5 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
Both themes must work at all times: After any frontend change, verify both neon dark and clean light render correctly.
- Distinctive: line 20
Only edit with explicit maintainer approval.
- Distinctive: line 25
No placeholder UI: If a feature is not ready it does not appear in the UI.
- Distinctive: line 26
No grey boxes, no "coming soon" panels, no disabled stubs for incomplete features.
- Distinctive: line 77
BEFORE committing. The suite must pass against a fresh dev stack + seed.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md 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
Flightdeck Dashboard -- Claude Code Rules
Component-specific rules moved out of the root CLAUDE.md so they load only when working under dashboard/. All root CLAUDE.md rules still apply; the numbering below keeps the original rule numbers.
Frontend Code Rules
- Frontend unit tests: Vitest + React Testing Library. Every component that handles data or state must have unit tests.
- E2E tests: Playwright. Full user flows in both neon dark and clean light.
- Never use MUI, Ant Design, or Chakra UI. shadcn/ui and custom components only.
- Both themes must work at all times. After any frontend change, verify both neon dark and clean light render correctly. Breaking one theme is an incomplete task.
- Never casually edit globals.css or themes.css. These define both themes. Only edit with explicit maintainer approval.
- D3 is used for math only. In the timeline component, D3 is used exclusively
for
d3-scaleandd3-timecalculations. D3 must never manipulate the DOM. - No placeholder UI. If a feature is not ready it does not appear in the UI. No grey boxes, no "coming soon" panels, no disabled stubs for incomplete features.
E2E Discipline
40c. E2E test discipline. Every phase that adds or changes
user-visible UI behavior adds corresponding E2E tests at
dashboard/tests/e2e/ covering the new behavior. Tests are
named after the user journey they cover
(Tnn-<kebab-case-journey>.spec.ts), one journey per file so
a failing test's filename tells you what's broken without
opening the trace. The V-pass for any UI phase MUST list the
E2E tests that will be added before implementation starts.
Why: Phases 1 and 2 each shipped UI regressions (phantom
rows, font-mono size collapse, PR #24 bucket-divider
misalignment) that unit tests missed. The common shape: a
single component's mock test passed while the rendered
dashboard misbehaved. E2E tests exercising the real dashboard
against a seeded dev stack would have caught each one. The
Phase 3 Playwright foundation exists so every post-v0.4.0 UI
change inherits that floor.
How to apply: when planning a UI-touching task, name the E2E
tests in the plan. When implementing, write those tests before
or alongside the behavior change -- not after. When reviewing,
reject a UI PR whose only test coverage is unit tests.40c.1. E2E stability — tests that flake are fixed or deleted,
never merged as-is. CI retry is a tolerance buffer for
genuine infrastructure blips (stack boot race, NATS reconnect,
WSL disk flush), NOT for tests. The Playwright config sets
retries: 1 on CI and 0 locally so flakes surface on
the first run and get fixed. A test that fails on the second
sequential local run against unchanged code is a flake and
must not ship.
Why: flaky tests teach reviewers to ignore failures ("it's
just that flaky one") which is indistinguishable from
abandoned test coverage. One trusted test is worth ten flaky
ones.
How to apply: after writing a test, run the suite twice in a
row locally against a fresh dev stack + seed. Both must pass
cleanly. If any test flakes, debug the root cause (timing
assumption, race condition, implicit state) rather than
adding retry.40c.2. E2E as the pre-commit smoke gate for UI work. After any
UI edit, run cd dashboard && npm run test:e2e locally
BEFORE committing. The suite must pass against a fresh dev
stack + seed. This is the minimum verification bar for UI
changes, below which work is not considered complete.
Inherits from rule 40b (pre-commit live test): where 40b is
about runtime behaviour generally, 40c.2 specialises to the
dashboard and requires the Playwright suite specifically.40c.3. E2E theme coverage. Tests run under both neon-dark
and clean-light theme projects via Playwright's
projects config. Tests MUST NOT hardcode theme-specific
selectors or computed colour values; assertions are
theme-agnostic. Any new theme-dependent rendering logic
requires E2E coverage that passes under both themes. The
config already wires storageState per project; spec authors
just keep assertions structural.
Why: rule 14 requires both themes to work at all times.
Without automated per-theme coverage, "both themes work"
degrades to "dark theme works, light theme breaks on Tuesdays"
-- which is exactly the regression shape the font-mono collapse had until a
manual light-theme pass caught it.40c.4. Live-load Chrome verification after every dashboard step. When a step touches dashboard chrome (a page route, a panel, a route-level component, or any UI surface end users navigate to), the step does not close until the dev stack has been built with branch HEAD AND the affected surfaces have been opened in a real Chrome window AND the happy-path interaction has been performed manually. Mock- based unit tests, Vitest passing, and TypeScript clean are all necessary but insufficient — they verify the contract between component and props, not the contract between component and the live API / WebSocket / theme stylesheet / fleet store under real network conditions.
The verification log for the step must list:
- Which routes were opened (e.g. ``/mcp-policies``,
``/investigate``, ``/fleet``).
- Which interactions were exercised (e.g. open dialog →
fill required fields → submit; trigger 403 path; open
SessionDrawer on a session emitting target events).
- Which themes were checked (rule 14 requires both).
- The dev-stack build SHA (so the verification is pinned to
branch HEAD, not a stale prod-image layer per Rule 40b).
Inherits from Rule 40a (live-stack verification). Where 40a
is "exercise new runtime code paths against the live stack
before claiming they work" and 40b is "rebuild the stack
with branch HEAD before pre-commit testing", 40c.4 is the
specialisation for dashboard chrome: a live Chrome session
is the only thing that surfaces theme-token gaps, fleet-WS
re-fetch wiring, focus traps inside Radix portals, and the
"Mock said handler fires, real stack says backend 500"
class of bug.
Why: every step in the MCP Protection Policy work surfaced
at least one polish gap that mocks missed and Chrome caught
— empty MCP SERVERS panel on a live session, tab
overflow on small viewports, hardcoded amber-500 in the
soft-launch banner, "Admin token required" without an
actionable hint. Two-hat Chrome verification (operator
pretends to be a fresh user, then a hostile auditor) is the
only methodology that reliably surfaces these without
shipping them. Step 6.6 codifies the pattern after step 6
proved its value the hard way.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.

