maestro-bundle 1.3.0 → 1.4.0

package/README.md

@@ -1,83 +1,171 @@
 # maestro-bundle
 
-Um comando. Bundle instalado. Agente governado. Funciona com **qualquer editor AI**.
+Um comando. Bundle instalado. Agente governado. [GitHub Spec Kit](https://github.com/github/spec-kit) configurado.
 
 ```bash
 npx maestro-bundle ai-agents claude
 ```
 
+## O que faz
+
+1. Instala **AGENTS.md** + **skills** no formato correto do seu editor
+2. Instala o [GitHub Spec Kit](https://github.com/github/spec-kit) (`specify-cli@v0.4.3`) no projeto
+3. Roda `specify init` que registra os commands `/speckit.*` no editor
+4. Integra o `constitution.md` do bundle com os princípios do projeto
+
+O dev abre o editor e já tem skills + `/speckit.specify` funcionando.
+
 ## Editores suportados
 
 | Editor | Comando | O que instala |
 |---|---|---|
-| **Claude Code** | `npx maestro-bundle <bundle> claude` | `CLAUDE.md` + `.claude/rules/` |
-| **Cursor** | `npx maestro-bundle <bundle> cursor` | `.cursorrules` + `.cursor/rules/` |
-| **OpenAI Codex** | `npx maestro-bundle <bundle> codex` | `AGENTS.md` |
+| **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 de uma vez |
+| **Todos** | `npx maestro-bundle <bundle> all` | Tudo acima no mesmo repo |
 
 ## Bundles disponíveis
 
 ```bash
-npx maestro-bundle ai-agents claude              # Agentes AI com LangChain
-npx maestro-bundle jhipster-monorepo cursor       # JHipster monolítico
-npx maestro-bundle jhipster-microservices all     # JHipster microsserviços
-npx maestro-bundle data-pipeline codex            # Pipeline dados/ML
-npx maestro-bundle frontend-spa copilot           # React SPA
+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
 ```
 
 ## O que acontece
 
 ```
-$ npx maestro-bundle ai-agents all
+$ npx maestro-bundle ai-agents claude
 
   Bundle:  Sistema Multi-Agente com AI
-  Editor:  Claude Code, Cursor, OpenAI Codex, GitHub Copilot, Windsurf
+  Editor:  Claude Code
 
-  ✔ Claude Code: CLAUDE.md + AGENTS.md, 14 rules em .claude/rules/
-  ✔ Cursor: .cursorrules, 14 rules em .cursor/rules/
-  ✔ OpenAI Codex: AGENTS.md
-  ✔ GitHub Copilot: .github/copilot-instructions.md, 14 rules em .github/instructions/
-  ✔ Windsurf: .windsurfrules
-  ✔ 14 skills canônicas
-  ✔ .spec/constitution.md (GitHub Spec Kit)
-  ✔ Spec Kit instalado
+  ✔ Claude Code: AGENTS.md, CLAUDE.md → @AGENTS.md, 14 skills em .claude/skills/
+  ✔ 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:
+    Abra o projeto no editor AI e use /speckit.specify para começar
+```
+
+## Estrutura instalada por editor
+
+### Claude Code
+
+```
+seu-projeto/
+├── CLAUDE.md                                  # @AGENTS.md (aponta pro AGENTS.md)
+├── AGENTS.md                                  # Instruções do bundle
+├── .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
+│       ├── 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/
+```
+
+### Cursor
+
+```
+seu-projeto/
+├── AGENTS.md                                  # Instruções (Cursor lê automaticamente)
+├── .cursor/
+│   ├── skills/                                # Skills do bundle
+│   │   ├── rag-pipeline/SKILL.md
+│   │   └── ...
+│   └── commands/                              # Commands do Spec Kit
+│       ├── speckit.specify.md
+│       └── ...
+├── .specify/
+├── skills/
+└── references/
 ```
 
-## Onde cada editor procura
+### OpenAI Codex
 
 ```
 seu-projeto/
-├── CLAUDE.md                              ← Claude Code
-├── AGENTS.md                              ← Codex, agents.md universal
-├── .cursorrules                           ← Cursor
-├── .windsurfrules                         ← Windsurf
-├── .claude/rules/*.md                     ← Claude Code (skills como rules)
-├── .cursor/rules/*.md                     ← Cursor (skills como rules)
-├── .github/copilot-instructions.md        ← Copilot
-├── .github/instructions/*.instructions.md ← Copilot (skills)
-├── .spec/constitution.md                  ← GitHub Spec Kit (SDD)
-├── skills/                                ← Canônicas (Deep Agents, referência)
-│   ├── rag-pipeline/SKILL.md
-│   ├── clean-architecture/SKILL.md
-│   └── ...
-└── references/                            ← Docs sob demanda
+├── AGENTS.md                                  # Instruções (Codex lê automaticamente)
+├── .agents/
+│   └── skills/                                # Commands do Spec Kit (como skills)
+│       ├── speckit-constitution/SKILL.md
+│       ├── speckit-specify/SKILL.md
+│       └── ...
+├── .specify/
+├── skills/                                    # Skills canônicas
+└── references/
 ```
 
+## GitHub Spec Kit — SDD no editor
+
+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:
+
+| Command | 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
+```
+
+## 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
 
 ```bash
 # Instalar em diretório específico
 npx maestro-bundle jhipster-monorepo cursor ./meu-projeto
 
+# Instalar para todos os editores (time usa editores diferentes)
+npx maestro-bundle ai-agents all
+
 # Ver bundles e editores disponíveis
 npx maestro-bundle --help
 ```
 
 ## Links
 
-- [AGENTS.md spec](https://agents.md/) — Padrão universal para instruções de agentes
-- [GitHub Spec Kit](https://github.com/github/spec-kit) — SDD (Specification-Driven Development)
+- [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
+- [Agent Skills](https://agentskills.io) — Padrão aberto para skills de agentes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-bundle",
-  "version": "1.3.0",
+  "version": "1.4.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

@@ -323,7 +323,7 @@ async function main() {
   // Mapear editor para flag --ai do specify
   const aiFlags = {
     claude: "claude",
-    cursor: "cursor",
+    cursor: "cursor-agent",
     codex: "codex",
     copilot: "copilot",
     windsurf: "windsurf",
@@ -370,10 +370,13 @@ async function main() {
     let specInitOk = false;
 
     // Precisa de "y" piped pois specify pede confirmação se dir não vazio
-    // Usar --script sh para evitar dependência de pwsh no Windows
+    // --script sh para evitar dependência de pwsh no Windows
+    // --ai-skills necessário para codex
+    const extraFlags = primaryEditor === "codex" ? " --ai-skills" : "";
     const initCmds = [
-      `echo y | specify init . --ai ${aiFlag} --script sh`,
-      `echo y | specify init . --ai ${aiFlag}`,
+      `echo y | specify init . --ai ${aiFlag}${extraFlags} --script sh --force`,
+      `echo y | specify init . --ai ${aiFlag}${extraFlags} --script sh`,
+      `echo y | specify init . --ai ${aiFlag}${extraFlags}`,
     ];
     for (const cmd of initCmds) {
       try {

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

@@ -1,24 +1,35 @@
 ---
 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.
+description: Build multi-agent systems with LangGraph including orchestrator, subagents, routing, and delegation. Use when coordinating multiple agents, creating agent teams, or implementing orchestration workflows.
+version: 1.0.0
+author: Maestro
 ---
 
-# Orquestração de Agentes
+# Agent Orchestration
 
-## Arquitetura Multi-Agente
+Design and implement multi-agent systems where an orchestrator coordinates specialized subagents through task planning, intelligent routing, compliance validation, and human-in-the-loop approval.
 
-```
-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
-```
+## When to Use
+- Coordinating multiple specialized agents (frontend, backend, devops)
+- Implementing task decomposition and delegation workflows
+- Building a LangGraph StateGraph with routing logic
+- Adding human-in-the-loop approval gates for destructive operations
+- Creating agent pipelines that validate compliance before merging work
+
+## Available Operations
+1. Define orchestrator state schema
+2. Build the orchestrator graph with nodes and edges
+3. Implement intelligent task routing
+4. Delegate tasks to specialized subagents
+5. Add compliance validation nodes
+6. Wire up human-in-the-loop interrupt gates
+7. Merge work from multiple agent branches
 
-## AgentState
+## Multi-Step Workflow
+
+### Step 1: Define the Orchestrator State
+
+Create a typed state schema that tracks the full lifecycle of a demand.
 
 ```python
 from typing import TypedDict, Annotated, Literal
@@ -36,14 +47,17 @@ class OrchestratorState(TypedDict):
     final_status: str
 ```
 
-## Grafo do Orquestrador
+### Step 2: Build the Graph Structure
+
+Wire up the orchestrator nodes and conditional edges.
 
 ```python
 from langgraph.graph import StateGraph, START, END
+from langgraph.checkpoint.postgres import PostgresSaver
 
 graph = StateGraph(OrchestratorState)
 
-# Nós
+# Add nodes
 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)
@@ -52,7 +66,7 @@ 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
+# Wire edges
 graph.add_edge(START, "analyze_demand")
 graph.add_edge("analyze_demand", "plan_tasks")
 graph.add_edge("plan_tasks", "route_to_agent")
@@ -71,14 +85,37 @@ graph.add_edge("merge_work", END)
 app = graph.compile(checkpointer=PostgresSaver(conn))
 ```
 
-## Delegação para subagentes
+### Step 3: Implement Intelligent Routing
+
+Route tasks to the right subagent based on keywords or LLM classification.
+
+```python
+def route_to_agent(state: OrchestratorState) -> dict:
+    task = state["task_plan"][state["current_task_index"]]
+
+    routing_map = {
+        "frontend": ["ui", "component", "screen", "react", "css"],
+        "backend": ["api", "endpoint", "database", "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: use LLM to decide
+    return {"assigned_agents": {task["id"]: llm_route(task)}}
+```
+
+### Step 4: Delegate to Subagents
+
+Each subagent has its own graph, tools, and worktree.
 
 ```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,
@@ -95,28 +132,9 @@ async def execute_agent_node(state: OrchestratorState):
     }
 ```
 
-## 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)}}
-```
+### Step 5: Add Human-in-the-Loop Approval
 
-## Human-in-the-loop
+Use LangGraph interrupts for merge approval gates.
 
 ```python
 from langgraph.types import interrupt
@@ -126,7 +144,55 @@ def human_review_node(state: OrchestratorState):
         "type": "merge_approval",
         "branches": state["branch_status"],
         "compliance": state["compliance_results"],
-        "message": "Aprovar merge dos branches?"
+        "message": "Approve merging branches?"
     })
     return {"needs_human_review": False, "final_status": approval["decision"]}
 ```
+
+### Step 6: Run and Test the Orchestrator
+
+```bash
+# Run the orchestrator with a test demand
+python -m orchestrator.run --demand "Create CRUD for demands with REST API and React UI"
+
+# Verify the graph structure
+python -c "from orchestrator.graph import app; app.get_graph().print_ascii()"
+```
+
+## Resources
+- `references/graph-patterns.md` - Common LangGraph graph patterns for orchestration
+- `references/routing-strategies.md` - Detailed routing strategies and fallback mechanisms
+
+## Examples
+
+### Example 1: Decompose and Execute a Full-Stack Demand
+User asks: "Set up an orchestrator that decomposes a demand into frontend and backend tasks and delegates them."
+Response approach:
+1. Define OrchestratorState with task_plan and assigned_agents
+2. Create analyze_demand node that uses LLM to break down the demand
+3. Create plan_tasks node that structures tasks with dependencies
+4. Implement keyword-based routing for frontend vs backend
+5. Wire up execute_agent to delegate each task to the right subagent
+6. Add compliance validation before merge
+
+### Example 2: Add a New Agent Type
+User asks: "Add a QA agent that runs tests after backend tasks complete."
+Response approach:
+1. Create a QA agent graph with test-running tools
+2. Register it in the agent_registry
+3. Add "qa" keywords to the routing map (e.g., "test", "quality", "coverage")
+4. Add a conditional edge from execute_agent to route QA tasks after backend
+
+### Example 3: Implement Parallel Agent Execution
+User asks: "Make frontend and backend agents run in parallel instead of sequentially."
+Response approach:
+1. Use LangGraph's `Send` API to fan out to multiple agents simultaneously
+2. Add a `join_results` node that waits for all parallel branches
+3. Wire conditional edges from join_results to validate_compliance
+
+## Notes
+- Always use a checkpointer (PostgresSaver) so the orchestrator can resume after failures
+- Each subagent should operate in its own git worktree to avoid conflicts
+- Compliance validation should run before any merge operation
+- Human review gates are mandatory for destructive operations (merges, deployments)
+- Use thread_id based on demand_id for consistent state across invocations

package/templates/bundle-ai-agents/skills/agent-orchestration/references/graph-patterns.md

@@ -0,0 +1,50 @@
+# Graph Patterns Reference
+
+## Common LangGraph Orchestration Patterns
+
+### 1. Sequential Pipeline
+```
+START -> analyze -> plan -> execute -> validate -> END
+```
+Best for: Simple workflows with no branching.
+
+### 2. Router Pattern
+```
+START -> analyze -> router --(frontend)--> agent_frontend -> merge
+                          \--(backend)---> agent_backend  -> merge
+                          \--(devops)----> agent_devops   -> merge
+```
+Best for: Task delegation to specialized agents.
+
+### 3. Loop with Exit Condition
+```
+START -> plan -> execute -> check_done --(more tasks)--> execute
+                                       \--(all done)---> validate -> END
+```
+Best for: Iterating through a task list.
+
+### 4. Fan-Out / Fan-In (Parallel)
+```python
+from langgraph.types import Send
+
+def fan_out(state):
+    return [Send("execute_agent", {"task": t}) for t in state["task_plan"]]
+```
+Best for: Independent tasks that can run concurrently.
+
+### 5. Human-in-the-Loop Gate
+```python
+from langgraph.types import interrupt
+
+def approval_gate(state):
+    result = interrupt({"message": "Approve?", "data": state["summary"]})
+    return {"approved": result["decision"] == "yes"}
+```
+Best for: Destructive operations requiring human approval.
+
+## State Design Principles
+
+- Use `Annotated[list, add_messages]` for message accumulation.
+- Use `dict[str, str]` for mappings that grow over time (branch_status, assigned_agents).
+- Keep state flat -- avoid deeply nested structures.
+- Include a `current_task_index` integer for loop-based task execution.

package/templates/bundle-ai-agents/skills/agent-orchestration/references/routing-strategies.md

@@ -0,0 +1,47 @@
+# Routing Strategies Reference
+
+## Strategy 1: Keyword-Based Routing
+
+Fast, deterministic, zero-cost. Use as primary router.
+
+```python
+routing_map = {
+    "frontend": ["ui", "component", "screen", "react", "css", "layout", "form"],
+    "backend": ["api", "endpoint", "database", "service", "entity", "migration"],
+    "devops": ["deploy", "pipeline", "docker", "k8s", "ci", "monitoring"],
+    "qa": ["test", "coverage", "quality", "e2e", "integration test"],
+}
+```
+
+## Strategy 2: LLM-Based Routing (Fallback)
+
+Use when keywords are ambiguous. Costs tokens but handles edge cases.
+
+```python
+async def llm_route(task: dict) -> str:
+    response = await llm.ainvoke(f"""
+    Classify this task into exactly one category: frontend, backend, devops, qa.
+    Task: {task['description']}
+    Respond with just the category name.
+    """)
+    return response.content.strip().lower()
+```
+
+## Strategy 3: Embedding Similarity
+
+Pre-embed descriptions for each agent type, route by cosine similarity.
+
+```python
+agent_descriptions = {
+    "frontend": "UI components, React, CSS, forms, layouts, user interactions",
+    "backend": "REST APIs, business logic, database operations, services",
+    "devops": "Docker, CI/CD, deployments, infrastructure, monitoring",
+}
+```
+
+## Fallback Chain
+
+1. Try keyword match first (fastest).
+2. If no match, try embedding similarity (medium cost).
+3. If confidence < 0.7, use LLM routing (highest cost, best accuracy).
+4. If LLM is uncertain, default to "backend" and flag for human review.