maestro-bundle 1.3.1 → 1.4.0

package/templates/bundle-ai-agents/skills/clean-architecture/SKILL.md

@@ -1,28 +1,59 @@
 ---
 name: clean-architecture
-description: Implementar Clean Architecture com camadas de domínio, aplicação e infraestrutura. Use quando for criar módulos, organizar código em camadas, separar regras de negócio de infraestrutura, ou estruturar um projeto novo.
+description: Implement Clean Architecture with domain, application, and infrastructure layers. Use when creating modules, organizing code in layers, separating business rules from infrastructure, or structuring a new project.
+version: 1.0.0
+author: Maestro
 ---
 
 # Clean Architecture
 
-## Camadas
+Structure code into Domain, Application, and Infrastructure layers with strict dependency rules, ensuring business logic is isolated from frameworks and external services.
+
+## When to Use
+- Starting a new module or microservice
+- Refactoring code that mixes business logic with infrastructure
+- Creating entities, value objects, use cases, or repositories
+- Reviewing code for layer violations
+- Setting up project structure for a new feature
+
+## Available Operations
+1. Define domain entities with business rules and events
+2. Create application use cases that orchestrate domain logic
+3. Implement infrastructure adapters (repositories, HTTP clients)
+4. Set up dependency injection wiring
+5. Validate layer dependencies (no inward violations)
+
+## Multi-Step Workflow
+
+### Step 1: Set Up the Layer Structure
+
+Create the directory structure following the dependency rule: outer layers depend on inner layers, never the reverse.
+
+```bash
+mkdir -p src/domain/entities src/domain/repositories src/domain/value_objects src/domain/events
+mkdir -p src/application/use_cases src/application/dtos
+mkdir -p src/infrastructure/persistence src/infrastructure/http
+mkdir -p src/api/controllers
+```
 
 ```
-┌──────────────────────────────┐
-│         API / CLI            │  ← Controllers, Routers
-├──────────────────────────────┤
-│        APPLICATION           │  ← Use Cases, DTOs
-├──────────────────────────────┤
-│          DOMAIN              │  ← Entities, VOs, Events, Repos (interface)
-├──────────────────────────────┤
-│       INFRASTRUCTURE         │  ← DB, HTTP clients, Frameworks
-└──────────────────────────────┘
-
-Dependency Rule: setas apontam para DENTRO (infra → domain)
-Domain NUNCA importa de infrastructure
++------------------------------+
+|         API / CLI            |  <- Controllers, Routers
++------------------------------+
+|        APPLICATION           |  <- Use Cases, DTOs
++------------------------------+
+|          DOMAIN              |  <- Entities, VOs, Events, Repos (interface)
++------------------------------+
+|       INFRASTRUCTURE         |  <- DB, HTTP clients, Frameworks
++------------------------------+
+
+Dependency Rule: arrows point INWARD (infra -> domain)
+Domain NEVER imports from infrastructure
 ```
 
-## Domain Layer
+### Step 2: Build the Domain Layer
+
+Domain contains entities with business rules, value objects, domain events, and repository interfaces (ports).
 
 ```python
 # domain/entities/demand.py
@@ -45,7 +76,9 @@ class Demand:
     def pending_events(self) -> list[DomainEvent]:
         return list(self._events)
 
-# domain/repositories/demand_repository.py (PORT - apenas interface)
+# domain/repositories/demand_repository.py (PORT -- interface only)
+from abc import ABC, abstractmethod
+
 class DemandRepository(ABC):
     @abstractmethod
     def find_by_id(self, id: DemandId) -> Demand: ...
@@ -53,7 +86,9 @@ class DemandRepository(ABC):
     def save(self, demand: Demand) -> None: ...
 ```
 
-## Application Layer
+### Step 3: Build the Application Layer
+
+Application layer contains use cases that orchestrate domain entities. Use cases are the entry points for business operations.
 
 ```python
 # application/use_cases/decompose_demand.py
@@ -72,7 +107,9 @@ class DecomposeDemand:
         return DecomposeDemandOutput(tasks=[TaskDTO.from_entity(t) for t in tasks])
 ```
 
