@onion-architect-ai/cli 4.1.0-beta.1 → 4.1.0-beta.2

package/templates/.onion/contexts/technical/commands/intermediate/pr-update.md

@@ -0,0 +1,198 @@
+---
+name: pr-update
+description: Atualizar PR existente com mudanças adicionais.
+model: sonnet
+category: engineer
+tags: [pr, update, git]
+version: "4.0.0"
+updated: "2025-12-20"
+level: intermediate
+context: technical
+---
+
+# 🔄 Engineer PR Update
+
+Atualizar um Pull Request existente com mudanças adicionais. Este comando automatiza o processo completo de commit, push e documentação quando você já executou `/engineer/pr` mas fez mudanças subsequentes.
+
+## 🎯 Funcionalidades
+
+### Detecção Automática de Contexto
+- Identifica automaticamente a branch de feature ativa
+- Detecta mudanças pendentes (staged/unstaged/untracked)
+- Valida se existe PR aberto para a branch atual
+- Verifica se está na sessão de desenvolvimento correta
+
+### Commit Inteligente e Descritivo
+- Analisa arquivos modificados para categorizar mudanças
+- Gera mensagem de commit contextual e descritiva
+- Suporta diferentes tipos de mudanças (fix, feat, docs, refactor)
+- Mantém histórico limpo com commits atômicos
+
+### Sincronização Automática
+- Push automático para branch do PR existente
+- Atualização do ClickUp com comentário detalhado
+- Validação de que PR foi atualizado com sucesso
+- Timestamp e métricas das mudanças aplicadas
+
+## 🚀 Como Usar
+
+```bash
+/engineer/pr-update
+```
+
+### Exemplos com Parâmetros Opcionais
+```bash
+/engineer/pr-update                           # Análise automática + commit inteligente
+/engineer/pr-update --type fix               # Força tipo de commit específico
+/engineer/pr-update --message "Custom msg"   # Mensagem personalizada
+/engineer/pr-update --dry-run               # Preview sem executar
+```
+
+## 🤝 Integração ClickUp MCP
+
+### Detecção de Task Ativa
+- Lê task ID do arquivo `.cursor/sessions/[slug]/context.md`
+- Identifica PR existente através da task ou branch
+- Valida se task está em status "in progress" com tag "under-review"
+
+### Comentário Automático Padronizado
+
+**Chamar abstração MCP para documentação de atualização:**
+
+```typescript
+// Ao atualizar PR com novos commits, chamar:
+await commentPRUpdated(taskId, {
+  commitType: "fix|feat|refactor|docs|chore",
+  commitHash: "[hash do commit]",
+  filesModified: N,
+  linesAdded: N,
+  linesRemoved: N,
+  description: "[descrição das mudanças]"
+});
+```
+
+**Referências:**
+- **Padrão 4 (PR Atualizada)**: `.cursor/docs/strategies/clickup-comment-patterns.md`
+- **Abstração MCP**: `commentPRUpdated()` em `.cursor/utils/clickup-mcp-wrappers.md` (linhas 632-661)
+
+## ⚙️ Processo Automático
+
+1. **Validação de Contexto**: Confirma branch de feature + sessão ativa
+2. **Análise de Mudanças**: Categoriza arquivos modificados por tipo
+3. **Geração de Commit**: Cria mensagem contextual e descritiva
+4. **Staging Inteligente**: Adiciona apenas arquivos relevantes
+5. **Commit & Push**: Executa commit + push para branch do PR
+6. **Atualização ClickUp**: Documenta mudanças com comentário formatado
+7. **Validação Final**: Confirma que PR foi atualizado com sucesso
+
+## 🧠 Detecção Inteligente de Tipos
+
+### Tipos de Commit Auto-Detectados
+- **fix**: Correções de bugs, patches, hotfixes
+- **feat**: Novas funcionalidades, enhancements
+- **docs**: Mudanças apenas em documentação
+- **refactor**: Refatoração sem mudança de funcionalidade
+- **style**: Formatação, linting, style fixes
+- **test**: Adição ou correção de testes
+- **chore**: Tarefas de manutenção, configuração
+
+### Análise de Arquivos Modificados
+```markdown
+## Categorização Automática:
+- `.cursor/commands/` → "feat/fix: Comando updates"
+- `docs/` → "docs: Documentation updates"
+- `tests/` → "test: Test updates"
+- `*.md` (session files) → "chore: Session documentation"
+- Múltiplos tipos → "chore: Multiple updates"
+```
+
+## ⚠️ Resolução de Problemas
+
+### Problema: "Não há PR ativo para esta branch"
+**Solução**: Executar `/engineer/pr` primeiro para criar o PR inicial
+```bash
+# Se necessário, criar PR primeiro:
+/engineer/pr
+```
+
+### Problema: "Nenhuma mudança detectada"
+**Solução**: Verificar se há arquivos modificados
+```bash
+git status  # Confirmar mudanças pendentes
+```
+
+### Problema: "Branch não está sincronizada"
+**Solução**: Sincronizar branch antes de atualizar
+```bash
+git pull origin [branch-name]  # Sincronizar primeiro
+/engineer/pr-update           # Depois atualizar
+```
+
+### Problema: "Task ClickUp não encontrada"
+**Solução**: Verificar context.md da sessão ativa
+- Confirmar task ID no arquivo `.cursor/sessions/[slug]/context.md`
+- Validar se task existe e está acessível
+
+## 💡 Casos de Uso Comuns
+
+### 1. Correções Pós-Review
+```bash
+# Após feedback do code review:
+# 1. Fazer correções solicitadas
+# 2. Executar:
+/engineer/pr-update --type fix
+```
+
+### 2. Melhorias Adicionais
+```bash
+# Após pensar em melhorias:
+# 1. Implementar enhancements
+# 2. Executar:
+/engineer/pr-update --type feat
+```
+
+### 3. Documentação Esquecida
+```bash
+# Após lembrar de documentar:
+# 1. Atualizar docs
+# 2. Executar:
+/engineer/pr-update --type docs
+```
+
+### 4. Correções Arquiteturais
+```bash
+# Como no exemplo atual:
+# 1. Implementar correções arquiteturais
+# 2. Executar:
+/engineer/pr-update --type fix --message "Correção arquitetural - Phase→Subtask sync"
+```
+
+## 🔗 Integração com Workflow
+
+### Fluxo Padrão Completo
+1. `/product/task` - Criar task ClickUp
+2. `/engineer/start` - Iniciar desenvolvimento  
+3. `/engineer/work` - Desenvolver features
+4. `/engineer/pre-pr` - Validações finais
+5. `/engineer/pr` - Criar Pull Request
+6. **`/engineer/pr-update`** - Atualizar PR com mudanças adicionais (quantas vezes necessário)
+7. Merge do PR → Auto-sync `/git/sync`
+
+### Compatibilidade com Comandos Existentes
+- ✅ Funciona após `/engineer/pr`
+- ✅ Integra com `/engineer/work` progress tracking
+- ✅ Compatível com `/git/sync` automático pós-merge
+- ✅ Respeita mapeamento Phase→Subtask do context.md
+
+---
+
+**🎯 VALOR AGREGADO: Este comando elimina o processo manual de atualização de PRs, automatizando commit inteligente, push, e documentação ClickUp em uma única operação otimizada.**
+
+## 📈 Benefícios
+
+- ⚡ **Automação completa** do processo de update
+- 🧠 **Commits inteligentes** com mensagens contextuais
+- 📝 **Documentação automática** no ClickUp
+- 🔄 **Consistência** no workflow de PRs
+- ⏰ **Economia de tempo** significativa
+- 🎯 **Redução de erros** manuais

