ForgeCraft

⚠️ Obsoleto (setembro de 2026), e essa é a boa notícia

O trabalho do ForgeCraft era configurar um projeto para Generative Specification e codificar suas propriedades de qualidade. Esse trabalho agora pertence ao próprio modelo. Aponte um assistente de codificação capaz para o white paper e guia de campo do GS e peça para configurar o projeto como GS: ele criará a árvore de navegação sentinela e conectará os portões para você, ajustados ao seu código, sem ferramenta separada. Essa é a própria tese da disciplina se concretizando, a fricção de adoção incorporada ao executor.

• Configuração agora é um prompt: dê ao seu assistente o white paper / guia de campo (DOI https://doi.org/10.5281/zenodo.21726017, e pragmaworks.dev) e peça para configurar o projeto como GS.
• Os portões são hooks de CI padrão (tsc, eslint, jscpd, cobertura, dependency-cruiser, commit-msg) que o modelo conecta a partir da especificação. O conjunto de portões conquistado com dificuldade que captura o catálogo de patologias está preservado no src/analyzers/ deste repositório para referência, e um modelo de portão curado ficará em pragmaworks.dev.
• O que ainda agrega valor são os servidores MCP GS componíveis que fazem o que um modelo não pode fazer facilmente por conta própria: Chronicle (memória entre sessões) e Chronos (grafo do histórico do git). ForgeCraft não é um deles.

Este pacote não recebe mais atualizações. A última versão permanece instalável para referência.

ForgeCraft

O contrato de qualidade dentro do qual seu assistente de codificação de IA trabalha.

Você contratou um engenheiro de IA. Ele é brilhante. Também instalou as mesmas 14 extensões do VS Code duas vezes hoje, subiu 6 contêineres Docker que nunca vai limpar, e seu disco foi de 12 GB livres para 0 KB em uma sessão.

Um disco cheio não falha graciosamente. Ele mata o VS Code, o terminal, o Docker e o banco de dados simultaneamente.

ForgeCraft é o contrato de qualidade dentro do qual seu assistente de codificação de IA trabalha — para que ele construa rápido e não destrua a casa.

npx forgecraft-mcp setup .

Suporta: Claude (CLAUDE.md) · Cursor (.cursor/rules/) · GitHub Copilot (.github/copilot-instructions.md) · Windsurf (.windsurfrules) · Cline (.clinerules) · Aider (CONVENTIONS.md)

Uma estrutura de qualidade para desenvolvimento de software assistido por IA

Cada sessão, cada projeto, cada assistente de IA — medido contra o mesmo modelo de Generative Specification com 7 propriedades. Não é vibração. Não é uma pontuação de linter. Uma pontuação de 14 que mostra exatamente onde está a lacuna e por quê.

$ npx forgecraft-mcp verify .

| Property        | Score | Evidence                                        |
|-----------------|-------|-------------------------------------------------|
| Self-Describing | ✅ 2/2 | CLAUDE.md — 352 non-empty lines                |
| Bounded         | ✅ 2/2 | No direct DB calls in route files              |
| Verifiable      | ✅ 2/2 | 64 test files — 87% coverage                   |
| Defended        | ✅ 2/2 | Pre-commit hook + lint config present           |
| Auditable       | ✅ 2/2 | 11 ADRs in docs/adrs/ + Status.md              |
| Composable      | ✅ 2/2 | Service layer + repository layer detected       |
| Executable      | ✅ 2/2 | Tests passed + CI pipeline configured           |

Total: 14/14 ✅ PASS · Threshold 11/14

Higiene do ambiente de desenvolvimento — imposta por convenção

ForgeCraft injeta regras aplicáveis nas instruções de IA de cada projeto, tornando a poluição do ambiente uma violação de convenção, não um incidente.

Extensões do VS Code Antes de instalar: code --list-extensions | grep -i <name>. Instale apenas se nenhuma versão na faixa principal necessária já estiver presente. A mesma extensão não é baixada duas vezes no mesmo dia.

Contêineres Docker Verifique antes de criar: docker ps -a --filter name=<service>. Se existir, inicie-o — não o crie. Prefira docker compose up (reutilização) em vez de docker run puro (sempre cria novo). Logs limitados a 500 MB. docker system prune -f é documentado como uma etapa de manutenção periódica, não uma emergência.

Exceção: Múltiplos contêineres do mesmo serviço são permitidos quando diferem significativamente no conjunto de plugins ou na versão principal — por exemplo, um contêiner postgres-pgvector ao lado de um contêiner postgres padrão. Nomeie os contêineres para refletir a variante (por exemplo, db-pgvector, db-timescale); caso contrário, a regra de deduplicação se aplica.

Ambientes virtuais Python Um .venv por raiz de projeto. Reutilize se a versão Python major.minor corresponder. Nunca crie um venv em um subdiretório, a menos que seja um pacote instalável independente. Dependências não utilizadas sinalizadas por pip list --not-required.

Dados sintéticos e de séries temporais Antes de escrever mais de 100 MB de dados gerados, a IA pergunta: reter bruto, condensar estatisticamente ou excluir após a execução? Conjuntos de dados sintéticos com mais de 7 dias sem referência de código: peça para excluir.

Geral Se o workspace crescer além de 2 GB fora dos artefatos de build conhecidos (node_modules/, .venv/, dist/), exiba um aviso e pare. Nunca cresça o workspace silenciosamente.

Configuração do projeto em uma frase

Read the spec in docs/specs/, set up this project with ForgeCraft,
scaffold it with the right tags, recommend the tech stack, start building.

Esse é todo o prompt de integração. ForgeCraft lê a especificação, a IA atribui as tags, e o ForgeCraft escreve o arquivo de instruções, emite Status.md, docs/adrs/, docs/PRD.md, docs/TechSpec.md, hooks e skills. A IA tem contexto completo. Você começa a construir.

ForgeCraft escaneia seu projeto, detecta automaticamente sua stack e gera arquivos de instruções personalizados a partir de 116 blocos curados — SOLID, arquitetura hexagonal, pirâmides de teste, CI/CD e 24 conjuntos de regras específicos de domínio — em segundos.

Portões de qualidade

Portões de qualidade são verificações estruturadas de aprovação/reprovação que seu assistente de IA executa em momentos definidos — antes de um commit, antes de um release, após um deploy. Não são regras de linter. Cada portão tem uma condição, um requisito de evidência e um sinalizador para saber se a revisão humana é obrigatória.

Os portões são organizados por fase de release para que você não execute testes de caos de pré-release no primeiro dia de um projeto greenfield:

Portões marcados com requires_human_review: true não podem ser aprovados automaticamente — algumas verificações exigem um humano.

A biblioteca completa de portões, o guia de contribuição e o esquema estão no repositório de portões de qualidade →

ADRs, sequenciados automaticamente

Toda decisão arquitetural não óbvia é registrada. ForgeCraft sequencia automaticamente docs/adrs/NNNN-slug.md no formato MADR — contexto, decisão, alternativas, consequências. Seu assistente de IA raciocina sobre escolhas passadas. Sua equipe para de re-litigar.

npx forgecraft-mcp generate_adr . --title "Use event sourcing for order history" \
  --status Accepted \
  --context "Order mutations need full audit trail for compliance" \
  --decision "Append-only event log, project current state on read"
# → docs/adrs/0004-use-event-sourcing-for-order-history.md

Configuração do assistente de IA vs ForgeCraft

claude init, as regras de workspace do Cursor ou o arquivo de instruções do Copilot fazem você começar. ForgeCraft leva você aos padrões de produção — em todos os assistentes de IA, todas as sessões, todos os engenheiros da equipe.

Playbook de fluxo de trabalho

Após a configuração, sua IA tem o contexto. Esses prompts direcionam o trabalho. Copie, cole, execute.

→ Playbook completo de fluxo de trabalho · Versão online

Como funciona

# First-time setup — auto-detects your stack
npx forgecraft-mcp setup .

flowchart TD
    A["<b>setup .</b><br/>npx forgecraft-mcp setup ."] --> B["Phase 1 — Analyze<br/>Reads spec · infers tags"]
    B --> C{AI assistant\nin the loop?}
    C -->|"Yes (MCP)"| D["Phase 2 — Calibrate<br/>LLM corrects tags from spec<br/>Writes forgecraft.yaml · CLAUDE.md<br/>PRD.md · hooks · ADR-000"]
    C -->|"No (CLI only)"| E["⚠️ CLI-only mode<br/>Directory heuristics only<br/>→ configure an AI assistant"]
    D --> F["<b>check_cascade</b><br/>5-step readiness gate<br/>1 · Functional spec<br/>2 · Architecture + C4<br/>3 · Constitution<br/>4 · ADRs<br/>5 · Use cases"]
    F --> G{All 5 passing?}
    G -->|"Stubs / missing"| H["Fill artifacts<br/>docs/PRD.md · docs/adrs/<br/>docs/use-cases.md"]
    H --> F
    G -->|"✅ All pass"| I["<b>generate_session_prompt</b><br/>Bound context for next task"]
    I --> J["Implement with TDD<br/>RED → GREEN → REFACTOR<br/>+ Documentation Cascade"]
    J --> K["<b>audit_project</b><br/>Score 0 – 100"]
    K --> L{Score ≥ 90?}
    L -->|"Violations found"| M["WORKFLOWS.md remediation<br/>file_length · layer_violation<br/>hardcoded_url · missing_prd"]
    M --> J
    L -->|"✅ Score ≥ 90"| N["<b>close_cycle</b><br/>Re-check cascade · assess gates<br/>promote to registry · bump version"]
    N --> O{Roadmap\ncomplete?}
    O -->|"More features"| I
    O -->|"All done"| P["<b>start_hardening</b><br/>Mutation tests · OWASP · load test"]
    P --> Q["🚢 Ship"]

    style A fill:#1a2e1a,color:#90ee90,stroke:#3a6e3a
    style Q fill:#1a2a3e,color:#87ceeb,stroke:#3a5a8e
    style E fill:#2e1a1a,color:#ffaa88,stroke:#6e3a3a
    style M fill:#2e2a00,color:#ffd700,stroke:#6e6000

ForgeCraft é uma ferramenta CLI de configuração. Execute uma vez para configurar seu projeto e depois remova-a — ela não tem pegada em runtime.

Opcionalmente, adicione o sentinela MCP para permitir que seu assistente de IA diagnostique e recomende comandos:

claude mcp add forgecraft -- npx -y forgecraft-mcp

O sentinela é uma única ferramenta (~200 tokens). Ele lê três artefatos — forgecraft.yaml, CLAUDE.md, .claude/hooks — deriva o próximo comando CLI correto e o retorna. Nada mais. Este é o princípio central da metodologia expresso como design de ferramenta: um leitor sem estado, um conjunto finito de artefatos, uma ação derivada. Remova-o após a configuração inicial para recuperar o orçamento de tokens.

O que você obtém

Após npx forgecraft-mcp setup, seu projeto tem:

your-project/
├── forgecraft.yaml        ← Your config (tags, tier, customizations)
├── CLAUDE.md              ← Engineering standards (Claude)
├── .cursor/rules/         ← Engineering standards (Cursor)
├── .github/copilot-instructions.md  ← Engineering standards (Copilot)
├── Status.md              ← Session continuity tracker
├── .claude/hooks/         ← Pre-commit quality gates
├── docs/
│   ├── PRD.md             ← Requirements skeleton
│   └── TechSpec.md        ← Architecture + NFR sections
└── src/shared/            ← Config, errors, logger starters

Os arquivos de instruções

Este é o valor central. Montados a partir de blocos curados que cobrem:

• Princípios SOLID — regras concretas, não platitudes
• Arquitetura hexagonal — portas, adaptadores, DTOs, limites de camada
• Pirâmide de testes — metas de unitário/integração/E2E, taxonomia de test doubles
• Código limpo — CQS, cláusulas de guarda, imutabilidade, funções puras
• CI/CD e deploy — estágios de pipeline, ambientes, previews de deploy
• Padrões de domínio — DDD, CQRS, event sourcing (quando seu projeto precisar)
• Operações 12-Factor — configuração, ausência de estado, descartabilidade, logging

Cada bloco é originado da literatura de engenharia estabelecida (Martin, Evans, Wiggins) e adaptado para desenvolvimento assistido por IA.

24 tags — detectadas por IA, ajustáveis pelo usuário

As tags dizem ao ForgeCraft o que seu projeto é. Na primeira configuração, a IA analisa sua especificação e código-fonte e as atribui. Você pode revisar e substituir em forgecraft.yaml. Os blocos se mesclam sem conflitos — adicione ou remova tags conforme o projeto evolui.

A lista completa de tags e o guia de contribuição estão no repositório de portões de qualidade →

Níveis de profundidade de conteúdo

Nem todo projeto precisa de DDD no primeiro dia.

Definido em forgecraft.yaml:

projectName: my-api
tags: [UNIVERSAL, API]
tier: recommended

Comandos CLI

npx forgecraft-mcp <command> [dir] [flags]

Flags comuns

--tags UNIVERSAL API     Project classification tags (or read from forgecraft.yaml)
--tier core|recommended  Content depth (default: recommended)
--targets claude cursor  AI assistant targets (default: claude)
--dry-run                Preview without writing files
--compact                Strip explanatory bullet tails and deduplicate lines (~20-40% smaller output)
--apply                  Apply changes (for refresh)
--language typescript    typescript | python (default: typescript)
--scope focused          comprehensive | focused (for review)

MCP Sentinel

Opcionalmente, adicione o sentinel MCP do ForgeCraft para permitir que seu assistente de IA diagnostique seu projeto e sugira o comando CLI correto:

O sentinel é uma ferramenta mínima única (~200 tokens por requisição, vs ~1.500 para uma suíte completa de ferramentas). Ele verifica se forgecraft.yaml, seu arquivo de instruções de IA e seus hooks existem, e então retorna o comando CLI direcionado para o estado atual do projeto.

O design é intencional. A superfície completa de comandos do ForgeCraft — 21 ações — vive na CLI, não no servidor MCP. O servidor MCP expõe exatamente uma ferramenta que lê três artefatos e retorna uma recomendação. Este é o princípio da Especificação Generativa na própria arquitetura da ferramenta: um leitor sem estado, um conjunto limitado de artefatos, uma ação derivada. A ferramenta pratica o que escreve em seus arquivos de instrução.

Um efeito colateral: toda ferramenta MCP declarada é lida pelo modelo a cada turno, seja invocada ou não. Uma ferramenta custa 200 tokens. Vinte e uma ferramentas custam 1.500. O sentinel mantém o orçamento MCP recomendado pela metodologia (≤3 servidores ativos) por design.

Fluxo de trabalho recomendado:

1. Adicione o sentinel ao seu assistente de IA (veja exemplos de configuração abaixo)
2. Deixe seu assistente de IA executar npx forgecraft-mcp setup .
3. Remova o sentinel da sua configuração MCP ativa
4. Re-adicione quando precisar atualizar ou auditar

{
  "mcpServers": {
    "forgecraft": {
      "command": "npx",
      "args": ["-y", "forgecraft-mcp"]
    }
  }
}

{
  "servers": {
    "forgecraft": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "forgecraft-mcp"]
    }
  }
}

