# ${PROJECT_NAME} — Agent Context

> Guidelines for AI agents working on this NestJS + Next.js monorepo.
> **Update this file** when you discover reusable patterns or non-obvious requirements.

## Codebase Patterns

- **Monorepo structure:** pnpm workspaces + TurboRepo
  - `apps/api/` — NestJS backend
  - `apps/web/` — Next.js frontend
  - `packages/shared/` — Shared types and utilities
- **Database:** Prisma ORM — schema at `apps/api/prisma/schema.prisma`
- **Auth:** Configured in `apps/api/src/auth/`
- **API:** RESTful with DTOs for validation

## Common Gotchas

- **Always run `pnpm install`** after pulling — lockfile changes frequently
- **Prisma generate** after schema changes: `pnpm --filter api prisma generate`
- **Environment variables:** Frontend vars need `NEXT_PUBLIC_` prefix
- **Import paths:** Use `@shared/` alias for shared package imports
- **Tests require running database:** Set `DATABASE_URL` in `.env.test`
- **TurboRepo caching:** Run `pnpm clean` if builds behave unexpectedly

## Context Management

Context = tokens = cost. Be smart.

| Strategy | When |
|----------|------|
| **Spawn sub-agents** | Isolated coding tasks, research |
| **Batch operations** | Group related API calls |
| **Check existing patterns** | Before writing new code |
| **Minimize re-reading** | Don't re-read files you just wrote |

## Quality Gates

**All must pass before any commit:**

```bash
pnpm typecheck && pnpm lint && pnpm test
```

## Orchestrator Integration

### Task Prefix
Use `${TASK_PREFIX}` for orchestrated tasks (e.g., `${TASK_PREFIX}-SEC-001`).

### Worker Checklist
1. Read the finding details from the report
2. Implement the fix following existing patterns
3. Run quality gates (ALL must pass)
4. Commit: `git commit -m "fix({finding_id}): brief description"`
5. Push: `git push origin {branch}`
6. Report result as JSON

### Post-Coding Review
After implementing changes, the orchestrator will run:
1. **Codex code review** — `~/.mosaic/rails/codex/codex-code-review.sh --uncommitted`
2. **Codex security review** — `~/.mosaic/rails/codex/codex-security-review.sh --uncommitted`
3. If blockers/critical findings: remediation task created
4. If clean: task marked done

## Workflow (Non-Negotiable)

```
1. Branch    → git checkout -b feature/XX-description
2. Code      → TDD: write test (RED), implement (GREEN), refactor
3. Test      → pnpm test (must pass)
4. Push      → git push origin feature/XX-description
5. PR        → Create PR to develop (not main)
6. Review    → Wait for approval or self-merge if authorized
7. Close     → Close related issues
```

**Never merge directly to develop without a PR.**

## Key Files

| File | Purpose |
|------|---------|
| `CLAUDE.md` | Project overview and conventions |
| `apps/api/prisma/schema.prisma` | Database schema |
| `apps/api/src/` | Backend source |
| `apps/web/app/` | Frontend pages |
| `packages/shared/` | Shared types |
| `.env.example` | Required environment variables |

---

_Model-agnostic. Works for Claude, Codex, GPT, Llama, etc._