package/templates/.onion/contexts/technical/commands/intermediate/pre-pr.md

@@ -0,0 +1,91 @@
+---
+name: pre-pr
+description: Validação completa antes do PR. Verifica padrões e qualidade.
+model: sonnet
+category: engineer
+tags: [validation, pr, quality]
+version: "4.0.0"
+updated: "2025-12-20"
+level: intermediate
+context: technical
+---
+
+# Pre-PR - Validação Completa Antes do Pull Request
+
+Estamos nos aproximando de finalizar o trabalho nesta branch e nos preparar para um pull request. Agora, é hora de fazer verificações finais e limpezas para garantir que estamos alinhados com nossos padrões e objetivos.
+
+## 🔄 **Auto-Update ClickUp**
+
+Este comando **automaticamente atualiza** a task ClickUp durante preparação para PR:
+
+### **✅ Updates Automáticos SEMPRE:**
+- **Validação de critérios de aceitação** - Verifica todos os checkboxes
+- **Comentário de preparação** com checklist completo
+- **Tag 'ready-for-pr'** quando todas verificações passam
+- **Tag 'needs-fixes'** se verificações falham
+- **Progresso estimado** para 90% (quase pronto)
+
+### **💬 Formato do Comentário de Pre-PR:**
+
+**Chamar abstrações MCP para validação automatizada:**
+
+```typescript
+// 1. Validar Critérios de Aceitação
+const validation = await validateAcceptanceCriteria(taskId);
+// Retorna: { isComplete, coverage, criteria[], pendingCriteria[] }
+
+// 2. Criar comentário de validação com resultado
+await commentPrePRValidation(taskId, {
+  validationResult: validation,
+  technicalChecks: { metaSpecs: true, codeReview: true, tests: true },
+  readyForPR: validation.isComplete
+});
+```
+
+**Referências:**
+- **Padrão 5 (Validação Pre-PR)**: `.cursor/docs/strategies/clickup-comment-patterns.md`
+- **Abstrações MCP**: 
+  - `validateAcceptanceCriteria()` em `.cursor/utils/clickup-mcp-wrappers.md` (linhas 534-600)
+  - `commentPrePRValidation()` em `.cursor/utils/clickup-mcp-wrappers.md` (linhas 603-629)
+
+### **📋 Identificação da Task:**
+1. **Context.md**: Lê task-id da sessão ativa
+2. **Branch atual**: Detecta automaticamente pela branch git
+
+## Checklist de Preparação:
+
+### ✅ Validação de Critérios de Aceitação:
+1. **Extrair critérios** - Ler checkboxes da description da task/subtask
+2. **Validar cobertura** - Confirmar que TODOS os checkboxes estão marcados `[x]`
+3. **Gerar relatório** - Criar lista de critérios validados
+4. **Bloquear se incompleto** - Se algum critério não estiver marcado, indicar no comentário
+
+### 🔧 Validações Técnicas:
+1. Invoque o agente `branch-metaspec-checker` para verificar se a branch está alinhada com as meta specs do projeto.
+2. Invoque o agente `branch-code-reviewer` para revisar o código e garantir que está bom para lançar.
+3. Invoque o agente `branch-documentation-writer` para atualizar a documentação do projeto.
+4. Invoque o agente `branch-test-planner` para finalizar a escrita de testes para a branch.
+
+### 📋 AUTO-UPDATE:
+5. **Validar critérios de aceitação** - Verificar todos os checkboxes
+6. **Adicionar comentário de preparação** no ClickUp automaticamente
+7. **Aplicar tags** (ready-for-pr ou needs-fixes)
+8. **Atualizar progresso** para 90%
+
+Você também precisará lidar com todo o feedback que esses agentes fornecerem e fazer mudanças e correções conforme necessário.
+
+Uma vez terminado E todos os critérios de aceitação validados, me avise e peça minha permissão para abrir o Pull Request.
+
+
+
+---
+
+## 📚 Pré-requisitos
+
+Domine comandos starter antes de usar este comando intermediate/advanced.
+
+Consulte os comandos help para ver hierarquia completa:
+- /business/help --level=starter
+- /technical/help --level=starter
+
+💡 Comandos intermediate/advanced assumem familiaridade com workflows básicos.

