maestro

name	maestro
description	Maestro monorepo orchestrator for the official Laravel starter kits. Use this skill when making changes to any starter kit source files, building kits, running tests, or working with the kit inheritance hierarchy, placeholder system, teams feature, or any development workflow in this repo.

Maestro Skill

What is Maestro

Maestro is the monorepo orchestrator for the official Laravel starter kits. All starter kit source files live here and get built out to individual repositories. Changes are made in this repo, and Maestro automatically creates PRs for the affected starter kit repos after merge.

Project Structure

maestro/
├── kits/              # Source files for all starter kits (inheritance-based layering)
├── orchestrator/      # Laravel app that builds and watches starter kits
├── build/             # Generated starter kit (git-ignored) — make changes here during dev
├── browser_tests/     # Cross-kit browser tests for CI
└── .github/           # GitHub workflows

Commands

All commands below run from the orchestrator/ directory unless noted otherwise.

Command	Description
php artisan build	Build a starter kit into build/. Interactive or use flags (see below).
php artisan build --kit=vue	Build Vue Fortify kit directly.
php artisan build --kit=svelte --blank	Build Blank Svelte kit.
php artisan build --kit=livewire --workos	Build Livewire WorkOS kit.
php artisan build --kit=react --teams	Build React Fortify kit with Teams.
php artisan build --kit=vue --workos --teams	Build Vue WorkOS kit with Teams.
composer kit:run	Start dev server + file watcher (syncs build/ back to kits/).
composer kits:pint	Run Pint on kits/ and browser_tests/.
composer kits:lint	Run kits:pint, then lint/format Inertia variants and sync back.
composer kits:check	Build and run CI checks (composer setup && composer ci:check) for all 21 kit variants sequentially.
composer kits:browser-tests	Build and run browser tests for all 8 Fortify kit variants (4 base + 4 teams).
php artisan fortify:matrix --kit=React	Run all Fortify auth_features permutations for one kit.
npm run watch:kits	Run only the file watcher (no dev server).
composer setup && composer ci:check	Run inside build/ — installs deps, builds frontend, runs checks (see below).

Selective Execution

Pass --livewire, --react, --svelte, and/or --vue to target specific frameworks. Pass --blank, --fortify, --workos, --components, and/or --teams to target specific variants. Combine both to narrow down exactly which kit variants to run:

composer kits:check -- --react --svelte
composer kits:check -- --vue --svelte --fortify     # Vue and Svelte, Fortify variants only
composer kits:check -- --livewire --fortify --workos # Livewire Fortify and WorkOS only
composer kits:check -- --workos                      # all frameworks, WorkOS variant only
composer kits:lint -- --vue
composer kits:lint -- --livewire                     # runs only the shared Pint step (no frontend lint phase)
composer kits:browser-tests -- --vue

No flags runs the full default matrix for each command.

Available --kit values defined in orchestrator/app/Enums/StarterKit.php.

CI Checks (composer ci:check)

Every starter kit has a ci:check composer script that validates the kit without auto-fixing. Run composer setup first to install dependencies and build the frontend (composer setup runs composer install, npm install, and npm run build, which generates the Wayfinder types used by the frontend checks).

Inertia kits run: Vite+ formatting and linting via npm run check, framework type checking via npm run types:check, then @test (Pint + PHPUnit).

Livewire kits run: @test (pint + PHPUnit) only.

Fortify Feature Matrix

Run from orchestrator/: php artisan fortify:matrix --kit=React|Svelte|Vue|Livewire.

Add --teams or Livewire-only --components as needed. The command builds build/, snapshots it, applies every auth_features permutation through chisel.php, and runs lint/checks for each result. Inertia matrix checks use Bun only; if Bun is missing, let it fail.

Starter Kit Variants (21 total)

These are the full starter kit identifiers written to orchestrator/storage/app/private/starter_kit and used by orchestrator/scripts/watch.js for layer syncing.

