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/ — authoritative behavioral specification (sections 00–10): the what. This is the contract; implement to it.
• docs/architecture/ — architecture playbook (00–10): the how (state, persistence, modals, routing, rendering, inference, relationships, vega-editor techniques, visual design, interaction & feedback). 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-driven rebuild — the behavior is fixed in docs/spec/; the architecture is adapted from Syto. Implement to 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. Arbitrate findings that needed session context: either accept them, or overrule them and record the missing rationale where the reviewer looked for it — an overruled finding without a writing-down will recur. Then commit only when invited.