-## Infrastructure Layer
+### Step 4: Build the Infrastructure Layer
+
+Infrastructure implements the ports defined in the domain layer (adapters).
 
 ```python
 # infrastructure/persistence/pg_demand_repository.py (ADAPTER)
@@ -92,8 +129,63 @@ class PgDemandRepository(DemandRepository):
         self._session.commit()
 ```
 
-## Regra de ouro
+### Step 5: Validate Layer Dependencies
+
+Check that no layer violations exist. Domain must never import from infrastructure.
+
+```bash
+# Check for import violations (domain importing from infrastructure)
+grep -r "from src.infrastructure" src/domain/ && echo "VIOLATION: Domain imports infrastructure!" || echo "OK: No violations"
+grep -r "from src.api" src/domain/ && echo "VIOLATION: Domain imports API!" || echo "OK: No violations"
+grep -r "from src.infrastructure" src/application/ && echo "VIOLATION: Application imports infrastructure!" || echo "OK: No violations"
+```
+
+Use a linter rule to enforce this:
 
-Use Case orquestra → Entity contém regra → Repository persiste
+```bash
+ruff check src/ --select I  # Check import ordering
+```
 
-Nunca colocar regra de negócio no Controller, Repository ou "Service" genérico.
+## Resources
+- `references/layer-rules.md` - Detailed rules for what belongs in each layer
+- `references/dependency-injection.md` - Patterns for wiring layers together
+
+## Examples
+
+### Example 1: Create a New Feature Module
+User asks: "Create a user management module with CRUD operations."
+Response approach:
+1. Create domain entity `User` with validation rules and events
+2. Create value objects: `UserId`, `Email`, `UserStatus`
+3. Define `UserRepository` port (abstract class) in domain
+4. Create use cases: `CreateUser`, `GetUser`, `ListUsers`, `UpdateUser`
+5. Implement `PgUserRepository` adapter in infrastructure
+6. Create `UserController` in API layer with FastAPI routes
+7. Wire dependencies with dependency injection
+
+### Example 2: Refactor a "Fat Controller"
+User asks: "Our controller has all the business logic. Refactor it to Clean Architecture."
+Response approach:
+1. Identify business rules in the controller
+2. Extract domain entity with those rules as methods
+3. Create a use case that orchestrates the entity operations
+4. Move database calls to a repository adapter
+5. Controller should only: parse request -> call use case -> format response
+6. Run import validation to confirm no layer violations
+
+### Example 3: Add Domain Events
+User asks: "When a demand is decomposed, we need to notify other services."
+Response approach:
+1. Create `DemandDecomposed` domain event class
+2. Add event collection to the `Demand` entity
+3. Emit the event in the `decompose()` method
+4. Publish events in the use case after saving
+5. Infrastructure layer handles event delivery (message queue, HTTP, etc.)
+
+## Notes
+- **Golden rule**: Use Case orchestrates -> Entity contains rules -> Repository persists
+- Never put business logic in controllers, repositories, or generic "Service" classes
+- Domain layer has zero external dependencies (no frameworks, no database drivers)
+- Use cases should be small (one public method: `execute`)
+- Value objects enforce validation at construction -- use them for all domain primitives
+- Repository interfaces (ports) live in the domain; implementations (adapters) live in infrastructure

package/templates/bundle-ai-agents/skills/clean-architecture/references/dependency-injection.md

