maestro-bundle 1.7.0 → 1.8.0

package/package.json

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

@@ -33,6 +33,10 @@ const BUNDLES = {
     name: "Frontend SPA",
     desc: "React + TypeScript + Tailwind + Vite",
   },
+  "ai-agents-deep": {
+    name: "Deep Agent (tipo Claude Code)",
+    desc: "Python + Deep Agents SDK + LangGraph + Subagentes + Skills",
+  },
 };
 
 // ============================================================
@@ -321,8 +325,8 @@ async function main() {
   }
   spinner2.succeed(`${skills.length} skills canônicas em skills/`);
 
-  // 3. LangChain Skills (apenas para bundle ai-agents)
-  if (bundleName === "ai-agents") {
+  // 3. LangChain Skills (para bundles de AI)
+  if (bundleName === "ai-agents" || bundleName === "ai-agents-deep") {
     const spinnerLc = ora("Instalando LangChain Skills (langchain-ai/langchain-skills)").start();
     try {
       // Instalar todas as 11 skills do LangChain para o editor escolhido

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

@@ -0,0 +1,24 @@
+# Constitution — Projeto Deep Agent
+
+## Princípios
+
+1. **Spec primeiro, código depois** — Toda demanda passa pelo fluxo SDD antes de implementação
+2. **Agent harness completo** — Todo Deep Agent tem: tools, system prompt, middleware, backend, checkpointer
+3. **Subagentes para isolamento** — Tarefas especializadas vão para subagentes, nunca bloat no main
+4. **Human-in-the-loop obrigatório** — Operações destrutivas sempre pedem aprovação
+5. **Skills on-demand** — Carregar conhecimento quando relevante, não no startup
+
+## Padrões de desenvolvimento
+
+- Python 3.11+, type hints, Black + Ruff
+- Tools com schemas Pydantic e descrições claras
+- System prompts versionados em código
+- Checkpointer obrigatório (MemorySaver dev, PostgresSaver prod)
+- Backend explícito (nunca confiar no StateBackend default em prod)
+
+## Padrões de qualidade
+
+- Evals com golden dataset antes de deploy
+- Middleware de logging em todo agente
+- Testes unitários para tools e middleware
+- Cobertura mínima: 80%

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

@@ -0,0 +1,105 @@
+# Projeto: Deep Agent (tipo Claude Code)
+
+Você está construindo um Deep Agent — um agente AI autônomo que pode planejar, executar tarefas, gerenciar arquivos, delegar para subagentes e interagir com o usuário. Similar ao Claude Code, Cursor Agent ou Codex. Construído com o framework Deep Agents do LangChain.
+
+## Specification-Driven Development (SDD)
+
+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`.
+
+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
+
+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. 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
+
+## Stack do projeto
+
+- **Linguagem:** Python 3.11+
+- **Framework:** Deep Agents SDK (`deepagents`)
+- **Execução:** LangGraph (por baixo)
+- **Modelos:** Claude (Anthropic), GPT (OpenAI), Gemini (Google), Ollama (local)
+- **Backends:** StateBackend, FilesystemBackend, StoreBackend, LocalShellBackend, Sandboxes
+- **API:** FastAPI (para servir o agente como API)
+- **Observabilidade:** LangSmith ou Langfuse
+- **Testes:** Pytest + evals customizados
+
+## Estrutura do projeto
+
+```
+src/
+├── agent/                      # Definição do Deep Agent principal
+│   ├── main.py                 # create_deep_agent + configuração
+│   ├── tools.py                # Tools customizadas
+│   ├── subagents.py            # Definição de subagentes
+│   ├── middleware.py            # Middleware customizado
+│   └── prompts.py              # System prompts versionados
+├── skills/                     # Skills que o agente pode carregar
+│   ├── code-review/SKILL.md
+│   ├── deploy/SKILL.md
+│   └── ...
+├── backends/                   # Configuração de backends
+│   ├── filesystem.py
+│   ├── store.py
+│   └── composite.py
+├── api/                        # Servir agente como API (opcional)
+│   ├── server.py               # FastAPI
+│   └── websocket.py            # Streaming via WebSocket
+├── evals/                      # Avaliação do agente
+│   ├── golden_dataset.json
+│   ├── evaluators.py
+│   └── run_evals.py
+└── config/
+    ├── settings.py
+    └── models.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, Black + Ruff
+- Nomes descritivos, guard clauses
+- Tratar exceções com tipos específicos
+
+## Padrões de Deep Agent
+
+- System prompts versionados em `prompts.py`, nunca hardcoded
+- Tools com schemas Pydantic e descrições claras
+- Cada subagente tem UMA responsabilidade
+- Human-in-the-loop para operações destrutivas (delete, deploy, email)
+- Timeout e max_iterations em todo agente
+- Checkpointer obrigatório para persistência de estado
+- Backend explícito (nunca confiar no default em produção)
+- Skills carregadas on-demand, nunca todas no system prompt
+
+## Middleware obrigatório
+
+O Deep Agent já vem com middleware padrão que não deve ser desabilitado:
+- **TodoListMiddleware** — Planejamento de tarefas
+- **FilesystemMiddleware** — Gerenciamento de arquivos
+- **SubAgentMiddleware** — Delegação para subagentes
+- **SummarizationMiddleware** — Compressão de contexto
+
+## Git
+
+- Commits: `feat(agent): adicionar tool de busca semântica`
+- Branches: `feature/<componente>-<descricao>`
+- Nunca commitar API keys, .env
+
+## Testes
+
+- Testes unitários para tools e middleware
+- Testes de integração para o agente completo
+- Evals com golden dataset + LLM-as-judge
+- Cobertura mínima: 80%
+
+## References
+
+- `references/deep-agents-api.md` — API reference do Deep Agents SDK
+- `references/backends-guide.md` — Guia de backends e quando usar cada um
+- `references/middleware-guide.md` — Middleware padrão e customizado

package/templates/bundle-ai-agents-deep/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-deep/skills/deep-agent-backends/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: deep-agent-backends
+description: Configure Deep Agent backends (StateBackend, FilesystemBackend, StoreBackend, LocalShellBackend, CompositeBackend, Sandboxes). Use when choosing storage, configuring file access, or setting up persistent state.
+version: 1.0.0
+author: Maestro
+---
+
+# Deep Agent Backends
+
+Configure how your Deep Agent stores files and manages context. Backends determine where files live — in memory, on disk, in a database, or in a sandbox.
+
+## When to Use
+- When choosing between ephemeral vs persistent storage
+- When the agent needs local filesystem access
+- When you need shell execution capability
+- When routing different paths to different storage
+- When running in sandboxed environments (Modal, Daytona)
+
+## Available Operations
+1. Use StateBackend (ephemeral, default)
+2. Use FilesystemBackend (local disk)
+3. Use StoreBackend (persistent, cross-thread)
+4. Use LocalShellBackend (filesystem + shell)
+5. Use CompositeBackend (route paths to backends)
+6. Use Sandboxes (isolated execution)
+
+## Multi-Step Workflow
+
+### Step 1: Choose Your Backend
+
+| Backend | Persistence | Shell | Use when |
+|---|---|---|---|
+| StateBackend | Ephemeral (1 thread) | No | Prototyping, stateless tasks |
+| FilesystemBackend | Local disk | No | Read/write project files |
+| StoreBackend | DB (cross-thread) | No | Persistent memory, multi-session |
+| LocalShellBackend | Local disk | Yes | Full coding agent (like Claude Code) |
+| CompositeBackend | Mixed | Mixed | Different storage per path |
+| Sandboxes | Isolated | Yes | Untrusted code execution |
+
+### Step 2: StateBackend (Default)
+
+```python
+from deepagents import create_deep_agent
+
+# Uses StateBackend automatically — files live in memory, gone after session
+agent = create_deep_agent(model="anthropic:claude-sonnet-4-6")
+```
+
+### Step 3: FilesystemBackend (Local Files)
+
+```python
+from deepagents import create_deep_agent
+from deepagents.backends import FilesystemBackend
+
+agent = create_deep_agent(
+    model="anthropic:claude-sonnet-4-6",
+    backend=FilesystemBackend(root_dir=".", virtual_mode=True)
+)
+# Agent can now read/write files in the project directory
+```
+
+### Step 4: LocalShellBackend (Full Coding Agent)
+
+```python
+from deepagents import create_deep_agent
+from deepagents.backends import LocalShellBackend
+
+# WARNING: Agent can execute shell commands on your machine
+agent = create_deep_agent(
+    model="anthropic:claude-sonnet-4-6",
+    backend=LocalShellBackend(
+        root_dir=".",
+        env={"PATH": "/usr/bin:/bin", "HOME": "/home/user"}
+    )
+)
+# Agent can now: read/write files, run shell commands, install packages
+```
+
+### Step 5: StoreBackend (Persistent Memory)
+
+```python
+from deepagents import create_deep_agent
+from deepagents.backends import StoreBackend
+from langgraph.store.memory import InMemoryStore
+# Or for real persistence:
+# from langgraph.store.postgres import PostgresStore
+
+store = InMemoryStore()
+
+agent = create_deep_agent(
+    model="anthropic:claude-sonnet-4-6",
+    backend=lambda rt: StoreBackend(rt),
+    store=store  # Required for StoreBackend
+)
+```
+
+### Step 6: CompositeBackend (Route by Path)
+
+```python
+from deepagents import create_deep_agent
+from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
+from langgraph.store.memory import InMemoryStore
+
+composite = lambda rt: CompositeBackend(
+    default=StateBackend(rt),          # Everything else: ephemeral
+    routes={
+        "/memories/": StoreBackend(rt), # Memories: persistent
+    }
+)
+
+agent = create_deep_agent(
+    backend=composite,
+    store=InMemoryStore()
+)
+```
+
+### Step 7: Verify
+
+```bash
+python -c "
+from deepagents import create_deep_agent
+from deepagents.backends import FilesystemBackend
+
+agent = create_deep_agent(
+    backend=FilesystemBackend(root_dir='.', virtual_mode=True)
+)
+result = agent.invoke({
+    'messages': [{'role': 'user', 'content': 'List files in the current directory'}]
+})
+print(result['messages'][-1].content)
+"
+```
+
+## Resources
+- `references/backends-guide.md` — Detailed backend comparison and configuration
+
+## Examples
+
+### Example 1: Coding Agent with File Access
+User asks: "Create an agent that can edit my project files"
+Response approach:
+1. Use `FilesystemBackend(root_dir=".", virtual_mode=True)`
+2. Agent gets `ls`, `read_file`, `write_file`, `edit_file` tools
+3. Test with "list files" command
+
+### Example 2: Agent with Persistent Memory
+User asks: "Agent should remember things across sessions"
+Response approach:
+1. Use `CompositeBackend` with `StoreBackend` for `/memories/`
+2. Set up PostgresStore for production
+3. Agent writes to `/memories/` for long-term storage
+
+### Example 3: Full Coding Agent (like Claude Code)
+User asks: "Build an agent that can run tests and install packages"
+Response approach:
+1. Use `LocalShellBackend(root_dir=".")`
+2. Agent gets shell execution + file access
+3. Add safety: limit commands, use virtual env
+
+## Notes
+- StateBackend is ephemeral — files are gone after the session
+- FilesystemBackend `virtual_mode=True` is safer (sandboxed paths)
+- LocalShellBackend gives full shell access — use with caution
+- StoreBackend REQUIRES a `store` parameter
+- CompositeBackend is the production choice (ephemeral default + persistent memory)

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

@@ -0,0 +1,158 @@
+---
+name: deep-agent-cli
+description: Build and use the Deep Agents CLI for terminal-based coding agents. Use when creating a CLI coding agent, running Deep Agents from terminal, or building a Claude Code-like experience.
+version: 1.0.0
+author: Maestro
+---
+
+# Deep Agents CLI
+
+Build a terminal-based coding agent similar to Claude Code using the Deep Agents CLI or by creating your own CLI interface.
+
+## When to Use
+- When you want a Claude Code-like experience in the terminal
+- When building a CLI tool for AI-assisted coding
+- When running Deep Agents interactively
+
+## Available Operations
+1. Install and use the official Deep Agents CLI
+2. Build a custom CLI with rich terminal UI
+3. Configure CLI with local file access + shell
+4. Add skills and AGENTS.md to CLI agent
+
+## Multi-Step Workflow
+
+### Step 1: Install Deep Agents CLI
+
+```bash
+pip install deepagents
+# or
+uv tool install deepagents
+```
+
+### Step 2: Run the CLI
+
+```bash
+# Start interactive session
+deepagents
+
+# Start with a specific model
+deepagents --model anthropic:claude-sonnet-4-6
+
+# Start in a specific directory
+deepagents --dir ./my-project
+
+# Start with a prompt
+deepagents "Fix the failing tests in src/auth/"
+```
+
+### Step 3: Build Custom CLI
+
+```python
+# cli.py
+import asyncio
+import sys
+from deepagents import create_deep_agent
+from deepagents.backends import LocalShellBackend
+from langgraph.checkpoint.memory import MemorySaver
+
+async def main():
+    # Full coding agent with file + shell access
+    agent = create_deep_agent(
+        model="anthropic:claude-sonnet-4-6",
+        backend=LocalShellBackend(root_dir="."),
+        skills=["./skills/"],
+        memory=["/AGENTS.md"],
+        checkpointer=MemorySaver(),
+        system_prompt="You are a coding assistant. Follow the project conventions."
+    )
+
+    config = {"configurable": {"thread_id": "cli-session"}}
+
+    # One-shot mode
+    if len(sys.argv) > 1:
+        prompt = " ".join(sys.argv[1:])
+        async for event in agent.astream_events(
+            {"messages": [{"role": "user", "content": prompt}]},
+            config=config, version="v2"
+        ):
+            if event["event"] == "on_chat_model_stream":
+                print(event["data"]["chunk"].content, end="", flush=True)
+        print()
+        return
+
+    # Interactive mode
+    print("Coding Agent (type 'exit' to quit)\n")
+    while True:
+        try:
+            user_input = input("> ")
+        except (EOFError, KeyboardInterrupt):
+            break
+
+        if user_input.lower() in ("exit", "quit"):
+            break
+
+        async for event in agent.astream_events(
+            {"messages": [{"role": "user", "content": user_input}]},
+            config=config, version="v2"
+        ):
+            if event["event"] == "on_chat_model_stream":
+                print(event["data"]["chunk"].content, end="", flush=True)
+        print("\n")
+
+asyncio.run(main())
+```
+
+### Step 4: Make it Installable
+
+```toml
+# pyproject.toml
+[project]
+name = "my-coding-agent"
+version = "0.1.0"
+dependencies = ["deepagents"]
+
+[project.scripts]
+myagent = "cli:main"
+```
+
+```bash
+pip install -e .
+myagent "Fix the auth tests"
+```
+
+### Step 5: Verify
+
+```bash
+# Run the CLI
+python cli.py "List the files in the current directory"
+
+# Interactive mode
+python cli.py
+```
+
+## Resources
+- `references/cli-patterns.md` — CLI design patterns
+
+## Examples
+
+### Example 1: Simple Coding Agent
+User asks: "Create a CLI that can edit files and run tests"
+Response approach:
+1. Use `LocalShellBackend(root_dir=".")`
+2. Add `skills=["./skills/"]` for project skills
+3. Stream output with `astream_events`
+4. Test in project directory
+
+### Example 2: Add Project Context
+User asks: "Agent should know our project conventions"
+Response approach:
+1. Create AGENTS.md with conventions
+2. Pass `memory=["/AGENTS.md"]`
+3. Agent loads it at startup
+
+## Notes
+- LocalShellBackend gives full filesystem + shell — use responsibly
+- Always use `astream_events` for real-time output in CLI
+- `checkpointer` enables conversation memory within session
+- Skills load on-demand as user asks for things