Specsfy

Especifique. Prove. Entregue.

Esta apresentação reúne os caminhos públicos do Specsfy, uma metodologia prática para desenvolver software a partir de uma especificação única, executável e rastreável. Todo o projeto é mantido no monorepo promovaweb/specsfy.

Estrutura

Caminho Responsabilidade
skills/ metodologia executável e skills base
specialists/ skills técnicas opcionais
cli/ CLI, TUI, instalação e atualização
docs/ documentação oficial e contexto transversal
brand/ identidade visual e verbal
example/ aplicação interna de validação
specsfy/ tutorial público detalhado
tests/ contratos integrados do monorepo

Todos os caminhos compartilham a mesma raiz, histórico, branch, issues, tags e releases Git.

Instalação

Requer Node.js 22.20 ou superior, npm e o comando skills ou npx. Enquanto o repositório for privado, autentique uma vez com gh auth login. o CLI reutiliza essa sessão. Em automações, defina GH_TOKEN ou GITHUB_TOKEN com acesso de leitura ao repositório.

O executável versionado está disponível pelo download oficial get.specsfy.dev. Para instalar o pacote publicado e receber atualizações gerenciadas pelo npm:

npm install --global @promovaweb/specsfy
specsfy --version
cd caminho/do/projeto
specsfy doctor --project .
specsfy setup --project .

Depois da instalação, specsfy update --project . atualiza as skills do projeto e specsfy upgrade atualiza o próprio CLI.

Em um projeto iniciado com GitHub Spec Kit, $specsfy-setup lê .specify/memory/constitution.md e os arquivos existentes em specs/. A skill publica uma ponte de leitura em .specsfy/SPECKIT.md e preserva os artefatos originais nos mesmos caminhos.

O CLI instala a metodologia de skills/ e, sob demanda, especialistas de specialists/. Veja o guia de instalação, o primeiro uso e o guia do CLI. O portal completo está em docs/README.md.

Para desenvolver a partir do checkout:

git clone https://github.com/promovaweb/specsfy.git
cd specsfy
./scripts/install-cli.sh

Para reconstruir o manual de marca após alterar suas fontes:

make brand-guide

Esta raiz não é um projeto consumidor e não recebe specs/ ou skills instaladas.

Inspirações e fontes

O Specsfy desenvolve uma metodologia própria, mas reconhece três referências que ajudaram a organizar seu vocabulário e seu fluxo:

  • GitHub Spec Kit, pela aplicação de specification-driven development em etapas executáveis próximas ao código.
  • OpenSpec, pela proposta de manter especificações e mudanças como um acordo leve entre a pessoa responsável e o agente.
  • Categorias, de Aristóteles, pela atenção dada à classificação explícita de objetos, atributos, relações e estados antes de formular afirmações sobre eles.

Essas referências são fontes de inspiração, não dependências nem declarações de equivalência. O comportamento do Specsfy continua definido pelas skills, templates, validadores e testes deste repositório.

Validação

python3 -B -m unittest discover -s tests -p 'test_*.py'
uv run --quiet --with behave behave tests/features --no-capture

Os módulos possuem verificações focais descritas em seus AGENTS.md. Consulte AGENTS.md antes de contribuir.

As skills locais specsfy-monorepo-documentator e specsfy-release-cli mantêm, respectivamente, a documentação oficial e as releases estáveis do CLI.