Codex Starter Kit

01-setup.md

Setting Up Codex

Prerequisites

• Codex installed
• Recommended: install Codex via Homebrew for easy updates
• GitHub CLI authenticated (gh auth login)
• Copy config.toml to ~/.codex/config.toml

Quick Start

1. Create AGENTS.md at your repo root with project rules and collaboration preferences
2. Add reusable skills in .codex/skills/

File Structure

your-repo/
├── AGENTS.md                    # Repository rules and working conventions
└── .codex/
    └── skills/
        ├── pr/
        │   └── SKILL.md         # PR workflow
        └── review/
            └── SKILL.md         # Review workflow

Skills

Codex skills are workflow playbooks stored at .codex/skills/<name>/SKILL.md.

Starter skills:

• review.md
• pr.md

Use skills for process/checklists; keep policy in AGENTS.md.

Plan Mode

Use plan mode for larger changes that benefit from explicit steps before implementation.

Git Worktrees

Work on multiple branches in parallel:

git worktree add ../your-repo-2 feat/other-task

Run a separate Codex session in each worktree.

02-agents.md

Project Rules

Tooling

• Prefer the repository’s task runner/scripts (make, npm, pnpm, etc.) over ad-hoc commands.
• Use documented project commands when available.

Workflow

• Start from latest main before new work.
• Read relevant files before editing.
• Keep changes scoped, minimal, and well-engineered.
• Prefer editing existing files over creating new ones unless necessary.
• Do not guess; use concrete evidence (errors, logs, tests, snapshots, source) before changing code.
• Stop and ask if you encounter unexpected diffs or artifacts.

Commits

• Commit only when explicitly requested; do not auto-commit.
• Use the same Conventional Commit type for branch and commit:
  • Branch: <type>/*
  • Commit: type(scope): description
  • Allowed types: feat, fix, refactor, docs, test, chore
• Keep commit subject lines under 72 characters.

Code

• Choose pragmatic solutions: simplest approach that solves the real problem with low maintenance overhead.
• Avoid unnecessary indirection; add abstractions only when they clearly improve clarity or reduce real duplication.
• Avoid workaround-only fixes; prefer root-cause solutions.
• No intentional tech debt unless explicitly justified and tracked with TODO(username):.
• Keep naming short and descriptive.
• Remove debug code before review/commit.

Validation

• Run required linting and tests after code changes.
• Run type checks/build when changing contracts, public types, or boundary behavior.
• Document any validation that could not run and why.

Testing

• Add tests for meaningful regression risk or critical behavior.
• Avoid redundant or trivial tests that add maintenance overhead.

Documentation

• Update documentation when behavior or contracts change.
• Match existing documentation style.
• Keep this file policy-only; keep procedural checklists in reusable skills/workflows.

Safety

• Never use destructive git/file operations unless explicitly requested.
• Do not revert or discard unrelated changes without approval.
• If you see unexpected changes, pause and confirm before proceeding.

Communication

• Ask when requirements are unclear.
• Capture decisions, trade-offs, and open questions.
• Be explicit about assumptions, risks, and next steps.

03-review.md

name	description
review	Run a scoped PR review workflow, apply high-confidence fixes, validate changes, and report merge readiness.

Review - PR Review & Validation

Follow repository policies in AGENTS.md. This skill defines review workflow and reporting format only.

Step 1: Confirm PR Context

• If on main, create a scoped feature branch.
• If already on a feature branch, continue there.
• Ensure PR context exists:
  • If a PR exists for the branch, review against it.
  • If no PR exists, continue review against main...HEAD and create PR only if requested.

Step 2: Run Review Passes (Parallel Mindset)

Scope:

• Recommend changes only in files modified by this PR.
• Read other files for context only.
• If a fix requires changes outside PR scope, stop and ask first.

Passes:

• Codebase consistency and reuse
• Clean code and maintainability
• Defensive coding and security risks
• Documentation and localization impact
• UX/accessibility consistency
• Dead code check (unused files/exports/helpers introduced by PR)

Step 3: Apply Fixes

1. Apply high-confidence fixes first.
2. Keep changes minimal and in scope.
3. Prefer existing patterns over new abstractions unless clearly beneficial.
4. Track skipped recommendations with rationale.

Step 4: Validate

• Run repository-required validation commands from AGENTS.md.
• Include lint, typecheck, and tests relevant to the change.
• If any required validation cannot run, record what and why.

Step 5: Commit and Push (Only If Requested)

• Do not auto-commit.
• If requested, follow repository commit conventions in AGENTS.md.

Step 6: Final Summary

Provide:

• Findings (ordered by severity, with file references)
  • high: bug, regression, security issue, data-loss risk
  • medium: maintainability, performance, accessibility risk
  • low: style, minor cleanup, documentation polish
• Changes Applied
• Skipped (with rationale)
• Validation (pass/fail)
• Unable to Validate (with reason)
• Merge Readiness (ready vs another pass needed)

04-pr.md

name	description
pr	Prepare, validate, and create or update pull requests with GitHub CLI using repository policies.

PR Workflow

Follow these steps in order. Do not skip or reorder.

Follow repository policies in AGENTS.md (and equivalent policy files, if present). This skill defines PR preparation flow and output format only.

Step 1: Confirm Readiness

• Confirm with the user that implementation is complete and ready for PR prep.

Step 2: Validate

• Run required project validations (typically lint, typecheck, tests).
• Record pass/fail for your execution summary.
• Record any validation that could not run, with reason.

Step 3: Commit and Push (Only If Requested)

• Stage and commit only when explicitly requested.
• Follow project commit conventions (typically Conventional Commits).
• Push the branch when requested.

Step 4: Review Full Changeset

• Review main...HEAD (or the correct base) to understand final scope.
• Ensure PR summary reflects the real user/domain value, not incidental refactors.

Step 5: Draft PR Content

• Read .github/pull_request_template.md when available.
• Use concise, factual title/body.
• Include:
  • What changed
  • Why it changed
  • Linked issues/tickets
• Add screenshots for UI changes when relevant.
• Do not include routine validation logs in PR body by default (CI is the source of truth).
• If required template fields, issue links, or UI screenshots are missing, stop and ask.

Step 6: Confirm Before PR Mutation

• Wait for explicit user confirmation before creating/updating the PR.

Step 7: Create or Update PR

• Check for existing PR for current branch:
  • gh pr view --json number,url,title,body --head <branch>
• If PR exists:
  • Preserve existing body content.
  • Patch only requested sections; do not overwrite the whole body unless explicitly asked.
  • gh pr edit <number-or-url> --title "<title>" --body-file /tmp/pr-body.md
• If PR does not exist:
  • gh pr create --title "<title>" --body-file /tmp/pr-body.md --base <base> --head <branch>
• Re-check final PR state:
  • gh pr view --json number,url,title,body --head <branch>

Step 8: Report Result

Provide:

• PR Title
• PR Body (final text used)
• PR Link (URL)
• Validation (what passed/failed, and anything not run)
• Open Items (missing info, blockers, follow-ups)

05-config.toml

personality = "pragmatic"
model = "gpt-5.3-codex"
reasoning_effort = "medium"
response_verbosity = "concise"

[projects."/path/to/active/repos"]
trust_level = "trusted"

[notice.model_migrations]
"gpt-5.2-codex" = "gpt-5.3-codex"