| File | Purpose |
|---|---|
AGENTS.md |
Durable instructions the coding agent loads automatically |
SPEC.md |
Product and technical requirements and acceptance criteria |
ROADMAP.md |
Ordered outcomes, dependencies, risks, and exit criteria |
TASKS.md |
Current actionable work and validated status |
.agents/skills/ |
Reusable workflows Codex can invoke |
docs/ |
Reference material loaded only when requested or linked |
-
Install this repository's global instructions, configuration, rules, and reusable skills.
-
Inspect the real repository, branch, worktree, architecture, runtime paths, and existing validation.
-
Put durable project conventions and boundaries in
AGENTS.md. -
Define observable requirements, non-goals, and acceptance criteria in
SPEC.md. -
Order outcomes, risks, exit criteria, and validation in
ROADMAP.md. -
Break the current phase into reviewable work in
TASKS.md. -
Use
$ai-project-managerto produce a requirement-linked plan with automated and manual validation. -
Stop for plan approval when the user reserved that checkpoint.
-
Implement one approved phase, run focused checks, and inspect the diff.
-
Run the complete local gate and update task status only after it passes.
-
Use
$pr-readinessto run built-in Codex review with the matching scope:codex review --uncommitted codex review --base <target-branch> codex review --commit <sha>
Choose uncommitted work, a branch against its actual target, or one commit. Cover both committed and uncommitted work when the request includes both.
-
Verify every finding against the current diff. Fix only actionable defects, rerun affected validation, and repeat review of the affected scope until no actionable findings remain. Document verified false positives without changing correct code. A review-mode Codex instance reports findings directly and must not launch another nested review.
-
Commit validated, task-owned batches as work progresses under the global standing authorization. Push and open a ready-for-review pull request only when authorized. Create or leave a draft only when the user explicitly requests one. If known gates remain, stop before opening the pull request and report the blockers.
-
Require a completed Codex review loop, CI validation, applicable security checks, and a fresh independent review on the latest commit.
-
Fix or explain every review item, resolve completed threads, and repeat the checks after every push.
-
Complete and document required manual testing on the real target environment.
-
Merge only after the final diff, planning documents, CI, security checks, reviews, threads, and manual tests are clean.
Establish the security checks that apply to the repository instead of adding irrelevant gates:
- Enable secret scanning and push protection where available.
- Configure Dependabot for every package ecosystem and GitHub Actions.
- Run dependency review when dependency manifests can change.
- Configure CodeQL for every language in the repository that CodeQL supports.
- Document accepted exceptions with a reason, owner, and review date.
Record the problem, approach, important decisions, exact automated checks, manual tests, screenshots for visible changes, limitations, skipped validation, and follow-up work.
Do not rely on a coding agent discovering arbitrary documents by filename.
Reference supporting documents from AGENTS.md, a selected skill, or the task
prompt. Keep the specification, roadmap, tasks, and implementation synchronized
when requirements or architecture change.