maestro-bundle 1.8.0 → 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maestro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,234 +1,204 @@
 # maestro-bundle
 
-Um comando. Bundle instalado. Agente governado. Zero vibing code.
+One command. Full context for your AI agent. Any editor.
 
 ```bash
 npx maestro-bundle ai-agents claude
 ```
 
-## Filosofia: Sem spec, sem código
+## The problem
 
-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).
+AI agents (Claude Code, Cursor, Codex) are powerful, but without context they don't know:
 
-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:
+- What stack the project uses
+- Which coding standards to follow
+- What the application does (requirements)
+- What tools to use and when
+- That they should plan before coding
 
-```
-/speckit.specify → /speckit.plan → /speckit.tasks → /speckit.implement
-```
-
-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?"
+The result is **vibing code** — the agent generates code with no direction, no standards, no planning. Fine for prototypes, unacceptable for real projects with teams.
 
-## O que instala
+## The solution: layered context
 
-1. **AGENTS.md** + **skills** no formato correto do editor — padrões, convenções e capacidades do agente
-2. **PRD.md** — template de requisitos para o analista/dev preencher
-3. **GitHub Spec Kit** — `specify-cli` instalado + `specify init` executado no projeto, registrando os commands `/speckit.*` no editor
-4. **Constitution** — princípios do projeto integrados ao Spec Kit
-5. **LangChain Skills** — 11 skills oficiais extras (apenas para `ai-agents`)
-
-## Fluxo de trabalho
+maestro-bundle solves this by installing **4 layers of context** that work together:
 
 ```
 ┌─────────────────────────────────────────────────────────┐
-│  1. Dev instala o bundle                                │
-│     npx maestro-bundle ai-agents claude                 │
 │                                                         │
-│  2. Analista/dev preenche o PRD.md                      │
-│     (requisitos, user stories, API spec)                │
+│  PRD.md              WHAT to build                      │
+│  (requirements)      User stories, API spec, data       │
+│                      model, acceptance criteria         │
+│                                                         │
+├─────────────────────────────────────────────────────────┤
 │                                                         │
-│  3. Dev abre o editor e pede uma feature                │
-│     "Cria o endpoint de demands"                        │
+│  AGENTS.md           HOW to build                       │
+│  (standards)         Stack, architecture, conventions,  │
+│                      project structure, git flow        │
 │                                                         │
-│  4. Agente PARA e inicia o fluxo SDD:                   │
-│     /speckit.specify → spec.md                          │
-│     /speckit.plan    → plan.md                          │
-│     /speckit.tasks   → tasks.md                         │
-│     /speckit.implement → código                         │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│  Skills              WITH WHAT to build                 │
+│  (capabilities)      RAG pipeline, clean architecture,  │
+│                      deploy, testing, etc.              │
+│                                                         │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│  Spec Kit (SDD)      IN WHAT ORDER to build             │
+│  (process)           /speckit.specify → plan → tasks    │
+│                      → implement                        │
 │                                                         │
-│  5. Código é produzido seguindo:                        │
-│     - A spec (O QUE construir)                          │
-│     - O AGENTS.md (COMO construir)                      │
-│     - As skills (capacidades específicas)               │
-│     - O PRD.md (requisitos do produto)                  │
 └─────────────────────────────────────────────────────────┘
 ```
 
-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.
+Each layer gives the agent a different type of context. Together, they make the agent work like a senior dev who knows the project, follows the standards, and plans before coding.
+
+## What it installs
+
+```bash
+npx maestro-bundle ai-agents claude
+```
+
+| What | Purpose | Who fills it |
+|---|---|---|
+| **AGENTS.md** | Standards, stack, conventions | Bundle (automatic) |
+| **Skills** | Specific capabilities (RAG, clean arch, tests...) | Bundle (automatic) |
+| **PRD.md** | Product requirements, user stories, API spec | Analyst / Dev |
+| **Spec Kit** | SDD process — spec → plan → tasks → implement | Agent + Dev |
+| **Constitution** | Non-negotiable project principles | Bundle (automatic) |
+| **LangChain Skills** | 11 official LangChain skills (AI bundles) | Bundle (automatic) |
 
-## Arquivos do projeto: quem faz o quê
+The dev only needs to fill in `PRD.md`. Everything else comes ready.
 
