Halo Dev

If a change conflicts with the documented architecture, update the architecture document first with justification, then proceed.

Development Priority (Non-Negotiable)

• Modularity, quality, and maintainability come first.
• Performance must not regress (startup, runtime latency, memory).
• Responsive design is mandatory — every UI change must work at mobile width (< 640px).
• No hardcoded colors — use only CSS variable-based theme tokens.
• If a quick fix conflicts with architecture quality, choose the maintainable modular solution and request explicit user approval before proceeding.

Fast Navigation Policy

After the mandatory entry docs:

• Jump directly to touched module DESIGN.md:
  • src/main/apps/*/DESIGN.md
  • src/main/platform/*/DESIGN.md
• For transport-level changes, inspect:
  • src/main/ipc/
  • src/main/http/routes/index.ts
  • src/preload/index.ts
  • src/renderer/api/index.ts
• For renderer changes, check:
  • Existing component structure in src/renderer/components/
  • Existing stores in src/renderer/stores/
  • Existing hooks in src/renderer/hooks/

Source of Truth Priority

When docs and code differ:

1. Actual code in src/**
2. Module design docs (src/main/apps/*/DESIGN.md, src/main/platform/*/DESIGN.md)
3. quick.md, ARCHITECTURE.md, CONTEXT.md

Keeping These Documents Updated

After completing a development task, evaluate whether these documents need updating. Apply the following rules:

Update when the change significantly affects how a developer understands the codebase:

• New module or service added to the architecture
• New IPC channel introduced
• Major refactoring that changes code organization
• New architectural pattern or convention established
• Core data type added or significantly changed
• New component directory or page added

Do not update for changes that don't affect architectural understanding:

• Bug fixes
• Minor features within existing modules
• Styling or UI tweaks
• Performance optimizations that don't change structure
• Dependency updates
• Code cleanup or formatting

The threshold is: would a new AI developer make wrong assumptions without this information? If yes, update. If no, skip.