Preparar contexto do projeto
Garanta que o projeto tem um contexto persistente correto antes de qualquer
outra skill trabalhar. O setup lê o sistema existente, cria apenas os arquivos
de contexto ausentes, atualiza somente blocos reservados e encaminha lacunas
para as skills responsáveis. Ele não cria telas, rotas, persistência nem specs.
Modo de interação
Modo de interação: perguntas.
Antes de formular qualquer pergunta, leia e aplique o
Contrato de perguntas numeradas de .specsfy/Spec.md.
Escolher o caminho
| Situação |
Caminho |
| A raiz já foi confirmada nesta conversa e o setup completo já rodou |
Caminho curto |
| Primeira execução na conversa, contexto ausente ou pedido explícito de configuração |
Caminho completo |
O monitor retornou PENDING |
Caminho curto com a correção indicada |
Caminho curto
Use quando outra skill carrega o setup ou quando há handoff automático.
Reutilize a raiz confirmada, sem perguntar de novo.
Nas execuções obrigatórias seguintes da mesma conversa, a confirmação
inicial continua válida.
Execute o monitor:
node .agents/skills/specsfy-setup/scripts/monitor_context.mjs \
--project <raiz> --check
Em Laravel, execute também check_database_safety.mjs --project <raiz>
(seção Proteção do banco durante o setup).
Se tudo estiver atual, devolva o controle à skill chamadora. Se houver
PENDING, resolva pela tabela de handoffs da seção Monitorar e resolver pendências e repita o monitor.
Caminho completo
Siga as etapas na ordem. As leituras dentro de uma mesma etapa podem ser feitas
em paralelo; as etapas dependem do resultado da anterior.
- Confirmar a raiz. Se a pessoa já informou um caminho, resolva-o para
caminho absoluto e repita-o. Se não informou, ofereça exatamente estas
opções numeradas e aguarde:
1. Usar o diretório atual.,
2. Usar um subdiretório do Hub. e 3. Informar outro caminho.. Não deduza
o destino pela raiz Git. Em um Hub, execute no subdiretório escolhido ou
passe --project <raiz> e --root <raiz> aos scripts; contexto, specs,
testes e código ficam dentro dessa raiz, nunca no diretório pai.
- Ler o projeto. Leia em paralelo
AGENTS.md, CLAUDE.md e as instruções
locais. Depois execute
node .agents/skills/specsfy-setup/scripts/inspect_project.mjs --project <raiz>
e leia as fontes na ordem retornada: instruções, manifests, configuração,
aplicação, rotas, persistência, integrações, interface, testes e
documentação. Em base grande, leia por grupos e diga quais fontes foram
lidas. Só proponha stack ou escreva algo depois de entender o sistema atual
e registrar o que será preservado; não ter lido uma fonte não autoriza
substituir suas convenções.
- Consultar referências quando couber. Leia
as diretrizes publicáveis para
auditar o bloco reservado nos arquivos de agentes. Quando
.specify/memory/constitution.md existir, leia
a compatibilidade com GitHub Spec Kit.
- Diagnosticar o ambiente. Execute
specsfy doctor --project <raiz> e
corrija cada requisito ausente (Node.js, Git, npm, acesso ao projeto e
npx) antes de continuar.
- Reconciliar o contexto. Execute
node .agents/skills/specsfy-setup/scripts/setup_context.mjs --project <raiz>.
Detalhes na seção Arquivos de contexto.
- Proteger o banco. Em Laravel, rode a conferência da seção
Proteção do banco durante o setup.
- Inspecionar o resultado. Abra os arquivos gerados, incluindo
.specsfy/USER-PROFILE.md e .specsfy/PACKAGES.md quando existir, e a
fonte de stack usada pelo script. Com .specsfy/SPECKIT.md, abra a
constituição e cada fonte original listada. Antes de qualquer descoberta de
interface, execute
node .agents/skills/specsfy-setup/scripts/inspect_interface.mjs --project <raiz>
e abra as rotas, componentes e telas relacionados ao pedido. A saída orienta
a leitura; não substitui as fontes.
- Conversar sobre lacunas. Siga as seções
Perfil de conhecimento e memória de respostas e Roteiro adaptativo do setup.
- Instalar especialistas. Siga a seção
Stack e especialistas instalados pelo setup.
- Completar stack, regras e dados. Anuncie o handoff e carregue
$specsfy-aux-stack, $specsfy-aux-rules ou $specsfy-aux-database,
conforme a lacuna.
- Documentar. Em toda execução completa do setup, carregue
$specsfy-documentator depois das auxiliares (seção Cobertura funcional obrigatória no setup).
- Gitflow, somente sob pedido. Quando a pessoa pedir ou indicar
explicitamente Gitflow (ver references/gitflow.md),
anuncie o handoff, carregue
$specsfy-specialist-gitflow e registre a
convenção de branches confirmada em RULES.md via $specsfy-aux-rules.
Uma branch develop ou outro sinal implícito no repositório não é pedido.
- Fechar. Execute o monitor novamente e resolva todo
PENDING.
Pronto quando
- A raiz está confirmada e todos os comandos usaram essa raiz.
monitor_context.mjs --check não retorna PENDING.
- Em Laravel,
check_database_safety.mjs retornou SAFE.
- Os arquivos de contexto existem, nenhum arquivo existente foi substituído e
os blocos reservados estão atualizados sem duplicação.
- O núcleo e os especialistas detectados foram instalados ou a falha foi
relatada com a saída do comando.
- Na execução completa,
docs/ e .specsfy/PACKAGES.md foram reconstruídos
pelo $specsfy-documentator.
- Repetir o setup com as mesmas entradas não altera nada.
Arquivos de contexto
O setup_context.mjs renderiza PROJECT.md, STACK.md, RULES.md,
DATABASE.md, INTERFACE.md, DESIGNSYSTEM.MD e .specsfy/USER-PROFILE.md
a partir de .specsfy/templates/custom/<Nome>.md quando existir; caso
contrário, usa os gerenciados .specsfy/templates/Project.md, Stack.md,
Rules.md, Database.md, Interface.md, DESIGNSYSTEM.MD e
UserProfile.md. O script não mantém modelos paralelos embutidos. Quando
detecta GitHub Spec Kit, o mesmo comando lê a constituição e todos os arquivos
regulares em specs/ e atualiza o bloco gerenciado de .specsfy/SPECKIT.md.
PROJECT.md, INTERFACE.md e DESIGNSYSTEM.MD ficam na raiz. O
DESIGNSYSTEM.MD nasce com defaults de interface comuns e só é criado
quando ainda não existe.
STACK.md, RULES.md, DATABASE.md, PACKAGES.md, USER-PROFILE.md e a
projeção opcional SPECKIT.md ficam em .specsfy/.
- Esses documentos são contexto derivado do projeto, não spec, gate nem
autorização de implementação.
- Nunca substitua um arquivo de contexto existente, mesmo incompleto: ele pode
conter decisões humanas. Em
AGENTS.md, CLAUDE.md e
.specsfy/SPECKIT.md, atualize somente o bloco delimitado do framework.
Nunca cabe ao setup escrever, mover, renomear ou remover arquivos em
.specify/ e specs/, porque pertencem ao Spec Kit e às specs existentes.
- Em projeto com mais de um framework, registre todas as fontes observadas, sem
escolher um único stack em silêncio. Sem framework identificado, crie o
modelo genérico e declare a confirmação como pendente.
- O setup inicial não cria
SEMVER, Dockerfile, compose.yaml,
stack.yaml, deploy nem ansible/. Versionamento e deploy começam só
quando a pessoa pedir; nesse caso, anuncie o handoff para
$specsfy-specialist-deploy.
- Toda execução é idempotente: com as mesmas entradas, não altera arquivos já
reconciliados, não duplica blocos e não inicia outra etapa.
Perfil de conhecimento e memória de respostas
O setup conduz uma conversa adaptativa curta. Não aplica questionário fixo e
não pergunta novamente algo já confirmado.
Antes de qualquer pergunta, leia em paralelo:
.specsfy/USER-PROFILE.md, quando existir;
- a conversa atual e as respostas já dadas;
PROJECT.md, DESIGNSYSTEM.MD, .specsfy/STACK.md,
.specsfy/RULES.md, .specsfy/DATABASE.md e .specsfy/PACKAGES.md;
AGENTS.md, CLAUDE.md, .specsfy/SPECKIT.md e as fontes listadas por
ele, quando existirem;
- Inbox, backlog e specs aplicáveis, sem alterar esses arquivos.
Monte um mapa de assuntos respondidos. Uma declaração explícita da pessoa ou
uma informação inequívoca nas fontes responde ao assunto, mesmo com outras
palavras. Pergunte somente por lacuna, conflito ou informação que mudou desde
a última confirmação.
Quando o nível geral ainda não estiver no perfil nem na conversa, faça esta
primeira rodada:
Pergunta 1. Como você prefere receber as orientações deste setup?
1. Iniciante: explique os termos técnicos e o efeito de cada escolha antes de prosseguir.
2. Intermediário: conheço os fundamentos e prefiro explicações curtas junto das escolhas.
3. Experiente: posso responder com detalhes de stack, arquitetura, comandos e integrações.
4. Escrever outra resposta
5. Gere outras opções
6. Avançar
Normalize a resposta para iniciante, intermediário ou experiente e grave
em .specsfy/USER-PROFILE.md com fonte e data. Com nível já confirmado, use-o
sem perguntar. Se conversa e perfil divergirem, faça uma única pergunta para
resolver o conflito e registre a atualização.
| Nível |
Como perguntar |
iniciante |
explique o termo técnico na própria pergunta, diga por que a resposta é necessária e o efeito prático de cada opção |
intermediário |
use o nome técnico e acrescente explicação curta só quando a escolha puder confundir |
experiente |
pergunte direto por versões, fronteiras de framework, autenticação, persistência, testes, observabilidade, deploy e contratos de integração ainda abertos |
O nível ajusta a linguagem e não autoriza presumir respostas. Se a pessoa
mostrar experiência diferente em uma área, adapte só aquela área. Depois de
cada resposta, registre área, assunto, resposta, fonte, data e alcance no
perfil, retire o assunto do mapa de lacunas e só então escolha a próxima
pergunta, dentro do limite de oito perguntas por área.
Roteiro adaptativo do setup
Depois de confirmar a raiz e ler o projeto, escolha o primeiro assunto
necessário ainda sem resposta confirmada:
- objetivo do produto e resultado principal;
- pessoas usuárias, equipes e papéis;
- acesso, autenticação e permissões;
- dados principais, relações e tempo de retenção;
- telas, navegação e estados da interface;
- testes, observabilidade e deploy;
- integrações externas e serviços dependentes.
Se a fonte já responde com clareza, registre a origem no perfil e passe ao
próximo. Se duas fontes divergem, pergunte só pela diferença. Com todos os
assuntos aplicáveis confirmados, avise que o setup segue para a reconciliação
dos arquivos, sem criar perguntas artificiais.
Cobertura funcional obrigatória no setup
Durante a leitura do produto, relacione cada entidade de negócio às ações que a
pessoa precisa executar. Quando a jornada exigir administrar registros,
confirme a cobertura de criar, consultar, editar e apagar. Não force CRUD para
dados somente de leitura, históricos imutáveis, eventos ou informações mantidas
por integração. Se as fontes não mostrarem quais ações são necessárias,
confirme com a pessoa em uma rodada do contrato numerado antes de registrar.
Para cada tela de uso recorrente, identifique como a pessoa chega até ela pelos
menus do sistema e registre o item, o destino, a permissão e o comportamento
responsivo em INTERFACE.md. Rota técnica, callback ou etapa acessada só por
redirecionamento pode ficar fora do menu quando a jornada comprovar o acesso.
Se não estiver claro se a tela recebe link ou em qual menu aparece, confirme
com a pessoa em uma única rodada.
O setup registra essas necessidades no contexto e encaminha mudança de
comportamento para backlog e spec. A implementação posterior cobre o CRUD e os
links confirmados, com tarefas e testes próprios.
Em toda execução completa do setup, carregue $specsfy-documentator depois de
reconciliar contextos e especialistas. Reconstrua a documentação técnica de
todo o sistema existente em docs/ e .specsfy/PACKAGES.md, mesmo sem mudança
recente em aplicação, persistência ou dependências. Preserve texto humano fora
dos blocos gerenciados e resolva qualquer PENDING antes de encerrar. Quando
aplicação, persistência ou dependências mudarem durante outra etapa, o
documentador roda de novo ao fim da implementação.
Proteção do banco durante o setup
Quando o projeto tiver artisan, execute:
node .agents/skills/specsfy-setup/scripts/check_database_safety.mjs \
--project <raiz>
Esta regra é inegociável, porque um teste no banco errado apaga dados reais:
- Exija
.env.testing com APP_ENV=testing e destino de banco declarado de
forma explícita, diferente do banco de desenvolvimento indicado no .env.
Valor ausente faria o Laravel herdar a configuração de desenvolvimento e não
é aceito. O script não mostra credenciais nem valores de conexão.
PENDING impede qualquer teste focal, suíte ou regressão. Corrija o
ambiente, repita a conferência e continue só após SAFE. Nenhum teste roda
no banco de desenvolvimento, nem para diagnóstico.
IGNORED indica comando ou configuração capaz de apagar estruturas ou
registros, como migrate:fresh. Ignore o comando e não ofereça opção para
forçar sua execução.
Monitorar e resolver pendências
Execute monitor_context.mjs --project <raiz> --check no início e no fim de
cada mudança. Não contorne um PENDING: atualize o documento indicado e rode o
monitor de novo.
| Pendência |
Responsável |
| stack |
$specsfy-aux-stack |
| regras confirmadas |
$specsfy-aux-rules |
| persistência |
$specsfy-aux-database |
PACKAGES.md ausente ou desatualizado, docs/ desatualizado |
$specsfy-documentator |
Para mudança de aplicação sem impacto material na história ou finalidade,
registre essa avaliação nas fontes da tarefa e repita com
--acknowledge-project-no-change. Para regras, use
--acknowledge-rules-no-change com a mesma disciplina. O reconhecimento serve
para registrar uma avaliação, não para ocultar mudança documental real.
Stack e especialistas instalados pelo setup
Depois de ler a stack:
Instale o núcleo essencial do Specsfy (tabela abaixo).
Execute specsfy skills detect --project <raiz>.
Mostre a tabela de correspondência com o núcleo e os especialistas
detectados e avise quais serão instalados. Ao iniciar o setup, a pessoa já
autorizou essa instalação. Instale apenas o núcleo e os detectados, sem
especialistas genéricos extras:
npx skills add https://github.com/promovaweb/specsfy \
--skill <especialista-detectado> --agent universal --copy -y --full-depth
Carregue os especialistas instalados necessários à etapa atual.
Se o comando falhar, informe nome, saída e a continuação possível. Não
substitua a instalação por cópia manual. Especialistas instalados
manualmente continuam válidos: não os remova nem reinstale sem necessidade.
| Stack observada |
Especialista instalado |
| Laravel |
specsfy-specialist-laravel |
| Pacote Laravel recebido por URL GitHub |
specsfy-specialist-laravel-package-manager |
| Supabase |
specsfy-specialist-supabase |
| PostgreSQL |
specsfy-specialist-postgres |
| Redis |
specsfy-specialist-redis |
| React |
specsfy-specialist-react e specsfy-specialist-react-ui-components |
| Astro |
specsfy-specialist-astro |
| Next.js |
specsfy-specialist-nextjs |
| TypeScript |
specsfy-specialist-typescript |
| Tailwind CSS |
specsfy-specialist-tailwind-css |
| shadcn/ui |
specsfy-specialist-shadcn-ui |
| Docker ou Compose |
specsfy-specialist-docker |
| Release ou deploy completo |
specsfy-specialist-deploy |
| Docker Swarm |
specsfy-specialist-docker-swarm |
| Ansible |
specsfy-specialist-ansible |
| OpenAPI |
specsfy-specialist-web-api-design |
| OpenTelemetry ou Prometheus |
specsfy-specialist-observability |
| CI/CD |
specsfy-specialist-delivery-engineering |
| Núcleo instalado em todo setup |
Finalidade |
specsfy-specialist-data-modeling |
dados, entidades, relações e ciclo de vida |
specsfy-specialist-domain-modeling |
linguagem, regras e limites de domínio |
specsfy-specialist-software-architecture |
módulos, dependências e estrutura técnica |
specsfy-specialist-reui |
base ReUI para interfaces e CRUDs React/Tailwind |
specsfy-specialist-shadcn-ui |
primitives, tema e registry para o ReUI |
Em todo projeto Laravel com React, shadcn/ui e ReUI são instalados juntos:
shadcn/ui prepara a base e ReUI cria CRUDs e interfaces sobre ela. Depois da
instalação, registre em INTERFACE.md que telas React são compostas por
componentes. Cada nova tela consulta esse mapa, reutiliza o que existe e
registra componentes próprios, primitives shadcn/ui e composições ReUI com
arquivos e consumidores reais.
Para toda aplicação Laravel, Laravel Octane com Open Swoole é obrigatório.
Confira laravel/octane em composer.json e composer.lock, a extensão
openswoole na imagem e --server=swoole no runtime. Registre a combinação em
.specsfy/STACK.md e encaminhe a instalação ou correção ausente para uma spec
antes de aprovar o setup.
1---2name: specsfy-setup3description: Prepara, reconcilia e monitora o contexto persistente de um projeto Specsfy (PROJECT.md, DESIGNSYSTEM.MD, INTERFACE.md, STACK, RULES, DATABASE, PACKAGES e USER-PROFILE), confere a proteção do banco de testes, instala os especialistas detectados e preserva projetos com GitHub Spec Kit. Use no início de qualquer skill Specsfy, quando o projeto ainda não tiver contexto, quando o monitor apontar PENDING ou quando a pessoa pedir para configurar o Specsfy. Não use para registrar ideias (specsfy-01-inbox), refinar backlog (specsfy-02-backlog) nem para manter só stack, regras ou banco (specsfy-aux-stack, specsfy-aux-rules, specsfy-aux-database).4metadata:5 source: https://skillmd.com/skills/promovaweb/specsfy-setup6---78# Preparar contexto do projeto910Garanta que o projeto tem um contexto persistente correto antes de qualquer11outra skill trabalhar. O setup lê o sistema existente, cria apenas os arquivos12de contexto ausentes, atualiza somente blocos reservados e encaminha lacunas13para as skills responsáveis. Ele não cria telas, rotas, persistência nem specs.1415## Modo de interação1617Modo de interação: `perguntas`.18Antes de formular qualquer pergunta, leia e aplique o19`Contrato de perguntas numeradas` de `.specsfy/Spec.md`.2021## Escolher o caminho2223| Situação | Caminho |24| --- | --- |25| A raiz já foi confirmada nesta conversa e o setup completo já rodou | Caminho curto |26| Primeira execução na conversa, contexto ausente ou pedido explícito de configuração | Caminho completo |27| O monitor retornou `PENDING` | Caminho curto com a correção indicada |2829### Caminho curto3031Use quando outra skill carrega o setup ou quando há handoff automático.32331. Reutilize a raiz confirmada, sem perguntar de novo.34 Nas execuções obrigatórias seguintes da mesma conversa, a confirmação35 inicial continua válida.362. Execute o monitor:3738 ```bash39 node .agents/skills/specsfy-setup/scripts/monitor_context.mjs \40 --project <raiz> --check41 ```42433. Em Laravel, execute também `check_database_safety.mjs --project <raiz>`44 (seção `Proteção do banco durante o setup`).454. Se tudo estiver atual, devolva o controle à skill chamadora. Se houver46 `PENDING`, resolva pela tabela de handoffs da seção `Monitorar e resolver47 pendências` e repita o monitor.4849### Caminho completo5051Siga as etapas na ordem. As leituras dentro de uma mesma etapa podem ser feitas52em paralelo; as etapas dependem do resultado da anterior.53541. **Confirmar a raiz.** Se a pessoa já informou um caminho, resolva-o para55 caminho absoluto e repita-o. Se não informou, ofereça exatamente estas56 opções numeradas e aguarde: `1. Usar o diretório atual.`,57 `2. Usar um subdiretório do Hub.` e `3. Informar outro caminho.`. Não deduza58 o destino pela raiz Git. Em um Hub, execute no subdiretório escolhido ou59 passe `--project <raiz>` e `--root <raiz>` aos scripts; contexto, specs,60 testes e código ficam dentro dessa raiz, nunca no diretório pai.612. **Ler o projeto.** Leia em paralelo `AGENTS.md`, `CLAUDE.md` e as instruções62 locais. Depois execute63 `node .agents/skills/specsfy-setup/scripts/inspect_project.mjs --project <raiz>`64 e leia as fontes na ordem retornada: instruções, manifests, configuração,65 aplicação, rotas, persistência, integrações, interface, testes e66 documentação. Em base grande, leia por grupos e diga quais fontes foram67 lidas. Só proponha stack ou escreva algo depois de entender o sistema atual68 e registrar o que será preservado; não ter lido uma fonte não autoriza69 substituir suas convenções.703. **Consultar referências quando couber.** Leia71 [as diretrizes publicáveis](references/framework-instructions.md) para72 auditar o bloco reservado nos arquivos de agentes. Quando73 `.specify/memory/constitution.md` existir, leia74 [a compatibilidade com GitHub Spec Kit](references/github-spec-kit.md).754. **Diagnosticar o ambiente.** Execute `specsfy doctor --project <raiz>` e76 corrija cada requisito ausente (Node.js, Git, npm, acesso ao projeto e77 `npx`) antes de continuar.785. **Reconciliar o contexto.** Execute79 `node .agents/skills/specsfy-setup/scripts/setup_context.mjs --project <raiz>`.80 Detalhes na seção `Arquivos de contexto`.816. **Proteger o banco.** Em Laravel, rode a conferência da seção82 `Proteção do banco durante o setup`.837. **Inspecionar o resultado.** Abra os arquivos gerados, incluindo84 `.specsfy/USER-PROFILE.md` e `.specsfy/PACKAGES.md` quando existir, e a85 fonte de stack usada pelo script. Com `.specsfy/SPECKIT.md`, abra a86 constituição e cada fonte original listada. Antes de qualquer descoberta de87 interface, execute88 `node .agents/skills/specsfy-setup/scripts/inspect_interface.mjs --project <raiz>`89 e abra as rotas, componentes e telas relacionados ao pedido. A saída orienta90 a leitura; não substitui as fontes.918. **Conversar sobre lacunas.** Siga as seções `Perfil de conhecimento e92 memória de respostas` e `Roteiro adaptativo do setup`.939. **Instalar especialistas.** Siga a seção `Stack e especialistas instalados94 pelo setup`.9510. **Completar stack, regras e dados.** Anuncie o handoff e carregue96 `$specsfy-aux-stack`, `$specsfy-aux-rules` ou `$specsfy-aux-database`,97 conforme a lacuna.9811. **Documentar.** Em toda execução completa do setup, carregue99 `$specsfy-documentator` depois das auxiliares (seção `Cobertura funcional100 obrigatória no setup`).10112. **Gitflow, somente sob pedido.** Quando a pessoa pedir ou indicar102 explicitamente Gitflow (ver [references/gitflow.md](references/gitflow.md)),103 anuncie o handoff, carregue `$specsfy-specialist-gitflow` e registre a104 convenção de branches confirmada em `RULES.md` via `$specsfy-aux-rules`.105 Uma branch `develop` ou outro sinal implícito no repositório não é pedido.10613. **Fechar.** Execute o monitor novamente e resolva todo `PENDING`.107108## Pronto quando109110- A raiz está confirmada e todos os comandos usaram essa raiz.111- `monitor_context.mjs --check` não retorna `PENDING`.112- Em Laravel, `check_database_safety.mjs` retornou `SAFE`.113- Os arquivos de contexto existem, nenhum arquivo existente foi substituído e114 os blocos reservados estão atualizados sem duplicação.115- O núcleo e os especialistas detectados foram instalados ou a falha foi116 relatada com a saída do comando.117- Na execução completa, `docs/` e `.specsfy/PACKAGES.md` foram reconstruídos118 pelo `$specsfy-documentator`.119- Repetir o setup com as mesmas entradas não altera nada.120121## Arquivos de contexto122123O `setup_context.mjs` renderiza `PROJECT.md`, `STACK.md`, `RULES.md`,124`DATABASE.md`, `INTERFACE.md`, `DESIGNSYSTEM.MD` e `.specsfy/USER-PROFILE.md`125a partir de `.specsfy/templates/custom/<Nome>.md` quando existir; caso126contrário, usa os gerenciados `.specsfy/templates/Project.md`, `Stack.md`,127`Rules.md`, `Database.md`, `Interface.md`, `DESIGNSYSTEM.MD` e128`UserProfile.md`. O script não mantém modelos paralelos embutidos. Quando129detecta GitHub Spec Kit, o mesmo comando lê a constituição e todos os arquivos130regulares em `specs/` e atualiza o bloco gerenciado de `.specsfy/SPECKIT.md`.131132- `PROJECT.md`, `INTERFACE.md` e `DESIGNSYSTEM.MD` ficam na raiz. O133 `DESIGNSYSTEM.MD` nasce com defaults de interface comuns e só é criado134 quando ainda não existe.135- `STACK.md`, `RULES.md`, `DATABASE.md`, `PACKAGES.md`, `USER-PROFILE.md` e a136 projeção opcional `SPECKIT.md` ficam em `.specsfy/`.137- Esses documentos são contexto derivado do projeto, não spec, gate nem138 autorização de implementação.139- Nunca substitua um arquivo de contexto existente, mesmo incompleto: ele pode140 conter decisões humanas. Em `AGENTS.md`, `CLAUDE.md` e141 `.specsfy/SPECKIT.md`, atualize somente o bloco delimitado do framework.142 Nunca cabe ao setup escrever, mover, renomear ou remover arquivos em143 `.specify/` e `specs/`, porque pertencem ao Spec Kit e às specs existentes.144- Em projeto com mais de um framework, registre todas as fontes observadas, sem145 escolher um único stack em silêncio. Sem framework identificado, crie o146 modelo genérico e declare a confirmação como pendente.147- O setup inicial não cria `SEMVER`, `Dockerfile`, `compose.yaml`,148 `stack.yaml`, `deploy` nem `ansible/`. Versionamento e deploy começam só149 quando a pessoa pedir; nesse caso, anuncie o handoff para150 `$specsfy-specialist-deploy`.151- Toda execução é idempotente: com as mesmas entradas, não altera arquivos já152 reconciliados, não duplica blocos e não inicia outra etapa.153154## Perfil de conhecimento e memória de respostas155156O setup conduz uma conversa adaptativa curta. Não aplica questionário fixo e157não pergunta novamente algo já confirmado.158159Antes de qualquer pergunta, leia em paralelo:1601611. `.specsfy/USER-PROFILE.md`, quando existir;1622. a conversa atual e as respostas já dadas;1633. `PROJECT.md`, `DESIGNSYSTEM.MD`, `.specsfy/STACK.md`,164 `.specsfy/RULES.md`, `.specsfy/DATABASE.md` e `.specsfy/PACKAGES.md`;1654. `AGENTS.md`, `CLAUDE.md`, `.specsfy/SPECKIT.md` e as fontes listadas por166 ele, quando existirem;1675. Inbox, backlog e specs aplicáveis, sem alterar esses arquivos.168169Monte um mapa de assuntos respondidos. Uma declaração explícita da pessoa ou170uma informação inequívoca nas fontes responde ao assunto, mesmo com outras171palavras. Pergunte somente por lacuna, conflito ou informação que mudou desde172a última confirmação.173174Quando o nível geral ainda não estiver no perfil nem na conversa, faça esta175primeira rodada:176177```text178Pergunta 1. Como você prefere receber as orientações deste setup?1791. Iniciante: explique os termos técnicos e o efeito de cada escolha antes de prosseguir.1802. Intermediário: conheço os fundamentos e prefiro explicações curtas junto das escolhas.1813. Experiente: posso responder com detalhes de stack, arquitetura, comandos e integrações.1824. Escrever outra resposta1835. Gere outras opções1846. Avançar185```186187Normalize a resposta para `iniciante`, `intermediário` ou `experiente` e grave188em `.specsfy/USER-PROFILE.md` com fonte e data. Com nível já confirmado, use-o189sem perguntar. Se conversa e perfil divergirem, faça uma única pergunta para190resolver o conflito e registre a atualização.191192| Nível | Como perguntar |193| --- | --- |194| `iniciante` | explique o termo técnico na própria pergunta, diga por que a resposta é necessária e o efeito prático de cada opção |195| `intermediário` | use o nome técnico e acrescente explicação curta só quando a escolha puder confundir |196| `experiente` | pergunte direto por versões, fronteiras de framework, autenticação, persistência, testes, observabilidade, deploy e contratos de integração ainda abertos |197198O nível ajusta a linguagem e não autoriza presumir respostas. Se a pessoa199mostrar experiência diferente em uma área, adapte só aquela área. Depois de200cada resposta, registre área, assunto, resposta, fonte, data e alcance no201perfil, retire o assunto do mapa de lacunas e só então escolha a próxima202pergunta, dentro do limite de oito perguntas por área.203204## Roteiro adaptativo do setup205206Depois de confirmar a raiz e ler o projeto, escolha o primeiro assunto207necessário ainda sem resposta confirmada:2082091. objetivo do produto e resultado principal;2102. pessoas usuárias, equipes e papéis;2113. acesso, autenticação e permissões;2124. dados principais, relações e tempo de retenção;2135. telas, navegação e estados da interface;2146. testes, observabilidade e deploy;2157. integrações externas e serviços dependentes.216217Se a fonte já responde com clareza, registre a origem no perfil e passe ao218próximo. Se duas fontes divergem, pergunte só pela diferença. Com todos os219assuntos aplicáveis confirmados, avise que o setup segue para a reconciliação220dos arquivos, sem criar perguntas artificiais.221222## Cobertura funcional obrigatória no setup223224Durante a leitura do produto, relacione cada entidade de negócio às ações que a225pessoa precisa executar. Quando a jornada exigir administrar registros,226confirme a cobertura de criar, consultar, editar e apagar. Não force CRUD para227dados somente de leitura, históricos imutáveis, eventos ou informações mantidas228por integração. Se as fontes não mostrarem quais ações são necessárias,229confirme com a pessoa em uma rodada do contrato numerado antes de registrar.230231Para cada tela de uso recorrente, identifique como a pessoa chega até ela pelos232menus do sistema e registre o item, o destino, a permissão e o comportamento233responsivo em `INTERFACE.md`. Rota técnica, callback ou etapa acessada só por234redirecionamento pode ficar fora do menu quando a jornada comprovar o acesso.235Se não estiver claro se a tela recebe link ou em qual menu aparece, confirme236com a pessoa em uma única rodada.237238O setup registra essas necessidades no contexto e encaminha mudança de239comportamento para backlog e spec. A implementação posterior cobre o CRUD e os240links confirmados, com tarefas e testes próprios.241242Em toda execução completa do setup, carregue `$specsfy-documentator` depois de243reconciliar contextos e especialistas. Reconstrua a documentação técnica de244todo o sistema existente em `docs/` e `.specsfy/PACKAGES.md`, mesmo sem mudança245recente em aplicação, persistência ou dependências. Preserve texto humano fora246dos blocos gerenciados e resolva qualquer `PENDING` antes de encerrar. Quando247aplicação, persistência ou dependências mudarem durante outra etapa, o248documentador roda de novo ao fim da implementação.249250## Proteção do banco durante o setup251252Quando o projeto tiver `artisan`, execute:253254```bash255node .agents/skills/specsfy-setup/scripts/check_database_safety.mjs \256 --project <raiz>257```258259Esta regra é inegociável, porque um teste no banco errado apaga dados reais:260261- Exija `.env.testing` com `APP_ENV=testing` e destino de banco declarado de262 forma explícita, diferente do banco de desenvolvimento indicado no `.env`.263 Valor ausente faria o Laravel herdar a configuração de desenvolvimento e não264 é aceito. O script não mostra credenciais nem valores de conexão.265- `PENDING` impede qualquer teste focal, suíte ou regressão. Corrija o266 ambiente, repita a conferência e continue só após `SAFE`. Nenhum teste roda267 no banco de desenvolvimento, nem para diagnóstico.268- `IGNORED` indica comando ou configuração capaz de apagar estruturas ou269 registros, como `migrate:fresh`. Ignore o comando e não ofereça opção para270 forçar sua execução.271272## Monitorar e resolver pendências273274Execute `monitor_context.mjs --project <raiz> --check` no início e no fim de275cada mudança. Não contorne um `PENDING`: atualize o documento indicado e rode o276monitor de novo.277278| Pendência | Responsável |279| --- | --- |280| stack | `$specsfy-aux-stack` |281| regras confirmadas | `$specsfy-aux-rules` |282| persistência | `$specsfy-aux-database` |283| `PACKAGES.md` ausente ou desatualizado, `docs/` desatualizado | `$specsfy-documentator` |284285Para mudança de aplicação sem impacto material na história ou finalidade,286registre essa avaliação nas fontes da tarefa e repita com287`--acknowledge-project-no-change`. Para regras, use288`--acknowledge-rules-no-change` com a mesma disciplina. O reconhecimento serve289para registrar uma avaliação, não para ocultar mudança documental real.290291## Stack e especialistas instalados pelo setup292293Depois de ler a stack:2942951. Instale o núcleo essencial do Specsfy (tabela abaixo).2962. Execute `specsfy skills detect --project <raiz>`.2973. Mostre a tabela de correspondência com o núcleo e os especialistas298 detectados e avise quais serão instalados. Ao iniciar o setup, a pessoa já299 autorizou essa instalação. Instale apenas o núcleo e os detectados, sem300 especialistas genéricos extras:301302 ```bash303 npx skills add https://github.com/promovaweb/specsfy \304 --skill <especialista-detectado> --agent universal --copy -y --full-depth305 ```3063074. Carregue os especialistas instalados necessários à etapa atual.3085. Se o comando falhar, informe nome, saída e a continuação possível. Não309 substitua a instalação por cópia manual. Especialistas instalados310 manualmente continuam válidos: não os remova nem reinstale sem necessidade.311312| Stack observada | Especialista instalado |313| --- | --- |314| Laravel | `specsfy-specialist-laravel` |315| Pacote Laravel recebido por URL GitHub | `specsfy-specialist-laravel-package-manager` |316| Supabase | `specsfy-specialist-supabase` |317| PostgreSQL | `specsfy-specialist-postgres` |318| Redis | `specsfy-specialist-redis` |319| React | `specsfy-specialist-react` e `specsfy-specialist-react-ui-components` |320| Astro | `specsfy-specialist-astro` |321| Next.js | `specsfy-specialist-nextjs` |322| TypeScript | `specsfy-specialist-typescript` |323| Tailwind CSS | `specsfy-specialist-tailwind-css` |324| shadcn/ui | `specsfy-specialist-shadcn-ui` |325| Docker ou Compose | `specsfy-specialist-docker` |326| Release ou deploy completo | `specsfy-specialist-deploy` |327| Docker Swarm | `specsfy-specialist-docker-swarm` |328| Ansible | `specsfy-specialist-ansible` |329| OpenAPI | `specsfy-specialist-web-api-design` |330| OpenTelemetry ou Prometheus | `specsfy-specialist-observability` |331| CI/CD | `specsfy-specialist-delivery-engineering` |332333| Núcleo instalado em todo setup | Finalidade |334| --- | --- |335| `specsfy-specialist-data-modeling` | dados, entidades, relações e ciclo de vida |336| `specsfy-specialist-domain-modeling` | linguagem, regras e limites de domínio |337| `specsfy-specialist-software-architecture` | módulos, dependências e estrutura técnica |338| `specsfy-specialist-reui` | base ReUI para interfaces e CRUDs React/Tailwind |339| `specsfy-specialist-shadcn-ui` | primitives, tema e registry para o ReUI |340341Em todo projeto Laravel com React, shadcn/ui e ReUI são instalados juntos:342shadcn/ui prepara a base e ReUI cria CRUDs e interfaces sobre ela. Depois da343instalação, registre em `INTERFACE.md` que telas React são compostas por344componentes. Cada nova tela consulta esse mapa, reutiliza o que existe e345registra componentes próprios, primitives shadcn/ui e composições ReUI com346arquivos e consumidores reais.347348Para toda aplicação Laravel, Laravel Octane com Open Swoole é obrigatório.349Confira `laravel/octane` em `composer.json` e `composer.lock`, a extensão350`openswoole` na imagem e `--server=swoole` no runtime. Registre a combinação em351`.specsfy/STACK.md` e encaminhe a instalação ou correção ausente para uma spec352antes de aprovar o setup.