maestro-bundle 1.7.0 → 1.9.0

package/README.md

@@ -1,108 +1,126 @@
 # maestro-bundle
 
-Um comando. Bundle instalado. Agente governado. Zero vibing code.
+Um comando. Contexto completo pro agente AI. Qualquer editor.
 
 ```bash
 npx maestro-bundle ai-agents claude
 ```
 
-## Filosofia: Sem spec, sem código
+## O problema
 
-O maestro-bundle instala tudo que o agente AI precisa para trabalhar de forma **governada** — e a peça central disso é o [GitHub Spec Kit](https://github.com/github/spec-kit).
+Agentes AI (Claude Code, Cursor, Codex) são poderosos, mas sem contexto eles não sabem:
 
-O Spec Kit implementa **Specification-Driven Development (SDD)**: toda demanda — nova ou em andamento — precisa ter uma spec antes de qualquer linha de código. O agente é instruído a **recusar** implementar qualquer coisa que não tenha passado pelo fluxo:
+- Qual a stack do projeto
+- Quais padrões de código seguir
+- O que a aplicação faz (requisitos)
+- Que ferramentas usar e quando
+- Qual o plano antes de sair codando
 
-```
-/speckit.specify → /speckit.plan → /speckit.tasks → /speckit.implement
-```
-
-Isso elimina o "vibing code" — aquele padrão onde o dev abre o Cursor e sai codando sem planejamento, sem requisitos, sem spec. Com o bundle instalado, o agente AI vai parar e perguntar: "Cadê a spec?"
+O resultado é **vibing code** — o agente gera código sem direção, sem padrões, sem planejamento. Funciona para protótipos, mas é inviável para projetos reais com time.
 
-## O que instala
-
-1. **AGENTS.md** + **skills** no formato correto do editor — padrões, convenções e capacidades do agente
-2. **PRD.md** — template de requisitos para o analista/dev preencher
-3. **GitHub Spec Kit** — `specify-cli` instalado + `specify init` executado no projeto, registrando os commands `/speckit.*` no editor
-4. **Constitution** — princípios do projeto integrados ao Spec Kit
-5. **LangChain Skills** — 11 skills oficiais extras (apenas para `ai-agents`)
+## A solução: contexto em camadas
 
-## Fluxo de trabalho
+O maestro-bundle resolve isso instalando **3 camadas de contexto** que trabalham juntas:
 
 ```
 ┌─────────────────────────────────────────────────────────┐
-│  1. Dev instala o bundle                                │
-│     npx maestro-bundle ai-agents claude                 │
 │                                                         │
-│  2. Analista/dev preenche o PRD.md                      │
-│     (requisitos, user stories, API spec)                │
+│  PRD.md              O QUE construir                    │
+│  (requisitos)        User stories, API spec, modelo     │
+│                      de dados, critérios de aceite      │
+│                                                         │
+├─────────────────────────────────────────────────────────┤
 │                                                         │
-│  3. Dev abre o editor e pede uma feature                │
-│     "Cria o endpoint de demands"                        │
+│  AGENTS.md           COMO construir                     │
+│  (padrões)           Stack, arquitetura, convenções,    │
+│                      estrutura de projeto, git flow     │
 │                                                         │
-│  4. Agente PARA e inicia o fluxo SDD:                   │
-│     /speckit.specify → spec.md                          │
-│     /speckit.plan    → plan.md                          │
-│     /speckit.tasks   → tasks.md                         │
-│     /speckit.implement → código                         │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│  Skills              COM O QUE construir                │
+│  (capacidades)       RAG pipeline, clean architecture,  │
+│                      deploy, testes, etc.               │
+│                                                         │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│  Spec Kit (SDD)      EM QUE ORDEM construir             │
+│  (processo)          /speckit.specify → plan → tasks    │
+│                      → implement                        │
 │                                                         │
-│  5. Código é produzido seguindo:                        │
-│     - A spec (O QUE construir)                          │
-│     - O AGENTS.md (COMO construir)                      │
-│     - As skills (capacidades específicas)               │
-│     - O PRD.md (requisitos do produto)                  │
 └─────────────────────────────────────────────────────────┘
 ```
 
-Se a demanda já está no meio (spec existe), o agente continua de onde parou. Se é bug fix simples, pode corrigir direto. Mas feature nova sem spec? Não rola.
+Cada camada dá ao agente um tipo de contexto diferente. Juntas, elas fazem o agente trabalhar como um dev senior que conhece o projeto, segue os padrões e planeja antes de codar.
+
+## O que instala
+
+```bash
+npx maestro-bundle ai-agents claude
+```
+
+| O que | Para que | Quem preenche |
+|---|---|---|
+| **AGENTS.md** | Padrões, stack, convenções do projeto | Bundle (automático) |
+| **Skills** | Capacidades específicas (RAG, clean arch, testes...) | Bundle (automático) |
+| **PRD.md** | Requisitos do produto, user stories, API spec | Analista / Dev |
+| **Spec Kit** | Processo SDD — spec → plan → tasks → implement | Agente + Dev |
+| **Constitution** | Princípios inegociáveis do projeto | Bundle (automático) |
+| **LangChain Skills** | 11 skills oficiais LangChain (bundles AI) | Bundle (automático) |
 
-## Arquivos do projeto: quem faz o quê
+O dev só precisa preencher o `PRD.md`. Todo o resto vem pronto.
 
-| Arquivo | Quem escreve | Quando | Para quê |
-|---|---|---|---|
-| **AGENTS.md** | Bundle (automático) | Na instalação | Define COMO o agente trabalha (stack, padrões, convenções) |
-| **PRD.md** | Analista / Dev | Antes de codar | Define O QUE construir (user stories, API spec, modelo de dados) |
-| **`.specify/specs/*/spec.md`** | Agente via `/speckit.specify` | Antes de cada feature | Especificação detalhada da feature |
-| **`.specify/specs/*/plan.md`** | Agente via `/speckit.plan` | Após spec | Plano técnico (arquitetura, decisões) |
-| **`.specify/specs/*/tasks.md`** | Agente via `/speckit.tasks` | Após plan | Tasks atômicas implementáveis |
-| **skills/** | Bundle (automático) | Na instalação | Capacidades que o agente carrega sob demanda |
+## Como funciona na prática
 
-## Commands do Spec Kit disponíveis no editor
+```
+1. Dev instala o bundle
+   $ npx maestro-bundle ai-agents claude
 
-Após instalar o bundle, estes commands funcionam direto no editor:
+2. Analista/dev preenche o PRD.md com os requisitos
 
-| Command | Fase | O que faz |
-|---|---|---|
-| `/speckit.constitution` | Setup | Definir princípios e padrões do projeto |
-| `/speckit.specify` | Spec | Especificar O QUE construir e POR QUÊ |
-| `/speckit.plan` | Plan | Planejar arquitetura, stack, decisões técnicas |
-| `/speckit.tasks` | Tasks | Quebrar em tasks atômicas implementáveis |
-| `/speckit.implement` | Build | Executar todas as tasks seguindo o plano |
-| `/speckit.clarify` | (opcional) | Perguntas para desambiguar requisitos |
-| `/speckit.analyze` | (opcional) | Verificar consistência entre artefatos |
-| `/speckit.checklist` | (opcional) | Gerar checklists de qualidade |
+3. Dev abre o editor e pede uma feature:
+   "Cria o endpoint de autenticação JWT"
 
-## Editores suportados
+4. O agente já sabe:
+   - Os requisitos (PRD.md)
+   - A stack e padrões (AGENTS.md)
+   - Como fazer JWT (skill de authentication)
+   - Que precisa criar spec antes de codar (Spec Kit)
 
-| Editor | Comando | O que instala |
-|---|---|---|
-| **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 no mesmo repo |
+5. Resultado: código governado, consistente, planejado
+```
 
 ## Bundles disponíveis
 
+| Bundle | Tipo de projeto | Stack |
+|---|---|---|
+| `ai-agents` | Sistemas multi-agente com AI | Python, LangChain, LangGraph, FastAPI, pgvector |
+| `ai-agents-deep` | Deep Agent (tipo Claude Code) | Python, Deep Agents SDK, LangGraph, Subagentes |
+| `jhipster-monorepo` | Aplicação JHipster monolítica | Java 21, Spring Boot, Angular, PostgreSQL |
+| `jhipster-microservices` | Microsserviços JHipster | Java 21, Spring Boot, Kafka, Consul, K8s |
+| `data-pipeline` | Pipeline de dados e ML | Python, Pandas, Scikit-learn, MLflow |
+| `frontend-spa` | Frontend SPA | React, TypeScript, Tailwind, Vite |
+
 ```bash
-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
+npx maestro-bundle ai-agents claude
+npx maestro-bundle ai-agents-deep cursor
+npx maestro-bundle jhipster-monorepo claude
+npx maestro-bundle jhipster-microservices codex
+npx maestro-bundle data-pipeline copilot
+npx maestro-bundle frontend-spa windsurf
 ```
 
-## O que acontece
+## Editores suportados
+
+| Editor | Comando | Onde instala |
+|---|---|---|
+| **Claude Code** | `npx maestro-bundle <bundle> claude` | `CLAUDE.md` + `.claude/skills/` |
+| **Cursor** | `npx maestro-bundle <bundle> cursor` | `AGENTS.md` + `.cursor/skills/` |
+| **OpenAI Codex** | `npx maestro-bundle <bundle> codex` | `AGENTS.md` + `.agents/skills/` |
+| **GitHub Copilot** | `npx maestro-bundle <bundle> copilot` | `.github/copilot-instructions.md` |
+| **Windsurf** | `npx maestro-bundle <bundle> windsurf` | `.windsurfrules` |
+| **Todos** | `npx maestro-bundle <bundle> all` | Tudo acima no mesmo repo |
+
+## O que acontece ao instalar
 
 ```
 $ npx maestro-bundle ai-agents claude
@@ -110,121 +128,73 @@ $ npx maestro-bundle ai-agents claude
   Bundle:  Sistema Multi-Agente com AI
   Editor:  Claude Code
 
-  ✔ Claude Code: AGENTS.md, CLAUDE.md → @AGENTS.md, 14 skills em .claude/skills/
-  ✔ PRD.md template instalado (preencha com os requisitos do produto)
+  ✔ Claude Code: AGENTS.md, CLAUDE.md, 14 skills em .claude/skills/
+  ✔ PRD.md template instalado
   ✔ 11 LangChain Skills instaladas
-  ✔ 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
+  ✔ Constitution do bundle integrado
 
   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:
     1. Preencha o PRD.md com os requisitos do produto
     2. Abra o projeto no editor AI
     3. Use /speckit.specify para começar a primeira feature
 ```
 
-## Estrutura instalada
+## Estrutura no projeto
 
-### Claude Code
 ```
 seu-projeto/
-├── CLAUDE.md                                  # @AGENTS.md
-├── AGENTS.md                                  # COMO o agente trabalha
-├── PRD.md                                     # O QUE construir (preencher!)
+├── CLAUDE.md                    # Aponta para AGENTS.md
+├── AGENTS.md                    # Stack, padrões, convenções (automático)
+├── PRD.md                       # Requisitos do produto (preencher!)
 ├── .claude/
-│   ├── skills/                                # Skills do bundle
-│   │   ├── rag-pipeline/SKILL.md
-│   │   ├── clean-architecture/SKILL.md
+│   ├── skills/                  # Capacidades do agente
+│   │   ├── rag-pipeline/
+│   │   ├── clean-architecture/
+│   │   ├── testing-strategy/
 │   │   └── ...
-│   └── commands/                              # /speckit.* (gerado pelo Spec Kit)
+│   └── commands/                # Spec Kit commands
 │       ├── speckit.specify.md
 │       ├── speckit.plan.md
 │       ├── speckit.tasks.md
 │       └── speckit.implement.md
-├── .specify/                                  # Spec Kit
-│   ├── memory/constitution.md                 # Princípios do projeto
-│   ├── scripts/                               # Scripts auxiliares
-│   ├── templates/                             # Templates para spec, plan, tasks
-│   └── specs/                                 # Specs das features (criadas via /speckit.specify)
+├── .specify/                    # Specs, plans, tasks das features
+│   ├── memory/constitution.md
+│   ├── templates/
+│   └── specs/
 │       └── 001-feature-name/
 │           ├── spec.md
 │           ├── plan.md
 │           └── tasks.md
-├── skills/                                    # Skills canônicas (Deep Agents)
-└── references/                                # Docs de referência
+├── skills/                      # Skills canônicas (Deep Agents)
+└── references/                  # Docs de referência
 ```
 
-### Cursor
-```
-seu-projeto/
-├── AGENTS.md                                  # COMO o agente trabalha
-├── PRD.md                                     # O QUE construir (preencher!)
-├── .cursor/
-│   ├── skills/                                # Skills do bundle
-│   └── commands/                              # /speckit.* commands
-├── .specify/                                  # Spec Kit (specs, plans, tasks)
-├── skills/                                    # Skills canônicas
-└── references/
-```
-
-### OpenAI Codex
-```
-seu-projeto/
-├── AGENTS.md                                  # COMO o agente trabalha
-├── PRD.md                                     # O QUE construir (preencher!)
-├── .agents/skills/                            # speckit-* skills
-├── .specify/                                  # Spec Kit
-├── skills/                                    # Skills canônicas
-└── references/
-```
-
-## Skills extras do LangChain (bundle ai-agents)
+## Processo SDD com Spec Kit
 
-O bundle `ai-agents` instala automaticamente as 11 skills oficiais do [LangChain](https://github.com/langchain-ai/langchain-skills):
+O bundle instala o [GitHub Spec Kit](https://github.com/github/spec-kit) que adiciona commands no editor para o fluxo de Specification-Driven Development:
 
-| Skill | O que faz |
+| Command | O que faz |
 |---|---|
-| `framework-selection` | Escolher entre LangChain, LangGraph ou Deep Agents |
-| `langchain-fundamentals` | Criar agentes com `create_agent`, tools, middleware |
-| `langchain-middleware` | Human-in-the-loop, custom middleware, output estruturado |
-| `langchain-rag` | RAG: document loaders, embeddings, vector stores |
-| `langchain-dependencies` | Pacotes, versões, instalação |
-| `langgraph-fundamentals` | StateGraph, nodes, edges, streaming |
-| `langgraph-persistence` | Checkpointers, Store, time travel |
-| `langgraph-human-in-the-loop` | Interrupts, aprovação humana, resume |
-| `deep-agents-core` | Criar Deep Agents, harness, SKILL.md format |
-| `deep-agents-memory` | Memória e persistência para Deep Agents |
-| `deep-agents-orchestration` | Subagentes, planning, HITL |
+| `/speckit.specify` | Especificar O QUE construir e POR QUÊ |
+| `/speckit.plan` | Planejar arquitetura e decisões técnicas |
+| `/speckit.tasks` | Quebrar em tasks atômicas |
+| `/speckit.implement` | Executar as tasks seguindo o plano |
 
-## 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)
+O agente é instruído a seguir esse fluxo para features novas. Bug fixes simples podem ir direto.
 
-## Uso avançado
+## LangChain Skills (bundles AI)
 
-```bash
-# Instalar em diretório específico
-npx maestro-bundle jhipster-monorepo cursor ./meu-projeto
+Os bundles `ai-agents` e `ai-agents-deep` instalam automaticamente as [11 skills oficiais do LangChain](https://github.com/langchain-ai/langchain-skills) cobrindo LangChain, LangGraph e Deep Agents.
 
-# Instalar para todos os editores (time usa editores diferentes)
-npx maestro-bundle ai-agents all
+## Pré-requisitos
 
-# Ver bundles e editores disponíveis
-npx maestro-bundle --help
-```
+- **Node.js 18+**
+- **Git**
+- **uv** ou **pip** (para o Spec Kit — instalado automaticamente)
 
 ## Links
 

package/package.json

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