maestro-bundle 1.0.0

package/README.md

@@ -0,0 +1,91 @@
+# maestro-bundle
+
+Um comando. Bundle instalado. Agente governado.
+
+```bash
+npx maestro-bundle ai-agents
+```
+
+Instala automaticamente:
+- `AGENTS.md` na raiz (compatível com Cursor, Claude Code, Copilot, Windsurf, etc.)
+- `skills/` com todas as skills do bundle
+- `.spec/constitution.md` do GitHub Spec Kit
+- `references/` com docs de referência
+- Instala o GitHub Spec Kit se necessário
+
+## Bundles disponíveis
+
+```bash
+npx maestro-bundle ai-agents              # Python + LangChain + LangGraph + FastAPI
+npx maestro-bundle jhipster-monorepo       # Java 21 + Spring Boot + Angular + PostgreSQL
+npx maestro-bundle jhipster-microservices  # Java 21 + Spring Boot + Kafka + Consul + K8s
+npx maestro-bundle data-pipeline           # Python + Pandas + Scikit-learn + MLflow
+npx maestro-bundle frontend-spa            # React + TypeScript + Tailwind + Vite
+```
+
+## Uso
+
+```bash
+# Instalar no diretório atual
+npx maestro-bundle ai-agents
+
+# Instalar em outro diretório
+npx maestro-bundle jhipster-monorepo ./meu-projeto
+
+# Ver bundles disponíveis
+npx maestro-bundle --help
+```
+
+## O que acontece
+
+```
+$ npx maestro-bundle ai-agents
+
+  Instalando: Sistema Multi-Agente com AI
+  Destino:    /home/user/meu-projeto
+
+  ✔ Estrutura criada
+  ✔ AGENTS.md instalado na raiz
+  ✔ 14 skills instaladas
+  ✔ .spec/constitution.md instalado
+  ✔ References instalados
+  ✔ Spec Kit já disponível
+  ✔ Spec Kit inicializado
+
+  Pronto!
+
+  Arquivos instalados:
+    AGENTS.md                Comportamento do agente (qualquer editor AI)
+    .spec/constitution.md    Princípios do projeto (GitHub Spec Kit)
+    skills/ (14 skills)      Capacidades do agente
+    references/              Documentos de referência
+
+  Próximos passos:
+    1. Abra o projeto no seu editor AI (Cursor, Claude Code, Copilot, etc.)
+    2. O agente já conhece os padrões do projeto
+    3. Para nova demanda: /speckit.specify
+```
+
+## Resultado no projeto
+
+```
+seu-projeto/
+├── AGENTS.md                     # Lido por qualquer editor AI
+├── .spec/
+│   └── constitution.md           # Princípios (GitHub Spec Kit)
+├── skills/
+│   ├── commit-pattern/SKILL.md   # Do bundle-base
+│   ├── code-review/SKILL.md      # Do bundle-base
+│   ├── rag-pipeline/SKILL.md     # Do bundle escolhido
+│   ├── agent-orchestration/SKILL.md
+│   └── ...
+├── references/
+│   └── ...
+└── src/
+```
+
+## Compatibilidade
+
+O `AGENTS.md` segue o padrão [agents.md](https://agents.md/) e funciona com 30+ editores AI.
+
+O `.spec/` segue o padrão [GitHub Spec Kit](https://github.com/github/spec-kit) para SDD.

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "maestro-bundle",
+  "version": "1.0.0",
+  "description": "Instala bundles de governança para projetos com AI agents. Um comando, tudo configurado.",
+  "bin": {
+    "maestro-bundle": "./src/cli.mjs"
+  },
+  "type": "module",
+  "keywords": [
+    "ai",
+    "agents",
+    "governance",
+    "jhipster",
+    "langchain",
+    "spec-kit",
+    "sdd",
+    "agents-md"
+  ],
+  "author": "Maestro",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "ora": "^8.0.1"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, writeFileSync, cpSync, readdirSync, readFileSync } from "fs";
+import { join, resolve, dirname } from "path";
+import { execSync } from "child_process";
+import { fileURLToPath } from "url";
+import chalk from "chalk";
+import ora from "ora";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const BUNDLES = {
+  "ai-agents": {
+    name: "Sistema Multi-Agente com AI",
+    description: "Python + LangChain + LangGraph + FastAPI + pgvector",
+  },
+  "jhipster-monorepo": {
+    name: "JHipster Monorepo",
+    description: "Java 21 + Spring Boot + Angular + PostgreSQL + Liquibase",
+  },
+  "jhipster-microservices": {
+    name: "JHipster Microservices",
+    description: "Java 21 + Spring Boot + Angular + Kafka + Consul + K8s",
+  },
+  "data-pipeline": {
+    name: "Pipeline de Dados e ML",
+    description: "Python + Pandas + Scikit-learn + MLflow + Airflow",
+  },
+  "frontend-spa": {
+    name: "Frontend SPA",
+    description: "React + TypeScript + Tailwind + Vite",
+  },
+};
+
+function showHelp() {
+  console.log("");
+  console.log(chalk.bold("  maestro-bundle") + " — Instala bundles de governança para projetos com AI");
+  console.log("");
+  console.log(chalk.dim("  Uso:"));
+  console.log(`    npx maestro-bundle ${chalk.green("<bundle>")} ${chalk.dim("[diretório]")}`);
+  console.log("");
+  console.log(chalk.dim("  Bundles disponíveis:"));
+  console.log("");
+  for (const [key, info] of Object.entries(BUNDLES)) {
+    console.log(`    ${chalk.green(key.padEnd(26))} ${info.name}`);
+    console.log(`    ${"".padEnd(26)} ${chalk.dim(info.description)}`);
+    console.log("");
+  }
+  console.log(chalk.dim("  Exemplos:"));
+  console.log(`    npx maestro-bundle ai-agents`);
+  console.log(`    npx maestro-bundle jhipster-monorepo ./meu-projeto`);
+  console.log(`    npx maestro-bundle frontend-spa .`);
+  console.log("");
+}
+
+function countSkills(dir) {
+  if (!existsSync(dir)) return 0;
+  let count = 0;
+  for (const item of readdirSync(dir, { withFileTypes: true })) {
+    if (item.isDirectory()) {
+      const skillFile = join(dir, item.name, "SKILL.md");
+      if (existsSync(skillFile)) count++;
+    }
+  }
+  return count;
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+    showHelp();
+    process.exit(0);
+  }
+
+  const bundleName = args[0];
+  const targetDir = resolve(args[1] || ".");
+
+  if (!BUNDLES[bundleName]) {
+    console.error(chalk.red(`\n  Bundle "${bundleName}" não encontrado.\n`));
+    showHelp();
+    process.exit(1);
+  }
+
+  const info = BUNDLES[bundleName];
+  const templatesDir = join(__dirname, "..", "templates");
+  const baseDir = join(templatesDir, "bundle-base");
+  const bundleDir = join(templatesDir, `bundle-${bundleName}`);
+
+  if (!existsSync(bundleDir)) {
+    console.error(chalk.red(`\n  Templates do bundle "${bundleName}" não encontrados em ${bundleDir}\n`));
+    process.exit(1);
+  }
+
+  console.log("");
+  console.log(chalk.bold(`  Instalando: ${chalk.green(info.name)}`));
+  console.log(chalk.dim(`  Destino:    ${targetDir}`));
+  console.log("");
+
+  // 1. Criar diretórios
+  let spinner = ora("Criando estrutura").start();
+  for (const dir of ["skills", ".spec", "references"]) {
+    mkdirSync(join(targetDir, dir), { recursive: true });
+  }
+  spinner.succeed("Estrutura criada");
+
+  // 2. AGENTS.md (base + bundle concatenados)
+  spinner = ora("Instalando AGENTS.md").start();
+  let agentsMd = "";
+  const baseAgentsPath = join(baseDir, "AGENTS.md");
+  const bundleAgentsPath = join(bundleDir, "AGENTS.md");
+
+  if (existsSync(baseAgentsPath)) {
+    agentsMd += readFileSync(baseAgentsPath, "utf-8");
+  }
+  if (existsSync(bundleAgentsPath)) {
+    agentsMd += "\n\n---\n\n";
+    agentsMd += readFileSync(bundleAgentsPath, "utf-8");
+  }
+  writeFileSync(join(targetDir, "AGENTS.md"), agentsMd);
+  spinner.succeed("AGENTS.md instalado na raiz");
+
+  // 3. Skills (base + bundle)
+  spinner = ora("Instalando skills").start();
+  const skillsDir = join(targetDir, "skills");
+  if (existsSync(join(baseDir, "skills"))) {
+    cpSync(join(baseDir, "skills"), skillsDir, { recursive: true });
+  }
+  if (existsSync(join(bundleDir, "skills"))) {
+    cpSync(join(bundleDir, "skills"), skillsDir, { recursive: true });
+  }
+  const skillCount = countSkills(skillsDir);
+  spinner.succeed(`${skillCount} skills instaladas`);
+
+  // 4. .spec/constitution.md
+  spinner = ora("Instalando constitution (Spec Kit)").start();
+  if (existsSync(join(bundleDir, ".spec"))) {
+    cpSync(join(bundleDir, ".spec"), join(targetDir, ".spec"), { recursive: true });
+  }
+  spinner.succeed(".spec/constitution.md instalado");
+
+  // 5. References
+  spinner = ora("Instalando references").start();
+  if (existsSync(join(bundleDir, "references"))) {
+    cpSync(join(bundleDir, "references"), join(targetDir, "references"), { recursive: true });
+  }
+  spinner.succeed("References instalados");
+
+  // 6. GitHub Spec Kit
+  spinner = ora("Verificando GitHub Spec Kit").start();
+  let specKitInstalled = false;
+  try {
+    execSync("specify --version", { stdio: "ignore" });
+    specKitInstalled = true;
+    spinner.succeed("Spec Kit já disponível");
+  } catch {
+    spinner.info("Spec Kit não encontrado");
+    spinner = ora("Instalando GitHub Spec Kit...").start();
+    try {
+      execSync(
+        "uv tool install specify-cli --from git+https://github.com/github/spec-kit.git",
+        { stdio: "ignore", timeout: 120000 }
+      );
+      specKitInstalled = true;
+      spinner.succeed("Spec Kit instalado");
+    } catch {
+      try {
+        execSync(
+          "pip install specify-cli",
+          { stdio: "ignore", timeout: 60000 }
+        );
+        specKitInstalled = true;
+        spinner.succeed("Spec Kit instalado via pip");
+      } catch {
+        spinner.warn("Instale o Spec Kit manualmente:");
+        console.log(chalk.dim("    uv tool install specify-cli --from git+https://github.com/github/spec-kit.git"));
+      }
+    }
+  }
+
+  // 7. Inicializar Spec Kit
+  if (specKitInstalled) {
+    spinner = ora("Inicializando Spec Kit").start();
+    try {
+      execSync(`specify init "${targetDir}"`, { stdio: "ignore", timeout: 15000, cwd: targetDir });
+      spinner.succeed("Spec Kit inicializado");
+    } catch {
+      spinner.info("Execute 'specify init .' no diretório do projeto");
+    }
+  }
+
+  // Done
+  console.log("");
+  console.log(chalk.green.bold("  Pronto!"));
+  console.log("");
+  console.log("  Arquivos instalados:");
+  console.log(`    ${chalk.cyan("AGENTS.md")}                Comportamento do agente (qualquer editor AI)`);
+  console.log(`    ${chalk.cyan(".spec/constitution.md")}     Princípios do projeto (GitHub Spec Kit)`);
+  console.log(`    ${chalk.cyan(`skills/ (${skillCount} skills)`)}       Capacidades do agente`);
+  console.log(`    ${chalk.cyan("references/")}              Documentos de referência`);
+  console.log("");
+  console.log("  Próximos passos:");
+  console.log(`    1. Abra o projeto no seu editor AI ${chalk.dim("(Cursor, Claude Code, Copilot, etc.)")}`);
+  console.log("    2. O agente já conhece os padrões do projeto");
+  console.log(`    3. Para nova demanda: ${chalk.cyan("/speckit.specify")}`);
+  console.log("");
+}
+
+main().catch((err) => {
+  console.error(chalk.red(`\n  Erro: ${err.message}\n`));
+  process.exit(1);
+});

