@thatix.io/context-first-agents-cli 0.1.0 → 0.2.0

package/templates/commands/pt-BR/engineer/pre-pr.md

@@ -0,0 +1,359 @@
+# Preparação para Pull Request
+
+Este comando valida que tudo está pronto para criar Pull Requests.
+
+## 📋 Pré-requisitos
+
+- Implementação completa (todas as tarefas do `/plan` executadas)
+- Todos os commits realizados
+- Workspace limpo e organizado
+
+## 📋 Configuração do Projeto
+
+**⚠️ IMPORTANTE: Sempre leia os arquivos de configuração do projeto ANTES de executar este comando!**
+
+### Arquivos Obrigatórios
+
+1. **`context-manifest.json`** (raiz do orchestrator)
+   - Lista de repositórios do projeto
+   - Roles de cada repositório (metaspecs, application, etc.)
+   - URLs e dependências entre repositórios
+
+2. **`ai.properties.md`** (raiz do orchestrator)
+   - Configurações do projeto (`project_name`, `base_path`)
+   - Sistema de gerenciamento de tarefas (`task_management_system`)
+   - Credenciais e configurações específicas
+
+### Como Ler
+
+```bash
+# 1. Ler context-manifest.json
+cat context-manifest.json
+
+# 2. Ler ai.properties.md
+cat ai.properties.md
+```
+
+### Informações Essenciais
+
+Após ler os arquivos, você terá:
+- ✅ Lista completa de repositórios do projeto
+- ✅ Localização do repositório de metaspecs
+- ✅ Base path para localizar repositórios
+- ✅ Sistema de task management configurado
+- ✅ Configurações específicas do projeto
+
+**🛑 NÃO prossiga sem ler estes arquivos!** Eles contêm informações críticas para a execução correta do comando.
+
+
+## 🎯 Objetivo
+
+Garantir que a implementação está completa, testada e pronta para revisão antes de criar os PRs.
+
+## 🛑 CRÍTICO: ONDE TRABALHAR
+
+**⚠️ ATENÇÃO: TODO CÓDIGO (testes, fixes, ajustes) DEVE SER CRIADO DENTRO DO WORKTREE!**
+
+**✅ CORRETO** - Trabalhar dentro do worktree:
+```
+<orchestrator>/.sessions/<ISSUE-ID>/<repo-name>/src/file.ts  ✅
+<orchestrator>/.sessions/<ISSUE-ID>/<repo-name>/tests/test.ts  ✅
+<orchestrator>/.sessions/<ISSUE-ID>/<repo-name>/.eslintrc.js  ✅
+```
+
+**❌ ERRADO** - NUNCA criar código fora do worktree:
+```
+<orchestrator>/.sessions/test.ts  ❌
+<orchestrator>/.sessions/<ISSUE-ID>/test.ts  ❌
+{base_path}/<repo-name>/test.ts  ❌ (repositório principal!)
+```
+
+**REGRA ABSOLUTA**:
+- 🛑 **TODO código** (testes, fixes, configurações) **DEVE estar em** `<orchestrator>/.sessions/<ISSUE-ID>/<repo-name>/`
+- 🛑 **NUNCA modifique** o repositório principal em `{base_path}/<repo-name>/`
+- ✅ **Trabalhe APENAS** dentro do worktree do repositório específico
+
+## ✅ Checklist de Validação
+
+### 1. Completude da Implementação
+
+```markdown
+## Verificação de Completude
+
+- [ ] Todas as tarefas do plano foram executadas
+- [ ] Todos os requisitos funcionais do PRD foram implementados
+- [ ] Todos os critérios de aceitação foram atendidos
+- [ ] Nenhuma funcionalidade ficou pela metade
+```
+
+### 2. Qualidade do Código
+
+Para cada repositório modificado:
+
+```bash
+cd <repositório>
+
+# Verificar status
+git status
+
+# Verificar linting (exemplos por stack):
+# Node.js: npm run lint / yarn lint / pnpm lint
+# Python: flake8 . / pylint src/ / black --check .
+# Java: mvn checkstyle:check / gradle check
+# Go: golangci-lint run / go vet ./...
+# Ruby: rubocop
+# Rust: cargo clippy
+# PHP: ./vendor/bin/phpcs
+# C#: dotnet format --verify-no-changes
+
+# Verificar formatação (exemplos por stack):
+# Node.js: npm run format:check / prettier --check .
+# Python: black --check . / autopep8 --diff .
+# Java: mvn formatter:validate
+# Go: gofmt -l . / go fmt ./...
+# Ruby: rubocop --format-only
+# Rust: cargo fmt --check
+
+# Verificar build (exemplos por stack):
+# Node.js: npm run build / yarn build
+# Python: python setup.py build
+# Java: mvn compile / gradle build
+# Go: go build ./...
+# Ruby: rake build
+# Rust: cargo build
+```
+
+Checklist:
+```markdown
+## Qualidade do Código
+
+### <repo-1>
+- [ ] Linting sem erros
+- [ ] Formatação correta
+- [ ] Build sem erros
+- [ ] Sem warnings críticos
+
+### <repo-2>
+- [ ] Linting sem erros
+- [ ] Formatação correta
+- [ ] Build sem erros
+- [ ] Sem warnings críticos
+```
+
+### 3. Testes
+
+Para cada repositório:
+
+```bash
+cd <repositório>
+
+# Executar testes unitários (exemplos por stack):
+# Node.js: npm run test:unit / jest / vitest
+# Python: pytest tests/unit / python -m unittest
+# Java: mvn test / gradle test
+# Go: go test ./... -short
+# Ruby: rspec spec/unit / rake test:unit
+# Rust: cargo test --lib
+# PHP: ./vendor/bin/phpunit --testsuite=unit
+# C#: dotnet test --filter Category=Unit
+
+# Executar testes de integração (exemplos por stack):
+# Node.js: npm run test:integration
+# Python: pytest tests/integration
+# Java: mvn verify / gradle integrationTest
+# Go: go test ./... -run Integration
+# Ruby: rspec spec/integration
+# Rust: cargo test --test '*'
+# PHP: ./vendor/bin/phpunit --testsuite=integration
+
+# Verificar cobertura (exemplos por stack):
+# Node.js: npm run test:coverage / jest --coverage
+# Python: pytest --cov=src tests/
+# Java: mvn jacoco:report / gradle jacocoTestReport
+# Go: go test -cover ./...
+# Ruby: rspec --coverage
+# Rust: cargo tarpaulin
+# PHP: ./vendor/bin/phpunit --coverage-html coverage/
+```
+
+Checklist:
+```markdown
+## Testes
+
+### <repo-1>
+- [ ] Todos os testes unitários passando
+- [ ] Todos os testes de integração passando
+- [ ] Cobertura de testes adequada (>= X%)
+- [ ] Novos testes adicionados para novas funcionalidades
+
+### <repo-2>
+- [ ] Todos os testes unitários passando
+- [ ] Todos os testes de integração passando
+- [ ] Cobertura de testes adequada (>= X%)
+- [ ] Novos testes adicionados para novas funcionalidades
+```
+
+### 4. Documentação
+
+```markdown
+## Documentação
+
+- [ ] README atualizado (se necessário)
+- [ ] Comentários de código adequados
+- [ ] Documentação de APIs atualizada (se houver mudanças)
+- [ ] Changelog atualizado
+- [ ] Documentação técnica atualizada nas metaspecs (se aplicável)
+```
+
+### 5. Commits
+
+```markdown
+## Commits
+
+- [ ] Todos os commits têm mensagens claras e descritivas
+- [ ] Commits seguem o padrão do projeto (conventional commits, etc.)
+- [ ] Não há commits com mensagens genéricas ("fix", "update", etc.)
+- [ ] Commits estão organizados logicamente
+- [ ] Não há commits de debug ou temporários
+```
+
+### 6. Sincronização
+
+```markdown
+## Sincronização
+
+- [ ] Branches estão atualizadas com a branch base (main/develop)
+- [ ] Não há conflitos de merge
+- [ ] Mudanças entre repositórios estão sincronizadas
+- [ ] Dependências entre repos foram testadas
+```
+
+### 7. Segurança
+
+```markdown
+## Segurança
+
+- [ ] Não há credenciais ou secrets no código
+- [ ] Não há dados sensíveis em logs
+- [ ] Dependências de segurança foram verificadas
+- [ ] Não há vulnerabilidades conhecidas introduzidas
+```
+
+### 8. Performance
+
+```markdown
+## Performance
+
+- [ ] Não há regressões de performance óbvias
+- [ ] Queries/operações custosas foram otimizadas
+- [ ] Não há memory leaks introduzidos
+- [ ] Requisitos de performance do PRD foram atendidos
+```
+
+## 🔍 Validação Cruzada
+
+Se múltiplos repositórios foram modificados:
+
+```markdown
+## Validação Cruzada
+
+- [ ] Testei a integração entre os repositórios localmente
+- [ ] APIs/contratos entre repos estão consistentes
+- [ ] Não há breaking changes não documentados
+- [ ] Ordem de deploy/merge está clara
+```
+
+## 📄 Preparação da Descrição do PR
+
+Crie `./.sessions/<ISSUE-ID>/pr-description.md`:
+
+```markdown
+## 🎯 Objetivo
+[Breve descrição do que esta feature faz]
+
+## 📝 Mudanças Principais
+- [Mudança 1]
+- [Mudança 2]
+- [Mudança 3]
+
+## 🔗 Links
+- **Issue**: [ISSUE-ID]
+- **PRD**: [link ou caminho]
+- **Plano Técnico**: [link ou caminho]
+
+## ✅ Checklist
+- [x] Código implementado e testado
+- [x] Testes unitários adicionados/atualizados
+- [x] Testes de integração passando
+- [x] Documentação atualizada
+- [x] Linting e formatação OK
+- [x] Build sem erros
+
+## 🧪 Como Testar
+1. [Passo 1]
+2. [Passo 2]
+3. [Resultado esperado]
+
+## 🔍 Notas para Revisores
+- [Ponto de atenção 1]
+- [Ponto de atenção 2]
+```
+
+## 🚨 Problemas Encontrados
+
+Se alguma validação falhar:
+1. 🛑 **PARE** o processo de criação de PR
+2. 📝 **DOCUMENTE** o problema
+3. 🔧 **CORRIJA** o problema
+4. 🔄 **EXECUTE** `/pre-pr` novamente
+
+## 📊 Relatório de Validação
+
+Crie `./.sessions/<ISSUE-ID>/pre-pr-report.md`:
+
+```markdown
+# Relatório de Validação Pre-PR
+
+**Data**: [data/hora]
+**Issue**: [ISSUE-ID]
+
+## Status Geral
+✅ Pronto para PR / ⚠️ Pendências / ❌ Bloqueado
+
+## Repositórios Validados
+- **<repo-1>**: ✅ OK
+- **<repo-2>**: ✅ OK
+
+## Resumo de Testes
+- **Testes Unitários**: X/X passando
+- **Testes de Integração**: Y/Y passando
+- **Cobertura**: Z%
+
+## Pendências (se houver)
+- [Pendência 1]
+- [Pendência 2]
+
+## Próximos Passos
+- [x] Todas as validações passaram
+- [ ] Executar `/pr` para criar Pull Requests
+```
+
+---
+
+**Argumentos fornecidos**:
+
+```
+#$ARGUMENTS
+```
+
+---
+
+## 🎯 Próximo Passo
+
+Se todas as validações passaram:
+
+```bash
+/pr
+```
+
+Este comando criará os Pull Requests para todos os repositórios modificados.

