Imported from VictorStochero/laravel-worktree (skills/laravel-worktree/SKILL.md). Install upstream with npx skills add VictorStochero/laravel-worktree --skill laravel-worktree. Copyright stays with the author.

Laravel Worktree (multi-runtime)

Cria e opera git worktrees isolados para projetos Laravel — um ambiente paralelo completo por branch, sem tocar no checkout original. O runtime local (Herd / DDEV / Sail) muda só os detalhes de shell, domínio, banco e ciclo de container; o esqueleto (git worktree, base branch, .env, verificação da suíte) é comum. O foco é provisionamento rápido: subir o ambiente paralelo pronto para uso. O provisionamento nunca executa testes — apenas confirma que a suíte está descobrível.

Três operações: criar, inspecionar, limpar.

Validação: o branch Herd foi exercitado ponta a ponta. Os branches DDEV e Sail tiveram os comandos conferidos contra a documentação oficial (03/09/2026), mas não foram executados num ambiente real — confirmar o primeiro uso em cada um e abrir issue com o que divergir.

Passo 0 — Detectar o runtime

Decidir o runtime ativo (primeira condição que casar; em ambiguidade, perguntar):

• DDEV → existe .ddev/config.yaml no repo.
• Sail → existe vendor/bin/sail (ou ./vendor/bin/sail) e um docker-compose.yml/compose.yaml referenciando laravel/sail, e não há .ddev/.
• Herd → caso contrário (PHP no host; macOS/Windows com Herd). É o default.

Cada runtime define quatro coisas, usadas pelas operações abaixo:

Os comandos git rodam sempre no shell do host (nunca dentro do container), em qualquer runtime. No Windows isso significa PowerShell: instalações com MinGit não trazem bash, então não assumir que existe uma ferramenta Bash disponível.

Conceitos comuns (todos os runtimes)

• Entradas: flag ∈ { feature, fix, hotfix, chore, docs, test, refactor }; contexto em kebab-case; data = hoje AAAAMMDD; repo = nome do diretório do repositório.
• Pasta: {repo}-{flag}-{contexto} — sem data: a pasta vira o domínio local ({pasta}.test no Herd) e a data só polui a URL. Branch: {flag}/{AAAAMMDD}-{contexto} — a data fica aqui, onde é útil (histórico, ordenação, PRs). O par pasta↔branch se recupera de git worktree list --porcelain, nunca de parsing do nome da pasta.
• Não aninhar: se git rev-parse --git-dir ≠ --git-common-dir e não for submódulo (git rev-parse --show-superproject-working-tree vazio), já se está num worktree — parar.
• Colisão (checar antes de criar): pasta de destino já existente, ou branch já existente (git rev-parse --verify {branch}), ou worktree já registrado para essa branch (git worktree list) → parar e perguntar (reaproveitar o worktree existente? outro contexto? limpar o antigo primeiro?). Sem a data no nome da pasta, repetir o mesmo {flag} {contexto} colide de propósito — é o comportamento desejado, não um erro a contornar sozinho.
• Nomes de banco (Herd): {ctx_} = contexto com - trocado por _ (hífen em nome de banco obriga backtick e quebra em vários pontos). Dev = {db}_wt_{ctx_}, teste = {db}_wt_{ctx_}_test; multi-tenant → TENANCY_DB_PREFIX = {db}_wt_{ctx_}_tenant_. MySQL/MariaDB limitam nome de banco a 64 caracteres: se estourar, truncar o {ctx_} (nunca o sufixo _test, que é o que separa os dois bancos) e reportar o nome final ao usuário.
• Base remota: git fetch; derivar a base na primeira que existir em origin/: desenvolvimento → dev → develop → main. Gravar em {pasta}/.worktree-base e, uma única vez, acrescentar a linha .worktree-base a .git/info/exclude do repo — o info/exclude é comum a todos os worktrees, e sem isso o arquivo aparece untracked no git status de cada um (e acaba commitado por acidente).
• .env (chaves presentes apenas): APP_URL → domínio do runtime; multi-tenant (detectar config/tenancy.php ou stancl/tenancy) → CENTRAL_DOMAIN/TENANT_BASE_DOMAIN = domínio, SESSION_DOMAIN = .{domínio-base}; prefixos únicos (REDIS_PREFIX/CACHE_PREFIX ou REDIS_DB distinto); Warden child (detectar config/warden.php + WARDEN_MODE=child) → WARDEN_ENABLED=false; manter APP_KEY.
• Localização: worktree sempre fora do repo. No Herd, pasta-irmã na raiz parkeada. Nunca usar ferramenta de worktree nativa que ignore o setup do runtime (domínio/.env/DB).