package/templates/.onion/contexts/technical/commands/intermediate/start.md

@@ -0,0 +1,266 @@
+---
+name: start
+description: |
+  Iniciar desenvolvimento de feature. Cria sessão e analisa tasks.
+  Suporta múltiplos gerenciadores via TASK_MANAGER_PROVIDER.
+model: sonnet
+category: engineer
+tags: [development, workflow, session]
+version: "4.0.0"
+updated: "2025-12-20"
+level: intermediate
+context: technical
+---
+
+# Engineer Start
+
+Este é o comando para iniciar o desenvolvimento de uma funcionalidade.
+
+## 🔧 Pré-requisito: Detectar Provedor
+
+```typescript
+// Consultar .cursor/utils/task-manager/detector.md
+const config = detectProvider();
+const taskManager = getTaskManager();
+
+// Se tem task-id no input, validar compatibilidade
+if (taskId) {
+  const validation = validateProviderMatch(taskId, config.provider);
+  if (!validation.valid) {
+    console.warn(validation.warning);
+    // Perguntar ao usuário como proceder
+  }
+}
+```
+
+## Configuração
+- Se não estivermos em uma feature branch, peça permissão para criar uma
+- Se estivermos em uma feature branch que corresponde ao nome da funcionalidade, estamos prontos.
+- Certifique-se de que existe uma pasta .cursor/sessions/<feature-slug>
+- Peça ao usuário o input para esta sessão (você receberá um ou mais tasks para trabalhar)
+
+## Análise
+
+Analise as tasks, pais e filhos se necessário, e construa um entendimento inicial do que precisa ser desenvolvido. 
+
+### **📋 Análise via Task Manager:**
+**IMPORTANTE**: Use a abstração para ler tasks independente do provedor:
+
+```typescript
+// Via abstração - funciona para qualquer provedor (ClickUp, Asana, Linear)
+const task = await taskManager.getTask(taskId);
+const subtasks = await taskManager.getSubtasks(taskId);
+
+// Documentar no context.md
+console.log(`Provider: ${task.provider}`);
+console.log(`Task: ${task.name}`);
+console.log(`URL: ${task.url}`);
+```
+
+### **🎲 Validação de Story Points (Opcional mas Recomendado):**
+
+**CRÍTICO:** Antes de iniciar desenvolvimento, validar se task tem estimativa de story points:
+
+```typescript
+// Verificar se task tem story points estimados
+const storyPoints = task.customFields?.find(f => f.name === 'Story Points')?.value;
+
+if (!storyPoints || storyPoints === 0) {
+  console.warn(`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚠️ ATENÇÃO: TASK SEM ESTIMATIVA DE STORY POINTS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 Task: ${task.name}
+🎲 Story Points: Não estimado
+
+💡 RECOMENDAÇÕES:
+∟ Estimar antes de iniciar desenvolvimento
+∟ Usar: /product/estimate "${task.name}"
+∟ Ou: @story-points-framework-specialist
+
+⚠️ Continuar sem estimativa pode afetar:
+   - Planejamento de sprint
+   - Tracking de velocity
+   - Previsibilidade de entrega
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  `);
+  
+  // Perguntar ao usuário se deseja estimar agora
+  const shouldEstimate = await askUser('Deseja estimar story points agora? (s/n)');
+  
+  if (shouldEstimate) {
+    // Invocar agente de estimativa
+    await invokeStoryPointsEstimation(task);
+  }
+} else if (storyPoints > 13) {
+  console.warn(`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚠️ ALERTA: TASK IDENTIFICADA COMO ÉPICO
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 Task: ${task.name}
+🎲 Story Points: ${storyPoints} pontos
+
+💡 RECOMENDAÇÕES:
+∟ Considerar quebrar em múltiplas tasks menores
+∟ Usar: /product/refine para detalhar requisitos
+∟ Verificar se realmente precisa ser uma única task
+
+⚠️ Tasks > 13 pontos têm:
+   - Maior margem de erro na estimativa
+   - Risco de não caber no sprint
+   - Dificuldade de tracking de progresso
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  `);
+  
+  // Perguntar ao usuário se deseja continuar
+  const shouldContinue = await askUser('Deseja continuar mesmo assim? (s/n)');
+  if (!shouldContinue) {
+    console.log('💡 Sugestão: Use /product/refine para detalhar e quebrar a task');
+    return;
+  }
+} else {
+  console.log(`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ VALIDAÇÃO DE ESTIMATIVA
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 Task: ${task.name}
+🎲 Story Points: ${storyPoints} pontos
+
+✅ Estimativa válida para desenvolvimento
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  `);
+}
+```
+
+### **🔍 Validação de ID Incompatível:**
+Se o task-id salvo for de um provedor diferente do configurado:
+
+```
+⚠️ INCOMPATIBILIDADE DETECTADA
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Task ID: "86adfe9eb"
+Provedor detectado: clickup
+Provedor configurado: asana
+
+💡 Ações sugeridas:
+   1. Altere TASK_MANAGER_PROVIDER para 'clickup' no .env
+   2. Ou limpe a sessão atual e crie uma nova task
+   3. Execute /meta/setup-integration para reconfigurar
+```
+
+### **🔍 Questões de Análise:**
+Pense cuidadosamente sobre o que é solicitado, certifique-se de entender exatamente:
+    - Por que isso está sendo construído (contexto)
+    - Qual é o resultado esperado para esta task? (objetivo)
+    - Como deve ser construído, apenas direcionalmente, não em detalhes (abordagem)
+    - Se requer o uso de novas APIs/ferramentas, você as entende?
+    - Como deve ser testado?
+    - Quais são as dependências?
+    - Quais são as restrições?
+
+Após refletir sobre essas questões, formule as 3-5 clarificações mais importantes necessárias para completar a tarefa. Pergunte essas questões ao humano, enquanto também fornece seu entendimento e sugestões.
+
+Depois de obter as respostas do humano, considere se precisa fazer mais perguntas. Se sim, faça mais perguntas ao humano.
+
+Uma vez que tenha um bom entendimento do que está sendo construído, salve-o no arquivo .cursor/sessions/<feature-slug>/context.md e peça ao humano para revisar.
+
+Se o humano concordar com seu entendimento, você pode prosseguir para o próximo passo. Caso contrário, continue iterando juntos até obter aprovação explícita para seguir em frente.
+
+Se algo que você discutiu aqui afeta o que foi escrito nos requisitos, peça permissão ao humano para editar esses requisitos e fazer ajustes.
+
+## Arquitetura
+
+Dado seu entendimento do que será construído, você agora procederá ao desenvolvimento da arquitetura da funcionalidade.
+
+É aqui que você colocará seu chapéu de pensamento ultra e considerará o melhor caminho para construir a funcionalidade, considerando também os padrões e melhores práticas deste projeto.
+
+Seu documento de arquitetura deve incluir:
+    - Uma visão geral de alto nível do sistema (antes e depois da mudança)
+    - Componentes afetados e suas relações, dependências
+    - Padrões e melhores práticas que serão mantidos ou introduzidos
+    - Dependências externas
+    - Restrições e suposições
+    - Trade-offs e alternativas
+    - Lista dos principais arquivos a serem editados/criados
+
+Uma vez que tenha um bom entendimento do que está sendo construído, salve-o no arquivo .cursor/sessions/<feature-slug>/architecture.md e peça ao humano para revisar.
+
+## 🔄 **Auto-Update Task Manager**
+
+Este comando **automaticamente atualiza** a task quando inicia:
+
+### **✅ Updates Automáticos SEMPRE:**
+```typescript
+// Via abstração - funciona para qualquer provedor
+if (taskManager.isConfigured && taskId) {
+  // Atualizar status
+  await taskManager.updateStatus(taskId, 'in_progress');
+  
+  // Adicionar comentário de início
+  await taskManager.addComment(taskId, `
+🚀 DESENVOLVIMENTO INICIADO
+
+━━━━━━━━━━━━━━━━━━━━━━━━
+
+🏗️ SESSÃO ATIVADA:
+   ▶ Branch: feature/[slug]
+   ▶ Sessão: .cursor/sessions/[slug]/
+   ▶ Provider: ${taskManager.provider}
+
+📋 PLANO DE IMPLEMENTAÇÃO:
+   ∟ Fase 1: [Descrição]
+   ∟ Fase N: [Descrição]
+
+━━━━━━━━━━━━━━━━━━━━━━━━
+
+⏰ Iniciado: ${new Date().toISOString()}
+  `);
+}
+```
+
+### **📋 Identificação da Task:**
+1. **Context.md**: Lê task-id do arquivo `.cursor/sessions/[slug]/context.md`
+2. **Task Manager**: Usa `taskManager.getTask(taskId)` para estrutura completa
+3. **🆕 PHASE-SUBTASK MAPPING**: Cria mapeamento automático fase→subtask no context.md
+4. **Validação de ID**: Verifica compatibilidade do ID com provedor configurado
+5. **Não encontrada**: Pergunta ao usuário se deve vincular a uma task específica
+
+### **🗺️ OBRIGATÓRIO: Criar Phase-Subtask Mapping**
+Quando subtasks existem, o sistema deve **automaticamente**:
+1. **Detectar subtasks** via `taskManager.getSubtasks(taskId)`
+2. **Correlacionar com fases** do plan.md (por ordem ou nome)
+3. **Salvar mapeamento** no context.md para uso pelo `/engineer/work`
+4. **Validar correlação** e alertar se houver mismatch
+
+## Pesquisa
+
+Se você não tem certeza de como uma biblioteca específica funciona, você pode usar Context7 e Perplexity para buscar informações sobre ela. Então, não tente adivinhar.
+
+## 🔗 Referências
+
+- Abstração: `.cursor/utils/task-manager/`
+- Detector: `.cursor/utils/task-manager/detector.md`
+- Factory: `.cursor/utils/task-manager/factory.md`
+
+<feature-slug>
+#$ARGUMENTS
+</feature-slug>
+
+
+---
+
+## 📚 Pré-requisitos
+
+Domine comandos starter antes de usar este comando intermediate/advanced.
+
+Consulte os comandos help para ver hierarquia completa:
+- /business/help --level=starter
+- /technical/help --level=starter
+
+💡 Comandos intermediate/advanced assumem familiaridade com workflows básicos.