{
  "mcpServers": {
    "forgecraft": {
      "command": "npx",
      "args": ["-y", "forgecraft-mcp"]
    }
  }
}

Sem cliente MCP? Sem problemas — você não precisa dele. Execute npx forgecraft-mcp setup . diretamente no seu terminal. O sentinel MCP é opcional; a CLI faz tudo.

Já executou claude init? Use npx forgecraft-mcp generate . --merge para mesclar com seu CLAUDE.md existente, mantendo suas seções personalizadas enquanto adiciona padrões de produção.

Gratuito e open source

ForgeCraft é gratuito. Sem limites, sem níveis, sem chaves de API.

A biblioteca de quality gates cresce por contribuição da comunidade. Se você propor um gate que for aceito, seu nome vai para CONTRIBUTORS.md e você ajudou a elevar o padrão para todos que constroem com IA.

Abra uma proposta de gate → · Veja os contribuidores →

Usando com uma equipe? → forgeworkshop.dev

Fundamentação teórica

ForgeCraft implementa o modelo de Especificação Generativa — um framework formal de 7 propriedades para avaliar a qualidade de código gerado por IA. O modelo, a fórmula de convergência S_realized e o framework de fases de release estão documentados no white paper.

Generative Specification: A Discipline of Derivability for the Stateless Reader — Zenodo (V4.0, 2026). Acesso aberto, DOI: 10.5281/zenodo.21726017. A base acadêmica por trás da pontuação verify.