-| Arquivo | Quem escreve | Quando | Para quê |
-|---|---|---|---|
-| **AGENTS.md** | Bundle (automático) | Na instalação | Define COMO o agente trabalha (stack, padrões, convenções) |
-| **PRD.md** | Analista / Dev | Antes de codar | Define O QUE construir (user stories, API spec, modelo de dados) |
-| **`.specify/specs/*/spec.md`** | Agente via `/speckit.specify` | Antes de cada feature | Especificação detalhada da feature |
-| **`.specify/specs/*/plan.md`** | Agente via `/speckit.plan` | Após spec | Plano técnico (arquitetura, decisões) |
-| **`.specify/specs/*/tasks.md`** | Agente via `/speckit.tasks` | Após plan | Tasks atômicas implementáveis |
-| **skills/** | Bundle (automático) | Na instalação | Capacidades que o agente carrega sob demanda |
+## How it works in practice
 
-## Commands do Spec Kit disponíveis no editor
+```
+1. Dev installs the bundle
+   $ npx maestro-bundle ai-agents claude
 
-Após instalar o bundle, estes commands funcionam direto no editor:
+2. Analyst/dev fills PRD.md with requirements
 
-| Command | Fase | O que faz |
-|---|---|---|
-| `/speckit.constitution` | Setup | Definir princípios e padrões do projeto |
-| `/speckit.specify` | Spec | Especificar O QUE construir e POR QUÊ |
-| `/speckit.plan` | Plan | Planejar arquitetura, stack, decisões técnicas |
-| `/speckit.tasks` | Tasks | Quebrar em tasks atômicas implementáveis |
-| `/speckit.implement` | Build | Executar todas as tasks seguindo o plano |
-| `/speckit.clarify` | (opcional) | Perguntas para desambiguar requisitos |
-| `/speckit.analyze` | (opcional) | Verificar consistência entre artefatos |
-| `/speckit.checklist` | (opcional) | Gerar checklists de qualidade |
-
-## Editores suportados
-
-| Editor | Comando | O que instala |
-|---|---|---|
-| **Claude Code** | `npx maestro-bundle <bundle> claude` | `CLAUDE.md` + `.claude/skills/` + `.claude/commands/speckit.*` |
-| **Cursor** | `npx maestro-bundle <bundle> cursor` | `AGENTS.md` + `.cursor/skills/` + `.cursor/commands/speckit.*` |
-| **OpenAI Codex** | `npx maestro-bundle <bundle> codex` | `AGENTS.md` + `.agents/skills/speckit-*` |
-| **GitHub Copilot** | `npx maestro-bundle <bundle> copilot` | `.github/copilot-instructions.md` + `.github/instructions/` |
-| **Windsurf** | `npx maestro-bundle <bundle> windsurf` | `.windsurfrules` |
-| **Todos** | `npx maestro-bundle <bundle> all` | Tudo acima no mesmo repo |
+3. Dev opens the editor and requests a feature:
+   "Create the JWT authentication endpoint"
 
-## Bundles disponíveis
+4. The agent already knows:
+   - The requirements (PRD.md)
+   - The stack and standards (AGENTS.md)
+   - How to do JWT (authentication skill)
+   - That it needs to create a spec before coding (Spec Kit)
+
+5. Result: governed, consistent, planned code
+```
+
+## Available bundles
+
+| Bundle | Project type | Stack |
+|---|---|---|
+| `ai-agents` | Multi-agent AI systems | Python, LangChain, LangGraph, FastAPI, pgvector |
+| `ai-agents-deep` | Deep Agent (Claude Code-like) | Python, Deep Agents SDK, LangGraph, Subagents |
+| `jhipster-monorepo` | JHipster monolithic app | Java 21, Spring Boot, Angular, PostgreSQL |
+| `jhipster-microservices` | JHipster microservices | Java 21, Spring Boot, Kafka, Consul, K8s |
+| `data-pipeline` | Data & ML pipeline | Python, Pandas, Scikit-learn, MLflow |
+| `frontend-spa` | Frontend SPA | React, TypeScript, Tailwind, Vite |
 
 ```bash
-npx maestro-bundle ai-agents claude              # Python + LangChain + LangGraph + FastAPI
-npx maestro-bundle jhipster-monorepo cursor       # Java 21 + Spring Boot + Angular
-npx maestro-bundle jhipster-microservices codex   # Java 21 + Spring Boot + Kafka + K8s
-npx maestro-bundle data-pipeline copilot          # Python + Pandas + Scikit-learn + MLflow
-npx maestro-bundle frontend-spa windsurf          # React + TypeScript + Tailwind + Vite
+npx maestro-bundle ai-agents claude
+npx maestro-bundle ai-agents-deep cursor
+npx maestro-bundle jhipster-monorepo claude
+npx maestro-bundle jhipster-microservices codex
+npx maestro-bundle data-pipeline copilot
+npx maestro-bundle frontend-spa windsurf
 ```
 
-## O que acontece
+## Supported editors
+
+| Editor | Command | Where it installs |
+|---|---|---|
+| **Claude Code** | `npx maestro-bundle <bundle> claude` | `CLAUDE.md` + `.claude/skills/` |
+| **Cursor** | `npx maestro-bundle <bundle> cursor` | `AGENTS.md` + `.cursor/skills/` |
+| **OpenAI Codex** | `npx maestro-bundle <bundle> codex` | `AGENTS.md` + `.agents/skills/` |
+| **GitHub Copilot** | `npx maestro-bundle <bundle> copilot` | `.github/copilot-instructions.md` |
+| **Windsurf** | `npx maestro-bundle <bundle> windsurf` | `.windsurfrules` |
+| **All** | `npx maestro-bundle <bundle> all` | All of the above in the same repo |
+
+## What happens when you install
 
 ```
 $ npx maestro-bundle ai-agents claude
 
-  Bundle:  Sistema Multi-Agente com AI
+  Bundle:  Multi-Agent AI System
   Editor:  Claude Code
 
-  ✔ Claude Code: AGENTS.md, CLAUDE.md → @AGENTS.md, 14 skills em .claude/skills/
-  ✔ PRD.md template instalado (preencha com os requisitos do produto)
-  ✔ 11 LangChain Skills instaladas
-  ✔ 14 skills canônicas em skills/
-  ✔ references/ pronto
-  ✔ specify-cli v0.4.3 instalado
-  ✔ Spec Kit inicializado (/speckit.* commands disponíveis)
-  ✔ Constitution do bundle integrado ao Spec Kit
-
-  Pronto!
-
-  Comandos SDD disponíveis no editor:
-    /speckit.constitution  — Definir princípios do projeto
-    /speckit.specify       — Especificar O QUE e POR QUÊ
-    /speckit.plan          — Planejar arquitetura e stack
-    /speckit.tasks         — Quebrar em tasks atômicas
-    /speckit.implement     — Executar as tasks
-
-  Próximo passo:
-    1. Preencha o PRD.md com os requisitos do produto
-    2. Abra o projeto no editor AI
-    3. Use /speckit.specify para começar a primeira feature
+  ✔ Claude Code: AGENTS.md, CLAUDE.md, 14 skills in .claude/skills/
+  ✔ PRD.md template installed
+  ✔ 11 LangChain Skills installed
+  ✔ specify-cli v0.4.3 installed
+  ✔ Spec Kit initialized (/speckit.* commands available)
+  ✔ Bundle constitution integrated
+
+  Done!
+
+  Next steps:
+    1. Fill in PRD.md with your product requirements
+    2. Open the project in your AI editor
+    3. Use /speckit.specify to start your first feature
 ```
 
-## Estrutura instalada
+## Project structure
 
-### Claude Code
 ```
-seu-projeto/
-├── CLAUDE.md                                  # @AGENTS.md
-├── AGENTS.md                                  # COMO o agente trabalha
-├── PRD.md                                     # O QUE construir (preencher!)
+your-project/
+├── CLAUDE.md                    # Points to AGENTS.md
+├── AGENTS.md                    # Stack, standards, conventions (automatic)
+├── PRD.md                       # Product requirements (fill this in!)
 ├── .claude/
-│   ├── skills/                                # Skills do bundle
-│   │   ├── rag-pipeline/SKILL.md
-│   │   ├── clean-architecture/SKILL.md
+│   ├── skills/                  # Agent capabilities
+│   │   ├── rag-pipeline/
+│   │   ├── clean-architecture/
+│   │   ├── testing-strategy/
 │   │   └── ...
-│   └── commands/                              # /speckit.* (gerado pelo Spec Kit)
+│   └── commands/                # Spec Kit commands
 │       ├── speckit.specify.md
 │       ├── speckit.plan.md
 │       ├── speckit.tasks.md
 │       └── speckit.implement.md
-├── .specify/                                  # Spec Kit
-│   ├── memory/constitution.md                 # Princípios do projeto
-│   ├── scripts/                               # Scripts auxiliares
-│   ├── templates/                             # Templates para spec, plan, tasks
-│   └── specs/                                 # Specs das features (criadas via /speckit.specify)
+├── .specify/                    # Feature specs, plans, tasks
+│   ├── memory/constitution.md
+│   ├── templates/
+│   └── specs/
 │       └── 001-feature-name/
 │           ├── spec.md
 │           ├── plan.md
 │           └── tasks.md
-├── skills/                                    # Skills canônicas (Deep Agents)
-└── references/                                # Docs de referência
+├── skills/                      # Canonical skills (Deep Agents)
+└── references/                  # Reference docs
 ```
 
-### Cursor
-```
-seu-projeto/
-├── AGENTS.md                                  # COMO o agente trabalha
-├── PRD.md                                     # O QUE construir (preencher!)
-├── .cursor/
-│   ├── skills/                                # Skills do bundle
-│   └── commands/                              # /speckit.* commands
-├── .specify/                                  # Spec Kit (specs, plans, tasks)
-├── skills/                                    # Skills canônicas
-└── references/
-```
+## SDD process with Spec Kit
 
-### OpenAI Codex
-```
-seu-projeto/
-├── AGENTS.md                                  # COMO o agente trabalha
-├── PRD.md                                     # O QUE construir (preencher!)
-├── .agents/skills/                            # speckit-* skills
-├── .specify/                                  # Spec Kit
-├── skills/                                    # Skills canônicas
-└── references/
-```
+The bundle installs [GitHub Spec Kit](https://github.com/github/spec-kit) which adds commands to your editor for Specification-Driven Development:
 
-## Skills extras do LangChain (bundle ai-agents)
+| Command | What it does |
+|---|---|
+| `/speckit.specify` | Specify WHAT to build and WHY |
+| `/speckit.plan` | Plan architecture and technical decisions |
+| `/speckit.tasks` | Break down into atomic tasks |
+| `/speckit.implement` | Execute tasks following the plan |
 
-O bundle `ai-agents` instala automaticamente as 11 skills oficiais do [LangChain](https://github.com/langchain-ai/langchain-skills):
+The agent is instructed to follow this flow for new features. Simple bug fixes can go directly.
 
-| Skill | O que faz |
-|---|---|
-| `framework-selection` | Escolher entre LangChain, LangGraph ou Deep Agents |
-| `langchain-fundamentals` | Criar agentes com `create_agent`, tools, middleware |
-| `langchain-middleware` | Human-in-the-loop, custom middleware, output estruturado |
-| `langchain-rag` | RAG: document loaders, embeddings, vector stores |
-| `langchain-dependencies` | Pacotes, versões, instalação |
-| `langgraph-fundamentals` | StateGraph, nodes, edges, streaming |
-| `langgraph-persistence` | Checkpointers, Store, time travel |
-| `langgraph-human-in-the-loop` | Interrupts, aprovação humana, resume |
-| `deep-agents-core` | Criar Deep Agents, harness, SKILL.md format |
-| `deep-agents-memory` | Memória e persistência para Deep Agents |
-| `deep-agents-orchestration` | Subagentes, planning, HITL |
-
-## Pré-requisitos
-
-- **Node.js 18+** (para rodar o npx)
-- **Git** (para o specify init)
-- **uv** ou **pip** (para instalar o specify-cli — o bundle tenta instalar automaticamente)
-
-## Uso avançado
+## LangChain Skills (AI bundles)
 
-```bash
-# Instalar em diretório específico
-npx maestro-bundle jhipster-monorepo cursor ./meu-projeto
+The `ai-agents` and `ai-agents-deep` bundles automatically install the [11 official LangChain skills](https://github.com/langchain-ai/langchain-skills) covering LangChain, LangGraph, and Deep Agents.
 
-# Instalar para todos os editores (time usa editores diferentes)
-npx maestro-bundle ai-agents all
+## Prerequisites
 
-# Ver bundles e editores disponíveis
-npx maestro-bundle --help
-```
+- **Node.js 18+**
+- **Git**
+- **uv** or **pip** (for Spec Kit — installed automatically)
 
 ## Links
 
-- [AGENTS.md](https://agents.md/) — Padrão universal para instruções de agentes AI
+- [AGENTS.md](https://agents.md/) — Universal standard for AI agent instructions
 - [GitHub Spec Kit](https://github.com/github/spec-kit) — Specification-Driven Development
-- [LangChain Skills](https://github.com/langchain-ai/langchain-skills) — Skills oficiais LangChain
-- [Agent Skills](https://agentskills.io) — Padrão aberto para skills de agentes
+- [LangChain Skills](https://github.com/langchain-ai/langchain-skills) — Official LangChain skills
+- [Agent Skills](https://agentskills.io) — Open standard for agent skills

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "maestro-bundle",
-  "version": "1.8.0",
-  "description": "Instala bundles de governança para projetos com AI agents. Um comando, tudo configurado.",
+  "version": "2.0.0",
+  "description": "One command. Full context for your AI agent. Any editor. Install governance bundles with skills, PRD, AGENTS.md and GitHub Spec Kit.",
   "bin": {
     "maestro-bundle": "./src/cli.mjs"
   },