package/templates/bundle-ai-agents/.spec/constitution.md

@@ -0,0 +1,33 @@
+# Constitution — Projeto de Agentes AI
+
+## Princípios
+
+1. **Spec primeiro, código depois** — Toda demanda passa pelo fluxo SDD antes de implementação
+2. **Agente governado** — Todo agente segue seu AGENTS.md e skills, sem "vibing coding"
+3. **Observável** — Toda execução de agente é rastreada no Langfuse
+4. **Avaliável** — Todo agente tem evals com golden dataset antes de ir para produção
+5. **Context-aware** — Gerenciar janela de contexto com as 4 estratégias (Write, Select, Compress, Isolate)
+
+## Padrões de desenvolvimento
+
+- Clean Architecture para separar domínio de infraestrutura
+- Entidades ricas com comportamento (não anêmicas)
+- Value Objects para validação
+- Testes: >= 80% cobertura, evals para agentes
+- Python 3.11+, type hints, Black + Ruff
+
+## Padrões de agentes
+
+- System prompts versionados, nunca hardcoded
+- Tools com schemas Pydantic
+- Human-in-the-loop para operações destrutivas
+- Timeout e limite de iterações em loops
+- Memória de longo prazo via LangGraph Store
+
+## Padrões de qualidade
+
+- Code review obrigatório
+- Commits seguem Conventional Commits
+- Branches seguem estratégia feature/fix/hotfix
+- Nunca commitar secrets
+- Rate limiting em todas as APIs

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

