3 · Project constitution

TL;DR

Objective — write the constitution: the small set of files (AGENTS.md, CLAUDE.md, CLAUDE.local.md) 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.

Steps at a glance:

1. Run the onboarding interview — Before writing files, gather context. The agent should inspect both the stack and the app surface first, then pre-fill evidence-based answers for the user to confirm or correct.
2. Write AGENTS.md (the contract) — Write AGENTS.md at the repo root using the auto-detected stack so the tech-stack section is accurate.
3. Write CLAUDE.md (thin pointer) — Keep CLAUDE.md short so there’s no drift — it only redirects to AGENTS.md plus any Claude-specific notes.
4. Create CLAUDE.local.md (personal, gitignored) — This file holds the per-developer environment — local URL, server IPs, zone IDs — and only references credentials, never the secrets themselves.
5. Pick a credential store — CLAUDE.local.md only references credentials; the secrets themselves live in one of three stores.
6. Operator Provisioning Gate — One upfront 👤 step that gathers everything a human must supply across the whole playbook — accounts, API keys, license codes — and stores it in op:// now, so later phases read non-blocking instead of stalling mid-task.
7. Verify the constitution loads — Confirm a fresh agent actually reads the contract before declaring this step done.
8. Commit the constitution (C3) — commit the constitution files on develop while keeping the local overlay ignored, so every later agent session has a stable project contract.

User part + done-when

👤 User part — only a person can answer the onboarding interview: what the app does, the customer, the monetization, the CodeCanyon vendor family, the infra/domains, and which integrations hold secrets. The agent auto-detects the rest from the codebase.

Done when AGENTS.md + CLAUDE.md are written on disk, CLAUDE.local.md is created and gitignored, the onboarding interview (Q1–Q31 + summary) is recorded and confirmed, a fresh agent session references the stack/conventions unprompted, and C3 is committed on develop.  ·  ⏱ ~20 min  ·  🔀 user answers the interview, agent writes the files. See git policy.

Background

A CodeCanyon app is unfamiliar vendor code. The constitution is the committed contract plus a personal overlay — each layer has a distinct reader and git fate:

flowchart TB
  subgraph committed["Committed (team-shared)"]
    A["AGENTS.md<br/>canonical contract"]
    R[".claude/rules/*.md<br/>seeded in Rules & skills"]
    C["CLAUDE.md<br/>thin pointer → AGENTS.md"]
  end
  subgraph personal["Personal (gitignored)"]
    L["CLAUDE.local.md<br/>IPs, zone IDs, credential refs"]
  end
  C --> A
  A --> R
  Tools["Claude Code · Cursor · Codex · Gemini"] --> A
  Tools --> R
  Tools --> C
  Tools --> L

File	Committed?	Role
AGENTS.md	✅	The canonical contract. Tool-agnostic. Tech stack, conventions, safety rules, the read-set. Every modern agent reads it.
.claude/rules/	✅	Behavioral + reference rules (seeded in Rules & skills). Loaded at session start.
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: 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 there are never two copies that drift.

Per-project (this step) vs workspace-global (machine setup)

Machine setup is once per computer — gh, MCP servers, op, global skills. This step is once per CodeCanyon project — AGENTS.md, CLAUDE.md, and CLAUDE.local.md live in this repo root and travel with the clone. Do not put project domains, SSH aliases, or app-specific safety rules in ~/.claude/CLAUDE.md; put them here.

Verify before overwrite

If you used the kit + seed.sh path, AGENTS.md and CLAUDE.md may already exist. Read them first — update placeholders from the interview; do not blind-replace a seeded constitution. Same idempotency pattern as machine setup: verify, then change only what the interview overrides.

Bootstrap git vs Code & repository setup

Create the project already wrote bootstrap .gitignore, ran git init, promoted vendor with the completeness gate, and committed the pristine vendor baseline (C1) on author/v* + tag (develop at the same commit). .vscode/ was written on disk after C1 and committed at C2 (machine setup).

Code & repository setup adds the GitHub remote, merges full ignore rules, and pushes — it does not recreate the vendor import. Write constitution files during this step; commit them as C3 on develop. Never commit secrets, .env*, or a mistaken vendor/ path.

Alternative · kit + seed.sh

Use this instead of hand-authoring constitution through Cursor wiring file-by-file (Claude config, Rules & skills, and Cursor & other IDEs are included in the same drop).

1. Fetch + install in one command — from your project root (the app folder with the vendor tree from Create the project). No repo clone, no manual download:

   curl -fsSL https://library.zajapps.com/kits/codecanyon-ai-system.tgz | tar -xz
   bash seed.sh   # renames dot-* → real dotfiles; materializes project_context.md

   The tarball unpacks its contents straight into the current directory, then seed.sh wires them up. Prefer to inspect first? Browse the file map or MANIFEST, and read seed.sh after extracting — before you run it.

2. Fill placeholders — run the onboarding interview below (or answer the kit’s printed prompts) so AGENTS.md and project_context.md match this app.

3. Pick a permission mode — ./.claude/claude-mode/bin/set-claude-mode.sh medium (see Claude config).

4. Restart your agent session, then continue to Verify & gate.

What seed.sh lays down in one pass: AGENTS.md, CLAUDE.md, CLAUDE.local.md.example, the full .claude/ tree (settings, rules, skills, hooks, mode switcher), .mcp.json, and .cursor/ mirrors. The individual pages remain the reference if you need to change one subtree later.

Steps

1. Run the onboarding interview

Before writing files, gather context. The agent should inspect both the stack and the app surface first, then pre-fill evidence-based answers for the user to confirm or correct.

Who does this

🔀 User + Agent — the agent runs the auto-detection commands. 👤 User answers the human-only business/vendor/infra questions.

