maestro-bundle 1.3.1 → 1.5.0

package/README.md

@@ -9,12 +9,22 @@ 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
+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 dev abre o editor e já tem skills + `/speckit.specify` funcionando.
 
+## AGENTS.md vs PRD.md
+
+| Arquivo | Quem escreve | O que contém | Para que serve |
+|---|---|---|---|
+| **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 |
+
+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.
+
 ## Editores suportados
 
 | Editor | Comando | O que instala |
@@ -71,7 +81,8 @@ $ npx maestro-bundle ai-agents claude
 ```
 seu-projeto/
 ├── CLAUDE.md                                  # @AGENTS.md (aponta pro AGENTS.md)
-├── AGENTS.md                                  # Instruções do bundle
+├── AGENTS.md                                  # Define COMO o agente trabalha
+├── PRD.md                                     # Define O QUE construir (preencher!)
 ├── .claude/
 │   ├── skills/                                # Skills do bundle
 │   │   ├── rag-pipeline/SKILL.md
@@ -96,7 +107,8 @@ seu-projeto/
 
 ```
 seu-projeto/
-├── AGENTS.md                                  # Instruções (Cursor lê automaticamente)
+├── AGENTS.md                                  # Define COMO o agente trabalha
+├── PRD.md                                     # Define O QUE construir (preencher!)
 ├── .cursor/
 │   ├── skills/                                # Skills do bundle
 │   │   ├── rag-pipeline/SKILL.md
@@ -113,7 +125,8 @@ seu-projeto/
 
 ```
 seu-projeto/
-├── AGENTS.md                                  # Instruções (Codex lê automaticamente)
+├── 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

package/package.json

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

@@ -301,7 +301,18 @@ async function main() {
     spinner.succeed(`${EDITORS[editorKey].name}: ${results.join(", ")}`);
   }
 
-  // 2. Skills canônicas (sempre, para Deep Agents e referência)
+  // 2. PRD template
+  const prdTemplate = join(bundleDir, "PRD_TEMPLATE.md");
+  if (existsSync(prdTemplate)) {
+    const prdDest = join(targetDir, "PRD.md");
+    if (!existsSync(prdDest)) {
+      cpSync(prdTemplate, prdDest);
+      const spinnerPrd = ora("PRD.md template instalado").start();
+      spinnerPrd.succeed("PRD.md template instalado (preencha com os requisitos do produto)");
+    }
+  }
+
+  // 3. Skills canônicas (sempre, para Deep Agents e referência)
   const spinner2 = ora("Instalando skills canônicas").start();
   const skillsDest = join(targetDir, "skills");
   ensureDir(skillsDest);

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

@@ -14,6 +14,12 @@ Este projeto usa **GitHub Spec Kit** para governança. Antes de implementar qual
 
 Nunca pular direto para código. Spec primeiro, código depois.
 
+## Product Requirements Document
+
+O arquivo `PRD.md` na raiz do projeto contém os requisitos do produto definidos pelo analista/dev. Consulte-o para entender O QUE construir, as user stories, critérios de aceite, modelo de dados e API specification. Este AGENTS.md define COMO o agente deve trabalhar; o PRD define O QUE deve ser construído.
+
+- `PRD.md` — Requisitos do produto, user stories, API spec, modelo de dados
+
 ## References
 
 Documentos de referência que o agente deve consultar quando necessário:

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

@@ -0,0 +1,161 @@
+# Product Requirements Document (PRD)
+
+> Este documento define os requisitos do produto. Deve ser preenchido pelo analista de requisitos e/ou pelo dev antes de iniciar o desenvolvimento. O agente AI usa este documento como contexto para entender O QUE construir.
+
+## 1. Resumo Executivo
+
+<!-- Descreva em 2-3 frases o que é o produto e qual problema resolve -->
+
+## 2. Usuários Alvo
+
+<!-- Quem vai usar o sistema? Descreva as personas -->
+
+### Persona 1: [Nome]
+- **Perfil:**
+- **Objetivos:**
+- **Dores:**
+
+## 3. Escopo do MVP
+
+### Incluído no MVP
+- [ ] Feature 1
+- [ ] Feature 2
+- [ ] Feature 3
+
+### Fora do MVP (futuro)
+- [ ] Feature futura 1
+- [ ] Feature futura 2
+
+## 4. User Stories
+
+### US01: [Título]
+**Como** [persona], **quero** [ação], **para** [benefício].
+
+**Critérios de aceite:**
+- [ ] CA1:
+- [ ] CA2:
+
+### US02: [Título]
+**Como** [persona], **quero** [ação], **para** [benefício].
+
+**Critérios de aceite:**
+- [ ] CA1:
+- [ ] CA2:
+
+## 5. Arquitetura de Alto Nível
+
+<!-- Diagrama em Mermaid ou ASCII mostrando os componentes principais -->
+
+```mermaid
+graph LR
+    A[Frontend] --> B[API]
+    B --> C[Database]
+```
+
+### Estrutura de Diretórios
+
+```
+project/
+├── src/
+├── tests/
+└── ...
+```
+
+## 6. Features Detalhadas
+
+### Feature 1: [Nome]
+- **Descrição:**
+- **Regras de negócio:**
+  -
+- **Inputs:**
+- **Outputs:**
+- **Edge cases:**
+  -
+
+### Feature 2: [Nome]
+- **Descrição:**
+- **Regras de negócio:**
+  -
+
+## 7. Stack Tecnológica
+
+| Componente | Tecnologia | Justificativa |
+|---|---|---|
+| Backend | | |
+| Frontend | | |
+| Banco de dados | | |
+| Cache | | |
+| Deploy | | |
+
+## 8. API Specification
+
+### Endpoints
+
+#### `GET /api/v1/resource`
+- **Descrição:**
+- **Response:** `200 OK`
+```json
+{
+  "items": [],
+  "total": 0,
+  "page": 1,
+  "size": 20
+}
+```
+
+#### `POST /api/v1/resource`
+- **Descrição:**
+- **Body:**
+```json
+{
+  "field": "value"
+}
+```
+- **Response:** `201 Created`
+
+## 9. Modelo de Dados
+
+```sql
+CREATE TABLE example (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    name VARCHAR(100) NOT NULL,
+    created_at TIMESTAMP DEFAULT NOW()
+);
+```
+
+## 10. Requisitos Não-Funcionais
+
+| Requisito | Alvo | Prioridade |
+|---|---|---|
+| Performance | Response time < 500ms | Alta |
+| Disponibilidade | 99.9% uptime | Média |
+| Segurança | OWASP Top 10 | Alta |
+| Escalabilidade | Até X usuários simultâneos | Média |
+
+## 11. Fases de Implementação
+
+### Fase 1: Foundation
+- [ ] Setup do projeto
+- [ ] Modelo de dados
+- [ ] Endpoints básicos
+
+### Fase 2: Core Features
+- [ ] Feature 1 completa
+- [ ] Feature 2 completa
+
+### Fase 3: Polish
+- [ ] Testes E2E
+- [ ] Performance
+- [ ] Documentação
+
+## 12. Riscos e Mitigações
+
+| Risco | Impacto | Probabilidade | Mitigação |
+|---|---|---|---|
+| | | | |
+
+## 13. Critérios de Sucesso
+
+- [ ] Critério 1
+- [ ] Critério 2
+- [ ] Critério 3

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.