Engineering docs

Engineering Docs

22 habilidades componíveis e de acionamento automático que transformam seu agente de codificação em um engenheiro principal — da ideia bruta à documentação pronta para produção.

---

Por que Engineering Docs?

Seu agente de codificação é poderoso, mas ele não conhece a arquitetura do seu projeto, seus usuários ou suas restrições. Engineering Docs dá a ele habilidades de documentação em nível de engenheiro principal — para que ele possa:

• Transformar ideias brutas em blueprints completos — conceito de negócio → especificação técnica → arquitetura → plano de implantação
• Fazer as perguntas certas — entrevistas por chamada de ferramenta com 2 a 3 perguntas direcionadas por habilidade (sem perguntas repetidas)
• Gerar documentos prontos para produção — ISO/IEC/IEEE 29148, Modelo C4, STRIDE, padrões Google SRE
• Funcionar em 14+ agentes — Claude Code, Copilot, Cursor, Gemini CLI, Goose, Pi e mais

---

Como Funciona

O plugin funciona por meio de um fluxo de trabalho estruturado:

1. Usuário dá a ideia → A habilidade Orquestradora é ativada automaticamente
2. Detecção de modo → Greenfield (novo) vs Brownfield (existente)
3. Fase de entrevista → Perguntas por chamada de ferramenta com carregamento de contexto
4. Geração de documentos → Geração sequencial com 22 habilidades especializadas
5. Verificações de consistência → Validação entre documentos
6. Índice mestre → Blueprint completo pronto para implementação

---

Início Rápido

npx engineering-docs

Ou instale para seu agente específico:

Agente	Comando de Instalação
Claude Code	/plugin install engineering-docs@claude-plugins-official
Gemini CLI	gemini extensions install https://github.com/fattain-naime/engineering-docs
Cursor	/add-plugin engineering-docs
Goose	goose configure → adicionar extensão
Pi	pi install git:github.com/fattain-naime/engineering-docs
OpenCode	npx engineering-docs --opencode
Kilo Code	Instalar pelo marketplace de plugins do Kilo Code
Roo Code	Instalar pelo marketplace de plugins do Roo Code
Cline	npx engineering-docs --cline
Kimi Code	/plugins install https://github.com/fattain-naime/engineering-docs
Codex	Instalar pelo marketplace de plugins do Codex
Copilot CLI	npx engineering-docs --copilot
Factory Droid	npx engineering-docs --factory

Consulte Instalação para instruções detalhadas.

---

Como Funciona

graph LR
    A[Your Idea] --> B[Orchestrator]
    B --> C{Interview}
    C --> D[Business Concept]
    D --> E[Project Plan]
    E --> F[Technical Spec]
    F --> G[System Architecture]
    G --> H[API Design]
    H --> I[Implementation Plan]
    I --> J[Test Strategy]
    J --> K[Deployment Plan]
    K --> L[Master Index]

1. Dê sua ideia — "Quero construir X"
2. Responda 2 a 3 perguntas por habilidade — por chamadas de ferramenta, não no chat inline
3. Revise cada documento — aprove ou solicite alterações
4. Receba seu blueprint — conjunto de documentação completo e consistente

Recursos inteligentes:

• Carregamento de contexto — lê documentos anteriores antes de fazer perguntas (nunca repete)
• Entrevistas por chamada de ferramenta — captura de entrada limpa, sem poluir a conversa
• Dimensionamento correto — pula documentos que não se aplicam ao seu projeto
• Consistência entre documentos — verifica se nomes de entidades, papéis e decisões coincidem

---

O Que Está Incluído

Biblioteca de Habilidades (22 Habilidades)

Descoberta e Planejamento

Habilidade	O Que Produz
using-engineering-docs	Orquestradora — roteia automaticamente para todas as outras habilidades
business-concept	Problema, usuários, proposta de valor, monetização, restrições
project-plan	Escopo, marcos, RACI, cronograma, estrutura analítica do projeto
user-personas-behavior	Personas de usuário, JTBD, métricas de sucesso, plano de analytics

Especificação e Viabilidade

Habilidade	O Que Produz
technical-specification	SRS/TSD com sintaxe EARS, matriz de rastreabilidade
technical-feasibility-study	Recomendação de avançar/não avançar com evidências

Arquitetura e Design