package/templates/commands/pt-BR/engineer/start.md

@@ -0,0 +1,319 @@
+# Início do Desenvolvimento
+
+Este comando inicia o desenvolvimento de uma funcionalidade no workspace atual.
+
+## 📍 IMPORTANTE: Entenda a Estrutura
+
+**Workspace** (onde você trabalhará):
+```
+<orchestrator>/.sessions/<ISSUE-ID>/
+├── repo-1/          # worktree com branch feature/<ISSUE-ID>
+├── repo-2/          # worktree com branch feature/<ISSUE-ID>
+├── context.md       # contexto (imutável - criado por este comando)
+├── architecture.md  # arquitetura (imutável - criado por este comando)
+└── plan.md          # plano (mutável - criado por /plan)
+```
+
+**Repositórios principais** (apenas leitura):
+```
+{base_path}/repo-1/  # repo principal (branch main/master)
+{base_path}/repo-2/  # repo principal (branch main/master)
+```
+
+**REGRA DE OURO**:
+- ✅ Leia metaspecs e código dos repositórios principais (read-only)
+- ✅ Crie `context.md` e `architecture.md` em `.sessions/<ISSUE-ID>/`
+- ❌ NUNCA faça checkout nos repositórios principais
+- ❌ NUNCA modifique código neste comando (use `/work` depois)
+
+## 📋 Configuração do Projeto
+
+**⚠️ IMPORTANTE: Sempre leia os arquivos de configuração do projeto ANTES de executar este comando!**
+
+### Arquivos Obrigatórios
+
+1. **`context-manifest.json`** (raiz do orchestrator)
+   - Lista de repositórios do projeto
+   - Roles de cada repositório (metaspecs, application, etc.)
+   - URLs e dependências entre repositórios
+
+2. **`ai.properties.md`** (raiz do orchestrator)
+   - Configurações do projeto (`project_name`, `base_path`)
+   - Sistema de gerenciamento de tarefas (`task_management_system`)
+   - Credenciais e configurações específicas
+
+### Como Ler
+
+```bash
+# 1. Ler context-manifest.json
+cat context-manifest.json
+
+# 2. Ler ai.properties.md
+cat ai.properties.md
+```
+
+### Informações Essenciais
+
+Após ler os arquivos, você terá:
+- ✅ Lista completa de repositórios do projeto
+- ✅ Localização do repositório de metaspecs
+- ✅ Base path para localizar repositórios
+- ✅ Sistema de task management configurado
+- ✅ Configurações específicas do projeto
+
+**🛑 NÃO prossiga sem ler estes arquivos!** Eles contêm informações críticas para a execução correta do comando.
+
+
+## 📚 Carregar MetaSpecs
+
+**Localizar MetaSpecs automaticamente**:
+1. Leia `context-manifest.json` do orchestrator
+2. Encontre o repositório com `"role": "metaspecs"`
+3. Leia `ai.properties.md` para obter o `base_path`
+4. O metaspecs está em: `{base_path}/{metaspecs-repo-id}/`
+5. Leia os arquivos `index.md` relevantes:
+   - Contexto de negócio
+   - Stack, arquitetura e padrões técnicos
+   - Convenções do projeto
+   - ADRs (Architecture Decision Records)
+
+## 🎯 Contexto do Projeto
+
+Antes de iniciar, carregue o contexto consultando:
+- `context-manifest.json` - Estrutura de repositórios
+- MetaSpecs (localizado acima) - Arquitetura e padrões
+- `diretório do workspace` - Informações do workspace atual
+
+## ⚙️ Configuração Inicial
+
+1. **Verificar Workspace**:
+   - Confirme que está no workspace correto (verifique `diretório do workspace`)
+   - Liste os repositórios disponíveis no workspace
+
+2. **Verificar Branches**:
+   - Para cada repositório no workspace, verifique a branch atual
+   - Confirme que todas as branches estão sincronizadas
+
+3. **Carregar Especificação**:
+   - **Se task manager configurado**: Leia a issue usando o MCP apropriado
+   - **Senão**: Peça ao usuário o arquivo de especificação ou descrição da feature
+
+4. **Atualizar Status** (se task manager configurado):
+   - Mova a issue para "Em Progresso"
+
+## 📋 Análise e Entendimento
+
+Analise a especificação e construa entendimento completo respondendo:
+
+### Negócio
+- **Por que** isso está sendo construído?
+- **Quem** se beneficia?
+- **Qual** métrica queremos impactar?
+
+### Funcional
+- **Qual resultado esperado**? (comportamento do usuário, output do sistema)
+- **Quais componentes** serão criados/modificados em cada repositório?
+- **Quais integrações** entre repositórios são necessárias?
+
+### Técnico
+- **Stack aprovada**? Verificar contra especificações técnicas
+- **Padrões arquiteturais**? Verificar ADRs (se disponíveis)
+- **Dependências novas**? Justificar e documentar
+- **Como testar**? (conforme padrões do projeto)
+
+### Validação contra Metaspecs
+
+Se metaspecs estiverem disponíveis, validar:
+- Alinhado com estratégia e roadmap?
+- Usa stack tecnológica aprovada?
+- Respeita Architecture Decision Records?
+- Segue regras de negócio documentadas?
+
+## 🤔 Perguntas de Esclarecimento
+
+Após análise inicial, formule **3-5 clarificações mais importantes**:
+
+**Exemplos de perguntas relevantes**:
+- Qual repositório deve conter a lógica principal?
+- Como os repositórios devem se comunicar?
+- Há dependências entre as mudanças nos diferentes repos?
+- Qual a ordem de implementação recomendada?
+- Há impacto em APIs ou contratos entre serviços?
+
+## 💾 Criação do Context.md
+
+**IMPORTANTE**: Este arquivo é **IMUTÁVEL** após aprovação. Não deve ser modificado por comandos subsequentes.
+
+Crie arquivo `./.sessions/<ISSUE-ID>/context.md` com:
+
+```markdown
+# Context: [Nome da Feature]
+
+## Por Que
+[Valor de negócio, persona atendida, métrica impactada]
+
+## O Que
+[Funcionalidades principais, comportamento esperado]
+
+## Como
+[Abordagem técnica, componentes, repositórios afetados]
+
+## Validação contra Metaspecs
+- [x] Alinhado com estratégia de produto
+- [x] Atende persona correta
+- [x] Métrica impactada documentada
+- [x] Usa stack aprovada
+- [x] Respeita ADRs
+- [x] Sem conflitos com limitações conhecidas
+
+## Dependências
+[Bibliotecas, APIs, componentes existentes]
+
+## Restrições
+[Limitações técnicas, performance targets, budget]
+
+## Testes
+[E2E críticos, unit tests necessários, cobertura esperada]
+```
+
+**Após criar `context.md`, peça revisão e aprovação do usuário antes de prosseguir.**
+
+---
+
+## 🏗️ Criação do Architecture.md
+
+**IMPORTANTE**: Este arquivo é **IMUTÁVEL** após aprovação. Não deve ser modificado por comandos subsequentes.
+
+### Princípios Arquiteturais (OBRIGATÓRIO)
+
+**ANTES de criar a arquitetura, você DEVE:**
+
+1. **Ler ADRs (Architecture Decision Records)**:
+   - Liste ADRs em metaspecs
+   - Leia TODOS os ADRs relevantes para a feature
+   - Identifique restrições e padrões obrigatórios
+
+2. **Consultar padrões arquiteturais**:
+   - Leia guias de estrutura do projeto em metaspecs
+   - Leia padrões de código em metaspecs
+   - Identifique padrões existentes no código (use Glob/Grep para encontrar exemplos similares)
+
+3. **Validar compliance com ADRs**:
+   - Para cada ADR relevante, verifique se a solução proposta respeita as decisões
+   - Documente compliance no architecture.md
+   - Se houver violação, justifique ou proponha correção
+
+4. **Analisar código existente**:
+   - Use Glob/Grep para encontrar componentes/módulos similares
+   - Entenda padrões e estruturas existentes
+   - Alinhe nova implementação com padrões do projeto
+
+### Estrutura do Documento de Arquitetura
+
+Crie arquivo `./.sessions/<ISSUE-ID>/architecture.md` com:
+
+```markdown
+# Architecture: [Nome da Feature]
+
+## Visão Geral
+[Visão de alto nível do sistema antes e depois da mudança]
+
+## Componentes Afetados
+[Lista de componentes e suas relações, dependências]
+
+### Diagrama de Componentes
+[Descrição textual ou diagrama Mermaid dos componentes]
+
+### Fluxo de Dados
+1. [Passo 1 do fluxo]
+2. [Passo 2 do fluxo]
+3. [Passo 3 do fluxo]
+
+## Estrutura de Diretórios Proposta
+[Baseada em padrões do projeto]
+
+```
+repo-1/
+├── src/
+│   ├── components/
+│   │   └── NewComponent.tsx (CRIAR)
+│   └── services/
+│       └── NewService.ts (CRIAR)
+```
+
+## Padrões e Melhores Práticas
+[Padrões que serão mantidos ou introduzidos]
+
+## Validação de ADRs
+[Lista de ADRs consultados e compliance]
+
+- [x] ADR-001: [Nome] - Compliant
+- [x] ADR-002: [Nome] - Compliant
+
+## Dependências Externas
+[Bibliotecas que serão usadas ou adicionadas]
+
+## Decisões Técnicas
+
+### Decisão 1: [Título]
+**Contexto**: [Por que precisamos decidir isso]
+**Opções consideradas**:
+- Opção A: [Prós e contras]
+- Opção B: [Prós e contras]
+**Decisão**: [Opção escolhida]
+**Justificativa**: [Por que escolhemos esta opção]
+
+## Restrições e Suposições
+[Limitações técnicas e premissas]
+
+## Trade-offs
+[Alternativas consideradas e por que não foram escolhidas]
+
+## Consequências
+**Positivas**:
+- [Benefício 1]
+- [Benefício 2]
+
+**Negativas**:
+- [Custo/limitação 1]
+- [Custo/limitação 2]
+
+## Arquivos Principais
+[Lista dos principais arquivos a serem editados/criados]
+
+- `repo-1/src/components/NewComponent.tsx` (CRIAR)
+- `repo-1/src/services/NewService.ts` (CRIAR)
+- `repo-2/src/controllers/NewController.ts` (CRIAR)
+```
+
+**Após criar `architecture.md`, peça revisão e aprovação do usuário antes de prosseguir.**
+
+---
+
+**Argumentos fornecidos**:
+
+```
+#$ARGUMENTS
+```
+
+---
+
+## 🎯 Próximo Passo
+
+**Após aprovação do usuário dos arquivos `context.md` e `architecture.md`**:
+
+```bash
+/plan
+```
+
+Este comando criará o planejamento técnico detalhado da implementação.
+
+---
+
+## ⚠️ IMPORTANTE: Arquivos Imutáveis
+
+**`context.md` e `architecture.md` são IMUTÁVEIS após aprovação.**
+
+- ✅ Podem ser LIDOS por comandos subsequentes (`/plan`, `/work`)
+- ❌ NÃO devem ser MODIFICADOS por nenhum comando
+- ❌ Se houver necessidade de mudança, discuta com o usuário e crie novos arquivos ou atualize a issue no task manager