@@ -0,0 +1,60 @@
+# Dependency Injection Reference
+
+## FastAPI Dependency Injection
+
+```python
+# infrastructure/dependencies.py
+from fastapi import Depends
+from sqlalchemy.orm import Session
+
+def get_db_session() -> Session:
+    session = SessionLocal()
+    try:
+        yield session
+    finally:
+        session.close()
+
+def get_demand_repository(session: Session = Depends(get_db_session)) -> DemandRepository:
+    return PgDemandRepository(session)
+
+def get_decompose_demand(
+    repo: DemandRepository = Depends(get_demand_repository),
+    planner: TaskPlanner = Depends(get_task_planner),
+    event_bus: EventBus = Depends(get_event_bus),
+) -> DecomposeDemand:
+    return DecomposeDemand(repo=repo, planner=planner, event_bus=event_bus)
+```
+
+## Usage in Controller
+
+```python
+@router.post("/demands/{demand_id}/decompose")
+async def decompose_demand(
+    demand_id: str,
+    use_case: DecomposeDemand = Depends(get_decompose_demand),
+):
+    return use_case.execute(demand_id)
+```
+
+## Testing with Fakes
+
+```python
+# In tests, inject fakes instead of real implementations
+def test_decompose_demand():
+    repo = FakeDemandRepository()
+    planner = FakePlanner(tasks=[Task(...)])
+    event_bus = FakeEventBus()
+
+    use_case = DecomposeDemand(repo=repo, planner=planner, event_bus=event_bus)
+    result = use_case.execute("demand-123")
+
+    assert len(result.tasks) == 1
+    assert len(event_bus.published_events) == 1
+```
+
+## Principle
+
+- Controllers depend on use cases (via interface).
+- Use cases depend on repository interfaces (ports).
+- Infrastructure provides concrete implementations (adapters).
+- Tests inject fakes that implement the same interfaces.

package/templates/bundle-ai-agents/skills/clean-architecture/references/layer-rules.md

@@ -0,0 +1,56 @@
+# Layer Rules Reference
+
+## Domain Layer
+
+**Contains**: Entities, Value Objects, Domain Events, Repository Interfaces (Ports), Domain Services.
+
+**Rules**:
+- ZERO external dependencies (no frameworks, no database drivers, no HTTP clients)
+- Contains all business rules and invariants
+- Entities have identity and lifecycle
+- Value Objects are immutable and compared by value
+- Domain Events record things that happened
+- Repository interfaces define WHAT, not HOW
+
+**Allowed imports**: Only Python standard library and other domain classes.
+
+**Forbidden imports**: SQLAlchemy, FastAPI, requests, any infrastructure package.
+
+## Application Layer
+
+**Contains**: Use Cases, DTOs (Data Transfer Objects), Application Services.
+
+**Rules**:
+- Orchestrates domain entities and services
+- One use case = one business operation
+- Each use case has a single public method (`execute`)
+- Receives raw data, returns DTOs (never entities)
+- Publishes domain events after persisting changes
+
+**Allowed imports**: Domain layer classes.
+
+**Forbidden imports**: FastAPI, SQLAlchemy, any infrastructure or API package.
+
+## Infrastructure Layer
+
+**Contains**: Repository Implementations (Adapters), ORM Models, HTTP Clients, Message Queue Clients, External Service Integrations.
+
+**Rules**:
+- Implements interfaces defined in the domain layer
+- Converts between domain entities and persistence models
+- Handles all framework-specific code
+- Contains database migrations
+
+**Allowed imports**: Domain layer, Application layer, third-party libraries.
+
+## API Layer
+
+**Contains**: Controllers/Routers, Request/Response Models, Middleware, Authentication.
+
+**Rules**:
+- Thin layer: parse request -> call use case -> format response
+- No business logic
+- Handles HTTP-specific concerns (status codes, headers, auth)
+- Input validation at the boundary (Pydantic models)
+
+**Allowed imports**: Application layer (use cases, DTOs). Never domain entities directly.

package/templates/bundle-ai-agents/skills/context-engineering/SKILL.md

@@ -1,48 +1,72 @@
 ---
 name: context-engineering
-description: Implementar as 4 estratégias de context engineering (Write, Select, Compress, Isolate) para agentes. Use quando precisar gerenciar a janela de contexto, otimizar o que o agente recebe, ou reduzir custos de tokens.
+description: Implement the 4 context engineering strategies (Write, Select, Compress, Isolate) for AI agents. Use when managing context windows, optimizing what an agent receives, or reducing token costs.
+version: 1.0.0
+author: Maestro
 ---
 
 # Context Engineering
 
