# AGENTS.md Review Guidelines Block (Codex rubric)

Managed `## Review guidelines` block for the target project's `AGENTS.md`.
Codex honors this section in BOTH surfaces: the local CLI
(`codex exec review`) and the cloud GitHub reviewer apply "guidance from
the closest AGENTS.md to each changed file". This is the ONLY reliable
rubric injection point — `codex exec review` rejects a custom-instructions
prompt combined with `--base`/`--uncommitted`/`--commit`.

## Install rules

1. If `AGENTS.md` does not exist: create it with just the block below.
2. If it exists WITHOUT plugin markers but WITH a `## Review guidelines`
   section: show the existing section and STOP — ask before touching.
   User-authored guidelines win; offer to append missing rules only.
3. If plugin markers exist: replace content between markers only
   (same upsert convention as the `ELIXIR-PHOENIX-PLUGIN` CLAUDE.md block).
   **Exception**: carry over the project's existing `### Known non-issues`
   entries verbatim — they are project knowledge, not template content;
   wiping them resurrects the false positives they suppress.
4. Never modify anything outside the markers.

## Block to inject

```markdown
<!-- ELIXIR-PHOENIX-REVIEW-GUIDELINES:START -->
<!-- Last updated: {DATE} | Managed by /phx:init — edits inside markers are overwritten on --update -->

## Review guidelines

Elixir/Phoenix review priorities. Flag violations at the given priority.

- **P1** Money as float — monetary values must use `Decimal` or integer
  cents; flag any float arithmetic on prices/amounts.
- **P1** Unpinned query values — Ecto query values must use `^`; flag any
  interpolation of user input into queries.
- **P1** `String.to_atom/1` on user-controlled input — atom exhaustion DoS;
  require allowlist or validated `String.to_existing_atom/1`.
- **P1** Unconditional DB queries in LiveView `mount` — mount runs twice;
  expect `assign_async` or a `connected?/1`-guarded branch.
- **P1** Missing authorization in LiveView `handle_event` — every event
  handler must authorize; mount-time authorization is not sufficient.
- **P1** `raw/1` with untrusted content — XSS.
- **P1** Implicit cross join — `from(a in A, b in B)` without `on:` creates
  a Cartesian product.
- **P2** Lists over ~100 items in LiveView assigns — require streams.
- **P2** Oban worker hazards — non-idempotent `perform`, atom keys in args,
  structs stored in args (store IDs).
- **P2** Bare `{:error, _}` swallowing changesets — `{:error,
  %Ecto.Changeset{}}` must be matched explicitly or form errors never
  re-render.
- **P2** Unsupervised long-lived processes — no bare `GenServer.start_link`
  / `Agent.start_link` outside a supervision tree in production code.
- **P3** `has_many` preloads via JOIN — prefer separate queries for
  `has_many`, JOIN for `belongs_to` (row multiplication).

### Known non-issues (do NOT report these)

<!-- Add project-specific disproven findings here as reviewers repeat them.
     One line per pattern: what the reviewer keeps claiming + why it's wrong.
     Example:
- Ecto does NOT validate schema-declared generated columns used via
  fragment() in this codebase — verified {date}, do not report as a crash.
-->

<!-- ELIXIR-PHOENIX-REVIEW-GUIDELINES:END -->
```

## Notes

- Keep the block under ~35 lines — cloud reviews read the nearest AGENTS.md
  per changed file; a bloated rubric dilutes focus.
- Cloud reviews surface mainly P0/P1 per OpenAI docs (P2/P3 observed in
  practice) — putting a priority on each rule steers what Codex reports.
- Re-running `/phx:init --update` refreshes the block in place.

# Injectable Template for /phx:init

This file contains the exact content to inject between markers. Replace `{PLACEHOLDER}` values with detected values.

## Full Template

~~~markdown
<!-- ELIXIR-PHOENIX-PLUGIN:START -->
<!-- Auto-generated by /phx:init | {DATE} | Phoenix {PHOENIX_VERSION}, Ecto {ECTO_VERSION}{OPTIONAL_STACK} -->

# Elixir/Phoenix Plugin

## Routing

| Request | Path |
|---------|------|
| Bug, unexpected behavior, stack trace | `/phx:investigate` |
| Small change (<50 lines), config, CSS tweak | `/phx:quick` |
| Feature spanning 2+ contexts, or a new domain concept | `/phx:plan` → `/phx:work` → `/phx:review` |
| Auth, sessions, tokens, payments, billing | `/phx:plan` plus the `security-analyzer` agent — security work does not skip planning |
| Scope still unclear | `/phx:brainstorm` |

Ask about scope, access, and rollback before building anything in the bottom three
rows. Skip the questions when the user says "quick" or "just do it".

## Running a `/phx:*` skill

Skills are procedures — run their steps in order rather than improvising a
different workflow. Each one names an artifact file (`.claude/plans/{slug}/…`);
write it, including agent findings, before synthesizing anything from it. Chat-only
output loses the artifact the next phase reads.

Discovering the feature already exists is a finding to record in that artifact, not
a reason to exit early.

---

## IRON LAWS — STOP if violated

If code would violate ANY of these, you MUST:
1. STOP immediately
2. Show the problematic code
3. Show the correct pattern
4. Ask permission to apply the fix

**LiveView**:
1. NO DB queries in disconnected mount → use `assign_async`
2. Use streams for lists >100 items
3. Check `connected?/1` before PubSub subscribe
4. Match `{:error, %Ecto.Changeset{}}` explicitly — bare `{:error, _}` silently hides form errors

