maestro-bundle 1.3.1 → 1.4.0

package/templates/bundle-ai-agents/skills/testing-strategy/SKILL.md

@@ -1,27 +1,54 @@
 ---
 name: testing-strategy
-description: Implementar estratégia de testes com unitários, integração e e2e usando Pytest ou JUnit. Use quando for escrever testes, definir estratégia de testes, ou melhorar cobertura.
+description: Implement testing strategies with unit, integration, and e2e tests using Pytest or JUnit. Use when writing tests, defining test strategy, or improving test coverage.
+version: 1.0.0
+author: Maestro
 ---
 
-# Estratégia de Testes
+# Testing Strategy
 
-## Pirâmide
+Implement the testing pyramid with domain unit tests, integration tests for repositories, and e2e tests for API endpoints, following consistent naming and fixture patterns.
+
+## When to Use
+- Writing tests for new features or bug fixes
+- Setting up test infrastructure for a new project
+- Improving test coverage on existing code
+- Reviewing test quality and naming conventions
+- Configuring CI/CD test pipelines
+
+## Available Operations
+1. Write unit tests for domain entities and value objects
+2. Write integration tests for repositories and external services
+3. Write e2e tests for API endpoints
+4. Configure test fixtures and factories
+5. Run tests and measure coverage
+6. Set up test pipelines in CI/CD
+
+## Multi-Step Workflow
+
+### Step 1: Understand the Testing Pyramid
 
 ```
-        /  E2E  \          Poucos, lentos, caros
-       /  Integr. \        Moderados
-      / Unitários   \      Muitos, rápidos, baratos
+        /  E2E  \          Few, slow, expensive
+       / Integr. \         Moderate count
+      / Unit Tests \       Many, fast, cheap
 ```
 
-## Testes Unitários — Domínio
+- **Unit tests**: Test domain logic in isolation. No database, no HTTP, no external services.
+- **Integration tests**: Test adapters (repositories, clients) against real infrastructure.
+- **E2E tests**: Test full API request/response cycles.
 
-Testar regras de negócio sem infraestrutura.
+### Step 2: Write Unit Tests for Domain Entities
+
+Test business rules without any infrastructure dependency.
 
 ```python
 # tests/domain/test_demand.py
+import pytest
+
 class TestDemand:
     def test_should_decompose_new_demand(self):
-        demand = Demand(id=DemandId.generate(), description="Criar CRUD")
+        demand = Demand(id=DemandId.generate(), description="Create CRUD")
         planner = FakePlanner(tasks=[Task(...), Task(...)])
 
         tasks = demand.decompose(planner)
@@ -30,14 +57,14 @@ class TestDemand:
         assert demand.status == DemandStatus.PLANNED
 
     def test_should_reject_decompose_if_already_planned(self):
-        demand = Demand(id=DemandId.generate(), description="Criar CRUD")
+        demand = Demand(id=DemandId.generate(), description="Create CRUD")
         demand.decompose(FakePlanner(tasks=[Task(...)]))
 
         with pytest.raises(DemandAlreadyDecomposedException):
             demand.decompose(FakePlanner(tasks=[]))
 
     def test_should_not_allow_more_than_20_tasks(self):
-        demand = Demand(id=DemandId.generate(), description="Mega projeto")
+        demand = Demand(id=DemandId.generate(), description="Mega project")
         for i in range(20):
             demand.add_task(Task(...))
 
@@ -45,9 +72,10 @@ class TestDemand:
             demand.add_task(Task(...))
 ```
 
-## Testes Unitários — Value Objects
+### Step 3: Write Unit Tests for Value Objects
 
 ```python
+# tests/domain/test_compliance_score.py
 class TestComplianceScore:
     def test_passing_score(self):
         score = ComplianceScore(85.0)
@@ -62,10 +90,16 @@ class TestComplianceScore:
             ComplianceScore(150.0)
 ```
 