-As 4 estratégias conforme Anthropic:
+Apply the four context engineering strategies -- Write, Select, Compress, Isolate -- to maximize agent effectiveness while minimizing token costs.
 
-## 1. Write Context — Memória Persistente
+## When to Use
+- Designing what context an agent receives before execution
+- Optimizing a system prompt that is too long or unfocused
+- Reducing token costs on expensive LLM calls
+- Setting up context isolation between agents in a multi-agent system
+- Debugging an agent that "forgets" instructions or loses focus
 
-O que o agente "sabe" antes de começar.
+## Available Operations
+1. Write persistent context (CLAUDE.md, agents.md, skills)
+2. Select relevant context via retrieval
+3. Compress context to reduce token usage
+4. Isolate context per agent scope
+5. Budget context allocation across the window
+
+## Multi-Step Workflow
+
+### Step 1: Write Context -- Persistent Memory
+
+Define what the agent "knows" before any task begins. This is your baseline context layer.
 
 ```
-CLAUDE.md          → Padrões do projeto, arquitetura, decisões
-agents.md          → Comportamento específico do agente
-skills/SKILL.md    → Capacidades on-demand
-memory/            → Aprendizados de execuções anteriores
+CLAUDE.md          -> Project standards, architecture, decisions
+agents.md          -> Agent-specific behavior and role definition
+skills/SKILL.md    -> On-demand capabilities loaded when needed
+memory/            -> Learnings from previous executions
+```
+
+Check your CLAUDE.md token count:
+
+```bash
+wc -w CLAUDE.md  # Should be under ~1500 words (~2000 tokens)
 ```
 
-**Regra:** CLAUDE.md deve ter no máximo 2000 tokens. Se precisar de mais, mover para skills que são carregadas on-demand.
+**Rule**: CLAUDE.md must stay under 2000 tokens. If it grows beyond that, move details into skills that are loaded on-demand.
 
-## 2. Select Context — Retrieval Inteligente
+### Step 2: Select Context -- Retrieval for the Current Task
 
-Injetar apenas o contexto relevante para a task atual.
+Inject only the context relevant to the current task. Never dump everything.
 
 ```python
 def select_context(task: Task, retriever) -> str:
-    # Buscar skills relevantes para a task
+    # Retrieve skills relevant to the task
     relevant_skills = retriever.invoke(task.description)
 
-    # Buscar código relacionado no repo
+    # Search for related code in the repository
     related_code = code_search(task.description, worktree_path)
 
-    # Buscar decisões anteriores similares
+    # Find similar past decisions
     past_decisions = memory_store.search(task.description, k=3)
 
     return format_context(relevant_skills, related_code, past_decisions)
 ```
 
-**Regra:** Nunca injetar mais de 30% da janela de contexto com contexto selecionado. Deixar espaço para o agente raciocinar.
+**Rule**: Never inject more than 30% of the context window with selected context. Leave space for the agent to reason.
 
-## 3. Compress Context — Resumo Eficiente
+### Step 3: Compress Context -- Reduce Without Losing Essentials
 
-Reduzir informação sem perder o essencial.
+When context exceeds budget, compress it while preserving critical information.
 
 ```python
 async def compress_code(code: str, max_tokens: int = 2000) -> str:
@@ -50,23 +74,23 @@ async def compress_code(code: str, max_tokens: int = 2000) -> str:
         return code
 
     summary = await llm.ainvoke(f"""
-    Resuma este código mantendo:
-    - Assinaturas de funções/classes
-    - Tipos de entrada/saída
-    - Lógica principal (sem detalhes de implementação)
-    - Imports relevantes
+    Summarize this code keeping:
+    - Function/class signatures
+    - Input/output types
+    - Main logic (without implementation details)
+    - Relevant imports
 
-    Código:
+    Code:
     {code}
     """)
     return summary.content
 ```
 
-**Regra:** Comprimir apenas quando necessário. Código que o agente vai modificar deve estar completo, não comprimido.
+**Rule**: Never compress code the agent is about to modify. That code must remain complete and uncompressed.
 