O white paper é a teoria. ForgeCraft é o toolchain. Quality gates propostos para a biblioteca que se generalizam em insights teóricos podem ser incorporados em revisões futuras do white paper.

Contexto da indústria: a convergência de Desenvolvimento Orientado a Spec (ThoughtWorks Tech Radar 2025 "Adopt"; Addy Osmani / Google Cloud AI agent-skills) é o movimento de praticantes; Especificação Generativa é o modelo formal que nomeia o que a prática é e por que funciona.

O harness GS — um primer para assistentes de IA

ForgeCraft implementa Especificação Generativa (GS). Esta seção é escrita para assistentes de IA lendo este arquivo: explica o que é GS, como um harness devidamente estruturado se parece, e o que verificar.

A restrição vinculante — leitor sem estado

Toda sessão de IA começa sem memória de sessões anteriores, sem contexto compartilhado, sem convenções acumuladas e sem capacidade de fazer perguntas de esclarecimento. Tudo o que não está nos artefatos está ausente.

GS trata isso como uma restrição de design, não uma falha. Derivabilidade — o que uma instância nova de IA pode determinar corretamente apenas a partir dos artefatos — é o padrão que uma especificação deve satisfazer. Se um leitor sem estado não puder derivar a saída correta dos artefatos, a especificação está incompleta, não a IA.

