Informações permanentes do projeto mantidas pelo Specsfy

O Specsfy separa a descrição durável do sistema das especificações de cada mudança. O arquivo PROJECT.md explica a finalidade da aplicação, enquanto cinco documentos em .specsfy/ registram a stack, as instruções confirmadas, a persistência observada no código, os pacotes instalados e o perfil de interação do setup. As regras macro de interface ficam em DESIGNSYSTEM.MD, na raiz do projeto, e seguem um ciclo próprio com a skill especialista de design system.

Execute $specsfy-setup depois de instalar o framework. Depois disso, o framework a executa obrigatoriamente antes de iniciar cada skill, inclusive em transições automáticas, para verificar e reconciliar os contextos iniciais e os blocos reservados de agentes. Na mesma conversa, a raiz confirmada é reaproveitada sem perguntar de novo. A skill detecta Laravel, Next.js e Astro pelos manifests e sugere o modelo correspondente. $specsfy-documentator acrescenta e atualiza PACKAGES.md. Juntas, as skills mantêm esta estrutura:

1
<projeto>/
2
├── PROJECT.md
3
├── DESIGNSYSTEM.MD
4
├── docs/
5
│   └── packages/
6
│       ├── README.md
7
│       └── <vendor>-<nome>.md
8
└── .specsfy/
9
    ├── STACK.md
10
    ├── RULES.md
11
    ├── DATABASE.md
12
    ├── PACKAGES.md
13
    ├── USER-PROFILE.md
14
    └── SPECKIT.md      # somente quando GitHub Spec Kit for detectado

O setup também reserva blocos delimitados para as diretrizes do Specsfy em AGENTS.md e CLAUDE.md. Conteúdo fora desses blocos pertence ao usuário e é preservado. A referência publicável das diretrizes vive em specsfy-setup.

Os modelos ficam em .specsfy/templates/Project.md, Stack.md, Rules.md, Database.md e UserProfile.md, junto dos demais templates do framework. Para personalizar um deles, mantenha o mesmo nome em .specsfy/templates/custom/, essa cópia tem precedência e não é alterada pelo CLI.

Durante o setup, .specsfy/USER-PROFILE.md guarda o nível de conhecimento confirmado e as respostas já fornecidas. O agente consulta esse arquivo, a conversa e as fontes do projeto antes de perguntar. Assuntos já respondidos ficam fora da próxima rodada, perguntas técnicas recebem mais contexto para iniciantes e podem usar versões, arquitetura e integrações diretamente para pessoas experientes.

O setup também verifica como você administra cada informação principal do produto. Quando a jornada precisa de cadastro e manutenção, ele confirma as ações de criar, consultar, editar e apagar. Informações somente de leitura, históricos imutáveis e conteúdos mantidos por integrações não recebem um CRUD sem necessidade. Se o código e os documentos não deixarem essa necessidade clara, o setup pergunta antes de registrar a cobertura.

Para cada tela de uso recorrente, o setup identifica o caminho pelos menus do sistema. Ele registra item, destino, permissão e comportamento responsivo em INTERFACE.md. Rotas técnicas e etapas abertas apenas por redirecionamento podem ficar fora do menu. Quando o destino ou a presença do link estiverem abertos, você escolhe em uma pergunta numerada antes da continuação.

Ao terminar a preparação dos contextos e especialistas, o setup executa $specsfy-documentator. Essa etapa reconstrói a documentação técnica de todo o sistema existente em docs/ e atualiza .specsfy/PACKAGES.md, mesmo quando a execução não começou por uma alteração recente no código.

Use $specsfy-data-discovery antes de implementar quando ainda faltar explicar o que o produto precisa guardar, quem consulta cada informação e quando ela deixa de ser necessária. A skill registra as respostas confirmadas em uma seção própria de DATABASE.md, separada do que o código detectar depois.

Projeto existente com GitHub Spec Kit

O setup reconhece o GitHub Spec Kit pela constituição em .specify/memory/constitution.md. Quando ela existe, a skill lê a constituição e todos os arquivos regulares dentro de specs/, inclusive specs, planos, tarefas, contratos e anexos. O resultado aparece em .specsfy/SPECKIT.md como uma lista de caminhos, títulos, tipos e fingerprints SHA-256.

Abra as fontes listadas antes de trabalhar na feature correspondente. A constituição continua governando o projeto e os artefatos do GitHub Spec Kit permanecem nos caminhos originais. O setup não escreve, move, converte ou remove arquivos de .specify/ e specs/.

Você pode acrescentar notas próprias fora do bloco specsfy:speckit em .specsfy/SPECKIT.md. Uma nova execução atualiza somente o bloco delimitado. Se a constituição divergir de .specsfy/RULES.md, preserve os dois textos e resolva a divergência antes de alterar a feature.

Execute $specsfy-aux-stack após alterar frameworks, runtimes, ferramentas estruturais ou persistência. Execute $specsfy-aux-database sempre que criar ou alterar banco, schema, tabela, coleção, model persistente, campo, relação, índice ou migration. Use $specsfy-aux-rules para formular e acrescentar uma regra confirmada sem duplicar ou apagar regras anteriores.

Monitoramento durante mudanças

O monitor é executado pelas skills no início e no fim de uma mudança. Ele lê os arquivos staged, unstaged e untracked do Git para descobrir qual documento precisa ser revisto, mas não permanece como daemon em segundo plano:

1
node .agents/skills/specsfy-setup/scripts/monitor_context.mjs \
2
  --project . --check

PENDING impede a conclusão da tarefa e do Delivery Gate. Quando uma mudança de aplicação não altera história, finalidade, capacidades ou limites, registre essa avaliação na evidência da tarefa e execute novamente com --acknowledge-project-no-change. Para uma revisão de regras sem regra nova, use --acknowledge-rules-no-change somente depois de registrar a justificativa. Veja a topologia e o --check no guia de documentação técnica do sistema.

Preservação e atualização

• O setup cria um arquivo de informações somente quando ele ainda não existe. Isso inclui DESIGNSYSTEM.MD e .specsfy/USER-PROFILE.md: os templates iniciais apresentam padrões comuns de interface, CRUD, dashboard e registro da conversa. Os arquivos continuam humanos e qualquer conteúdo existente é preservado.
• As auxiliares atualizam apenas blocos detectados delimitados e preservam seções humanas.
• Uma nova varredura nunca autoriza remover silenciosamente uma definição humana.
• DATABASE.md usa tabelas Markdown para facilitar mapeamento e comparação.
• PACKAGES.md deriva de manifests, lockfiles e metadados locais, preservando texto humano fora do bloco gerado.
• Valores sensíveis não são lidos nem registrados. Cite somente nomes seguros de variáveis e caminhos das fontes.

O estado implementado é comprovado pelas fontes do próprio projeto. Os manifests e lockfiles mostram a stack, enquanto schemas e migrations mostram a persistência. Os documentos resumem essas evidências e as definições humanas que precisam permanecer entre mudanças. Eles não substituem a spec.md, não registram gates e nunca devem copiar segredos, valores de .env ou registros de produção.