Habilidade	O Que Produz
system-architecture-document	Diagramas C4, visões 4+1, stack tecnológico, NFRs
architecture-decision-record	Registro imutável de ADR (formato MADR)
database-design-document	ERD, schema, indexação, plano de migração
api-design-document	Contrato REST/OpenAPI 3.1, erros RFC 7807
admin-access-control-specification	Matriz RBAC, auditoria de logs, break-glass
technical-blueprint	TDD de qualidade Google/Stripe por funcionalidade
ux-flow-specification	Jornadas do usuário, fluxos de tela, estados de UI
design-system-specification	Design tokens, componentes, acessibilidade

Qualidade e Risco

Habilidade	O Que Produz
security-threat-model	Análise STRIDE, superfície de ataque, mitigações
test-strategy-document	Pirâmide de testes, portões de CI, metas de cobertura
implementation-plan	Sequência de build ordenada por dependências, portões de fase

Entrega e Operações

Habilidade	O Que Produz
deployment-plan	Estratégia de release, portão de avançar/não avançar, rollback
slo-error-budget-document	Metas de SLI/SLO, alertas de burn-rate
technical-runbook	Manual de operações de plantão (Google SRE)
disaster-recovery-plan	RTO/RPO, estratégia de backup, failover
incident-postmortem	RCA sem culpa com Five Whys

Agentes Personalizados (4 Agentes)

Agente	Finalidade
documentation-generator	Gerar documentação abrangente para projetos de software
architecture-reviewer	Revisar arquitetura de sistemas quanto a escalabilidade, segurança e manutenibilidade
api-designer	Projetar APIs RESTful seguindo as melhores práticas
test-strategist	Criar estratégias de teste abrangentes para projetos de software

Scripts Utilitários

Script	Finalidade
generate-dependency-graph.js	Visualização de dependências com Mermaid
validate-documents.js	Validação de documentos
calculate-error-budget.js	Calculadora de orçamento de erro SLO
generate-test-cases.js	Gerador de casos de teste a partir de especificações
generate-ddl.js	Gerador de DDL SQL a partir de schema
check-consistency.js	Verificador de consistência entre documentos

Integração MCP

.mcp.json          # MCP server configuration
scripts/validate.js    # Validation server (validate_document_set, check_consistency, generate_index)

Hooks

hooks/hooks.json          # SessionStart hook configuration
hooks/check-progress.js   # Check for in-progress documentation
hooks/run-hook.cmd        # Windows compatibility

Estrutura de Avaliação

evals/evals.json           # Test cases for orchestrator and key skills
evals/README.md            # How to run evals
evals/test-prompts/        # Sample test prompts

Estrutura do Plugin (Compatível com Claude)

engineering-docs/
├── .claude-plugin/
│   ├── plugin.json        # Plugin manifest
│   └── marketplace.json   # Marketplace manifest
├── skills/                # 22 skills (SKILL.md files)
├── agents/                # 4 custom agents
├── hooks/                 # Event handlers
├── .mcp.json              # MCP server configuration
├── scripts/               # All scripts (install, validate, test, utilities) (install.js, validate.js, test-skills.js)
├── scripts/               # Utility scripts + setup scripts
├── evals/                 # Test framework
└── integrations/          # Other agent platform configs
    ├── agents/            # Agent configs (AGENTS.md, CLAUDE.md, GEMINI.md)
    └── plugins/           # Plugin configs for 13+ platforms

Conformidade com as Diretrizes do Claude:

• ✅ Componentes na raiz do plugin (não dentro de .claude-plugin/)
• ✅ Habilidades no diretório skills/ com SKILL.md
• ✅ Agentes no diretório agents/ com frontmatter
• ✅ Hooks em hooks/hooks.json
• ✅ MCP em .mcp.json
• ✅ Nomenclatura kebab-case
• ✅ Validação aprovada: claude plugin validate .

---

Instalação

Instalador CLI (Recomendado)

npx engineering-docs

Detecta e copia automaticamente o plugin para o diretório do seu agente.

Instalação por Agente

Claude Code

# Official marketplace
/plugin install engineering-docs@claude-plugins-official

# Or register marketplace first
/plugin marketplace add fattain-naime/engineering-docs
/plugin install engineering-docs@engineering-docs

Gemini CLI

gemini extensions install https://github.com/fattain-naime/engineering-docs

Ou clone manualmente:

git clone https://github.com/fattain-naime/engineering-docs.git ~/.gemini/config/plugins/engineering-docs

Cursor / Windsurf

npx engineering-docs --cursor

Extrai cada habilidade para .cursor/rules/engineering-docs-*.mdc.

Goose

npx engineering-docs --goose