Stack	Variant Identifier	Auth / Feature Set
Livewire	livewire-blank	Blank (no auth)
Livewire	livewire	Fortify
Livewire	livewire-components	Fortify + Components
Livewire	livewire-workos	WorkOS
Livewire	livewire-teams	Fortify + Teams
Livewire	livewire-workos-teams	WorkOS + Teams
React	react-blank	Blank (no auth)
React	react	Fortify
React	react-workos	WorkOS
React	react-teams	Fortify + Teams
React	react-workos-teams	WorkOS + Teams
Svelte	svelte-blank	Blank (no auth)
Svelte	svelte	Fortify
Svelte	svelte-workos	WorkOS
Svelte	svelte-teams	Fortify + Teams
Svelte	svelte-workos-teams	WorkOS + Teams
Vue	vue-blank	Blank (no auth)
Vue	vue	Fortify
Vue	vue-workos	WorkOS
Vue	vue-teams	Fortify + Teams
Vue	vue-workos-teams	WorkOS + Teams

Kit Inheritance Hierarchy

Starter kits are built by layering folders in priority order. Higher-priority layers override files from lower ones.

Inertia (React / Svelte / Vue)

Shared/Blank
  → Inertia/Blank/Base
    → Inertia/Blank/{React|Svelte|Vue}
      → Shared/Base
        → Inertia/Base
          → Inertia/{React|Svelte|Vue}

For Fortify variant, add:
            → Shared/Fortify
              → Inertia/Fortify/Base
                → Inertia/Fortify/{React|Svelte|Vue}

For WorkOS variant, add:
            → Shared/WorkOS
              → Inertia/WorkOS/Base
                → Inertia/WorkOS/{React|Svelte|Vue}

For Teams (on top of Fortify or WorkOS), add:
                  → Shared/Teams/Base
                    → Shared/Teams/{Fortify|WorkOS}
                      → Inertia/Teams/Base
                        → Inertia/Teams/{React|Svelte|Vue}
                          → Inertia/Teams/{Fortify|WorkOS}/Base
                            → Inertia/Teams/{Fortify|WorkOS}/{React|Svelte|Vue}

Livewire

Shared/Blank
  → Livewire/Blank
    → Shared/Base
      → Livewire/Base
        → Shared/Fortify → Livewire/Fortify [→ Livewire/Components]
        OR Shared/WorkOS → Livewire/WorkOS

For Teams (on top of Fortify or WorkOS), add:
          → Shared/Teams/Base
            → Shared/Teams/{Fortify|WorkOS}
              → Livewire/Teams/Base
                → Livewire/Teams/{Fortify|WorkOS}

What This Means for Editing

• The watcher (orchestrator/scripts/watch.js) syncs changes from build/ back to the most specific layer in kits/.
• If a file exists in both Shared/Blank and Inertia/Fortify/Svelte, editing it in build/ syncs to Inertia/Fortify/Svelte.
• Files in kits/Shared/ affect all kits. Files in kits/Inertia/Svelte/ only affect Svelte.
• The watcher restores placeholders (e.g., {{dashboard}}) before syncing back — you don't need to worry about placeholders when editing in build/.
• Fortify kits use chisel.php plus @chisel-* markers to remove optional auth features. Keep markers wide enough that removed sections leave valid PHP/TS/Vue/Svelte/Blade.
• In kit Chisel scripts, prefer Chisel helpers ($c->npm()->run(...), $c->npm()->remove(...)) over hardcoded package-manager shell calls; Chisel follows the generated kit's Node runtime.

Kits Folder Structure

