@maestro-ai/cli 1.0.0

package/content/prompts/apis/versionamento.md

@@ -0,0 +1,313 @@
+# Prompt: Versionamento de APIs
+
+> **Prioridade**: 🟠 ALTA  
+> **Aplicável a**: APIs públicas, integrações com terceiros, sistemas com múltiplos clientes
+
+---
+
+## Por que Versionar?
+
+- **Breaking changes** sem quebrar clientes existentes
+- **Deprecação gradual** de funcionalidades
+- **Múltiplas versões** em produção simultaneamente
+- **Contratos estáveis** para integradores
+
+---
+
+## Estratégias de Versionamento
+
+| Estratégia | Exemplo | Prós | Contras |
+|------------|---------|------|---------|
+| **URL Path** | `/v1/users` | Simples, cache-friendly | Mudança de URL |
+| **Query Param** | `/users?version=1` | Fácil de adicionar | Menos RESTful |
+| **Header** | `Accept: application/vnd.api.v1+json` | Não polui URL | Menos visível |
+| **Content Negotiation** | `Accept: application/vnd.company.v2+json` | Padrão HTTP | Mais complexo |
+
+---
+
+## Prompt Base: Estratégia de Versionamento
+
+```text
+Atue como arquiteto de APIs.
+
+Estou criando uma API com as seguintes características:
+- Tipo: [REST/GraphQL]
+- Clientes: [internos/externos/públicos]
+- Frequência de breaking changes esperada: [alta/média/baixa]
+- Suporte simultâneo de versões: [ex. 2 versões, 6 meses]
+
+Recomende uma estratégia de versionamento considerando:
+
+1. **Mecanismo de Versão**
+   - URL path, header, query param, ou híbrido
+   - Justificativa para o contexto
+
+2. **Política de Deprecação**
+   - Quanto tempo uma versão é suportada?
+   - Como comunicar deprecação aos clientes?
+   - Headers de deprecação
+
+3. **O que constitui uma nova versão?**
+   - Breaking vs non-breaking changes
+   - Quando incrementar major/minor
+
+4. **Implementação**
+   - Estrutura de código para múltiplas versões
+   - Como compartilhar lógica entre versões
+   - Testes por versão
+
+5. **Documentação**
+   - OpenAPI por versão ou unificado?
+   - Changelog entre versões
+```
+
+---
+
+## Prompt: Implementar Versionamento
+
+```text
+Tenho uma API existente que precisa de versionamento:
+[COLE ESTRUTURA DE ENDPOINTS ATUAL]
+
+Stack: [ex. Node.js + Express / Java + Spring]
+
+Estratégia escolhida: [URL Path / Header / etc]
+
+Gere:
+1. Middleware/interceptor para roteamento de versões
+2. Estrutura de pastas para organizar versões
+3. Exemplo de endpoint com v1 e v2
+4. Headers de deprecação (Sunset, Deprecation)
+5. Testes para verificar compatibilidade
+```
+
+---
+
+## Prompt: Migrar de v1 para v2
+
+```text
+Tenho esta API v1:
+[COLE ENDPOINTS E SCHEMAS]
+
+Preciso criar v2 com estas mudanças:
+[DESCREVA BREAKING CHANGES]
+
+Gere:
+1. API v2 com as mudanças
+2. Estratégia de migração para clientes
+3. Período de dual-support recomendado
+4. Guia de migração para documentação
+5. Headers para comunicar deprecação de v1
+```
+
+---
+
+## Headers de Deprecação (RFC 8594)
+
+```http
+HTTP/1.1 200 OK
+Deprecation: @1735689600
+Sunset: Sat, 01 Jan 2025 00:00:00 GMT
+Link: <https://api.example.com/docs/v2>; rel="successor-version"
+```
+
+| Header | Significado |
+|--------|-------------|
+| `Deprecation` | Timestamp Unix de quando foi marcado como deprecated |
+| `Sunset` | Data após a qual não será mais disponível |
+| `Link: rel="successor-version"` | Link para nova versão |
+
+---
+
+## Exemplo: Versionamento por URL (Node.js + Express)
+
+```typescript
+// src/app.ts
+import express from 'express';
+import v1Router from './routes/v1';
+import v2Router from './routes/v2';
+
+const app = express();
+
+// Versionamento por URL
+app.use('/api/v1', v1Router);
+app.use('/api/v2', v2Router);
+
+// Fallback para versão padrão
+app.use('/api', (req, res, next) => {
+  res.redirect(301, `/api/v2${req.path}`);
+});
+```
+
+```typescript
+// src/routes/v1/users.ts
+router.get('/', async (req, res) => {
+  const users = await userService.getAll();
+  
+  // v1: resposta com formato antigo
+  res.json({
+    data: users.map(u => ({
+      id: u.id,
+      name: u.full_name, // v1 usa "name"
+      email: u.email
+    }))
+  });
+});
+```
+
+```typescript
+// src/routes/v2/users.ts
+router.get('/', async (req, res) => {
+  const users = await userService.getAll();
+  
+  // v2: resposta com novo formato
+  res.json({
+    data: users.map(u => ({
+      id: u.id,
+      full_name: u.full_name, // v2 usa "full_name"
+      email: u.email,
+      profile: u.profile // v2 adiciona profile
+    })),
+    meta: {
+      total: users.length,
+      version: 'v2'
+    }
+  });
+});
+```
+
+---
+
+## Exemplo: Versionamento por Header
+
+```typescript
+// src/middleware/versioning.ts
+const VERSION_HEADER = 'X-API-Version';
+const DEFAULT_VERSION = '2';
+
+export function versionRouter(req, res, next) {
+  const version = req.headers[VERSION_HEADER.toLowerCase()] || DEFAULT_VERSION;
+  
+  // Anexar versão ao request
+  req.apiVersion = version;
+  
+  // Adicionar headers de resposta
+  res.setHeader(VERSION_HEADER, version);
+  
+  if (version === '1') {
+    res.setHeader('Deprecation', '@1704067200');
+    res.setHeader('Sunset', 'Mon, 01 Jul 2024 00:00:00 GMT');
+  }
+  
+  next();
+}
+
+// No controller
+export function getUsers(req, res) {
+  const users = userService.getAll();
+  
+  if (req.apiVersion === '1') {
+    return res.json(formatV1(users));
+  }
+  
+  return res.json(formatV2(users));
+}
+```
+
+---
+
+## Política de Breaking Changes
+
+### O que é Breaking Change?
+
+| Tipo de Mudança | Breaking? | Ação |
+|-----------------|-----------|------|
+| Remover endpoint | ✅ Sim | Nova versão major |
+| Remover campo da resposta | ✅ Sim | Nova versão major |
+| Renomear campo | ✅ Sim | Nova versão major |
+| Alterar tipo de campo | ✅ Sim | Nova versão major |
+| Adicionar campo obrigatório no request | ✅ Sim | Nova versão major |
+| Adicionar campo opcional na resposta | ❌ Não | Versão atual |
+| Adicionar endpoint | ❌ Não | Versão atual |
+| Adicionar campo opcional no request | ❌ Não | Versão atual |
+
+### Exemplo de Política
+
+```markdown
+## Política de Versionamento - API [NOME]
+
+### Versões Suportadas
+- Máximo de 2 versões major em produção
+- Versão deprecated tem suporte por 6 meses após lançamento da próxima
+- Versão sunset é comunicada com 3 meses de antecedência
+
+### Comunicação
+- Changelog público em /docs/changelog
+- Email para clientes cadastrados em mudanças major
+- Headers Deprecation e Sunset em respostas
+
+### SLA de Deprecação
+1. Anúncio: -6 meses do sunset
+2. Deprecation header: -3 meses do sunset
+3. Sunset: remoção completa
+```
+
+---
+
+## Documentação Multi-Versão
+
+### OpenAPI por Versão
+
+```yaml
+# openapi-v1.yaml
+openapi: 3.0.0
+info:
+  title: API v1 (Deprecated)
+  version: 1.0.0
+  x-deprecation-date: 2024-01-01
+
+# openapi-v2.yaml
+openapi: 3.0.0
+info:
+  title: API v2 (Current)
+  version: 2.0.0
+```
+
+### Changelog
+
+```markdown
+# Changelog
+
+## v2.0.0 (2024-01-15)
+
+### Breaking Changes
+- `GET /users`: Campo `name` renomeado para `full_name`
+- `POST /users`: Campo `profile_url` agora é obrigatório
+
+### Migração de v1 para v2
+1. Substituir `name` por `full_name` em todas as requisições
+2. Adicionar `profile_url` ao criar usuários
+
+## v1.0.0 (2023-06-01)
+- Release inicial
+```
+
+---
+
+## Checklist
+
+- [ ] Estratégia de versionamento definida e documentada
+- [ ] Política de breaking changes clara
+- [ ] Headers de deprecação implementados
+- [ ] Documentação separada por versão
+- [ ] Changelog atualizado
+- [ ] Testes para todas as versões ativas
+- [ ] Roteamento de versões testado
+
+---
+
+## Referências
+
+- [RFC 8594 - The Sunset HTTP Header](https://tools.ietf.org/html/rfc8594)
+- [API Versioning Best Practices](https://www.mnot.net/blog/2012/12/04/api-evolution)
+- [Stripe API Versioning](https://stripe.com/docs/api/versioning)

package/content/prompts/arquitetura/arquitetura-c4-completo.md

@@ -0,0 +1,190 @@
+# Prompt: Arquitetura C4 Completa
+
+> **Quando usar**: Início da fase de arquitetura, para definir visão geral do sistema
+> **Especialista**: [Arquitetura de Software](../../02-especialistas/Especialista%20em%20Arquitetura%20de%20Software.md)
+> **Nível**: Médio a Complexo
+
+---
+
+## Fluxo de Contexto
+
+Antes de usar este prompt, tenha em mãos:
+- `docs/CONTEXTO.md` - Entendimento atual do projeto
+- `docs/02-requisitos/requisitos.md` - Requisitos funcionais e não-funcionais
+
+Após gerar, salve o resultado em:
+- `docs/05-arquitetura/arquitetura-c4.md`
+
+---
+
+## Prompt Completo
+
+```text
+Atue como arquiteto de software sênior especializado em arquitetura C4.
+
+## Contexto do Projeto
+
+[COLE O CONTEÚDO DE docs/CONTEXTO.md]
+
+## Requisitos
+
+Requisitos funcionais:
+[COLE RFs DE docs/02-requisitos/requisitos.md]
+
+Requisitos não-funcionais:
+[COLE RNFs DE docs/02-requisitos/requisitos.md]
+
+Stack sugerida: [DESCREVA A STACK PREFERENCIAL]
+Escala esperada: [X usuários simultâneos, Y requests/segundo]
+Orçamento de infra: [ORÇAMENTO MENSAL]
+
+---
+
+## Sua Missão
+
+Entregue uma arquitetura completa usando o modelo C4:
+
+### 1. Diagrama C4 Nível 1 (Contexto)
+- Atores externos (tipos de usuários)
+- Sistemas externos que integram
+- O sistema como caixa única
+- Gere em formato Mermaid
+
+### 2. Diagrama C4 Nível 2 (Containers)
+- Aplicações (web, API, mobile)
+- Bancos de dados
+- Message brokers (se aplicável)
+- Caches
+- Para cada container: tecnologia e responsabilidade
+- Gere em formato Mermaid
+
+### 3. Diagrama C4 Nível 3 (Componentes) para o container principal
+- Módulos/pacotes principais
+- Responsabilidades de cada componente
+- Dependências entre componentes
+- Gere em formato Mermaid
+
+### 4. Decisões Arquiteturais (ADRs)
+
+Para cada decisão, justifique:
+
+**Padrão arquitetural**: [MVC/Hexagonal/DDD/Clean Architecture]
+- Por que este padrão?
+- Alternativas consideradas e por que foram descartadas
+
+**Estratégia de persistência**:
+- Banco escolhido e justificativa
+- Estratégia de cache
+
+**Estratégia de escalabilidade**:
+- O que escala horizontalmente
+- Pontos de bottleneck potenciais
+
+**Observabilidade**:
+- Logs, métricas, traces
+- Ferramentas sugeridas
+
+**Segurança**:
+- Autenticação/autorização
+- Proteção de dados sensíveis
+
+### 5. Trade-offs e Custos
+- Prós e contras das decisões
+- O que sacrificamos e por quê
+- Custo estimado de infraestrutura (MVP e 6 meses)
+- Riscos técnicos identificados
+
+### 6. Estrutura de Pastas
+- Proposta de estrutura de diretórios do projeto
+```
+
+---
+
+## Exemplo de Uso
+
+```text
+Atue como arquiteto de software sênior especializado em arquitetura C4.
+
+## Contexto do Projeto
+
+Sistema de agendamento online para salões de beleza. Permite que 
+clientes agendem horários via web/mobile e recebam confirmação via WhatsApp.
+
+## Requisitos
+
+Requisitos funcionais:
+- RF-001: O sistema deve permitir agendamento online
+- RF-002: O sistema deve enviar confirmação via WhatsApp
+- RF-003: O sistema deve permitir cancelamento até 2h antes
+
+Requisitos não-funcionais:
+- RNF-001: Tempo de resposta < 2 segundos
+- RNF-002: Disponibilidade 99.5%
+
+Stack sugerida: Node.js + TypeScript + PostgreSQL + Redis
+Escala esperada: 500 usuários simultâneos, 50 requests/segundo
+Orçamento de infra: R$ 300/mês
+
+[CONTINUA COM O PROMPT COMPLETO]
+```
+
+---
+
+## Resposta Esperada
+
+### 1. Contexto (C4 L1)
+
+```mermaid
+graph TB
+    U[Usuário Final]
+    A[Admin do Salão]
+    S[Sistema de Agendamento]
+    P[Gateway de Pagamento]
+    W[API WhatsApp]
+    
+    U -->|Usa| S
+    A -->|Gerencia| S
+    S -->|Processa| P
+    S -->|Notifica| W
+```
+
+### 2. Containers (C4 L2)
+
+```mermaid
+graph TB
+    subgraph Sistema
+        WEB[Next.js - Frontend]
+        API[NestJS - API]
+        DB[(PostgreSQL)]
+        CACHE[(Redis)]
+    end
+    
+    WEB --> API
+    API --> DB
+    API --> CACHE
+```
+
+### 4. Decisões
+
+**Padrão**: Hexagonal Architecture
+- **Por quê**: Separação clara entre domínio e infraestrutura
+- **Alternativa descartada**: MVC - menos testável
+
+**Banco**: PostgreSQL
+- **Por quê**: ACID, JSON support, maturidade
+- **Cache**: Redis para sessões e queries frequentes
+
+---
+
+## Checklist Pós-Geração
+
+Após receber a arquitetura, valide:
+
+- [ ] Diagrama C4 inclui níveis 1, 2 e 3
+- [ ] Padrão arquitetural está justificado
+- [ ] Pelo menos 4 ADRs documentados
+- [ ] Estrutura de pastas proposta
+- [ ] Estimativa de custos presente (MVP e 6 meses)
+- [ ] Stack justificada com prós/contras
+- [ ] Riscos técnicos identificados
+- [ ] Salvar em `docs/05-arquitetura/arquitetura-c4.md`

package/content/prompts/arquitetura/clean-architecture.md

@@ -0,0 +1,151 @@
+# Prompt: Arquitetura Clean Architecture
+
+> **Quando usar**: Projetos de nível Médio (1-3 meses, 5-15 entidades)
+> **Especialista**: Arquitetura de Software
+
+---
+
+## Prompt Completo
+
+```text
+Atue como arquiteto de software sênior especializado em Clean Architecture.
+
+## Contexto do Projeto
+
+PRD:
+[COLE O CONTEÚDO DE docs/01-produto/PRD.md]
+
+Requisitos:
+[COLE O CONTEÚDO DE docs/02-requisitos/requisitos.md]
+
+Modelo de Domínio:
+[COLE O CONTEÚDO DE docs/04-modelo/modelo-dominio.md]
+
+Stack preferencial: [DESCREVA SUA STACK]
+Prazo: [PRAZO DO MVP]
+Orçamento de infra: [ORÇAMENTO MENSAL]
+
+---
+
+## Sua Missão
+
+Proponha uma arquitetura em Clean Architecture considerando:
+
+### 1. Camadas da Arquitetura
+
+Defina cada camada com responsabilidades claras:
+
+- **Domain Layer** (mais interna):
+  - Entidades de domínio (não são ORM models)
+  - Value Objects
+  - Regras de negócio puras
+  - Interfaces de repositórios (ports)
+
+- **Application Layer**:
+  - Use Cases / Application Services
+  - DTOs de entrada e saída
+  - Orquestração de fluxos
+  - Sem dependência de frameworks
+
+- **Infrastructure Layer**:
+  - Implementações de repositórios (adapters)
+  - Serviços externos (email, pagamento, etc)
+  - Configurações de banco de dados
+  - Clientes HTTP
+
+- **Interface Layer** (mais externa):
+  - Controllers / Handlers
+  - Presenters / Serializers
+  - Middlewares
+  - Validação de input
+
+### 2. Diagrama C4
+
+Gere diagramas em Mermaid para:
+
+**Nível 1 - Contexto**:
+- Usuários e sistemas externos
+- Relações de alto nível
+
+**Nível 2 - Containers**:
+- Frontend, Backend, Banco, Cache, etc
+- Tecnologias de cada container
+
+**Nível 3 - Componentes** (para o backend):
+- Módulos principais
+- Fluxo de dependências
+
+### 3. Decisões Arquiteturais (ADRs)
+
+Para cada decisão importante, documente:
+- Contexto: Por que é necessário decidir
+- Decisão: O que foi escolhido
+- Alternativas: O que foi descartado e por quê
+- Consequências: Prós e contras
+
+ADRs obrigatórios:
+- Escolha da stack
+- Padrão de arquitetura (Clean vs outras)
+- Estratégia de autenticação
+- Estratégia de persistência
+
+### 4. Trade-offs
+
+Explique:
+- Por que Clean Architecture e não algo mais simples
+- Por que não microserviços (se aplicável)
+- Custos de infra estimados (MVP e 6 meses)
+- Pontos de escalabilidade futura
+
+### 5. Formato de Saída
+
+Retorne um documento Markdown estruturado seguindo o template:
+- Use diagramas Mermaid
+- Inclua code snippets de exemplo para cada camada
+- Liste arquivos/pastas da estrutura proposta
+```
+
+---
+
+## Exemplo de Uso
+
+```text
+Atue como arquiteto de software sênior especializado em Clean Architecture.
+
+## Contexto do Projeto
+
+PRD:
+Sistema de gestão de tarefas para equipes remotas. Permite criar projetos, 
+adicionar tarefas com prazos, e acompanhar progresso.
+
+Requisitos:
+- RF-001: Usuário pode criar projetos
+- RF-002: Usuário pode adicionar tarefas a projetos
+- RF-003: Tarefas têm título, descrição, prazo e status
+- RNF-001: Suportar 1000 usuários simultâneos
+- RNF-002: Tempo de resposta < 200ms
+
+Modelo de Domínio:
+- User (id, name, email)
+- Project (id, name, ownerId)
+- Task (id, title, description, dueDate, status, projectId)
+
+Stack preferencial: Node.js + TypeScript + PostgreSQL
+Prazo: 2 meses
+Orçamento de infra: R$ 500/mês
+
+[CONTINUA COM O PROMPT COMPLETO ACIMA]
+```
+
+---
+
+## Checklist Pós-Geração
+
+Após receber a arquitetura, valide:
+
+- [ ] Diagrama C4 inclui níveis 1 e 2
+- [ ] Camadas estão bem definidas
+- [ ] Pelo menos 3 ADRs documentados
+- [ ] Estrutura de pastas proposta
+- [ ] Estimativa de custos presente
+- [ ] Stack justificada com prós/contras