mirror of
https://github.com/jjbrunton/Sauci.git
synced 2026-10-31 18:19:43 +00:00
88 lines
4.5 KiB
Markdown
88 lines
4.5 KiB
Markdown
# Sauci agent map
|
|
|
|
Sauci is a couples connection product: an Expo mobile app, React admin, Next.js
|
|
web app, standalone Node/PostgreSQL backend, hosted Supabase Auth, and an internal
|
|
MCP service in one npm/Turborepo workspace.
|
|
|
|
## Golden rules
|
|
|
|
1. Read the nearest `AGENTS.md` before changing a scoped area.
|
|
2. Preserve tenant and couple isolation. Never bypass RLS, role checks, or auth.
|
|
3. Product-data schema changes are committed SQL files in `apps/api/drizzle/`.
|
|
Hosted Supabase owns Auth only; do not deploy product-data migrations or Edge
|
|
Functions there. Never execute remote DDL through MCP or provider tools.
|
|
4. Never target production from local development or E2E. Database integration
|
|
tests must fail closed unless `DATABASE_URL` resolves to loopback. Authenticated
|
|
native acceptance may use only the designated non-production Auth project.
|
|
5. Read `apps/mobile/DESIGN.md` before mobile UI work.
|
|
6. Keep shared package exports type-only and route them through `src/index.ts`.
|
|
7. Do not commit secrets, generated evidence, local logs, or runtime state.
|
|
8. Implement in a task-specific git worktree created from current `staging`,
|
|
not in the shared `staging` checkout. After the work is verified, commit the
|
|
scoped changes, merge the completed task branch back into local `staging`,
|
|
push `staging`, and prove local and remote commit parity.
|
|
9. Before merging, identify every deployed app or service the change can affect
|
|
and prove the relevant compatibility contracts still hold. Preserve deployed
|
|
interfaces and supported client behavior; repository checks alone do not
|
|
prove a live change is safe.
|
|
10. Delegate every substantive repository task to at least one project agent so
|
|
detailed exploration or execution stays out of the primary context.
|
|
"Substantive" includes repository exploration, multi-file reasoning,
|
|
implementation, test execution, or contract/risk analysis. Use `repo_scout`
|
|
for read-only investigation and `implementation` for bounded changes; use
|
|
the additional roles according to `docs/agents/routing.md`. The primary
|
|
agent retains scope, acceptance, review, and the final answer. Skip
|
|
delegation only for trivial conversation, a single obvious lookup, or a
|
|
mechanical one-line edit whose coordination cost exceeds the work.
|
|
11. Use high-effort reviewers only for the risk triggers in
|
|
`docs/agents/routing.md`.
|
|
|
|
## Repository map
|
|
|
|
| Area | Purpose | Local instructions |
|
|
|---|---|---|
|
|
| `apps/mobile` | Expo React Native product | `apps/mobile/AGENTS.md` |
|
|
| `apps/admin` | Vite administration UI | `apps/admin/AGENTS.md` |
|
|
| `apps/web` | Next.js marketing/redemption UI | `apps/web/AGENTS.md` |
|
|
| `apps/api` | standalone API, worker, PostgreSQL migrations | repository rules |
|
|
| `apps/supabase` | legacy data-plane history; hosted Auth configuration only | `apps/supabase/AGENTS.md` |
|
|
| `apps/mcp` | internal administrative MCP service | `apps/mcp/AGENTS.md` |
|
|
| `packages/shared` | shared TypeScript contracts | `packages/shared/AGENTS.md` |
|
|
| `e2e` | cross-application Playwright flows | `e2e/README.md` |
|
|
| `docs` | maintained system of record | `docs/index.md` |
|
|
|
|
## Workflows
|
|
|
|
- Implementation: create a task worktree from current `staging`; commit verified
|
|
work, merge it back to local `staging`, push `staging`, and verify remote parity.
|
|
- Bootstrap: `npm ci`
|
|
- Full local stack: `scripts/dev-local.sh up`
|
|
- Fast checks: `npm run verify:fast`
|
|
- Authoritative repository checks: `npm run verify:full`
|
|
- Running-stack E2E: `npm run verify:e2e`
|
|
- Everything: `npm run verify`
|
|
- Before a PR: use `.codex/skills/verify/SKILL.md`
|
|
|
|
When a check cannot run because a prerequisite is absent, report it as an
|
|
environment limitation; do not call it a passing product check.
|
|
|
|
## Where to look
|
|
|
|
| Question | Source of truth |
|
|
|---|---|
|
|
| System boundaries and data flow | `docs/architecture/system.md` |
|
|
| Local services, ports, fixtures | `docs/development/local-stack.md` |
|
|
| Test layers and required gates | `docs/testing/strategy.md` |
|
|
| Database migration safety | `docs/operations/database-migrations.md` |
|
|
| Agent roles and effort routing | `docs/agents/routing.md` |
|
|
| Learning promotion | `docs/agents/learnings.md` |
|
|
| Mobile visual language | `apps/mobile/DESIGN.md` |
|
|
| Domain documentation index | `docs/index.md` |
|
|
|
|
## Documentation discipline
|
|
|
|
Update the maintained doc when a contract, command, port, or invariant changes.
|
|
Plans and historical notes are evidence, not current architecture. A repeated
|
|
lesson becomes permanent only after it is reproduced and promoted into a doc,
|
|
skill, fixture, or executable check.
|