kits/
├── Shared/
│   ├── Blank/       # Foundation: config, migrations, artisan, phpunit.xml, .env.example
│   ├── Base/        # Factories, bootstrap, gitignore
│   ├── Fortify/     # Auth Actions, Concerns, Providers, config/fortify.php
│   ├── WorkOS/      # WorkOS routes, migrations, config
│   └── Teams/
│       ├── Base/        # Core teams: models, trait, actions, events, middleware, policies, rules, notifications, migrations, factories, config
│       ├── Fortify/     # Fortify-specific: CreateNewUser (creates personal team), LoginResponse, RegisterResponse, UserFactory
│       └── WorkOS/      # WorkOS-specific: CreatePersonalTeam listener, auth routes, UserFactory
│
├── Inertia/
│   ├── Blank/
│   │   ├── Base/          # Shared Inertia backend (controllers, middleware, routes)
│   │   ├── React/         # React blank resources
│   │   ├── Svelte/        # Svelte blank resources
│   │   └── Vue/           # Vue blank resources
│   ├── Base/              # Authenticated backend (settings controllers, middleware, tests)
│   ├── React/             # React authenticated frontend
│   ├── Svelte/            # Svelte authenticated frontend
│   ├── Vue/               # Vue authenticated frontend
│   ├── Fortify/
│   │   ├── Base/          # Fortify backend (auth controllers, providers, tests)
│   │   ├── React/         # React auth pages
│   │   ├── Svelte/        # Svelte auth pages
│   │   └── Vue/           # Vue auth pages
│   ├── WorkOS/
│   │   ├── Base/          # WorkOS backend
│   │   ├── React/         # React WorkOS pages
│   │   ├── Svelte/        # Svelte WorkOS pages
│   │   └── Vue/           # Vue WorkOS pages
│   └── Teams/
│       ├── Base/              # Inertia teams backend: controllers, requests, routes, middleware, tests
│       ├── React/             # React teams UI: components (TeamSwitcher, AppHeader, etc.), pages, types
│       ├── Svelte/            # Svelte teams UI: components (TeamSwitcher, AppHeader, etc.), pages, types
│       ├── Vue/               # Vue teams UI: components (TeamSwitcher, AppHeader, etc.), pages, types
│       ├── Fortify/
│       │   ├── Base/          # Fortify teams backend: User model, FortifyServiceProvider, routes, auth tests
│       │   ├── React/         # React Fortify teams: welcome page, settings layout
│       │   ├── Svelte/        # Svelte Fortify teams: welcome page, settings layout
│       │   └── Vue/           # Vue Fortify teams: welcome page, settings layout
│       └── WorkOS/
│           ├── Base/          # WorkOS teams backend: User model, routes
│           ├── React/         # React WorkOS teams: welcome page, settings layout
│           ├── Svelte/        # Svelte WorkOS teams: welcome page, settings layout
│           └── Vue/           # Vue WorkOS teams: welcome page, settings layout
│
└── Livewire/
    ├── Blank/
    ├── Base/
    ├── Fortify/
    ├── Components/        # Multi-file Blade components variant
    ├── WorkOS/
    └── Teams/
        ├── Base/              # Livewire teams: Blade views (header, sidebar, team-switcher, team pages), tests
        ├── Fortify/           # Livewire Fortify teams: User model, FortifyServiceProvider, settings layout, routes, auth tests
        └── WorkOS/            # Livewire WorkOS teams: User model, settings layout, routes

Placeholder System

The build process replaces {{placeholder}} tokens in files with framework-specific values. The mapping lives in orchestrator/scripts/ui-components.json. For example:

• {{dashboard}} → Dashboard (Svelte/Vue) or dashboard (React)
• {{auth_login}} → auth/Login (Svelte/Vue) or auth/login (React)
• {{teams_index}} → teams/Index (Vue) or teams/index (React)
• {{teams_edit}} → teams/Edit (Vue) or teams/edit (React)

Svelte and Vue use PascalCase page names. React uses kebab-case.

Teams Feature

Teams is an additive layer that can be enabled on top of Fortify or WorkOS auth variants. It is not available with --blank or --components variants.

Build Flag

Use --teams with any kit + auth variant combination:

php artisan build --kit=react --teams           # React + Fortify + Teams
php artisan build --kit=vue --workos --teams     # Vue + WorkOS + Teams
php artisan build --kit=livewire --teams         # Livewire + Fortify + Teams

