Skip to content
Back to search

specsfy

O Specsfy ajuda você a transformar uma ideia em software testado sem espalhar requisitos, planos e tarefas por vários arquivos.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/promovaweb/specsfy with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/promovaweb/specsfy'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/promovaweb--specsfy/badge.svg)](/listings/promovaweb--specsfy)

HTML

<a href="/listings/promovaweb--specsfy"><img src="/api/listings/promovaweb--specsfy/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 282 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <a href="https://github.com/promovaweb/specsfy">
  3. <picture>
  4. <source srcset="brand/logo/icon.svg" type="image/svg+xml">
  5. <img src="brand/logo/icon.png" alt="Logo do Specsfy" width="128">
  6. </picture>
  7. </a>
  8. </p>
  9. <h1 align="center">Specsfy</h1>
  10. <p align="center">
  11. Transforme uma ideia em software testado a partir de uma especificação única, conduzida por agentes de IA.
  12. </p>
  13. <p align="center">Um projeto da <a href="https://promovaweb.com">Promovaweb</a></p>
  14. <p align="center">
  15. <a href="https://github.com/promovaweb/specsfy/releases/latest"><img alt="GitHub Release" src="https://img.shields.io/github/v/release/promovaweb/specsfy"></a>
  16. <a href="https://www.npmjs.com/package/@promovaweb/specsfy"><img alt="npm" src="https://img.shields.io/npm/v/@promovaweb/specsfy"></a>
  17. <a href="https://github.com/promovaweb/specsfy/actions/workflows/specsfy.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/promovaweb/specsfy/specsfy.yml"></a>
  18. <a href="LICENSE"><img alt="Licença" src="https://img.shields.io/github/license/promovaweb/specsfy"></a>
  19. </p>
  20. <p align="center">
  21. <a href="https://promovaweb.com/discord"><img alt="Discord: obter ajuda e conversar com a Comunidade" src="https://img.shields.io/badge/Discord-Obter%20ajuda%20e%20conversar%20com%20a%20Comunidade-5865F2?style=for-the-badge&logo=discord&logoColor=white"></a>
  22. </p>
  23. <p align="center">
  24. <a href="https://promovaweb.com/docs/specsfy/">Documentação</a> ·
  25. <a href="https://promovaweb.com/discord">Discord</a> ·
  26. <a href="https://promovaweb.com/planos?utm_source=github&utm_medium=readme&utm_campaign=specsfy">Planos da Promovaweb</a> ·
  27. <a href="cli/CHANGELOG.md">Changelog</a>
  28. </p>
  29. ## O que é
  30. Specsfy é uma metodologia executável para levar uma ideia até software testado.
  31. A pessoa conversa com o agente. As skills organizam requisitos, testes e tarefas
  32. em uma especificação única. Cada etapa entrega um resultado conferível antes da
  33. próxima. O mesmo identificador acompanha a história do pedido até a
  34. verificação.
  35. Esta apresentação mostra como instalar e usar o produto. O monorepo
  36. [`promovaweb/specsfy`](https://github.com/promovaweb/specsfy) reúne a
  37. metodologia, o CLI, os especialistas e a documentação em módulos com
  38. responsabilidades próprias.
  39. | Modo | Como se usa | Para quem |
  40. | --- | --- | --- |
  41. | Skills | `$specsfy-*` dentro do agente | conduzir a especificação e a entrega |
  42. | CLI | `specsfy <comando>` | terminal, scripts e CI |
  43. | TUI | `specsfy` | acompanhar specs, gates e tarefas |
  44. | MCP | `specsfy mcp` | agentes que acessam o projeto por ferramentas |
  45. ## Instalação
  46. Requisitos: Node.js 22.20 ou superior e npm.
  47. ```bash
  48. npm install --global @promovaweb/specsfy
  49. specsfy --version
  50. ```
  51. O pacote npm baixa e confere o executável da plataforma na primeira execução.
  52. Para instalar sem npm, baixe de `get.specsfy.dev` o lançador em Node.js, que
  53. faz o mesmo download na primeira execução:
  54. ```bash
  55. mkdir -p "$HOME/.local/bin"
  56. curl -fL get.specsfy.dev -o "$HOME/.local/bin/specsfy"
  57. chmod +x "$HOME/.local/bin/specsfy"
  58. ```
  59. Cada [GitHub Release](https://github.com/promovaweb/specsfy/releases) publica os
  60. cinco executáveis e o `SHA256SUMS`. O executável compilado não depende de
  61. Node.js nem de Bun. Baixe o da sua plataforma, confira o hash e coloque-o em um
  62. diretório do `PATH`.
  63. Para atualizar o CLI e as skills do projeto:
  64. ```bash
  65. specsfy upgrade
  66. specsfy update --project .
  67. ```
  68. `upgrade` troca o próprio binário. `update` atualiza skills, templates e blocos
  69. gerenciados no projeto consumidor.
  70. ## Primeiros passos
  71. ```bash
  72. cd caminho/do/projeto
  73. specsfy doctor --project .
  74. specsfy install --project .
  75. specsfy skills list
  76. specsfy progress --project .
  77. ```
  78. `doctor` confere o runtime, o terminal e as configurações. Com `--project`,
  79. ele também confere Git, o CLI de skills e o token do GitHub do projeto. `install` publica as skills base em `.agents/skills/`, grava
  80. `.specsfy/Spec.md` e reconcilia os blocos gerenciados de `AGENTS.md` e
  81. `CLAUDE.md`. Uma instalação nova pode mostrar zero specs. Isso confirma que o
  82. CLI lê o projeto.
  83. A primeira spec nasce na conversa com o agente:
  84. ```text
  85. Use $specsfy-setup para preparar este projeto.
  86. Use $specsfy-01-inbox para capturar: criar uma página /boas-vindas que cumprimente a pessoa pelo nome.
  87. ```
  88. O agente grava a captura em `specs/inbox/`. A skill `$specsfy-setup` lê o
  89. projeto antes de perguntar e registra o perfil de interação em
  90. `.specsfy/USER-PROFILE.md`.
  91. Em um projeto iniciado com o [GitHub Spec Kit](https://github.com/github/spec-kit),
  92. `$specsfy-setup` lê `.specify/memory/constitution.md` e os arquivos de
  93. `specs/`. A skill publica uma ponte de leitura em `.specsfy/SPECKIT.md` e
  94. preserva os artefatos originais nos mesmos caminhos.
  95. ## Uso
  96. Abra a TUI no projeto:
  97. ```bash
  98. specsfy
  99. specsfy tui --project .
  100. ```
  101. Consulte o estado e o progresso:
  102. ```bash
  103. specsfy status
  104. specsfy progress --project .
  105. specsfy progress --project . --json
  106. specsfy progress --project . --watch
  107. ```
  108. Trabalhe com specs, tarefas e gates:
  109. ```bash
  110. specsfy specs list
  111. specsfy specs show 0001 --content
  112. specsfy tasks next 0001
  113. specsfy gate spec 0001
  114. specsfy gate tasks 0001
  115. specsfy verify --boundary local
  116. ```
  117. `gate` aprova com código `0` e reprova com `10`. `verify` executa a política
  118. inteira, inclusive a verificação usada no CI. O progresso apenas lê: ele projeta
  119. checkboxes e gates sem alterar a fonte normativa da spec.
  120. Instale especialistas por stack quando precisar:
  121. ```bash
  122. specsfy install --project . --detected
  123. specsfy skills install specsfy-specialist-laravel --project .
  124. ```
  125. Uma recomendação do agente não instala o especialista. A pessoa confirma a
  126. instalação.
  127. ## Uso com agentes
  128. O `install` publica as skills em `.agents/skills/`, no formato universal.
  129. [Claude Code](https://github.com/anthropics/claude-code),
  130. [Codex](https://github.com/openai/codex) e
  131. [OpenCode](https://github.com/anomalyco/opencode) leem a mesma metodologia a
  132. partir do projeto. A key `skills.agents` aceita outros alvos separados por
  133. vírgula:
  134. ```bash
  135. specsfy config set skills.agents universal,claude-code,codex,opencode
  136. ```
  137. O contrato fica em `.specsfy/Spec.md`. As skills ficam em `.agents/skills/`.
  138. Para expor o projeto por MCP, adicione o servidor ao cliente:
  139. ```json
  140. {
  141. "mcpServers": {
  142. "specsfy": { "command": "specsfy", "args": ["mcp"] }
  143. }
  144. }
  145. ```
  146. No Claude Code, o caminho curto é `claude mcp add specsfy -- specsfy mcp`. As
  147. ferramentas de leitura consultam specs, gates e progresso. As ferramentas de
  148. escrita alteram arquivos do projeto e não pedem confirmação. Comece por
  149. `project_status` e confirme o efeito antes de alterar. `specsfy mcp --list`
  150. mostra todas as ferramentas, resources e prompts.
  151. ## Saída para scripts
  152. Comandos de leitura aceitam `--json`:
  153. ```bash
  154. specsfy progress --project . --json
  155. specsfy gate spec 0001 --json
  156. ```
  157. | Código | Significado |
  158. | --- | --- |
  159. | `0` | sucesso |
  160. | `1` | falha geral, sem classificação específica |
  161. | `3` | configuração inválida ou diagnóstico com requisito reprovado |
  162. | `2` | uso inválido de argumentos, opções ou subcomando |
  163. | `6` | recurso não encontrado, como o projeto ou a spec |
  164. | `10` | gate ou validação reprovada |
  165. `specsfy --help` lista todos os códigos. A
  166. [referência dos comandos](docs/user/cli-reference.md) detalha as opções.
  167. ## Documentação
  168. A documentação publicada fica em
  169. [promovaweb.com/docs/specsfy](https://promovaweb.com/docs/specsfy/). No
  170. repositório, [`docs/README.md`](docs/README.md) separa o percurso de uso do
  171. percurso de desenvolvimento.
  172. - [Guia do usuário](docs/user/README.md): instalação, primeira entrega e rotina
  173. com o CLI.
  174. - [Referência dos comandos](docs/user/cli-reference.md): argumentos, opções e
  175. códigos de saída.
  176. - [Casos de uso](docs/user/use-cases.md): receitas por situação, do bug ao MVP.
  177. - [Exemplos completos](docs/user/examples.md): os arquivos de uma entrega real e
  178. mensagens prontas para cada etapa.
  179. - [Referência rápida](docs/user/reference.md): arquivos, estados, gates, IDs,
  180. skills, comandos e glossário em uma página.
  181. - [Deploy](docs/user/deploy.md): release, servidores e produção em Docker Swarm
  182. com o especialista `specsfy-specialist-deploy`.
  183. - [Edição em PDF e EPUB](ebook/): o mesmo guia do usuário em formato portátil.
  184. - [Tutorial completo](specsfy/README.md): uma primeira entrega passo a passo, da
  185. captura à verificação.
  186. A aplicação interna em [`example/`](example/) valida o framework em um projeto
  187. real. O manual de marca em `brand/Specsfy-Manual-de-Marca.pdf` é gerado a partir
  188. de `brand/` com `make brand-guide`.
  189. ## Feito com
  190. | Projeto | Para quê |
  191. | --- | --- |
  192. | [Bun](https://github.com/oven-sh/bun) | compilação do binário |
  193. | [Node.js](https://github.com/nodejs/node) | lançador do pacote npm e instalação |
  194. | [Termfy](https://github.com/promovaweb/termfy) | framework de CLI, TUI e MCP da Promovaweb |
  195. | [OpenTUI](https://github.com/anomalyco/opentui) | componentes da TUI |
  196. | [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk) | servidor MCP |
  197. | [skills](https://github.com/vercel-labs/skills) | instalação de skills no projeto |
  198. ## Comunidade e suporte
  199. - **Discord:** [obter ajuda e conversar com a Comunidade](https://promovaweb.com/discord).
  200. - **Bugs e pedidos:** abra uma [issue](https://github.com/promovaweb/specsfy/issues)
  201. com a versão, o sistema operacional e o passo a passo para reproduzir.
  202. - **Novidades:** acompanhe o [CHANGELOG](cli/CHANGELOG.md) e as
  203. [releases](https://github.com/promovaweb/specsfy/releases).
  204. ## Contribuir
  205. Leia o [CONTRIBUTING.md](CONTRIBUTING.md) antes de alterar o código. Ele
  206. descreve o ambiente, os comandos de validação e o fluxo de release. A release
  207. do CLI segue a skill `specsfy-release-cli`, em
  208. `cli/.agents/skills/specsfy-release-cli/`.
  209. ## Promovaweb
  210. O Specsfy é mantido pela [Promovaweb](https://promovaweb.com), comunidade de
  211. co-working digital onde profissionais aprendem a construir, automatizar e gerir
  212. negócios de tecnologia e IA com aulas ao vivo, Co-works e revisão de projetos
  213. reais.
  214. Quer usar o Specsfy em projetos de verdade, com acompanhamento? Conheça os
  215. [planos da Promovaweb](https://promovaweb.com/planos?utm_source=github&utm_medium=readme&utm_campaign=specsfy).
  216. ## Licença
  217. Distribuído sob a [GNU AGPL 3.0](LICENSE). A licença não concede o uso do
  218. nome e do logo do Specsfy nem da marca Promovaweb (AGPL 3.0, seção 7, item e).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.