1. Auto-detect the stack from the repo.

   head -30 composer.json     # Laravel version, PHP req, key packages
   head -20 package.json      # frontend deps (Livewire / Alpine / Vue / Tailwind)
   ls routes/                 # route files → surface area
   ls -d app/Http/Controllers/*/ 2>/dev/null   # controller organization
   ls database/migrations/ | wc -l             # migration count → deploy timeout risk
   # Expected: Laravel version, frontend deps, route/controller layout, migration count

   • ✅ The auto-detected Laravel version, frontend, CSS, auth, and DB are captured for the interview.

2. Inspect what the app actually does before asking business questions. Generic interview choices miss the mark on CodeCanyon apps. Read the models, migrations, modules, and route groups so the agent can pre-fill the app’s feature surface and monetization model from evidence.

   find app/Models -maxdepth 1 -type f -name '*.php' 2>/dev/null | sed 's#app/Models/##' | sort | head -80
   find Modules app/Classes -maxdepth 2 -type d 2>/dev/null | head -80
   rg -n "Plan|Subscription|Order|Coupon|Module|Trial|Payment|Invoice|Warehouse|Helpdesk|Chat" \
     app database routes Modules 2>/dev/null | head -120
   # Expected: feature areas, billing/plan objects, module system, and route groups are visible enough to pre-fill the interview

   • ✅ The agent can say, “I see subscription plans / orders / coupons / modules / feature areas X-Y-Z; confirm or correct.”
   • ✅ Human-only questions stay human-owned, but they are grounded in the actual codebase instead of hardcoded generic options.

3. Research the CodeCanyon listing when the user supplies the item URL (optional but high leverage for vendor family, docs links, and install quirks).

   👤 Ask: “What is the CodeCanyon URL for this script?” Then fetch the listing and extract name, author, Laravel/PHP requirements, feature bullets, documentation URL, demo URL, and recent changelog notes. Summarize back for confirmation.

   • ✅ Listing summary confirmed by the user.
   • ✅ Online documentation / support URLs captured for a ## Vendor documentation section in AGENTS.md (bundled PDFs/HTML in the ZIP are catalogued later in Code & repository setup).

4. Auto-detect infra already on the machine before asking domain/hosting questions — present defaults the user can accept or override.

   echo "=== Auto-detect (workspace-global — from machine setup) ==="
   gh auth status 2>&1 | head -3
   git config --global user.name 2>/dev/null; git config --global user.email 2>/dev/null
   grep "^Host " ~/.ssh/config 2>/dev/null | grep -v '\*' || echo "No SSH Host aliases yet"
   [ -n "$CF_API_TOKEN" ] && echo "CF_API_TOKEN: set" || echo "CF_API_TOKEN: not set"
   command -v op >/dev/null && op vault ls >/dev/null 2>&1 && echo "1Password: OK" || echo "1Password: not ready"
   # Expected: gh auth, git identity, existing SSH aliases, Cloudflare token, op status visible before you ask infra questions

   • ✅ Detected GitHub identity, SSH aliases, and credential store status are shown as defaults in the infra questions below.

5. Answer the human-only questions and record them — they populate AGENTS.md, CLAUDE.local.md, project_context.md, and later Zaj-PROJECT.md. The agent asks conversationally (not as an unreadable wall); you answer; the agent writes every answer to _onboarding-summary.md (gitignored scratch) or your note app before drafting any committed file.

   Do not skip recording

   If an answer is “undecided” or “use defaults”, write that explicitly. Empty fields become wrong assumptions in Phase 4 (deploy.php) and Phase 6 (superadmin).

   A · App source (before the numbered bank)

   If this is a CodeCanyon project (default for this playbook) — 👤 the agent asks exactly:

   What is the CodeCanyon URL for this script? (e.g. https://codecanyon.net/item/[name]/[id])

   🤖 After you answer, the agent fetches the listing, summarizes name/version/author/stack/features/docs/demo/changelog, and you confirm accuracy. Bundled vendor PDFs/HTML are catalogued in Code & repository setup — online docs URL still belongs in the interview now.

   If NOT CodeCanyon — 👤 the agent asks exactly:

   What kind of project is this? (custom Laravel, GitHub clone, other framework)

   B · Business context (Q1–Q10 · 👤 USER only)

   #	Question
   1	What is the app/brand name for this deployment? (use the exact public name you want customers to see)
   2	What domain will it live on? (for example, your production domain)
   3	What type of product is this? (SaaS, marketplace, CMS, directory, tool, API, other)
   4	Brief one-line description of what it does? (e.g. “AI content generation platform”)
   5	Who is the target audience? (developers, businesses, consumers, enterprise, other)
   6	What region/language are you targeting? (global English, Arabic, multi-language, other)
   7	Any specific industry focus? (healthcare, education, finance, general, other)
   8	How will you charge users? (subscription, one-time, freemium, credits/tokens, other)
   9	Which payment gateway(s) do you want? (Stripe, PayPal, both, other)
   10	Do you need invoicing or tax compliance? (Stripe Tax, manual, merchant of record, none yet)

   Also capture for vendor CodeCanyon apps (feeds ## Vendor documentation) — required for every CodeCanyon project:

   Field	Question
   Vendor family	Which CodeCanyon vendor family? (Froiden, LiquidThemes, WorkDo, InfyOm, IqonicDesign, other)
   Listing URL	From step A — confirmed CodeCanyon item URL
   Docs URL	Online documentation URL from listing or author site
   Demo URL	Demo URL if listed (optional)
   Support URL	Author support / ticket URL if known (optional)

   C · Infrastructure (Q11–Q28 · 👤 USER; agent pre-fills from step 4)

   The agent runs step 4 first, presents a defaults table (GitHub account, git name/email, SSH hosts, Cloudflare, Atlas, Docker), and you may say “use defaults” for the whole row set. Then it asks only what auto-detect cannot know — using these exact prompts when relevant:

   #	Question
   11	Which GitHub account/organization should this repo live under? (personal account, org name, or create new)
   12	Repo visibility: private or public? (default: private)
   13	What git username and email for commits? (detected: [name] / [email] — keep or change?)
   14	What hosting provider will you use? (Hostinger, DigitalOcean, AWS, Hetzner, other)
   15	Already have servers? Or need to create staging + production? (If SSH hosts detected: “I see [list]. Which are for this project? Or need new ones?“)
   16	If existing: what are the server IPs? (auto-fill from SSH config when host matched)
   17	SSH access — reuse detected host alias, or set up from scratch?
   18	Non-production environment topology? (one staging, multiple staging/UAT/sandbox/client-demo targets, custom names like preview or qa, or none yet)
   19	Are you using Cloudflare? (If CF_API_TOKEN set: “Cloudflare already configured. Same account?“)
   20	If Cloudflare: is the domain already added to Cloudflare? (agent may look up zone ID via MCP)
   21	What email provider for transactional email? (SendGrid, Mailgun, Brevo, Hostinger SMTP, Titan, undecided)
   22	Do you need custom email addresses? (e.g. support@domain.com — already have / need to create / not needed)
   23	Database preference: MySQL or MariaDB? (default: MySQL)
   24	Database GUI preference? (TablePlus if installed, else phpMyAdmin, other)
   25	Use Atlas for schema management? (if installed: “Atlas detected — use it?” else skip / mysqldump)
   26	Use Bytebase for DB change tracking? (default: skip)
   27	Use Redis caching now? (default: skip — can add later)
   28	Use Sentry for error tracking? (default: yes if free tier — can add later)

   Server mapping (required — pairs with Phase 2 hard gate)

   After Q15–Q17, the agent seeds a candidate mapping from ~/.ssh/config, DNS/dig, and hosting MCP listings — then stops for explicit operator confirmation before writing CLAUDE.local.md or project_context.md.

   Environment	Record (after confirmation)
   Non-production target(s)	Environment key (staging-primary, qa, uat, client-demo, etc.) · URL/domain · SSH alias · IP · hosting username/order ID (if known)
   Production	Environment key (production) · URL/domain · SSH alias · IP · hosting username/order ID (if known)

   Discovery ≠ authorization

   Auto-detect and MCP listings are proposals only. Do not create DNS records, hosting sites, databases, or deploy targets until the operator confirms which IP/account/SSH alias belongs to each environment row in Zaj-PROJECT.md. When multiple hosting accounts exist, the machine-wide Hostinger MCP token may not cover this project’s servers — note per-project token, hPanel, or SSH fallback in CLAUDE.local.md.

   The agent must not assert conclusions about servers it cannot reach (“production isn’t reachable” / “X is the only VPS”) — ask, don’t guess.

   Integrations the agent may pre-fill from composer.json — 👤 you confirm or override:

   Topic	Confirm
   Stack	Laravel version, PHP requirement, frontend (Livewire / Alpine / Vue / Inertia), CSS (Tailwind / Bootstrap)
   Auth	Sanctum, Passport, JWT, Fortify, Breeze, Jetstream — what the repo actually uses
   Payments detected	Stripe, PayPal, Razorpay, Paddle, Cashier, etc. — match Q8–Q9
   Secrets	Which integrations hold live secrets today? (Stripe test+live keys, mail API, OAuth, webhooks)

   D · Team & workflow (Q29–Q31 · 👤 USER only)

   #	Question
   29	Solo developer or team? (affects branch strategy, PR workflow, credential conventions)
   30	Other AI tools alongside Claude Code? (Cursor, Copilot, Codex, Gemini — drives IDE mirror configs)
   31	Any deadline or timeline pressure? (urgent vs relaxed — prioritizes phase sequence and post-launch tracks)

   • ✅ Every row above has a recorded answer or explicit undecided / use defaults before step 6.

6. Compile the interview summary and get sign-off.

   🤖 Draft _onboarding-summary.md (or paste into chat). 👤 Review and correct — this is the gate before writing AGENTS.md.

   ## Project onboarding summary
   
   **App:** [Name] — [one-line description]
   **Source:** CodeCanyon ([Script Name] v[X.X] by [Author]) / Custom / GitHub
   **Domain:** [domain.com]
   **Type:** [SaaS / marketplace / etc.]
   **Vendor family:** [Froiden / … / other]
   **Listing / docs:** [codecanyon URL] · [docs URL]
   
   **Audience:** [target] | **Region:** [region] | **Language:** [lang]
   **Industry:** [focus]
   **Monetization:** [model] via [gateway(s)]
   **Tax / invoicing:** [Stripe Tax / manual / undecided with trigger]
   
   **Infrastructure:**
   - GitHub: [account/org] | Repo: [private/public] | Git user: [name] <[email]>
   - Hosting: [provider]
   - **Primary non-production:** [env key] · [SSH alias] · [IP] · [hosting acct/order if known] — **confirmed by operator**
   - **Production:** [SSH alias] · [IP] · [hosting acct/order if known] — **confirmed by operator**
   - DNS/CDN: [Cloudflare/other] | Zone: [ID or "to be set up"]
   - Email: [provider] | Custom addresses: [yes/no/undecided]
   - Database: [MySQL/MariaDB] | GUI: [tool]
   - SSH: [alias(es) / needs setup]
   
   **Optional tools:** Atlas [yes/no] | Bytebase [yes/no] | Redis [yes/no] | Sentry [yes/no]
   
   **Team:** [solo/team of N] | **AI tools:** [list] | **Timeline:** [urgent/relaxed]
   
   **Detected from source code:**
   - Laravel [version], PHP ^[version]
   - Auth: [Sanctum/Passport/…]
   - Payments: [packages detected]
   - Frontend: [Tailwind/Bootstrap + Alpine/Livewire/Vue]
   - [X] migrations, [Y] models, [Z] route files
   - Feature surface (from recon): [modules / plans / orders / …]

   • ✅ You replied confirmed (or listed corrections). Agent updates the summary before drafting files.

Capture the answers as an interview summary

Paste the answers into a short scratch note (or have the agent write _onboarding-summary.md) before drafting the files. They are reused in AGENTS.md, CLAUDE.local.md, and the project_context.md rule in Rules & skills.

Interview block	Feeds into
App source (CodeCanyon URL + listing research)	AGENTS.md · ## Vendor documentation · Phase 6 superadmin
Q1–Q4 identity + Q5–Q7 audience	AGENTS.md · ## What this is · project_context.md
Q8–Q10 monetization + vendor family/URLs	AGENTS.md · Zaj-PROJECT.md · Phase 6 billing setup
Stack + payment package confirmation	AGENTS.md · ## Tech stack
Q11–Q28 infrastructure + server mapping	CLAUDE.local.md · project_context.md · Zaj-PROJECT.md · deploy.php (Phase 4)
Q29–Q31 team & timeline	Branch/PR conventions · IDE mirrors · phase prioritization
Full summary (step 6)	_onboarding-summary.md scratch → all files above; re-run via deploy-codecanyon interview mode

After major decisions in later phases, use /revise-claude-md (or update AGENTS.md directly) so the constitution stays current — do not let session-only memory replace the committed contract.

2. Write AGENTS.md (the contract)

Write AGENTS.md at the repo root using the auto-detected stack so the tech-stack section is accurate. The kit ships a complete version; the essential shape is below.

Who does this

🤖 Agent drafts AGENTS.md from the interview answers and the auto-detected stack. 👤 User confirms the business/vendor lines that only a person knows.

1. Draft the file at the repo root with the canonical 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. `Zaj-PROJECT.md` — non-secret current truth: identity, versions, paths, environments, SSH aliases, and tracker links. If missing in a legacy project, read `Admin-Local/1-Project/1-Info/ProjectCard.md` as fallback, then create `Zaj-PROJECT.md`.
   3. `.claude/rules/` — behavioral + reference rules (auto-loaded).
   4. `Zaj-PROGRESS.md` and `Zaj-BACKLOG.md` — current work and deferred work.
   5. `Zaj-CUSTOMIZATIONS.md` — vendor-deviation ledger (create an empty stub at [Create the project §6](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/01-project-setup/) or Phase 2 import; until then, treat as “not yet created”).
   6. `CLAUDE.local.md` — personal env (if present, gitignored).
   
   ## Vendor documentation
   - CodeCanyon item: <listing URL>
   - Online docs: <docs URL> · Demo: <demo URL> · Support: <support URL>
   - Bundled docs in repo: _(filled after Phase 2 extraction — paths under `_Source/` or `Admin-Local/2-Docs/1-VendorDocs/`)_
   
   > **Logging cadence:** append to `Zaj-CUSTOMIZATIONS.md` **at the moment of the deviation**, not in a batch later — one entry per in-place vendor edit (`ZAJ:BEGIN/END`), net-new file (`ZAJ:FILE`), custom `_zaj` migration, and provisional/strategic decision (e.g. the Stripe account-strategy block). After any installer / deploy / migration / vendor update, run `git diff --name-only` and reconcile anything untracked against the ledger before committing.
   
   ## Tech stack
   - Laravel <version> (PHP ^<version>), <Livewire/Alpine/Vue>, <Tailwind/Bootstrap>, MySQL, <Sanctum/Passport>.
   
   ## Conventions
   - `Zaj-PROJECT.md` is the project bible for current facts. `Zaj-CUSTOMIZATIONS.md` is the vendor-deviation ledger. Do not scatter current toolchain/path/server facts through one-off notes.
   - 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)
   - **Default = act, don't hedge:** update trackers, run verification, commit routine completed work, and choose the secure/professional default when it is clearly better. Ask only for secrets, paid/provider dashboards, production cutovers, destructive actions, business/scope/legal choices, or genuinely equal options.
   - **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 `Zaj-CUSTOMIZATIONS.md`.
   - **Migrations:** guard with `Schema::hasTable()/hasColumn()`; never `migrate:fresh|wipe|reset` on shared data.
   - **Route protection:** block sensitive paths at the web-server level (`.htaccess` `[F]` / Nginx `deny`), not only in middleware. CodeCanyon apps often boot heavy middleware stacks; a middleware-only installer block can 500 before it blocks. Web-server denial stops the request before PHP boots.
   - **`.env` quoting:** **always** double-quote *every* `.env` value. Unquoted, the characters `#  $  &  ^  [  +  *  ;` and spaces break `.env` parsing. A password like `p@ss#w&rd$1` written unquoted silently truncates to `p@ss` (parsing stops at the first `#`). Applies to `DB_PASSWORD`, `REDIS_PASSWORD`, `MAIL_PASSWORD`, API keys — every value:
   
     ```dotenv
     # ❌ silently truncates to  p@ss
     DB_PASSWORD=p@ss#w&rd$1
     # ✅ stored intact
     DB_PASSWORD="p@ss#w&rd$1"

   • Composer auth: for private/paid packages, set composer config --global github-oauth.github.com <token> — never paste tokens inline into composer.json.
   • 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.
   • Cloudflare budgets: free-plan WAF/rate-limit/cache budgets are tight. Scope WAF/rate-limit to /admin, /login, /install, and /update; never challenge the public landing page or checkout without a human SEO/business decision.

   AI-agent conventions

   • Read this file and .claude/rules/ before any SSH or deploy action.
   • Read before SSH: check AGENTS.md, CLAUDE.local.md, ~/.ssh/config, and server-environment.conf (if present) — only SSH when the answer is not already local.
   • Read before asking: check interview notes, .env.example, and existing configs before re-asking the user.
   • Prefer MCP/API tools and gh over hand-run shell where one exists; include dashboard steps only as fallback.
   • Stay within resource budgets — shared hosting (migration timeouts, memory) and the Cloudflare free plan (≈ 5 WAF rules, 1 rate-limit rule, 10 cache rules). Note usage and remaining capacity after each Cloudflare operation.
   • Never challenge the landing page. Scope every WAF / rate-limit rule to specific sensitive paths (/admin, /login, /install) — never apply a challenge or block to / or a broad URI pattern; that blocks search engines and real visitors.
   • Never silently skip SHOULD/OPTIONAL tasks — default to doing SHOULD work. Mark OPTIONAL work N/A only when the project state or provisioning table proves it is not adopted, and list every N/A/skipped item with evidence at phase end.
   • Orchestration skill: read ~/.claude/skills/zaj-laravel-codecanyon/SKILL.md (or the project’s /deploy-codecanyon command) at session start — safety rules apply whether or not the skill is invoked.
   • Never replace the vendor landing page or demo content silently — flag it for a human decision.

   - ✅ The tech-stack line matches what Create the project auto-detected; vendor family and business lines match the interview.

2. Verify on disk — commit as C3 at the end of this page.

   test -f AGENTS.md && git add -n AGENTS.md
   # Expected: AGENTS.md listed (dry-run) — commit in §8 below

   • ✅ AGENTS.md is at the repo root (written now; committed at C3).

Zaj-CUSTOMIZATIONS.md cadence

Create Zaj-CUSTOMIZATIONS.md early even if it starts empty. Log every vendor deviation with date, file, reason, marker ([x] done, [~] partial, [s] skipped with reason, [!] blocker), and restore instructions. The file is a customization ledger, not a replacement for CLAUDE.local.md.

3. Write CLAUDE.md (thin pointer)

Keep CLAUDE.md short so there’s no drift — it only redirects to AGENTS.md plus any Claude-specific notes.

1. Create the pointer at the repo root.

   # 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/skills/zaj-laravel-codecanyon/SKILL.md` at session start — orchestration + safety rules apply whether or not the skill is invoked.
   - After [Rules & skills](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/05-rules-and-skills/), `.claude/rules/` loads at session start — **restart the IDE/agent session** after seeding rules so they take effect.
   - `CLAUDE.local.md` (gitignored) holds personal/machine notes.

   • ✅ CLAUDE.md contains only a redirect + Claude-specific notes — no duplicated stack/conventions.

2. Verify on disk (same timing as AGENTS.md — commit at C3).

   test -f CLAUDE.md && git add -n CLAUDE.md
   # Expected: CLAUDE.md listed (dry-run)

   • ✅ CLAUDE.md sits at the repo root alongside AGENTS.md.

4. Create CLAUDE.local.md (personal, gitignored)

This file holds the per-developer environment — local URL, server IPs, zone IDs — and only references credentials, never the secrets themselves. It must never enter git.

Who does this

👤 User fills in the personal values (local URL, IPs, zone IDs); 🤖 Agent wires the gitignore and verifies.

1. Write the personal file at the repo root.

   # CLAUDE.local.md — Personal (NOT committed)
   
   ## My environment
   - Local URL: http://<app>.test
   - DB GUI: TablePlus
   
   ## Cloudflare
   - Zone ID: <your-zone-id>
   - Server IP: <your-server-ip>
   - DNS token env var: $CF_API_TOKEN
   
   ## Hosting
   - Provider: <Hostinger / cPanel / other>
   - Username: <hosting-user> · Order ID: <order-id> (if applicable)
   - **Primary non-production:** key `<NON_PROD_ENV_KEY>` · alias `<NON_PROD_SSH>` · IP `<NON_PROD_IP>` · acct/order `<NON_PROD_ACCT>`
   - **Production:** alias `<PRODUCTION_SSH>` · IP `<PRODUCTION_IP>` · acct/order `<PRODUCTION_ACCT>`
   - Document root: /home/<user>/domains/<domain>/public_html
   - Hosting MCP note: <machine-wide token covers this acct / per-project token needed / hPanel-only>
   
   ## Credentials
   - Stored in: <1Password vault `<Project>` / Admin-Local/…/credentials.md>
   - ⚠️ When writing passwords to `.env`, always double-quote them.
   
   ## Email (populate in deploy / superadmin phases)
   - Provider: <Titan / SendGrid / Mailgun / …>
   - admin@<domain> · noreply@<domain> · support@<domain> _(when created)_

   • ✅ The file references where credentials live, never the secret values.

2. Gitignore personal scratch + confirm.

   for f in CLAUDE.local.md _onboarding-summary.md; do
     grep -qx "$f" .gitignore 2>/dev/null || echo "$f" >> .gitignore
   done
   git check-ignore CLAUDE.local.md _onboarding-summary.md
   # Expected: both filenames printed — never staged

   • ✅ git check-ignore echoes both filenames — interview scratch and personal overlay stay out of git.

5. Pick a credential store

CLAUDE.local.md only references credentials; the secrets themselves live in one of three stores. The default is 1Password (op) because it keeps secrets encrypted and lets the project commit safe op:// templates instead of plaintext env copies.

Who does this

🔀 User + Agent — 👤 User decides the store (team vs solo); 🤖 Agent wires the .env.tpl / render command for Option A.

Option	Best for	How it works
A · 1Password CLI (op) default / recommended	Teams, repeat deployments, secret rotation	Secrets stay in a project vault (app secrets) plus a shared General-Dev vault (account-wide infra creds — see two-vault model below). Option A1 (default): commit a .env.tpl with only op:// refs; teammates run op inject. Option A2: gitignore .env.tpl when solo or vault structure should stay out of git — each dev obtains the template via 1Password/onboarding (see sub-choice below).
B · Vault templates	Offline / no 1Password	Per-env files live only in gitignored Admin-Local/1-Project/2-Vault/; only .env.example is tracked — wired in Phase 2 · Wire .env templates.
C · credentials.md	Solo / throwaway	A single gitignored markdown file in the vault lists each secret. Simpler, but unencrypted on disk — never commit it.

Pick one env strategy — don’t run both A and B

Option A is the canonical path for setup-new. If you choose A, skip Phase-2’s three vault-template files. Within Option A, pick A1 (commit .env.tpl) or A2 (gitignore .env.tpl) — both are valid; the tradeoff is shared template in git vs keeping vault/item names out of the repo. Mixing a committed .env.tpl with vault .env.staging copies creates two sources of truth.

For 1Password references, use this convention everywhere: op://<vault>/<item>/<field> where vault = project ([PROJECT]), item = environment for .env values (Local, Staging, Production), and field = a flat env var. Phase 2 seeds the baseline fields (DB_PASSWORD, APP_KEY, etc.); later phases may add more flat fields (for example STRIPE_SECRET) before a template references them. Example value line: DB_PASSWORD="op://[PROJECT]/Production/DB_PASSWORD".

Two-vault model — project vault + shared infra vault

op://<Project>/<env>/<key> assumes every secret is project-scoped. Some creds are account-wide infra — a Hostinger account API token, a Cloudflare token, a registrar key, Admin-Server webhooks, MonSpark heartbeat URLs — and span every project on that account. Storing them per-project duplicates the secret and multiplies rotation points (rotate once, update N vaults). Split into two vaults. The default shared vault name in examples is General-Dev, but the operator may use any name; record the actual shared infra vault in Zaj-PROJECT.md.

Vault	Holds	Reference shape	Example
<Project> (per-project)	Baseline env fields seeded in Phase 2 (APP_KEY, DB_*, env_file) plus later-added app secrets that differ per environment (STRIPE_SECRET, MAIL_PASSWORD)	op://<Project>/<env>/<KEY>	op://[PROJECT]/Production/DB_PASSWORD
<SharedInfraVault> (default example: General-Dev)	Infra creds shared across projects: hosting account token, Cloudflare token, registrar key, Admin-Server Slack/Discord webhooks, MonSpark/heartbeat URLs — one item per account or provider	op://<SharedInfraVault>/<account-or-provider>/<KEY>	op://General-Dev/Hostinger-zaj.commerce/HOSTINGER_API_TOKEN

When a project uses multiple hosting accounts (e.g. staging on one Hostinger login, production on another), the shared vault holds one item per account, and each environment’s .env.tpl points at the right account item.

Grant the project service account BOTH vaults

The service account from Machine setup §3.5 is created scoped to the project vault. It does not automatically see the shared infra vault. If you leave it project-only, op inject fails the moment a template references op://General-Dev/... or the project’s chosen shared vault — the agent can’t read the infra creds it needs (e.g. op item get returns “isn’t a vault in this account”).

Grant the SA read on the shared infra vault too — either recreate the SA with both vaults, or grant it in the 1Password web UI (Developer → service account → Manage Access → add the shared vault read). Verify both are visible:

SHARED_INFRA_VAULT="General-Dev" # example; use the actual vault from Zaj-PROJECT.md
op vault ls | grep -E "<Project>|${SHARED_INFRA_VAULT}"
# Expected: BOTH vault names listed for the active token

op:// belongs only on real value lines

op inject scans the whole template file for secret references, including comments. Never put op://... examples in .env.tpl comments; a commented production example can still make a local render fail if that item/field does not exist. Keep alternate-environment examples in prose outside the template, and verify with grep -n '^[[:space:]]*#.*op://' .env*.tpl.

Permission posture for Option A — read and write the safe templates

The agent must be able to read safe templates (.env.example, .env.tpl) and run discovery/render commands (op vault ls, op item ls, op inject). It must also be able to edit those same safe templates — the agent legitimately needs to add keys, switch a local driver (e.g. sqlite → mysql), or regenerate refs while wiring the constitution.

The .env* guards block two directions, and both are commonly over-broad:

Guard	Wrongly blocks	Correct scope
Read (fixed earlier)	Read(./.env.example), Read(./.env.tpl)	block real secret files; allow .env.example / .env.tpl
Write (this fix)	Edit/Write(./.env.tpl), Edit(./.env.example)	block real secret files; allow .env.tpl / .env.<env>.tpl / .env.example

If the write guard is a blanket .env* deny, the agent can’t Edit .env.tpl and routes around via temp files. Mirror the read fix on the write side — block only real secret files, allow the safe templates:

// .claude/settings.json — deny REAL secret files, allow safe templates (read + write)
"deny": [
  "Read(./.env)", "Read(./.env.local)", "Read(./.env.*.local)",
  "Read(./.env.production)", "Read(./.env.staging)",
  "Write(./.env)", "Write(./.env.local)", "Write(./.env.*.local)",
  "Write(./.env.production)", "Write(./.env.staging)",
  "Edit(./.env)", "Edit(./.env.local)", "Edit(./.env.*.local)",
  "Edit(./.env.production)", "Edit(./.env.staging)"
],
"allow": [
  "Read(./.env.example)", "Read(./.env.tpl)", "Read(./.env.*.tpl)",
  "Write(./.env.example)", "Write(./.env.tpl)", "Write(./.env.*.tpl)",
  "Edit(./.env.example)", "Edit(./.env.tpl)", "Edit(./.env.*.tpl)"
]

The rendered .env / .env.<env> (real secrets) stay write-protected; only the op://-ref templates and the placeholder .env.example are editable. If a global Claude setting denies Read(./.env.*) or Write(./.env.*), a project-local allow cannot override it — a human must install the AI-System defaults before the session starts (see Claude config).

1. (Option A) Install and verify op. Machine setup has the full CLI walkthrough; here you only confirm the chosen store is usable from this project.

   command -v op >/dev/null || brew install --cask 1password/tap/1password-cli
   op --version
   op vault ls >/dev/null && echo "op vault access OK"
   # Expected: op 2.x; vault access OK

   • ✅ op vault ls works. Do not use op whoami as the service-account test.

2. Pick or create the project vault — service account creates it. For the zero-manual-grant path, the same service account from Machine setup §3.5 creates the project vault. Do not reuse a human-created vault unless a human explicitly granted that service account access in 1Password.

   PROJECT="<ProjectName>"
   SHARED_INFRA_VAULT="General-Dev"  # example; use the actual shared vault name if different
   op vault get "$PROJECT" >/dev/null 2>&1 || op vault create "$PROJECT" >/dev/null
   op vault get "$PROJECT" >/dev/null && echo "vault OK: $PROJECT"
   
   # Shared infra vault — created once for the account, reused by every project (see two-vault model above)
   op vault get "$SHARED_INFRA_VAULT" >/dev/null 2>&1 || op vault create "$SHARED_INFRA_VAULT" >/dev/null
   op vault get "$SHARED_INFRA_VAULT" >/dev/null && echo "vault OK: $SHARED_INFRA_VAULT (shared infra)"
   
   # The project SA must read BOTH vaults — verify before proceeding
   op vault ls | grep -E "^${PROJECT}\b|^${SHARED_INFRA_VAULT}\b" || echo "FAIL: SA cannot see one of the vaults — grant access (see danger box above)"
   # Expected: vault OK: <ProjectName>; vault OK: <SharedInfraVault>; both listed for the SA

   • ✅ The vault name is the project name, not the environment and not a generic “Env” bucket.
   • ✅ The shared infra vault exists, and the project SA can see both vaults (op vault ls lists both). If only the project vault shows, grant the SA shared-vault read per the danger box above before continuing — infra-cred renders will fail otherwise.
   • ✅ If op vault create fails with access/permission error, recreate the service account with vault-creation permission or use the 1Password UI to grant access; do not keep retrying item creation against a vault the token cannot see.

3. Standardize the per-environment item shape. Setup uses one Secure Note item per environment inside the project vault: Local, Staging, and Production. Phase 2 · Prerequisites §3 seeds these items idempotently before .env.tpl or production deploy steps reference them.

   Content	Fields	Why
   Flat env fields — same names everywhere	DB_CONNECTION, DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD, APP_KEY, env_file	Matches op://<Project>/<Environment>/<Field> exactly, so templates never reference a missing item or dotted sub-field.
   Concealed fields	DB_PASSWORD, APP_KEY, env_file	These can contain secrets or the rendered .env blob. Never print them; verify by length, exit code, or non-secret fields.

   PROJECT="<ProjectName>"
   for item in Local Staging Production; do
     op item get "$item" --vault "$PROJECT" >/dev/null 2>&1 \
       && echo "item exists: $item" \
       || echo "TODO: Phase 2 Prerequisites must seed '$item' in vault '$PROJECT'"
   done
   # Expected: each item exists before any op://<Project>/<Environment>/<Field> template is rendered

   • ✅ Local, Staging, and Production items exist before rendering templates.
   • ✅ Each item has the same flat field set; no active setup path uses a single Databases item with dotted fields like Staging.password.

   The env_file blob MUST be auto-generated — never hand-maintained

   A hand-typed env_file drifts the instant you rotate a single secret field, and you paste a stale .env into production. Guarantee sync by generating the blob from the template with op inject and writing it back, so the blob is always a deterministic render of the current secret fields. Regenerate it on every secret change (Step 5 below shows the command). Read the blob with op read "op://<Project>/<env>/env_file"; never edit it by hand in the 1Password app.

   Read-only service account fallback

   If policy grants the service account read-only vault access, create or edit items in the 1Password app (human session). The agent can still run op inject to render .env from committed templates — it cannot op item create until write access exists. The write probe in machine setup §3.5 catches read-only SAs before you discover the gap at item creation.

4. Generate .env.tpl from .env.example keys — don’t hand-write it.

   PROJECT="<ProjectName>"
   ENVIRONMENT="Local"
   test -f .env.example || { echo "FAIL: create .env.example first"; exit 1; }
   
   awk -F= -v vault="$PROJECT" -v item="$ENVIRONMENT" '
     /^[[:space:]]*#/ || /^[[:space:]]*$/ { print; next }
     /^[A-Za-z_][A-Za-z0-9_]*=/ {
       key=$1
       print key "=\"op://" vault "/" item "/" key "\""
       next
     }
     { print }
   ' .env.example > .env.tpl
   
   grep -q 'op://'"$PROJECT"'/'"$ENVIRONMENT" .env.tpl && echo ".env.tpl refs OK"
   if grep -n '^[[:space:]]*#.*op://' .env.tpl; then
     echo "FAIL: remove op:// references from .env.tpl comments"; exit 1
   fi
   # Expected: .env.tpl exists; every key points at op://<Project>/<Environment>/<KEY>

   • ✅ .env.tpl contains references only — no secret values.
   • ✅ .env.tpl has no commented op:// references. Comments may describe the environment, but examples containing op:// live in docs, not inside the template.

   Record A1 vs A2 in CLAUDE.local.md before render (default A1 for multi-developer repos).

5. Render + verify without printing values.

   op inject -f -i .env.tpl -o .env
   test -s .env && echo ".env rendered"
   grep -q '^APP_KEY=' .env && echo "APP_KEY present (value hidden)"
   git check-ignore .env
   git check-ignore .env.tpl || echo ".env.tpl trackable OK"
   # Expected: .env rendered; .env ignored; .env.tpl not ignored

   • ✅ .env is populated and gitignored; .env.tpl is trackable and contains only op:// references.

   Sync the env_file blob back to 1Password (auto-generated — keeps the one-paste blob current):

   PROJECT="<ProjectName>" ENVIRONMENT="Local"
   # Render once, then push the whole .env as the item's env_file field (never hand-typed)
   BLOB="$(op inject -f -i .env.tpl)"
   op item edit "$ENVIRONMENT" --vault "$PROJECT" "env_file[text]=$BLOB" >/dev/null \
     && echo "env_file blob synced for $ENVIRONMENT"
   unset BLOB
   # Verify it round-trips (length only — never print the body)
   op read "op://$PROJECT/$ENVIRONMENT/env_file" | wc -c
   # Expected: byte count > 0 — blob matches the current secret fields

   • ✅ The env_file blob is a fresh render, so it can never drift from the individual secret fields. Re-run this whenever any secret field changes.

   Option A sub-choice — commit vs gitignore .env.tpl:

   Sub-choice	When	Tradeoff
   A1 — commit .env.tpl (default for teams)	Multi-developer repo	Shared render template in git; teammates clone and run op inject
   A2 — gitignore .env.tpl	Solo owner or refs expose vault structure	Remove !.env.tpl from bootstrap .gitignore; each dev obtains template via 1Password/onboarding

   # A1 (default): trackable template
   git check-ignore .env.tpl || echo ".env.tpl trackable OK"
   # A2 (owner choice): intentionally gitignored
   git check-ignore .env.tpl && echo ".env.tpl gitignored by owner choice OK"

6. Thread staging/production through deploy. For each environment, render from that environment item rather than copying a local .env.

   # Example: render production from op://<Project>/Production/<KEY>
   PROJECT="<ProjectName>" ENVIRONMENT="Production"
   awk -F= -v vault="$PROJECT" -v item="$ENVIRONMENT" '
     /^[[:space:]]*#/ || /^[[:space:]]*$/ { print; next }
     /^[A-Za-z_][A-Za-z0-9_]*=/ { key=$1; print key "=\"op://" vault "/" item "/" key "\""; next }
     { print }
   ' .env.example > ".env.${ENVIRONMENT}.tpl"
   if grep -n '^[[:space:]]*#.*op://' ".env.${ENVIRONMENT}.tpl"; then
     echo "FAIL: remove op:// references from template comments"; exit 1
   fi
   op inject -f -i ".env.${ENVIRONMENT}.tpl" -o ".env.${ENVIRONMENT}"
   # Expected: .env.Production rendered locally for upload/deploy, never committed

   • ✅ Each deployment environment has a reproducible render path from 1Password.

Secret hygiene applies regardless of store

Whichever store you choose, the universal secret-handling discipline still holds — verify tokens by length only, never echo characters into a session, keep sk_* keys out of shell env, and rotate on team changes. The agent loads these as feedback_secret_handling.md / feedback_stripe_agent_safety.md in Rules & skills.

6. Operator Provisioning Gate

One upfront 👤 step that gathers everything a human must supply across the whole playbook — accounts, API keys, license codes — and stores it in op:// now, so later phases read non-blocking instead of stalling mid-task. Without this gate, operator inputs are scattered (hosting at Phase 2, Stripe at Phase 6, production infra at Phase 4) and every phase pauses to ask the human for one more credential.

Who does this

👤 User supplies the values (the agent cannot create accounts or read a vendor license email); 🤖 Agent stores each into op://, builds the status table, and flags what’s still missing. This pairs with the prerequisites tooling check — that gate ensures the CLI tools are present; this gate ensures the credentials are present.

Capture inputs now; carry infrastructure forward

Production infra that can’t exist yet (a prod VPS, a live Stripe account) is recorded as a later-phase carry-forward — but its inputs (which hosting account, which Stripe mode) are captured here so the owning phase has everything the moment it runs. Carry-forward means the work has a named owner and trigger; it does not mean the operator gets asked again later.

1. Walk the operator through every input the playbook will need. Group by domain so nothing is missed. Store each secret into the right vault (op://<Project>/<env>/<KEY> for app secrets, op://<SharedInfraVault>/<account-or-provider>/<KEY> for account-wide infra; General-Dev is only the default example). Mark the status of each: ✅ provided · ⏳ carry-forward (captured, infra not built) · ❌ missing — blocks Phase N.

   Domain	Item(s) the human must supply	Store at	Needed by	Status
   Hosting	Account login(s), SSH key/access, server IP(s), DB host/user/password	op://General-Dev/<account>/... (token) · op://<Project>/<env>/DB_*	Phase 4–5 (deploy)
   GitHub	Repo account/org, repo visibility, deploy key (if CI)	gh auth (machine setup) · op://General-Dev/GitHub/DEPLOY_KEY	Phase 2 (code repo)
   Domain / DNS	Domain name, registrar access, Cloudflare account + token + zone ID	op://General-Dev/Cloudflare/CF_API_TOKEN · zone ID in CLAUDE.local.md	Phase 5 (staging DNS)
   Payments	Stripe test+live keys (or PayPal), webhook signing secret	op://<Project>/<env>/STRIPE_SECRET, STRIPE_WEBHOOK_SECRET	Phase 6 (superadmin billing)
   Email	Transactional provider API key / SMTP creds	op://<Project>/<env>/MAIL_PASSWORD (or MAIL_API_KEY)	Phase 5–6
   Admin-Server alerting	Slack/Discord ops/deploy/backups webhook URLs; MonSpark/Healthchecks/Better Stack/Cronitor/UptimeRobot heartbeat URLs	op://<SharedInfraVault>/Admin-Server/SLACK_WEBHOOK_OPS etc.; runtime copy only in gitignored ~/Admin-Server/config/server.env	Shared-hosting setup · Phase 4 deploy notifications · Phase 5 monitoring
   Observability	Sentry DSN, PostHog key (if used), MonSpark API key/heartbeat URL if adopted	op://<Project>/<env>/SENTRY_DSN, POSTHOG_KEY; op://<SharedInfraVault>/MonSpark/...	Phase 7 (monitoring)
   Vendor license	CodeCanyon purchase code / license key, Envato token (if updater)	op://<Project>/CodeCanyon License/VENDOR_LICENSE_CODE	Phase 2 install / Phase 6 updater
   1Password	Project vault + shared infra vault (default example: General-Dev) + service account with both granted	— (this section’s prereq)	All phases (every render)

   • ✅ Every row has a status. Anything ❌ missing that blocks an early phase (Phase 2–5) is resolved now; items that only block later phases may stay ⏳ carry-forward with their inputs captured.

2. Store each provided secret into op:// immediately — do not leave it in chat. Use op item edit to add a field to the matching environment item (or op item create for a shared-infra-vault item). Verify by length only.

   PROJECT="<ProjectName>"
   SHARED_INFRA_VAULT="General-Dev"  # example; use the actual shared vault name if different
   # Example: add the Stripe live key as a field on the Production item
   op item edit "Production" --vault "$PROJECT" "STRIPE_SECRET[password]=<paste>" >/dev/null
   op item get "Production" --vault "$PROJECT" --fields label=STRIPE_SECRET --reveal | wc -c
   # Expected: byte count > 0 — value stored, never printed
   
   # Example: account-wide Cloudflare token in the shared vault
   op item edit "Cloudflare" --vault "$SHARED_INFRA_VAULT" "CF_API_TOKEN[password]=<paste>" >/dev/null 2>&1 \
     || op item create --vault "$SHARED_INFRA_VAULT" --category "API Credential" --title "Cloudflare" "CF_API_TOKEN[password]=<paste>" >/dev/null

   • ✅ Each secret lives in op://, referenced (never inlined) by later phases. The provisioning table is a status board, not a place secrets are written.

3. Record the gate outcome. Write the status table into _onboarding-summary.md (gitignored) and add a one-line provisional entry to Zaj-CUSTOMIZATIONS.md noting which inputs are provided vs carried forward, so a later phase reads the board instead of re-interviewing.

   • ✅ The provisioning table is recorded; carry-forward items name the phase they unblock; no early-phase blocker remains ❌.

7. Verify the constitution loads

Confirm a fresh agent actually reads the contract before declaring this step done.

Who does this

🔀 User + Agent — 👤 User starts a fresh agent session; 🤖 Agent demonstrates it absorbed the constitution.

1. Start a fresh agent session in the project and watch for unprompted stack/convention references.

   # From project root — constitution files on disk
   test -f AGENTS.md && test -f CLAUDE.md && echo "constitution files OK"
   git check-ignore CLAUDE.local.md && echo "local overlay ignored OK"
   ls .claude/rules/*.md 2>/dev/null | wc -l   # 0 until Rules & skills; note count after seed

   Ask the new session: “What is this project’s stack, and what safety rules apply to tinker and migrations?” — and, after Rules & skills, “List the .claude/rules/ files you loaded.”

   • ✅ Without being told, the agent references the stack/conventions — proof it read AGENTS.md. If not, confirm the files are at the repo root and restart the session (memory files load once at start, not mid-chat).

8. Commit the constitution (C3)

Who does this

🤖 Agent commits on develop. Keep CLAUDE.local.md gitignored.

1. Stage and commit C3 from the project root.

   git branch --show-current    # must be develop
   git add AGENTS.md CLAUDE.md .gitignore
   # Option A1 (default): commit the op:// template — references only
   if git check-ignore -q .env.tpl 2>/dev/null; then
     echo "A2 — .env.tpl gitignored by owner choice; skip git add"
   elif test -f .env.tpl; then
     git add .env.tpl
   fi
   git commit -m "feat(ai): project constitution (AGENTS.md + CLAUDE.md)"
   git log --oneline -3         # C3 atop C2 + C1
   # Expected: C3 on develop; CLAUDE.local.md not staged; .env.tpl added only for A1

   • ✅ git log -3 shows C3; git check-ignore CLAUDE.local.md still succeeds.
   • ✅ A1: .env.tpl in C3 (references only). A2: .env.tpl gitignored — confirm with git check-ignore .env.tpl and record the choice in CLAUDE.local.md.

Checklist

Do not mark this step done until every box below is checked.

• 🔀 Interview complete — CodeCanyon URL (or non-CC path) + Q1–Q31 answered or marked undecided/defaults; vendor family + docs URLs captured; stack/integrations confirmed.
• 🔀 Interview summary signed off — step 6 summary reviewed; corrections applied before drafting files.
• 🤖 AGENTS.md written — at the repo root, tech-stack line matches the auto-detected stack; C3 committed.
• 🤖 CLAUDE.md written — thin pointer only; no duplicated stack/conventions; included in C3.
• 👤 CLAUDE.local.md created — personal env filled in; references (not values) for credentials.
• 🤖 CLAUDE.local.md gitignored — git check-ignore CLAUDE.local.md echoes the filename.
• 👤 Credential store chosen — Option A (1Password, default), B (vault templates), or C (credentials.md) recorded in CLAUDE.local.md; if A, record A1 (commit .env.tpl) or A2 (gitignore .env.tpl).
• 🔀 Two-vault model set up (Option A) — project vault (<Project>) and shared General-Dev vault both exist; project SA can read both (op vault ls lists both).
• 🔀 Env items shaped (Option A) — Local / Staging / Production items exist with flat fields (DB_CONNECTION, DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD, APP_KEY, env_file); concealed fields are verified without printing.
• 🤖 .env* write guard scoped — write/edit denies cover real secret files only; .env.tpl / .env.<env>.tpl / .env.example are editable.
• 🔀 Operator Provisioning Gate run — every input the playbook needs (hosting, GitHub, DNS/Cloudflare, payments, email, observability, vendor license, 1Password) captured into op:// with a needed-by-Phase / status row; no early-phase blocker left ❌.
• 🔀 Constitution verified — a fresh agent session references the stack/conventions unprompted.
• 🤖 C3 committed on develop — AGENTS.md + CLAUDE.md + .gitignore (+ .env.tpl for A1 only; A2 confirms git check-ignore .env.tpl); CLAUDE.local.md gitignored.

→Next step

Claude config