In interactive mode, you'll be prompted "Would you like to enable the Teams feature?" after selecting an auth variant (unless Blank is selected).

Supported Variants

Stack	Fortify + Teams	WorkOS + Teams
React	react-teams	react-workos-teams
Vue	vue-teams	vue-workos-teams
Livewire	livewire-teams	livewire-workos-teams
Svelte	svelte-teams	svelte-workos-teams

These identifiers are written to orchestrator/storage/app/private/starter_kit and used by the watch script to determine which kit layers to sync.

Architecture Overview

Core (Shared/Teams/Base): Models (Team, Membership, TeamInvitation), HasTeams trait (added to User model), TeamRole enum (Owner/Admin/Member with permission-based access), CreateTeam action, 9 domain events, 3 notifications (invitation, acceptance, removal), TeamPolicy, EnsureMembership and SetTeamUrlDefaults middleware, validation rules, migrations, factories, and config/teams.php.

Auth variant overrides:

• Fortify (Shared/Teams/Fortify): Overrides CreateNewUser to create a personal team on registration. Custom LoginResponse/RegisterResponse/TwoFactorLoginResponse that resolve the current team and set URL defaults before redirecting.
• WorkOS (Shared/Teams/WorkOS): Uses a CreatePersonalTeam event listener on Laravel's Registered event. Overrides auth routes to include team context after authentication.

Inertia controllers (Inertia/Teams/Base): TeamController (CRUD + switch), TeamMemberController (role update, removal), TeamInvitationController (create, cancel, accept). Routes defined in routes/teams.php with EnsureMembership middleware.

Frontend components (per framework in Inertia/Teams/{React|Svelte|Vue}): TeamSwitcher, CreateTeamModal, AppHeader, AppSidebar, NavUser, UserInfo, Dashboard, teams/index page, teams/edit page, TypeScript types.

Livewire views (Livewire/Teams/Base): Blade components for team-switcher, header, sidebar, desktop-user-menu. Team pages: index, edit, accept-invitation.

Roles and Permissions

Role	Level	Permissions
Owner	3	team:update, team:delete, member:add, member:update, member:remove, invitation:create, invitation:cancel
Admin	2	team:update, invitation:create, invitation:cancel
Member	1	(none)

Only Admin and Member roles are assignable. Owner is automatically set on team creation.

Key Team Files

File	Purpose
kits/Shared/Teams/Base/app/Concerns/HasTeams.php	User trait: team relationships, switching, permissions
kits/Shared/Teams/Base/app/Models/Team.php	Team model with slug routing, soft deletes
kits/Shared/Teams/Base/app/Enums/TeamRole.php	Role enum with hierarchical permissions
kits/Shared/Teams/Base/app/Actions/Teams/CreateTeam.php	Team creation action (transaction, events)
kits/Shared/Teams/Base/config/teams.php	Team config: user model, invitation settings
kits/Inertia/Teams/Base/app/Http/Controllers/Teams/	Team, member, and invitation controllers
kits/Inertia/Teams/Base/routes/teams.php	Team routes with EnsureMembership middleware

Workflow

1. Build: cd orchestrator && php artisan build --kit=svelte
2. Develop: composer kit:run (starts dev server at localhost:8000 + watcher)
3. Edit: If build/ exists and the watcher is running, make changes in build/ — the watcher syncs them to kits/. Otherwise, edit kits/ directly.
4. Stop kit:run: Press Ctrl+C before running kits:lint or kits:check — running them while the watcher is active corrupts kits/.
5. Test: composer kits:pint → composer kits:lint (Inertia only) → composer kits:check
6. Commit: Commit the changes in kits/ (not build/)
7. PR: Create PR; after merge, Maestro auto-creates PRs for affected kit repos

Browser Tests (Local CI Parity)

To run browser tests for all kits locally, run from the orchestrator/ directory:

composer kits:browser-tests

This builds each variant (4 Fortify + 4 Fortify Teams), copies the appropriate browser tests, installs dependencies, and runs the tests — matching the steps in .github/workflows/browser-tests.yml.

