name: bootstrap-starter-app description: Bootstrap a fresh Laravel app from this starter kit repo into ~/projects using the bundled deterministic shell script. Use when Codex should create a new project with fresh git history, keep the first commit identical to the starter kit snapshot, seed a project README from the user's app brief, start the app locally through the shared proxy flow, and avoid extra app-specific edits during bootstrap.

Bootstrap Starter App

Goal

Create a fresh app from this starter kit in ~/projects/<project-name> without inheriting git history while still seeding the new repo with the app's own README.

The root commit in the new repo must be the starter kit snapshot. If the user provides enough product context, bootstrap should also add a project README in a second commit so the repo starts with the app brief already captured.

Default Workflow

Use the bundled script first:

./.codex/skills/bootstrap-starter-app/scripts/bootstrap_starter_app.sh

This is the default path because it is deterministic and uses this repo as the source starter kit automatically.

Collect Inputs

• If the user did not provide a project name, ask one concise plain-text question: What should the new project be called?
• Default the target directory to ~/projects/<project-name> unless the user explicitly asks for another location.
• Default to starting the app locally after bootstrap unless the user explicitly says not to.
• If the user provides enough product context, write a concise project README before running the script and pass it with --readme-file.
• Do not create a remote or make other tracked app-specific edits during bootstrap unless the user explicitly asks for that in the same turn.

Script Contract

Run the script with:

./.codex/skills/bootstrap-starter-app/scripts/bootstrap_starter_app.sh \
  --project-name <project-name> \
  --readme-file /absolute/path/to/README.md

Useful options:

• --source-dir <path> to bootstrap from a different starter repo
• --target-root <path> to create the app somewhere other than ~/projects
• --start none to prepare the project without bringing Sail up
• --no-seed to skip the default user seed
• --readme-file <path> to copy a project README into the new repo and commit it after the starter root commit

What The Script Does

1. Verifies the source starter repo is clean.
2. Copies the tracked starter files from the source commit with git archive.
3. Initializes a fresh git repo in the new project.
4. Makes the root commit before local environment changes.
5. Copies .env.example to .env and writes project-specific local hosts.
6. Runs:
   • composer install
   • ./bin/local-up.sh
   • ./vendor/bin/sail artisan key:generate --ansi
   • ./vendor/bin/sail artisan migrate --force --ansi
   • ./vendor/bin/sail artisan db:seed --force
   • ./vendor/bin/sail npm ci
   • ./vendor/bin/sail npm run build
7. If --readme-file is provided, copies it to README.md and makes a second commit with the project brief.
8. Fails if bootstrap leaves tracked changes in the generated app.
9. Prints the local URLs, direct ports, source commit, and seeded login.

Verification

After the script succeeds:

• report the exact app directory
• report the source commit used
• report whether a README commit was added
• confirm whether the new repo has a remote
• verify at least the app root and login route using the proxy app URL

Prefer the repo-local playwright-route-smoke-test skill for route verification when Playwright CLI works on the machine. If Playwright CLI is unavailable or broken, report that briefly and fall back to direct HTTP checks for / and /login so bootstrap work is not blocked by tooling.