maestro-bundle 1.0.0

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

@@ -0,0 +1,66 @@
+---
+name: prompt-engineering
+description: Criar e otimizar system prompts para agentes seguindo melhores práticas de context engineering. Use quando precisar escrever prompts, melhorar prompts existentes, ou criar instruções para agentes.
+---
+
+# Prompt Engineering para Agentes
+
+## Estrutura de System Prompt
+
+```
+1. IDENTIDADE — Quem o agente é
+2. OBJETIVO — O que ele deve alcançar
+3. FERRAMENTAS — O que tem disponível
+4. REGRAS — Limites inegociáveis
+5. FORMATO — Como estruturar a saída
+6. EXEMPLOS — Demonstrações concretas
+```
+
+## Template
+
+```python
+SYSTEM_PROMPT = """
+## Identidade
+Você é {role}, especializado em {especialidade}.
+
+## Objetivo
+Sua missão é {objetivo_principal}. Você trabalha dentro do Maestro,
+uma plataforma de governança de desenvolvimento.
+
+## Ferramentas disponíveis
+{lista_de_tools_com_descrição}
+
+## Regras
+1. Sempre seguir o bundle {bundle_name} para padrões de código
+2. Todo commit deve referenciar a task: {task_id}
+3. Trabalhar apenas na worktree designada: {worktree_path}
+4. Reportar progresso a cada etapa significativa
+5. Solicitar human review para operações destrutivas
+
+## Formato de resposta
+- Para código: blocos com linguagem especificada
+- Para decisões: justificar com "porquê"
+- Para erros: incluir contexto e sugestão de fix
+
+## Exemplo
+Task: "Criar endpoint GET /api/v1/demands"
+Ação: Criar controller, use case, repository seguindo Clean Architecture
+Branch: feature/backend-{task_id}
+"""
+```
+
+## Boas práticas
+
+1. **Seja específico** — "Crie uma API REST com FastAPI" > "Crie uma API"
+2. **Explique o porquê** — "Usar Value Objects porque garantem validação no construtor" > "Usar Value Objects"
+3. **Dê exemplos** — Um bom exemplo vale mais que 10 linhas de instrução
+4. **Evite negativos** — "Mantenha funções com até 20 linhas" > "Não crie funções longas"
+5. **Priorize** — Coloque as regras mais importantes primeiro
+6. **Teste** — Rode o prompt com cenários reais antes de deployar
+
+## Anti-patterns
+
+- NEVER/ALWAYS em excesso (perde a força)
+- Instruções contraditórias
+- Prompts com 5000+ palavras (o agente se perde)
+- Regras sem justificativa (o agente não sabe quando flexibilizar)

package/templates/bundle-ai-agents/skills/rag-pipeline/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: rag-pipeline
+description: Construir pipeline RAG completo com ingestão, chunking, embedding, indexação e retrieval usando LangChain + pgvector. Use sempre que precisar implementar busca semântica, responder perguntas sobre documentos, ou criar um sistema de retrieval.
+---
+
+# RAG Pipeline
+
+## Pipeline completo
+
+```
+Documentos → Loader → Splitter → Embeddings → pgvector → Retriever → Re-ranker → LLM
+```
+
+## 1. Ingestão
+
+```python
+from langchain_community.document_loaders import DirectoryLoader, UnstructuredMarkdownLoader
+from langchain.text_splitter import RecursiveCharacterTextSplitter
+
+# Loader por tipo de documento
+loader = DirectoryLoader(
+    "./documents/",
+    glob="**/*.md",
+    loader_cls=UnstructuredMarkdownLoader
+)
+docs = loader.load()
+
+# Splitter com separadores Markdown
+splitter = RecursiveCharacterTextSplitter(
+    chunk_size=1000,
+    chunk_overlap=200,
+    separators=["\n## ", "\n### ", "\n\n", "\n", ". ", " "]
+)
+chunks = splitter.split_documents(docs)
+```
+
+## 2. Metadados obrigatórios
+
+Cada chunk deve ter:
+```python
+for chunk in chunks:
+    chunk.metadata.update({
+        "source": chunk.metadata.get("source", "unknown"),
+        "doc_type": classify_document(chunk),  # skill, agent_md, prd, code
+        "language": detect_language(chunk),
+        "created_at": datetime.now().isoformat(),
+    })
+```
+
+## 3. Embedding + Indexação
+
+```python
+from langchain_openai import OpenAIEmbeddings
+from langchain_postgres import PGVector
+
+embeddings = OpenAIEmbeddings(model="text-embedding-3-large", dimensions=1536)
+
+vectorstore = PGVector(
+    collection_name="documents",
+    connection=DATABASE_URL,
+    embedding_function=embeddings,
+)
+vectorstore.add_documents(chunks)
+```
+
+## 4. Retrieval Híbrido
+
+```python
+from langchain.retrievers import EnsembleRetriever
+from langchain_community.retrievers import BM25Retriever
+
+# Semântico
+semantic_retriever = vectorstore.as_retriever(search_kwargs={"k": 20})
+
+# Keyword
+bm25_retriever = BM25Retriever.from_documents(chunks, k=20)
+
+# Ensemble com RRF
+hybrid_retriever = EnsembleRetriever(
+    retrievers=[semantic_retriever, bm25_retriever],
+    weights=[0.6, 0.4]
+)
+```
+
+## 5. Re-ranking
+
+```python
+from langchain.retrievers import ContextualCompressionRetriever
+from langchain_cohere import CohereRerank
+
+reranker = CohereRerank(top_n=5)
+final_retriever = ContextualCompressionRetriever(
+    base_compressor=reranker,
+    base_retriever=hybrid_retriever
+)
+```
+
+## 6. Query Chain
+
+```python
+from langchain_core.prompts import ChatPromptTemplate
+from langchain_core.output_parsers import StrOutputParser
+
+prompt = ChatPromptTemplate.from_template("""
+Responda a pergunta baseado apenas no contexto fornecido.
+Se a resposta não estiver no contexto, diga "Não encontrei essa informação".
+
+Contexto: {context}
+Pergunta: {question}
+""")
+
+chain = (
+    {"context": final_retriever, "question": RunnablePassthrough()}
+    | prompt
+    | llm
+    | StrOutputParser()
+)
+
+result = chain.invoke("Qual skill usar para criar componentes React?")
+```
+
+## Checklist de qualidade
+
+- [ ] Chunks testados com perguntas reais
+- [ ] Metadados completos em todos os chunks
+- [ ] Retrieval quality medido com golden dataset
+- [ ] Re-ranking ativo para refinar top-k
+- [ ] Fallback para quando retrieval não encontra nada

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

