3.9 KiB
Agent Instructions
You are helping implement MosaicIQ, an AI-native equity research workspace.
Use the attached MosaicIQ Design Document v3 as the primary reference for product intent, UX direction, architecture, screen specs, agent behavior, and implementation details. This file is intentionally light; the design doc contains the fuller guidance.
Core Direction
Build a clean, fast, local-first equity research application with a t3-code-style architecture:
- Clear client/server boundary
- Typed RPC layer for all client/server communication
- Local-first persistence
- Simple, composable React components
- Minimal magic, strong types, predictable state
- Practical implementation over over-engineering
Product Identity
The product name is MosaicIQ.
Do not use old/internal names like “Meridian” in user-facing UI unless the design doc explicitly says it is internal.
Design Feel
Follow the design doc’s editorial research-workstation style:
- Serif display typography for headings
- Monospace for tickers, numbers, metadata, financial tables, and code-like labels
- Sans-serif for body/UI text
- Warm neutral palette with one restrained rust accent
- Hairline borders and whitespace instead of heavy cards, shadows, or gradients
- Dense but calm layout for analysts working on desktop screens
Keep the UI serious, analytical, and professional.
Architecture Rules
Prefer the structure described in the design doc:
- Client never reads or writes storage directly
- Client talks to the server through typed RPC methods
- Server owns SQLite persistence, agent orchestration, file I/O, and export logic
- Client owns UI state such as active screen, panels, collapsed nav, search, and display preferences
- Use schema validation and safe defaults for settings
- Keep the path open for future remote/server deployment
Agent Behavior
Agents should feel like collaborative research analysts, not black-box tools.
They should:
- Surface assumptions
- Cite or reference source material when possible
- Flag uncertainty
- Ask for clarification only when needed
- Support review, acceptance, rejection, and revision workflows
- Avoid pushing unvalidated conclusions directly into final outputs
Use the design doc’s agent system, validation loop, and screen guidance for details.
Implementation Priorities
Start simple and build in layers:
- App shell and navigation
- Portfolio/company workspace
- Financial model table UI
- Memo editor
- Agent orchestration UI
- RPC/server persistence
- Export flows
- Validation/review loops
Do not try to implement everything at once. Favor small, working vertical slices.
Coding Style
- Use TypeScript throughout
- Keep components small and readable
- Prefer explicit state and typed data contracts
- Avoid unnecessary abstractions
- Avoid large monolithic files
- Keep styling consistent with the design tokens in the design doc
- Make empty, loading, error, and disabled states feel intentional
Dev Server
NEVER start, stop, restart, or manage the app/dev server. Do not run npm run dev, pnpm dev, yarn dev, vite, vite preview, Electron launch commands, or equivalent server/app-start commands.
The user runs the app independently. Your job is to write/edit code and run non-server verification commands such as typecheck, lint, tests, or production build when requested or appropriate.
Do not open or navigate a browser to the local app unless the user explicitly asks for browser inspection and confirms that they already have the app running.
When Unsure
Refer back to the MosaicIQ Design Document v3. It contains additional helpful information on:
- Design tokens
- Screen specifications
- Component behavior
- RPC methods
- SSE events
- Data/state shape
- Persistence/versioning
- Agent workflows
- Export center
- Accessibility and keyboard shortcuts
Default to the design doc unless it conflicts with a newer explicit instruction.