---

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 diff
• profile (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.md
• goal.md
• docs/project-memory/PLANS.md
• docs/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 lines
• goal.md exists and stays short enough to read every session
• docs/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:

• templates/AGENTS.md.template
• templates/goal.md.template
• templates/settings.json.template
• templates/project-memory/PLANS.md.template
• templates/project-memory/CONTINUITY.md.template
• templates/state/decisions.md.template
• templates/rules/project-rules.md.template

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 interaction
• allowed-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

• references/permission-presets.md — safe permissions blocks for .Codex/settings.json
• references/setup-policy.md — the inspect → plan → apply → verify policy in detail
• examples/before-after-structure.md — what a repo looks like before and after --apply

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 exists
• scripts/verify_setup.py — runs the post-apply checks
• scripts/merge_templates.py — merges a template into an existing file without overwriting

These are intentionally small. Read them before running.