Digite para filtrar as páginas da documentação.

    Specsfy

    Referência rápida do Specsfy: arquivos, estados e comandos

    Consulte em uma página os arquivos, estados, gates, Effort, skills, comandos do CLI, proteções e o glossário do Specsfy durante o trabalho no projeto.

    Onde fica cada coisa

    Caminho O que guarda
    specs/inbox/ capturas que ainda precisam de tratamento
    specs/inbox/processed/ capturas já cobertas por specs aprovadas
    specs/backlog/<NNNN>-<slug>.md itens escolhidos para refinamento
    specs/<estado>/<NNNN>-<slug>/spec.md fonte única de uma entrega
    specs/<estado>/<NNNN>-<slug>/research/ evidências de pesquisa indexadas pela spec
    specs.md e specs/milestones/MNN.md projeção de milestones, specs e backlog
    PROJECT.md história, finalidade, capacidades e limites do projeto
    INTERFACE.md registro do design system e dos componentes reutilizáveis
    DESIGNSYSTEM.MD orientações gerais de interface, padrões de CRUD e exceções
    .specsfy/STACK.md tecnologias estruturais e suas evidências
    .specsfy/RULES.md diretrizes confirmadas pelo projeto
    .specsfy/DATABASE.md quadro completo de persistência
    .specsfy/PACKAGES.md pacotes npm e Composer com finalidade curta
    .specsfy/USER-PROFILE.md nível de conhecimento e respostas já confirmadas
    .specsfy/templates/custom/ suas versões dos templates, nunca alteradas pelo CLI
    .agents/skills/ skills instaladas no projeto
    docs/ documentação técnica reconstruída do sistema

    O Specsfy não cria plan.md, tasks.md, research.md ou data-model.md. Tudo o que governa a entrega, do plano às tarefas e às pesquisas, fica na spec.md.

    Aprofunde em Informações permanentes do projeto e na Referência do método.

    Estados

    draft → defined → planned → in-progress → review → completed
    Draft → Defined → Planned → Implementing → Reviewing → Complete
    Pasta Status Significa
    draft Draft definição em construção
    defined Defined Definition Gate aprovado
    planned Planned plano, tarefas e RED prontos
    in-progress Implementing tarefas em execução
    review Reviewing Delivery Gate aprovado
    completed Complete aceite final e documentação atualizada

    Mova a spec com specsfy specs transition <id> <pasta>. O comando move o pacote inteiro e atualiza o Status no mesmo ato.

    Atos e gates

    Ato O que comprova Gate Validador
    I · Definir problema, escopo, histórias, requisitos e cenários BDD Definition Gate specsfy gate spec <id>
    II · Projetar e provar plano, tarefas e RED válido Plan Gate specsfy gate tasks <id>
    III · Entregar e validar GREEN, regressão e evidências Delivery Gate specsfy gate trace <id> --full-chain e specsfy gate evidence <id> --delivery

    Cada gate sai com código 0 quando aprova e 10 quando reprova. specsfy verify roda a política inteira e serve de entrada para o CI.

    O que reabre cada ato:

    • mudança de comportamento reabre os atos I, II e III,
    • mudança somente de plano reabre os atos II e III,
    • um gate posterior não permanece aprovado sobre uma entrada invalidada.

    Effort

    Pontuação Perfil Situação típica
    1–2 light ajuste atômico em padrão conhecido
    3–6 standard mudança local ou integração conhecida
    7–8 high mudança transversal, migração ou integração externa
    9–10 maximum arquitetura ou incerteza relevante

    Effort mede a capacidade de raciocínio e execução necessária, não prazo nem prioridade. Atualize com specsfy specs effort <id> <1-10> --reason "<motivo>" a cada informação material nova.

    Identificadores

    Prefixo Representa Exemplo
    SPEC- a especificação SPEC-0001
    BACKLOG- item de backlog BACKLOG-0001
    US- história de usuário US-001
    FR- requisito funcional FR-002
    NFR- requisito não funcional NFR-001
    AC- cenário BDD de aceite AC-003
    T tarefa T004
    R- pesquisa registrada R-001

    O marcador SPECSFY: no teste liga o caso aos IDs que ele comprova, por exemplo // SPECSFY: US-001 FR-001 AC-001.

    A cobertura mínima que o Specsfy exige em cada spec segue estas condições, que os validadores do framework conferem antes de aprovar o Delivery Gate:

    • três cenários AC distintos para a feature e para cada US, FR e NFR, considerando somente os IDs declarados em **Cobre**,
    • três casos TDD executáveis para a feature e para cada US, FR e NFR, cada um com seu próprio marcador.

    Checklist de cada tarefa

    Item Pergunta que responde
    PREP o contexto, os arquivos e as dependências foram conferidos?
    EXECUTE a mudança foi feita?
    VERIFY os testes focais e a regressão passaram?
    VISUAL bordas, espaçamentos e tipografia foram conferidos, ou não há interface?
    EVIDENCE comandos e resultados foram registrados na spec?
    IMPROVE o que ficou melhor ou o que foi aprendido?

    Skills

    Skill Use quando
    specsfy-01-inbox quiser guardar uma ideia sem perguntas
    specsfy-02-backlog quiser refinar uma ideia e decidir o comportamento
    specsfy-03-specify quiser criar a spec de uma entrega
    specsfy-04-validate precisar aprovar a definição
    specsfy-05-tasks precisar planejar as tarefas
    specsfy-06-tdd-bdd precisar preparar ou verificar testes
    specsfy-07-implement for implementar a entrega
    specsfy-update-spec algo mudar depois da definição
    specsfy-progress quiser consultar o estado sem alterar nada
    specsfy-interviewer quiser conversar sobre a spec e só depois avançar
    specsfy-mvp-milestone-interviewer for definir o MVP de um produto
    specsfy-roadmap-milestone-interviewer for planejar a evolução após o MVP
    specsfy-milestone-governor precisar manter os milestones alinhados
    specsfy-data-discovery o sistema precisar guardar informações novas

    Skills de apoio, chamadas pelo próprio fluxo:

    Skill Papel
    specsfy-setup prepara e reconcilia o contexto antes de qualquer skill
    specsfy-documentator reconstrói docs/ e .specsfy/PACKAGES.md após cada implementação
    specsfy-aux-stack atualiza .specsfy/STACK.md após mudança de tecnologia
    specsfy-aux-rules registra diretrizes confirmadas em .specsfy/RULES.md
    specsfy-aux-database atualiza .specsfy/DATABASE.md quando o banco muda

    Aprofunde no índice de Skills base.

    Comandos do CLI

    Comando Faz
    specsfy abre a TUI, com as abas Overview, Specs, Backlog, Gates, Tests, Skills e About
    specsfy --skill imprime a documentação embutida do framework
    specsfy install --project . instala skills, templates e blocos gerenciados
    specsfy doctor --project . confere runtime, terminal, configuração, Git e token do GitHub
    specsfy update atualiza skills, templates e blocos gerenciados do projeto
    specsfy upgrade substitui o próprio binário pela última release
    specsfy skills list lista o catálogo do framework e dos especialistas
    specsfy skills detect recomenda especialistas pela stack
    specsfy skills install <nome> instala um especialista
    specsfy status resume specs por estado, gates, tarefas, backlog e inbox
    specsfy progress --spec <id> projeta o progresso de uma spec
    specsfy specs list lista as specs com estado, gates e tarefas
    specsfy specs new --title "<título>" cria uma spec em specs/draft/ pelo template
    specsfy specs transition <id> <pasta> move a spec de estado
    specsfy specs effort <id> <1-10> --reason "<motivo>" registra o Effort
    specsfy specs change <id> projeta o impacto de uma mudança tardia, sem editar
    specsfy tasks next <id> mostra a próxima tarefa pronta
    specsfy inbox capture grava uma captura na Inbox
    specsfy inbox process retira da fila capturas cobertas por specs aprovadas
    specsfy gate <gate> <id> roda um gate: spec, tasks, interface, trace, acceptance, evidence, findings ou database
    specsfy verify roda a política inteira, para o CI
    specsfy context setup cria os arquivos de contexto que ainda não existem
    specsfy docs build reconstrói docs/ e .specsfy/PACKAGES.md
    specsfy milestones sync atualiza specs.md e os milestones
    specsfy test roda a suíte com o runner da stack e a proteção do banco
    specsfy mcp inicia o servidor MCP para o agente
    specsfy config list mostra as preferências

    Quase todos aceitam --project <caminho> e --json. O specsfy <comando> --help mostra as opções de cada comando do CLI. A lista completa, com os códigos de saída, está na Referência dos comandos.

    Mensagens de transição

    O agente usa formatos fixos para que você acompanhe o fluxo:

    Pendência detectada: <descrição> — ação: resolvendo nesta etapa
    Transição automática: $<origem> → $<destino> — motivo: <motivo> — resultado esperado: <resultado>
    Retomada automática: $<destino> → $<origem> — pendência resolvida: <resultado>

    Uma transição não autoriza sozinha ações destrutivas, publicação, deploy ou instalação de especialista. Cada uma dessas ações depende da sua autorização.

    Proteções que não podem ser desligadas

    • nenhum teste roda no banco de desenvolvimento,
    • comandos que apagam ou recriam banco são recusados em qualquer situação, como migrate:fresh, migrate:refresh, db:wipe, DROP TABLE e TRUNCATE,
    • testes Laravel usam DatabaseTransactions e exigem .env.testing com banco separado,
    • conteúdo fora dos blocos specsfy:*:start e specsfy:*:end pertence a você e não é alterado pelo CLI.

    Glossário

    Termo Significado
    BDD descrição do comportamento em cenários Given, When, Then, legíveis por qualquer pessoa
    TDD prática de escrever o teste primeiro e vê-lo falhar
    RED falha do teste causada pela ausência do comportamento ainda não implementado
    GREEN o mesmo teste passando depois da implementação
    REFACTOR melhoria do código mantendo os testes verdes
    Gate ponto de controle que só passa com prova registrada
    Effort escala de 1 a 10 da capacidade necessária para a entrega
    Rastreabilidade ligação entre requisito, cenário, teste, tarefa e evidência
    Especialista skill técnica opcional para uma tecnologia ou disciplina
    MVP menor conjunto de entregas que demonstra o valor do produto
    Milestone marco demonstrável que agrupa specs e itens de backlog

    Referências externas

    O método combina práticas consolidadas. Estas fontes ajudam a entender os conceitos por trás de cada etapa:

    Assunto Fonte Endereço
    BDD e Gherkin documentação oficial do Cucumber https://cucumber.io/docs/gherkin/
    Especificação por exemplos Gojko Adzic, Specification by Example https://gojko.net/books/specification-by-example/
    TDD Kent Beck, Test-Driven Development: By Example https://www.oreilly.com/library/view/test-driven-development/0321146530/
    Versionamento Semantic Versioning 2.0.0 https://semver.org/lang/pt-BR/
    Skills de agentes formato aberto SKILL.md https://agentskills.io/
    Pest documentação oficial https://pestphp.com/docs/
    Vitest documentação oficial https://vitest.dev/guide/
    Spec Kit repositório do GitHub Spec Kit https://github.com/github/spec-kit

    O Specsfy usa essas ideias como base, mas a definição que vale no seu projeto é a registrada no contrato instalado em .specsfy/Spec.md e na spec.md de cada entrega.

    Justificativa de tamanho

    A referência rápida reúne em uma página o que os demais capítulos explicam em detalhe. Dividi-la anularia sua função de consulta única durante o trabalho.

    Planos Promovaweb

    Tire seus projetos do papel

    O Plano Martech cobre automação e atendimento. O Plano IA Makers acrescenta desenvolvimento com IA, enquanto o Plano Founders trata de gestão de negócios. Todos são anuais.

    Plano Martech

    Para conectar automação, marketing e atendimento com infraestrutura própria.

    R$ 897

    R$ 597/ano

    • Grade de automação, atendimento, marketing e análise de indicadores
    • Instalador Exclusivo Promovaweb
    • n8n, Evolution API, Chatwoot e Mautic
    • Trilha DevOps incluída
    • Encontros ao vivo (terça e quinta)
    • Comunidade e acompanhamento
    Conhecer o plano

    Plano Founders

    Plano anual para fazer um projeto de tecnologia avançar, com 90 dias de mentoria intensiva. R$ 1.997 à vista ou até 10x de R$ 219 no cartão.

    R$ 1.997/ano

    • 12 meses de acesso ao Founders
    • 90 dias de mentoria intensiva, um encontro por dia útil
    • Dia de conteúdo (terça e quinta) e War Room (segunda, quarta e sexta)
    • Encontro semanal em grupo após a fase intensiva
    • Formação Vibe Coding incluída no plano anual
    • Consultoria individual de até duas horas (bônus)
    Conhecer o plano