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.

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.  ·  ⏱ ~10 min  ·  🔀 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.

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.

Who does this

🤖 Agent runs the seed script from the project root. 👤 User reviews the index afterward if desired.

1. Run the seed script 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

   • ✅ .claude/rules/ fills with the feedback_* + reference_* set and a human-readable index.

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.

   ---
   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>
   - Staging: staging.<domain>   Production: <domain>
   - Current phase: AI System 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_guide_hiccup_logging.md — log guide gaps / vendor quirks to a hiccups log instead of silent inline fixes
• 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
• 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.

Who does this

🤖 Agent runs the download into the project; fill any <placeholders> for this project as you go.

1. 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.

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

   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.

   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).

   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.

Seed the project tracking files now — later phases depend on them

The kit’s seed.sh drops three tracking files the agent appends to for the rest of the build. They must exist now — later phases say “log it in the task ledger” / “append to the hiccups log” and the seeded rules (feedback_guide_hiccup_logging.md) have nothing to write to if the file is missing. If you built the AI system by hand, create the three empty files now so nothing downstream has a dangling reference.

File	Role
_CUSTOMIZATIONS.md	Every vendor deviation (the customization ledger; first real entries land in Code & repository setup).
guide-hiccups-log.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.
task-ledger.md	Per-task progress + deferred TODOs carried across phases — the committed, team-visible counterpart to the gitignored CLAUDE.local.md.

They live under Admin-Local/1-Project/ (top-level single-file artifacts go directly there, not in a subfolder).

Task-ledger marker protocol — update the marker BEFORE moving on

The ledger is only useful if it stays current. After every task from here on, set its marker before starting the next task:

Marker	Meaning
[x]	done — add the completion date
[~]	started / in progress
[s]	intentionally skipped — add the reason
[!]	blocked — add the blocker

## Phase 1A — Workspace Setup
- [x] 1 — Install core dev tools ✅ <date>
- [s] 3 — Atlas CLI install ⚪ skipped: <reason>

## Phase 1B — Project Setup
- [x] 1.1 — Project folder + source files ✅ <date>
- [~] 1.12 — Seed task ledger 🟡 started <date> (you are here)

Backfill on first seed: add a line for every Phase 1A / 1B task already completed this session, matching the guide’s task numbers verbatim, and commit the backfill as a separate commit so the audit trail reads “ledger seeded” → “ledger backfilled” as two distinct steps.

The ledger is not CLAUDE.local.md. CLAUDE.local.md tracks phase-level state and stays private/gitignored; task-ledger.md tracks individual task state and is committed so any new session, machine, or teammate sees exactly what’s outstanding.

Other project files seeded here — you act on them in later phases

The kit also drops a few optional / conditional project files so later phases find them ready. Don’t fill them in now — just know where each is used so none feels “lost”:

• brand-profile.json + asset-deployment-map.json — under Admin-Local/1-Project/0-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.
• research-todos.md (a deep-research queue) and a persisted-scripts taxonomy — only relevant if you run market research or persist replay scripts; skip otherwise.

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.

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 _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 optional/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 that reviewers will be dispatched from the global agent pool when needed.

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.

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.

3. Commit rules + skills (C5)

Who does this

🤖 Agent commits on develop. Orchestrator stays from C2 — this commit adds rules, stack skills, and agents.

1. 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 — this is not optional

.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.

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.

🚨 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.

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.

   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.

   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 — _CUSTOMIZATIONS.md, guide-hiccups-log.md, and task-ledger.md exist at the repo root / Admin-Local/ (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 step

Cursor & other IDEs