4 · Rules & skills

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.

Rules vs skills

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 so they travel with the repo.

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. From the project root:

bash .claude/rules/seed-project-rules.sh   # idempotent — only adds/updates by mtime

It’s safe to re-run anytime the rule set is updated; it never touches your project_*.md files.

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

Add a project-specific context file

The universal rules are universal; add one file for this project’s current state:

---
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: Phase 1 (setup just completed — update as you go)

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

Save it as .claude/rules/project_context.md. This file is yours — seed re-runs never overwrite project_* files.

2. Install skills into .claude/skills/

The kit ships:

• The deploy orchestrator (deploy-codecanyon) — the phase-by-phase pipeline driver with built-in safety rules. (You may also keep a global copy in ~/.claude/commands/; the project copy makes it travel with the repo.)
• Stack skill stubs — e.g. a staging-vs-production execution skill, plus any framework skills your project needs.

If your project uses Stripe, also install the Stripe agent skill via your skills tooling so the agent gets Stripe-specific guidance. Commit everything:

git add .claude/rules/ .claude/skills/
git commit -m "Seed project rules + install skills (AI System Phase 1)"

3. 🚨 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, your current session keeps running with the old/empty context and the new rules have zero effect.

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/?" — it should list the feedback_* + reference_* set plus project_context.md

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 the whole phase.

Gate

✅ .claude/rules/ seeded (universal set + project_context.md), skills installed in .claude/skills/, both committed, and the session restarted with rules confirmed loaded. → Continue to Cursor & other IDEs.