Phase 1 · Set up the AI System

Before you write a single line of customization, you set up the AI System — the agent operating system that makes every later phase faster, safer, and reproducible. This is Phase 1 of the playbook, and it runs once per machine plus once per app.

Why this is Phase 1, not an afterthought

A CodeCanyon app is someone else’s code. You will be reading unfamiliar vendor source, making surgical edits you must be able to find again at the next vendor update, and running destructive-capable commands (migrations, seeders, deploys). An agent that boots with a written constitution, the right permission mode, and a library of rules turns that risky work into a guided, gated, recoverable process. Set it up first; coast on it for the other ten phases.

What “the AI System” actually is

It’s a small set of plain-text files committed to the repo (plus a couple of gitignored personal ones) that any AI coding tool reads on startup:

• A constitution (AGENTS.md) — the one cross-tool contract every agent reads first.
• A thin pointer (CLAUDE.md) and a personal scratchpad (CLAUDE.local.md, gitignored).
• Permission modes (.claude/settings*.json) — strict / medium / yolo, plus a hard-block hook that no mode can override.
• Rules (.claude/rules/) — behavioral (feedback_*) and reference (reference_*) knowledge, seeded from a shared template set.
• Skills (.claude/skills/) — reusable procedures, including the deployment orchestrator.
• IDE wiring — .mcp.json (MCP servers), .cursor/rules/, optional Gemini/Codex mirrors.

flowchart TD
  Boot["Agent session start"] --> AG["AGENTS.md<br/>(cross-tool constitution)"]
  AG --> CL["CLAUDE.md (thin pointer)"]
  AG --> CLL["CLAUDE.local.md<br/>(gitignored personal notes)"]
  Boot --> S[".claude/settings.json (committed)"]
  Boot --> SL[".claude/settings.local.json<br/>(gitignored · permission mode)"]
  SL --> Hook["PreToolUse hook<br/>block-destructive.sh"]
  Boot --> R[".claude/rules/<br/>feedback_* · reference_* · project_*"]
  Boot --> SK[".claude/skills/<br/>deploy orchestrator + stack skills"]
  Boot --> MCP[".mcp.json + .cursor/rules/"]

The flow at a glance

0 / 6 done Reset

1. 1 Machine setup (once per machine)
   Authenticate gh, register your MCP servers, install the permission-mode switcher and the deploy orchestrator. See Machine setup.
2. 2 Write the project constitution
   AGENTS.md + thin CLAUDE.md + gitignored CLAUDE.local.md, via a short onboarding interview. See Project constitution.
3. 3 Configure Claude permissions + hooks
   Commit .claude/settings.json, pick a permission mode, wire the destructive-command and vendor-edit guards. See Claude config.
4. 4 Seed rules + install skills
   Seed .claude/rules/ from the template set, drop the stack skills and deploy orchestrator into .claude/skills/, then restart. See Rules & skills.
5. 5 Wire the other IDEs
   .mcp.json (Laravel Boost), .cursor/rules/000-boot.mdc, optional Gemini/Codex mirrors. See Cursor & other IDEs.
6. 6 Verify + gate
   Run the verification checklist and confirm the Phase 1 gate before moving to Phase 2. See Verify & gate.

Skip the typing — use the kit

Everything below ships as a copy-paste template kit so you don’t hand-author these files. The kit reproduces the full set — AGENTS.md, CLAUDE.md, the .claude/ tree (settings, rules, skills, hooks), .mcp.json, the Cursor boot rule, and a seed.sh that drops it all into place.

➡️ CodeCanyon AI-System Kit — download it, run seed.sh, fill in the placeholders, restart your session.

The sub-pages explain what each file does and why so you can adapt it; the kit gives you the what ready-made.

Sub-steps

1. Machine setup — once per machine
2. Project constitution — AGENTS.md / CLAUDE.md
3. Claude config — settings, permission modes, hooks
4. Rules & skills — seed rules, install skills
5. Cursor & other IDEs — MCP + multi-tool wiring
6. Verify & gate — checklist + the gate to Phase 2

The committed vs gitignored split (read this once)

The single most important concept in this phase: which files travel with the repo and which stay on your machine.

| File | Committed? | Why | |---|---|---| | AGENTS.md, CLAUDE.md | ✅ Yes | The shared contract — every teammate and every tool reads it | | .claude/settings.json | ✅ Yes | Project-wide settings (e.g. disabled MCP servers) everyone should share | | .claude/rules/** | ✅ Yes | Team-shared behavioral + reference rules — travel on clone | | .claude/skills/** | ✅ Yes | Reusable procedures, including the deploy orchestrator | | .mcp.json | ✅ Yes | Project MCP servers (e.g. Laravel Boost) | | .claude/settings.local.json | ❌ Gitignored | Personal permission mode — a per-developer friction choice, not a team rule | | CLAUDE.local.md | ❌ Gitignored | Personal progress notes, machine-specific paths, scratch | | Secrets / .env* | ❌ Gitignored | Never in the repo — use a secrets manager |

Keep this split honest and the rest of the phase is mechanical.