1 · Create the project & bring in the code

TL;DR

Objective — stand up the workspace the rest of the AI System setup builds inside: create the project folder, open it in your IDE and Claude Code, and bring the CodeCanyon vendor ZIP in so the agent can inspect the real code. Everything after this — the constitution, rules, config — is written into this folder, about this codebase.

User part + done-when

👤 User part — create the folder, open the editor, download the CodeCanyon ZIP, extract it (usually in Downloads), and move the ZIP + extracted folder + license files into _source/.

🤖 Agent part — verify the layout in _source/, write an anchored bootstrap .gitignore, git init, copy the app to the project root, prove nothing was missed with the completeness gate, commit the pristine vendor-only baseline (C1) on author/v* + tag (then develop), then write .vscode/ on disk (committed at C2 · machine setup).

Done when the project folder is open in your IDE with Claude Code running inside it, _source/ holds the ZIP + extracted tree + license files on disk only (fully gitignored), git is initialized, the pristine vendor baseline exists on author/vX.X.X + author-vX.X.X tag with develop at the same commit, the Laravel app at root passed the completeness gate, and .vscode/ is written on disk (not in the baseline commit).  ·  ⏱ ~20 min  ·  👤 user then 🤖 agent.

Background

The AI System lives inside the project — AGENTS.md, CLAUDE.md, .claude/rules/, .claude/skills/, IDE wiring. All of that is written into the project folder and describes this app. So before any of it, you need two things in place: the folder (open in your tools) and the vendor code (so the agent can read composer.json, routes, and migrations when it writes the constitution in the next step).

The full git import — GitHub remote, branch model, storage subtree ignores, push — continues in Code & repository setup. This page gets the code onto disk, starts a local repo safely, and lands the most valuable commit in a CodeCanyon project: pristine vendor at root + bootstrap .gitignore only — the diff anchor for _CUSTOMIZATIONS.md, ZAJ:BEGIN/END, and every future vendor update.

flowchart LR
  IG["bootstrap<br/>.gitignore"] --> R["vendor at root<br/>(rsync promote)"]
  R --> C["commit<br/>pristine only"]
  C --> B["branch<br/>author/vX.X.X"]
  C --> T["tag<br/>author-vX.X.X"]
  B --> D["develop<br/>(same commit)"]
  D --> AI["steps 02–06<br/>C2–C6 commits"]

What the pristine baseline includes / excludes

	Path	Why
✅	Vendor source at project root + bootstrap .gitignore	Repo infrastructure + untouched author tree — stock Laravel ships a root .gitignore too
❌	/_source/	143k-file duplicate + ZIP + license — on disk only, never in history
❌	/.vscode/	Our editor config — committed at C2 (machine setup)
❌	.claude/, AGENTS.md, …	Do not exist yet — that is why baseline runs before the constitution

Binding — _source/ on disk, never in git

Two different jobs — do not conflate them.

	_source/ on disk	_source/ in git
Purpose	Rollback manifest, ZIP archive, license retention, rsync reference	❌ Never — not even license.txt, not “until Code & repository setup”, not a partial track
Who needs it	You + the agent during promote / vendor-update forensics	Nobody — only promoted root vendor source belongs in history
How	Keep ZIP + extracted tree after rsync promote (copy, don’t move)	Single rule: /_source/ in bootstrap .gitignore before git init

Obsolete patterns — reject if an old guide or agent suggests them:

• “Track the license in git, ignore the rest of _source/” — use negation !_source/license.txt ❌
• “_source/ stays trackable until Phase 2” ❌ — full ignore at bootstrap (§4), verified before baseline commit (§6)
• “Commit the ZIP for provenance” ❌ — ZIP stays on disk + in your purchase account; git gets root vendor only

Machine setup mentions _source/ on disk for pre-baseline rollback — that does not mean git should ever see it.

The headline lesson: prove completeness with the filesystem, never with git

Whether every file reached the root is a filesystem question — answer it with a rsync dry-run (completeness gate below), not git add. Git staging is filtered by .gitignore (that’s its whole job), so it silently omits the very files that get missed (.env, vendor/, node_modules/, the .zip). Completeness ≠ tracking scope.