Operação A — CRIAR

1. Detectar runtime (Passo 0), não aninhar e checar colisão (pasta/branch/worktree já existentes).
2. Base remota + git worktree add <destino> -b {branch} origin/{base}; gravar .worktree-base.
   • Herd: <destino> = <raiz_herd>/{pasta}.
   • DDEV/Sail: <destino> pode ser pasta-irmã qualquer fora do repo.
3. .env: copiar da origem e aplicar os ajustes comuns. Banco por runtime:
   • Herd: DB_DATABASE (e TENANCY_DB_DATABASE/TENANCY_DB_PREFIX se existirem) pelos nomes de banco definidos nos conceitos comuns.
   • DDEV/Sail: banco é isolado pelo container — não apontar para um DB compartilhado; manter o esquema do runtime (DDEV injeta db; Sail usa o serviço do compose). No Sail, todo worktree que sobe ao mesmo tempo precisa de COMPOSE_PROJECT_NAME e de todas as portas publicadas únicas: APP_PORT, VITE_PORT, FORWARD_DB_PORT e as FORWARD_*_PORT dos serviços presentes no compose (Redis, Mailpit, Meilisearch…). Basta uma repetida para o up falhar com port is already allocated.
4. Subir o ambiente do runtime:
   • Herd: nada a subir (a pasta já é servida). Criar o DB dedicado (PDO via .php temporário → CREATE DATABASE IF NOT EXISTS, apagar o temp).
   • DDEV: ddev config --project-name={pasta} --project-type=laravel --docroot=public (ou copiar .ddev/config.yaml e trocar o name) → ddev start.
   • Sail: garantir vendor/ (passo 5) e sail up -d.
5. Dependências:
   • Herd: composer install. Em Windows, se falhar por ext-pcntl/ext-posix (Horizon e libs Unix-only), repetir com --ignore-platform-req=ext-pcntl --ignore-platform-req=ext-posix (+ as extensões reportadas).
   • DDEV: ddev composer install (container tem pcntl/posix — sem flags).
   • Sail: composer install no host para obter vendor/bin/sail, depois sail composer install se preferir paridade de container.
6. Migrar: migrate --seed pelo shell do runtime (limpo + seed — não clonar dados). Herd: php artisan migrate --seed. DDEV: ddev artisan migrate --seed. Sail: sail artisan migrate --seed.
7. storage:link pelo shell do runtime.
8. Front-end: se houver package.json, npm install (Herd) / ddev npm install / sail npm install (+ build se necessário).
9. Ambiente de teste: se houver .env.testing versionado, alinhar o host de DB ao runtime ativo. Um .env.testing apontando para db/mysql (DDEV/Docker) quebra no Herd (getaddrinfo for db failed) e vice-versa. Se existir um exemplo do runtime (.env.testing.example-herd, .env.testing.example-ddev, etc.), sobrepor o correto como .env.testing e usar um banco de teste dedicado ao worktree (nomes nos conceitos comuns; no DDEV/Sail o do próprio container); criá-lo e migrar com migrate --env=testing. Banco de teste compartilhado entre worktrees é falha garantida: RefreshDatabase/migrate:fresh de um derruba o schema do outro, e o sintoma (Table ... already exists, coluna desconhecida, suíte inteira vermelha) não parece concorrência.
10. Verificar a suíte — nunca rodá-la: o provisionamento jamais executa a suíte de testes, nem inteira, nem por --testsuite, nem "só os Unit". A verificação é ... artisan test --list-tests: a listagem sozinha já faz o boot da app e valida autoload, .env.testing, conexão com o banco de teste e descoberta dos testes — em segundos, sem executar um único teste. Se a listagem falhar (fatal, host de DB errado, autoload quebrado), reportar e perguntar. Rodar a suíte é decisão do usuário, depois, sob demanda — e aí não confundir regressão nova com falha pré-existente (URL/host hardcoded, ou teste que depende da suíte inteira ter migrado o banco de teste).

