maestro-bundle 1.7.0 → 1.9.0

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

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

@@ -0,0 +1,165 @@
+---
+name: deep-agent-creation
+description: Create Deep Agents with create_deep_agent(), configure model, tools, system prompt, and run. Use when starting a new deep agent project, configuring an agent, or adding tools.
+version: 1.0.0
+author: Maestro
+---
+
+# Deep Agent Creation
+
+Create and configure Deep Agents using `create_deep_agent()` with tools, system prompts, and model selection.
+
+## When to Use
+- When creating a new Deep Agent from scratch
+- When adding custom tools to an agent
+- When configuring model and system prompt
+- When setting up the main agent entry point
+
+## Available Operations
+1. Install Deep Agents SDK
+2. Define custom tools
+3. Create agent with `create_deep_agent()`
+4. Run agent with `invoke()` or `stream()`
+5. Configure model provider
+
+## Multi-Step Workflow
+
+### Step 1: Install
+
+```bash
+pip install deepagents
+# or
+uv add deepagents
+
+# For search capability
+pip install tavily-python
+```
+
+### Step 2: Set API Keys
+
+```bash
+export ANTHROPIC_API_KEY=your-key
+# or
+export OPENAI_API_KEY=your-key
+```
+
+### Step 3: Define Custom Tools
+
+```python
+# agent/tools.py
+from langchain.tools import tool
+
+@tool
+def search_codebase(query: str, file_pattern: str = "**/*.py") -> str:
+    """Search the codebase for files matching a pattern and containing a query."""
+    import glob
+    results = []
+    for filepath in glob.glob(file_pattern, recursive=True):
+        with open(filepath) as f:
+            content = f.read()
+            if query.lower() in content.lower():
+                results.append(f"Found in {filepath}")
+    return "\n".join(results) if results else "No matches found"
+
+@tool
+def run_tests(test_path: str = "tests/") -> str:
+    """Run pytest on the specified path and return results."""
+    import subprocess
+    result = subprocess.run(
+        ["pytest", test_path, "-v", "--tb=short"],
+        capture_output=True, text=True, timeout=120
+    )
+    return result.stdout + result.stderr
+
+@tool
+def lint_code(path: str = "src/") -> str:
+    """Run ruff linter on the specified path."""
+    import subprocess
+    result = subprocess.run(
+        ["ruff", "check", path],
+        capture_output=True, text=True
+    )
+    return result.stdout or "No lint issues found"
+```
+
+### Step 4: Create the Agent
+
+```python
+# agent/main.py
+from deepagents import create_deep_agent
+from agent.tools import search_codebase, run_tests, lint_code
+
+agent = create_deep_agent(
+    model="anthropic:claude-sonnet-4-6",
+    tools=[search_codebase, run_tests, lint_code],
+    system_prompt="""You are a coding assistant that helps developers write,
+    test, and review code. You follow clean architecture principles and
+    always run tests after making changes."""
+)
+
+# Run
+config = {"configurable": {"thread_id": "session-1"}}
+result = agent.invoke(
+    {"messages": [{"role": "user", "content": "Review the auth module"}]},
+    config=config
+)
+print(result["messages"][-1].content)
+```
+
+### Step 5: Stream Responses
+
+```python
+# For real-time output (like Claude Code)
+async for event in agent.astream_events(
+    {"messages": [{"role": "user", "content": "Fix the failing tests"}]},
+    config=config,
+    version="v2"
+):
+    if event["event"] == "on_chat_model_stream":
+        print(event["data"]["chunk"].content, end="", flush=True)
+```
+
+### Step 6: Verify
+
+```bash
+# Run the agent
+python agent/main.py
+
+# Run tests
+pytest tests/ -v
+```
+
+## Resources
+- `references/deep-agents-api.md` — Full API reference for create_deep_agent()
+- `references/model-providers.md` — Supported model providers and format
+
+## Examples
+
+### Example 1: Minimal Agent
+User asks: "Create a simple deep agent with web search"
+Response approach:
+1. `pip install deepagents tavily-python`
+2. Create `@tool` for Tavily search
+3. Call `create_deep_agent(tools=[search])`
+4. Test with `agent.invoke()`
+
+### Example 2: Coding Agent
+User asks: "Create an agent that can edit files and run tests"
+Response approach:
+1. Define tools: `run_tests`, `lint_code`, `search_codebase`
+2. Use `FilesystemBackend` for file access
+3. Add system prompt with coding conventions
+4. Test end-to-end
+
+### Example 3: Multi-Model Agent
+User asks: "Use Claude for reasoning and GPT for code generation"
+Response approach:
+1. Main agent: `model="anthropic:claude-sonnet-4-6"`
+2. Subagent for code: `model="openai:gpt-4o"`
+3. Route tasks based on type
+
+## Notes
+- Built-in tools: `write_todos`, `ls`, `read_file`, `write_file`, `edit_file`, `glob`, `grep`, `task`
+- Model format: `"provider:model-name"` (e.g., `"anthropic:claude-sonnet-4-6"`)
+- Always use `thread_id` for conversation persistence
+- System prompt is appended to built-in prompts, not replaces them