2 · Project constitution

A CodeCanyon app is unfamiliar vendor code. The constitution is the small set of files that tells every AI tool what this project is, how to behave, and what never to touch — loaded automatically at the start of every session so the agent never starts blind.

The three files (and who reads them)

flowchart LR
  A["AGENTS.md<br/>cross-tool constitution<br/>(committed)"]
  C["CLAUDE.md<br/>thin pointer → AGENTS.md<br/>(committed)"]
  L["CLAUDE.local.md<br/>personal env + secrets refs<br/>(gitignored)"]
  C -->|points to| A
  A -.read by.-> Tools["Claude Code · Cursor · Codex · Gemini · others"]
  L -.personal overlay.-> Claude["your Claude Code session"]

File	Committed?	Role
AGENTS.md	✅	The canonical contract. Tool-agnostic. Tech stack, conventions, safety rules, the read-set. Every modern agent reads it.
CLAUDE.md	✅	A thin pointer that says “read AGENTS.md first,” plus any Claude-specific notes. Keeps a single source of truth.
CLAUDE.local.md	❌ gitignored	Personal: your local URL, server IPs, zone IDs, credential-store references. Differs per developer; never in git.

Why AGENTS.md as the canonical file

Older guides put everything in CLAUDE.md. The hybrid here promotes AGENTS.md to the canonical contract because it’s the emerging cross-tool standard — Cursor, Codex, Gemini, and Claude Code all read it. CLAUDE.md becomes a one-line redirect so you never maintain two copies that drift.

Step 1 — The onboarding interview (5 min)

Before writing files, gather context. Ask (or have the agent ask) and record the answers:

• Business: What does the app do? Who’s the customer? What’s the monetization (tiers, one-time, subscription)?
• Vendor: Which CodeCanyon item / vendor family (Froiden, LiquidThemes, WorkDo, InfyOm, IqonicDesign, other)? This predicts gotchas later.
• Stack: Laravel version, frontend (Livewire/Alpine/Vue), CSS (Tailwind/Bootstrap), auth (Sanctum/Passport), DB.
• Infra: Where does it deploy? Domain(s)? Staging URL? Hosting provider?
• Integrations: Stripe? Mail provider? Anything with secrets?

These answers populate the files below.

Step 2 — AGENTS.md (the contract)

Inspect the project first so the stack section is accurate:

head -30 composer.json     # Laravel version, PHP req, packages
head -20 package.json       # frontend deps
ls routes/ && ls database/migrations/ | wc -l

Then write AGENTS.md at the repo root. The kit ships a complete version; the essential shape:

# AGENTS.md — <AppName>

> Cross-tool constitution. Every AI agent (Claude Code, Cursor, Codex, Gemini) reads this first.

## What this is
<AppName> — a <SaaS / marketplace / directory> built on a CodeCanyon Laravel base (<vendor family>).

## Read first (the read-set)
1. This file (AGENTS.md).
2. `.claude/rules/` — behavioral + reference rules (auto-loaded).
3. `CLAUDE.local.md` — personal env (if present, gitignored).
4. `_CUSTOMIZATIONS.md` — log of every deviation from vendor code.

## Tech stack
- Laravel <version> (PHP ^<version>), <Livewire/Alpine/Vue>, <Tailwind/Bootstrap>, MySQL, <Sanctum/Passport>.

## Conventions
- Custom migrations use a `_zaj` suffix; never edit vendor migrations (overwritten on update).
- Wrap in-place vendor edits with `ZAJ:BEGIN` / `ZAJ:END` markers; net-new files start with `ZAJ:FILE`.
- Use `gh` for all GitHub operations.

## Safety rules (non-negotiable)
- **Tinker:** never create/update/delete records via `php artisan tinker` without explicit approval; prefer direct SQL reads.
- **Vendor files:** never modify `vendor/`; document deviations in `_CUSTOMIZATIONS.md`.
- **Migrations:** guard with `Schema::hasTable()/hasColumn()`; never `migrate:fresh|wipe|reset` on shared data.
- **`.env`:** always double-quote values (`DB_PASSWORD="p@ss#w&rd"`); special chars truncate unquoted.
- **Post-change:** after any installer/deploy/migration, run `git diff --name-only` and report before committing.
- **Secrets:** store in a secrets manager or the gitignored credentials file — never echo secret characters into a session.

Commit it: git add AGENTS.md && git commit -m "Add AGENTS.md cross-tool constitution".

Step 3 — CLAUDE.md (thin pointer)

Keep it short so there’s no drift:

# CLAUDE.md — <AppName>

> Single source of truth lives in **AGENTS.md** — read it first.
> This file holds only Claude-specific notes to avoid cross-tool drift.

## Claude-specific notes
- Read `~/.claude/commands/deploy-codecanyon.md` at session start — orchestration + safety rules apply whether or not the skill is invoked.
- `CLAUDE.local.md` (gitignored) holds personal/machine notes.

Step 4 — CLAUDE.local.md (personal, gitignored)

# CLAUDE.local.md — Personal (NOT committed)

## My environment
- Local URL: http://<app>.test
- DB GUI: TablePlus

## Infra
- Zone ID: <your-zone-id>      Server IP: <your-server-ip>
- DNS token env var: $CF_API_TOKEN
- Hosting: <provider> · root: /home/<user>/domains/<domain>/public_html

## Credentials
- Stored in: <1Password vault / credentials file path>
- ⚠️ When writing passwords to `.env`, always double-quote them.

Then gitignore it and confirm:

grep -q "CLAUDE.local.md" .gitignore || echo "CLAUDE.local.md" >> .gitignore
git check-ignore CLAUDE.local.md   # → CLAUDE.local.md

Verify

Start a fresh agent session in the project. Without being told, it should reference the stack/conventions — proof it read AGENTS.md. If not, confirm the files are at the repo root and restart the session.

Gate

✅ AGENTS.md + CLAUDE.md committed, CLAUDE.local.md created and gitignored, interview answers recorded. → Continue to Claude config.