**Ecto**:
5. NO `:float` for money → `:decimal` or `:integer` (cents)
6. Pin values with `^` in queries — never interpolate
7. Separate queries for `has_many`, JOIN for `belongs_to`

**Security**:
8. NO `String.to_atom(user_input)` — atom exhaustion attack
9. AUTHORIZE every `handle_event` — mount auth is not enough
10. NO `raw/1` with untrusted content — XSS vulnerability

**OTP**:
11. NO process without runtime reason — processes are for concurrency/state/isolation
12. Mix tasks: `Mix.Task.run("app.config")` + `Application.ensure_all_started/1`, NEVER `Mix.Task.run("app.start")` (boots full tree: endpoint port, Oban consuming)
13. Capture Gettext/CLDR locale BEFORE spawning Task/GenServer — locale is process-local, spawned processes reset to default

**Code Style**:
14. Comments aren't commit messages — change reasoning (the bug, what it replaces) goes in the commit/PR, not code. No issue tags inline (`# ENA-1234`). Keep only durable facts: footguns, quirks

{OBAN_SECTION}

{OBAN_PRO_SECTION}

{ASH_SECTION}

{TIDEWAVE_SECTION}

## VERIFICATION — MANDATORY after code changes

After each code change, run this before presenting results:

```
mix compile --warnings-as-errors && mix format --check-formatted
```

Present code as complete only after verification passes.
Offer `mix test` after significant changes.

## POST-ACTION — Offer follow-ups

| After | Offer |
|-------|-------|
| Bug fix | "Capture as lesson with /phx:learn-from-fix?" |
| Feature complete | "Quality check with /phx:review?" |
| Migration | "Check migration safety?" |

## QUICK REFERENCE

| Want To... | Use |
|------------|-----|
| Simple feature | Describe it (auto-complexity runs) |
| Complex feature | `/phx:plan` → `/phx:work` → `/phx:review` |
| Debug bug | `/phx:investigate` |
| Review code | `/phx:review` |
| Project health | `/phx:audit` |

<!-- ELIXIR-PHOENIX-PLUGIN:END -->
~~~

## Conditional Sections

### OBAN_SECTION (if Oban detected, not Pro)

```markdown
## Oban — STOP if violated

- Jobs MUST be idempotent (safe to retry)
- Args MUST use STRING keys: `%{"user_id" => id}` not atoms
- NEVER store structs in args — store IDs only
```

### OBAN_PRO_SECTION (if Oban Pro detected)

```markdown
## Oban Pro — Different API

Use `process/1` NOT `perform/1`. Use `@impl Oban.Pro.Worker`.
Standard Oban patterns DO NOT apply.
```

### ASH_SECTION (if Ash detected)

```markdown
## Ash Framework — Use ash-framework skill

This project uses Ash Framework. Before writing ANY Ash code:

1. Load the `ash-framework` skill — it owns all Ash patterns and Iron Laws
2. Research: `mix usage_rules.search_docs "<topic>" -p ash -p ash_phoenix -p ash_postgres -p ash_authentication -p ash_oban`
3. Module lookup: `mix usage_rules.docs Ash.Resource`
4. Generators: `mix ash.gen.resource`, `mix ash.codegen`, `mix ash.gen.domain`

Ash is a complement to Phoenix/Ecto — LiveView, security, and OTP Iron Laws still apply. For data access, prefer Ash actions via domain code interfaces over direct `Repo` calls.
```

### TIDEWAVE_SECTION (if Tidewave detected)

```markdown
## Tidewave — Use MCP tools

PREFER these over file-based alternatives:
- `mcp__tidewave__get_docs` — Fetch docs
- `mcp__tidewave__project_eval` — Evaluate in running app
- `mcp__tidewave__execute_sql_query` — Database queries
```

## Placeholder Values

| Placeholder | Source | Example |
|-------------|--------|---------|
| `{DATE}` | Current date | 2026-02-05 |
| `{PHOENIX_VERSION}` | `grep phoenix mix.exs` | 1.8.3 |
| `{ECTO_VERSION}` | `grep ecto mix.exs` | 3.13.5 |
| `{OPTIONAL_STACK}` | Detected optional deps | , Oban, Tidewave |
| `{OBAN_SECTION}` | If oban in deps | Include Oban section |
| `{OBAN_PRO_SECTION}` | If oban_pro in deps | Include Pro warning |
| `{ASH_SECTION}` | If ash in deps | Include Ash warning |
| `{TIDEWAVE_SECTION}` | If tidewave in deps | Include Tidewave section |

## Detection Commands

```bash
# Phoenix version
grep -oP '{:phoenix.*"~> \K[0-9.]+' mix.exs 2>/dev/null || echo "?"

# Ecto version
grep -oP '{:ecto.*"~> \K[0-9.]+' mix.exs 2>/dev/null || echo "?"

# Optional dependencies
grep -q ':oban,' mix.exs && echo "oban"
grep -q ':oban_pro,' mix.exs && echo "oban_pro"
grep -q ':ash,' mix.exs && echo "ash"
grep -q ':tidewave,' mix.exs && echo "tidewave"

# Project size (for greenfield detection)
find lib -name "*.ex" 2>/dev/null | wc -l
```

## Marker Format

**Start marker**: `<!-- ELIXIR-PHOENIX-PLUGIN:START -->`
**End marker**: `<!-- ELIXIR-PHOENIX-PLUGIN:END -->`

Content between markers is fully replaceable by `--update`.
Content outside markers is NEVER modified.