Encore OS is a multi-tenant healthcare ERP for behavioral health and recovery housing operations. Platform version
0.9.0-alpha. 12 cores: PF + 11 domain cores. Your work will live in one or two of them; the architecture keeps you from accidentally breaking the others.Day one (45 minutes)
1
Get the repo running
Follow Setup Quick Start end-to-end. You’ll clone, install (
npm ci — legacy-peer-deps is preset), configure .env, start Supabase locally, and run npm run dev. Don’t skip the Supabase step; nothing works without it.2
Read the constitution
/governance/canonical/constitution is non-negotiable guardrails. Skim §1 (Architecture), §3 (Security), §5 (Database), §7 (Testing). When in doubt about anything, the constitution wins.3
Skim AGENTS
/governance/canonical/agents is the always-loaded quick reference. It documents patterns, the regulatory decision tree, and the list of things AI agents (and humans) must never do. You’ll re-read this dozens of times.4
Learn the boundary rules
Core Boundary Rules — what’s allowed across the 12 cores. The single most common review comment is “core X is importing from core Y; route through PF.” Internalize this on day one.
5
Run the tests
Testing setup and run is the canonical test reference. Run npm run test:baseline once to see the full pyramid (unit + integration + RLS smoke + E2E smoke) execute. If it fails locally, fix it before writing any code — the environment is wrong.Daily commands
The cheat-sheet you’ll actually use: Development Quick Reference.How specs become code
Encore OS is spec-driven. Every shippable change traces to a spec. The pipeline:eos-spec next --spec <ID>. See SPEC_COMMAND_CHEATSHEET for the full taxonomy and SPEC_WORKFLOW for the canonical workflow doc.
You won’t always touch every stage — many specs are inherited mid-pipeline. But you do need to know what the current status means before you commit.
How AI fits in
This codebase is co-authored with AI assistants (Claude Code, Cursor, Lovable, GitHub Copilot). The rules they follow are the rules you follow. The hierarchy:/governance/canonical/ai-guide— workflow, decision framework, implementation log protocol./governance/canonical/agents— quick-reference and “AI must never” list.MCP Usage— Model Context Protocol servers we use (Supabase, Fallow, Context7, encore-api-surface).AGENTS_BEST_PRACTICES_CURSOR— when you’re driving with Cursor.
Where things live
Common reviewer pushbacks
Where to go from here
- Architecture deep-dive:
/architecture/indexand the 22 ADRs - Spec governance:
/governance/index - All dev guides:
/development/index - Testing:
/testing/TESTING_SETUP_AND_RUN - Database:
/database/migration-workflow - Operations:
/operations/docs-health(live coverage scorecard)