maestro-bundle 1.5.0 → 1.7.0

package/README.md

@@ -1,29 +1,85 @@
 # maestro-bundle
 
-Um comando. Bundle instalado. Agente governado. [GitHub Spec Kit](https://github.com/github/spec-kit) configurado.
+Um comando. Bundle instalado. Agente governado. Zero vibing code.
 
 ```bash
 npx maestro-bundle ai-agents claude
 ```
 
-## O que faz
+## Filosofia: Sem spec, sem código
 
-1. Instala **AGENTS.md** + **skills** no formato correto do seu editor
-2. Cria **PRD.md** — template de requisitos para o analista/dev preencher
-3. Instala o [GitHub Spec Kit](https://github.com/github/spec-kit) (`specify-cli@v0.4.3`) no projeto
-4. Roda `specify init` que registra os commands `/speckit.*` no editor
-5. Integra o `constitution.md` do bundle com os princípios do projeto
+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).
 
-O dev abre o editor e já tem skills + `/speckit.specify` funcionando.
+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:
 
-## AGENTS.md vs PRD.md
+```
+/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?"
+
+## O que instala
+
+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
 
-| Arquivo | Quem escreve | O que contém | Para que serve |
+```
+┌─────────────────────────────────────────────────────────┐
+│  1. Dev instala o bundle                                │
+│     npx maestro-bundle ai-agents claude                 │
+│                                                         │
+│  2. Analista/dev preenche o PRD.md                      │
+│     (requisitos, user stories, API spec)                │
+│                                                         │
+│  3. Dev abre o editor e pede uma feature                │
+│     "Cria o endpoint de demands"                        │
+│                                                         │
+│  4. Agente PARA e inicia o fluxo SDD:                   │
+│     /speckit.specify → spec.md                          │
+│     /speckit.plan    → plan.md                          │
+│     /speckit.tasks   → tasks.md                         │
+│     /speckit.implement → código                         │
+│                                                         │
+│  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.
+
+## Arquivos do projeto: quem faz o quê
+
+| Arquivo | Quem escreve | Quando | Para quê |
 |---|---|---|---|
-| **AGENTS.md** | Bundle (automático) | Stack, padrões, estrutura, convenções | Define COMO o agente trabalha |
-| **PRD.md** | Analista / Dev | User stories, requisitos, API spec, modelo de dados | Define O QUE deve ser construído |
+| **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 |
+
+## Commands do Spec Kit disponíveis no editor
+
+Após instalar o bundle, estes commands funcionam direto no editor:
 
-O `AGENTS.md` vem pronto no bundle. O `PRD.md` vem como template — o dev/analista preenche com os requisitos do projeto antes de começar a codar. O agente AI usa ambos como contexto.
+| 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
 
@@ -55,6 +111,8 @@ $ npx maestro-bundle ai-agents claude
   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
@@ -71,92 +129,83 @@ $ npx maestro-bundle ai-agents claude
     /speckit.implement     — Executar as tasks
 
   Próximo passo:
-    Abra o projeto no editor AI e use /speckit.specify para começar
+    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
 ```
 
-## Estrutura instalada por editor
+## Estrutura instalada
 
 ### Claude Code
-
 ```
 seu-projeto/
-├── CLAUDE.md                                  # @AGENTS.md (aponta pro AGENTS.md)
-├── AGENTS.md                                  # Define COMO o agente trabalha
-├── PRD.md                                     # Define O QUE construir (preencher!)
+├── CLAUDE.md                                  # @AGENTS.md
+├── AGENTS.md                                  # COMO o agente trabalha
+├── PRD.md                                     # O QUE construir (preencher!)
 ├── .claude/
 │   ├── skills/                                # Skills do bundle
 │   │   ├── rag-pipeline/SKILL.md
 │   │   ├── clean-architecture/SKILL.md
-│   │   ├── commit-pattern/SKILL.md
 │   │   └── ...
-│   └── commands/                              # Commands do Spec Kit (gerado pelo specify init)
-│       ├── speckit.constitution.md
+│   └── commands/                              # /speckit.* (gerado pelo Spec Kit)
 │       ├── speckit.specify.md
 │       ├── speckit.plan.md
 │       ├── speckit.tasks.md
 │       └── speckit.implement.md
-├── .specify/                                  # Spec Kit (templates, scripts, constitution)
-│   ├── memory/constitution.md
-│   ├── scripts/
-│   └── templates/
-├── skills/                                    # Skills canônicas (para Deep Agents)
-└── references/
+├── .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)
+│       └── 001-feature-name/
+│           ├── spec.md
+│           ├── plan.md
+│           └── tasks.md
+├── skills/                                    # Skills canônicas (Deep Agents)
+└── references/                                # Docs de referência
 ```
 
 ### Cursor
-
 ```
 seu-projeto/
