# Codex + CI Checklist

Goal: Use Codex as a powerful assistant **without** breaking the Box System or letting unreviewed AI code slip into production.

This checklist is for every feature or refactor where Codex is involved.

---

## 1. Before You Ask Codex

- [ ] **Create a feature branch** from `main` or `develop`: - Example: `feature/auto-registration-device-code`.
- [ ] **Confirm docs are up to date**: - `docs/ARCHITECTURE.md` - `docs/SYSTEM_OVERVIEW.md` - `docs/DEVELOPMENT_CHECKLIST.md` - `docs/ROADMAP.md`
- [ ] **Clarify the task in your own words**: - What are you changing? - Which app? (`box-mgnt-api`, `box-app-api`, `box-stats-api`) - What are the constraints? (e.g. “no breaking changes”, “BigInt timestamps”)

---

## 2. When Prompting Codex

- [ ] **Mention the project context**: - “We are in `box-nestjs-monorepo` (NestJS + TypeScript, MySQL, Mongo, Redis).”
- [ ] **Tell Codex to read the docs** referenced in `.codex/config.json`.
- [ ] **Use a structured prompt** (from `docs/CODEX_PROMPTS.md`), including: - Architecture reference. - Tech stack. - Constraints: - TypeScript only. - NestJS patterns. - BigInt epoch for timestamps. - Avoid breaking changes.
- [ ] **Ask for a plan before code**: - “Step 1: Summarize current design.” - “Step 2: Propose changes and list affected files.” - “Step 3: Wait for confirmation before generating TypeScript code.”

---

## 3. Reviewing Codex’s Plan

- [ ] Check the **alignment with architecture**: - Does the plan match `ARCHITECTURE.md` and `API_FLOW_DIAGRAMS.md`?
- [ ] Check **scope vs roadmap**: - Is the change consistent with the current phase in `ROADMAP.md`?
- [ ] Check **dependencies & impact**: - Which modules, services, DTOs, and DB schemas are affected?
- [ ] If anything feels off: - [ ] Ask Codex to revise the plan. - [ ] Or narrow the scope.

Do **not** accept auto-generated code if the plan itself looks wrong.

---

## 4. Generating Code with Codex

- [ ] Ask Codex to: - Generate TypeScript code **in small chunks** (one module/file at a time). - Clearly label which file each snippet belongs to.
- [ ] Verify: - [ ] Uses TypeScript and NestJS decorators correctly. - [ ] Respects BigInt timestamps for date/time fields. - [ ] Uses existing conventions from `libs/common`, `libs/core`, `libs/db`.
- [ ] Manually **paste code into files** (or let Codex apply edits, but still review them).

---

## 5. Local Verification (Before Commit)

- [ ] Run **TypeScript compilation**: - `pnpm build` or `pnpm lint` + `pnpm tsc` equivalent.
- [ ] Run **linters & formatters**: - `pnpm lint` - `pnpm format` (if applicable)
- [ ] Run **tests**: - `pnpm test` (or app-specific test commands)
- [ ] If schema changed: - [ ] Run Prisma format & generate: - `pnpm prisma:format` - `pnpm prisma:generate` - [ ] Apply local migrations to dev DB (if needed).
- [ ] Test **key endpoints** manually with curl/Postman: - Especially: - New/modified endpoints. - Auth-protected routes. - Redis-related flows (ad placement, stats events).

If anything fails, fix it yourself or ask Codex for a focused correction (with error logs included in the prompt).

---

## 6. Preparing the Pull Request

- [ ] Create a **clear PR title**: - Example: `feat(app-api): auto-register users by device_code`.
- [ ] In the PR description, include: - [ ] Summary of the change. - [ ] Which parts were generated or heavily assisted by Codex. - [ ] Link to **relevant docs** in `docs/` (architecture, roadmap). - [ ] Any potential risks or backward-compatibility notes.
- [ ] Attach **testing evidence**: - [ ] Commands you ran (lint, test, build). - [ ] Screenshots/logs for manual endpoint tests if useful.

---

## 7. Code Review (Human + Codex-Assisted)

Reviewer checklist:

- [ ] Understand the **functional goal** of the change.
- [ ] Confirm architecture alignment: - Modules/controllers/services match design.
- [ ] Check for: - [ ] Hardcoded secrets or credentials. - [ ] Direct DB access bypassing `libs/db` abstractions. - [ ] Inconsistent DTOs or response shapes. - [ ] Missing validation on inputs.
- [ ] Check **error handling & logging**: - Are important failures logged in a structured way?
- [ ] Optionally, use Codex again: - Ask it to review a specific file/method for: - Complexity. - Edge cases. - Missing null/undefined handling.

---

## 8. CI Integration

- [ ] Ensure your CI pipeline runs on each PR: - Lint - Tests - Build (optional)
- [ ] If CI fails: - [ ] Fix locally. - [ ] Re-run tests. - [ ] Push updates.
- [ ] Do **not** override CI protections** to merge failing PRs**, even if Codex generated the code.

---

## 9. After Merge

- [ ] Monitor logs/metrics in the relevant environment: - Error rates. - Latency. - Queue depth (for stats).
- [ ] If issues appear: - [ ] Create a hotfix branch. - [ ] Optionally use Codex to assist in debugging, but: - Keep changes small and review carefully.

---

## 10. Golden Rules

1. Codex is a **power tool**, not an excuse to skip thinking.
2. Docs in `docs/` are **the source of truth**; Codex must follow them.
3. Never merge Codex-generated changes **without**:
   - Passing tests.
   - At least one human review.
4. When in doubt:
   - Reduce the scope.
   - Add more tests.
   - Ask Codex for a design explanation before touching code.