@@ -0,0 +1,95 @@
+---
+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.
+---
+
+# Estratégia de Testes
+
+## Pirâmide
+
+```
+        /  E2E  \          Poucos, lentos, caros
+       /  Integr. \        Moderados
+      / Unitários   \      Muitos, rápidos, baratos
+```
+
+## Testes Unitários — Domínio
+
+Testar regras de negócio sem infraestrutura.
+
+```python
+# tests/domain/test_demand.py
+class TestDemand:
+    def test_should_decompose_new_demand(self):
+        demand = Demand(id=DemandId.generate(), description="Criar CRUD")
+        planner = FakePlanner(tasks=[Task(...), Task(...)])
+
+        tasks = demand.decompose(planner)
+
+        assert len(tasks) == 2
+        assert demand.status == DemandStatus.PLANNED
+
+    def test_should_reject_decompose_if_already_planned(self):
+        demand = Demand(id=DemandId.generate(), description="Criar 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")
+        for i in range(20):
+            demand.add_task(Task(...))
+
+        with pytest.raises(TooManyTasksException):
+            demand.add_task(Task(...))
+```
+
+## Testes Unitários — Value Objects
+
+```python
+class TestComplianceScore:
+    def test_passing_score(self):
+        score = ComplianceScore(85.0)
+        assert score.is_passing() is True
+
+    def test_failing_score(self):
+        score = ComplianceScore(60.0)
+        assert score.is_passing() is False
+
+    def test_invalid_score_raises(self):
+        with pytest.raises(ValueError):
+            ComplianceScore(150.0)
+```
+
+## Testes de Integração — Repositórios
+
+```python
+# tests/infrastructure/test_pg_demand_repository.py
+@pytest.fixture
+def db_session():
+    engine = create_engine(TEST_DATABASE_URL)
+    with Session(engine) as session:
+        yield session
+        session.rollback()
+
+class TestPgDemandRepository:
+    def test_should_save_and_find_demand(self, db_session):
+        repo = PgDemandRepository(db_session)
+        demand = Demand(id=DemandId.generate(), description="Test")
+
+        repo.save(demand)
+        found = repo.find_by_id(demand.id)
+
+        assert found.description == "Test"
+```
+
+## Naming
+
+```
+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
+```

package/templates/bundle-base/AGENTS.md

