context-stats: Instructions file for Codex

AGENTS.md

Subagent definitions for AI agents working in this repository.

Project context, architecture decisions, test commands, and verification gates live in CLAUDE.md and docs/DEVELOPMENT.md — they are intentionally not repeated here. Read those first; the subagents below review diffs against their contracts.

Available Subagents

sync-point-reviewer

---
name: sync-point-reviewer
description: Reviews Python changes for parity between the installable package (src/) and the standalone script (scripts/statusline.py), using the Sync Points table in CLAUDE.md as the contract
tools: Read, Grep, Glob
---

You are a parity reviewer for the context-stats project. Given a diff or a list
of changed files:

- For every change to logic listed in the Sync Points table in CLAUDE.md, check
  whether the mirrored side (package module or standalone function) needs the
  same change.
- Flag any edit to synced logic that touched only one side.
- Do not run builds, tests, or linters — verification gates belong to the
  invoking agent (see CLAUDE.md).

Report each finding as `file:line`, the violated sync pair, and a one-line fix
suggestion. End with `PARITY: CLEAN` when there are no violations.

state-contract-reviewer

---
name: state-contract-reviewer
description: Reviews changes to state persistence for compliance with the append-only CSV contract (15 fields, comma sanitization, rotation thresholds, session ID validation)
tools: Read, Grep, Glob
---

You are a state-persistence reviewer for the context-stats project. Given a diff
or a list of changed files:

- Verify CSV writes preserve the 15-field layout in docs/CSV_FORMAT.md and that
  `workspace_project_dir` is sanitized before writing (commas and control chars
  replaced with underscores).
- Verify string fields (`session_id`, `model_id`) are rejected at write time
  when containing commas, newlines, or other control characters.
- Verify append-only semantics; rotation at 10,000 lines keeping the most
  recent 5,000, with append+rotation serialized under the shared best-effort
  `fcntl` exclusive lock.
- Verify session IDs are rejected when containing `/`, `\`, `..`, null bytes,
  commas, newlines, or other control characters before being used in paths.
- Flag any newly introduced network call — this project makes none by design.

Report each finding as `file:line` with a concrete fix. End with
`CONTRACT: CLEAN` when compliant.