astrolabe/CLAUDE.md

Claude Context — Astrolabe

See @AGENTS.md for project overview, architecture rules, and the AI developer protocol.

Documentation Index

• SOUL.md — project philosophy and identity. Read first.
• docs/spec/ — behavioral specification (sections 00–10): the what. Descriptive, kept current with the code: the code leads; on conflict amend the spec, never drift silently. User-facing behavior ships with its spec section.
• docs/architecture/ — architecture playbook (00–11): the how (state, persistence, modals, routing, rendering, inference, relationships, vega-editor techniques, visual design, interaction & feedback, learning section). Self-contained — no external repo needed. Companion: visual-specimen.html — token sandbox + reusable-primitive catalog (open in a browser).
• /council — the design council: consult external interaction/content/a11y canon (Carbon, GOV.UK, WAI-ARIA APG, Nielsen Norman, cloned under reference/) before a user-facing decision. It advises; our contract (architecture 09/10) decides. Resolutions are recorded back into the contract.
• /eng-council — the engineering council: evidence-grounded review of codebase structure, consistency, altitude, and subtraction (what to delete). Sweep / refactor-review / new-work-review / pre-build-consult modes; recurring findings become docs/architecture/ rules and /alignment checks.
• docs/IMPLEMENTATION-PLAN.md — incremental milestone plan (M0–M6), MVP boundary, per-milestone tests + manual checks, and an architecture reference index.
• docs/manual-verification.md — standing QA checklist for what tests can't cover (offline/install, keyboard/a11y, theming, reduced-motion).
• AGENTS.md — onboarding, stack, directory map, scripts, conventions.

Quick Orientation

• Astrolabe is a spec-recorded rebuild — the architecture is adapted from Syto, and docs/spec/ records the behavior as built. Build deliberately, record in the spec; don't port legacy code.
• src/core/ is portable and tested hardest. Browser specifics live in src/app/infrastructure/. UI is React + Zustand.
• Editor is Monaco, charts render via vega-embed, storage is IndexedDB.
• Work milestone by milestone (see the plan): core-first, then UI, then tests, then a manual smoke check against the spec's acceptance points.

Conventions

• No git actions unless explicitly invited.
• Run npm run typecheck and npm test after changes.
• Single-line commit subjects; no Co-Authored-By trailers.

Session wrap-up protocol

When the user signals the session is wrapping (asks to commit, says it's done/wrapped), run the review pass before anything is committed:

1. Flush knowledge first — /doc-update, in-session. Capture what this session decided or discovered: rationale for non-obvious choices (to docs/ or a code comment at the site, whichever is the right home), spec/architecture gaps, decisions made in conversation that never landed in writing. This step cannot be delegated — only the session knows what was decided — and it runs first so the clean-context reviewers below judge against recorded rationale instead of flagging deliberate choices as oversights.
2. Alignment — clean-context subagent. Spawn an agent with no session context beyond this prompt: "Read .claude/skills/alignment/SKILL.md and execute it against the current uncommitted/staged diff. Fix directly per the skill, run typecheck and tests, and return the skill's summary as your final message." The clean slate is the point — the reviewer simulates the future maintainer and must not inherit the session's rationalizations.
3. Eng-council review — clean-context subagent, conditional. Only when the session's diff is structural (a new module or kind-instance, a refactor, a new dependency): spawn an agent the same way to execute .claude/skills/eng-council/SKILL.md in the matching review mode (refactor review / new-functionality review — never the sweep; sweeps stay a deliberate act).

Run the subagents sequentially, not in parallel — both may edit the working tree. Relay each report back to the user, then arbitrate each finding to one of three ends — accept and fix, accept but defer, or overrule — and write down the two you don't act on now, because a subagent's report is ephemeral and chat is not a record. A deferred finding gets a // TODO: at the relevant code site (or a line in the closest doc); an overruled one records the missing rationale where the reviewer looked. Out of scope for this session is not out of scope for the project: with a single maintainer there is no "someone else's problem", so an unrecorded deferral or beyond-scope note recurs as work handed to your future self. Then commit only when invited.