@@ -0,0 +1,118 @@
+# Bundle Base — Padrões da Organização
+
+Este é o bundle base que TODOS os desenvolvedores devem usar. Ele define os padrões inegociáveis da organização.
+
+## Quem você é
+
+Você é um assistente de desenvolvimento que segue rigorosamente os padrões da organização. Todo código produzido deve aderir às convenções abaixo.
+
+## Padrões de Código
+
+### Geral
+- Máximo de 500 linhas por arquivo
+- Funções com no máximo 20 linhas
+- Nomes de variáveis e funções descritivos (nunca `d`, `x`, `tmp`)
+- Usar funções nativas da linguagem para manipulação de strings
+- Evitar ifs aninhados (hadouken) — usar early returns e guard clauses
+- Tratar fluxos de exceção, não só o caminho feliz
+- Não deixar código morto, comentários TODO sem prazo, ou prints de debug
+
+### Python
+- Usar f-strings para interpolação
+- Type hints em todas as funções públicas
+- Docstrings apenas em funções complexas (não óbvias)
+- Black para formatação, Ruff para linting
+
+### TypeScript
+- Strict mode habilitado
+- Interfaces sobre types quando possível
+- Async/await sobre .then()
+
+### Java
+- Seguir convenções do Google Java Style Guide
+- Records para DTOs imutáveis
+- Optional ao invés de null
+
+## Padrões de Git
+
+### Branches
+- `main` — produção, protegida
+- `develop` — integração
+- `feature/<escopo>-<descricao>` — novas funcionalidades
+- `fix/<escopo>-<descricao>` — correções
+- `hotfix/<descricao>` — correções urgentes em produção
+
+### Commits
+Formato: `<tipo>(<escopo>): <descrição>`
+
+Tipos permitidos:
+- `feat` — nova funcionalidade
+- `fix` — correção de bug
+- `refactor` — refatoração sem mudança de comportamento
+- `docs` — documentação
+- `test` — adição ou correção de testes
+- `chore` — tarefas de manutenção
+- `ci` — mudanças em CI/CD
+
+Exemplos:
+```
+feat(auth): implementar autenticação JWT
+fix(api): corrigir timeout na busca de usuários
+refactor(domain): extrair value object para CPF
+```
+
+### Pull Requests
+- Título curto (< 70 caracteres)
+- Descrição com: resumo, motivação, como testar
+- Sempre vincular à task/issue
+- Mínimo 1 reviewer
+
+## Segurança
+
+- NUNCA commitar secrets (.env, credentials, API keys)
+- Rate limiting em todas as APIs
+- Validar inputs em fronteiras do sistema (API, UI)
+- Seguir OWASP Top 10
+- HTTPS obrigatório
+
+## Testes
+
+- Cobertura mínima: 80% no código de domínio
+- Testes unitários para regras de negócio
+- Testes de integração para repositórios e APIs
+- Nomear testes descritivamente: `should_return_error_when_email_is_invalid`
+
+## Estrutura de Projeto
+
+Organizar por domínio/feature, não por tipo técnico:
+
+```
+# BOM — por domínio
+src/
+├── demands/
+├── bundles/
+├── agents/
+└── tracking/
+
+# RUIM — por camada técnica
+src/
+├── controllers/
+├── services/
+├── repositories/
+└── models/
+```
+
+## Documentação
+
+- README.md na raiz com: propósito, como rodar, como testar
+- ADRs para decisões arquiteturais significativas
+- Diagramas como código (Mermaid) versionados no repo
+
+## O que NÃO fazer
+
+- Não usar `any` em TypeScript
+- Não ignorar erros com try/catch vazio
+- Não fazer push direto na main
+- Não criar utils/helpers genéricos "para o futuro"
+- Não instalar dependências sem justificativa
+- Não fazer "vibing coding" — sempre ter uma task/spec associada

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

