mirror of
https://github.com/jjbrunton/Sauci.git
synced 2026-10-31 10:19:43 +00:00
jjbrunton
bdfe8b7171
Keep Sol responsible for scope, steering, and final acceptance while assigning one continuous discovery, implementation, testing, and iteration unit to Terra. Route additional reviewers and runtime verification by risk and avoid redundant verification passes.
92 lines
4.8 KiB
Markdown
92 lines
4.8 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. The Sol primary agent owns scope, risk classification, acceptance criteria,
|
|
progress steering, final diff and evidence review, and the final answer.
|
|
Delegate every substantive repository task to a project agent. Each
|
|
substantive implementation must use one Terra `implementation` agent as a
|
|
coherent execution unit, normally combining scoped discovery, implementation,
|
|
focused tests, and iteration. "Substantive" includes repository exploration,
|
|
multi-file reasoning, implementation, test execution, or contract/risk
|
|
analysis. Add a `repo_scout`, reviewer, or verifier only for separable work or
|
|
the triggers in `docs/agents/routing.md`; do not duplicate the implementation
|
|
agent's detailed exploration or checks without a concrete reason. 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`.
|
|
12. Agents must not use em dash characters in text they add to this repository.
|
|
|
|
## 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.
|