ai-development-patterns: Instructions file for Codex

Agent Instructions

Task Tracking

Tasks live in .tasks/backlog.jsonl — an append-only JSONL file, one task per line, git-tracked. There is no daemon and no database: the file is the record and git is the history.

Do NOT use TodoWrite, TaskCreate, markdown TODO lists, or bd/beads — this repo migrated off beads on 2026-08-17.

A task's state is its LAST line. The file is append-only, so grep '"status": *"open"' also matches tasks that were later closed, over-reporting the open set. Always fold last-line-wins:

python3 -c "import json;last={};[last.__setitem__(t['id'],t) for t in map(json.loads,filter(str.strip,open('.tasks/backlog.jsonl')))];print('\n'.join(f\"{i}  {t['title'][:68]}\" for i,t in last.items() if t['status']=='open'))"

Close a task by APPENDING a new line with status set to closed; never edit or delete an existing line. Work discovered while doing another task gets its own line with discovered_from set to the parent id.

Schema: {id, title, status, blocks[], depends_on[], spec_ref, created, priority, description, discovered_from?} — status is open or closed; priority is 1 (most urgent) to 4; a task is ready when every id in depends_on is closed. Issue ids keep their original beads form so existing commit messages still resolve.

The full beads history is archived verbatim at .tasks/beads-archive.jsonl.

Pattern Adoption Evaluation

Run model-backed pattern-adoption research only through the repository-local $evaluate-pattern-adoption skill in an interactive, signed-in local evaluator client (Codex today). Never run it in GitHub Actions, expose evaluator API keys to the repository, or bypass either the exact plan approval or the separate draft-PR publication approval. Use no more than three read-only research subagents at once, keep the root task as the sole writer, and use a fresh read-only verifier for every batch. GitHub Actions is limited to deterministic validation and read-only link/content checks for this capability.