@@ -0,0 +1,42 @@
+---
+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.
+---
+
+# Estratégia de Branches Maestro
+
+## Branches permanentes
+
+| 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 |
+
+## Branches temporárias
+
+| Padrão | Exemplo | Origem | Destino |
+|---|---|---|---|
+| `feature/<modulo>-<desc>` | `feature/demands-auto-decompose` | `develop` | `develop` |
+| `fix/<modulo>-<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` |
+
+## Fluxo para agentes do Maestro
+
+Cada agente trabalha em worktree isolada com seu próprio branch:
+
+```
+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.
+
+## Regras
+
+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

package/templates/bundle-base/skills/code-review/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: code-review
+description: Revisar código seguindo os padrões da organização. Use quando for revisar um PR, avaliar qualidade de código, ou quando o desenvolvedor pedir review.
+---
+
+# Code Review — Padrões da organização
+
+## Checklist de Review
+
+### 1. Correção
+- O código faz o que a task/spec pede?
+- Os edge cases estão cobertos?
+- Os fluxos de exceção estão tratados?
+
+### 2. Qualidade
+- Arquivos com mais de 500 linhas? Dividir.
+- Funções com mais de 20 linhas? Extrair.
+- Ifs aninhados (hadouken)? Usar early return.
+- Nomes descritivos? (`calculateComplianceScore` > `calc`)
+- Código duplicado? Extrair se repetir 3+ vezes.
+- Código morto? Remover.
+
+### 3. Segurança
+- Inputs validados nas fronteiras?
+- Secrets hardcoded? REJEITAR.
+- SQL injection possível? Usar parameterized queries.
+- Rate limiting presente nas APIs?
+
+### 4. Testes
+- Testes unitários para regras de negócio?
+- Nomes de testes descritivos?
+- Testes cobrem caminho feliz E fluxos alternativos?
+
+### 5. Padrões
+- Commit segue Conventional Commits?
+- Branch segue nomenclatura?
+- Estrutura de diretórios por domínio?
+- Linguagem ubíqua do projeto respeitada?
+
+## Formato do Feedback
+
+Categorizar cada comentário:
+
+- **[BLOCKER]** — Deve ser corrigido antes do merge
+- **[SUGGESTION]** — Melhoria recomendada, não obrigatória
+- **[QUESTION]** — Dúvida sobre a intenção do código
+- **[PRAISE]** — Algo bem feito que vale destacar
+
+Exemplo:
+```
+[BLOCKER] linha 45: API key hardcoded. Mover para variável de ambiente.
+[SUGGESTION] linha 120: Esse if aninhado ficaria mais legível com early return.
+[PRAISE] Boa extração do value object ComplianceScore.
+```

package/templates/bundle-base/skills/commit-pattern/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: commit-pattern
+description: Gerar mensagens de commit seguindo o padrão Conventional Commits da organização. Use sempre que for fazer um commit, commitar mudanças, ou precisar de uma mensagem de commit.
+---
+
+# Padrão de Commit Maestro
+
+## Formato
+
+```
+<tipo>(<escopo>): <descrição imperativa em português>
+```
+
+## Tipos
+
+| Tipo | Quando usar |
+|---|---|
+| `feat` | Nova funcionalidade para o usuário |
+| `fix` | Correção de bug |
+| `refactor` | Mudança de código que não altera comportamento |
+| `docs` | Mudanças apenas em documentação |
+| `test` | Adição ou correção de testes |
+| `chore` | Build, deps, configs, tarefas de manutenção |
+| `ci` | Mudanças em CI/CD (pipelines, workflows) |
+| `perf` | Melhoria de performance |
+
+## Regras
+
+1. Descrição no imperativo: "adicionar", não "adicionado" ou "adicionando"
+2. Primeira letra minúscula
+3. Sem ponto final
+4. Máximo 72 caracteres na primeira linha
+5. Escopo é o módulo/feature afetada
+6. Se a mudança quebra compatibilidade, adicionar `BREAKING CHANGE:` no corpo
+
+## Exemplos
+
+```
+feat(demands): adicionar decomposição automática de tasks
+fix(agents): corrigir timeout na execução de skill
+refactor(bundles): extrair validação para value object
+test(tracking): adicionar testes para eventos MCP
+docs(readme): atualizar instruções de instalação
+chore(deps): atualizar langchain para 0.3.x
+ci(gitlab): adicionar stage de compliance check
+```
+
+## Corpo (opcional)
+
+Para mudanças complexas, adicionar corpo explicando o **porquê**:
+
+```
+refactor(orchestrator): simplificar alocação de agentes
+
+A alocação anterior usava um loop O(n²) comparando todos os agentes
+com todas as tasks. Agora usa um mapa indexado por tipo de agente,
+reduzindo para O(n).
+```

package/templates/bundle-data-pipeline/.spec/constitution.md

@@ -0,0 +1,32 @@
+# Constitution — Projeto Pipeline de Dados e ML
+
+## Princípios
+
+1. **Spec primeiro, código depois** — Toda demanda passa pelo fluxo SDD antes de implementação
+2. **Dados originais são imutáveis** — Nunca editar dados em `raw/`
+3. **Reprodutibilidade** — Todo pipeline deve ser reproduzível com mesma entrada = mesma saída
+4. **Baseline obrigatório** — Todo modelo precisa de baseline para comparação
+5. **Notebook para exploração, script para produção** — Refatorar antes de merge
+
+## Padrões de desenvolvimento
+
+- Python 3.11+, type hints, Black + Ruff
+- Funções puras para transformações (input → output)
+- Validação de schema em cada etapa (Pandera)
+- Versionamento de datasets com DVC
+- Experiment tracking com MLflow
+
+## Padrões de ML
+
+- Cross-validation k=5 mínimo
+- Métricas documentadas no MLflow
+- Feature importance registrada
+- Random seed consistente
+- A/B testing antes de substituir modelo
+
+## Padrões de qualidade
+
+- Testes de schema para transformações
+- Testes de regressão para métricas
+- Cobertura mínima: 80% em pipelines
+- Commits seguem Conventional Commits