Steps

1. Create the project folder and open it

Open your terminal, make an empty folder for the app, then open that folder in your editor and Claude Code — so the agent and every command operate on this project.

Who does this

👤 User — creating the folder and opening the editor / AI session are things only a person does.

1. Open a terminal, then make the folder and move into it.

   mkdir -p ~/Sites/my-app && cd ~/Sites/my-app
   # Expected: an empty folder is created and your terminal is inside it

   • ✅ pwd prints your new project path.

2. Open it in your IDE and start Claude Code inside it.

   code .    # or: cursor .
   claude    # starts a Claude Code session in this folder
   # Expected: the editor opens the folder as its root; the AI session's cwd is the project

   • ✅ The editor shows the (empty) project as its root, and Claude Code is running inside it.

2. Stage the CodeCanyon download in _source/

Download from CodeCanyon, extract locally (usually in Downloads), then move the ZIP, extracted folder, and license files into _source/ — nothing at the project root yet. Everything under _source/ stays on disk only; §4 adds /_source/ to .gitignore before git init so nothing here ever enters git (not the ZIP, not the tree, not license .txt files).

Who does this

👤 User — browser download, local unzip, and moving files into the project.

mkdir -p _source
# Adjust paths to match your Downloads folder and item name
mv ~/Downloads/<item>.zip ~/Downloads/<extracted-folder> _source/
mv ~/Downloads/*license*.txt _source/ 2>/dev/null || true
ls _source/
# Expected: ZIP + extracted tree + license text visible under _source/

• ✅ _source/ contains the ZIP, the extracted folder, and license files — nothing promoted to the project root yet.

3. Verify the Laravel app path in _source/

Find the folder that actually contains the Laravel app (artisan + composer.json may sit one level down inside a CodeCanyon wrapper).

Who does this

🤖 Agent

find _source -maxdepth 4 \( -name artisan -o -name composer.json \) | head -20
# Expected: both files appear under the same directory inside _source/

• ✅ The Laravel app directory inside _source/ is identified (same folder holds artisan and composer.json).

4. Write an anchored bootstrap .gitignore and initialize git

Write .gitignore before git init and before promoting the app. /_source/ is fully ignored — the ZIP, extracted tree, and license files stay on disk for rollback and provenance (you handle license retention outside git). Do not partially track _source/; committing the extracted duplicate is never desirable.

You may copy the kit template verbatim: dot-gitignore.bootstrap.example in the AI System kit tarball → project root .gitignore. The kit seed.sh does not write this file — bootstrap git is always §4 on this page.

Who does this

🤖 Agent

.gitignore

# Bootstrap .gitignore — project setup (minimal C1 baseline; expand after the author anchor)
# Dependencies (root only — leading slash = root-only)
/vendor/
/node_modules/

# Archive — NEVER in git (ZIP + extracted tree + license on disk only)
/_source/

# Secrets (refine after C1; keep templates trackable)
.env
.env.*
!.env.example
!.env.tpl

Anchor every ignore rule with a leading slash

/vendor/ ignores only the root dependency folder. A bare vendor/ (no slash) would also match resources/views/vendor, public/vendor, and nested node_modules — real app folders that must stay tracked. Anchoring (/vendor/, /node_modules/) is what makes promotion safe. Live proof from a real Workdo app:

resources/views/vendor  → tracked ✅    (a naive "vendor/" would wrongly ignore it)
vendor                  → git-ignored   (root deps — correct)

git init
git check-ignore -v _source/ _source/. _source/license.txt 2>/dev/null | head -5
# Expected: each path matches rule /_source/ (or _source/ under that rule)
git status
# Expected: repo exists; _source/ absent from untracked; vendor/, node_modules/, .env/.env.* not listed

• ✅ .gitignore exists at the project root before any git command runs.
• ✅ git check-ignore reports _source/, nested paths, and license files under _source/ as ignored.
• ✅ git init completed; git status does not show vendor/, node_modules/, .env, .env.*, or anything under _source/.

5. Promote the Laravel app to the project root — and prove nothing was missed

Copy (don’t move) the identified app folder’s contents so artisan, composer.json, and the usual Laravel directories sit at the root — not inside a CodeCanyon wrapper. Keep the original folder, ZIP, and license files in _source/: that pristine copy is your manifest to verify against (and the one you may want to explore to confirm nothing dropped). Writing .vscode/ after the baseline — not a delete — handles the duplicate index, so promotion stays non-destructive and re-runnable.

Who does this

🤖 Agent

1. Copy the app to the root. A trailing slash + -a brings dotfiles (.env, .htaccess, .editorconfig) too — but never let a vendor root .gitignore replace the bootstrap you wrote earlier (stock Laravel and many CodeCanyon items ship one). Use a leading slash on the rsync exclude — same anchor rule as the bootstrap block: bare .gitignore would skip every nested Laravel ignore (storage/, bootstrap/cache/, database/, …).

   APP_DIR="_source/<folder-with-artisan>"   # from the layout check above
   rsync -a --exclude='/.gitignore' "$APP_DIR"/ ./
   # Expected: ./artisan and ./composer.json exist at the project root
   test -f artisan && test -f composer.json && echo "smoke: root OK"
   grep -q 'Bootstrap .gitignore' .gitignore && grep -q '/_source/' .gitignore && echo "bootstrap .gitignore intact"
   test -f bootstrap/cache/.gitignore && test -f storage/app/.gitignore && echo "nested Laravel .gitignore files copied"
   test -f "$APP_DIR/.gitignore" && echo "note: vendor .gitignore at $APP_DIR/.gitignore — merge useful lines in Code & repository setup, not via rsync"

   • ✅ artisan and composer.json are at the project root (smoke check, not the gate).
   • ✅ Bootstrap header + /_source/ rule still present at the root (vendor root .gitignore did not clobber the bootstrap block).
   • ✅ Nested Laravel .gitignore files (e.g. bootstrap/cache/, storage/app/) were copied — the exclude is root-only (/.gitignore).

2. Run the completeness gate. A filesystem dry-run that prints zero lines when every source file is present and identical at root — the real “nothing missed” check the two-file smoke can’t give you. Exclude only the root .gitignore (/.gitignore): root keeps the bootstrap; a diff on that one file is expected when the vendor shipped their own. Nested .gitignore files must appear in the gate — a bare .gitignore exclude would hide their absence.

   # any '>f' line = a file missing or different at root. Output MUST be empty.
   DIFF=$(rsync -ain --exclude='/.gitignore' "$APP_DIR"/ ./ | awk '$1 ~ /^>f/')
   [ -z "$DIFF" ] && echo "PASS: no file missed" || { echo "FAIL — missing/changed:"; echo "$DIFF"; }

   • ✅ Prints PASS: no file missed. Never exclude vendor/ or node_modules/ from this gate — a vendor-named folder going missing is the exact failure it guards against.

3. Confirm the dotfiles landed (these are what historically went missing).

   for f in .env .env.example .htaccess .editorconfig; do
     test -f "$f" && echo "$f ✅" || echo "$f MISSING ⚠"
   done

   • ✅ .env (and the rest, where the vendor shipped them) are present at the root.

Don’t prove completeness with git add / git status

.gitignore deliberately hides .env, vendor/, node_modules/, and the .zip — precisely the files that get dropped. A git staging list reads “complete” while omitting them. Promotion completeness (did every byte reach root?) is a filesystem question — use the rsync -ain gate above. Tracking scope (what enters history?) is the gitignore question. Keep the two separate, and never rm -rf "$APP_DIR" here — the copy is non-destructive on purpose; any cleanup is a deliberate later step in Code & repository setup.

Staging has a second blind spot: user-level ignore rules outside the repo. Handle that at C1, not after the anchor is already wrong.

Global gitignore can corrupt the pristine baseline

Git also applies the user’s machine-level core.excludesFile (often ~/.gitignore_global) during git add. A global pattern like *.xml can silently keep real vendor files such as phpunit.xml out of C1 while the filesystem completeness gate still passes, because the file exists on disk. For the pristine vendor baseline only, neutralize the global excludes file with git -c core.excludesFile=/dev/null add -A; the repo .gitignore still blocks _source/, dependencies, and real env files.

The dependency install stays later even with the safer staging command.

Don’t composer install yet

The vendor’s vendor/ directory may carry author patches. Promoting source code is fine; installing dependencies waits until local development verifies the app — don’t run composer install here, or you risk overwriting patches before they’re identified. The pristine baseline commit (next sub-step) freezes promoted source only; author/v* already exists before machine setup and constitution.

6. Commit the pristine vendor baseline — author/v* + tag

This is the single most valuable commit in a CodeCanyon repo: vendor source + bootstrap .gitignore, nothing else. Every customization you ever make is git diff author-vX.X.X..HEAD — the anchor the _CUSTOMIZATIONS.md / ZAJ:BEGIN/END ownership model depends on.

Commit & freeze builds on this (push, working branch) — it does not recreate the baseline.

Who does this

🤖 Agent — try auto-detect, safety-check the stage, commit, branch, and tag. 👤 User sets VERSION only when both heuristics miss (common on non-Workdo vendors).

1. Set the vendor version for branch + tag names.

   Most Laravel apps have no top-level "version" in composer.json (stock laravel/laravel skeleton). Workdo / many CodeCanyon Laravel items store the vendor semver in config/verification.php as system_version — try that before asking the user. Other vendors: CodeCanyon item page, README, or changelog.

   # Heuristic 1 — composer (often empty)
   VERSION="$(grep -E '"version"\s*:' composer.json 2>/dev/null | grep -oE '[0-9]+(\.[0-9]+)+' | head -1)"
   # Heuristic 2 — Workdo family (config/verification.php → system_version)
   [ -n "$VERSION" ] || VERSION="$(grep -E "['\"]system_version['\"]" config/verification.php 2>/dev/null | grep -oE '[0-9]+(\.[0-9]+)+' | head -1)"
   : "${VERSION:?export VERSION=x.y.z — both heuristics missed; set from CodeCanyon item / README / changelog}"
   echo "Vendor version: $VERSION"
   # Expected: VERSION is set — Workdo often fills via verification.php; else export VERSION=7.6 (your item's semver)

   • ✅ VERSION is the Workdo / vendor semver you will freeze (export VERSION=… only when both greps return nothing).

2. Safety-check — prove _source/ is fully ignored (not partial), .vscode/ stays out, and global excludes cannot corrupt C1, before staging.

   git check-ignore -q _source/ && echo "_source/ ignored OK" || { echo "STOP: add /_source/ to .gitignore"; exit 1; }
   git check-ignore -q _source/license.txt 2>/dev/null && echo "license under _source ignored OK" || { echo "STOP: full /_source/ ignore only — no ! negation for license"; exit 1; }
   git check-ignore -q .vscode/settings.json 2>/dev/null && echo ".vscode ignored OK" || echo "note: .vscode not written yet — OK"
   git status --short _source/ 2>/dev/null | grep . && { echo "STOP: _source/ visible to git"; exit 1; } || echo "_source/ absent from status OK"
   GLOBAL="$(git config --get core.excludesFile || true)"
   GLOBAL_SHADOW=0
   if [ -n "$GLOBAL" ] && [ -f "$GLOBAL" ]; then
     echo "Global excludesFile: $GLOBAL"
     for f in phpunit.xml composer.json .env.example artisan; do
       test -f "$f" || continue
       if git check-ignore -v "$f" 2>/dev/null | grep -Fq "$GLOBAL"; then
         echo "FAIL: $f shadowed by global excludesFile ($GLOBAL)"
         GLOBAL_SHADOW=1
       fi
     done
     if [ "$GLOBAL_SHADOW" -eq 1 ]; then
       echo "FAIL: global excludesFile shadows app-critical files (listed above)"
       echo "STOP: plain git add is forbidden for C1 — continue ONLY at step 3 with git -c core.excludesFile=/dev/null add -A"
     else
       echo "global excludesFile present — no shadow on app-critical files OK"
     fi
   fi
   # Expected: all _source / .vscode ignore checks OK; global shadow → FAIL + mandatory neutralized staging in step 3

   • ✅ _source/ is fully gitignored (including license paths).
   • ✅ If core.excludesFile shadows app-critical files, the step prints FAIL/STOP (not a warning) and C1 must use neutralized staging in step 3 — never plain git add.

3. Stage, verify the index, commit pristine vendor only, then freeze branch + tag and point develop at the same commit.

   Use git diff --cached --name-only with root-anchored paths — immune to status.showUntrackedFiles=all listing resources/views/vendor/… as untracked noise.

   Use an annotated author tag — lightweight git tag author-v… fails with fatal: no tag message? when tag.gpgSign=true or tag.forceSignAnnotated=true (common on signed-tag setups).

   git config --get core.excludesFile && echo "note: global excludes file exists — neutralized for C1 staging" || true
   git -c core.excludesFile=/dev/null add -A
   git -c core.excludesFile=/dev/null status --porcelain | head -40
   for f in phpunit.xml composer.json .env.example artisan; do
     test -f "$f" || continue
     git check-ignore -q "$f" 2>/dev/null && continue
     git diff --cached --name-only -- "$f" | grep -qx "$f" \
       || { echo "STOP! $f on disk but missing from C1 index — re-run with git -c core.excludesFile=/dev/null add -A"; exit 1; }
   done
   echo "app-critical index cross-check OK"
   git diff --cached --name-only | grep -E '^(vendor/|node_modules/)' && { echo "STOP! /vendor/ or /node_modules/ not ignored — fix bootstrap .gitignore"; exit 1; } || echo "deps not in index OK"
   git diff --cached --name-only | grep -xE '^\.env$' && { echo "STOP! .env staged"; exit 1; } || echo ".env not in index OK"
   git diff --cached --name-only | grep -E '^(_source/|\.vscode/)' && { echo "STOP! archive/editor staged"; exit 1; } || echo "archive/editor not in index OK"
   git status --short | head -30    # review: vendor tree + .gitignore only — no _source/, .vscode/, .claude/
   git commit -m "📦 Import v${VERSION} from CodeCanyon (pristine author baseline)"
   git branch "author/v${VERSION}"   # frozen — never commit here again
   git tag -a "author-v${VERSION}" -m "Import v${VERSION} from CodeCanyon (pristine author baseline)"   # permanent diff anchor
   git branch -M develop             # working branch starts here; AI commits advance develop only
   git log -1 --oneline
   git branch --list 'author/*' && git tag --list 'author-*'
   # Expected: one commit; author/vX.X.X branch + annotated author-vX.X.X tag; current branch develop

   • ✅ C1 was staged with core.excludesFile=/dev/null, so global ignores cannot shadow files like phpunit.xml.
   • ✅ Every on-disk app-critical file (phpunit.xml, composer.json, .env.example, artisan) that is not repo-ignored appears in the C1 index — hard-stop if any is missing.
   • ✅ Cached paths include no vendor/, node_modules/, .env, _source/, or .vscode/; git log -1 is the pristine import; author/v${VERSION} and annotated author-v${VERSION} exist; git branch --show-current prints develop.

Never commit customizations on author/v*

All AI System files, .vscode/, and every future customization land on develop (or your working branch) — never on author/v*. The frozen branch stays vendor-pristine forever.

7. Write editor config for this repo — one clean PHP language server

Write .vscode/ after the baseline commit so it never enters the pristine snapshot. It stays on disk, uncommitted until C2 at machine setup. Machine-wide extension installs are global — same page §2.

Who does this

🤖 Agent

1. .vscode/settings.json — exclude _source/ from indexing. intelephense.files.exclude is the load-bearing line: Intelephense indexes via its own exclude and does not reliably honor VS Code’s files.exclude, so without it the LSP re-indexes the whole _source/ duplicate. Use search/watcher excludes — not files.exclude, which would hide _source/ from the Explorer and fight the “explore it to verify” workflow.

   {
     "intelephense.files.exclude": ["**/_source/**", "**/node_modules/**", "**/vendor/**/{Tests,tests}/**"],
     "search.exclude": { "_source/**": true },
     "files.watcherExclude": { "**/_source/**": true },
     "php.suggest.basic": false,
     "php.validate.enable": false,
     "editor.formatOnSave": true,
     "[blade]": {
       "editor.defaultFormatter": "shufo.vscode-blade-formatter"
     }
   }

   • ✅ vendor/ stays indexed (framework autocomplete); only _source/ is excluded, and it’s still visible in the Explorer.
   • ✅ php.suggest.basic / php.validate.enable are off — the built-in PHP language features step aside so only Intelephense runs (one LSP; pairs with the competitor-uninstall in machine setup).

2. .vscode/extensions.json — the canonical six (identical to machine setup; do not extend one list without updating the other).

   Extension	Marketplace ID
   Intelephense	bmewburn.vscode-intelephense-client
   Laravel Blade	onecentlin.laravel-blade
   Blade formatter	shufo.vscode-blade-formatter
   Laravel 5 Snippets	onecentlin.laravel5-snippets
   Laravel Extra IntelliSense	amiralizadeh9480.laravel-extra-intellisense
   EditorConfig	editorconfig.editorconfig

   {
     "recommendations": [
       "bmewburn.vscode-intelephense-client",
       "onecentlin.laravel-blade",
       "shufo.vscode-blade-formatter",
       "onecentlin.laravel5-snippets",
       "amiralizadeh9480.laravel-extra-intellisense",
       "editorconfig.editorconfig"
     ]
   }

   git check-ignore -q .vscode/settings.json && echo "vscode gitignored OK (until C2)" || echo "note: already un-ignored"
   ls .vscode/settings.json .vscode/extensions.json
   # Expected: both files exist on disk; not in the pristine baseline; committed at C2

   • ✅ .vscode/*.json files exist on disk; they are not in the pristine baseline commit. Blade files now have an actual formatter instead of formatOnSave silently doing nothing for .blade.php.

Checklist

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

• 👤 Folder open — the project folder is the workspace root in your IDE, with Claude Code running inside it.
• 👤 Staged in _source/ — CodeCanyon ZIP, extracted folder, and license .txt files are in _source/.
• 🤖 App path verified — the folder inside _source/ that contains artisan + composer.json is identified.
• 🤖 _source/ fully gitignored — /_source/ in bootstrap .gitignore; git check-ignore -v _source/ _source/license.txt matches; no !_source/… negation; git status shows nothing under _source/.
• 🤖 Anchored bootstrap git — leading-slash anchors + /_source/; then git init; git status shows no vendor/, node_modules/, .env, or .env.*.
• 🤖 App copied to root — artisan + composer.json sit at the project root; the ZIP + extracted tree + license files remain in _source/ on disk (copied, not moved; never committed).
• 🤖 Completeness gate passes — rsync -ain --exclude='/.gitignore' "$APP_DIR"/ ./ prints zero >f lines; bootstrap .gitignore header still present; nested Laravel .gitignore files at root; .env/dotfiles at root. Verified by filesystem, not git add.
• 🤖 Pristine baseline frozen — one commit with vendor + .gitignore only; global-excludes hard-stop passed (or no core.excludesFile); staged with git -c core.excludesFile=/dev/null add -A; app-critical index cross-check OK (phpunit.xml etc. when on disk); author/vX.X.X branch + author-vX.X.X tag exist; develop is current; git log --oneline -1 is the import message.
• 🤖 Editor config on disk — .vscode/settings.json + .vscode/extensions.json written (uncommitted until C2 at machine setup), including the Blade formatter extension + [blade] formatter setting.
• 🤖 No composer install yet — dependency install waits for local development.

→Next step

Machine setup