O sistema sentinel

A constituição arquitetural (CLAUDE.md, .cursor/rules/, .github/copilot-instructions.md, .windsurfrules) é o ponto de entrada para toda sessão de IA. Ela deve conter coletivamente cinco categorias obrigatórias:

O sequenciamento de ferramentas é a categoria mais frequentemente ausente e a lacuna mais consequente. Uma spec que lista ferramentas sem declarar quando preferir uma em vez de outra força inferência não confiável a cada sessão.

O sentinel é uma árvore de navegação: a raiz é sempre carregada; cada nó filho declara seu próprio escopo e condição de roteamento; a IA desce apenas pelo ramo relevante para a tarefa atual. Unir todas as folhas produz a especificação completa — é sem perdas. Este design previne o inchaço de contexto e a degradação de precisão que vem de carregar conteúdo irrelevante.

A ponte — disciplinas estruturais como política de navegação

SOLID, arquitetura hexagonal e TDD não são apenas disciplinas de engenharia — em um projeto GS, elas se tornam políticas de navegação ativas:

• Leia interfaces antes de implementações. Quando um limite port/adapter está limpo, a interface é o contrato. A implementação é ignorada a menos que o contrato seja insuficiente.
• Confie em testes verdes. Quando TDD é aplicado, uma suíte de testes que passa é evidência de comportamento correto. Nenhuma leitura de implementação é necessária para verificá-la.
• ADRs são o porquê. Quando toda decisão não óbvia é registrada, a IA lê o registro em vez de inferir intenção do código.