-├── AGENTS.md                                  # Define COMO o agente trabalha
-├── PRD.md                                     # Define O QUE construir (preencher!)
+├── AGENTS.md                                  # COMO o agente trabalha
+├── PRD.md                                     # O QUE construir (preencher!)
 ├── .cursor/
 │   ├── skills/                                # Skills do bundle
-│   │   ├── rag-pipeline/SKILL.md
-│   │   └── ...
-│   └── commands/                              # Commands do Spec Kit
-│       ├── speckit.specify.md
-│       └── ...
-├── .specify/
-├── skills/
+│   └── commands/                              # /speckit.* commands
+├── .specify/                                  # Spec Kit (specs, plans, tasks)
+├── skills/                                    # Skills canônicas
 └── references/
 ```
 
 ### OpenAI Codex
-
 ```
 seu-projeto/
-├── AGENTS.md                                  # Define COMO o agente trabalha
-├── PRD.md                                     # Define O QUE construir (preencher!)
-├── .agents/
-│   └── skills/                                # Commands do Spec Kit (como skills)
-│       ├── speckit-constitution/SKILL.md
-│       ├── speckit-specify/SKILL.md
-│       └── ...
-├── .specify/
+├── AGENTS.md                                  # COMO o agente trabalha
+├── PRD.md                                     # O QUE construir (preencher!)
+├── .agents/skills/                            # speckit-* skills
+├── .specify/                                  # Spec Kit
 ├── skills/                                    # Skills canônicas
 └── references/
 ```
 
-## GitHub Spec Kit — SDD no editor
+## Skills extras do LangChain (bundle ai-agents)
 
-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:
+O bundle `ai-agents` instala automaticamente as 11 skills oficiais do [LangChain](https://github.com/langchain-ai/langchain-skills):
 
-| Command | O que faz |
+| Skill | O que faz |
 |---|---|
-| `/speckit.constitution` | Definir princípios e padrões do projeto |
-| `/speckit.specify` | Especificar O QUE construir e POR QUÊ |
-| `/speckit.plan` | Planejar arquitetura, stack, decisões técnicas |
-| `/speckit.tasks` | Quebrar em tasks atômicas implementáveis |
-| `/speckit.implement` | Executar todas as tasks |
-| `/speckit.clarify` | Fazer perguntas para desambiguar requisitos |
-| `/speckit.analyze` | Verificar consistência entre artefatos |
-| `/speckit.checklist` | Gerar checklists de qualidade |
-
-O fluxo SDD garante que ninguém sai codando sem spec:
-
-```
-/speckit.specify → /speckit.plan → /speckit.tasks → /speckit.implement
-```
+| `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
 