-## Testes de Integração — Repositórios
+### Step 4: Write Integration Tests for Repositories
+
+Test against a real database using fixtures with rollback.
 
 ```python
 # tests/infrastructure/test_pg_demand_repository.py
+import pytest
+from sqlalchemy import create_engine
+from sqlalchemy.orm import Session
+
 @pytest.fixture
 def db_session():
     engine = create_engine(TEST_DATABASE_URL)
@@ -84,12 +118,87 @@ class TestPgDemandRepository:
         assert found.description == "Test"
 ```
 
-## Naming
+### Step 5: Run Tests and Measure Coverage
+
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run only unit tests
+pytest tests/domain/ -v
+
+# Run only integration tests
+pytest tests/infrastructure/ -v --timeout=30
 
+# Run with coverage report
+pytest tests/ --cov=src --cov-report=term-missing --cov-fail-under=80
+
+# Run specific test file
+pytest tests/domain/test_demand.py -v
+
+# Run tests matching a pattern
+pytest tests/ -k "test_should_decompose" -v
 ```
-test_should_<resultado>_when_<condição>
 
-test_should_return_error_when_email_is_invalid
-test_should_decompose_demand_when_status_is_created
-test_should_reject_merge_when_conflicts_exist
+### Step 6: Set Up CI/CD Test Pipeline
+
+```yaml
+test:
+  stage: test
+  script:
+    - pip install -r requirements-test.txt
+    - pytest tests/domain/ -v --junitxml=reports/unit.xml
+    - pytest tests/infrastructure/ -v --junitxml=reports/integration.xml --timeout=60
+    - pytest tests/ --cov=src --cov-report=xml --cov-fail-under=80
+  artifacts:
+    reports:
+      junit:
+        - reports/*.xml
+      coverage_report:
+        coverage_format: cobertura
+        path: coverage.xml
 ```
+
+## Resources
+- `references/naming-conventions.md` - Test naming patterns and organization guidelines
+- `references/fixture-patterns.md` - Common pytest fixture patterns and factories
+
+## Examples
+
+### Example 1: Write Tests for a New Feature
+User asks: "Write tests for the new user registration feature."
+Response approach:
+1. Unit test the `User` entity: valid creation, email validation, password rules
+2. Unit test the `RegisterUser` use case: happy path, duplicate email, invalid data
+3. Integration test the `PgUserRepository`: save and find
+4. E2e test the `POST /api/v1/users` endpoint: 201 on success, 422 on invalid data
+5. Run: `pytest tests/ -v --cov=src`
+
+### Example 2: Improve Test Coverage
+User asks: "Our coverage is at 45%. Get it to 80%."
+Response approach:
+1. Run `pytest --cov=src --cov-report=term-missing` to find uncovered lines
+2. Prioritize domain layer (business rules are the most valuable to test)
+3. Add edge case tests for existing entities (error paths, boundary values)
+4. Add integration tests for untested repositories
+5. Skip e2e tests for now (lowest ROI per coverage point)
+6. Target: domain 95%, application 85%, infrastructure 70%
+
+### Example 3: Set Up Testing for a New Project
+User asks: "Set up the test infrastructure for our new Python project."
+Response approach:
+1. Install dependencies: `pip install pytest pytest-cov pytest-asyncio`
+2. Create `conftest.py` with database session fixtures
+3. Create directory structure: `tests/domain/`, `tests/application/`, `tests/infrastructure/`, `tests/api/`
+4. Add `pytest.ini` or `pyproject.toml` with test configuration
+5. Create a sample test to verify the setup
+6. Add test commands to Makefile or scripts
+
+## Notes
+- Follow the naming convention: `test_should_<result>_when_<condition>`
+- Unit tests must run without any external dependencies (no DB, no HTTP)
+- Use fakes/stubs for dependencies in unit tests, not mocks (fakes are more maintainable)
+- Integration tests should roll back database changes after each test
+- Coverage threshold: 80% minimum, but focus on testing business rules, not getters/setters
+- Run unit tests first in CI (fast feedback), integration tests second, e2e last
+- Each test should test one behavior -- avoid testing multiple things in a single test

package/templates/bundle-ai-agents/skills/testing-strategy/references/fixture-patterns.md

@@ -0,0 +1,81 @@
+# Fixture Patterns Reference
+
+## Database Session Fixture (with rollback)
+
+```python
+@pytest.fixture
+def db_session():
+    engine = create_engine(TEST_DATABASE_URL)
+    connection = engine.connect()
+    transaction = connection.begin()
+    session = Session(bind=connection)
+
+    yield session
+
+    session.close()
+    transaction.rollback()
+    connection.close()
+```
+
+## Factory Fixtures
+
+```python
+@pytest.fixture
+def make_demand():
+    def _make(
+        description: str = "Test demand",
+        status: DemandStatus = DemandStatus.CREATED,
+    ) -> Demand:
+        return Demand(
+            id=DemandId.generate(),
+            description=description,
+            status=status,
+        )
+    return _make
+
+# Usage in test
+def test_something(make_demand):
+    demand = make_demand(description="Custom demand")
+```
+
+## Async Fixtures
+
+```python
+@pytest.fixture
+async def async_client(app):
+    async with AsyncClient(app=app, base_url="http://test") as client:
+        yield client
+```
+
+## Fake Implementations
+
+```python
+class FakeDemandRepository(DemandRepository):
+    def __init__(self):
+        self._demands: dict[str, Demand] = {}
+
+    def find_by_id(self, id: DemandId) -> Demand:
+        demand = self._demands.get(str(id))
+        if not demand:
+            raise DemandNotFoundException(id)
+        return demand
+
+    def save(self, demand: Demand) -> None:
+        self._demands[str(demand.id)] = demand
+
+class FakeEventBus(EventBus):
+    def __init__(self):
+        self.published_events: list[DomainEvent] = []
+
+    def publish(self, event: DomainEvent) -> None:
+        self.published_events.append(event)
+```
+
+## Fixture Scoping
+
+| Scope | Lifecycle | Use For |
+|---|---|---|
+| `function` (default) | Each test | Most fixtures |
+| `class` | Each test class | Shared setup within a class |
+| `module` | Each test file | Expensive setup (DB schema) |
+| `session` | Entire test run | One-time setup (create DB) |

package/templates/bundle-ai-agents/skills/testing-strategy/references/naming-conventions.md

@@ -0,0 +1,69 @@
+# Test Naming Conventions Reference
+
+## Test Method Naming
+
+```
+test_should_<expected_result>_when_<condition>
+```
+
+### Examples
+
+```python
+# Good names
+test_should_return_error_when_email_is_invalid
+test_should_decompose_demand_when_status_is_created
+test_should_reject_merge_when_conflicts_exist
+test_should_create_user_when_data_is_valid
+test_should_raise_not_found_when_id_does_not_exist
+
+# Bad names
+test_demand()          # What about demand?
+test_error()           # What error? When?
+test_create()          # Create what? Under what condition?
+test_1()               # Meaningless
+```
+
+## Test Class Naming
+
+```python
+class TestDemand:           # Domain entity tests
+class TestDecomposeDemand:  # Use case tests
+class TestPgDemandRepository:  # Repository integration tests
+class TestDemandEndpoints:  # API e2e tests
+```
+
+## File Organization
+
+```
+tests/
+  domain/
+    test_demand.py
+    test_task.py
+    test_compliance_score.py
+  application/
+    test_decompose_demand.py
+    test_create_demand.py
+  infrastructure/
+    test_pg_demand_repository.py
+    test_pg_task_repository.py
+  api/
+    test_demand_endpoints.py
+    test_task_endpoints.py
+  conftest.py              # Shared fixtures
+```
+
+## Test Structure (AAA Pattern)
+
+```python
+def test_should_decompose_demand_when_status_is_created(self):
+    # Arrange
+    demand = Demand(id=DemandId.generate(), description="Create CRUD")
+    planner = FakePlanner(tasks=[Task(...)])
+
+    # Act
+    tasks = demand.decompose(planner)
+
+    # Assert
+    assert len(tasks) == 1
+    assert demand.status == DemandStatus.PLANNED
+```

package/templates/bundle-base/skills/branch-strategy/SKILL.md

@@ -1,42 +1,155 @@
 ---
 name: branch-strategy
-description: Criar e gerenciar branches seguindo a estratégia Git da organização. Use quando for criar branch, iniciar uma feature, ou organizar o fluxo de branches.
+description: Create and manage Git branches following the organization's branching strategy. Use when creating branches, starting features, managing releases, or organizing Git workflow.
+version: 1.0.0
+author: Maestro
 ---
 
-# Estratégia de Branches Maestro
+# Branch Strategy
 
-## Branches permanentes
+Create and manage Git branches following the Maestro branching strategy with permanent and temporary branches.
 
-| Branch | Propósito | Proteção |
-|---|---|---|
-| `main` | Código em produção | Protegida, só via MR aprovado |
-| `develop` | Integração de features | Protegida, MR com 1+ reviewer |
+## When to Use
+- When creating a new feature branch
+- When starting a bug fix or hotfix
+- When preparing a release
+- When merging branches or resolving conflicts
+- When setting up agent worktrees
+
+## Available Operations
+1. Create a feature branch
+2. Create a fix/hotfix branch
+3. Create a release branch
+4. Rebase and prepare for merge request
+5. Set up agent worktree with isolated branch
 
-## Branches temporárias
+## Multi-Step Workflow
 
-| Padrão | Exemplo | Origem | Destino |
+### Step 1: Identify Branch Type
+
+| Pattern | Example | Origin | Target |
 |---|---|---|---|
-| `feature/<modulo>-<desc>` | `feature/demands-auto-decompose` | `develop` | `develop` |
-| `fix/<modulo>-<desc>` | `fix/agents-timeout-skill` | `develop` | `develop` |
+| `feature/<module>-<desc>` | `feature/demands-auto-decompose` | `develop` | `develop` |
+| `fix/<module>-<desc>` | `fix/agents-timeout-skill` | `develop` | `develop` |
 | `hotfix/<desc>` | `hotfix/fix-login-crash` | `main` | `main` + `develop` |
-| `release/<versao>` | `release/1.2.0` | `develop` | `main` + `develop` |
+| `release/<version>` | `release/1.2.0` | `develop` | `main` + `develop` |
+
+Permanent branches:
+
+| Branch | Purpose | Protection |
+|---|---|---|
+| `main` | Production code | Protected, merge only via approved MR |
+| `develop` | Feature integration | Protected, MR with 1+ reviewer |
+
+### Step 2: Create the Branch
+
+```bash
+# Feature branch
+git checkout develop
+git pull origin develop
+git checkout -b feature/demands-auto-decompose
 
-## Fluxo para agentes do Maestro
+# Fix branch
+git checkout develop
+git pull origin develop
+git checkout -b fix/agents-timeout-skill
 
-Cada agente trabalha em worktree isolada com seu próprio branch:
+# Hotfix branch (from main)
+git checkout main
+git pull origin main
+git checkout -b hotfix/fix-login-crash
 
+# Release branch
+git checkout develop
+git pull origin develop
+git checkout -b release/1.2.0
+```
+
+### Step 3: Work and Commit
+Follow the commit-pattern skill for commit messages.
+
+```bash
+git add <files>
+git commit -m "feat(demands): adicionar decomposicao automatica de tasks"
+```
+
+### Step 4: Rebase Before Merge Request
+
+```bash
+git fetch origin
+git rebase origin/develop
+# Resolve conflicts if any, then:
+git rebase --continue
+```
+
+### Step 5: Push and Create Merge Request
+
+```bash
+git push origin feature/demands-auto-decompose
+# Create MR via GitLab/GitHub UI or CLI
+```
+
+### Step 6: Clean Up After Merge
+
+```bash
+git checkout develop
+git pull origin develop
+git branch -d feature/demands-auto-decompose
+git push origin --delete feature/demands-auto-decompose
+```
+
+### Agent Worktree Flow
+For Maestro agents working in isolated worktrees:
+
+```bash
+# Create worktree for agent
+git worktree add ../agent-frontend-workspace feature/agent-frontend-<task-id>
+
+# Agent works in its worktree
+cd ../agent-frontend-workspace
+# ... make changes, commit ...
+
+# Remove worktree after merge
+git worktree remove ../agent-frontend-workspace
+```
+
+Agent branch naming:
 ```
 feature/agent-frontend-<task-id>
 feature/agent-backend-<task-id>
 feature/agent-devops-<task-id>
 ```
 
-O agente orquestrador faz o merge após aprovação humana.
+## Resources
+- `references/branch-rules.md` - Branch naming rules and protection policies
+
+## Examples
+### Example 1: Start a New Feature
+User asks: "Create a branch for the new dashboard feature"
+Response approach:
+1. Run `git checkout develop && git pull origin develop`
+2. Run `git checkout -b feature/dashboard-metrics`
+3. Confirm branch created with `git branch --show-current`
+
+### Example 2: Hotfix in Production
+User asks: "We need to fix a critical login bug in production"
+Response approach:
+1. Run `git checkout main && git pull origin main`
+2. Run `git checkout -b hotfix/fix-login-crash`
+3. After fix, merge to both `main` and `develop`
 
-## Regras
+### Example 3: Prepare for Merge
+User asks: "My feature is ready, prepare it for review"
+Response approach:
+1. Run `git fetch origin && git rebase origin/develop`
+2. Resolve any conflicts
+3. Run `git push origin feature/<branch-name>`
+4. Guide user to create the MR
 
-1. Nunca commitar direto na `main` ou `develop`
-2. Branches de feature vivem no máximo 5 dias
-3. Rebase antes de abrir MR (manter histórico limpo)
-4. Deletar branch após merge
-5. Um branch = uma task/issue
+## Notes
+- Never commit directly to `main` or `develop`
+- Feature branches should live at most 5 days
+- Always rebase before opening MR to keep clean history
+- Delete branch after merge
+- One branch = one task/issue
+- The orchestrator agent handles merge after human approval

package/templates/bundle-base/skills/branch-strategy/references/branch-rules.md

@@ -0,0 +1,40 @@
+# Branch Rules Reference
+
+## Naming Convention
+```
+feature/<module>-<short-description>
+fix/<module>-<short-description>
+hotfix/<short-description>
+release/<semver>
+```
+
+## Branch Lifecycle
+1. Create from correct base branch
+2. Work and commit (max 5 days for features)
+3. Rebase onto latest base before MR
+4. Open Merge Request with 1+ reviewer
+5. Merge after approval
+6. Delete branch after merge
+
+## Protection Rules
+| Branch | Direct Push | MR Required | Reviewers |
+|---|---|---|---|
+| `main` | No | Yes | 2+ |
+| `develop` | No | Yes | 1+ |
+| `feature/*` | Yes | N/A | N/A |
+| `release/*` | Yes | Yes (to main) | 2+ |
+
+## Agent Worktree Branches
+```
+feature/agent-frontend-<task-id>
+feature/agent-backend-<task-id>
+feature/agent-devops-<task-id>
+```
+- Each agent works in an isolated Git worktree
+- Orchestrator merges after human approval
+- Worktree is removed after merge
+
+## Merge Strategy
+- Feature/Fix to develop: Squash merge (clean history)
+- Release to main: Merge commit (preserve history)
+- Hotfix to main: Merge commit, then cherry-pick to develop