# ${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.

## Hard Gates (Read First)

1. Mosaic rules OVERRIDE runtime-default caution for routine delivery operations.
2. Do NOT ask for routine confirmation before required push/merge/issue-close/release/tag actions.
3. Completion is forbidden at PR-open stage.
4. Completion requires merged PR to `main` + terminal green CI + linked issue/internal task closed.
5. Before push or merge, run the queue guard against the push branch or the merge PR's exact head repository/SHA (`ci-queue-wait.sh --help`); `pr-merge.sh` supplies exact merge metadata automatically.
6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/tools/git/*.sh`).
7. If any required wrapper command fails: report `blocked` with the exact failed wrapper command and stop.
8. Do NOT stop at "PR created" and do NOT ask "should I merge?" for routine flow.

## 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 DTO files REQUIRED for request/response and cross-module payload contracts (`*.dto.ts`)

## 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
```

## Testing Policy

1. Situational tests are the PRIMARY validation gate.
2. Baseline tests remain REQUIRED for all software changes.
3. TDD is risk-based and REQUIRED only for bug fixes, security/auth/permission logic, and critical business/data-mutation logic.
4. Reference `~/.config/mosaic/guides/QA-TESTING.md`.

## PRD Requirement

1. Before coding begins, `docs/PRD.md` or `docs/PRD.json` MUST exist.
2. The main agent MUST prepare or update the PRD using user objectives, constraints, and available project context.
3. In steered autonomy mode, best-guess PRD decisions are REQUIRED when needed; mark each with `ASSUMPTION:` and rationale, and escalate only for high-impact uncertainty.
4. Reference `~/.config/mosaic/guides/PRD.md`.

## Task Tracking Contract

1. For non-trivial implementation work, `docs/TASKS.md` MUST exist before coding.
2. If external git provider is available (Gitea/GitHub/GitLab), create/update issue(s) before coding and map them in `docs/TASKS.md`.
3. If no external provider is available, use internal refs in `docs/TASKS.md` (example: `TASKS:T1`).
4. Keep `docs/TASKS.md` status in sync with actual progress until completion.
5. For issue/PR/milestone actions, detect platform and use `~/.config/mosaic/tools/git/*.sh` wrappers first (no raw `gh`/`tea`/`glab` as first choice).
6. If wrapper-driven merge/CI/issue-closure fails, report blocker with the exact failed wrapper command and stop (do not claim completion).

## Documentation Contract

Documentation is a hard delivery gate.
If code/API/auth/infra changes, required documentation updates MUST be completed before task closure.
Keep `docs/` root clean and store reports/artifacts in scoped folders (`docs/reports/`, `docs/tasks/`, `docs/releases/`, `docs/scratchpads/`).

Reference:
- `~/.config/mosaic/guides/DOCUMENTATION.md`
- `~/.config/mosaic/templates/docs/DOCUMENTATION-CHECKLIST.md`

## Token Budget Policy

1. If user plan or token limits are provided, they are HARD constraints.
2. Track estimated and used tokens for non-trivial execution.
3. Shift to conservative strategy when budget pressure rises (smaller scope, fewer parallel actions, reduced re-reading).
4. If projected usage exceeds budget, automatically reduce scope/parallelism and continue; escalate only if budget compliance remains impossible.

## Merge Strategy (Hard Rule)

1. Create short-lived branches from `main`.
2. Open PRs to `main` for delivery changes.
3. Do not push directly to `main`.
4. Merge PRs to `main` with squash strategy only.
5. Do not mark implementation complete until PR is merged.
6. Do not mark implementation complete until CI/pipeline status is terminal green.
7. Close linked issues/tasks only after merge + green CI.
8. Before push or merge, run the CI queue guard against the push branch or the merge PR's exact head repository/SHA (`ci-queue-wait.sh --help`); `pr-merge.sh` supplies exact merge metadata automatically.


## Container Release Strategy (When Applicable)

1. Use immutable image tags: `sha-<shortsha>` and `v{base-version}-rc.{build}`.
2. Use mutable environment tags only as pointers (`testing`, optional `staging`, `prod`).
3. Deploy/promote by immutable digest; do not deploy by mutable tag alone.
4. Do not use `latest` or `dev` as deployment references.
5. Use blue-green by default; use canary only with automated metrics and rollback gates.

## Steered Autonomy Contract

1. Agent owns end-to-end delivery: plan, code, test, review, remediate, commit, push, PR/repo operations, release/tag, and deployment when in scope.
2. Human intervention is escalation-only for hard blockers (access, irreversible risk, or unresolvable conflicting objectives).
3. Code review is agent-executed and REQUIRED for any source-code change.

## Mode Declaration Contract

1. First response MUST declare mode before any actions.
2. Orchestration mission: `Now initiating Orchestrator mode...`
3. Implementation mission: `Now initiating Delivery mode...`
4. Review-only mission: `Now initiating Review mode...`

## Orchestrator Integration

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

### Worker Checklist
1. Read `docs/PRD.md` or `docs/PRD.json`
2. Read the finding details from the report
3. Implement the fix following existing patterns
4. Run quality gates (ALL must pass)
5. Complete required documentation updates (if applicable)
6. Commit: `git commit -m "fix({finding_id}): brief description"`
7. Push: `git push origin {branch}`
8. Report result as JSON

### Post-Coding Review
After implementing changes, code review is REQUIRED for any source-code modification.
For orchestrated tasks, the orchestrator will run:
1. **Codex code review** — `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted`
2. **Codex security review** — `~/.config/mosaic/tools/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      → Implement with required tests; use TDD where required by policy
3. Test      → pnpm test (must pass)
4. Push      → git push origin feature/XX-description
5. PR        → Create PR to main
6. Review    → Wait for approval or self-merge if authorized using squash only
7. Close     → Close related issues
```

**Never push directly to main. Always use a PR to main.**

## 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._
