maestro-bundle 1.3.1 → 1.4.0

package/package.json

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

package/templates/bundle-ai-agents/skills/api-design/SKILL.md

@@ -1,22 +1,46 @@
 ---
 name: api-design
-description: Criar APIs REST com FastAPI ou Spring Boot seguindo padrões de versionamento, paginação, error handling e documentação. Use quando for criar endpoints, definir contratos de API, ou estruturar controllers.
+description: Design REST APIs with FastAPI or Spring Boot following patterns for versioning, pagination, error handling, and documentation. Use when creating endpoints, defining API contracts, or structuring controllers.
+version: 1.0.0
+author: Maestro
 ---
 
 # API Design
 
-## Padrões REST
+Build production-ready REST APIs with standardized patterns for routing, pagination, error handling, versioning, and OpenAPI documentation.
 
-| Operação | Método | Path | Status | Body |
+## When to Use
+- Creating new REST API endpoints
+- Defining API contracts and response schemas
+- Adding pagination, filtering, or sorting to list endpoints
+- Implementing standardized error handling
+- Setting up API versioning strategy
+- Generating OpenAPI/Swagger documentation
+
+## Available Operations
+1. Create CRUD endpoints with FastAPI
+2. Define request/response models with Pydantic
+3. Implement standardized error handling
+4. Add pagination to list endpoints
+5. Configure API versioning
+6. Generate and validate OpenAPI documentation
+
+## Multi-Step Workflow
+
+### Step 1: Define the REST Contract
+
+Map business operations to HTTP methods and paths.
+
+| Operation | Method | Path | Status | Body |
 |---|---|---|---|---|
-| Listar | GET | `/api/v1/demands` | 200 | Lista paginada |
-| Buscar | GET | `/api/v1/demands/{id}` | 200 | Objeto |
-| Criar | POST | `/api/v1/demands` | 201 | Objeto criado |
-| Atualizar | PUT | `/api/v1/demands/{id}` | 200 | Objeto atualizado |
-| Patch | PATCH | `/api/v1/demands/{id}` | 200 | Objeto atualizado |
-| Deletar | DELETE | `/api/v1/demands/{id}` | 204 | Vazio |
+| List | GET | `/api/v1/demands` | 200 | Paginated list |
+| Get | GET | `/api/v1/demands/{id}` | 200 | Single object |
+| Create | POST | `/api/v1/demands` | 201 | Created object |
+| Update | PUT | `/api/v1/demands/{id}` | 200 | Updated object |
+| Patch | PATCH | `/api/v1/demands/{id}` | 200 | Updated object |
+| Delete | DELETE | `/api/v1/demands/{id}` | 204 | Empty |
 
-## FastAPI — Template
+### Step 2: Create the Controller with FastAPI
 
 ```python
 from fastapi import APIRouter, Depends, HTTPException, Query
@@ -56,9 +80,14 @@ async def get_demand(
     return result
 ```
 
-## Error Handling padronizado
+### Step 3: Implement Error Handling
+
+Standardize error responses across all endpoints.
 
 ```python
+from pydantic import BaseModel
+from fastapi.responses import JSONResponse
+
 class ErrorResponse(BaseModel):
     error: str
     message: str
@@ -68,20 +97,28 @@ class ErrorResponse(BaseModel):
 async def domain_exception_handler(request, exc: DomainException):
     return JSONResponse(
         status_code=422,
-        content=ErrorResponse(error="domain_error", message=str(exc)).dict()
+        content=ErrorResponse(error="domain_error", message=str(exc)).model_dump()
     )
 
 @app.exception_handler(NotFoundException)
 async def not_found_handler(request, exc: NotFoundException):
     return JSONResponse(
         status_code=404,
-        content=ErrorResponse(error="not_found", message=str(exc)).dict()
+        content=ErrorResponse(error="not_found", message=str(exc)).model_dump()
     )
 ```
 
-## Paginação
+### Step 4: Add Pagination
+
+Create a reusable pagination response model.
 
 ```python
+from math import ceil
+from pydantic import BaseModel, model_validator
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
 class PaginatedResponse(BaseModel, Generic[T]):
     items: list[T]
     total: int
@@ -95,6 +132,78 @@ class PaginatedResponse(BaseModel, Generic[T]):
         return values
 ```
 
-## Versionamento
+### Step 5: Configure Versioning
+
+Use path-based versioning: `/api/v1/`, `/api/v2/`.
+
+```python
+from fastapi import FastAPI
+
+app = FastAPI(title="Maestro API", version="1.0.0")
+
+# Mount versioned routers
+app.include_router(demands_v1_router, prefix="/api/v1")
+app.include_router(demands_v2_router, prefix="/api/v2")
+```
+
+**Rule**: Keep v1 running until all clients have migrated to v2.
+
+### Step 6: Validate the API
+
+Test endpoints and verify OpenAPI docs.
+
+```bash
+# Run the API server
+uvicorn src.main:app --reload --port 8000
+
+# Test an endpoint
+curl -s http://localhost:8000/api/v1/demands?page=1&size=10 | python -m json.tool
+
+# Verify OpenAPI schema is valid
+curl -s http://localhost:8000/openapi.json | python -m json.tool > /dev/null && echo "Valid OpenAPI schema"
+
+# Run API tests
+pytest tests/api/ -v
+```
 
