maestro-bundle 1.8.0 → 1.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +120 -150
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,108 +1,126 @@
1
1
  # maestro-bundle
2
2
 
3
- Um comando. Bundle instalado. Agente governado. Zero vibing code.
3
+ Um comando. Contexto completo pro agente AI. Qualquer editor.
4
4
 
5
5
  ```bash
6
6
  npx maestro-bundle ai-agents claude
7
7
  ```
8
8
 
9
- ## Filosofia: Sem spec, sem código
9
+ ## O problema
10
10
 
11
- O maestro-bundle instala tudo que o agente AI precisa para trabalhar de forma **governada** — e a peça central disso é o [GitHub Spec Kit](https://github.com/github/spec-kit).
11
+ Agentes AI (Claude Code, Cursor, Codex) são poderosos, mas sem contexto eles não sabem:
12
12
 
13
- O Spec Kit implementa **Specification-Driven Development (SDD)**: toda demanda — nova ou em andamento — precisa ter uma spec antes de qualquer linha de código. O agente é instruído a **recusar** implementar qualquer coisa que não tenha passado pelo fluxo:
13
+ - Qual a stack do projeto
14
+ - Quais padrões de código seguir
15
+ - O que a aplicação faz (requisitos)
16
+ - Que ferramentas usar e quando
17
+ - Qual o plano antes de sair codando
14
18
 
15
- ```
16
- /speckit.specify → /speckit.plan → /speckit.tasks → /speckit.implement
17
- ```
18
-
19
- Isso elimina o "vibing code" — aquele padrão onde o dev abre o Cursor e sai codando sem planejamento, sem requisitos, sem spec. Com o bundle instalado, o agente AI vai parar e perguntar: "Cadê a spec?"
19
+ O resultado é **vibing code** — o agente gera código sem direção, sem padrões, sem planejamento. Funciona para protótipos, mas é inviável para projetos reais com time.
20
20
 
21
- ## O que instala
22
-
23
- 1. **AGENTS.md** + **skills** no formato correto do editor — padrões, convenções e capacidades do agente
24
- 2. **PRD.md** — template de requisitos para o analista/dev preencher
25
- 3. **GitHub Spec Kit** — `specify-cli` instalado + `specify init` executado no projeto, registrando os commands `/speckit.*` no editor
26
- 4. **Constitution** — princípios do projeto integrados ao Spec Kit
27
- 5. **LangChain Skills** — 11 skills oficiais extras (apenas para `ai-agents`)
21
+ ## A solução: contexto em camadas
28
22
 
29
- ## Fluxo de trabalho
23
+ O maestro-bundle resolve isso instalando **3 camadas de contexto** que trabalham juntas:
30
24
 
31
25
  ```
32
26
  ┌─────────────────────────────────────────────────────────┐
33
- │ 1. Dev instala o bundle │
34
- │ npx maestro-bundle ai-agents claude │
35
27
  │ │
36
- │ 2. Analista/dev preenche o PRD.md │
37
- │ (requisitos, user stories, API spec) │
28
+ │ PRD.md O QUE construir │
29
+ │ (requisitos) User stories, API spec, modelo │
30
+ │ de dados, critérios de aceite │
31
+ │ │
32
+ ├─────────────────────────────────────────────────────────┤
38
33
  │ │
39
- │ 3. Dev abre o editor e pede uma feature │
40
- │ "Cria o endpoint de demands" │
34
+ │ AGENTS.md COMO construir │
35
+ │ (padrões) Stack, arquitetura, convenções, │
36
+ │ estrutura de projeto, git flow │
41
37
  │ │
42
- │ 4. Agente PARA e inicia o fluxo SDD: │
43
- │ /speckit.specify → spec.md │
44
- │ /speckit.plan → plan.md │
45
- │ /speckit.tasks → tasks.md │
46
- │ /speckit.implement → código │
38
+ ├─────────────────────────────────────────────────────────┤
39
+ │ │
40
+ │ Skills COM O QUE construir │
41
+ │ (capacidades) RAG pipeline, clean architecture, │
42
+ │ deploy, testes, etc. │
43
+ │ │
44
+ ├─────────────────────────────────────────────────────────┤
45
+ │ │
46
+ │ Spec Kit (SDD) EM QUE ORDEM construir │
47
+ │ (processo) /speckit.specify → plan → tasks │
48
+ │ → implement │
47
49
  │ │
48
- │ 5. Código é produzido seguindo: │
49
- │ - A spec (O QUE construir) │
50
- │ - O AGENTS.md (COMO construir) │
51
- │ - As skills (capacidades específicas) │
52
- │ - O PRD.md (requisitos do produto) │
53
50
  └─────────────────────────────────────────────────────────┘
54
51
  ```
55
52
 
56
- Se a demanda já está no meio (spec existe), o agente continua de onde parou. Se é bug fix simples, pode corrigir direto. Mas feature nova sem spec? Não rola.
53
+ Cada camada dá ao agente um tipo de contexto diferente. Juntas, elas fazem o agente trabalhar como um dev senior que conhece o projeto, segue os padrões e planeja antes de codar.
54
+
55
+ ## O que instala
56
+
57
+ ```bash
58
+ npx maestro-bundle ai-agents claude
59
+ ```
60
+
61
+ | O que | Para que | Quem preenche |
62
+ |---|---|---|
63
+ | **AGENTS.md** | Padrões, stack, convenções do projeto | Bundle (automático) |
64
+ | **Skills** | Capacidades específicas (RAG, clean arch, testes...) | Bundle (automático) |
65
+ | **PRD.md** | Requisitos do produto, user stories, API spec | Analista / Dev |
66
+ | **Spec Kit** | Processo SDD — spec → plan → tasks → implement | Agente + Dev |
67
+ | **Constitution** | Princípios inegociáveis do projeto | Bundle (automático) |
68
+ | **LangChain Skills** | 11 skills oficiais LangChain (bundles AI) | Bundle (automático) |
57
69
 
58
- ## Arquivos do projeto: quem faz o quê
70
+ O dev só precisa preencher o `PRD.md`. Todo o resto vem pronto.
59
71
 
60
- | Arquivo | Quem escreve | Quando | Para quê |
61
- |---|---|---|---|
62
- | **AGENTS.md** | Bundle (automático) | Na instalação | Define COMO o agente trabalha (stack, padrões, convenções) |
63
- | **PRD.md** | Analista / Dev | Antes de codar | Define O QUE construir (user stories, API spec, modelo de dados) |
64
- | **`.specify/specs/*/spec.md`** | Agente via `/speckit.specify` | Antes de cada feature | Especificação detalhada da feature |
65
- | **`.specify/specs/*/plan.md`** | Agente via `/speckit.plan` | Após spec | Plano técnico (arquitetura, decisões) |
66
- | **`.specify/specs/*/tasks.md`** | Agente via `/speckit.tasks` | Após plan | Tasks atômicas implementáveis |
67
- | **skills/** | Bundle (automático) | Na instalação | Capacidades que o agente carrega sob demanda |
72
+ ## Como funciona na prática
68
73
 
69
- ## Commands do Spec Kit disponíveis no editor
74
+ ```
75
+ 1. Dev instala o bundle
76
+ $ npx maestro-bundle ai-agents claude
70
77
 
71
- Após instalar o bundle, estes commands funcionam direto no editor:
78
+ 2. Analista/dev preenche o PRD.md com os requisitos
72
79
 
73
- | Command | Fase | O que faz |
74
- |---|---|---|
75
- | `/speckit.constitution` | Setup | Definir princípios e padrões do projeto |
76
- | `/speckit.specify` | Spec | Especificar O QUE construir e POR QUÊ |
77
- | `/speckit.plan` | Plan | Planejar arquitetura, stack, decisões técnicas |
78
- | `/speckit.tasks` | Tasks | Quebrar em tasks atômicas implementáveis |
79
- | `/speckit.implement` | Build | Executar todas as tasks seguindo o plano |
80
- | `/speckit.clarify` | (opcional) | Perguntas para desambiguar requisitos |
81
- | `/speckit.analyze` | (opcional) | Verificar consistência entre artefatos |
82
- | `/speckit.checklist` | (opcional) | Gerar checklists de qualidade |
80
+ 3. Dev abre o editor e pede uma feature:
81
+ "Cria o endpoint de autenticação JWT"
83
82
 
84
- ## Editores suportados
83
+ 4. O agente já sabe:
84
+ - Os requisitos (PRD.md)
85
+ - A stack e padrões (AGENTS.md)
86
+ - Como fazer JWT (skill de authentication)
87
+ - Que precisa criar spec antes de codar (Spec Kit)
85
88
 
86
- | Editor | Comando | O que instala |
87
- |---|---|---|
88
- | **Claude Code** | `npx maestro-bundle <bundle> claude` | `CLAUDE.md` + `.claude/skills/` + `.claude/commands/speckit.*` |
89
- | **Cursor** | `npx maestro-bundle <bundle> cursor` | `AGENTS.md` + `.cursor/skills/` + `.cursor/commands/speckit.*` |
90
- | **OpenAI Codex** | `npx maestro-bundle <bundle> codex` | `AGENTS.md` + `.agents/skills/speckit-*` |
91
- | **GitHub Copilot** | `npx maestro-bundle <bundle> copilot` | `.github/copilot-instructions.md` + `.github/instructions/` |
92
- | **Windsurf** | `npx maestro-bundle <bundle> windsurf` | `.windsurfrules` |
93
- | **Todos** | `npx maestro-bundle <bundle> all` | Tudo acima no mesmo repo |
89
+ 5. Resultado: código governado, consistente, planejado
90
+ ```
94
91
 
95
92
  ## Bundles disponíveis
96
93
 
94
+ | Bundle | Tipo de projeto | Stack |
95
+ |---|---|---|
96
+ | `ai-agents` | Sistemas multi-agente com AI | Python, LangChain, LangGraph, FastAPI, pgvector |
97
+ | `ai-agents-deep` | Deep Agent (tipo Claude Code) | Python, Deep Agents SDK, LangGraph, Subagentes |
98
+ | `jhipster-monorepo` | Aplicação JHipster monolítica | Java 21, Spring Boot, Angular, PostgreSQL |
99
+ | `jhipster-microservices` | Microsserviços JHipster | Java 21, Spring Boot, Kafka, Consul, K8s |
100
+ | `data-pipeline` | Pipeline de dados e ML | Python, Pandas, Scikit-learn, MLflow |
101
+ | `frontend-spa` | Frontend SPA | React, TypeScript, Tailwind, Vite |
102
+
97
103
  ```bash
98
- npx maestro-bundle ai-agents claude # Python + LangChain + LangGraph + FastAPI
99
- npx maestro-bundle jhipster-monorepo cursor # Java 21 + Spring Boot + Angular
100
- npx maestro-bundle jhipster-microservices codex # Java 21 + Spring Boot + Kafka + K8s
101
- npx maestro-bundle data-pipeline copilot # Python + Pandas + Scikit-learn + MLflow
102
- npx maestro-bundle frontend-spa windsurf # React + TypeScript + Tailwind + Vite
104
+ npx maestro-bundle ai-agents claude
105
+ npx maestro-bundle ai-agents-deep cursor
106
+ npx maestro-bundle jhipster-monorepo claude
107
+ npx maestro-bundle jhipster-microservices codex
108
+ npx maestro-bundle data-pipeline copilot
109
+ npx maestro-bundle frontend-spa windsurf
103
110
  ```
104
111
 
105
- ## O que acontece
112
+ ## Editores suportados
113
+
114
+ | Editor | Comando | Onde instala |
115
+ |---|---|---|
116
+ | **Claude Code** | `npx maestro-bundle <bundle> claude` | `CLAUDE.md` + `.claude/skills/` |
117
+ | **Cursor** | `npx maestro-bundle <bundle> cursor` | `AGENTS.md` + `.cursor/skills/` |
118
+ | **OpenAI Codex** | `npx maestro-bundle <bundle> codex` | `AGENTS.md` + `.agents/skills/` |
119
+ | **GitHub Copilot** | `npx maestro-bundle <bundle> copilot` | `.github/copilot-instructions.md` |
120
+ | **Windsurf** | `npx maestro-bundle <bundle> windsurf` | `.windsurfrules` |
121
+ | **Todos** | `npx maestro-bundle <bundle> all` | Tudo acima no mesmo repo |
122
+
123
+ ## O que acontece ao instalar
106
124
 
107
125
  ```
108
126
  $ npx maestro-bundle ai-agents claude
@@ -110,121 +128,73 @@ $ npx maestro-bundle ai-agents claude
110
128
  Bundle: Sistema Multi-Agente com AI
111
129
  Editor: Claude Code
112
130
 
113
- ✔ Claude Code: AGENTS.md, CLAUDE.md → @AGENTS.md, 14 skills em .claude/skills/
114
- ✔ PRD.md template instalado (preencha com os requisitos do produto)
131
+ ✔ Claude Code: AGENTS.md, CLAUDE.md, 14 skills em .claude/skills/
132
+ ✔ PRD.md template instalado
115
133
  ✔ 11 LangChain Skills instaladas
116
- ✔ 14 skills canônicas em skills/
117
- ✔ references/ pronto
118
134
  ✔ specify-cli v0.4.3 instalado
119
135
  ✔ Spec Kit inicializado (/speckit.* commands disponíveis)
120
- ✔ Constitution do bundle integrado ao Spec Kit
136
+ ✔ Constitution do bundle integrado
121
137
 
122
138
  Pronto!
123
139
 
124
- Comandos SDD disponíveis no editor:
125
- /speckit.constitution — Definir princípios do projeto
126
- /speckit.specify — Especificar O QUE e POR QUÊ
127
- /speckit.plan — Planejar arquitetura e stack
128
- /speckit.tasks — Quebrar em tasks atômicas
129
- /speckit.implement — Executar as tasks
130
-
131
140
  Próximo passo:
132
141
  1. Preencha o PRD.md com os requisitos do produto
133
142
  2. Abra o projeto no editor AI
134
143
  3. Use /speckit.specify para começar a primeira feature
135
144
  ```
136
145
 
137
- ## Estrutura instalada
146
+ ## Estrutura no projeto
138
147
 
139
- ### Claude Code
140
148
  ```
141
149
  seu-projeto/
142
- ├── CLAUDE.md # @AGENTS.md
143
- ├── AGENTS.md # COMO o agente trabalha
144
- ├── PRD.md # O QUE construir (preencher!)
150
+ ├── CLAUDE.md # Aponta para AGENTS.md
151
+ ├── AGENTS.md # Stack, padrões, convenções (automático)
152
+ ├── PRD.md # Requisitos do produto (preencher!)
145
153
  ├── .claude/
146
- │ ├── skills/ # Skills do bundle
147
- │ │ ├── rag-pipeline/SKILL.md
148
- │ │ ├── clean-architecture/SKILL.md
154
+ │ ├── skills/ # Capacidades do agente
155
+ │ │ ├── rag-pipeline/
156
+ │ │ ├── clean-architecture/
157
+ │ │ ├── testing-strategy/
149
158
  │ │ └── ...
150
- │ └── commands/ # /speckit.* (gerado pelo Spec Kit)
159
+ │ └── commands/ # Spec Kit commands
151
160
  │ ├── speckit.specify.md
152
161
  │ ├── speckit.plan.md
153
162
  │ ├── speckit.tasks.md
154
163
  │ └── speckit.implement.md
155
- ├── .specify/ # Spec Kit
156
- │ ├── memory/constitution.md # Princípios do projeto
157
- │ ├── scripts/ # Scripts auxiliares
158
- │ ├── templates/ # Templates para spec, plan, tasks
159
- │ └── specs/ # Specs das features (criadas via /speckit.specify)
164
+ ├── .specify/ # Specs, plans, tasks das features
165
+ │ ├── memory/constitution.md
166
+ │ ├── templates/
167
+ │ └── specs/
160
168
  │ └── 001-feature-name/
161
169
  │ ├── spec.md
162
170
  │ ├── plan.md
163
171
  │ └── tasks.md
164
- ├── skills/ # Skills canônicas (Deep Agents)
165
- └── references/ # Docs de referência
172
+ ├── skills/ # Skills canônicas (Deep Agents)
173
+ └── references/ # Docs de referência
166
174
  ```
167
175
 
168
- ### Cursor
169
- ```
170
- seu-projeto/
171
- ├── AGENTS.md # COMO o agente trabalha
172
- ├── PRD.md # O QUE construir (preencher!)
173
- ├── .cursor/
174
- │ ├── skills/ # Skills do bundle
175
- │ └── commands/ # /speckit.* commands
176
- ├── .specify/ # Spec Kit (specs, plans, tasks)
177
- ├── skills/ # Skills canônicas
178
- └── references/
179
- ```
180
-
181
- ### OpenAI Codex
182
- ```
183
- seu-projeto/
184
- ├── AGENTS.md # COMO o agente trabalha
185
- ├── PRD.md # O QUE construir (preencher!)
186
- ├── .agents/skills/ # speckit-* skills
187
- ├── .specify/ # Spec Kit
188
- ├── skills/ # Skills canônicas
189
- └── references/
190
- ```
191
-
192
- ## Skills extras do LangChain (bundle ai-agents)
176
+ ## Processo SDD com Spec Kit
193
177
 
194
- O bundle `ai-agents` instala automaticamente as 11 skills oficiais do [LangChain](https://github.com/langchain-ai/langchain-skills):
178
+ O bundle instala o [GitHub Spec Kit](https://github.com/github/spec-kit) que adiciona commands no editor para o fluxo de Specification-Driven Development:
195
179
 
196
- | Skill | O que faz |
180
+ | Command | O que faz |
197
181
  |---|---|
198
- | `framework-selection` | Escolher entre LangChain, LangGraph ou Deep Agents |
199
- | `langchain-fundamentals` | Criar agentes com `create_agent`, tools, middleware |
200
- | `langchain-middleware` | Human-in-the-loop, custom middleware, output estruturado |
201
- | `langchain-rag` | RAG: document loaders, embeddings, vector stores |
202
- | `langchain-dependencies` | Pacotes, versões, instalação |
203
- | `langgraph-fundamentals` | StateGraph, nodes, edges, streaming |
204
- | `langgraph-persistence` | Checkpointers, Store, time travel |
205
- | `langgraph-human-in-the-loop` | Interrupts, aprovação humana, resume |
206
- | `deep-agents-core` | Criar Deep Agents, harness, SKILL.md format |
207
- | `deep-agents-memory` | Memória e persistência para Deep Agents |
208
- | `deep-agents-orchestration` | Subagentes, planning, HITL |
182
+ | `/speckit.specify` | Especificar O QUE construir e POR QUÊ |
183
+ | `/speckit.plan` | Planejar arquitetura e decisões técnicas |
184
+ | `/speckit.tasks` | Quebrar em tasks atômicas |
185
+ | `/speckit.implement` | Executar as tasks seguindo o plano |
209
186
 
210
- ## Pré-requisitos
211
-
212
- - **Node.js 18+** (para rodar o npx)
213
- - **Git** (para o specify init)
214
- - **uv** ou **pip** (para instalar o specify-cli — o bundle tenta instalar automaticamente)
187
+ O agente é instruído a seguir esse fluxo para features novas. Bug fixes simples podem ir direto.
215
188
 
216
- ## Uso avançado
189
+ ## LangChain Skills (bundles AI)
217
190
 
218
- ```bash
219
- # Instalar em diretório específico
220
- npx maestro-bundle jhipster-monorepo cursor ./meu-projeto
191
+ Os bundles `ai-agents` e `ai-agents-deep` instalam automaticamente as [11 skills oficiais do LangChain](https://github.com/langchain-ai/langchain-skills) cobrindo LangChain, LangGraph e Deep Agents.
221
192
 
222
- # Instalar para todos os editores (time usa editores diferentes)
223
- npx maestro-bundle ai-agents all
193
+ ## Pré-requisitos
224
194
 
225
- # Ver bundles e editores disponíveis
226
- npx maestro-bundle --help
227
- ```
195
+ - **Node.js 18+**
196
+ - **Git**
197
+ - **uv** ou **pip** (para o Spec Kit — instalado automaticamente)
228
198
 
229
199
  ## Links
230
200
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "maestro-bundle",
3
- "version": "1.8.0",
3
+ "version": "1.9.0",
4
4
  "description": "Instala bundles de governança para projetos com AI agents. Um comando, tudo configurado.",
5
5
  "bin": {
6
6
  "maestro-bundle": "./src/cli.mjs"