@@ -0,0 +1,140 @@
+# Projeto: Sistema Multi-Agente com AI
+
+Você está construindo um sistema de agentes AI com orquestração, RAG e execução autônoma de tarefas. O backend é Python com FastAPI, a orquestração usa LangChain + LangGraph, e a infra roda em containers.
+
+## Specification-Driven Development (SDD)
+
+Este projeto usa **GitHub Spec Kit** para governança. Antes de implementar qualquer demanda:
+
+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.
+
+## References
+
+Documentos de referência que o agente deve consultar quando necessário:
+
+- `references/fastapi-patterns.md` — Padrões de endpoints FastAPI
+- `references/langgraph-patterns.md` — Padrões de grafos LangGraph
+- `references/rag-best-practices.md` — Melhores práticas de RAG
+- `references/eval-framework.md` — Framework de avaliação de agentes
+
+## Stack do projeto
+
+- **Linguagem:** Python 3.11+
+- **Agentes:** LangChain + LangGraph + Deep Agents
+- **API:** FastAPI
+- **Banco:** PostgreSQL (relacional + pgvector para RAG)
+- **Cache/Filas:** Redis Streams
+- **Embeddings:** text-embedding-3-large ou multilingual-e5-large
+- **Observabilidade:** Langfuse (self-hosted)
+- **Containers:** Docker + K3s
+- **Testes:** Pytest + evals customizados
+
+## Estrutura do projeto
+
+```
+src/
+├── agents/                     # Definição dos agentes
+│   ├── orchestrator/
+│   │   ├── agent.py            # Deep Agent orquestrador
+│   │   ├── state.py            # AgentState do LangGraph
+│   │   ├── nodes.py            # Nós do grafo
+│   │   ├── tools.py            # Tools do agente
+│   │   └── prompts.py          # System prompts versionados
+│   ├── frontend_agent/
+│   ├── backend_agent/
+│   └── devops_agent/
+├── domain/                     # Clean Architecture — regras de negócio
+│   ├── entities/
+│   ├── value_objects/
+│   ├── events/
+│   ├── services/
+│   └── repositories/           # Interfaces (ports)
+├── application/                # Use cases
+│   ├── use_cases/
+│   ├── dtos/
+│   └── mappers/
+├── infrastructure/             # Implementações (adapters)
+│   ├── persistence/
+│   ├── mcp/
+│   ├── langfuse/
+│   └── config/
+├── rag/                        # Pipeline de RAG
+│   ├── ingest.py
+│   ├── retriever.py
+│   ├── embeddings.py
+│   └── reranker.py
+├── api/                        # Endpoints REST + WebSocket
+│   ├── controllers/
+│   └── middlewares/
+├── evals/                      # Avaliação dos agentes
+│   ├── golden_dataset.json
+│   ├── evaluators.py
+│   ├── run_evals.py
+│   └── judges.py
+└── memory/                     # Memória longo prazo
+    ├── store.py
+    └── checkpointer.py
+```
+
+## Padrões de código
+
+- Máximo 500 linhas por arquivo, 20 linhas por função
+- Type hints em funções públicas
+- f-strings para interpolação
+- Black + Ruff para formatação
+- Nomes descritivos, sem abreviações
+- Guard clauses em vez de ifs aninhados
+- Tratar exceções com tipos específicos, nunca `except Exception` vazio
+
+## Padrões de agentes
+
+- Cada agente tem UMA responsabilidade
+- System prompts versionados em `prompts.py`, nunca hardcoded
+- Tools com nomes claros, descrições precisas e schemas Pydantic
+- Timeout e limite de iterações em todo loop
+- Human-in-the-loop para: merge, deploy, delete, operações destrutivas
+- Traces no Langfuse para toda execução
+- Eval com golden dataset antes de deploy
+
+## Context Engineering
+
+- **Write:** Este CLAUDE.md + skills por contexto
+- **Select:** RAG para injetar contexto relevante ao agente
+- **Compress:** Summarization de código longo antes de enviar
+- **Isolate:** Cada agente com contexto isolado (worktree + janela separada)
+
+## RAG
+
+- RecursiveCharacterTextSplitter (chunk 1000, overlap 200)
+- Metadados obrigatórios: source, doc_type, language, created_at
+- Hybrid search: pgvector + ts_vector + RRF
+- Re-ranking com cross-encoder no top-k
+- Testar retrieval quality antes de ir para produção
+
+## Git
+
+- Commits: `feat(agents): adicionar roteamento condicional`
+- Branches: `feature/<modulo>-<descricao>`
+- Nunca commitar secrets, .env, API keys
+- Worktrees isoladas por agente quando em execução paralela
+
+## Testes
+
+- Unitários: Value Objects, Entities, regras de domínio (>= 90%)
+- Integração: Repositórios, APIs (>= 70%)
+- Evals: Golden dataset + LLM-as-judge + rule-based (>= 80% score)
+- Nome: `test_should_<resultado>_when_<condição>`
+
+## Segurança
+
+- Rate limiting em todas as APIs
+- Guardrails contra prompt injection nos inputs
+- JWT para autenticação, API keys para agentes
+- HTTPS obrigatório
+- Validar inputs nas fronteiras do sistema