-Usar path-based: `/api/v1/`, `/api/v2/`. Manter v1 funcionando até todos os clientes migrarem.
+## Resources
+- `references/rest-conventions.md` - Complete REST naming and status code conventions
+- `references/pydantic-patterns.md` - Common Pydantic model patterns for API schemas
+
+## Examples
+
+### Example 1: Build a Complete CRUD API
+User asks: "Create a full CRUD API for managing tasks."
+Response approach:
+1. Define the 6 REST operations (list, get, create, update, patch, delete)
+2. Create Pydantic models: `CreateTaskRequest`, `UpdateTaskRequest`, `TaskResponse`
+3. Create `PaginatedResponse[TaskResponse]` for the list endpoint
+4. Wire each endpoint to its corresponding use case
+5. Add error handlers for `NotFoundException` and `ValidationError`
+6. Test all endpoints with `pytest` and `httpx.AsyncClient`
+
+### Example 2: Add Filtering and Sorting
+User asks: "Add status filtering and date sorting to the demands list endpoint."
+Response approach:
+1. Add query parameters: `status: str | None`, `sort_by: str = "created_at"`, `sort_order: str = "desc"`
+2. Pass parameters to the use case
+3. Update the repository query to support filtering and ordering
+4. Add index on the filtered/sorted columns if not present
+5. Test with: `curl "http://localhost:8000/api/v1/demands?status=active&sort_by=created_at&sort_order=desc"`
+
+### Example 3: Add API Authentication
+User asks: "Protect our endpoints with JWT authentication."
+Response approach:
+1. Create a `get_current_user` dependency that validates JWT tokens
+2. Add the dependency to protected endpoints
+3. Create a `/auth/token` endpoint for token generation
+4. Add 401 and 403 error handlers
+5. Update OpenAPI schema with security definitions
+
+## Notes
+- Controllers should be thin: parse request -> call use case -> format response
+- Always use Pydantic models for request validation (never trust raw input)
+- Use `response_model` in route decorators to enforce response schema
+- Pagination defaults: page=1, size=20, max size=100
+- Path-based versioning (`/api/v1/`) is the simplest and most maintainable approach
+- Generate OpenAPI docs automatically -- never maintain them manually

package/templates/bundle-ai-agents/skills/api-design/references/pydantic-patterns.md

@@ -0,0 +1,72 @@
+# Pydantic Patterns Reference
+
+## Request Models
+
+```python
+from pydantic import BaseModel, Field, EmailStr
+
+class CreateDemandRequest(BaseModel):
+    description: str = Field(..., min_length=10, max_length=1000)
+    requester: str = Field(..., min_length=1)
+    priority: str = Field(default="medium", pattern="^(low|medium|high|critical)$")
+
+class UpdateDemandRequest(BaseModel):
+    description: str | None = Field(None, min_length=10, max_length=1000)
+    priority: str | None = Field(None, pattern="^(low|medium|high|critical)$")
+    status: str | None = Field(None, pattern="^(created|planned|in_progress|completed)$")
+```
+
+## Response Models
+
+```python
+from datetime import datetime
+
+class DemandResponse(BaseModel):
+    id: str
+    description: str
+    status: str
+    requester: str
+    created_at: datetime
+    updated_at: datetime
+
+    model_config = {"from_attributes": True}
+```
+
+## Pagination
+
+```python
+from math import ceil
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+class PaginatedResponse(BaseModel, Generic[T]):
+    items: list[T]
+    total: int
+    page: int
+    size: int
+    pages: int
+
+    @model_validator(mode="before")
+    def calc_pages(cls, values):
+        if values.get("size", 0) > 0:
+            values["pages"] = ceil(values["total"] / values["size"])
+        return values
+```
+
+## Validation Patterns
+
+```python
+from pydantic import field_validator
+
+class CreateUserRequest(BaseModel):
+    email: EmailStr
+    username: str = Field(..., min_length=3, max_length=50)
+
+    @field_validator("username")
+    @classmethod
+    def username_alphanumeric(cls, v: str) -> str:
+        if not v.replace("_", "").replace("-", "").isalnum():
+            raise ValueError("Username must be alphanumeric (with _ and -)")
+        return v.lower()
+```

package/templates/bundle-ai-agents/skills/api-design/references/rest-conventions.md

@@ -0,0 +1,51 @@
+# REST Conventions Reference
+
+## URL Naming
+
+- Use plural nouns: `/demands`, `/tasks`, `/users`
+- Use kebab-case for multi-word resources: `/task-assignments`
+- Nest for relationships: `/demands/{id}/tasks`
+- Maximum 2 levels of nesting
+- Query parameters for filtering: `?status=active&sort_by=created_at`
+
+## HTTP Methods
+
+| Method | Idempotent | Safe | Use For |
+|---|---|---|---|
+| GET | Yes | Yes | Read resources |
+| POST | No | No | Create resources |
+| PUT | Yes | No | Full update (replace) |
+| PATCH | No | No | Partial update |
+| DELETE | Yes | No | Remove resources |
+
+## Status Codes
+
+| Code | Meaning | When to Use |
+|---|---|---|
+| 200 | OK | Successful GET, PUT, PATCH |
+| 201 | Created | Successful POST |
+| 204 | No Content | Successful DELETE |
+| 400 | Bad Request | Malformed request body |
+| 401 | Unauthorized | Missing or invalid authentication |
+| 403 | Forbidden | Authenticated but not authorized |
+| 404 | Not Found | Resource does not exist |
+| 409 | Conflict | Duplicate resource or state conflict |
+| 422 | Unprocessable Entity | Valid syntax but business rule violation |
+| 500 | Internal Server Error | Unexpected server failure |
+
+## Error Response Format
+
+```json
+{
+  "error": "not_found",
+  "message": "Demand with id 'abc-123' not found",
+  "details": ["Check the demand ID and try again"]
+}
+```
+
+## Headers
+
+- `Content-Type: application/json` on all responses
+- `Location: /api/v1/demands/{id}` on 201 Created
+- `X-Request-Id: uuid` for tracing
+- `X-Total-Count: 42` for pagination metadata (optional)