Ou configure manualmente em ~/.config/goose/config.yaml.

Pi

npx engineering-docs --pi

Ou instale a partir do git:

pi install git:github.com/fattain-naime/engineering-docs

OpenCode

npx engineering-docs --opencode

Kilo Code

npx engineering-docs --kilo

Ou instale pelo marketplace de plugins do Kilo Code.

Codex / GitHub Copilot

npx engineering-docs --codex

Copilot CLI

npx engineering-docs --copilot

Cline

npx engineering-docs --cline

Copia .clinerules para a raiz do seu projeto.

Factory Droid

npx engineering-docs --factory

Roo Code

npx engineering-docs --roo

Kimi Code

npx engineering-docs --kimi

Ou instale dentro do Kimi Code:

/plugins install https://github.com/fattain-naime/engineering-docs

Scripts Multiplataforma

# Windows (PowerShell)
pwsh scripts\setup.ps1
pwsh scripts\setup.ps1 -Target gemini
pwsh scripts\setup.ps1 -Target claude

# Linux / macOS (Bash)
chmod +x scripts/setup.sh
./scripts/setup.sh
./scripts/setup.sh --gemini
./scripts/setup.sh --claude

Destinos suportados: gemini, claude, local, cursor, kimi, codex, goose, pi, opencode, kilo, roo, cline, factory, copilot

Comportamento de Gravação Segura

Todos os métodos de instalação usam gravação segura para arquivos de configuração do agente:

• AGENTS.md — Criado somente se não existir
• CLAUDE.md — Criado somente se não existir
• GEMINI.md — Criado somente se não existir
• COPILOT.md — Criado somente se não existir
• GOOSE.md — Criado somente se não existir
• PI.md — Criado somente se não existir

Suas personalizações são sempre preservadas.

---

Compatibilidade Multiagente

Plataforma	Formato de Manifesto	Caminho de Instalação
Claude Code	.claude-plugin/plugin.json	~/.claude/plugins/engineering-docs/
Gemini CLI	integrations/plugins/gemini-extension.json	~/.gemini/config/plugins/engineering-docs/
Cursor / Windsurf	integrations/plugins/.cursor-plugin/plugin.json	./.cursor/rules/engineering-docs-*.mdc
Kimi Code	integrations/plugins/.kimi-plugin/plugin.json	~/.kimi-code/plugins/engineering-docs/
Codex	integrations/plugins/.codex-plugin/plugin.json	./.codex/engineering-docs/
OpenCode	integrations/plugins/.opencode/plugin.json	./.opencode/engineering-docs/
Goose	integrations/plugins/.goose/GOOSE.md	~/.config/goose/extensions/engineering-docs/
Pi	integrations/plugins/.pi/PI.md	~/.pi/packages/engineering-docs/
Kilo Code	integrations/plugins/.kilo-plugin/plugin.json	~/.kilo-code/plugins/engineering-docs/
Roo Code	integrations/plugins/.roo-plugin/plugin.json	~/.roo-code/plugins/engineering-docs/
Cline	integrations/plugins/.cline/.clinerules	./.clinerules
Factory Droid	integrations/plugins/.factory-plugin/plugin.json	~/.factory/plugins/engineering-docs/
Copilot CLI	integrations/plugins/.copilot/COPILOT.md	~/.copilot/plugins/engineering-docs/

---

Testes

# Run plugin validation
claude plugin validate .

# Run skill tests
npm test

# Test MCP server
node scripts/validate.js

---

Filosofia

• Sistêmico em vez de Ad-hoc — Processos rigorosos e reproduzíveis geram software mais seguro e limpo
• Rastreabilidade — Todo requisito está vinculado a uma meta de negócio e a um caso de teste
• Visual em Primeiro Lugar — Arquiteturas complexas mapeadas com diagramas Mermaid rastreáveis por Git
• Segurança Operacional — Nenhuma funcionalidade está completa sem roteiro de implantação, monitoramento e rollback
• Aprendizado sem Culpa — Falhas de produção são pontos de dados para fortalecimento do sistema

---

Contribuição

Aceitamos habilidades da comunidade! Revise CONTRIBUTING.md para as diretrizes.

---

Comunidade

• GitHub: fattain-naime/engineering-docs
• Issues: Relatar bugs ou solicitar recursos

---

Autor

• Fattain Naime — iamnaime.info.bd
• Repositório: https://github.com/fattain-naime/engineering-docs

---

Licença

MIT. Consulte LICENSE.