-## 4. Isolate Context — Escopo por Agente
+### Step 4: Isolate Context -- Scope Per Agent
 
-Cada agente vê apenas o que precisa.
+Each agent should see only what it needs. No shared context windows.
 
 ```python
 agent_contexts = {
@@ -83,16 +107,60 @@ agent_contexts = {
 }
 ```
 
-**Regra:** Agentes nunca compartilham janela de contexto. Comunicação via mensagens estruturadas, não via contexto compartilhado.
+**Rule**: Agents never share a context window. Communication happens via structured messages, not shared context.
+
+### Step 5: Budget Context Allocation
+
+For a 200k token model, allocate the context window as follows:
 
-## Budget de contexto
+| Component | % | Tokens | Description |
+|---|---|---|---|
+| System prompt + CLAUDE.md | 5% | 10k | Identity, rules, format |
+| Loaded skills | 10% | 20k | On-demand capabilities |
+| Retrieved code/docs (Select) | 25% | 50k | Task-relevant context |
+| Conversation history | 15% | 30k | Previous messages |
+| **Reasoning space** | **45%** | **90k** | Model's working memory |
 
-Para um modelo com 200k tokens:
+Verify current usage:
+
+```bash
+python -m context.budget --prompt system_prompt.md --skills skills/ --history conversation.json
+```
 
-| Componente | % | Tokens |
-|---|---|---|
-| System prompt + CLAUDE.md | 5% | 10k |
-| Skills carregadas | 10% | 20k |
-| Código relevante (Select) | 25% | 50k |
-| Histórico de conversa | 15% | 30k |
-| **Espaço para raciocínio** | **45%** | **90k** |
+## Resources
+- `references/context-budget-calculator.md` - Formulas and guidelines for calculating context budgets
+- `references/compression-techniques.md` - Techniques for compressing different content types
+
+## Examples
+
+### Example 1: Set Up Context for a New Agent
+User asks: "Configure the context strategy for our new QA agent."
+Response approach:
+1. Write: Create agents/qa.md with QA agent identity, rules, and test standards
+2. Select: Configure retriever to pull test files and coverage reports relevant to the task
+3. Isolate: Limit visibility to `tests/`, `src/` (read-only), and CI config files
+4. Budget: Allocate 5% system prompt, 20% test context, 20% source code, 55% reasoning
+
+### Example 2: Fix an Agent That Loses Focus
+User asks: "Our backend agent keeps forgetting to follow Clean Architecture halfway through long tasks."
+Response approach:
+1. Check CLAUDE.md size -- if over 2000 tokens, move details to skills
+2. Move Clean Architecture rules into a skill that gets loaded per-task
+3. Add a "checkpoint" mechanism: after every 5 tool calls, re-inject key rules
+4. Reduce conversation history to last 10 messages to free reasoning space
+
+### Example 3: Reduce Token Costs
+User asks: "Our agent costs are too high. Optimize the context usage."
+Response approach:
+1. Audit current context window usage with the budget calculator
+2. Compress code summaries for files the agent reads but does not modify
+3. Reduce retrieved context from k=20 to k=5 with re-ranking
+4. Shorten system prompt by moving examples to a skill file
+5. Target: 40% reduction in input tokens per invocation
+
+## Notes
+- The 45% reasoning space is sacred -- never fill more than 55% of the window with context
+- CLAUDE.md changes affect all agents -- be deliberate about what goes there
+- Skills are the pressure release valve: move detailed instructions there for on-demand loading
+- Monitor token usage per agent invocation to catch context bloat early
+- Code the agent will modify must always be included uncompressed

package/templates/bundle-ai-agents/skills/context-engineering/references/compression-techniques.md