package/templates/bundle-ai-agents/skills/agent-orchestration/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: agent-orchestration
+description: Criar sistemas multi-agente com LangGraph incluindo orquestrador, subagentes, roteamento e delegação. Use quando precisar coordenar múltiplos agentes, criar times de agentes, ou implementar orquestração com LangGraph.
+---
+
+# Orquestração de Agentes
+
+## Arquitetura Multi-Agente
+
+```
+Orquestrador (LangGraph StateGraph)
+├── Router Node → decide qual agente executar
+├── Agent Frontend → executa tasks de frontend
+├── Agent Backend → executa tasks de backend
+├── Agent DevOps → executa tasks de infra
+├── Validator Node → valida compliance com bundle
+├── Human Review → interrupt para aprovação
+└── Merger Node → mergea branches dos agentes
+```
+
+## AgentState
+
+```python
+from typing import TypedDict, Annotated, Literal
+from langgraph.graph.message import add_messages
+
+class OrchestratorState(TypedDict):
+    messages: Annotated[list, add_messages]
+    demand: dict
+    task_plan: list[dict]
+    current_task_index: int
+    assigned_agents: dict[str, str]  # task_id -> agent_type
+    branch_status: dict[str, str]    # agent -> branch_name
+    compliance_results: list[dict]
+    needs_human_review: bool
+    final_status: str
+```
+
+## Grafo do Orquestrador
+
+```python
+from langgraph.graph import StateGraph, START, END
+
+graph = StateGraph(OrchestratorState)
+
+# Nós
+graph.add_node("analyze_demand", analyze_demand_node)
+graph.add_node("plan_tasks", plan_tasks_node)
+graph.add_node("route_to_agent", route_to_agent_node)
+graph.add_node("execute_agent", execute_agent_node)
+graph.add_node("validate_compliance", validate_compliance_node)
+graph.add_node("human_review", human_review_node)
+graph.add_node("merge_work", merge_work_node)
+
+# Edges
+graph.add_edge(START, "analyze_demand")
+graph.add_edge("analyze_demand", "plan_tasks")
+graph.add_edge("plan_tasks", "route_to_agent")
+graph.add_conditional_edges("route_to_agent", should_continue, {
+    "execute": "execute_agent",
+    "all_done": "validate_compliance"
+})
+graph.add_edge("execute_agent", "route_to_agent")
+graph.add_conditional_edges("validate_compliance", needs_review, {
+    "review": "human_review",
+    "pass": "merge_work"
+})
+graph.add_edge("human_review", "merge_work")
+graph.add_edge("merge_work", END)
+
+app = graph.compile(checkpointer=PostgresSaver(conn))
+```
+
+## Delegação para subagentes
+
+```python
+async def execute_agent_node(state: OrchestratorState):
+    task = state["task_plan"][state["current_task_index"]]
+    agent_type = state["assigned_agents"][task["id"]]
+
+    # Cada agente tem seu próprio grafo/tools
+    agent = agent_registry.get(agent_type)
+    result = await agent.ainvoke({
+        "task": task,
+        "bundle": bundles[agent_type],
+        "worktree": worktrees[agent_type]
+    })
+
+    return {
+        "current_task_index": state["current_task_index"] + 1,
+        "branch_status": {
+            **state["branch_status"],
+            agent_type: result["branch_name"]
+        }
+    }
+```
+
+## Roteamento inteligente
+
+```python
+def route_to_agent(state: OrchestratorState) -> dict:
+    """Decide qual tipo de agente executar baseado na task"""
+    task = state["task_plan"][state["current_task_index"]]
+
+    routing_map = {
+        "frontend": ["ui", "componente", "tela", "react", "css"],
+        "backend": ["api", "endpoint", "banco", "service", "entity"],
+        "devops": ["deploy", "pipeline", "docker", "k8s", "ci"],
+    }
+
+    for agent_type, keywords in routing_map.items():
+        if any(kw in task["description"].lower() for kw in keywords):
+            return {"assigned_agents": {task["id"]: agent_type}}
+
+    # Fallback: usar LLM para decidir
+    return {"assigned_agents": {task["id"]: llm_route(task)}}
+```
+
+## Human-in-the-loop
+
+```python
+from langgraph.types import interrupt
+
+def human_review_node(state: OrchestratorState):
+    approval = interrupt({
+        "type": "merge_approval",
+        "branches": state["branch_status"],
+        "compliance": state["compliance_results"],
+        "message": "Aprovar merge dos branches?"
+    })
+    return {"needs_human_review": False, "final_status": approval["decision"]}
+```