AGENTS.md

Scope

This file applies to the entire repository.

Before starting substantial work, read the roadmap that matches the task:

Updating the relevant roadmap is part of the definition of done.

Do not finish a task and leave its roadmap stale.

Required behavior:

if you complete or materially change implementation progress, update docs/implementation-roadmap.md in the same change
if you add, remove, or materially revise inbox Markdown test cases or test-plan documents, update docs/tests/inbox/ROADMAP.md in the same change
when a test-plan document is created, update document progress
when a test case is written, update authored-case tracking and pending backlog
when a planned item is no longer needed, mark it as removed or deferred instead of silently dropping it

For docs/tests/inbox/:

organize by folder plus README.md
do not use numeric test IDs
use stable case slugs and keep the roadmap synchronized with the actual files on disk

For skills/:

treat this directory as project-local Codex skill packages, not general documentation
use skills to package reusable agent workflows, constraints, and bundled assets so other agents can use them without rediscovering repository context
keep each skill self-contained around SKILL.md; add agents/openai.yaml and bundled assets only when they directly support real invocation
if a skill depends on an executable or other runtime asset, prefer bundling the required artifact with the skill instead of relying on ad hoc rebuild instructions as the primary workflow
when updating an existing skill, keep SKILL.md, agents/openai.yaml, and bundled assets consistent with each other
if you add or materially change a project skill, update docs/implementation-roadmap.md in the same change