Browser tests are split into three layers under browser_tests/:

• browser_tests/bootstrap/ — shared Pest config, TestCase, and phpunit.xml. Copied for all 8 jobs.
• browser_tests/common/ — Fortify browser tests. Copied only for non-teams builds.
• browser_tests/teams/ — Teams browser tests. Copied only for Teams builds.

Each variant runs exactly one test suite (common or teams), not both.

Per-Kit Command Sequence

Run from the repo root unless noted:

# 1) Install orchestrator dependencies
cd orchestrator
composer install --no-interaction --prefer-dist

# 2) Build the target kit (replace <Kit> with Livewire, React, Svelte, or Vue)
#    Add --teams for Teams variants
php artisan build --kit=<Kit>
cd ..

# 3) Copy browser test bootstrap + suite into build/
cp -r browser_tests/bootstrap/* build/
cp -r browser_tests/common/* build/      # For non-teams variants
# cp -r browser_tests/teams/* build/     # For Teams variants instead

# 4) Install browser testing dependencies in build/
cd build
composer remove --dev phpunit/phpunit --no-interaction --no-update
composer require --dev pestphp/pest pestphp/pest-plugin-browser pestphp/pest-plugin-laravel --no-interaction
npm install
npm install playwright@1.61.1  # Pinned: Playwright 1.62 removed server-side timeouts that pest-plugin-browser relies on

# 5) Install Playwright browsers/deps
npx playwright install --with-deps

# 6) Prepare app env and build frontend assets
cp .env.example .env
php artisan key:generate
npm run build

# 7) Run browser tests
php vendor/bin/pest --parallel
cd ..

Key Files Reference

File	Purpose
orchestrator/app/Console/Commands/BuildCommand.php	Build orchestration logic
orchestrator/app/Enums/StarterKit.php	Available kit enum
orchestrator/scripts/watch.js	File watcher: syncs build → kits with placeholder restoration
orchestrator/scripts/run.js	Dev server launcher
orchestrator/scripts/ui-components.json	Placeholder → framework-specific name mapping
orchestrator/storage/app/private/starter_kit	Stores which kit is currently built
orchestrator/CLAUDE.md	Laravel Boost guidelines (PHP, Laravel 12, Pest 4, Tailwind v4)

Important Rules

1. Where to edit: If a build/ folder exists at the project root and composer kit:run is running (dev server + file watcher), make changes in build/ — the watcher syncs them back to kits/. If there is no build/ folder or the watcher is not running, edit kits/ directly. Always commit in kits/ regardless.
2. Follow sibling patterns: When creating a Svelte file, check the React and Vue equivalents for expected structure and behavior and vice-versa.
3. Layer awareness: Know which layer a file belongs to. Shared files affect all kits. Framework-specific files only affect that framework. Teams layers sit on top of auth layers — place team-specific code in the appropriate Teams/ directory.
4. Placeholder awareness: Files in kits/ contain {{placeholders}}. Files in build/ have resolved values. The watcher handles conversion.
5. Lint/check while watcher is stopped: kits:lint and kits:check both delete and rebuild build/ for each variant. If kit:run is active, the watcher interprets those deletions as file removals and propagates them to kits/, corrupting the source. Always stop kit:run before running kits:lint or kits:check. kits:pint is safe to run at any time — it operates directly on kits/ and never touches build/.
6. Lint changes: Run composer kits:pint for fast PHP formatting of kits/ and browser_tests/. Run composer kits:lint to run Pint then lint/format all Inertia variants and sync changes back to kits/.
7. Test after changes: Run composer setup && composer ci:check inside build/ to verify nothing is broken.
8. Teams layer placement: When modifying teams code, choose the correct layer: Shared/Teams/Base for cross-stack logic (models, traits, middleware), Shared/Teams/{Fortify|WorkOS} for auth-variant-specific overrides, or for stack-specific backend, and or for frontend/variant-specific UI.