Reportar (criação)

Pasta + URL; branch + base (.worktree-base); bancos criados (dev e teste, com os nomes finais); verificação da suíte (descoberta OK / falha + causa). Dizer explicitamente que nenhum teste foi executado — rodar a suíte fica a cargo do usuário.

Operação B — INSPECIONAR

1. git worktree list --porcelain → pasta, branch, HEAD.
2. Enriquecer (best-effort): URL (pelo runtime + nome da pasta), base (.worktree-base), banco/projeto, e estado sujo (git -C <pasta> status -sb).
3. Tabela: pasta | branch | base | URL | banco/projeto | sujo?. Sinalizar órfãos (pasta sumiu, registro existe) → sugerir git worktree prune. Para DDEV, complementar com ddev list.

Operação C — LIMPAR

Confirmar antes de qualquer passo destrutivo.

1. Identificar alvo (pasta/branch). Ler {pasta}/.env (banco) e .worktree-base antes de remover.
2. Salvaguarda: git -C <pasta> status -sb — havendo mudanças não commitadas/não enviadas, avisar e exigir confirmação explícita.
3. Teardown do runtime (libera o banco isolado):
   • DDEV: ddev delete --omit-snapshot --yes {pasta} (remove projeto + banco). Sem --yes o comando pede confirmação interativa e trava numa sessão não-interativa; ddev delete não apaga a pasta de código — quem faz isso é o passo 4.
   • Sail: sail down -v na pasta (remove containers + volumes).
   • Herd: dropar os bancos dedicados — dev, _test e, em multi-tenant, todos os que começam com o prefixo de tenant do worktree (SHOW DATABASES LIKE '{db}_wt_{contexto}%' e conferir a lista com o usuário antes) — via .php temporário (DROP DATABASE IF EXISTS, apagar o temp).
4. git worktree remove <pasta> (--force só se necessário e confirmado). No Windows, o remove pode esvaziar o registro mas deixar a pasta (lock de arquivo) — conferir e apagar o residual com Remove-Item -Recurse -Force <pasta>.
5. git branch -d <branch> (-D só se não mergeada e confirmado).
6. git worktree prune.

Reportar (limpeza)

O que foi removido (pasta, branch, banco/projeto) e o que foi preservado/abortado por salvaguarda.

Pull Request

PR sempre com alvo na base de .worktree-base (nunca main se a origem foi develop/dev/desenvolvimento): gh pr create --base <base> --head <branch>.

Red flags

• Worktree dentro do repo ou aninhado.
• Misturar shells/domínios de runtimes (ex.: php artisan no host num projeto DDEV; .test no Sail).
• Clonar dados da origem em vez de migrate --seed limpo.
• Executar testes no provisionamento — suíte inteira, --testsuite=Unit, --filter "só para conferir": nada disso. A verificação é --list-tests e só. Também não tratar falha pré-existente como bloqueio.
• Banco de teste compartilhado entre worktrees (ou com o checkout original) — cada worktree tem o seu, senão um RefreshDatabase derruba o outro.
• Datar o nome da pasta (polui a URL) ou tentar deduzir a branch a partir do nome da pasta em vez de git worktree list --porcelain.
• Dropar banco / ddev delete / sail down -v / --force sem confirmar mudanças não salvas.