@@ -0,0 +1,76 @@
+# Compression Techniques Reference
+
+## Technique 1: Code Skeleton
+
+Keep signatures and types, remove implementation details.
+
+**Before** (450 tokens):
+```python
+class DemandRepository:
+    def __init__(self, session: Session):
+        self._session = session
+
+    def find_by_id(self, id: DemandId) -> Demand:
+        model = self._session.query(DemandModel).filter_by(id=str(id)).first()
+        if not model:
+            raise DemandNotFoundException(id)
+        return Demand(
+            id=DemandId(model.id),
+            description=model.description,
+            status=DemandStatus(model.status),
+        )
+
+    def save(self, demand: Demand) -> None:
+        model = DemandModel(
+            id=str(demand.id),
+            description=demand.description,
+            status=demand.status.value,
+        )
+        self._session.merge(model)
+        self._session.commit()
+```
+
+**After** (120 tokens):
+```python
+class DemandRepository:
+    def __init__(self, session: Session): ...
+    def find_by_id(self, id: DemandId) -> Demand: ...  # raises DemandNotFoundException
+    def save(self, demand: Demand) -> None: ...  # merges and commits
+```
+
+## Technique 2: Summary with Key Facts
+
+For documentation, extract bullet points instead of full text.
+
+**Before**: 500-word architecture document.
+**After**: 5 bullet points with the critical decisions.
+
+## Technique 3: History Trimming
+
+Keep only the last N messages, or summarize older messages.
+
+```python
+def trim_history(messages: list, max_messages: int = 10) -> list:
+    if len(messages) <= max_messages:
+        return messages
+    # Keep system message + last N messages
+    return [messages[0]] + messages[-max_messages:]
+```
+
+## Technique 4: Selective File Loading
+
+Load only the files the agent will interact with, not the entire directory.
+
+```python
+def select_files(task_description: str, file_index: dict) -> list[str]:
+    # Use embedding similarity to find relevant files
+    relevant = retriever.invoke(task_description)
+    return [f.metadata["path"] for f in relevant[:5]]
+```
+
+## When NOT to Compress
+
+- Code the agent is about to modify (needs full context)
+- Error messages and stack traces (details matter)
+- Test files being debugged
+- Configuration files being updated

package/templates/bundle-ai-agents/skills/context-engineering/references/context-budget-calculator.md

@@ -0,0 +1,45 @@
+# Context Budget Calculator Reference
+
+## Budget Formula
+
+```
+total_available = model_context_window
+reasoning_space = total_available * 0.45  # NEVER reduce below 40%
+usable_context = total_available - reasoning_space
+
+system_prompt_budget = usable_context * 0.09    # ~5% of total
+skills_budget = usable_context * 0.18           # ~10% of total
+retrieved_context_budget = usable_context * 0.45 # ~25% of total
+history_budget = usable_context * 0.27          # ~15% of total
+```
+
+## Budget by Model
+
+| Model | Context Window | System + Skills | Retrieved | History | Reasoning |
+|---|---|---|---|---|---|
+| Claude Sonnet (200k) | 200,000 | 30,000 | 50,000 | 30,000 | 90,000 |
+| Claude Haiku (200k) | 200,000 | 30,000 | 50,000 | 30,000 | 90,000 |
+| GPT-4 Turbo (128k) | 128,000 | 19,200 | 32,000 | 19,200 | 57,600 |
+| GPT-4o (128k) | 128,000 | 19,200 | 32,000 | 19,200 | 57,600 |
+
+## Warning Signs of Context Bloat
+
+1. Agent starts ignoring rules mentioned in the system prompt -> system prompt too far back
+2. Agent repeats itself -> conversation history too long, compress or trim
+3. Agent hallucinates code structure -> retrieved context is stale or missing
+4. Agent is slow and expensive -> too much context being sent per invocation
+
+## Quick Check
+
+```python
+import tiktoken
+
+def check_budget(system_prompt, skills, retrieved, history, model_limit=200000):
+    enc = tiktoken.encoding_for_model("gpt-4")  # approximate
+    total = sum(len(enc.encode(t)) for t in [system_prompt, skills, retrieved, history])
+    usage_pct = total / model_limit * 100
+    reasoning_pct = (model_limit - total) / model_limit * 100
+    print(f"Context usage: {usage_pct:.1f}% | Reasoning space: {reasoning_pct:.1f}%")
+    if reasoning_pct < 40:
+        print("WARNING: Reasoning space below 40%. Reduce context.")
+```