maestro-bundle 1.2.1 → 1.3.1

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 (3) hide show
  1. package/README.md +125 -37
  2. package/package.json +1 -1
  3. package/src/cli.mjs +33 -23
package/README.md CHANGED
@@ -1,83 +1,171 @@
1
1
  # maestro-bundle
2
2
 
3
- Um comando. Bundle instalado. Agente governado. Funciona com **qualquer editor AI**.
3
+ Um comando. Bundle instalado. Agente governado. [GitHub Spec Kit](https://github.com/github/spec-kit) configurado.
4
4
 
5
5
  ```bash
6
6
  npx maestro-bundle ai-agents claude
7
7
  ```
8
8
 
9
+ ## O que faz
10
+
11
+ 1. Instala **AGENTS.md** + **skills** no formato correto do seu editor
12
+ 2. Instala o [GitHub Spec Kit](https://github.com/github/spec-kit) (`specify-cli@v0.4.3`) no projeto
13
+ 3. Roda `specify init` que registra os commands `/speckit.*` no editor
14
+ 4. Integra o `constitution.md` do bundle com os princípios do projeto
15
+
16
+ O dev abre o editor e já tem skills + `/speckit.specify` funcionando.
17
+
9
18
  ## Editores suportados
10
19
 
11
20
  | Editor | Comando | O que instala |
12
21
  |---|---|---|
13
- | **Claude Code** | `npx maestro-bundle <bundle> claude` | `CLAUDE.md` + `.claude/rules/` |
14
- | **Cursor** | `npx maestro-bundle <bundle> cursor` | `.cursorrules` + `.cursor/rules/` |
15
- | **OpenAI Codex** | `npx maestro-bundle <bundle> codex` | `AGENTS.md` |
22
+ | **Claude Code** | `npx maestro-bundle <bundle> claude` | `CLAUDE.md` + `.claude/skills/` + `.claude/commands/speckit.*` |
23
+ | **Cursor** | `npx maestro-bundle <bundle> cursor` | `AGENTS.md` + `.cursor/skills/` + `.cursor/commands/speckit.*` |
24
+ | **OpenAI Codex** | `npx maestro-bundle <bundle> codex` | `AGENTS.md` + `.agents/skills/speckit-*` |
16
25
  | **GitHub Copilot** | `npx maestro-bundle <bundle> copilot` | `.github/copilot-instructions.md` + `.github/instructions/` |
17
26
  | **Windsurf** | `npx maestro-bundle <bundle> windsurf` | `.windsurfrules` |
18
- | **Todos** | `npx maestro-bundle <bundle> all` | Tudo acima de uma vez |
27
+ | **Todos** | `npx maestro-bundle <bundle> all` | Tudo acima no mesmo repo |
19
28
 
20
29
  ## Bundles disponíveis
21
30
 
22
31
  ```bash
23
- npx maestro-bundle ai-agents claude # Agentes AI com LangChain
24
- npx maestro-bundle jhipster-monorepo cursor # JHipster monolítico
25
- npx maestro-bundle jhipster-microservices all # JHipster microsserviços
26
- npx maestro-bundle data-pipeline codex # Pipeline dados/ML
27
- npx maestro-bundle frontend-spa copilot # React SPA
32
+ npx maestro-bundle ai-agents claude # Python + LangChain + LangGraph + FastAPI
33
+ npx maestro-bundle jhipster-monorepo cursor # Java 21 + Spring Boot + Angular
34
+ npx maestro-bundle jhipster-microservices codex # Java 21 + Spring Boot + Kafka + K8s
35
+ npx maestro-bundle data-pipeline copilot # Python + Pandas + Scikit-learn + MLflow
36
+ npx maestro-bundle frontend-spa windsurf # React + TypeScript + Tailwind + Vite
28
37
  ```
29
38
 
30
39
  ## O que acontece
31
40
 
32
41
  ```
33
- $ npx maestro-bundle ai-agents all
42
+ $ npx maestro-bundle ai-agents claude
34
43
 
35
44
  Bundle: Sistema Multi-Agente com AI
36
- Editor: Claude Code, Cursor, OpenAI Codex, GitHub Copilot, Windsurf
45
+ Editor: Claude Code
37
46
 
38
- ✔ Claude Code: CLAUDE.md + AGENTS.md, 14 rules em .claude/rules/
39
- ✔ Cursor: .cursorrules, 14 rules em .cursor/rules/
40
- ✔ OpenAI Codex: AGENTS.md
41
- ✔ GitHub Copilot: .github/copilot-instructions.md, 14 rules em .github/instructions/
42
- ✔ Windsurf: .windsurfrules
43
- ✔ 14 skills canônicas
44
- ✔ .spec/constitution.md (GitHub Spec Kit)
45
- ✔ Spec Kit instalado
47
+ ✔ Claude Code: AGENTS.md, CLAUDE.md → @AGENTS.md, 14 skills em .claude/skills/
48
+ ✔ 14 skills canônicas em skills/
49
+ ✔ references/ pronto
50
+ ✔ specify-cli v0.4.3 instalado
51
+ ✔ Spec Kit inicializado (/speckit.* commands disponíveis)
52
+ ✔ Constitution do bundle integrado ao Spec Kit
46
53
 
47
54
  Pronto!
55
+
56
+ Comandos SDD disponíveis no editor:
57
+ /speckit.constitution — Definir princípios do projeto
58
+ /speckit.specify — Especificar O QUE e POR QUÊ
59
+ /speckit.plan — Planejar arquitetura e stack
60
+ /speckit.tasks — Quebrar em tasks atômicas
61
+ /speckit.implement — Executar as tasks
62
+
63
+ Próximo passo:
64
+ Abra o projeto no editor AI e use /speckit.specify para começar
65
+ ```
66
+
67
+ ## Estrutura instalada por editor
68
+
69
+ ### Claude Code
70
+
71
+ ```
72
+ seu-projeto/
73
+ ├── CLAUDE.md # @AGENTS.md (aponta pro AGENTS.md)
74
+ ├── AGENTS.md # Instruções do bundle
75
+ ├── .claude/
76
+ │ ├── skills/ # Skills do bundle
77
+ │ │ ├── rag-pipeline/SKILL.md
78
+ │ │ ├── clean-architecture/SKILL.md
79
+ │ │ ├── commit-pattern/SKILL.md
80
+ │ │ └── ...
81
+ │ └── commands/ # Commands do Spec Kit (gerado pelo specify init)
82
+ │ ├── speckit.constitution.md
83
+ │ ├── speckit.specify.md
84
+ │ ├── speckit.plan.md
85
+ │ ├── speckit.tasks.md
86
+ │ └── speckit.implement.md
87
+ ├── .specify/ # Spec Kit (templates, scripts, constitution)
88
+ │ ├── memory/constitution.md
89
+ │ ├── scripts/
90
+ │ └── templates/
91
+ ├── skills/ # Skills canônicas (para Deep Agents)
92
+ └── references/
93
+ ```
94
+
95
+ ### Cursor
96
+
97
+ ```
98
+ seu-projeto/
99
+ ├── AGENTS.md # Instruções (Cursor lê automaticamente)
100
+ ├── .cursor/
101
+ │ ├── skills/ # Skills do bundle
102
+ │ │ ├── rag-pipeline/SKILL.md
103
+ │ │ └── ...
104
+ │ └── commands/ # Commands do Spec Kit
105
+ │ ├── speckit.specify.md
106
+ │ └── ...
107
+ ├── .specify/
108
+ ├── skills/
109
+ └── references/
48
110
  ```
49
111
 
50
- ## Onde cada editor procura
112
+ ### OpenAI Codex
51
113
 
52
114
  ```
53
115
  seu-projeto/
54
- ├── CLAUDE.md ← Claude Code
55
- ├── AGENTS.md ← Codex, agents.md universal
56
- ├── .cursorrules ← Cursor
57
- ├── .windsurfrules ← Windsurf
58
- ├── .claude/rules/*.md ← Claude Code (skills como rules)
59
- ├── .cursor/rules/*.md ← Cursor (skills como rules)
60
- ├── .github/copilot-instructions.md ← Copilot
61
- ├── .github/instructions/*.instructions.md ← Copilot (skills)
62
- ├── .spec/constitution.md ← GitHub Spec Kit (SDD)
63
- ├── skills/ ← Canônicas (Deep Agents, referência)
64
- │ ├── rag-pipeline/SKILL.md
65
- │ ├── clean-architecture/SKILL.md
66
- │ └── ...
67
- └── references/ ← Docs sob demanda
116
+ ├── AGENTS.md # Instruções (Codex lê automaticamente)
117
+ ├── .agents/
118
+ │ └── skills/ # Commands do Spec Kit (como skills)
119
+ │ ├── speckit-constitution/SKILL.md
120
+ │ ├── speckit-specify/SKILL.md
121
+ │ └── ...
122
+ ├── .specify/
123
+ ├── skills/ # Skills canônicas
124
+ └── references/
68
125
  ```
69
126
 
127
+ ## GitHub Spec Kit — SDD no editor
128
+
129
+ O bundle instala automaticamente o [GitHub Spec Kit](https://github.com/github/spec-kit) no projeto. Isso significa que ao abrir o editor o dev já pode usar:
130
+
131
+ | Command | O que faz |
132
+ |---|---|
133
+ | `/speckit.constitution` | Definir princípios e padrões do projeto |
134
+ | `/speckit.specify` | Especificar O QUE construir e POR QUÊ |
135
+ | `/speckit.plan` | Planejar arquitetura, stack, decisões técnicas |
136
+ | `/speckit.tasks` | Quebrar em tasks atômicas implementáveis |
137
+ | `/speckit.implement` | Executar todas as tasks |
138
+ | `/speckit.clarify` | Fazer perguntas para desambiguar requisitos |
139
+ | `/speckit.analyze` | Verificar consistência entre artefatos |
140
+ | `/speckit.checklist` | Gerar checklists de qualidade |
141
+
142
+ O fluxo SDD garante que ninguém sai codando sem spec:
143
+
144
+ ```
145
+ /speckit.specify → /speckit.plan → /speckit.tasks → /speckit.implement
146
+ ```
147
+
148
+ ## Pré-requisitos
149
+
150
+ - **Node.js 18+** (para rodar o npx)
151
+ - **Git** (para o specify init)
152
+ - **uv** ou **pip** (para instalar o specify-cli — o bundle tenta instalar automaticamente)
153
+
70
154
  ## Uso avançado
71
155
 
72
156
  ```bash
73
157
  # Instalar em diretório específico
74
158
  npx maestro-bundle jhipster-monorepo cursor ./meu-projeto
75
159
 
160
+ # Instalar para todos os editores (time usa editores diferentes)
161
+ npx maestro-bundle ai-agents all
162
+
76
163
  # Ver bundles e editores disponíveis
77
164
  npx maestro-bundle --help
78
165
  ```
79
166
 
80
167
  ## Links
81
168
 
82
- - [AGENTS.md spec](https://agents.md/) — Padrão universal para instruções de agentes
83
- - [GitHub Spec Kit](https://github.com/github/spec-kit) — SDD (Specification-Driven Development)
169
+ - [AGENTS.md](https://agents.md/) — Padrão universal para instruções de agentes AI
170
+ - [GitHub Spec Kit](https://github.com/github/spec-kit) — Specification-Driven Development
171
+ - [Agent Skills](https://agentskills.io) — Padrão aberto para skills de agentes
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "maestro-bundle",
3
- "version": "1.2.1",
3
+ "version": "1.3.1",
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"
package/src/cli.mjs CHANGED
@@ -323,7 +323,7 @@ async function main() {
323
323
  // Mapear editor para flag --ai do specify
324
324
  const aiFlags = {
325
325
  claude: "claude",
326
- cursor: "cursor",
326
+ cursor: "cursor-agent",
327
327
  codex: "codex",
328
328
  copilot: "copilot",
329
329
  windsurf: "windsurf",
@@ -332,34 +332,33 @@ async function main() {
332
332
  const primaryEditor = editorsToInstall[0];
333
333
  const aiFlag = aiFlags[primaryEditor] || "claude";
334
334
 
335
- // 4a. Instalar specify-cli se não tiver
336
- const spinner4 = ora("Verificando GitHub Spec Kit (specify-cli)").start();
335
+ // 4a. Instalar specify-cli
336
+ const SPECKIT_VERSION = "v0.4.3";
337
+ const spinner4 = ora("Instalando GitHub Spec Kit (specify-cli)").start();
337
338
  let specifyInstalled = false;
339
+
340
+ // Verificar se já está instalado (specify não aceita --version, usar --help)
338
341
  try {
339
- execSync("specify --version", { stdio: "ignore" });
342
+ execSync("specify --help", { stdio: "ignore" });
340
343
  specifyInstalled = true;
341
344
  spinner4.succeed("specify-cli já instalado");
342
345
  } catch {
343
- spinner4.info("specify-cli não encontrado");
344
- const spinner4b = ora("Instalando specify-cli...").start();
346
+ // Não instalado — instalar
345
347
  try {
346
- const SPECKIT_VERSION = "v0.4.3";
347
- execSync(`uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@${SPECKIT_VERSION}`, {
348
- stdio: "ignore", timeout: 120000,
348
+ execSync(`uv tool install specify-cli --from "git+https://github.com/github/spec-kit.git@${SPECKIT_VERSION}"`, {
349
+ stdio: "pipe", timeout: 120000,
349
350
  });
350
351
  specifyInstalled = true;
351
- spinner4b.succeed(`specify-cli ${SPECKIT_VERSION} instalado`);
352
- } catch {
352
+ spinner4.succeed(`specify-cli ${SPECKIT_VERSION} instalado`);
353
+ } catch (err) {
354
+ // Pode já estar instalado mas uv retorna erro, checar de novo
353
355
  try {
354
- const SPECKIT_VERSION = "v0.4.3";
355
- execSync(`pip install specify-cli --src git+https://github.com/github/spec-kit.git@${SPECKIT_VERSION}`, {
356
- stdio: "ignore", timeout: 60000,
357
- });
356
+ execSync("specify --help", { stdio: "ignore" });
358
357
  specifyInstalled = true;
359
- spinner4b.succeed("specify-cli instalado via pip");
358
+ spinner4.succeed("specify-cli já instalado");
360
359
  } catch {
361
- spinner4b.warn("Não foi possível instalar. Instale manualmente:");
362
- console.log(chalk.dim(" uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v0.4.3"));
360
+ spinner4.warn("Não foi possível instalar. Rode manualmente:");
361
+ console.log(chalk.dim(` uv tool install specify-cli --from "git+https://github.com/github/spec-kit.git@${SPECKIT_VERSION}"`));
363
362
  }
364
363
  }
365
364
  }
@@ -369,14 +368,25 @@ async function main() {
369
368
  const spinner4c = ora(`Inicializando Spec Kit no projeto (--ai ${aiFlag})`).start();
370
369
  const specifyEnv = { ...process.env, PYTHONIOENCODING: "utf-8", PYTHONUTF8: "1" };
371
370
  let specInitOk = false;
371
+
372
+ // Precisa de "y" piped pois specify pede confirmação se dir não vazio
373
+ // --script sh para evitar dependência de pwsh no Windows
374
+ // --ai-skills necessário para codex
375
+ const extraFlags = primaryEditor === "codex" ? " --ai-skills" : "";
372
376
  const initCmds = [
373
- `specify init --here --ai ${aiFlag}`,
374
- `specify init . --ai ${aiFlag}`,
375
- `specify init --here --ai ${aiFlag} --no-git`,
377
+ `echo y | specify init . --ai ${aiFlag}${extraFlags} --script sh --force`,
378
+ `echo y | specify init . --ai ${aiFlag}${extraFlags} --script sh`,
379
+ `echo y | specify init . --ai ${aiFlag}${extraFlags}`,
376
380
  ];
377
381
  for (const cmd of initCmds) {
378
382
  try {
379
- execSync(cmd, { stdio: "ignore", timeout: 30000, cwd: targetDir, env: specifyEnv });
383
+ execSync(cmd, {
384
+ stdio: "pipe",
385
+ timeout: 60000,
386
+ cwd: targetDir,
387
+ env: specifyEnv,
388
+ shell: true,
389
+ });
380
390
  specInitOk = true;
381
391
  break;
382
392
  } catch { /* try next */ }
@@ -386,7 +396,7 @@ async function main() {
386
396
  } else {
387
397
  spinner4c.warn("Inicialize manualmente no terminal:");
388
398
  console.log(chalk.dim(` cd ${targetDir}`));
389
- console.log(chalk.dim(` specify init --here --ai ${aiFlag}`));
399
+ console.log(chalk.dim(` specify init . --ai ${aiFlag} --script sh`));
390
400
  }
391
401
 
392
402
  // 4c. Copiar constitution.md do bundle para dentro do .specify/memory/