5 · Rules & skills

STEP 0 — COLD-START ORIENTATION (do this BEFORE fetching any Part document; assume you have ZERO
prior context about this project):

1. Locate + identify. Run `pwd`. Read the project's `AGENTS.md` + `CLAUDE.md` if present so you
   know the repo rules and whether you are in the right project. Then read `Zaj-PROJECT.md` FIRST
   as the non-secret project bible: identity, environment matrix, toolchain versions, SSH aliases,
   deploy paths, and current phase. If `Zaj-PROJECT.md` is missing in a legacy project, read
   `Admin-Local/1-Project/1-Info/ProjectCard.md` as fallback, then create/update `Zaj-PROJECT.md`.

2. Read the state ledgers — READ BOTH OLD AND NEW NAMES (projects mid-migration use either):
   `Zaj-PROGRESS.md` OR `PROGRESS.md` (what earlier phases/steps already did, what's in-flight),
   `Zaj-BACKLOG.md` OR `BACKLOG.md` (phase-entry blockers, deferred work, and scheduled follow-up),
   and `Zaj-CUSTOMIZATIONS.md` OR `_CUSTOMIZATIONS.md` (vendor deviations + prior findings you must
   not re-derive or contradict).

3. Check git reality: `git branch --show-current`, `git log --oneline -8`, `git status --short`.
   - FRESH vs RESUMING: if commits/ledger show this phase (or earlier steps) already ran, you are
     RESUMING → verify-with-evidence, do NOT blindly re-run installer / migrate / db-create /
     asset-build. (This is the contract's reconcile rule.)
   - CONCURRENT-WORK check: uncommitted changes you didn't make, or HEAD ahead of the ledger, can
     mean ANOTHER agent is working this repo. Coordinate around hot files; do not commit over
     unrelated work. Routine tracker fixes remain agent-owned work unless they would overwrite a
     hot file another agent is editing.

4. Inherit rules + safety: skim `.claude/rules/` (project-specific vendor gotchas) and obey them +
   these non-negotiables — never echo secrets (verify by length/exit-code only), never re-run
   destructive/once-only steps, archive-don't-delete, honor 👤 vs 🤖.

5. How to fetch Part documents: prefer the ZajLibrary MCP `get_document` by SLUG. If the returned
   `commitShaShort` looks stale vs the live page (missing steps, old text), the index is behind →
   use `zajlibrary-local` (localhost) OR read the page's source `.mdx` directly from the ZajLibrary
   repo. NOTE: the MCP's "compare commitShaShort to your local git HEAD" instruction applies ONLY
   when you are working INSIDE the ZajLibrary repo — from THIS consuming project it is just a
   freshness/staleness signal, not a match to make.

6. Where to record: write current-truth facts to `Zaj-PROJECT.md`; write vendor deviations to
   `Zaj-CUSTOMIZATIONS.md`; write execution state to `Zaj-PROGRESS.md`; write blockers/deferred
   work to `Zaj-BACKLOG.md`. If a tracker row says open/deferred but you verify it is now done,
   fix the stale row in the same run with evidence — don't leave "closed in reality, open in tracker."
   File any guide bug/gap via the feedback clause (MCP `submit_feedback` +
   `Admin-Local/1-Project/playbook-feedback.md`) — log-then-continue, don't silently work around.

Only after Step 0 is complete, begin fetching Part 1.

# ZajLibrary — implementation playbook

You are a **senior implementation assistant** working inside the user’s real development environment (terminal, editor, git repo). You are **not** a documentation writer, tutor, or library editor.

**Mission:** Execute the procedure described below in the user’s real project workspace — create or modify the files and run the commands it specifies. Do not just summarize it.

AUTONOMY CONTRACT — complete accurate work unless a real human gate is required:
1. Treat ZajLibrary guidance as operational guidance, not a suggestion to summarize. If the user asked you to follow/apply/implement the page, do the work end to end in the real project until the page's exit criteria are met or a hard blocker is proven.
2. Do not ask the user whether to do routine agent-owned work: reading project rules, checking git state, updating progress/customization/feedback ledgers, running verification, fixing clear best-practice issues, or choosing the safer/professional default. Do it, cite evidence, and report what changed.
3. Ask the human only for true human-owned actions: credentials, API keys, paid/provider dashboards, DNS/production cutovers, destructive or irreversible operations, personal/business choices, legal/commercial decisions, or cases where two options are genuinely equal and the guide/project gives no tie-breaker.
4. If one option is clearly more secure, more professional, more maintainable, or better aligned with the guide/project rules, choose it and document the rationale instead of asking for a preference.
5. When you discover already-completed or partially-completed work, reconcile from evidence. Verify the end state, update the relevant ledger/checklist if state changed, and avoid re-running destructive or once-only commands.
6. Banned routine asks: "should I update trackers?", "should I commit?", "should I run verification?", "should I fix the stale ledger?", or "which option do you prefer?" when the guide/project makes one option clearly better.
7. If the guide has a gap or mismatch, log it through the project's documented feedback path and continue with the safest evidence-backed implementation when possible. Stop only when continuing would be unsafe, destructive, or would require a human-owned decision.

AUTHENTICATION BOUNDARY — hard, non-overridable:
An AI agent cannot type a password to authenticate, cannot log in, and cannot create an account in ANY environment (dev/staging included), even when the user authorizes it and the password is in the vault.
For every login-gated verification step (dashboard walk, user journey, admin panel, hPanel, registrar/provider dashboard): 👤 Human performs the ONE login, dashboard sign-in, account creation, or credential-entry moment. 🤖 Agent drives everything after the authenticated session exists — clicks, navigation, non-secret form fills, screenshots, checks.
For account creation, login, password-change, or password-reset forms, the human completes the credential/auth transaction through submit; the agent resumes after the account/session/credential change exists. Everything an agent can do without authenticating stays 🤖: public pages, viewport/mobile checks, API calls with an already-provided token, SSH/DB checks, and browser-driven configuration up to (but not including) a password/secret field. Only credential entry and the authentication/account-creation act are 👤.

## Metadata
- title: 5 · Rules & skills
- url: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/05-rules-and-skills/
- shelf: Build & Create
- doc_type: implementation playbook
- status: current
- kind: playbook
- category: tech-stack
- subcategory: laravel
- topic: codecanyon
- phase: 1
- part_number: 5 (legacy stepNumber frontmatter)
- legacy_step_number: 5
- est_time: ~10 min
- description: Seed .claude/rules/ with the universal behavioral + reference rule set, install the stack skills and deploy orchestrator into .claude/skills/, then restart so the new context loads.
- tags: ai-system, rules, skills, memory

## Execution rules (binding)
- This is Part 5 of phase 1 (~10 min) — execute this Part fully, then stop at its `## Checklist`.
- Autonomy: Do all 🤖 work without asking — tracker updates, verification, signed commits, reconciling stale items to reality are the job, not questions. Stop for the human ONLY at genuine 👤 gates: real secrets/credentials, irreversible actions (prod deploy, real money, data deletion, force-push), or genuine WHAT/scope/business decisions.
- Full ≠ optional: Autonomy does not mean minimal. Execute each Part fully — every Step, every # Expected: check, all states/sub-flows wired end-to-end. Never ship a happy-path subset as "done." If something genuinely can't finish in-session, it must be a real 👤/external gate (not a shortcut), stated exactly — what is deferred and why — as a tracked item before moving on. When the user says "do fully," honor it to completion.
- For playbooks, treat a Part as the `.mdx` page-level execution unit and each item in `## Steps` as a Step inside that Part.
- Follow `## Steps` in order. Do not skip Steps or declare the work complete early.
- Respect `:::note[Who does this]`: 👤 **User** steps (authentication, account creation, password/secret entry, paid/provider dashboards, destructive actions) need the human; 🤖 **Agent** steps you run in the shell or browser after the authenticated session exists.
- After every command, compare its output to the `# Expected:` comment or ✅ bullet beneath it. If it differs, investigate safely and reconcile from evidence first; ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices.
- Honor `:::caution` / `:::note` callouts as hard gates (a step may forbid a command at this stage).
- Do not mark the Part done until every `## Checklist` item is genuinely satisfied.
- Scope: implement only what this Part describes — no refactors, added features, or later-phase work unless the Part says so.
- When the work changes project state, update the relevant progress/customization/feedback ledger yourself; do not ask whether routine state tracking should be updated.
- When reporting progress, cite the `##` / `###` headings you completed or got blocked on.
- Secrets: never put API keys, passwords, or `.env` values in frontend code, commits, or chat logs — use server-side `.env` / config only, and keep `.env` gitignored.
- EXECUTION CONTRACT — full coverage, no silent skips:
1. Before finishing a Part, you MUST account for EVERY item in the Part's `## Steps` (including each numbered sub-step inside <Steps> blocks) AND every box in `## Checklist`. Nothing is implicitly done.
2. Scope labels are not skip permission. `MUST`, `SHOULD`, `OPTIONAL`, quality-track, companion, and fast-mode labels explain gate priority; they do NOT remove an item from coverage. Default to FULL execution. Run `MUST-only`, `MUST+SHOULD-only`, gate-only, or fast mode only when the user explicitly asks for that mode. Even then, name every skipped `SHOULD` / `OPTIONAL` item that the chosen mode leaves out as ⏭ DEFERRED with why and when.
3. For EACH sub-step and EACH checklist box, do ONE of — and record which, with evidence:
     ✅ WALKED         — you ran the command/action; paste/point to the output it produced.
     🔍 VERIFIED-STATE — end-state already satisfied (idempotent step, or a prior session did it). Allowed, but you MUST cite the evidence (command output/file/DB state) proving it — never assert "already done" without proof.
     ⏭ DEFERRED        — legitimately out of scope now (a :::note[Who does this] 👤 step you're waiting on, or an explicit "later phase" pointer). State why + to when.
     ◐ PARTIAL         — some sub-parts done, some deferred; list exactly which and why.
4. Honor every `# Expected:` / ✅ bullet — compare actual output. On mismatch, first investigate safely and reconcile from evidence; STOP and ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices. Honor :::caution/:::danger as hard gates. Honor 👤 vs 🤖.
5. Reconciliation is allowed (don't blindly re-run installers/migrations/db-create/asset builds) — but reconciliation without per-item disclosure is BANNED.
6. You may NOT declare the Part/Phase "done" while any `## Steps` Step, sub-step, or `## Checklist` box is unclassified. Silent omission = incomplete.
7. Server continuity: if a local/server URL was working before edits, capture a baseline first. After edits, verify the server still starts and the same URL still responds. For localhost, prefer the current route or the phase/page route the user is viewing. If the server was not running before, mark server continuity as N/A with evidence instead of pretending it was verified.
8. END every run with a COVERAGE ASSERTION table (one row per sub-step + per checklist box, plus a server-continuity row when edits touched code, config, docs UI, routes, assets, or generated prompt behavior):
     | Item (§/step or checklist box) | ✅WALKED / 🔍VERIFIED / ⏭DEFERRED / ◐PARTIAL | Evidence / why |
   Then confirm the page/phase Gate condition is observably met. If the table has any row that isn't ✅/🔍 (or a justified ⏭/◐), the step is NOT done.
9. Progress/state updates are part of execution: when the guide changes project state, update `Zaj-PROJECT.md`, `Zaj-PROGRESS.md`, `Zaj-BACKLOG.md`, `Zaj-CUSTOMIZATIONS.md`, and/or `playbook-feedback.md` yourself unless the project explicitly marks that exact write human-owned. Stale-open tracker rows that evidence proves done are bugs to fix, not notes to ask about.
10. Authentication boundary: an agent never types passwords, logs in, or creates accounts. Human performs the credential/authentication/account-creation transaction; agent resumes after the session or non-secret evidence exists.
11. Secrets: never put keys/passwords/.env values in code, commits, or chat; verify by length/exit-code only.

---

# 5 · Rules & skills

## TL;DR

**Objective** — seed `.claude/rules/` with the universal behavioral + reference rule set, install the stack skills and deploy orchestrator into `.claude/skills/`, then **restart** so the new context loads. This is the **accumulated-knowledge** layer — hard-won lessons from past CodeCanyon deployments that arm every future session.

**Steps at a glance:**
1. **Seed `.claude/rules/`** — The kit ships the full universal rule set plus a `seed-project-rules.sh` that
   copies them into `.claude/rules/`, backs up any existing versions, and writes a human-readable index.
2. **Install skills into `.claude/skills/`** — The `zaj-laravel-codecanyon` orchestrator should already be in
   the project from C2 (machine setup §5).
3. **Commit rules + skills (C5)** — commit the rule and skill layers, so the repo carries the stack-specific
   operating system future sessions need.
4. **Restart all layers** — `.claude/rules/` and `.claude/skills/` load once at session start and are *not*
   re-scanned mid-session.

:::note[User part + done-when]
**👤 User part** — the only human-only action is the **restart**: end the session and start a fresh one so the seeded rules and skills actually load. Everything else is terminal-runnable.

**Done when** `.claude/rules/` is seeded (universal set + `project_context.md`), stack skills are installed in `.claude/skills/`, **C5** is committed on `develop`, and a **fresh session** confirms the rules are loaded. &nbsp;·&nbsp; **⏱ ~10 min** &nbsp;·&nbsp; 🔀 mostly the agent, one user restart.
:::

## Background

Rules and skills are the **accumulated knowledge** layer — hard-won lessons from past CodeCanyon deployments that arm every future session (and every teammate who pulls the repo) so you don't re-hit known bugs from scratch.

| Layer | Location | What it is | Loaded |
|---|---|---|---|
| **Rules** | `.claude/rules/*.md` | Behavioral (`feedback_*`) + reference (`reference_*`) + project (`project_*`) knowledge | In full, at session start |
| **Skills** | `.claude/skills/` | Reusable *procedures* the agent invokes on demand (e.g. the deploy orchestrator) | On invocation |

Both are **committed at C5** (orchestrator already at **C2**) so they travel with the repo — see [git policy](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/#git-policy).

```mermaid
flowchart TD
  Boot[Agent session start] --> Rules[".claude/rules/<br/>loaded in full"]
  Boot --> Skills[".claude/skills/<br/>invoked on demand"]
  Rules --> Guard[Behavior + reference + project context]
  Skills --> Proc[Procedures e.g. deploy orchestrator]
```

## Steps

### 1. Seed `.claude/rules/`

The kit ships the full universal rule set plus a `seed-project-rules.sh` that copies them into `.claude/rules/`, backs up any existing versions, and writes a human-readable index. It's safe to re-run anytime the rule set is updated; it never touches your `project_*.md` files.

:::danger[Do not run full `seed.sh` on hand-built projects]
If you already wrote `AGENTS.md`, `.claude/settings.json`, and constitution files page-by-page, **never** run the kit's full `seed.sh` — it overwrites hand-built project policy. Use **Path B** below (rules bundle only).
:::

:::note[Who does this]
🤖 **Agent** runs the seed path from the project root. 👤 **User** reviews the index afterward if desired.
:::

<Steps>

1. **Choose Path A or Path B**, then seed rules.

   | Path | When | Command |
   | --- | --- | --- |
   | **A — kit install** | Fresh AI-System kit / `seed.sh` already ran | `bash .claude/rules/seed-project-rules.sh` |
   | **B — hand-built** | Constitution/settings written manually first | Copy rules from kit temp dir only (see below) |

   **Path A** — from the project root:

   ```bash
   bash .claude/rules/seed-project-rules.sh   # idempotent — only adds/updates by mtime
   # Expected: rules copied/updated; existing project_*.md files left untouched
   ```

   **Path B** — fetch kit, copy **only** `.claude/rules/`:

   ```bash
   KIT_DIR="Admin-Local/0-Setup/codecanyon-ai-system-kit"
   mkdir -p .claude/rules Admin-Local/1-Project
   cp -R "$KIT_DIR/dot-claude/rules/." .claude/rules/
   touch Zaj-PROJECT.md \
         .tool-versions \
         Zaj-CUSTOMIZATIONS.md \
         Zaj-PROGRESS.md \
         Zaj-BACKLOG.md \
         Zaj-CHANGELOG.md \
         Admin-Local/1-Project/playbook-feedback.md
   # Expected: rules + tracking files exist; AGENTS.md/CLAUDE.md/settings untouched
   ```

   - ✅ `.claude/rules/` fills with the `feedback_*` + `reference_*` set (Path A or B).

2. **Add a project-specific context file.** The universal rules are universal; add one file for *this* project's current state. Save it as `.claude/rules/project_context.md` — this file is yours, and seed re-runs never overwrite `project_*` files.

   ```markdown
   ---
   name: Project context — <AppName>
   description: High-level context every session should load. Update as the project progresses.
   ---

   ## <AppName>
   - Type: <SaaS / marketplace / directory>
   - Vendor family: <Froiden / LiquidThemes / WorkDo / InfyOm / IqonicDesign / other>
   - Tech stack: Laravel <version>, <notes>
   - Environments: see `Zaj-PROJECT.md` environment matrix (`staging-primary`, `qa`, `uat`, `production`, etc.)
   - Current phase: AI dev environment setup (complete — update as you go)

   ## Known vendor gotchas (fill in after the local dev source scan)
   - APP_ENV hardcoding: <not yet scanned>
   ```

   - ✅ `.claude/rules/project_context.md` exists with this project's type, vendor family, stack, and environments.

</Steps>

#### What gets seeded (grouped for discoverability)

**Meta — how to work with the system itself**
- `feedback_rule_persistence.md` — when to write a rule directly vs propose-first; keep rules small, grouped, cross-referenced
- `feedback_guide_updates_proactive.md` — apply guide edits directly when root cause is clear
- `feedback_playbook_feedback_logging.md` — log guide gaps / vendor quirks to project playbook feedback instead of silent inline fixes
- `feedback_devlog_convention.md` — use `Admin-Local/1-Project/90-DevLog/` as the build journal and hot-file coordination surface
- `feedback_commit_split_strategy.md` — the rules→deviations→content→docs commit pattern
- `feedback_idempotent_replay_scripts.md` · `feedback_replay_script_persistence.md` — recoverable, persisted bulk-write scripts

**CodeCanyon vendor handling**
- `feedback_product_naming.md` — use your project names, never vendor script names
- `feedback_vendor_assumptions_verify.md` — installed ≠ canonically used; grep source first
- `feedback_vendor_ui_first.md` · `feedback_vendor_ui_warnings.md` — prefer vendor UI/code paths; treat UI warnings as hypotheses
- `feedback_observer_reseed_trap.md` — vendor observers silently re-materialize defaults; check `app/Observers/` first
- `feedback_demo_content_replacement.md` — replace vendor demo content (fake testimonials are a legal landmine)
- `feedback_tier_gating_model.md` — discover the vendor's gating model before designing tiers
- `reference_codecanyon_vendor_families.md` — known gotchas by vendor family
- `reference_vendor_deviation_pattern.md` — the safe 3-file deviation pattern with comment markers

**Customization-ownership system**
- `feedback_zaj_code_markers.md` — wrap edits in `ZAJ:BEGIN/END`; net-new files get `ZAJ:FILE`
- `feedback_zaj_table_naming.md` — table/migration naming conventions
- `reference_zaj_customization_strategy.md` — the vendor-customization vs new-module vs table-extension decision tree

**Laravel / PHP**
- `feedback_blade_short_php_form.md` · `feedback_env_hardcoding_scan.md` · `feedback_php_alt_binary_artisan.md` · `feedback_toolchain_version_parity.md`
- `reference_laravel_execution_patterns.md` — when to use tinker vs script vs artisan vs seeder vs migration

**Deploy / infra**
- `feedback_shared_files_add_not_set.md` · `feedback_cron_every_minute_gotcha.md` · `feedback_staging_vs_production_execution.md`

**Security / secrets**
- `feedback_secret_handling.md` · `feedback_server_side_secret_execution.md` · `feedback_op_signin_interactive.md` · `feedback_stripe_agent_safety.md`
- `reference_stripe_restricted_key_scopes.md`

**i18n / content**
- `feedback_free_translate_polysemy.md` — spot-check machine translations for polysemy before shipping

### 2. Install skills into `.claude/skills/`

The **`zaj-laravel-codecanyon`** orchestrator should already be in the project from **C2** ([machine setup §5](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/02-machine-setup/#5-install-the-deploy-orchestrator-skill--per-project-then-customize)). This step adds **stack skills** (Stripe, etc.) — skip re-downloading the orchestrator unless C2 was skipped.

:::note[Who does this]
🤖 **Agent** runs the download into the project; fill any `<placeholders>` for this project as you go.
:::

<Steps>

1. **Confirm the orchestrator from C2** (or download if missing).

   ```bash
   test -d .claude/skills/zaj-laravel-codecanyon/handbook \
     && echo "orchestrator present (C2)" \
     || { mkdir -p .claude/skills/zaj-laravel-codecanyon
          curl -fsSL https://library.zajapps.com/skills/zaj-laravel-codecanyon.tgz \
            | tar -xz -C .claude/skills/zaj-laravel-codecanyon; }
   # Expected: handbook/ + SKILL.md present
   ```

   - ✅ `.claude/skills/zaj-laravel-codecanyon/handbook/` exists **or** you deliberately use a global `~/.claude/skills/zaj-laravel-codecanyon` copy only.

2. **Add stack skills** (Stripe example — install only if this project uses Stripe).

   ```bash
   npx skills add stripe            # example — installs the Stripe skill into .claude/skills/
   ls .claude/skills/
   # Expected: orchestrator + any stack skills you chose
   ```

   - ✅ `ls .claude/skills/` lists the orchestrator (downloaded into the project) and any stack/Stripe skills.

3. **If you built by hand, copy only the rules bundle.**

   If you already wrote `AGENTS.md`, `.claude/settings.json`, and project mirrors by hand, do **not** run the kit's full `seed.sh` here. Use the kit as a source tree and copy the rule files deliberately so you do not overwrite hand-built project policy.

   ```bash
   KIT_DIR="Admin-Local/0-Setup/codecanyon-ai-system-kit"
   mkdir -p .claude/rules
   cp -R "$KIT_DIR/dot-claude/rules/." .claude/rules/
   # Expected: only .claude/rules/ is copied from the kit in this hand-built path
   ```

   - ✅ Hand-built constitution/settings files remain untouched; `.claude/rules/` carries the CodeCanyon feedback rules.

4. **Verify on disk** — commit at **C5** (§3 below).

   ```bash
   git add -n .claude/rules/ .claude/skills/ .claude/agents/
   # Expected: paths listed (dry-run) — commit in §3 below
   ```

   - ✅ `.claude/rules/` + stack skills are in place. `.claude/agents/` is present only if you created real reviewer files, not just placeholders.

</Steps>

:::note[Seed the project trackers now — later phases depend on them]
The kit's `seed.sh` drops the **tracking files** the agent appends to for the rest of the build. They must exist **now** — later phases say "update `Zaj-PROGRESS.md`", "promote this to `Zaj-BACKLOG.md`", or "append to playbook feedback", and the seeded rules (`feedback_playbook_feedback_logging.md`) have nothing to write to if the file is missing. If you built the AI system by hand, create the empty files now so nothing downstream has a dangling reference.

| File | Role |
| --- | --- |
| `Zaj-PROJECT.md` (root) | Non-secret current truth: identity, repo, toolchain versions, environment matrix, deploy paths, SSH aliases, and tracker links. |
| `.tool-versions` (root) | Machine-readable PHP / Node / Composer targets for teams using asdf/mise; DB engine and collation stay in `Zaj-PROJECT.md`. |
| `Zaj-CUSTOMIZATIONS.md` (root) | Vendor-deviation ledger and root ownership map; first real entries land in Code & repository setup. |
| `Zaj-PROGRESS.md` (root) | Current / in-flight phase and step progress — the **committed, team-visible** counterpart to the gitignored `CLAUDE.local.md`. |
| `Zaj-BACKLOG.md` (root) | Deferred / future work surfaced during execution or research, before promotion to GitHub Issues. |
| `Zaj-CHANGELOG.md` (root) | Internal done/history release log; keeps your SemVer separate from vendor release notes. |
| `Admin-Local/1-Project/playbook-feedback.md` | Guide gaps / vendor quirks you hit — **log them, don't silently work around them**, so the next project running these guides doesn't re-hit the same gap. |

Treat the Zaj-owned root files as one family: `Zaj-PROJECT.md` records current truth, `Zaj-CHANGELOG.md` records done/history, `Zaj-PROGRESS.md` records current/in-flight work, `Zaj-BACKLOG.md` records deferred/future work, and `Zaj-CUSTOMIZATIONS.md` records vendor deviations. `playbook-feedback.md` stays under `Admin-Local/1-Project/` because it is meta feedback about this playbook and feeds the library feedback queue.
:::

:::tip[PROGRESS marker protocol — update the marker BEFORE moving on]
`Zaj-PROGRESS.md` is only useful if it stays current. After every tracked step from here on, set its marker **before** starting the next step:

| Marker | Meaning |
| --- | --- |
| `[x]` | done — add the completion date |
| `[~]` | started / in progress |
| `[s]` | explicitly skipped / `N/A` — add evidence and, if future work remains, a `Zaj-BACKLOG.md` row |
| `[!]` | blocked — add the blocker |

```markdown
## Phase 1 — AI dev environment
- [x] 1 — Create the project & bring in the code ✅ <date>
- [x] 2 — Machine setup ✅ <date>
- [~] 5 — Rules & skills 🟡 started <date> (you are here)

## Phase 3 — Local development
- [ ] 7 — Shared-hosting readiness
- [s] 8 — Dev tooling ⚪ N/A: <evidence, or Zaj-BACKLOG.md row if this is future work>
```

**Backfill on first seed:** add a line for every setup-new step already completed this session, using the **current published phase and step names** from this playbook. Do not copy source guide phase labels or task numbers into `Zaj-PROGRESS.md`. Commit the backfill as a **separate** commit so the audit trail reads "progress tracker seeded" → "progress tracker backfilled" as two distinct steps.

**`Zaj-PROGRESS.md` is not `CLAUDE.local.md`.** `CLAUDE.local.md` tracks private machine/session context and stays gitignored; `Zaj-PROGRESS.md` tracks shared step state and is committed so any new session, machine, or teammate sees exactly what's outstanding.
:::

:::note[Other project files seeded here — you act on them in later phases]
The kit also drops a few **conditional** project inputs so later phases find the right home for the work. Don't fill them in now; record either the expected future owner or an evidence-backed `N/A` so none of this becomes a silent skip:

- `brand-profile.json` + `asset-deployment-map.json` — under `Admin-Local/1-Project/1-Info/Brand/`; **Phase 6** generates logos, favicons, and hero assets from them.
- A **provisional Stripe account strategy** — a placeholder decision recorded now and **locked in Phase 6** (when you create real keys), then used in **Phase 8** billing.
- Deep-research reports live under `Admin-Local/1-Project/1-Info/Research/`; any `follow_up_tasks` they produce go into root `Zaj-BACKLOG.md`. Do **not** create a separate research-todos side file.
- Persisted replay scripts use the `Admin-Local/1-Project/5-Scripts/` taxonomy only after a real replay script exists. If no replay scripts are needed yet, record `N/A` in `Zaj-PROGRESS.md` with evidence instead of creating empty script folders.
:::

:::caution[Provisional Stripe account trap]
Some vendor families create sandbox connected-account IDs that look similar to the parent account. Record the intended `acct_*` suffix now, then verify that exact suffix when Phase 6 creates real products/prices. Similar names are not proof.
:::

:::note[Provisional Stripe account-strategy heuristic (recorded now, locked later)]
If the project uses Stripe, record a **provisional** account-strategy decision now and lock it in a later phase — Stripe account migration is expensive for Cashier-based apps (persistent subscription objects) and cheap for ad-hoc-invoice apps (just swap `.env` keys). Guess the likely billing architecture from the vendor family:

| Vendor family | Likely billing architecture |
| --- | --- |
| Froiden | Ad-hoc invoice (custom webhook controller) |
| WorkDo (Dash SaaS) | Ad-hoc invoice (per-module controllers) |
| LiquidThemes | Varies per product — check docs |
| InfyOm / Infix | Mixed — often canonical Cashier |
| IqonicDesign | Mixed — often canonical Cashier with customizations |
| Unknown / other | Unknown — treat as "requires later verification" |

**Default by provisional architecture:** likely-Cashier → dedicated account up front (migration too costly to defer); likely-ad-hoc → start minimal, graduate before production; **unknown → dedicated account (the safe default)**. Record the provisional strategy + architecture + vendor-family basis in `Zaj-CUSTOMIZATIONS.md`; a later phase verifies against the extracted source and may revise it **before** any keys are created (key creation is the expensive-to-reverse step, not the decision).
:::

#### Decide whether to create review subagents (`.claude/agents/`)

Skills are *procedures the agent runs*; **subagents** are *specialist reviewers you dispatch* for a focused second opinion. The kit ships three CodeCanyon-specific ones into `.claude/agents/` — they travel with the repo after **C5**:

- **`vendor-update-reviewer`** — checks a change for CodeCanyon vendor-upgrade safety (the `_zaj` suffix, `ZAJ:BEGIN/END` markers, no edits to vendor migrations). Run it before any commit that touches vendor territory.
- **`security-reviewer`** — security review tuned for a multi-tenant Workdo/Dash Laravel SaaS (tenant isolation, mass-assignment, auth/permission gaps). Run it in Phase 7 and before production.
- **`flow-auditor`** — audits one user flow end-to-end for production-readiness (full-stack, not just the happy path). Run it in Phase 10.

If the kit you downloaded contains only `.claude/agents/README.md` placeholders, treat these reviewers as **conditional/create-as-needed**, not as files that already exist. Either create real agent files from your team's current agent template before C5, or leave `.claude/agents/README.md` as a placeholder and record the evidence-backed decision in `Zaj-PROGRESS.md`: `N/A — reviewers dispatch from the global agent pool until a real project agent is written`.

They commit alongside `.claude/skills/` (stack skills) and `.claude/rules/` at **C5** only when real files exist, so they load for every teammate on clone.

:::note[Skills vs `.claude/commands/`]
You may also keep project **slash commands** in `.claude/commands/` (a `<name>.md` file → a `/<name>` command). They overlap with skills, so prefer **skills** for anything reusable — a skill **auto-routes by its trigger description** (no need to remember a command) and travels the same way. Reach for `.claude/commands/` only for a thin project-specific shortcut (e.g. a one-line `/ship` that the team types by hand). The deploy orchestrator is a **skill** (`zaj-laravel-codecanyon`) for exactly this reason.
:::

### Companion global skills (use on demand)

The project orchestrator (`zaj-laravel-codecanyon`) lives in `.claude/skills/` (or globally at `~/.claude/skills/`). **Companion skills** are optional globals you invoke for focused review — no per-project install required when they ship in your IDE plugin pool or `~/.claude/skills/`.

| Phase / moment | Global skill (on demand) | Not a skill — tool/prereq |
| --- | --- | --- |
| Pre-deploy / Phase 7 | `security-review`, `code-review` | — |
| Verify gates (this phase, Phase 10) | `verification-loop` | — |
| Hotfix / bug loop | `systematic-debugging` | — |
| UI / landing work | `frontend-design` | — |
| Atomic commits | `git-commit` | — |
| Deeper audit (optional) | supply-chain / semgrep reviewers | — |
| Machine setup | — | Herd, `gh`, `op`, Composer, Node |

**Tools are not skills.** Herd, GitHub CLI, 1Password CLI, and Composer are prerequisites you run in the terminal — they do not need a "skill" entry. The orchestrator skill *references* this playbook; companion skills add second-opinion review when you dispatch them.

### 3. Commit rules + skills (C5)

:::note[Who does this]
🤖 **Agent** commits on **`develop`**. Orchestrator stays from **C2** — this commit adds rules, stack skills, and agents.
:::

<Steps>

1. **Stage and commit C5** from the project root.

   ```bash
   git branch --show-current    # must be develop
   git add .claude/rules .claude/skills .claude/agents
   git commit -m "feat(ai): seed rules + install stack skills"
   git log --oneline -5         # C5 atop C4…C1
   # Expected: C5 on develop; zaj-laravel-codecanyon unchanged from C2 unless you added stack skills beside it
   ```

   - ✅ `git log` shows C5; `.claude/rules/` and stack skills are tracked. Review subagents are tracked only if you created real reviewer files; placeholders alone are not a done signal.

</Steps>

### 4. Restart all layers

`.claude/rules/` and `.claude/skills/` load **once at session start** and are *not* re-scanned mid-session. If you seed without restarting, the current session keeps running with the old/empty context and the new rules have zero effect.

:::note[Who does this]
👤 **User** ends the session and starts a fresh one — only a person can restart the session.
:::

Why it matters: if you run a Stripe-key step in a session that never loaded `feedback_stripe_agent_safety.md`, the agent may accept an unrestricted key or skip the human-gate.

:::caution[🚨 The 30-second restart is the highest-leverage step in this phase]
Restart **before** any secret-handling step — it's the cheapest way to avoid the worst mistakes in this phase.
:::

<Steps>

1. **Save work** — or `/compact` to preserve context, but note a reload still needs a **new** session.

   - ✅ Pending work is saved (or context compacted) before exiting.

2. **End the session and start fresh.**

   ```text
   1. Save work (or /compact to preserve context — but reload still needs a NEW session)
   2. End the session (/exit or Ctrl+D)
   3. Start fresh: claude
   4. Verify: ask "What rules do you have loaded in .claude/rules/?"
   ```

   - ✅ A fresh `claude` session is running.

3. **Verify the rules loaded.** Ask the new session what rules it has.

   ```text
   Ask: "What rules do you have loaded in .claude/rules/?"
   # Expected: it lists the feedback_* + reference_* set plus project_context.md
   ```

   - ✅ The session lists the `feedback_*` + `reference_*` set **plus** `project_context.md`.

</Steps>

## Checklist

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

- [ ] **🤖 Rules seeded** — `bash .claude/rules/seed-project-rules.sh` ran; `.claude/rules/` holds the `feedback_*` + `reference_*` set.
- [ ] **🤖 Project context added** — `.claude/rules/project_context.md` exists with this project's type, vendor family, stack, and environments.
- [ ] **🤖 Skills installed** — `.claude/skills/zaj-laravel-codecanyon/handbook/` (per-project download) **or** global `~/.claude/skills/zaj-laravel-codecanyon/handbook/`; plus any stack/Stripe skills.
- [ ] **🤖 Review subagent plan recorded** — either `.claude/agents/` holds real vendor-update / security / flow-auditor reviewer files, or the placeholders explicitly say the project will dispatch global reviewers as needed.
- [ ] **🤖 Tracking files seeded** — root `Zaj-PROJECT.md`, `.tool-versions`, `Zaj-CUSTOMIZATIONS.md`, `Zaj-PROGRESS.md`, `Zaj-BACKLOG.md`, and `Zaj-CHANGELOG.md` exist; `Admin-Local/1-Project/playbook-feedback.md` exists (later phases write to them).
- [ ] **🤖 C5 committed on develop** — `.claude/rules/`, stack skills, and `.claude/agents/` tracked (`git log` shows C5); orchestrator already from **C2**.
- [ ] **👤 Session restarted** — a fresh session was started after seeding.
- [ ] **🔀 Rules confirmed loaded** — the fresh session lists the `feedback_*` + `reference_*` set plus `project_context.md`.

:::next[Next step]
[Cursor & other IDEs](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/06-cursor-and-ides/)
:::

# 5 · Rules & skills

> Source: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/05-rules-and-skills/

## TL;DR

**Objective** — seed `.claude/rules/` with the universal behavioral + reference rule set, install the stack skills and deploy orchestrator into `.claude/skills/`, then **restart** so the new context loads. This is the **accumulated-knowledge** layer — hard-won lessons from past CodeCanyon deployments that arm every future session.

**Steps at a glance:**
1. **Seed `.claude/rules/`** — The kit ships the full universal rule set plus a `seed-project-rules.sh` that
   copies them into `.claude/rules/`, backs up any existing versions, and writes a human-readable index.
2. **Install skills into `.claude/skills/`** — The `zaj-laravel-codecanyon` orchestrator should already be in
   the project from C2 (machine setup §5).
3. **Commit rules + skills (C5)** — commit the rule and skill layers, so the repo carries the stack-specific
   operating system future sessions need.
4. **Restart all layers** — `.claude/rules/` and `.claude/skills/` load once at session start and are *not*
   re-scanned mid-session.

:::note[User part + done-when]
**👤 User part** — the only human-only action is the **restart**: end the session and start a fresh one so the seeded rules and skills actually load. Everything else is terminal-runnable.

**Done when** `.claude/rules/` is seeded (universal set + `project_context.md`), stack skills are installed in `.claude/skills/`, **C5** is committed on `develop`, and a **fresh session** confirms the rules are loaded. &nbsp;·&nbsp; **⏱ ~10 min** &nbsp;·&nbsp; 🔀 mostly the agent, one user restart.
:::

## Background

Rules and skills are the **accumulated knowledge** layer — hard-won lessons from past CodeCanyon deployments that arm every future session (and every teammate who pulls the repo) so you don't re-hit known bugs from scratch.

| Layer | Location | What it is | Loaded |
|---|---|---|---|
| **Rules** | `.claude/rules/*.md` | Behavioral (`feedback_*`) + reference (`reference_*`) + project (`project_*`) knowledge | In full, at session start |
| **Skills** | `.claude/skills/` | Reusable *procedures* the agent invokes on demand (e.g. the deploy orchestrator) | On invocation |

Both are **committed at C5** (orchestrator already at **C2**) so they travel with the repo — see [git policy](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/#git-policy).

```mermaid
flowchart TD
  Boot[Agent session start] --> Rules[".claude/rules/<br/>loaded in full"]
  Boot --> Skills[".claude/skills/<br/>invoked on demand"]
  Rules --> Guard[Behavior + reference + project context]
  Skills --> Proc[Procedures e.g. deploy orchestrator]
```

## Steps

### 1. Seed `.claude/rules/`

The kit ships the full universal rule set plus a `seed-project-rules.sh` that copies them into `.claude/rules/`, backs up any existing versions, and writes a human-readable index. It's safe to re-run anytime the rule set is updated; it never touches your `project_*.md` files.

:::danger[Do not run full `seed.sh` on hand-built projects]
If you already wrote `AGENTS.md`, `.claude/settings.json`, and constitution files page-by-page, **never** run the kit's full `seed.sh` — it overwrites hand-built project policy. Use **Path B** below (rules bundle only).
:::

:::note[Who does this]
🤖 **Agent** runs the seed path from the project root. 👤 **User** reviews the index afterward if desired.
:::

<Steps>

1. **Choose Path A or Path B**, then seed rules.

   | Path | When | Command |
   | --- | --- | --- |
   | **A — kit install** | Fresh AI-System kit / `seed.sh` already ran | `bash .claude/rules/seed-project-rules.sh` |
   | **B — hand-built** | Constitution/settings written manually first | Copy rules from kit temp dir only (see below) |

   **Path A** — from the project root:

   ```bash
   bash .claude/rules/seed-project-rules.sh   # idempotent — only adds/updates by mtime
   # Expected: rules copied/updated; existing project_*.md files left untouched
   ```

   **Path B** — fetch kit, copy **only** `.claude/rules/`:

   ```bash
   KIT_DIR="Admin-Local/0-Setup/codecanyon-ai-system-kit"
   mkdir -p .claude/rules Admin-Local/1-Project
   cp -R "$KIT_DIR/dot-claude/rules/." .claude/rules/
   touch Zaj-PROJECT.md \
         .tool-versions \
         Zaj-CUSTOMIZATIONS.md \
         Zaj-PROGRESS.md \
         Zaj-BACKLOG.md \
         Zaj-CHANGELOG.md \
         Admin-Local/1-Project/playbook-feedback.md
   # Expected: rules + tracking files exist; AGENTS.md/CLAUDE.md/settings untouched
   ```

   - ✅ `.claude/rules/` fills with the `feedback_*` + `reference_*` set (Path A or B).

2. **Add a project-specific context file.** The universal rules are universal; add one file for *this* project's current state. Save it as `.claude/rules/project_context.md` — this file is yours, and seed re-runs never overwrite `project_*` files.

   ```markdown
   ---
   name: Project context — <AppName>
   description: High-level context every session should load. Update as the project progresses.
   ---

   ## <AppName>
   - Type: <SaaS / marketplace / directory>
   - Vendor family: <Froiden / LiquidThemes / WorkDo / InfyOm / IqonicDesign / other>
   - Tech stack: Laravel <version>, <notes>
   - Environments: see `Zaj-PROJECT.md` environment matrix (`staging-primary`, `qa`, `uat`, `production`, etc.)
   - Current phase: AI dev environment setup (complete — update as you go)

   ## Known vendor gotchas (fill in after the local dev source scan)
   - APP_ENV hardcoding: <not yet scanned>
   ```

   - ✅ `.claude/rules/project_context.md` exists with this project's type, vendor family, stack, and environments.

</Steps>

#### What gets seeded (grouped for discoverability)

**Meta — how to work with the system itself**
- `feedback_rule_persistence.md` — when to write a rule directly vs propose-first; keep rules small, grouped, cross-referenced
- `feedback_guide_updates_proactive.md` — apply guide edits directly when root cause is clear
- `feedback_playbook_feedback_logging.md` — log guide gaps / vendor quirks to project playbook feedback instead of silent inline fixes
- `feedback_devlog_convention.md` — use `Admin-Local/1-Project/90-DevLog/` as the build journal and hot-file coordination surface
- `feedback_commit_split_strategy.md` — the rules→deviations→content→docs commit pattern
- `feedback_idempotent_replay_scripts.md` · `feedback_replay_script_persistence.md` — recoverable, persisted bulk-write scripts

**CodeCanyon vendor handling**
- `feedback_product_naming.md` — use your project names, never vendor script names
- `feedback_vendor_assumptions_verify.md` — installed ≠ canonically used; grep source first
- `feedback_vendor_ui_first.md` · `feedback_vendor_ui_warnings.md` — prefer vendor UI/code paths; treat UI warnings as hypotheses
- `feedback_observer_reseed_trap.md` — vendor observers silently re-materialize defaults; check `app/Observers/` first
- `feedback_demo_content_replacement.md` — replace vendor demo content (fake testimonials are a legal landmine)
- `feedback_tier_gating_model.md` — discover the vendor's gating model before designing tiers
- `reference_codecanyon_vendor_families.md` — known gotchas by vendor family
- `reference_vendor_deviation_pattern.md` — the safe 3-file deviation pattern with comment markers

**Customization-ownership system**
- `feedback_zaj_code_markers.md` — wrap edits in `ZAJ:BEGIN/END`; net-new files get `ZAJ:FILE`
- `feedback_zaj_table_naming.md` — table/migration naming conventions
- `reference_zaj_customization_strategy.md` — the vendor-customization vs new-module vs table-extension decision tree

**Laravel / PHP**
- `feedback_blade_short_php_form.md` · `feedback_env_hardcoding_scan.md` · `feedback_php_alt_binary_artisan.md` · `feedback_toolchain_version_parity.md`
- `reference_laravel_execution_patterns.md` — when to use tinker vs script vs artisan vs seeder vs migration

**Deploy / infra**
- `feedback_shared_files_add_not_set.md` · `feedback_cron_every_minute_gotcha.md` · `feedback_staging_vs_production_execution.md`

**Security / secrets**
- `feedback_secret_handling.md` · `feedback_server_side_secret_execution.md` · `feedback_op_signin_interactive.md` · `feedback_stripe_agent_safety.md`
- `reference_stripe_restricted_key_scopes.md`

**i18n / content**
- `feedback_free_translate_polysemy.md` — spot-check machine translations for polysemy before shipping

### 2. Install skills into `.claude/skills/`

The **`zaj-laravel-codecanyon`** orchestrator should already be in the project from **C2** ([machine setup §5](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/02-machine-setup/#5-install-the-deploy-orchestrator-skill--per-project-then-customize)). This step adds **stack skills** (Stripe, etc.) — skip re-downloading the orchestrator unless C2 was skipped.

:::note[Who does this]
🤖 **Agent** runs the download into the project; fill any `<placeholders>` for this project as you go.
:::

<Steps>

1. **Confirm the orchestrator from C2** (or download if missing).

   ```bash
   test -d .claude/skills/zaj-laravel-codecanyon/handbook \
     && echo "orchestrator present (C2)" \
     || { mkdir -p .claude/skills/zaj-laravel-codecanyon
          curl -fsSL https://library.zajapps.com/skills/zaj-laravel-codecanyon.tgz \
            | tar -xz -C .claude/skills/zaj-laravel-codecanyon; }
   # Expected: handbook/ + SKILL.md present
   ```

   - ✅ `.claude/skills/zaj-laravel-codecanyon/handbook/` exists **or** you deliberately use a global `~/.claude/skills/zaj-laravel-codecanyon` copy only.

2. **Add stack skills** (Stripe example — install only if this project uses Stripe).

   ```bash
   npx skills add stripe            # example — installs the Stripe skill into .claude/skills/
   ls .claude/skills/
   # Expected: orchestrator + any stack skills you chose
   ```

   - ✅ `ls .claude/skills/` lists the orchestrator (downloaded into the project) and any stack/Stripe skills.

3. **If you built by hand, copy only the rules bundle.**

   If you already wrote `AGENTS.md`, `.claude/settings.json`, and project mirrors by hand, do **not** run the kit's full `seed.sh` here. Use the kit as a source tree and copy the rule files deliberately so you do not overwrite hand-built project policy.

   ```bash
   KIT_DIR="Admin-Local/0-Setup/codecanyon-ai-system-kit"
   mkdir -p .claude/rules
   cp -R "$KIT_DIR/dot-claude/rules/." .claude/rules/
   # Expected: only .claude/rules/ is copied from the kit in this hand-built path
   ```

   - ✅ Hand-built constitution/settings files remain untouched; `.claude/rules/` carries the CodeCanyon feedback rules.

4. **Verify on disk** — commit at **C5** (§3 below).

   ```bash
   git add -n .claude/rules/ .claude/skills/ .claude/agents/
   # Expected: paths listed (dry-run) — commit in §3 below
   ```

   - ✅ `.claude/rules/` + stack skills are in place. `.claude/agents/` is present only if you created real reviewer files, not just placeholders.

</Steps>

:::note[Seed the project trackers now — later phases depend on them]
The kit's `seed.sh` drops the **tracking files** the agent appends to for the rest of the build. They must exist **now** — later phases say "update `Zaj-PROGRESS.md`", "promote this to `Zaj-BACKLOG.md`", or "append to playbook feedback", and the seeded rules (`feedback_playbook_feedback_logging.md`) have nothing to write to if the file is missing. If you built the AI system by hand, create the empty files now so nothing downstream has a dangling reference.

| File | Role |
| --- | --- |
| `Zaj-PROJECT.md` (root) | Non-secret current truth: identity, repo, toolchain versions, environment matrix, deploy paths, SSH aliases, and tracker links. |
| `.tool-versions` (root) | Machine-readable PHP / Node / Composer targets for teams using asdf/mise; DB engine and collation stay in `Zaj-PROJECT.md`. |
| `Zaj-CUSTOMIZATIONS.md` (root) | Vendor-deviation ledger and root ownership map; first real entries land in Code & repository setup. |
| `Zaj-PROGRESS.md` (root) | Current / in-flight phase and step progress — the **committed, team-visible** counterpart to the gitignored `CLAUDE.local.md`. |
| `Zaj-BACKLOG.md` (root) | Deferred / future work surfaced during execution or research, before promotion to GitHub Issues. |
| `Zaj-CHANGELOG.md` (root) | Internal done/history release log; keeps your SemVer separate from vendor release notes. |
| `Admin-Local/1-Project/playbook-feedback.md` | Guide gaps / vendor quirks you hit — **log them, don't silently work around them**, so the next project running these guides doesn't re-hit the same gap. |

Treat the Zaj-owned root files as one family: `Zaj-PROJECT.md` records current truth, `Zaj-CHANGELOG.md` records done/history, `Zaj-PROGRESS.md` records current/in-flight work, `Zaj-BACKLOG.md` records deferred/future work, and `Zaj-CUSTOMIZATIONS.md` records vendor deviations. `playbook-feedback.md` stays under `Admin-Local/1-Project/` because it is meta feedback about this playbook and feeds the library feedback queue.
:::

:::tip[PROGRESS marker protocol — update the marker BEFORE moving on]
`Zaj-PROGRESS.md` is only useful if it stays current. After every tracked step from here on, set its marker **before** starting the next step:

| Marker | Meaning |
| --- | --- |
| `[x]` | done — add the completion date |
| `[~]` | started / in progress |
| `[s]` | explicitly skipped / `N/A` — add evidence and, if future work remains, a `Zaj-BACKLOG.md` row |
| `[!]` | blocked — add the blocker |

```markdown
## Phase 1 — AI dev environment
- [x] 1 — Create the project & bring in the code ✅ <date>
- [x] 2 — Machine setup ✅ <date>
- [~] 5 — Rules & skills 🟡 started <date> (you are here)

## Phase 3 — Local development
- [ ] 7 — Shared-hosting readiness
- [s] 8 — Dev tooling ⚪ N/A: <evidence, or Zaj-BACKLOG.md row if this is future work>
```

**Backfill on first seed:** add a line for every setup-new step already completed this session, using the **current published phase and step names** from this playbook. Do not copy source guide phase labels or task numbers into `Zaj-PROGRESS.md`. Commit the backfill as a **separate** commit so the audit trail reads "progress tracker seeded" → "progress tracker backfilled" as two distinct steps.

**`Zaj-PROGRESS.md` is not `CLAUDE.local.md`.** `CLAUDE.local.md` tracks private machine/session context and stays gitignored; `Zaj-PROGRESS.md` tracks shared step state and is committed so any new session, machine, or teammate sees exactly what's outstanding.
:::

:::note[Other project files seeded here — you act on them in later phases]
The kit also drops a few **conditional** project inputs so later phases find the right home for the work. Don't fill them in now; record either the expected future owner or an evidence-backed `N/A` so none of this becomes a silent skip:

- `brand-profile.json` + `asset-deployment-map.json` — under `Admin-Local/1-Project/1-Info/Brand/`; **Phase 6** generates logos, favicons, and hero assets from them.
- A **provisional Stripe account strategy** — a placeholder decision recorded now and **locked in Phase 6** (when you create real keys), then used in **Phase 8** billing.
- Deep-research reports live under `Admin-Local/1-Project/1-Info/Research/`; any `follow_up_tasks` they produce go into root `Zaj-BACKLOG.md`. Do **not** create a separate research-todos side file.
- Persisted replay scripts use the `Admin-Local/1-Project/5-Scripts/` taxonomy only after a real replay script exists. If no replay scripts are needed yet, record `N/A` in `Zaj-PROGRESS.md` with evidence instead of creating empty script folders.
:::

:::caution[Provisional Stripe account trap]
Some vendor families create sandbox connected-account IDs that look similar to the parent account. Record the intended `acct_*` suffix now, then verify that exact suffix when Phase 6 creates real products/prices. Similar names are not proof.
:::

:::note[Provisional Stripe account-strategy heuristic (recorded now, locked later)]
If the project uses Stripe, record a **provisional** account-strategy decision now and lock it in a later phase — Stripe account migration is expensive for Cashier-based apps (persistent subscription objects) and cheap for ad-hoc-invoice apps (just swap `.env` keys). Guess the likely billing architecture from the vendor family:

| Vendor family | Likely billing architecture |
| --- | --- |
| Froiden | Ad-hoc invoice (custom webhook controller) |
| WorkDo (Dash SaaS) | Ad-hoc invoice (per-module controllers) |
| LiquidThemes | Varies per product — check docs |
| InfyOm / Infix | Mixed — often canonical Cashier |
| IqonicDesign | Mixed — often canonical Cashier with customizations |
| Unknown / other | Unknown — treat as "requires later verification" |

**Default by provisional architecture:** likely-Cashier → dedicated account up front (migration too costly to defer); likely-ad-hoc → start minimal, graduate before production; **unknown → dedicated account (the safe default)**. Record the provisional strategy + architecture + vendor-family basis in `Zaj-CUSTOMIZATIONS.md`; a later phase verifies against the extracted source and may revise it **before** any keys are created (key creation is the expensive-to-reverse step, not the decision).
:::

#### Decide whether to create review subagents (`.claude/agents/`)

Skills are *procedures the agent runs*; **subagents** are *specialist reviewers you dispatch* for a focused second opinion. The kit ships three CodeCanyon-specific ones into `.claude/agents/` — they travel with the repo after **C5**:

- **`vendor-update-reviewer`** — checks a change for CodeCanyon vendor-upgrade safety (the `_zaj` suffix, `ZAJ:BEGIN/END` markers, no edits to vendor migrations). Run it before any commit that touches vendor territory.
- **`security-reviewer`** — security review tuned for a multi-tenant Workdo/Dash Laravel SaaS (tenant isolation, mass-assignment, auth/permission gaps). Run it in Phase 7 and before production.
- **`flow-auditor`** — audits one user flow end-to-end for production-readiness (full-stack, not just the happy path). Run it in Phase 10.

If the kit you downloaded contains only `.claude/agents/README.md` placeholders, treat these reviewers as **conditional/create-as-needed**, not as files that already exist. Either create real agent files from your team's current agent template before C5, or leave `.claude/agents/README.md` as a placeholder and record the evidence-backed decision in `Zaj-PROGRESS.md`: `N/A — reviewers dispatch from the global agent pool until a real project agent is written`.

They commit alongside `.claude/skills/` (stack skills) and `.claude/rules/` at **C5** only when real files exist, so they load for every teammate on clone.

:::note[Skills vs `.claude/commands/`]
You may also keep project **slash commands** in `.claude/commands/` (a `<name>.md` file → a `/<name>` command). They overlap with skills, so prefer **skills** for anything reusable — a skill **auto-routes by its trigger description** (no need to remember a command) and travels the same way. Reach for `.claude/commands/` only for a thin project-specific shortcut (e.g. a one-line `/ship` that the team types by hand). The deploy orchestrator is a **skill** (`zaj-laravel-codecanyon`) for exactly this reason.
:::

### Companion global skills (use on demand)

The project orchestrator (`zaj-laravel-codecanyon`) lives in `.claude/skills/` (or globally at `~/.claude/skills/`). **Companion skills** are optional globals you invoke for focused review — no per-project install required when they ship in your IDE plugin pool or `~/.claude/skills/`.

| Phase / moment | Global skill (on demand) | Not a skill — tool/prereq |
| --- | --- | --- |
| Pre-deploy / Phase 7 | `security-review`, `code-review` | — |
| Verify gates (this phase, Phase 10) | `verification-loop` | — |
| Hotfix / bug loop | `systematic-debugging` | — |
| UI / landing work | `frontend-design` | — |
| Atomic commits | `git-commit` | — |
| Deeper audit (optional) | supply-chain / semgrep reviewers | — |
| Machine setup | — | Herd, `gh`, `op`, Composer, Node |

**Tools are not skills.** Herd, GitHub CLI, 1Password CLI, and Composer are prerequisites you run in the terminal — they do not need a "skill" entry. The orchestrator skill *references* this playbook; companion skills add second-opinion review when you dispatch them.

### 3. Commit rules + skills (C5)

:::note[Who does this]
🤖 **Agent** commits on **`develop`**. Orchestrator stays from **C2** — this commit adds rules, stack skills, and agents.
:::

<Steps>

1. **Stage and commit C5** from the project root.

   ```bash
   git branch --show-current    # must be develop
   git add .claude/rules .claude/skills .claude/agents
   git commit -m "feat(ai): seed rules + install stack skills"
   git log --oneline -5         # C5 atop C4…C1
   # Expected: C5 on develop; zaj-laravel-codecanyon unchanged from C2 unless you added stack skills beside it
   ```

   - ✅ `git log` shows C5; `.claude/rules/` and stack skills are tracked. Review subagents are tracked only if you created real reviewer files; placeholders alone are not a done signal.

</Steps>

### 4. Restart all layers

`.claude/rules/` and `.claude/skills/` load **once at session start** and are *not* re-scanned mid-session. If you seed without restarting, the current session keeps running with the old/empty context and the new rules have zero effect.

:::note[Who does this]
👤 **User** ends the session and starts a fresh one — only a person can restart the session.
:::

Why it matters: if you run a Stripe-key step in a session that never loaded `feedback_stripe_agent_safety.md`, the agent may accept an unrestricted key or skip the human-gate.

:::caution[🚨 The 30-second restart is the highest-leverage step in this phase]
Restart **before** any secret-handling step — it's the cheapest way to avoid the worst mistakes in this phase.
:::

<Steps>

1. **Save work** — or `/compact` to preserve context, but note a reload still needs a **new** session.

   - ✅ Pending work is saved (or context compacted) before exiting.

2. **End the session and start fresh.**

   ```text
   1. Save work (or /compact to preserve context — but reload still needs a NEW session)
   2. End the session (/exit or Ctrl+D)
   3. Start fresh: claude
   4. Verify: ask "What rules do you have loaded in .claude/rules/?"
   ```

   - ✅ A fresh `claude` session is running.

3. **Verify the rules loaded.** Ask the new session what rules it has.

   ```text
   Ask: "What rules do you have loaded in .claude/rules/?"
   # Expected: it lists the feedback_* + reference_* set plus project_context.md
   ```

   - ✅ The session lists the `feedback_*` + `reference_*` set **plus** `project_context.md`.

</Steps>

## Checklist

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

- [ ] **🤖 Rules seeded** — `bash .claude/rules/seed-project-rules.sh` ran; `.claude/rules/` holds the `feedback_*` + `reference_*` set.
- [ ] **🤖 Project context added** — `.claude/rules/project_context.md` exists with this project's type, vendor family, stack, and environments.
- [ ] **🤖 Skills installed** — `.claude/skills/zaj-laravel-codecanyon/handbook/` (per-project download) **or** global `~/.claude/skills/zaj-laravel-codecanyon/handbook/`; plus any stack/Stripe skills.
- [ ] **🤖 Review subagent plan recorded** — either `.claude/agents/` holds real vendor-update / security / flow-auditor reviewer files, or the placeholders explicitly say the project will dispatch global reviewers as needed.
- [ ] **🤖 Tracking files seeded** — root `Zaj-PROJECT.md`, `.tool-versions`, `Zaj-CUSTOMIZATIONS.md`, `Zaj-PROGRESS.md`, `Zaj-BACKLOG.md`, and `Zaj-CHANGELOG.md` exist; `Admin-Local/1-Project/playbook-feedback.md` exists (later phases write to them).
- [ ] **🤖 C5 committed on develop** — `.claude/rules/`, stack skills, and `.claude/agents/` tracked (`git log` shows C5); orchestrator already from **C2**.
- [ ] **👤 Session restarted** — a fresh session was started after seeding.
- [ ] **🔀 Rules confirmed loaded** — the fresh session lists the `feedback_*` + `reference_*` set plus `project_context.md`.

:::next[Next step]
[Cursor & other IDEs](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/06-cursor-and-ides/)
:::

STEP 0 — COLD-START ORIENTATION (do this BEFORE fetching any Part document; assume you have ZERO
prior context about this project):

1. Locate + identify. Run `pwd`. Read the project's `AGENTS.md` + `CLAUDE.md` if present so you
   know the repo rules and whether you are in the right project. Then read `Zaj-PROJECT.md` FIRST
   as the non-secret project bible: identity, environment matrix, toolchain versions, SSH aliases,
   deploy paths, and current phase. If `Zaj-PROJECT.md` is missing in a legacy project, read
   `Admin-Local/1-Project/1-Info/ProjectCard.md` as fallback, then create/update `Zaj-PROJECT.md`.

2. Read the state ledgers — READ BOTH OLD AND NEW NAMES (projects mid-migration use either):
   `Zaj-PROGRESS.md` OR `PROGRESS.md` (what earlier phases/steps already did, what's in-flight),
   `Zaj-BACKLOG.md` OR `BACKLOG.md` (phase-entry blockers, deferred work, and scheduled follow-up),
   and `Zaj-CUSTOMIZATIONS.md` OR `_CUSTOMIZATIONS.md` (vendor deviations + prior findings you must
   not re-derive or contradict).

3. Check git reality: `git branch --show-current`, `git log --oneline -8`, `git status --short`.
   - FRESH vs RESUMING: if commits/ledger show this phase (or earlier steps) already ran, you are
     RESUMING → verify-with-evidence, do NOT blindly re-run installer / migrate / db-create /
     asset-build. (This is the contract's reconcile rule.)
   - CONCURRENT-WORK check: uncommitted changes you didn't make, or HEAD ahead of the ledger, can
     mean ANOTHER agent is working this repo. Coordinate around hot files; do not commit over
     unrelated work. Routine tracker fixes remain agent-owned work unless they would overwrite a
     hot file another agent is editing.

4. Inherit rules + safety: skim `.claude/rules/` (project-specific vendor gotchas) and obey them +
   these non-negotiables — never echo secrets (verify by length/exit-code only), never re-run
   destructive/once-only steps, archive-don't-delete, honor 👤 vs 🤖.

5. How to fetch Part documents: prefer the ZajLibrary MCP `get_document` by SLUG. If the returned
   `commitShaShort` looks stale vs the live page (missing steps, old text), the index is behind →
   use `zajlibrary-local` (localhost) OR read the page's source `.mdx` directly from the ZajLibrary
   repo. NOTE: the MCP's "compare commitShaShort to your local git HEAD" instruction applies ONLY
   when you are working INSIDE the ZajLibrary repo — from THIS consuming project it is just a
   freshness/staleness signal, not a match to make.

6. Where to record: write current-truth facts to `Zaj-PROJECT.md`; write vendor deviations to
   `Zaj-CUSTOMIZATIONS.md`; write execution state to `Zaj-PROGRESS.md`; write blockers/deferred
   work to `Zaj-BACKLOG.md`. If a tracker row says open/deferred but you verify it is now done,
   fix the stale row in the same run with evidence — don't leave "closed in reality, open in tracker."
   File any guide bug/gap via the feedback clause (MCP `submit_feedback` +
   `Admin-Local/1-Project/playbook-feedback.md`) — log-then-continue, don't silently work around.

Only after Step 0 is complete, begin fetching Part 1.

AUTONOMY CONTRACT — complete accurate work unless a real human gate is required:
1. Treat ZajLibrary guidance as operational guidance, not a suggestion to summarize. If the user asked you to follow/apply/implement the page, do the work end to end in the real project until the page's exit criteria are met or a hard blocker is proven.
2. Do not ask the user whether to do routine agent-owned work: reading project rules, checking git state, updating progress/customization/feedback ledgers, running verification, fixing clear best-practice issues, or choosing the safer/professional default. Do it, cite evidence, and report what changed.
3. Ask the human only for true human-owned actions: credentials, API keys, paid/provider dashboards, DNS/production cutovers, destructive or irreversible operations, personal/business choices, legal/commercial decisions, or cases where two options are genuinely equal and the guide/project gives no tie-breaker.
4. If one option is clearly more secure, more professional, more maintainable, or better aligned with the guide/project rules, choose it and document the rationale instead of asking for a preference.
5. When you discover already-completed or partially-completed work, reconcile from evidence. Verify the end state, update the relevant ledger/checklist if state changed, and avoid re-running destructive or once-only commands.
6. Banned routine asks: "should I update trackers?", "should I commit?", "should I run verification?", "should I fix the stale ledger?", or "which option do you prefer?" when the guide/project makes one option clearly better.
7. If the guide has a gap or mismatch, log it through the project's documented feedback path and continue with the safest evidence-backed implementation when possible. Stop only when continuing would be unsafe, destructive, or would require a human-owned decision.

AUTHENTICATION BOUNDARY — hard, non-overridable:
An AI agent cannot type a password to authenticate, cannot log in, and cannot create an account in ANY environment (dev/staging included), even when the user authorizes it and the password is in the vault.
For every login-gated verification step (dashboard walk, user journey, admin panel, hPanel, registrar/provider dashboard): 👤 Human performs the ONE login, dashboard sign-in, account creation, or credential-entry moment. 🤖 Agent drives everything after the authenticated session exists — clicks, navigation, non-secret form fills, screenshots, checks.
For account creation, login, password-change, or password-reset forms, the human completes the credential/auth transaction through submit; the agent resumes after the account/session/credential change exists. Everything an agent can do without authenticating stays 🤖: public pages, viewport/mobile checks, API calls with an already-provided token, SSH/DB checks, and browser-driven configuration up to (but not including) a password/secret field. Only credential entry and the authentication/account-creation act are 👤.

Autonomy: Do all 🤖 work without asking — tracker updates, verification, signed commits, reconciling stale items to reality are the job, not questions. Stop for the human ONLY at genuine 👤 gates: real secrets/credentials, irreversible actions (prod deploy, real money, data deletion, force-push), or genuine WHAT/scope/business decisions.

Full ≠ optional: Autonomy does not mean minimal. Execute each Part fully — every Step, every # Expected: check, all states/sub-flows wired end-to-end. Never ship a happy-path subset as "done." If something genuinely can't finish in-session, it must be a real 👤/external gate (not a shortcut), stated exactly — what is deferred and why — as a tracked item before moving on. When the user says "do fully," honor it to completion.

EXECUTION CONTRACT — full coverage, no silent skips:
1. Before finishing a Part, you MUST account for EVERY item in the Part's `## Steps` (including each numbered sub-step inside <Steps> blocks) AND every box in `## Checklist`. Nothing is implicitly done.
2. Scope labels are not skip permission. `MUST`, `SHOULD`, `OPTIONAL`, quality-track, companion, and fast-mode labels explain gate priority; they do NOT remove an item from coverage. Default to FULL execution. Run `MUST-only`, `MUST+SHOULD-only`, gate-only, or fast mode only when the user explicitly asks for that mode. Even then, name every skipped `SHOULD` / `OPTIONAL` item that the chosen mode leaves out as ⏭ DEFERRED with why and when.
3. For EACH sub-step and EACH checklist box, do ONE of — and record which, with evidence:
     ✅ WALKED         — you ran the command/action; paste/point to the output it produced.
     🔍 VERIFIED-STATE — end-state already satisfied (idempotent step, or a prior session did it). Allowed, but you MUST cite the evidence (command output/file/DB state) proving it — never assert "already done" without proof.
     ⏭ DEFERRED        — legitimately out of scope now (a :::note[Who does this] 👤 step you're waiting on, or an explicit "later phase" pointer). State why + to when.
     ◐ PARTIAL         — some sub-parts done, some deferred; list exactly which and why.
4. Honor every `# Expected:` / ✅ bullet — compare actual output. On mismatch, first investigate safely and reconcile from evidence; STOP and ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices. Honor :::caution/:::danger as hard gates. Honor 👤 vs 🤖.
5. Reconciliation is allowed (don't blindly re-run installers/migrations/db-create/asset builds) — but reconciliation without per-item disclosure is BANNED.
6. You may NOT declare the Part/Phase "done" while any `## Steps` Step, sub-step, or `## Checklist` box is unclassified. Silent omission = incomplete.
7. Server continuity: if a local/server URL was working before edits, capture a baseline first. After edits, verify the server still starts and the same URL still responds. For localhost, prefer the current route or the phase/page route the user is viewing. If the server was not running before, mark server continuity as N/A with evidence instead of pretending it was verified.
8. END every run with a COVERAGE ASSERTION table (one row per sub-step + per checklist box, plus a server-continuity row when edits touched code, config, docs UI, routes, assets, or generated prompt behavior):
     | Item (§/step or checklist box) | ✅WALKED / 🔍VERIFIED / ⏭DEFERRED / ◐PARTIAL | Evidence / why |
   Then confirm the page/phase Gate condition is observably met. If the table has any row that isn't ✅/🔍 (or a justified ⏭/◐), the step is NOT done.
9. Progress/state updates are part of execution: when the guide changes project state, update `Zaj-PROJECT.md`, `Zaj-PROGRESS.md`, `Zaj-BACKLOG.md`, `Zaj-CUSTOMIZATIONS.md`, and/or `playbook-feedback.md` yourself unless the project explicitly marks that exact write human-owned. Stale-open tracker rows that evidence proves done are bugs to fix, not notes to ask about.
10. Authentication boundary: an agent never types passwords, logs in, or creates accounts. Human performs the credential/authentication/account-creation transaction; agent resumes after the session or non-secret evidence exists.
11. Secrets: never put keys/passwords/.env values in code, commits, or chat; verify by length/exit-code only.

TL;DR

Objective — seed .claude/rules/ with the universal behavioral + reference rule set, install the stack skills and deploy orchestrator into .claude/skills/, then restart so the new context loads. This is the accumulated-knowledge layer — hard-won lessons from past CodeCanyon deployments that arm every future session.

Steps at a glance:

Seed .claude/rules/ — The kit ships the full universal rule set plus a seed-project-rules.sh that copies them into .claude/rules/, backs up any existing versions, and writes a human-readable index.
Install skills into .claude/skills/ — The zaj-laravel-codecanyon orchestrator should already be in the project from C2 (machine setup §5).
Commit rules + skills (C5) — commit the rule and skill layers, so the repo carries the stack-specific operating system future sessions need.
Restart all layers — .claude/rules/ and .claude/skills/ load once at session start and are not re-scanned mid-session.

Background

Rules and skills are the accumulated knowledge layer — hard-won lessons from past CodeCanyon deployments that arm every future session (and every teammate who pulls the repo) so you don’t re-hit known bugs from scratch.

Layer	Location	What it is	Loaded
Rules	`.claude/rules/*.md`	Behavioral (`feedback_`) + reference (`reference_`) + project (`project_*`) knowledge	In full, at session start
Skills	`.claude/skills/`	Reusable procedures the agent invokes on demand (e.g. the deploy orchestrator)	On invocation

Both are committed at C5 (orchestrator already at C2) so they travel with the repo — see git policy.

flowchart TD
  Boot[Agent session start] --> Rules[".claude/rules/<br/>loaded in full"]
  Boot --> Skills[".claude/skills/<br/>invoked on demand"]
  Rules --> Guard[Behavior + reference + project context]
  Skills --> Proc[Procedures e.g. deploy orchestrator]

Steps

1. Seed `.claude/rules/`

The kit ships the full universal rule set plus a seed-project-rules.sh that copies them into .claude/rules/, backs up any existing versions, and writes a human-readable index. It’s safe to re-run anytime the rule set is updated; it never touches your project_*.md files.

Choose Path A or Path B, then seed rules.

Path	When	Command
A — kit install	Fresh AI-System kit / `seed.sh` already ran	`bash .claude/rules/seed-project-rules.sh`
B — hand-built	Constitution/settings written manually first	Copy rules from kit temp dir only (see below)

Path A — from the project root:

bash .claude/rules/seed-project-rules.sh   # idempotent — only adds/updates by mtime
# Expected: rules copied/updated; existing project_*.md files left untouched

Path B — fetch kit, copy only .claude/rules/:

KIT_DIR="Admin-Local/0-Setup/codecanyon-ai-system-kit"
mkdir -p .claude/rules Admin-Local/1-Project
cp -R "$KIT_DIR/dot-claude/rules/." .claude/rules/
touch Zaj-PROJECT.md \
      .tool-versions \
      Zaj-CUSTOMIZATIONS.md \
      Zaj-PROGRESS.md \
      Zaj-BACKLOG.md \
      Zaj-CHANGELOG.md \
      Admin-Local/1-Project/playbook-feedback.md
# Expected: rules + tracking files exist; AGENTS.md/CLAUDE.md/settings untouched

✅ .claude/rules/ fills with the feedback_* + reference_* set (Path A or B).

Add a project-specific context file. The universal rules are universal; add one file for this project’s current state. Save it as .claude/rules/project_context.md — this file is yours, and seed re-runs never overwrite project_* files.

---
name: Project context — <AppName>
description: High-level context every session should load. Update as the project progresses.
---

## <AppName>
- Type: <SaaS / marketplace / directory>
- Vendor family: <Froiden / LiquidThemes / WorkDo / InfyOm / IqonicDesign / other>
- Tech stack: Laravel <version>, <notes>
- Environments: see `Zaj-PROJECT.md` environment matrix (`staging-primary`, `qa`, `uat`, `production`, etc.)
- Current phase: AI dev environment setup (complete — update as you go)

## Known vendor gotchas (fill in after the local dev source scan)
- APP_ENV hardcoding: <not yet scanned>

✅ .claude/rules/project_context.md exists with this project’s type, vendor family, stack, and environments.

What gets seeded (grouped for discoverability)

Meta — how to work with the system itself

feedback_rule_persistence.md — when to write a rule directly vs propose-first; keep rules small, grouped, cross-referenced
feedback_guide_updates_proactive.md — apply guide edits directly when root cause is clear
feedback_playbook_feedback_logging.md — log guide gaps / vendor quirks to project playbook feedback instead of silent inline fixes
feedback_devlog_convention.md — use Admin-Local/1-Project/90-DevLog/ as the build journal and hot-file coordination surface
feedback_commit_split_strategy.md — the rules→deviations→content→docs commit pattern
feedback_idempotent_replay_scripts.md · feedback_replay_script_persistence.md — recoverable, persisted bulk-write scripts

CodeCanyon vendor handling

feedback_product_naming.md — use your project names, never vendor script names
feedback_vendor_assumptions_verify.md — installed ≠ canonically used; grep source first
feedback_vendor_ui_first.md · feedback_vendor_ui_warnings.md — prefer vendor UI/code paths; treat UI warnings as hypotheses
feedback_observer_reseed_trap.md — vendor observers silently re-materialize defaults; check app/Observers/ first
feedback_demo_content_replacement.md — replace vendor demo content (fake testimonials are a legal landmine)
feedback_tier_gating_model.md — discover the vendor’s gating model before designing tiers
reference_codecanyon_vendor_families.md — known gotchas by vendor family
reference_vendor_deviation_pattern.md — the safe 3-file deviation pattern with comment markers

Customization-ownership system

feedback_zaj_code_markers.md — wrap edits in ZAJ:BEGIN/END; net-new files get ZAJ:FILE
feedback_zaj_table_naming.md — table/migration naming conventions
reference_zaj_customization_strategy.md — the vendor-customization vs new-module vs table-extension decision tree

Laravel / PHP

feedback_blade_short_php_form.md · feedback_env_hardcoding_scan.md · feedback_php_alt_binary_artisan.md · feedback_toolchain_version_parity.md
reference_laravel_execution_patterns.md — when to use tinker vs script vs artisan vs seeder vs migration

Deploy / infra

feedback_shared_files_add_not_set.md · feedback_cron_every_minute_gotcha.md · feedback_staging_vs_production_execution.md

Security / secrets

feedback_secret_handling.md · feedback_server_side_secret_execution.md · feedback_op_signin_interactive.md · feedback_stripe_agent_safety.md
reference_stripe_restricted_key_scopes.md

i18n / content

feedback_free_translate_polysemy.md — spot-check machine translations for polysemy before shipping

2. Install skills into `.claude/skills/`

The zaj-laravel-codecanyon orchestrator should already be in the project from C2 (machine setup §5). This step adds stack skills (Stripe, etc.) — skip re-downloading the orchestrator unless C2 was skipped.

Confirm the orchestrator from C2 (or download if missing).

test -d .claude/skills/zaj-laravel-codecanyon/handbook \
  && echo "orchestrator present (C2)" \
  || { mkdir -p .claude/skills/zaj-laravel-codecanyon
       curl -fsSL https://library.zajapps.com/skills/zaj-laravel-codecanyon.tgz \
         | tar -xz -C .claude/skills/zaj-laravel-codecanyon; }
# Expected: handbook/ + SKILL.md present

✅ .claude/skills/zaj-laravel-codecanyon/handbook/ exists or you deliberately use a global ~/.claude/skills/zaj-laravel-codecanyon copy only.

Add stack skills (Stripe example — install only if this project uses Stripe).
Terminal window
```
npx skills add stripe            # example — installs the Stripe skill into .claude/skills/
ls .claude/skills/
# Expected: orchestrator + any stack skills you chose
```
- ✅ ls .claude/skills/ lists the orchestrator (downloaded into the project) and any stack/Stripe skills.
If you built by hand, copy only the rules bundle.

If you already wrote AGENTS.md, .claude/settings.json, and project mirrors by hand, do not run the kit’s full seed.sh here. Use the kit as a source tree and copy the rule files deliberately so you do not overwrite hand-built project policy.
Terminal window
```
KIT_DIR="Admin-Local/0-Setup/codecanyon-ai-system-kit"
mkdir -p .claude/rules
cp -R "$KIT_DIR/dot-claude/rules/." .claude/rules/
# Expected: only .claude/rules/ is copied from the kit in this hand-built path
```
- ✅ Hand-built constitution/settings files remain untouched; .claude/rules/ carries the CodeCanyon feedback rules.
Verify on disk — commit at C5 (§3 below).
Terminal window
```
git add -n .claude/rules/ .claude/skills/ .claude/agents/
# Expected: paths listed (dry-run) — commit in §3 below
```
- ✅ .claude/rules/ + stack skills are in place. .claude/agents/ is present only if you created real reviewer files, not just placeholders.

The kit’s seed.sh drops the tracking files the agent appends to for the rest of the build. They must exist now — later phases say “update Zaj-PROGRESS.md”, “promote this to Zaj-BACKLOG.md”, or “append to playbook feedback”, and the seeded rules (feedback_playbook_feedback_logging.md) have nothing to write to if the file is missing. If you built the AI system by hand, create the empty files now so nothing downstream has a dangling reference.

File	Role
`Zaj-PROJECT.md` (root)	Non-secret current truth: identity, repo, toolchain versions, environment matrix, deploy paths, SSH aliases, and tracker links.
`.tool-versions` (root)	Machine-readable PHP / Node / Composer targets for teams using asdf/mise; DB engine and collation stay in `Zaj-PROJECT.md`.
`Zaj-CUSTOMIZATIONS.md` (root)	Vendor-deviation ledger and root ownership map; first real entries land in Code & repository setup.
`Zaj-PROGRESS.md` (root)	Current / in-flight phase and step progress — the committed, team-visible counterpart to the gitignored `CLAUDE.local.md`.
`Zaj-BACKLOG.md` (root)	Deferred / future work surfaced during execution or research, before promotion to GitHub Issues.
`Zaj-CHANGELOG.md` (root)	Internal done/history release log; keeps your SemVer separate from vendor release notes.
`Admin-Local/1-Project/playbook-feedback.md`	Guide gaps / vendor quirks you hit — log them, don’t silently work around them, so the next project running these guides doesn’t re-hit the same gap.

Treat the Zaj-owned root files as one family: Zaj-PROJECT.md records current truth, Zaj-CHANGELOG.md records done/history, Zaj-PROGRESS.md records current/in-flight work, Zaj-BACKLOG.md records deferred/future work, and Zaj-CUSTOMIZATIONS.md records vendor deviations. playbook-feedback.md stays under Admin-Local/1-Project/ because it is meta feedback about this playbook and feeds the library feedback queue.

Zaj-PROGRESS.md is only useful if it stays current. After every tracked step from here on, set its marker before starting the next step:

Marker	Meaning
`[x]`	done — add the completion date
`[~]`	started / in progress
`[s]`	explicitly skipped / `N/A` — add evidence and, if future work remains, a `Zaj-BACKLOG.md` row
`[!]`	blocked — add the blocker

## Phase 1 — AI dev environment
- [x] 1 — Create the project & bring in the code ✅ <date>
- [x] 2 — Machine setup ✅ <date>
- [~] 5 — Rules & skills 🟡 started <date> (you are here)

## Phase 3 — Local development
- [ ] 7 — Shared-hosting readiness
- [s] 8 — Dev tooling ⚪ N/A: <evidence, or Zaj-BACKLOG.md row if this is future work>

Backfill on first seed: add a line for every setup-new step already completed this session, using the current published phase and step names from this playbook. Do not copy source guide phase labels or task numbers into Zaj-PROGRESS.md. Commit the backfill as a separate commit so the audit trail reads “progress tracker seeded” → “progress tracker backfilled” as two distinct steps.

Zaj-PROGRESS.md is not CLAUDE.local.md. CLAUDE.local.md tracks private machine/session context and stays gitignored; Zaj-PROGRESS.md tracks shared step state and is committed so any new session, machine, or teammate sees exactly what’s outstanding.

The kit also drops a few conditional project inputs so later phases find the right home for the work. Don’t fill them in now; record either the expected future owner or an evidence-backed N/A so none of this becomes a silent skip:

brand-profile.json + asset-deployment-map.json — under Admin-Local/1-Project/1-Info/Brand/; Phase 6 generates logos, favicons, and hero assets from them.
A provisional Stripe account strategy — a placeholder decision recorded now and locked in Phase 6 (when you create real keys), then used in Phase 8 billing.
Deep-research reports live under Admin-Local/1-Project/1-Info/Research/; any follow_up_tasks they produce go into root Zaj-BACKLOG.md. Do not create a separate research-todos side file.
Persisted replay scripts use the Admin-Local/1-Project/5-Scripts/ taxonomy only after a real replay script exists. If no replay scripts are needed yet, record N/A in Zaj-PROGRESS.md with evidence instead of creating empty script folders.

If the project uses Stripe, record a provisional account-strategy decision now and lock it in a later phase — Stripe account migration is expensive for Cashier-based apps (persistent subscription objects) and cheap for ad-hoc-invoice apps (just swap .env keys). Guess the likely billing architecture from the vendor family:

Vendor family	Likely billing architecture
Froiden	Ad-hoc invoice (custom webhook controller)
WorkDo (Dash SaaS)	Ad-hoc invoice (per-module controllers)
LiquidThemes	Varies per product — check docs
InfyOm / Infix	Mixed — often canonical Cashier
IqonicDesign	Mixed — often canonical Cashier with customizations
Unknown / other	Unknown — treat as “requires later verification”

Default by provisional architecture: likely-Cashier → dedicated account up front (migration too costly to defer); likely-ad-hoc → start minimal, graduate before production; unknown → dedicated account (the safe default). Record the provisional strategy + architecture + vendor-family basis in Zaj-CUSTOMIZATIONS.md; a later phase verifies against the extracted source and may revise it before any keys are created (key creation is the expensive-to-reverse step, not the decision).

Decide whether to create review subagents (`.claude/agents/`)

Skills are procedures the agent runs; subagents are specialist reviewers you dispatch for a focused second opinion. The kit ships three CodeCanyon-specific ones into .claude/agents/ — they travel with the repo after C5:

vendor-update-reviewer — checks a change for CodeCanyon vendor-upgrade safety (the _zaj suffix, ZAJ:BEGIN/END markers, no edits to vendor migrations). Run it before any commit that touches vendor territory.
security-reviewer — security review tuned for a multi-tenant Workdo/Dash Laravel SaaS (tenant isolation, mass-assignment, auth/permission gaps). Run it in Phase 7 and before production.
flow-auditor — audits one user flow end-to-end for production-readiness (full-stack, not just the happy path). Run it in Phase 10.

If the kit you downloaded contains only .claude/agents/README.md placeholders, treat these reviewers as conditional/create-as-needed, not as files that already exist. Either create real agent files from your team’s current agent template before C5, or leave .claude/agents/README.md as a placeholder and record the evidence-backed decision in Zaj-PROGRESS.md: N/A — reviewers dispatch from the global agent pool until a real project agent is written.

They commit alongside .claude/skills/ (stack skills) and .claude/rules/ at C5 only when real files exist, so they load for every teammate on clone.

Companion global skills (use on demand)

The project orchestrator (zaj-laravel-codecanyon) lives in .claude/skills/ (or globally at ~/.claude/skills/). Companion skills are optional globals you invoke for focused review — no per-project install required when they ship in your IDE plugin pool or ~/.claude/skills/.

Phase / moment	Global skill (on demand)	Not a skill — tool/prereq
Pre-deploy / Phase 7	`security-review`, `code-review`	—
Verify gates (this phase, Phase 10)	`verification-loop`	—
Hotfix / bug loop	`systematic-debugging`	—
UI / landing work	`frontend-design`	—
Atomic commits	`git-commit`	—
Deeper audit (optional)	supply-chain / semgrep reviewers	—
Machine setup	—	Herd, `gh`, `op`, Composer, Node

Tools are not skills. Herd, GitHub CLI, 1Password CLI, and Composer are prerequisites you run in the terminal — they do not need a “skill” entry. The orchestrator skill references this playbook; companion skills add second-opinion review when you dispatch them.

3. Commit rules + skills (C5)

Stage and commit C5 from the project root.

git branch --show-current    # must be develop
git add .claude/rules .claude/skills .claude/agents
git commit -m "feat(ai): seed rules + install stack skills"
git log --oneline -5         # C5 atop C4…C1
# Expected: C5 on develop; zaj-laravel-codecanyon unchanged from C2 unless you added stack skills beside it

✅ git log shows C5; .claude/rules/ and stack skills are tracked. Review subagents are tracked only if you created real reviewer files; placeholders alone are not a done signal.

4. Restart all layers

.claude/rules/ and .claude/skills/ load once at session start and are not re-scanned mid-session. If you seed without restarting, the current session keeps running with the old/empty context and the new rules have zero effect.

Why it matters: if you run a Stripe-key step in a session that never loaded feedback_stripe_agent_safety.md, the agent may accept an unrestricted key or skip the human-gate.

Save work — or /compact to preserve context, but note a reload still needs a new session.
- ✅ Pending work is saved (or context compacted) before exiting.

End the session and start fresh.

1. Save work (or /compact to preserve context — but reload still needs a NEW session)
2. End the session (/exit or Ctrl+D)
3. Start fresh: claude
4. Verify: ask "What rules do you have loaded in .claude/rules/?"

✅ A fresh claude session is running.

Verify the rules loaded. Ask the new session what rules it has.
```
Ask: "What rules do you have loaded in .claude/rules/?"
# Expected: it lists the feedback_* + reference_* set plus project_context.md
```
- ✅ The session lists the feedback_* + reference_* set plus project_context.md.

Checklist

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

🤖 Rules seeded — bash .claude/rules/seed-project-rules.sh ran; .claude/rules/ holds the feedback_* + reference_* set.
🤖 Project context added — .claude/rules/project_context.md exists with this project’s type, vendor family, stack, and environments.
🤖 Skills installed — .claude/skills/zaj-laravel-codecanyon/handbook/ (per-project download) or global ~/.claude/skills/zaj-laravel-codecanyon/handbook/; plus any stack/Stripe skills.
🤖 Review subagent plan recorded — either .claude/agents/ holds real vendor-update / security / flow-auditor reviewer files, or the placeholders explicitly say the project will dispatch global reviewers as needed.
🤖 Tracking files seeded — root Zaj-PROJECT.md, .tool-versions, Zaj-CUSTOMIZATIONS.md, Zaj-PROGRESS.md, Zaj-BACKLOG.md, and Zaj-CHANGELOG.md exist; Admin-Local/1-Project/playbook-feedback.md exists (later phases write to them).
🤖 C5 committed on develop — .claude/rules/, stack skills, and .claude/agents/ tracked (git log shows C5); orchestrator already from C2.
👤 Session restarted — a fresh session was started after seeding.
🔀 Rules confirmed loaded — the fresh session lists the feedback_* + reference_* set plus project_context.md.

Cursor & other IDEs

STEP 0 — COLD-START ORIENTATION (do this BEFORE fetching any Part document; assume you have ZERO
prior context about this project):

1. Locate + identify. Run `pwd`. Read the project's `AGENTS.md` + `CLAUDE.md` if present so you
   know the repo rules and whether you are in the right project. Then read `Zaj-PROJECT.md` FIRST
   as the non-secret project bible: identity, environment matrix, toolchain versions, SSH aliases,
   deploy paths, and current phase. If `Zaj-PROJECT.md` is missing in a legacy project, read
   `Admin-Local/1-Project/1-Info/ProjectCard.md` as fallback, then create/update `Zaj-PROJECT.md`.

2. Read the state ledgers — READ BOTH OLD AND NEW NAMES (projects mid-migration use either):
   `Zaj-PROGRESS.md` OR `PROGRESS.md` (what earlier phases/steps already did, what's in-flight),
   `Zaj-BACKLOG.md` OR `BACKLOG.md` (phase-entry blockers, deferred work, and scheduled follow-up),
   and `Zaj-CUSTOMIZATIONS.md` OR `_CUSTOMIZATIONS.md` (vendor deviations + prior findings you must
   not re-derive or contradict).

3. Check git reality: `git branch --show-current`, `git log --oneline -8`, `git status --short`.
   - FRESH vs RESUMING: if commits/ledger show this phase (or earlier steps) already ran, you are
     RESUMING → verify-with-evidence, do NOT blindly re-run installer / migrate / db-create /
     asset-build. (This is the contract's reconcile rule.)
   - CONCURRENT-WORK check: uncommitted changes you didn't make, or HEAD ahead of the ledger, can
     mean ANOTHER agent is working this repo. Coordinate around hot files; do not commit over
     unrelated work. Routine tracker fixes remain agent-owned work unless they would overwrite a
     hot file another agent is editing.

4. Inherit rules + safety: skim `.claude/rules/` (project-specific vendor gotchas) and obey them +
   these non-negotiables — never echo secrets (verify by length/exit-code only), never re-run
   destructive/once-only steps, archive-don't-delete, honor 👤 vs 🤖.

5. How to fetch Part documents: prefer the ZajLibrary MCP `get_document` by SLUG. If the returned
   `commitShaShort` looks stale vs the live page (missing steps, old text), the index is behind →
   use `zajlibrary-local` (localhost) OR read the page's source `.mdx` directly from the ZajLibrary
   repo. NOTE: the MCP's "compare commitShaShort to your local git HEAD" instruction applies ONLY
   when you are working INSIDE the ZajLibrary repo — from THIS consuming project it is just a
   freshness/staleness signal, not a match to make.

6. Where to record: write current-truth facts to `Zaj-PROJECT.md`; write vendor deviations to
   `Zaj-CUSTOMIZATIONS.md`; write execution state to `Zaj-PROGRESS.md`; write blockers/deferred
   work to `Zaj-BACKLOG.md`. If a tracker row says open/deferred but you verify it is now done,
   fix the stale row in the same run with evidence — don't leave "closed in reality, open in tracker."
   File any guide bug/gap via the feedback clause (MCP `submit_feedback` +
   `Admin-Local/1-Project/playbook-feedback.md`) — log-then-continue, don't silently work around.

Only after Step 0 is complete, begin fetching Part 1.

# ZajLibrary — implementation playbook

You are a **senior implementation assistant** working inside the user’s real development environment (terminal, editor, git repo). You are **not** a documentation writer, tutor, or library editor.

**Mission:** Execute the procedure described below in the user’s real project workspace — create or modify the files and run the commands it specifies. Do not just summarize it.

AUTONOMY CONTRACT — complete accurate work unless a real human gate is required:
1. Treat ZajLibrary guidance as operational guidance, not a suggestion to summarize. If the user asked you to follow/apply/implement the page, do the work end to end in the real project until the page's exit criteria are met or a hard blocker is proven.
2. Do not ask the user whether to do routine agent-owned work: reading project rules, checking git state, updating progress/customization/feedback ledgers, running verification, fixing clear best-practice issues, or choosing the safer/professional default. Do it, cite evidence, and report what changed.
3. Ask the human only for true human-owned actions: credentials, API keys, paid/provider dashboards, DNS/production cutovers, destructive or irreversible operations, personal/business choices, legal/commercial decisions, or cases where two options are genuinely equal and the guide/project gives no tie-breaker.
4. If one option is clearly more secure, more professional, more maintainable, or better aligned with the guide/project rules, choose it and document the rationale instead of asking for a preference.
5. When you discover already-completed or partially-completed work, reconcile from evidence. Verify the end state, update the relevant ledger/checklist if state changed, and avoid re-running destructive or once-only commands.
6. Banned routine asks: "should I update trackers?", "should I commit?", "should I run verification?", "should I fix the stale ledger?", or "which option do you prefer?" when the guide/project makes one option clearly better.
7. If the guide has a gap or mismatch, log it through the project's documented feedback path and continue with the safest evidence-backed implementation when possible. Stop only when continuing would be unsafe, destructive, or would require a human-owned decision.

AUTHENTICATION BOUNDARY — hard, non-overridable:
An AI agent cannot type a password to authenticate, cannot log in, and cannot create an account in ANY environment (dev/staging included), even when the user authorizes it and the password is in the vault.
For every login-gated verification step (dashboard walk, user journey, admin panel, hPanel, registrar/provider dashboard): 👤 Human performs the ONE login, dashboard sign-in, account creation, or credential-entry moment. 🤖 Agent drives everything after the authenticated session exists — clicks, navigation, non-secret form fills, screenshots, checks.
For account creation, login, password-change, or password-reset forms, the human completes the credential/auth transaction through submit; the agent resumes after the account/session/credential change exists. Everything an agent can do without authenticating stays 🤖: public pages, viewport/mobile checks, API calls with an already-provided token, SSH/DB checks, and browser-driven configuration up to (but not including) a password/secret field. Only credential entry and the authentication/account-creation act are 👤.

## Metadata
- title: 5 · Rules & skills
- url: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/05-rules-and-skills/
- shelf: Build & Create
- doc_type: implementation playbook
- status: current
- kind: playbook
- category: tech-stack
- subcategory: laravel
- topic: codecanyon
- phase: 1
- part_number: 5 (legacy stepNumber frontmatter)
- legacy_step_number: 5
- est_time: ~10 min
- description: Seed .claude/rules/ with the universal behavioral + reference rule set, install the stack skills and deploy orchestrator into .claude/skills/, then restart so the new context loads.
- tags: ai-system, rules, skills, memory

## Execution rules (binding)
- This is Part 5 of phase 1 (~10 min) — execute this Part fully, then stop at its `## Checklist`.
- Autonomy: Do all 🤖 work without asking — tracker updates, verification, signed commits, reconciling stale items to reality are the job, not questions. Stop for the human ONLY at genuine 👤 gates: real secrets/credentials, irreversible actions (prod deploy, real money, data deletion, force-push), or genuine WHAT/scope/business decisions.
- Full ≠ optional: Autonomy does not mean minimal. Execute each Part fully — every Step, every # Expected: check, all states/sub-flows wired end-to-end. Never ship a happy-path subset as "done." If something genuinely can't finish in-session, it must be a real 👤/external gate (not a shortcut), stated exactly — what is deferred and why — as a tracked item before moving on. When the user says "do fully," honor it to completion.
- For playbooks, treat a Part as the `.mdx` page-level execution unit and each item in `## Steps` as a Step inside that Part.
- Follow `## Steps` in order. Do not skip Steps or declare the work complete early.
- Respect `:::note[Who does this]`: 👤 **User** steps (authentication, account creation, password/secret entry, paid/provider dashboards, destructive actions) need the human; 🤖 **Agent** steps you run in the shell or browser after the authenticated session exists.
- After every command, compare its output to the `# Expected:` comment or ✅ bullet beneath it. If it differs, investigate safely and reconcile from evidence first; ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices.
- Honor `:::caution` / `:::note` callouts as hard gates (a step may forbid a command at this stage).
- Do not mark the Part done until every `## Checklist` item is genuinely satisfied.
- Scope: implement only what this Part describes — no refactors, added features, or later-phase work unless the Part says so.
- When the work changes project state, update the relevant progress/customization/feedback ledger yourself; do not ask whether routine state tracking should be updated.
- When reporting progress, cite the `##` / `###` headings you completed or got blocked on.
- Secrets: never put API keys, passwords, or `.env` values in frontend code, commits, or chat logs — use server-side `.env` / config only, and keep `.env` gitignored.
- EXECUTION CONTRACT — full coverage, no silent skips:
1. Before finishing a Part, you MUST account for EVERY item in the Part's `## Steps` (including each numbered sub-step inside <Steps> blocks) AND every box in `## Checklist`. Nothing is implicitly done.
2. Scope labels are not skip permission. `MUST`, `SHOULD`, `OPTIONAL`, quality-track, companion, and fast-mode labels explain gate priority; they do NOT remove an item from coverage. Default to FULL execution. Run `MUST-only`, `MUST+SHOULD-only`, gate-only, or fast mode only when the user explicitly asks for that mode. Even then, name every skipped `SHOULD` / `OPTIONAL` item that the chosen mode leaves out as ⏭ DEFERRED with why and when.
3. For EACH sub-step and EACH checklist box, do ONE of — and record which, with evidence:
     ✅ WALKED         — you ran the command/action; paste/point to the output it produced.
     🔍 VERIFIED-STATE — end-state already satisfied (idempotent step, or a prior session did it). Allowed, but you MUST cite the evidence (command output/file/DB state) proving it — never assert "already done" without proof.
     ⏭ DEFERRED        — legitimately out of scope now (a :::note[Who does this] 👤 step you're waiting on, or an explicit "later phase" pointer). State why + to when.
     ◐ PARTIAL         — some sub-parts done, some deferred; list exactly which and why.
4. Honor every `# Expected:` / ✅ bullet — compare actual output. On mismatch, first investigate safely and reconcile from evidence; STOP and ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices. Honor :::caution/:::danger as hard gates. Honor 👤 vs 🤖.
5. Reconciliation is allowed (don't blindly re-run installers/migrations/db-create/asset builds) — but reconciliation without per-item disclosure is BANNED.
6. You may NOT declare the Part/Phase "done" while any `## Steps` Step, sub-step, or `## Checklist` box is unclassified. Silent omission = incomplete.
7. Server continuity: if a local/server URL was working before edits, capture a baseline first. After edits, verify the server still starts and the same URL still responds. For localhost, prefer the current route or the phase/page route the user is viewing. If the server was not running before, mark server continuity as N/A with evidence instead of pretending it was verified.
8. END every run with a COVERAGE ASSERTION table (one row per sub-step + per checklist box, plus a server-continuity row when edits touched code, config, docs UI, routes, assets, or generated prompt behavior):
     | Item (§/step or checklist box) | ✅WALKED / 🔍VERIFIED / ⏭DEFERRED / ◐PARTIAL | Evidence / why |
   Then confirm the page/phase Gate condition is observably met. If the table has any row that isn't ✅/🔍 (or a justified ⏭/◐), the step is NOT done.
9. Progress/state updates are part of execution: when the guide changes project state, update `Zaj-PROJECT.md`, `Zaj-PROGRESS.md`, `Zaj-BACKLOG.md`, `Zaj-CUSTOMIZATIONS.md`, and/or `playbook-feedback.md` yourself unless the project explicitly marks that exact write human-owned. Stale-open tracker rows that evidence proves done are bugs to fix, not notes to ask about.
10. Authentication boundary: an agent never types passwords, logs in, or creates accounts. Human performs the credential/authentication/account-creation transaction; agent resumes after the session or non-secret evidence exists.
11. Secrets: never put keys/passwords/.env values in code, commits, or chat; verify by length/exit-code only.

---

# 5 · Rules & skills

## TL;DR

**Objective** — seed `.claude/rules/` with the universal behavioral + reference rule set, install the stack skills and deploy orchestrator into `.claude/skills/`, then **restart** so the new context loads. This is the **accumulated-knowledge** layer — hard-won lessons from past CodeCanyon deployments that arm every future session.

**Steps at a glance:**
1. **Seed `.claude/rules/`** — The kit ships the full universal rule set plus a `seed-project-rules.sh` that
   copies them into `.claude/rules/`, backs up any existing versions, and writes a human-readable index.
2. **Install skills into `.claude/skills/`** — The `zaj-laravel-codecanyon` orchestrator should already be in
   the project from C2 (machine setup §5).
3. **Commit rules + skills (C5)** — commit the rule and skill layers, so the repo carries the stack-specific
   operating system future sessions need.
4. **Restart all layers** — `.claude/rules/` and `.claude/skills/` load once at session start and are *not*
   re-scanned mid-session.

:::note[User part + done-when]
**👤 User part** — the only human-only action is the **restart**: end the session and start a fresh one so the seeded rules and skills actually load. Everything else is terminal-runnable.

**Done when** `.claude/rules/` is seeded (universal set + `project_context.md`), stack skills are installed in `.claude/skills/`, **C5** is committed on `develop`, and a **fresh session** confirms the rules are loaded. &nbsp;·&nbsp; **⏱ ~10 min** &nbsp;·&nbsp; 🔀 mostly the agent, one user restart.
:::

## Background

Rules and skills are the **accumulated knowledge** layer — hard-won lessons from past CodeCanyon deployments that arm every future session (and every teammate who pulls the repo) so you don't re-hit known bugs from scratch.

| Layer | Location | What it is | Loaded |
|---|---|---|---|
| **Rules** | `.claude/rules/*.md` | Behavioral (`feedback_*`) + reference (`reference_*`) + project (`project_*`) knowledge | In full, at session start |
| **Skills** | `.claude/skills/` | Reusable *procedures* the agent invokes on demand (e.g. the deploy orchestrator) | On invocation |

Both are **committed at C5** (orchestrator already at **C2**) so they travel with the repo — see [git policy](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/#git-policy).

```mermaid
flowchart TD
  Boot[Agent session start] --> Rules[".claude/rules/<br/>loaded in full"]
  Boot --> Skills[".claude/skills/<br/>invoked on demand"]
  Rules --> Guard[Behavior + reference + project context]
  Skills --> Proc[Procedures e.g. deploy orchestrator]
```

## Steps

### 1. Seed `.claude/rules/`

The kit ships the full universal rule set plus a `seed-project-rules.sh` that copies them into `.claude/rules/`, backs up any existing versions, and writes a human-readable index. It's safe to re-run anytime the rule set is updated; it never touches your `project_*.md` files.

:::danger[Do not run full `seed.sh` on hand-built projects]
If you already wrote `AGENTS.md`, `.claude/settings.json`, and constitution files page-by-page, **never** run the kit's full `seed.sh` — it overwrites hand-built project policy. Use **Path B** below (rules bundle only).
:::

:::note[Who does this]
🤖 **Agent** runs the seed path from the project root. 👤 **User** reviews the index afterward if desired.
:::

<Steps>

1. **Choose Path A or Path B**, then seed rules.

   | Path | When | Command |
   | --- | --- | --- |
   | **A — kit install** | Fresh AI-System kit / `seed.sh` already ran | `bash .claude/rules/seed-project-rules.sh` |
   | **B — hand-built** | Constitution/settings written manually first | Copy rules from kit temp dir only (see below) |

   **Path A** — from the project root:

   ```bash
   bash .claude/rules/seed-project-rules.sh   # idempotent — only adds/updates by mtime
   # Expected: rules copied/updated; existing project_*.md files left untouched
   ```

   **Path B** — fetch kit, copy **only** `.claude/rules/`:

   ```bash
   KIT_DIR="Admin-Local/0-Setup/codecanyon-ai-system-kit"
   mkdir -p .claude/rules Admin-Local/1-Project
   cp -R "$KIT_DIR/dot-claude/rules/." .claude/rules/
   touch Zaj-PROJECT.md \
         .tool-versions \
         Zaj-CUSTOMIZATIONS.md \
         Zaj-PROGRESS.md \
         Zaj-BACKLOG.md \
         Zaj-CHANGELOG.md \
         Admin-Local/1-Project/playbook-feedback.md
   # Expected: rules + tracking files exist; AGENTS.md/CLAUDE.md/settings untouched
   ```

   - ✅ `.claude/rules/` fills with the `feedback_*` + `reference_*` set (Path A or B).

2. **Add a project-specific context file.** The universal rules are universal; add one file for *this* project's current state. Save it as `.claude/rules/project_context.md` — this file is yours, and seed re-runs never overwrite `project_*` files.

   ```markdown
   ---
   name: Project context — <AppName>
   description: High-level context every session should load. Update as the project progresses.
   ---

   ## <AppName>
   - Type: <SaaS / marketplace / directory>
   - Vendor family: <Froiden / LiquidThemes / WorkDo / InfyOm / IqonicDesign / other>
   - Tech stack: Laravel <version>, <notes>
   - Environments: see `Zaj-PROJECT.md` environment matrix (`staging-primary`, `qa`, `uat`, `production`, etc.)
   - Current phase: AI dev environment setup (complete — update as you go)

   ## Known vendor gotchas (fill in after the local dev source scan)
   - APP_ENV hardcoding: <not yet scanned>
   ```

   - ✅ `.claude/rules/project_context.md` exists with this project's type, vendor family, stack, and environments.

</Steps>

#### What gets seeded (grouped for discoverability)

**Meta — how to work with the system itself**
- `feedback_rule_persistence.md` — when to write a rule directly vs propose-first; keep rules small, grouped, cross-referenced
- `feedback_guide_updates_proactive.md` — apply guide edits directly when root cause is clear
- `feedback_playbook_feedback_logging.md` — log guide gaps / vendor quirks to project playbook feedback instead of silent inline fixes
- `feedback_devlog_convention.md` — use `Admin-Local/1-Project/90-DevLog/` as the build journal and hot-file coordination surface
- `feedback_commit_split_strategy.md` — the rules→deviations→content→docs commit pattern
- `feedback_idempotent_replay_scripts.md` · `feedback_replay_script_persistence.md` — recoverable, persisted bulk-write scripts

**CodeCanyon vendor handling**
- `feedback_product_naming.md` — use your project names, never vendor script names
- `feedback_vendor_assumptions_verify.md` — installed ≠ canonically used; grep source first
- `feedback_vendor_ui_first.md` · `feedback_vendor_ui_warnings.md` — prefer vendor UI/code paths; treat UI warnings as hypotheses
- `feedback_observer_reseed_trap.md` — vendor observers silently re-materialize defaults; check `app/Observers/` first
- `feedback_demo_content_replacement.md` — replace vendor demo content (fake testimonials are a legal landmine)
- `feedback_tier_gating_model.md` — discover the vendor's gating model before designing tiers
- `reference_codecanyon_vendor_families.md` — known gotchas by vendor family
- `reference_vendor_deviation_pattern.md` — the safe 3-file deviation pattern with comment markers

**Customization-ownership system**
- `feedback_zaj_code_markers.md` — wrap edits in `ZAJ:BEGIN/END`; net-new files get `ZAJ:FILE`
- `feedback_zaj_table_naming.md` — table/migration naming conventions
- `reference_zaj_customization_strategy.md` — the vendor-customization vs new-module vs table-extension decision tree

**Laravel / PHP**
- `feedback_blade_short_php_form.md` · `feedback_env_hardcoding_scan.md` · `feedback_php_alt_binary_artisan.md` · `feedback_toolchain_version_parity.md`
- `reference_laravel_execution_patterns.md` — when to use tinker vs script vs artisan vs seeder vs migration

**Deploy / infra**
- `feedback_shared_files_add_not_set.md` · `feedback_cron_every_minute_gotcha.md` · `feedback_staging_vs_production_execution.md`

**Security / secrets**
- `feedback_secret_handling.md` · `feedback_server_side_secret_execution.md` · `feedback_op_signin_interactive.md` · `feedback_stripe_agent_safety.md`
- `reference_stripe_restricted_key_scopes.md`

**i18n / content**
- `feedback_free_translate_polysemy.md` — spot-check machine translations for polysemy before shipping

### 2. Install skills into `.claude/skills/`

The **`zaj-laravel-codecanyon`** orchestrator should already be in the project from **C2** ([machine setup §5](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/02-machine-setup/#5-install-the-deploy-orchestrator-skill--per-project-then-customize)). This step adds **stack skills** (Stripe, etc.) — skip re-downloading the orchestrator unless C2 was skipped.

:::note[Who does this]
🤖 **Agent** runs the download into the project; fill any `<placeholders>` for this project as you go.
:::

<Steps>

1. **Confirm the orchestrator from C2** (or download if missing).

   ```bash
   test -d .claude/skills/zaj-laravel-codecanyon/handbook \
     && echo "orchestrator present (C2)" \
     || { mkdir -p .claude/skills/zaj-laravel-codecanyon
          curl -fsSL https://library.zajapps.com/skills/zaj-laravel-codecanyon.tgz \
            | tar -xz -C .claude/skills/zaj-laravel-codecanyon; }
   # Expected: handbook/ + SKILL.md present
   ```

   - ✅ `.claude/skills/zaj-laravel-codecanyon/handbook/` exists **or** you deliberately use a global `~/.claude/skills/zaj-laravel-codecanyon` copy only.

2. **Add stack skills** (Stripe example — install only if this project uses Stripe).

   ```bash
   npx skills add stripe            # example — installs the Stripe skill into .claude/skills/
   ls .claude/skills/
   # Expected: orchestrator + any stack skills you chose
   ```

   - ✅ `ls .claude/skills/` lists the orchestrator (downloaded into the project) and any stack/Stripe skills.

3. **If you built by hand, copy only the rules bundle.**

   If you already wrote `AGENTS.md`, `.claude/settings.json`, and project mirrors by hand, do **not** run the kit's full `seed.sh` here. Use the kit as a source tree and copy the rule files deliberately so you do not overwrite hand-built project policy.

   ```bash
   KIT_DIR="Admin-Local/0-Setup/codecanyon-ai-system-kit"
   mkdir -p .claude/rules
   cp -R "$KIT_DIR/dot-claude/rules/." .claude/rules/
   # Expected: only .claude/rules/ is copied from the kit in this hand-built path
   ```

   - ✅ Hand-built constitution/settings files remain untouched; `.claude/rules/` carries the CodeCanyon feedback rules.

4. **Verify on disk** — commit at **C5** (§3 below).

   ```bash
   git add -n .claude/rules/ .claude/skills/ .claude/agents/
   # Expected: paths listed (dry-run) — commit in §3 below
   ```

   - ✅ `.claude/rules/` + stack skills are in place. `.claude/agents/` is present only if you created real reviewer files, not just placeholders.

</Steps>

:::note[Seed the project trackers now — later phases depend on them]
The kit's `seed.sh` drops the **tracking files** the agent appends to for the rest of the build. They must exist **now** — later phases say "update `Zaj-PROGRESS.md`", "promote this to `Zaj-BACKLOG.md`", or "append to playbook feedback", and the seeded rules (`feedback_playbook_feedback_logging.md`) have nothing to write to if the file is missing. If you built the AI system by hand, create the empty files now so nothing downstream has a dangling reference.

| File | Role |
| --- | --- |
| `Zaj-PROJECT.md` (root) | Non-secret current truth: identity, repo, toolchain versions, environment matrix, deploy paths, SSH aliases, and tracker links. |
| `.tool-versions` (root) | Machine-readable PHP / Node / Composer targets for teams using asdf/mise; DB engine and collation stay in `Zaj-PROJECT.md`. |
| `Zaj-CUSTOMIZATIONS.md` (root) | Vendor-deviation ledger and root ownership map; first real entries land in Code & repository setup. |
| `Zaj-PROGRESS.md` (root) | Current / in-flight phase and step progress — the **committed, team-visible** counterpart to the gitignored `CLAUDE.local.md`. |
| `Zaj-BACKLOG.md` (root) | Deferred / future work surfaced during execution or research, before promotion to GitHub Issues. |
| `Zaj-CHANGELOG.md` (root) | Internal done/history release log; keeps your SemVer separate from vendor release notes. |
| `Admin-Local/1-Project/playbook-feedback.md` | Guide gaps / vendor quirks you hit — **log them, don't silently work around them**, so the next project running these guides doesn't re-hit the same gap. |

Treat the Zaj-owned root files as one family: `Zaj-PROJECT.md` records current truth, `Zaj-CHANGELOG.md` records done/history, `Zaj-PROGRESS.md` records current/in-flight work, `Zaj-BACKLOG.md` records deferred/future work, and `Zaj-CUSTOMIZATIONS.md` records vendor deviations. `playbook-feedback.md` stays under `Admin-Local/1-Project/` because it is meta feedback about this playbook and feeds the library feedback queue.
:::

:::tip[PROGRESS marker protocol — update the marker BEFORE moving on]
`Zaj-PROGRESS.md` is only useful if it stays current. After every tracked step from here on, set its marker **before** starting the next step:

| Marker | Meaning |
| --- | --- |
| `[x]` | done — add the completion date |
| `[~]` | started / in progress |
| `[s]` | explicitly skipped / `N/A` — add evidence and, if future work remains, a `Zaj-BACKLOG.md` row |
| `[!]` | blocked — add the blocker |

```markdown
## Phase 1 — AI dev environment
- [x] 1 — Create the project & bring in the code ✅ <date>
- [x] 2 — Machine setup ✅ <date>
- [~] 5 — Rules & skills 🟡 started <date> (you are here)

## Phase 3 — Local development
- [ ] 7 — Shared-hosting readiness
- [s] 8 — Dev tooling ⚪ N/A: <evidence, or Zaj-BACKLOG.md row if this is future work>
```

**Backfill on first seed:** add a line for every setup-new step already completed this session, using the **current published phase and step names** from this playbook. Do not copy source guide phase labels or task numbers into `Zaj-PROGRESS.md`. Commit the backfill as a **separate** commit so the audit trail reads "progress tracker seeded" → "progress tracker backfilled" as two distinct steps.

**`Zaj-PROGRESS.md` is not `CLAUDE.local.md`.** `CLAUDE.local.md` tracks private machine/session context and stays gitignored; `Zaj-PROGRESS.md` tracks shared step state and is committed so any new session, machine, or teammate sees exactly what's outstanding.
:::

:::note[Other project files seeded here — you act on them in later phases]
The kit also drops a few **conditional** project inputs so later phases find the right home for the work. Don't fill them in now; record either the expected future owner or an evidence-backed `N/A` so none of this becomes a silent skip:

- `brand-profile.json` + `asset-deployment-map.json` — under `Admin-Local/1-Project/1-Info/Brand/`; **Phase 6** generates logos, favicons, and hero assets from them.
- A **provisional Stripe account strategy** — a placeholder decision recorded now and **locked in Phase 6** (when you create real keys), then used in **Phase 8** billing.
- Deep-research reports live under `Admin-Local/1-Project/1-Info/Research/`; any `follow_up_tasks` they produce go into root `Zaj-BACKLOG.md`. Do **not** create a separate research-todos side file.
- Persisted replay scripts use the `Admin-Local/1-Project/5-Scripts/` taxonomy only after a real replay script exists. If no replay scripts are needed yet, record `N/A` in `Zaj-PROGRESS.md` with evidence instead of creating empty script folders.
:::

:::caution[Provisional Stripe account trap]
Some vendor families create sandbox connected-account IDs that look similar to the parent account. Record the intended `acct_*` suffix now, then verify that exact suffix when Phase 6 creates real products/prices. Similar names are not proof.
:::

:::note[Provisional Stripe account-strategy heuristic (recorded now, locked later)]
If the project uses Stripe, record a **provisional** account-strategy decision now and lock it in a later phase — Stripe account migration is expensive for Cashier-based apps (persistent subscription objects) and cheap for ad-hoc-invoice apps (just swap `.env` keys). Guess the likely billing architecture from the vendor family:

| Vendor family | Likely billing architecture |
| --- | --- |
| Froiden | Ad-hoc invoice (custom webhook controller) |
| WorkDo (Dash SaaS) | Ad-hoc invoice (per-module controllers) |
| LiquidThemes | Varies per product — check docs |
| InfyOm / Infix | Mixed — often canonical Cashier |
| IqonicDesign | Mixed — often canonical Cashier with customizations |
| Unknown / other | Unknown — treat as "requires later verification" |

**Default by provisional architecture:** likely-Cashier → dedicated account up front (migration too costly to defer); likely-ad-hoc → start minimal, graduate before production; **unknown → dedicated account (the safe default)**. Record the provisional strategy + architecture + vendor-family basis in `Zaj-CUSTOMIZATIONS.md`; a later phase verifies against the extracted source and may revise it **before** any keys are created (key creation is the expensive-to-reverse step, not the decision).
:::

#### Decide whether to create review subagents (`.claude/agents/`)

Skills are *procedures the agent runs*; **subagents** are *specialist reviewers you dispatch* for a focused second opinion. The kit ships three CodeCanyon-specific ones into `.claude/agents/` — they travel with the repo after **C5**:

- **`vendor-update-reviewer`** — checks a change for CodeCanyon vendor-upgrade safety (the `_zaj` suffix, `ZAJ:BEGIN/END` markers, no edits to vendor migrations). Run it before any commit that touches vendor territory.
- **`security-reviewer`** — security review tuned for a multi-tenant Workdo/Dash Laravel SaaS (tenant isolation, mass-assignment, auth/permission gaps). Run it in Phase 7 and before production.
- **`flow-auditor`** — audits one user flow end-to-end for production-readiness (full-stack, not just the happy path). Run it in Phase 10.

If the kit you downloaded contains only `.claude/agents/README.md` placeholders, treat these reviewers as **conditional/create-as-needed**, not as files that already exist. Either create real agent files from your team's current agent template before C5, or leave `.claude/agents/README.md` as a placeholder and record the evidence-backed decision in `Zaj-PROGRESS.md`: `N/A — reviewers dispatch from the global agent pool until a real project agent is written`.

They commit alongside `.claude/skills/` (stack skills) and `.claude/rules/` at **C5** only when real files exist, so they load for every teammate on clone.

:::note[Skills vs `.claude/commands/`]
You may also keep project **slash commands** in `.claude/commands/` (a `<name>.md` file → a `/<name>` command). They overlap with skills, so prefer **skills** for anything reusable — a skill **auto-routes by its trigger description** (no need to remember a command) and travels the same way. Reach for `.claude/commands/` only for a thin project-specific shortcut (e.g. a one-line `/ship` that the team types by hand). The deploy orchestrator is a **skill** (`zaj-laravel-codecanyon`) for exactly this reason.
:::

### Companion global skills (use on demand)

The project orchestrator (`zaj-laravel-codecanyon`) lives in `.claude/skills/` (or globally at `~/.claude/skills/`). **Companion skills** are optional globals you invoke for focused review — no per-project install required when they ship in your IDE plugin pool or `~/.claude/skills/`.

| Phase / moment | Global skill (on demand) | Not a skill — tool/prereq |
| --- | --- | --- |
| Pre-deploy / Phase 7 | `security-review`, `code-review` | — |
| Verify gates (this phase, Phase 10) | `verification-loop` | — |
| Hotfix / bug loop | `systematic-debugging` | — |
| UI / landing work | `frontend-design` | — |
| Atomic commits | `git-commit` | — |
| Deeper audit (optional) | supply-chain / semgrep reviewers | — |
| Machine setup | — | Herd, `gh`, `op`, Composer, Node |

**Tools are not skills.** Herd, GitHub CLI, 1Password CLI, and Composer are prerequisites you run in the terminal — they do not need a "skill" entry. The orchestrator skill *references* this playbook; companion skills add second-opinion review when you dispatch them.

### 3. Commit rules + skills (C5)

:::note[Who does this]
🤖 **Agent** commits on **`develop`**. Orchestrator stays from **C2** — this commit adds rules, stack skills, and agents.
:::

<Steps>

1. **Stage and commit C5** from the project root.

   ```bash
   git branch --show-current    # must be develop
   git add .claude/rules .claude/skills .claude/agents
   git commit -m "feat(ai): seed rules + install stack skills"
   git log --oneline -5         # C5 atop C4…C1
   # Expected: C5 on develop; zaj-laravel-codecanyon unchanged from C2 unless you added stack skills beside it
   ```

   - ✅ `git log` shows C5; `.claude/rules/` and stack skills are tracked. Review subagents are tracked only if you created real reviewer files; placeholders alone are not a done signal.

</Steps>

### 4. Restart all layers

`.claude/rules/` and `.claude/skills/` load **once at session start** and are *not* re-scanned mid-session. If you seed without restarting, the current session keeps running with the old/empty context and the new rules have zero effect.

:::note[Who does this]
👤 **User** ends the session and starts a fresh one — only a person can restart the session.
:::

Why it matters: if you run a Stripe-key step in a session that never loaded `feedback_stripe_agent_safety.md`, the agent may accept an unrestricted key or skip the human-gate.

:::caution[🚨 The 30-second restart is the highest-leverage step in this phase]
Restart **before** any secret-handling step — it's the cheapest way to avoid the worst mistakes in this phase.
:::

<Steps>

1. **Save work** — or `/compact` to preserve context, but note a reload still needs a **new** session.

   - ✅ Pending work is saved (or context compacted) before exiting.

2. **End the session and start fresh.**

   ```text
   1. Save work (or /compact to preserve context — but reload still needs a NEW session)
   2. End the session (/exit or Ctrl+D)
   3. Start fresh: claude
   4. Verify: ask "What rules do you have loaded in .claude/rules/?"
   ```

   - ✅ A fresh `claude` session is running.

3. **Verify the rules loaded.** Ask the new session what rules it has.

   ```text
   Ask: "What rules do you have loaded in .claude/rules/?"
   # Expected: it lists the feedback_* + reference_* set plus project_context.md
   ```

   - ✅ The session lists the `feedback_*` + `reference_*` set **plus** `project_context.md`.

</Steps>

## Checklist

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

- [ ] **🤖 Rules seeded** — `bash .claude/rules/seed-project-rules.sh` ran; `.claude/rules/` holds the `feedback_*` + `reference_*` set.
- [ ] **🤖 Project context added** — `.claude/rules/project_context.md` exists with this project's type, vendor family, stack, and environments.
- [ ] **🤖 Skills installed** — `.claude/skills/zaj-laravel-codecanyon/handbook/` (per-project download) **or** global `~/.claude/skills/zaj-laravel-codecanyon/handbook/`; plus any stack/Stripe skills.
- [ ] **🤖 Review subagent plan recorded** — either `.claude/agents/` holds real vendor-update / security / flow-auditor reviewer files, or the placeholders explicitly say the project will dispatch global reviewers as needed.
- [ ] **🤖 Tracking files seeded** — root `Zaj-PROJECT.md`, `.tool-versions`, `Zaj-CUSTOMIZATIONS.md`, `Zaj-PROGRESS.md`, `Zaj-BACKLOG.md`, and `Zaj-CHANGELOG.md` exist; `Admin-Local/1-Project/playbook-feedback.md` exists (later phases write to them).
- [ ] **🤖 C5 committed on develop** — `.claude/rules/`, stack skills, and `.claude/agents/` tracked (`git log` shows C5); orchestrator already from **C2**.
- [ ] **👤 Session restarted** — a fresh session was started after seeding.
- [ ] **🔀 Rules confirmed loaded** — the fresh session lists the `feedback_*` + `reference_*` set plus `project_context.md`.

:::next[Next step]
[Cursor & other IDEs](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/06-cursor-and-ides/)
:::

# 5 · Rules & skills

> Source: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/05-rules-and-skills/

## TL;DR

**Objective** — seed `.claude/rules/` with the universal behavioral + reference rule set, install the stack skills and deploy orchestrator into `.claude/skills/`, then **restart** so the new context loads. This is the **accumulated-knowledge** layer — hard-won lessons from past CodeCanyon deployments that arm every future session.

**Steps at a glance:**
1. **Seed `.claude/rules/`** — The kit ships the full universal rule set plus a `seed-project-rules.sh` that
   copies them into `.claude/rules/`, backs up any existing versions, and writes a human-readable index.
2. **Install skills into `.claude/skills/`** — The `zaj-laravel-codecanyon` orchestrator should already be in
   the project from C2 (machine setup §5).
3. **Commit rules + skills (C5)** — commit the rule and skill layers, so the repo carries the stack-specific
   operating system future sessions need.
4. **Restart all layers** — `.claude/rules/` and `.claude/skills/` load once at session start and are *not*
   re-scanned mid-session.

:::note[User part + done-when]
**👤 User part** — the only human-only action is the **restart**: end the session and start a fresh one so the seeded rules and skills actually load. Everything else is terminal-runnable.

**Done when** `.claude/rules/` is seeded (universal set + `project_context.md`), stack skills are installed in `.claude/skills/`, **C5** is committed on `develop`, and a **fresh session** confirms the rules are loaded. &nbsp;·&nbsp; **⏱ ~10 min** &nbsp;·&nbsp; 🔀 mostly the agent, one user restart.
:::

## Background

Rules and skills are the **accumulated knowledge** layer — hard-won lessons from past CodeCanyon deployments that arm every future session (and every teammate who pulls the repo) so you don't re-hit known bugs from scratch.

| Layer | Location | What it is | Loaded |
|---|---|---|---|
| **Rules** | `.claude/rules/*.md` | Behavioral (`feedback_*`) + reference (`reference_*`) + project (`project_*`) knowledge | In full, at session start |
| **Skills** | `.claude/skills/` | Reusable *procedures* the agent invokes on demand (e.g. the deploy orchestrator) | On invocation |

Both are **committed at C5** (orchestrator already at **C2**) so they travel with the repo — see [git policy](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/#git-policy).

```mermaid
flowchart TD
  Boot[Agent session start] --> Rules[".claude/rules/<br/>loaded in full"]
  Boot --> Skills[".claude/skills/<br/>invoked on demand"]
  Rules --> Guard[Behavior + reference + project context]
  Skills --> Proc[Procedures e.g. deploy orchestrator]
```

## Steps

### 1. Seed `.claude/rules/`

The kit ships the full universal rule set plus a `seed-project-rules.sh` that copies them into `.claude/rules/`, backs up any existing versions, and writes a human-readable index. It's safe to re-run anytime the rule set is updated; it never touches your `project_*.md` files.

:::danger[Do not run full `seed.sh` on hand-built projects]
If you already wrote `AGENTS.md`, `.claude/settings.json`, and constitution files page-by-page, **never** run the kit's full `seed.sh` — it overwrites hand-built project policy. Use **Path B** below (rules bundle only).
:::

:::note[Who does this]
🤖 **Agent** runs the seed path from the project root. 👤 **User** reviews the index afterward if desired.
:::

<Steps>

1. **Choose Path A or Path B**, then seed rules.

   | Path | When | Command |
   | --- | --- | --- |
   | **A — kit install** | Fresh AI-System kit / `seed.sh` already ran | `bash .claude/rules/seed-project-rules.sh` |
   | **B — hand-built** | Constitution/settings written manually first | Copy rules from kit temp dir only (see below) |

   **Path A** — from the project root:

   ```bash
   bash .claude/rules/seed-project-rules.sh   # idempotent — only adds/updates by mtime
   # Expected: rules copied/updated; existing project_*.md files left untouched
   ```

   **Path B** — fetch kit, copy **only** `.claude/rules/`:

   ```bash
   KIT_DIR="Admin-Local/0-Setup/codecanyon-ai-system-kit"
   mkdir -p .claude/rules Admin-Local/1-Project
   cp -R "$KIT_DIR/dot-claude/rules/." .claude/rules/
   touch Zaj-PROJECT.md \
         .tool-versions \
         Zaj-CUSTOMIZATIONS.md \
         Zaj-PROGRESS.md \
         Zaj-BACKLOG.md \
         Zaj-CHANGELOG.md \
         Admin-Local/1-Project/playbook-feedback.md
   # Expected: rules + tracking files exist; AGENTS.md/CLAUDE.md/settings untouched
   ```

   - ✅ `.claude/rules/` fills with the `feedback_*` + `reference_*` set (Path A or B).

2. **Add a project-specific context file.** The universal rules are universal; add one file for *this* project's current state. Save it as `.claude/rules/project_context.md` — this file is yours, and seed re-runs never overwrite `project_*` files.

   ```markdown
   ---
   name: Project context — <AppName>
   description: High-level context every session should load. Update as the project progresses.
   ---

   ## <AppName>
   - Type: <SaaS / marketplace / directory>
   - Vendor family: <Froiden / LiquidThemes / WorkDo / InfyOm / IqonicDesign / other>
   - Tech stack: Laravel <version>, <notes>
   - Environments: see `Zaj-PROJECT.md` environment matrix (`staging-primary`, `qa`, `uat`, `production`, etc.)
   - Current phase: AI dev environment setup (complete — update as you go)

   ## Known vendor gotchas (fill in after the local dev source scan)
   - APP_ENV hardcoding: <not yet scanned>
   ```

   - ✅ `.claude/rules/project_context.md` exists with this project's type, vendor family, stack, and environments.

</Steps>

#### What gets seeded (grouped for discoverability)

**Meta — how to work with the system itself**
- `feedback_rule_persistence.md` — when to write a rule directly vs propose-first; keep rules small, grouped, cross-referenced
- `feedback_guide_updates_proactive.md` — apply guide edits directly when root cause is clear
- `feedback_playbook_feedback_logging.md` — log guide gaps / vendor quirks to project playbook feedback instead of silent inline fixes
- `feedback_devlog_convention.md` — use `Admin-Local/1-Project/90-DevLog/` as the build journal and hot-file coordination surface
- `feedback_commit_split_strategy.md` — the rules→deviations→content→docs commit pattern
- `feedback_idempotent_replay_scripts.md` · `feedback_replay_script_persistence.md` — recoverable, persisted bulk-write scripts

**CodeCanyon vendor handling**
- `feedback_product_naming.md` — use your project names, never vendor script names
- `feedback_vendor_assumptions_verify.md` — installed ≠ canonically used; grep source first
- `feedback_vendor_ui_first.md` · `feedback_vendor_ui_warnings.md` — prefer vendor UI/code paths; treat UI warnings as hypotheses
- `feedback_observer_reseed_trap.md` — vendor observers silently re-materialize defaults; check `app/Observers/` first
- `feedback_demo_content_replacement.md` — replace vendor demo content (fake testimonials are a legal landmine)
- `feedback_tier_gating_model.md` — discover the vendor's gating model before designing tiers
- `reference_codecanyon_vendor_families.md` — known gotchas by vendor family
- `reference_vendor_deviation_pattern.md` — the safe 3-file deviation pattern with comment markers

**Customization-ownership system**
- `feedback_zaj_code_markers.md` — wrap edits in `ZAJ:BEGIN/END`; net-new files get `ZAJ:FILE`
- `feedback_zaj_table_naming.md` — table/migration naming conventions
- `reference_zaj_customization_strategy.md` — the vendor-customization vs new-module vs table-extension decision tree

**Laravel / PHP**
- `feedback_blade_short_php_form.md` · `feedback_env_hardcoding_scan.md` · `feedback_php_alt_binary_artisan.md` · `feedback_toolchain_version_parity.md`
- `reference_laravel_execution_patterns.md` — when to use tinker vs script vs artisan vs seeder vs migration

**Deploy / infra**
- `feedback_shared_files_add_not_set.md` · `feedback_cron_every_minute_gotcha.md` · `feedback_staging_vs_production_execution.md`

**Security / secrets**
- `feedback_secret_handling.md` · `feedback_server_side_secret_execution.md` · `feedback_op_signin_interactive.md` · `feedback_stripe_agent_safety.md`
- `reference_stripe_restricted_key_scopes.md`

**i18n / content**
- `feedback_free_translate_polysemy.md` — spot-check machine translations for polysemy before shipping

### 2. Install skills into `.claude/skills/`

The **`zaj-laravel-codecanyon`** orchestrator should already be in the project from **C2** ([machine setup §5](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/02-machine-setup/#5-install-the-deploy-orchestrator-skill--per-project-then-customize)). This step adds **stack skills** (Stripe, etc.) — skip re-downloading the orchestrator unless C2 was skipped.

:::note[Who does this]
🤖 **Agent** runs the download into the project; fill any `<placeholders>` for this project as you go.
:::

<Steps>

1. **Confirm the orchestrator from C2** (or download if missing).

   ```bash
   test -d .claude/skills/zaj-laravel-codecanyon/handbook \
     && echo "orchestrator present (C2)" \
     || { mkdir -p .claude/skills/zaj-laravel-codecanyon
          curl -fsSL https://library.zajapps.com/skills/zaj-laravel-codecanyon.tgz \
            | tar -xz -C .claude/skills/zaj-laravel-codecanyon; }
   # Expected: handbook/ + SKILL.md present
   ```

   - ✅ `.claude/skills/zaj-laravel-codecanyon/handbook/` exists **or** you deliberately use a global `~/.claude/skills/zaj-laravel-codecanyon` copy only.

2. **Add stack skills** (Stripe example — install only if this project uses Stripe).

   ```bash
   npx skills add stripe            # example — installs the Stripe skill into .claude/skills/
   ls .claude/skills/
   # Expected: orchestrator + any stack skills you chose
   ```

   - ✅ `ls .claude/skills/` lists the orchestrator (downloaded into the project) and any stack/Stripe skills.

3. **If you built by hand, copy only the rules bundle.**

   If you already wrote `AGENTS.md`, `.claude/settings.json`, and project mirrors by hand, do **not** run the kit's full `seed.sh` here. Use the kit as a source tree and copy the rule files deliberately so you do not overwrite hand-built project policy.

   ```bash
   KIT_DIR="Admin-Local/0-Setup/codecanyon-ai-system-kit"
   mkdir -p .claude/rules
   cp -R "$KIT_DIR/dot-claude/rules/." .claude/rules/
   # Expected: only .claude/rules/ is copied from the kit in this hand-built path
   ```

   - ✅ Hand-built constitution/settings files remain untouched; `.claude/rules/` carries the CodeCanyon feedback rules.

4. **Verify on disk** — commit at **C5** (§3 below).

   ```bash
   git add -n .claude/rules/ .claude/skills/ .claude/agents/
   # Expected: paths listed (dry-run) — commit in §3 below
   ```

   - ✅ `.claude/rules/` + stack skills are in place. `.claude/agents/` is present only if you created real reviewer files, not just placeholders.

</Steps>

:::note[Seed the project trackers now — later phases depend on them]
The kit's `seed.sh` drops the **tracking files** the agent appends to for the rest of the build. They must exist **now** — later phases say "update `Zaj-PROGRESS.md`", "promote this to `Zaj-BACKLOG.md`", or "append to playbook feedback", and the seeded rules (`feedback_playbook_feedback_logging.md`) have nothing to write to if the file is missing. If you built the AI system by hand, create the empty files now so nothing downstream has a dangling reference.

| File | Role |
| --- | --- |
| `Zaj-PROJECT.md` (root) | Non-secret current truth: identity, repo, toolchain versions, environment matrix, deploy paths, SSH aliases, and tracker links. |
| `.tool-versions` (root) | Machine-readable PHP / Node / Composer targets for teams using asdf/mise; DB engine and collation stay in `Zaj-PROJECT.md`. |
| `Zaj-CUSTOMIZATIONS.md` (root) | Vendor-deviation ledger and root ownership map; first real entries land in Code & repository setup. |
| `Zaj-PROGRESS.md` (root) | Current / in-flight phase and step progress — the **committed, team-visible** counterpart to the gitignored `CLAUDE.local.md`. |
| `Zaj-BACKLOG.md` (root) | Deferred / future work surfaced during execution or research, before promotion to GitHub Issues. |
| `Zaj-CHANGELOG.md` (root) | Internal done/history release log; keeps your SemVer separate from vendor release notes. |
| `Admin-Local/1-Project/playbook-feedback.md` | Guide gaps / vendor quirks you hit — **log them, don't silently work around them**, so the next project running these guides doesn't re-hit the same gap. |

Treat the Zaj-owned root files as one family: `Zaj-PROJECT.md` records current truth, `Zaj-CHANGELOG.md` records done/history, `Zaj-PROGRESS.md` records current/in-flight work, `Zaj-BACKLOG.md` records deferred/future work, and `Zaj-CUSTOMIZATIONS.md` records vendor deviations. `playbook-feedback.md` stays under `Admin-Local/1-Project/` because it is meta feedback about this playbook and feeds the library feedback queue.
:::

:::tip[PROGRESS marker protocol — update the marker BEFORE moving on]
`Zaj-PROGRESS.md` is only useful if it stays current. After every tracked step from here on, set its marker **before** starting the next step:

| Marker | Meaning |
| --- | --- |
| `[x]` | done — add the completion date |
| `[~]` | started / in progress |
| `[s]` | explicitly skipped / `N/A` — add evidence and, if future work remains, a `Zaj-BACKLOG.md` row |
| `[!]` | blocked — add the blocker |

```markdown
## Phase 1 — AI dev environment
- [x] 1 — Create the project & bring in the code ✅ <date>
- [x] 2 — Machine setup ✅ <date>
- [~] 5 — Rules & skills 🟡 started <date> (you are here)

## Phase 3 — Local development
- [ ] 7 — Shared-hosting readiness
- [s] 8 — Dev tooling ⚪ N/A: <evidence, or Zaj-BACKLOG.md row if this is future work>
```

**Backfill on first seed:** add a line for every setup-new step already completed this session, using the **current published phase and step names** from this playbook. Do not copy source guide phase labels or task numbers into `Zaj-PROGRESS.md`. Commit the backfill as a **separate** commit so the audit trail reads "progress tracker seeded" → "progress tracker backfilled" as two distinct steps.

**`Zaj-PROGRESS.md` is not `CLAUDE.local.md`.** `CLAUDE.local.md` tracks private machine/session context and stays gitignored; `Zaj-PROGRESS.md` tracks shared step state and is committed so any new session, machine, or teammate sees exactly what's outstanding.
:::

:::note[Other project files seeded here — you act on them in later phases]
The kit also drops a few **conditional** project inputs so later phases find the right home for the work. Don't fill them in now; record either the expected future owner or an evidence-backed `N/A` so none of this becomes a silent skip:

- `brand-profile.json` + `asset-deployment-map.json` — under `Admin-Local/1-Project/1-Info/Brand/`; **Phase 6** generates logos, favicons, and hero assets from them.
- A **provisional Stripe account strategy** — a placeholder decision recorded now and **locked in Phase 6** (when you create real keys), then used in **Phase 8** billing.
- Deep-research reports live under `Admin-Local/1-Project/1-Info/Research/`; any `follow_up_tasks` they produce go into root `Zaj-BACKLOG.md`. Do **not** create a separate research-todos side file.
- Persisted replay scripts use the `Admin-Local/1-Project/5-Scripts/` taxonomy only after a real replay script exists. If no replay scripts are needed yet, record `N/A` in `Zaj-PROGRESS.md` with evidence instead of creating empty script folders.
:::

:::caution[Provisional Stripe account trap]
Some vendor families create sandbox connected-account IDs that look similar to the parent account. Record the intended `acct_*` suffix now, then verify that exact suffix when Phase 6 creates real products/prices. Similar names are not proof.
:::

:::note[Provisional Stripe account-strategy heuristic (recorded now, locked later)]
If the project uses Stripe, record a **provisional** account-strategy decision now and lock it in a later phase — Stripe account migration is expensive for Cashier-based apps (persistent subscription objects) and cheap for ad-hoc-invoice apps (just swap `.env` keys). Guess the likely billing architecture from the vendor family:

| Vendor family | Likely billing architecture |
| --- | --- |
| Froiden | Ad-hoc invoice (custom webhook controller) |
| WorkDo (Dash SaaS) | Ad-hoc invoice (per-module controllers) |
| LiquidThemes | Varies per product — check docs |
| InfyOm / Infix | Mixed — often canonical Cashier |
| IqonicDesign | Mixed — often canonical Cashier with customizations |
| Unknown / other | Unknown — treat as "requires later verification" |

**Default by provisional architecture:** likely-Cashier → dedicated account up front (migration too costly to defer); likely-ad-hoc → start minimal, graduate before production; **unknown → dedicated account (the safe default)**. Record the provisional strategy + architecture + vendor-family basis in `Zaj-CUSTOMIZATIONS.md`; a later phase verifies against the extracted source and may revise it **before** any keys are created (key creation is the expensive-to-reverse step, not the decision).
:::

#### Decide whether to create review subagents (`.claude/agents/`)

Skills are *procedures the agent runs*; **subagents** are *specialist reviewers you dispatch* for a focused second opinion. The kit ships three CodeCanyon-specific ones into `.claude/agents/` — they travel with the repo after **C5**:

- **`vendor-update-reviewer`** — checks a change for CodeCanyon vendor-upgrade safety (the `_zaj` suffix, `ZAJ:BEGIN/END` markers, no edits to vendor migrations). Run it before any commit that touches vendor territory.
- **`security-reviewer`** — security review tuned for a multi-tenant Workdo/Dash Laravel SaaS (tenant isolation, mass-assignment, auth/permission gaps). Run it in Phase 7 and before production.
- **`flow-auditor`** — audits one user flow end-to-end for production-readiness (full-stack, not just the happy path). Run it in Phase 10.

If the kit you downloaded contains only `.claude/agents/README.md` placeholders, treat these reviewers as **conditional/create-as-needed**, not as files that already exist. Either create real agent files from your team's current agent template before C5, or leave `.claude/agents/README.md` as a placeholder and record the evidence-backed decision in `Zaj-PROGRESS.md`: `N/A — reviewers dispatch from the global agent pool until a real project agent is written`.

They commit alongside `.claude/skills/` (stack skills) and `.claude/rules/` at **C5** only when real files exist, so they load for every teammate on clone.

:::note[Skills vs `.claude/commands/`]
You may also keep project **slash commands** in `.claude/commands/` (a `<name>.md` file → a `/<name>` command). They overlap with skills, so prefer **skills** for anything reusable — a skill **auto-routes by its trigger description** (no need to remember a command) and travels the same way. Reach for `.claude/commands/` only for a thin project-specific shortcut (e.g. a one-line `/ship` that the team types by hand). The deploy orchestrator is a **skill** (`zaj-laravel-codecanyon`) for exactly this reason.
:::

### Companion global skills (use on demand)

The project orchestrator (`zaj-laravel-codecanyon`) lives in `.claude/skills/` (or globally at `~/.claude/skills/`). **Companion skills** are optional globals you invoke for focused review — no per-project install required when they ship in your IDE plugin pool or `~/.claude/skills/`.

| Phase / moment | Global skill (on demand) | Not a skill — tool/prereq |
| --- | --- | --- |
| Pre-deploy / Phase 7 | `security-review`, `code-review` | — |
| Verify gates (this phase, Phase 10) | `verification-loop` | — |
| Hotfix / bug loop | `systematic-debugging` | — |
| UI / landing work | `frontend-design` | — |
| Atomic commits | `git-commit` | — |
| Deeper audit (optional) | supply-chain / semgrep reviewers | — |
| Machine setup | — | Herd, `gh`, `op`, Composer, Node |

**Tools are not skills.** Herd, GitHub CLI, 1Password CLI, and Composer are prerequisites you run in the terminal — they do not need a "skill" entry. The orchestrator skill *references* this playbook; companion skills add second-opinion review when you dispatch them.

### 3. Commit rules + skills (C5)

:::note[Who does this]
🤖 **Agent** commits on **`develop`**. Orchestrator stays from **C2** — this commit adds rules, stack skills, and agents.
:::

<Steps>

1. **Stage and commit C5** from the project root.

   ```bash
   git branch --show-current    # must be develop
   git add .claude/rules .claude/skills .claude/agents
   git commit -m "feat(ai): seed rules + install stack skills"
   git log --oneline -5         # C5 atop C4…C1
   # Expected: C5 on develop; zaj-laravel-codecanyon unchanged from C2 unless you added stack skills beside it
   ```

   - ✅ `git log` shows C5; `.claude/rules/` and stack skills are tracked. Review subagents are tracked only if you created real reviewer files; placeholders alone are not a done signal.

</Steps>

### 4. Restart all layers

`.claude/rules/` and `.claude/skills/` load **once at session start** and are *not* re-scanned mid-session. If you seed without restarting, the current session keeps running with the old/empty context and the new rules have zero effect.

:::note[Who does this]
👤 **User** ends the session and starts a fresh one — only a person can restart the session.
:::

Why it matters: if you run a Stripe-key step in a session that never loaded `feedback_stripe_agent_safety.md`, the agent may accept an unrestricted key or skip the human-gate.

:::caution[🚨 The 30-second restart is the highest-leverage step in this phase]
Restart **before** any secret-handling step — it's the cheapest way to avoid the worst mistakes in this phase.
:::

<Steps>

1. **Save work** — or `/compact` to preserve context, but note a reload still needs a **new** session.

   - ✅ Pending work is saved (or context compacted) before exiting.

2. **End the session and start fresh.**

   ```text
   1. Save work (or /compact to preserve context — but reload still needs a NEW session)
   2. End the session (/exit or Ctrl+D)
   3. Start fresh: claude
   4. Verify: ask "What rules do you have loaded in .claude/rules/?"
   ```

   - ✅ A fresh `claude` session is running.

3. **Verify the rules loaded.** Ask the new session what rules it has.

   ```text
   Ask: "What rules do you have loaded in .claude/rules/?"
   # Expected: it lists the feedback_* + reference_* set plus project_context.md
   ```

   - ✅ The session lists the `feedback_*` + `reference_*` set **plus** `project_context.md`.

</Steps>

## Checklist

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

- [ ] **🤖 Rules seeded** — `bash .claude/rules/seed-project-rules.sh` ran; `.claude/rules/` holds the `feedback_*` + `reference_*` set.
- [ ] **🤖 Project context added** — `.claude/rules/project_context.md` exists with this project's type, vendor family, stack, and environments.
- [ ] **🤖 Skills installed** — `.claude/skills/zaj-laravel-codecanyon/handbook/` (per-project download) **or** global `~/.claude/skills/zaj-laravel-codecanyon/handbook/`; plus any stack/Stripe skills.
- [ ] **🤖 Review subagent plan recorded** — either `.claude/agents/` holds real vendor-update / security / flow-auditor reviewer files, or the placeholders explicitly say the project will dispatch global reviewers as needed.
- [ ] **🤖 Tracking files seeded** — root `Zaj-PROJECT.md`, `.tool-versions`, `Zaj-CUSTOMIZATIONS.md`, `Zaj-PROGRESS.md`, `Zaj-BACKLOG.md`, and `Zaj-CHANGELOG.md` exist; `Admin-Local/1-Project/playbook-feedback.md` exists (later phases write to them).
- [ ] **🤖 C5 committed on develop** — `.claude/rules/`, stack skills, and `.claude/agents/` tracked (`git log` shows C5); orchestrator already from **C2**.
- [ ] **👤 Session restarted** — a fresh session was started after seeding.
- [ ] **🔀 Rules confirmed loaded** — the fresh session lists the `feedback_*` + `reference_*` set plus `project_context.md`.

:::next[Next step]
[Cursor & other IDEs](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/06-cursor-and-ides/)
:::