# Repository Guidelines

**MAIN RULE:** DON'T MADE UP ANYTHING!!! IF YOU NOT SURE - DOUBLECHECK IT VIA PROJECT DOCUMENTATION, TOOL DOCUMENTATION, APPROPRIATE MCP, WEB SEARCH OR JUST ASK FOR ME TO CLARIFY. 

## Working Principles

1. **Check docs first**: Read relevant documents files before starting tasks (links provided below)
2. **Minimal changes**: Update only necessary files, prefer simple robust solutions
3. **Use SKILLS**: For best results in specific areas, use the appropriate **SKILLS** in `.codex/skills` (56 skills available)
4. **Agents orchestration**: Use `.codex/skills/ai-agent-orchestrator/SKILL.md` skill to improve your efficiency.
5. **Use MCP servers**: Available via `mcp__<server>__<tool>`: GitHub (`github`), Chrome DevTools (`chrome-devtools`)
6. **TypeScript strict mode**: Avoid `any` types, **NEVER** disable linter or TypeScript, **NEVER** use types casting
7. **Concise comments**: Explain "why" not "what", code should be self-documenting
8. **No over-engineering**: Build for a small SaaS used by owner-operators. Choose the simplest robust solution that is fast to implement, easy to understand, and easy to support. Avoid enterprise-style architecture and unnecessary complexity: no extra fallbacks, premature abstractions, microservices, Kubernetes, complex orchestration, heavy caching, or distributed-system patterns unless the task explicitly requires them. User-facing copy must use plain language and avoid accounting jargon.
9. **Native errors for external services**: Pass through errors from Gemini/OpenAI as-is
10. **Centralized exceptions only**: Always use centralized exceptions instead of inlined logs or exceptions
11. **Use tools and agents**: Use MCP servers, web search, and agents when needed
12. **Avoid hardcoded constants**: Add to `backend/src/constants/` or `frontend/src/shared/constants/`
13. **Avoid silent failures**: Provide proper observability for all failure modes
14. **Documentation matters**: After **EACH** task update appropriate documentation files AND for **EACH** new module or feature create documentation file in appropriate directory: `backend/docs/`, `frontend/docs/` or common `docs/`
15. **Aliases for imports**: For **ALL** imports use aliases `@` instead of absolute or relative paths
16. **Tests matters**: After **EACH** task update appropriate unit and e2e tests AND for **EACH** new functionality create new tests (unit or e2e depending on the feature’s complexity and importance)

## Documentation Entry Points

- Frontend documentation index: `frontend/docs/index.md`
- Frontend architecture contract: `frontend/docs/frontend-architecture.md`
- Backend and cross-project integration plan: `docs/full-integration-refactor-plan.md`

For frontend work, read `frontend/docs/frontend-architecture.md` before implementation and follow its three-layer approach: view components, business logic, and API/data access.