| name | setup-project |
| description | Initializes or audits Codex project configuration. Use manually to create or update AGENTS.md, goal.md, docs/project-memory, .Codex/skills, .Codex/agents, .Codex/hooks, .Codex/rules, and settings files after inspecting the repository. Manual use only via /setup-project. |
| disable-model-invocation | true |
| argument-hint | [--dry-run|--apply] [profile] |
Setup Project
Purpose
Initialize or audit the Codex project configuration for the current repository.
This skill never overwrites existing files blindly. It always inspects first, proposes a diff, then applies changes only after explicit user approval.
The selling point is not "fast initialization" — it is "never destroys existing setup, no matter how many times you run it."
Operating Modes
--dry-run (default): inspect and propose changes only — no writes--apply: apply approved changes after the user confirms the diffprofile (optional): one of minimal, standard, full — controls how much project memory and .Codex/ structure is scaffolded
If the user runs /setup-project with no argument, treat it as --dry-run.
Workflow
Always follow this order. Do not skip steps.
1. Inspect
Read whatever already exists. Do not assume a fresh repo.
AGENTS.mdgoal.mddocs/project-memory/PLANS.mddocs/project-memory/CONTINUITY.md.Codex/settings.json.Codex/settings.local.json.Codex/skills/.Codex/agents/.Codex/hooks/.Codex/rules/.Codex/state/package.json / pyproject.toml / Cargo.toml / go.mod etc. — for project type detection.gitignore — to confirm .Codex/settings.local.json is ignored
If .Codex/ already exists with files, treat the project as "already set up" and switch to audit mode rather than scaffolding.
2. Detect
Identify:
- package manager (npm / pnpm / yarn / bun / uv / poetry / cargo / go)
- framework (Next.js / Nuxt / SvelteKit / Rails / Django / etc.)
- test command
- build command
- lint / typecheck command
- existing AI agent files (Cursor
.cursor/, Codex AGENTS.md, Gemini GEMINI.md)
3. Plan
Output a proposed diff in this shape:
[CREATE] goal.md
[CREATE] docs/project-memory/PLANS.md
[CREATE] docs/project-memory/CONTINUITY.md
[UPDATE] AGENTS.md (append "## Test commands" section, no overwrite)
[SKIP] .Codex/settings.json (already present, audit only)
[AUDIT] .Codex/settings.json → 3 broad permissions flagged
Show the user the actual content that will be written for every [CREATE]. For [UPDATE], show a unified diff.
4. Apply
Only after the user confirms. Apply changes one file at a time. For every existing file that will be modified:
- Make a backup at
<path>.bak.<timestamp> first
- Prefer append/merge over replace
- Never delete a file the user did not ask to delete
5. Verify
After applying:
- JSON parses cleanly (
.Codex/settings.json, .Codex/settings.local.json)
- No duplicate permission rules
- No broad/dangerous permissions (
Bash(*), unrestricted Write)
- No secrets in
.Codex/settings.json (it is shared)
AGENTS.md length under ~200 linesgoal.md exists and stays short enough to read every sessiondocs/project-memory/PLANS.md and docs/project-memory/CONTINUITY.md exist for standard / full.Codex/settings.local.json is in .gitignore- Expected directory tree exists for the chosen profile
If any check fails, report it and offer a follow-up fix — do not silently re-edit.
Profiles
minimal
AGENTS.md
goal.md
.Codex/settings.json
.Codex/settings.local.json.example
standard (default)
Adds:
docs/project-memory/{PLANS,CONTINUITY}.md
.Codex/state/decisions.md
.Codex/rules/project-rules.md
.Codex/hooks/README.md # docs only — hooks NOT enabled
full
Adds starter skills under .Codex/skills/ (e.g. project-health/, update-memory/, write-spec/). Hooks remain disabled by default. Enabling hooks requires a separate explicit step — see references/setup-policy.md.
Templates
Use templates from this skill folder, not from memory:
Safety Rules
These are non-negotiable.
- Never overwrite an existing file without showing a diff first.
- Prefer appending or merging over replacing.
- Create
.bak.<timestamp> backups before any destructive edit.
- Do not add broad Bash permissions like
Bash(*) or Bash(rm *).
- Do not write secrets, API keys, or per-user paths into
.Codex/settings.json (it is shared with the team).
- Per-user / machine-local config goes in
.Codex/settings.local.json only.
- Confirm
.Codex/settings.local.json is in .gitignore before writing anything to it.
- Keep
AGENTS.md short. Push detailed procedures into skills, rules, or references.
- Do not enable hooks automatically. Hooks execute shell commands — they need explicit user opt-in.
Role Separation
Do not duplicate content across these files. Each has a distinct job.
| File | Role | Put here | Do NOT put here |
|---|
goal.md | North Star | The repo's enduring goal and decision rule | Task plans, implementation notes, churn |
AGENTS.md | Always-loaded cross-agent context | Project summary, top commands, hard rules | Long procedures, rarely-used rules |
docs/project-memory/PLANS.md | Durable plan | Milestones, current phase, scoped priorities | Session transcript, raw logs |
docs/project-memory/CONTINUITY.md | Session handoff | Current state, next actions, verification status | Permanent design rules |
.Codex/skills/ | Procedures loaded on demand | PR creation, deploy checks, spec writing | Always-on rules |
.Codex/rules/ | Reference rules | UI rules, API conventions, bans | Anything needed every turn |
.Codex/state/ | Agent-local state | Tool-specific state such as decisions or scratch handoff | The canonical plan or continuity ledger |
Gotchas
See references/common-gotchas.md for:
disable-model-invocation and auto-discovery interactionallowed-tools is permission expansion, not restriction- Why
version and priority frontmatter keys are not used
- Why
goal.md, PLANS.md, and CONTINUITY.md must not duplicate each other
- Why hooks should not be enabled at scaffold time
References
Scripts
When the situation is mechanical (JSON parsing, file diffing, structure verification), prefer running the helper scripts over freehand work:
scripts/inspect_project.py — emits a JSON report of what currently existsscripts/verify_setup.py — runs the post-apply checksscripts/merge_templates.py — merges a template into an existing file without overwriting
These are intentionally small. Read them before running.