@@ -181,4 +230,5 @@ npx maestro-bundle --help
 
 - [AGENTS.md](https://agents.md/) — Padrão universal para instruções de agentes AI
 - [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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-bundle",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "Instala bundles de governança para projetos com AI agents. Um comando, tudo configurado.",
   "bin": {
     "maestro-bundle": "./src/cli.mjs"

package/src/cli.mjs

@@ -321,7 +321,33 @@ async function main() {
   }
   spinner2.succeed(`${skills.length} skills canônicas em skills/`);
 
-  // 3. References
+  // 3. LangChain Skills (apenas para bundle ai-agents)
+  if (bundleName === "ai-agents") {
+    const spinnerLc = ora("Instalando LangChain Skills (langchain-ai/langchain-skills)").start();
+    try {
+      // Instalar todas as 11 skills do LangChain para o editor escolhido
+      const agentFlag = primaryEditor === "cursor" ? "cursor" : primaryEditor === "codex" ? "codex" : "claude-code";
+      execSync(
+        `npx skills add langchain-ai/langchain-skills --agent ${agentFlag} --skill "*" --yes`,
+        { stdio: "pipe", timeout: 120000, cwd: targetDir, shell: true }
+      );
+      spinnerLc.succeed("11 LangChain Skills instaladas (framework-selection, langchain-*, langgraph-*, deep-agents-*)");
+    } catch {
+      // Fallback: tentar sem --agent
+      try {
+        execSync(
+          `npx skills add langchain-ai/langchain-skills --skill "*" --yes`,
+          { stdio: "pipe", timeout: 120000, cwd: targetDir, shell: true }
+        );
+        spinnerLc.succeed("11 LangChain Skills instaladas");
+      } catch {
+        spinnerLc.warn("Instale manualmente as LangChain Skills:");
+        console.log(chalk.dim("    npx skills add langchain-ai/langchain-skills --skill '*' --yes"));
+      }
+    }
+  }
+
+  // 4. References
   const spinner3 = ora("Instalando references").start();
   const refsSrc = join(bundleDir, "references");
   ensureDir(join(targetDir, "references"));

package/templates/bundle-ai-agents/AGENTS.md

@@ -4,15 +4,12 @@ Você está construindo um sistema de agentes AI com orquestração, RAG e execu
 
 ## Specification-Driven Development (SDD)
 
-Este projeto usa **GitHub Spec Kit** para governança. Antes de implementar qualquer demanda:
+A regra fundamental de SDD está definida no bundle-base (AGENTS.md base) e é inegociável:
+**Sem spec, sem código. Sem exceção.** O agente deve recusar implementar qualquer demanda que
+não tenha passado pelo fluxo `/speckit.specify` → `/speckit.plan` → `/speckit.tasks` → `/speckit.implement`.
 
-1. Rodar `/speckit.constitution` — se `.spec/constitution.md` não existir
-2. Rodar `/speckit.specify` — descrever O QUE e POR QUÊ (não como)
-3. Rodar `/speckit.plan` — arquitetura e decisões técnicas
-4. Rodar `/speckit.tasks` — quebrar em tasks atômicas
-5. Rodar `/speckit.implement` — executar as tasks
-
-Nunca pular direto para código. Spec primeiro, código depois.
+Se o usuário pedir para codar algo sem spec, PARE e inicie o fluxo SDD primeiro.
+Consulte `.specify/specs/` para verificar se já existe spec para a demanda.
 
 ## Product Requirements Document
 

package/templates/bundle-base/AGENTS.md

@@ -2,9 +2,47 @@
 
 Este é o bundle base que TODOS os desenvolvedores devem usar. Ele define os padrões inegociáveis da organização.
 
+## REGRA FUNDAMENTAL: Specification-Driven Development (SDD)
+
+Este projeto usa **GitHub Spec Kit** para governança. Toda demanda — nova ou em andamento — DEVE seguir o fluxo SDD. Sem spec, sem código. Isso não é opcional.
+
+### Antes de escrever qualquer código:
+
+1. `/speckit.constitution` — Definir princípios (só na primeira vez do projeto)
+2. `/speckit.specify` — Descrever O QUE construir e POR QUÊ (nunca o como)
+3. `/speckit.plan` — Planejar arquitetura, stack e decisões técnicas
+4. `/speckit.tasks` — Quebrar em tasks atômicas implementáveis
+5. `/speckit.implement` — Executar as tasks seguindo o plano
+
+### Anti-vibing code
+
+Vibing code é quando alguém começa a codar sem spec, sem plano, sem tasks — só "vai fazendo". Isso é proibido neste projeto. Se o usuário pedir para implementar algo e não existir spec:
+
+1. **PARE**. Não escreva código.
+2. Informe que precisa criar a spec primeiro.
+3. Rode `/speckit.specify` para iniciar o processo.
+4. Só após ter spec → plan → tasks, comece a implementar.
+
+Se a demanda já está no meio (spec já existe), verifique:
+- `.specify/specs/` contém a spec da feature?
+- O plano existe em `plan.md`?
+- As tasks estão em `tasks.md`?
+
+Se sim, continue de onde parou. Se não, crie a spec antes de prosseguir.
+
+### Demanda nova vs demanda em andamento
+
+| Situação | O que fazer |
+|---|---|
+| Demanda nova, sem spec | `/speckit.specify` → `/speckit.plan` → `/speckit.tasks` → `/speckit.implement` |
+| Demanda com spec mas sem plano | `/speckit.plan` → `/speckit.tasks` → `/speckit.implement` |
+| Demanda com plano e tasks | `/speckit.implement` (continuar de onde parou) |
+| Bug fix simples | Pode corrigir direto, mas documentar no spec se afetar o plano |
+| Refactoring | Criar spec se afetar arquitetura; se for cosmético, pode fazer direto |
+
 ## Quem você é
 
-Você é um assistente de desenvolvimento que segue rigorosamente os padrões da organização. Todo código produzido deve aderir às convenções abaixo.
+Você é um assistente de desenvolvimento que segue rigorosamente os padrões da organização. Todo código produzido deve aderir às convenções abaixo. Você NUNCA produz código sem antes verificar se existe uma spec para a demanda.
 
 ## Padrões de Código
 

package/templates/bundle-data-pipeline/AGENTS.md

@@ -4,15 +4,12 @@ Você está construindo um pipeline de dados que inclui ingestão, processamento
 
 ## Specification-Driven Development (SDD)
 
-Este projeto usa **GitHub Spec Kit** para governança. Antes de implementar qualquer demanda:
+A regra fundamental de SDD está definida no bundle-base (AGENTS.md base) e é inegociável:
+**Sem spec, sem código. Sem exceção.** O agente deve recusar implementar qualquer demanda que
+não tenha passado pelo fluxo `/speckit.specify` → `/speckit.plan` → `/speckit.tasks` → `/speckit.implement`.
 
-1. Rodar `/speckit.constitution` — se `.spec/constitution.md` não existir
-2. Rodar `/speckit.specify` — descrever O QUE e POR QUÊ (não como)
-3. Rodar `/speckit.plan` — arquitetura e decisões técnicas
-4. Rodar `/speckit.tasks` — quebrar em tasks atômicas
-5. Rodar `/speckit.implement` — executar as tasks
-
-Nunca pular direto para código. Spec primeiro, código depois.
+Se o usuário pedir para codar algo sem spec, PARE e inicie o fluxo SDD primeiro.
+Consulte `.specify/specs/` para verificar se já existe spec para a demanda.
 
 ## Product Requirements Document
 

package/templates/bundle-frontend-spa/AGENTS.md

@@ -4,15 +4,12 @@ Você está construindo uma aplicação frontend moderna com React, TypeScript e
 
 ## Specification-Driven Development (SDD)
 
-Este projeto usa **GitHub Spec Kit** para governança. Antes de implementar qualquer demanda:
+A regra fundamental de SDD está definida no bundle-base (AGENTS.md base) e é inegociável:
+**Sem spec, sem código. Sem exceção.** O agente deve recusar implementar qualquer demanda que
+não tenha passado pelo fluxo `/speckit.specify` → `/speckit.plan` → `/speckit.tasks` → `/speckit.implement`.
 
-1. Rodar `/speckit.constitution` — se `.spec/constitution.md` não existir
-2. Rodar `/speckit.specify` — descrever O QUE e POR QUÊ (não como)
-3. Rodar `/speckit.plan` — arquitetura e decisões técnicas
-4. Rodar `/speckit.tasks` — quebrar em tasks atômicas
-5. Rodar `/speckit.implement` — executar as tasks
-
-Nunca pular direto para código. Spec primeiro, código depois.
+Se o usuário pedir para codar algo sem spec, PARE e inicie o fluxo SDD primeiro.
+Consulte `.specify/specs/` para verificar se já existe spec para a demanda.
 
 ## Product Requirements Document
 

package/templates/bundle-jhipster-microservices/AGENTS.md

@@ -4,15 +4,12 @@ Você está construindo uma arquitetura de microsserviços com JHipster. Múltip
 
 ## Specification-Driven Development (SDD)
 
-Este projeto usa **GitHub Spec Kit** para governança. Antes de implementar qualquer demanda:
+A regra fundamental de SDD está definida no bundle-base (AGENTS.md base) e é inegociável:
+**Sem spec, sem código. Sem exceção.** O agente deve recusar implementar qualquer demanda que
+não tenha passado pelo fluxo `/speckit.specify` → `/speckit.plan` → `/speckit.tasks` → `/speckit.implement`.
 
-1. Rodar `/speckit.constitution` — se `.spec/constitution.md` não existir
-2. Rodar `/speckit.specify` — descrever O QUE e POR QUÊ (não como)
-3. Rodar `/speckit.plan` — arquitetura e decisões técnicas
-4. Rodar `/speckit.tasks` — quebrar em tasks atômicas
-5. Rodar `/speckit.implement` — executar as tasks
-
-Nunca pular direto para código. Spec primeiro, código depois.
+Se o usuário pedir para codar algo sem spec, PARE e inicie o fluxo SDD primeiro.
+Consulte `.specify/specs/` para verificar se já existe spec para a demanda.
 
 ## Product Requirements Document
 

package/templates/bundle-jhipster-monorepo/AGENTS.md

@@ -4,15 +4,12 @@ Você está construindo uma aplicação monolítica com JHipster. Backend em Jav
 
 ## Specification-Driven Development (SDD)
 
-Este projeto usa **GitHub Spec Kit** para governança. Antes de implementar qualquer demanda:
+A regra fundamental de SDD está definida no bundle-base (AGENTS.md base) e é inegociável:
+**Sem spec, sem código. Sem exceção.** O agente deve recusar implementar qualquer demanda que
+não tenha passado pelo fluxo `/speckit.specify` → `/speckit.plan` → `/speckit.tasks` → `/speckit.implement`.
 
-1. Rodar `/speckit.constitution` — se `.spec/constitution.md` não existir
-2. Rodar `/speckit.specify` — descrever O QUE e POR QUÊ (não como)
-3. Rodar `/speckit.plan` — arquitetura e decisões técnicas
-4. Rodar `/speckit.tasks` — quebrar em tasks atômicas
-5. Rodar `/speckit.implement` — executar as tasks
-
-Nunca pular direto para código. Spec primeiro, código depois.
+Se o usuário pedir para codar algo sem spec, PARE e inicie o fluxo SDD primeiro.
+Consulte `.specify/specs/` para verificar se já existe spec para a demanda.
 
 ## Product Requirements Document