AstralView/AGENTS.md

AGENTS.md — AstralView Repo Rules (AI + Human)

This repository is a high-quality monorepo. Any change must keep the system:

• Correct (tests + typechecks)
• Understandable (clean architecture + docs)
• Low-coupling (SDK is framework-agnostic)
• High availability mindset (resilience, safe defaults)

Non‑Negotiables

1. No big-bang rewrites. Work in small, reviewable steps.
2. SDK is sacred. packages/sdk must not depend on React/Vue/DOM. Pure TS.
3. Editor depends on SDK, not vice versa.
4. Docs are truthful. If docs claim something works, it must be tested.
5. Keep boundaries explicit. Cross-package imports must be via package entrypoints.

Quality Gates (must be green)

• pnpm -r lint
• pnpm -r build
• pnpm -r typecheck
• pnpm -r test (when tests exist)

Architecture Conventions

packages/sdk

• Expose only stable APIs via src/index.ts.
• Use clear layers: core/ (types + pure functions), runtime/ (optional adapters).
• Prefer dependency inversion (interfaces) over direct imports.

packages/editor

• React + TypeScript.
• UI state (view) separated from business logic (SDK).
• Any persistence/networking should go through SDK interfaces.

packages/docs

• VitePress.
• Document the public SDK API and editor usage.

Code Style

• TypeScript strict.
• No any unless justified.
• Prefer explicit names over cleverness.

Commit Discipline

• Conventional commits recommended: feat:, fix:, docs:, chore:, refactor:.
• Each commit should build.

Security / Safety

• Do not add telemetry.
• Do not check in secrets.
• Avoid unsafe shell commands in scripts.