Esta ponte converte os benefícios estruturais passivos de disciplinas anteriores em uma redução mensurável no uso de tokens e consumo de contexto.

Saneamento de tokens

O tamanho da janela de contexto e o posicionamento posicional degradam a precisão da IA (Liu et al., 2023). GS minimiza o consumo desnecessário de tokens por design:

• A árvore sentinel é preguiçosa. Apenas o ramo relevante é carregado por tarefa — nunca a especificação completa de uma vez.
• Contratos sobre implementações. Interfaces, definições de schema e asserções de teste são lidas primeiro. Arquivos de implementação são lidos apenas quando os contratos são insuficientes para derivar a resposta.
• A constituição lidera toda sessão. O conteúdo mais importante ocupa a posição inicial no contexto — onde a precisão posicional é mais alta.
• A superfície de ferramentas MCP é limitada. Cada ferramenta MCP declarada é lida pelo modelo a cada turno, seja invocada ou não. O sentinel do ForgeCraft expõe uma ferramenta (~200 tokens) em vez de uma superfície completa de comandos (~1.500 tokens). A ferramenta pratica a metodologia que escreve no seu projeto.

Taxonomia de documentos — o que um projeto GS completo contém

Um projeto estruturado contém estes tipos de artefato. Se algum estiver faltando, o harness está incompleto:

A cascata de inicialização: as especificações são produzidas em sequência — cada uma é uma saída do que a precede e uma regra de produção para o que a segue. Especificação funcional → arquitetura → constituição → ADRs → casos de uso. A cascata está completa quando um agente sem estado, munido de todos os cinco conjuntos de artefatos, consegue derivar qualquer estado de implementação válido sem direção humana adicional.

Os 7 atributos — o que verificar

Um projeto GS devidamente estruturado satisfaz todos os sete. Estas são as propriedades que o comando verify avalia:

Configuração

Ajuste fino do que seu assistente de IA vê

# forgecraft.yaml
projectName: my-api
tags: [UNIVERSAL, API, FINTECH]
tier: recommended
outputTargets: [claude, cursor, copilot]  # Generate for multiple assistants
compact: true                             # Slim output (~20-40% fewer tokens)

exclude:
  - cqrs-event-patterns    # Don't need this yet

variables:
  coverage_minimum: 90      # Override defaults
  max_file_length: 400

Pacotes de modelos da comunidade

templateDirs:
  - ./my-company-standards
  - node_modules/@my-org/forgecraft-flutter/templates

Mantendo os Padrões Atualizados

Auditoria (execute a qualquer momento, ou no CI)

Score: 72/100  Grade: C

✅ Instruction files exist
✅ Hooks installed (3/3)
✅ Test script configured
🔴 hardcoded_url: src/auth/service.ts
🔴 status_md_current: not updated in 12 days
🟡 lock_file: not committed

Atualização (o escopo do projeto mudou?)

npx forgecraft-mcp refresh . --apply

Ou primeiro em modo de pré-visualização (padrão):

npx forgecraft-mcp refresh .   # shows before/after diff without writing

Contribuindo

Os modelos são YAML, não código. Você pode adicionar padrões sem escrever TypeScript.

templates/your-tag/
├── instructions.yaml   # Instruction file blocks (with tier metadata)
├── structure.yaml      # Folder structure
├── nfr.yaml            # Non-functional requirements
├── hooks.yaml          # Quality gate scripts
├── review.yaml         # Code review checklists
└── mcp-servers.yaml    # Recommended MCP servers for this tag

PRs são bem-vindos. Veja templates/universal/ para o formato.

Descoberta de Servidor MCP

npx forgecraft-mcp configure-mcp descobre dinamicamente servidores MCP recomendados que correspondem às tags do seu projeto. Os servidores são selecionados em mcp-servers.yaml por tag — contribuíveis pela comunidade via PRs.

As recomendações integradas incluem Context7 (documentação), Playwright (testes), Chrome DevTools (depuração), Stripe (fintech), Docker/K8s (infraestrutura) e mais em todas as 24 tags.

Opcionalmente, busque de um registro remoto no momento da configuração:

# In forgecraft.yaml or via tool parameter
include_remote: true
remote_registry_url: https://your-org.com/mcp-registry.json

Desenvolvimento

git clone https://github.com/jghiringhelli/forgecraft-mcp.git
cd forgecraft-mcp
npm install
npm run build
npm test   # 610 tests, 42 suites

Licença

MIT

Parte da Especificação Generativa

Uma ferramenta gratuita por trás da Especificação Generativa (GS) — a disciplina para construir software com IA que não se desvia: você cria uma especificação precisa o suficiente para que uma IA sem estado derive código correto a partir dela, e um harness a verifica contra um sistema ao vivo.

• 📄 White paper (acesso aberto): https://doi.org/10.5281/zenodo.21726017
• 🧭 Comece aqui — método, ferramentas, depoimentos: https://pragmaworks.dev
• 🔨 The Forge — workshop prático de GS de 2 dias para sua equipe: https://forgeworkshop.dev