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

package/templates/.cursor/docs/clickup/clickup-acceptance-criteria-strategy.md

@@ -0,0 +1,329 @@
+# 📋 Estratégia de Critérios de Aceitação com Checkboxes Interativos
+
+## 🎯 Objetivo
+
+Usar **checkboxes markdown interativos** nativos do ClickUp para rastreamento visual de critérios de aceitação durante desenvolvimento.
+
+---
+
+## ✅ Como Funciona
+
+### O ClickUp Renderiza Checkboxes Markdown
+
+O ClickUp renderiza automaticamente checkboxes markdown em descriptions:
+
+```markdown
+- [ ] Critério não marcado
+- [x] Critério marcado
+```
+
+**Resultado no ClickUp:**
+- ☑️ Checkboxes **completamente interativos**
+- ✅ Podem ser **marcados/desmarcados** dinamicamente
+- 📊 **Rastreamento visual** de progresso
+- 🎯 **Não requer API** especial, tudo via markdown
+
+---
+
+## 📝 Template de Critérios de Aceitação
+
+### Para DESCRIPTIONS (Markdown com Checkboxes):
+
+```markdown
+## 🎯 Objetivo da Task
+
+[DESCRIÇÃO_DETALHADA]
+
+---
+
+## 📋 Escopo de Implementação
+
+### ✅ Funcionalidades:
+- [x] Feature A - Implementada
+- [ ] Feature B - Em progresso
+- [ ] Feature C - Pendente
+
+### 🔧 Arquitetura Técnica:
+- [x] Componente X modificado
+- [ ] Integration Y implementada
+
+### 📊 Métricas Esperadas:
+
+| Metric | Before | After | Target |
+|--------|--------|-------|--------|
+| Performance | N/A | [VALOR] | ✅ |
+| Coverage | N/A | [VALOR] | ✅ |
+
+---
+
+## ✅ Critérios de Aceitação
+
+- [ ] Funcionalidade A implementada
+- [ ] Testes passando com cobertura > 95%
+- [ ] Documentation atualizada
+- [ ] Performance dentro do target
+- [ ] Code review aprovado
+
+---
+
+**🎯 Success Metric**: Todos os critérios marcados = Task completa  
+**🕒 Timeline**: [PRAZO_ESTIMADO]
+```
+
+---
+
+## 🔄 Fluxo de Atualização Durante Desenvolvimento
+
+### Quando Usar `/engineer/work`:
+
+```
+Fase 1: Backend Implementation
+├── ✅ COMPLETA
+└── Marcar critérios relacionados como [x]
+
+Fase 2: Frontend Integration
+├── 🔄 EM PROGRESSO
+└── Atualizar checkboxes conforme progresso
+
+Fase 3: Testing & QA
+├── ⏳ PENDENTE
+└── Manter como [ ] até início
+```
+
+### Atualização Automática de Checkboxes:
+
+**Quando uma fase é completada:**
+
+1. **Identificar critérios relacionados** àquela fase
+2. **Atualizar description** marcando checkboxes `[x]`
+3. **Adicionar comentário** com progresso
+4. **Manter sincronizado** conforme desenvolvimento
+
+---
+
+## 💻 Implementação em Comandos
+
+### Em `/engineer/work`:
+
+```typescript
+// Quando uma fase é completada
+async function completePhase(taskId, phaseName, criteria) {
+  // 1. Buscar description atual
+  const task = await mcp_clickup_get_task({ task_id: taskId });
+  let description = task.description;
+  
+  // 2. Marcar critérios relacionados
+  for (const criterion of criteria) {
+    // Trocar "- [ ]" por "- [x]" para este critério
+    description = description.replace(
+      `- [ ] ${criterion}`,
+      `- [x] ${criterion}`
+    );
+  }
+  
+  // 3. Atualizar description com checkboxes marcados
+  await mcp_clickup_update_task({
+    task_id: taskId,
+    markdown_description: description
+  });
+  
+  // 4. Adicionar comentário com progresso
+  await mcp_clickup_create_task_comment({
+    task_id: taskId,
+    comment_text: `✅ Fase Completada: ${phaseName}
+    
+    Critérios de aceitação relacionados marcados como completos.
+    Veja description para status visual completo.`
+  });
+}
+```
+
+### Em `/product/check-acceptance`:
+
+```typescript
+// Validar e marcar automaticamente critérios
+async function checkAcceptanceCriteria(taskId) {
+  // 1. Buscar task
+  const task = await mcp_clickup_get_task({ task_id: taskId });
+  
+  // 2. Extrair critérios da description
+  const criteria = extractCriteria(task.markdown_description);
+  
+  // 3. Validar cada um
+  let updated = false;
+  let newDescription = task.markdown_description;
+  
+  for (const criterion of criteria) {
+    const isValid = await validateCriterion(criterion);
+    
+    if (isValid && criterion.status === 'unchecked') {
+      // Marcar como válido
+      newDescription = newDescription.replace(
+        `- [ ] ${criterion.text}`,
+        `- [x] ${criterion.text} ✅`
+      );
+      updated = true;
+    }
+  }
+  
+  // 4. Atualizar se houve mudanças
+  if (updated) {
+    await mcp_clickup_update_task({
+      task_id: taskId,
+      markdown_description: newDescription
+    });
+    
+    console.log(`✅ ${countMarked(newDescription)}/${criteria.length} critérios marcados`);
+  }
+}
+```
+
+---
+
+## 📊 Exemplo Prático
+
+### Task Inicial (Todos pendentes):
+
+```markdown
+## ✅ Critérios de Aceitação
+
+- [ ] Usuário consegue fazer login com email/senha
+- [ ] JWT é gerado e retornado após login
+- [ ] Refresh token permite renovação de sessão
+- [ ] Rotas protegidas bloqueam acesso não autenticado
+- [ ] Logout invalida tokens corretamente
+- [ ] Testes de segurança passando
+- [ ] Documentação de API atualizada
+```
+
+**Progresso Visual:** 0/7 completos
+
+---
+
+### Após Fase 1 (Backend completa):
+
+```markdown
+## ✅ Critérios de Aceitação
+
+- [x] Usuário consegue fazer login com email/senha
+- [x] JWT é gerado e retornado após login
+- [x] Refresh token permite renovação de sessão
+- [ ] Rotas protegidas bloqueam acesso não autenticado
+- [x] Logout invalida tokens corretamente
+- [ ] Testes de segurança passando
+- [ ] Documentação de API atualizada
+```
+
+**Progresso Visual:** 4/7 completos
+
+---
+
+### Após Fase 2 (Frontend completa):
+
+```markdown
+## ✅ Critérios de Aceitação
+
+- [x] Usuário consegue fazer login com email/senha
+- [x] JWT é gerado e retornado após login
+- [x] Refresh token permite renovação de sessão
+- [x] Rotas protegidas bloqueam acesso não autenticado
+- [x] Logout invalida tokens corretamente
+- [ ] Testes de segurança passando
+- [ ] Documentação de API atualizada
+```
+
+**Progresso Visual:** 5/7 completos
+
+---
+
+### Após Validação (Todos completos):
+
+```markdown
+## ✅ Critérios de Aceitação
+
+- [x] Usuário consegue fazer login com email/senha ✅
+- [x] JWT é gerado e retornado após login ✅
+- [x] Refresh token permite renovação de sessão ✅
+- [x] Rotas protegidas bloqueam acesso não autenticado ✅
+- [x] Logout invalida tokens corretamente ✅
+- [x] Testes de segurança passando ✅
+- [x] Documentação de API atualizada ✅
+```
+
+**Progresso Visual:** 7/7 completos ✅
+
+---
+
+## 🎯 Benefícios
+
+### Para Desenvolvedores:
+- ✅ Visão clara do progresso
+- ✅ Feedback imediato ao marcar
+- ✅ Rastreamento de cada critério
+- ✅ Fácil identificar o que falta
+
+### Para Product Owners:
+- ✅ Status visual na description
+- ✅ Não precisa abrir comentários
+- ✅ Fácil ver completude da task
+- ✅ Melhor comunicação do progresso
+
+### Para Code Reviewers:
+- ✅ Validação rápida de requisitos
+- ✅ Checklist de aceitar/rejeitar
+- ✅ Rastreabilidade de critérios
+- ✅ Menos discussão sobre requisitos
+
+---
+
+## 🔧 Boas Práticas
+
+### ✅ Fazer:
+- ✅ Manter checkboxes simples e diretos
+- ✅ Descrever o que cada critério testa
+- ✅ Usar linguagem clara e acionável
+- ✅ Atualizar regularmente conforme progresso
+- ✅ Marcar como completo quando realmente está pronto
+
+### ❌ Evitar:
+- ❌ Critérios muito vagos ou ambíguos
+- ❌ Criterios não mensuráveis
+- ❌ Marcar como completo sem validar
+- ❌ Deixar checkboxes desatualizados
+- ❌ Misturar com informações técnicas detalhadas
+
+---
+
+## 📚 Integração com Outros Comandos
+
+### `/product/task`
+- Cria task com template de checkboxes
+- Descrição já inclui seção de critérios
+
+### `/engineer/work`
+- Marca checkboxes ao completar fases
+- Atualiza description conforme progresso
+
+### `/product/check-acceptance`
+- Valida automaticamente critérios
+- Marca como completo quando validado
+
+### `/engineer/pr`
+- Referencia checkboxes na PR
+- Valida que todos estão marcados antes de merge
+
+---
+
+## 🚀 Próximos Passos
+
+1. **Usar em `/product/task`** - Template com checkboxes
+2. **Atualizar `/engineer/work`** - Marcar conforme completa
+3. **Criar `/product/check-acceptance`** - Validação automática
+4. **Testar com task real** - Validar fluxo completo
+
+---
+
+**Última atualização**: 2025-11-05  
+**Status**: Documentado e pronto para implementação  
+**Prioridade**: ALTA - Rastreamento visual de progresso
+

package/templates/.cursor/docs/clickup/clickup-auto-update-strategy.md

@@ -0,0 +1,318 @@
+# 🔄 Estratégia de Auto-Update ClickUp
+
+Este documento define quando e como os comandos do Sistema Onion devem **automaticamente atualizar** tasks no ClickUp vs quando devem **pedir confirmação** do usuário.
+
+## 🎯 **Princípios Fundamentais**
+
+### **✅ Atualização AUTOMÁTICA quando:**
+- ✅ **Baixo risco** - mudança é informativa/progress tracking
+- ✅ **Esperado pelo usuário** - parte natural do comando
+- ✅ **Reversível** - pode ser desfeito facilmente
+- ✅ **Status tracking** - progresso natural do workflow
+
+### **⚠️ Confirmação NECESSÁRIA quando:**
+- ⚠️ **Alto impacto** - mudança afeta timeline/priority/assignees
+- ⚠️ **Irreversível** - não pode ser facilmente desfeito
+- ⚠️ **Decisão de negócio** - requer aprovação stakeholder
+- ⚠️ **Múltiplas opções** - várias alternativas possíveis
+
+## 📊 **Matriz de Decisão por Comando**
+
+| Comando | Auto-Update | Confirmação | Detalhes |
+|---------|-------------|-------------|----------|
+| **`/product/task`** | ✅ Status → "To Do" | - | Task criada em estado inicial |
+| **`/engineer/start`** | ✅ Status → "In Progress" | - | Início natural do desenvolvimento |
+| **`/engineer/work`** | ✅ Comentário DETALHADO na subtask<br>✅ Comentário RESUMIDO na task principal<br>✅ Status da subtask → "Done" | - | **ESTRATÉGIA DUAL** - Ver `.cursor/docs/clickup/clickup-dual-comment-strategy.md` |
+| **`/engineer/pre-pr`** | ✅ Comments de checklist | - | Preparação para PR |
+| **`/engineer/pr`** | ✅ Status → "In Progress"<br>✅ Tag "under-review"<br>✅ Comment PR details | - | **JÁ IMPLEMENTADO** |
+| **`/product/task-check`** | ✅ Comments de verificação | ⚠️ Status change | Verificação é tracking, mas status requer decisão |
+| **`/product/validate-task`** | ✅ Comments de análise | ⚠️ Priority/Status changes | Análise é tracking, mudanças estruturais requerem aprovação |
+| **`/engineer/bump`** | ✅ Comments de versioning | - | Tracking de releases |
+| **`/engineer/docs`** | ✅ Comments de documentação | - | Updates de docs |
+
+## 🔧 **Implementação por Comando**
+
+### **1. `/product/task-check <task-id>`**
+
+#### **Auto-Update SEMPRE:**
+```javascript
+// Comentário automático com resultados
+create_task_comment({
+  taskId: taskId,
+  commentText: `🔍 VERIFICAÇÃO DE IMPLEMENTAÇÃO
+
+━━━━━━━━━━━━━━━━━━━━━━━━
+
+📊 RESULTADO DA VERIFICAÇÃO:
+   ∟ Status: ${verificationStatus}
+   ∟ Completude: ${completionPercentage}%
+   ∟ Arquivos verificados: ${filesChecked}
+
+✅ IMPLEMENTADO:
+   ∟ ${implementedFeatures.join('\n   ∟ ')}
+
+⚠️ PENDENTE:
+   ∟ ${pendingItems.join('\n   ∟ ')}
+
+━━━━━━━━━━━━━━━━━━━━━━━━
+
+⏰ Verificado: ${timestamp} | 🎯 Próximo: ${nextAction}`
+})
+```
+
+#### **Confirmação SE necessário:**
+```javascript
+if (verificationStatus === 'COMPLETE' && currentStatus !== 'Done') {
+  // Perguntar se deve mover para Done
+  const userConfirm = await askUser("Task verificada como completa. Mover status para 'Done'?")
+  if (userConfirm) {
+    update_task({ taskId, status: 'Done' })
+  }
+}
+```
+
+### **2. `/product/validate-task <task-id>`**
+
+#### **Auto-Update SEMPRE:**
+```javascript
+create_task_comment({
+  taskId: taskId,
+  commentText: `📊 VALIDAÇÃO ESTRATÉGICA
+
+━━━━━━━━━━━━━━━━━━━━━━━━
+
+🎯 ANÁLISE EXECUTIVA:
+   ∟ Viabilidade: ${viabilityScore}/10
+   ∟ Alinhamento: ${alignmentScore}/10
+   ∟ Complexidade: ${complexityLevel}
+
+✅ PONTOS FORTES:
+   ∟ ${strongPoints.join('\n   ∟ ')}
+
+⚠️ RISCOS IDENTIFICADOS:
+   ∟ ${risks.join('\n   ∟ ')}
+
+💡 RECOMENDAÇÕES:
+   ∟ ${recommendations.join('\n   ∟ ')}
+
+━━━━━━━━━━━━━━━━━━━━━━━━
+
+⏰ Validado: ${timestamp} | 🎯 Status: ${validationResult}`
+})
+```
+
+#### **Confirmação PARA mudanças estruturais:**
+```javascript
+if (recommendations.includes('PRIORITY_CHANGE')) {
+  const newPriority = await askUser(`Recomendo mudar prioridade para ${suggestedPriority}. Confirmar?`)
+}
+
+if (recommendations.includes('SCOPE_REDUCTION')) {
+  const confirmed = await askUser(`Task muito complexa. Quebrar em subtasks?`)
+}
+```
+
+### **3. `/engineer/work` (ESTRATÉGIA DUAL)**
+
+#### **Auto-Update SEMPRE (em ORDEM):**
+
+**1. Comentário DETALHADO na SUBTASK:**
+```javascript
+// Comentário técnico completo na subtask correspondente
+const subtaskId = getSubtaskIdForPhase(currentPhase, contextMd);
+
+await mcp_clickup_create_task_comment({
+  task_id: subtaskId,  // ← SUBTASK ID
+  workspace_id: workspaceId,
+  comment_text: `🔧 FASE COMPLETADA: ${phaseName}
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📁 ARQUIVOS MODIFICADOS:
+   ∟ ${file1}
+   ∟ ${file2}
+   ∟ ... e mais ${moreFiles.length} arquivos
+
+🔧 IMPLEMENTAÇÕES:
+   ▶ ${implementation1}
+   ▶ ${implementation2}
+
+✅ TESTES ADICIONADOS:
+   ∟ ${testFile1} (${testCount1} testes)
+   ∟ Cobertura: ${coverage}%
+
+💡 DECISÕES TÉCNICAS:
+   ∟ ${decision1}
+   ∟ ${decision2}
+
+🚀 PRÓXIMOS PASSOS:
+   ∟ ${nextPhase}
+   ∟ ${nextAction1}
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+⏰ Completado: ${timestamp} | 🎯 Status: Done`
+});
+```
+
+**2. Atualizar STATUS da SUBTASK:**
+```javascript
+await mcp_clickup_update_task({
+  task_id: subtaskId,  // ← SUBTASK ID
+  workspace_id: workspaceId,
+  status: 'Done'
+});
+```
+
+**3. Comentário RESUMIDO na TASK PRINCIPAL:**
+```javascript
+const mainTaskId = getMainTaskId(contextMd);
+
+await mcp_clickup_create_task_comment({
+  task_id: mainTaskId,  // ← MAIN TASK ID
+  workspace_id: workspaceId,
+  comment_text: `📝 PROGRESSO: Fase ${phaseNum}/${totalPhases} Completada
+
+✅ ${phaseName} - Concluída
+   ∟ Subtask: #${subtaskId}
+   ∟ Detalhes: Ver comentário na subtask
+
+🎯 Próximo: Fase ${nextPhaseNum} - ${nextPhaseName}
+
+⏰ ${timestamp}`
+});
+```
+
+**📚 Documentação completa**: `.cursor/docs/clickup/clickup-dual-comment-strategy.md`
+
+### **4. `/engineer/start <slug>` (quando sessão tem task-id)**
+
+#### **Auto-Update SEMPRE:**
+```javascript
+update_task({
+  taskId: sessionTaskId,
+  status: 'In Progress'
+})
+
+create_task_comment({
+  taskId: sessionTaskId,
+  commentText: `🚀 DESENVOLVIMENTO INICIADO
+
+━━━━━━━━━━━━━━━━━━━━━━━━
+
+🏗️ SESSÃO ATIVADA:
+   ▶ Branch: ${featureBranch}
+   ▶ Sessão: .cursor/sessions/${slug}/
+   ▶ Arquitetura: Definida e aprovada
+
+📋 PLANO DE IMPLEMENTAÇÃO:
+   ∟ ${phases.join('\n   ∟ ')}
+
+━━━━━━━━━━━━━━━━━━━━━━━━
+
+⏰ Iniciado: ${timestamp} | 🎯 Próximo: Implementar Fase 1`
+})
+```
+
+## ⚙️ **Configuração por Comando**
+
+### **Pattern de Implementação:**
+
+```typescript
+interface AutoUpdateConfig {
+  command: string
+  autoUpdates: {
+    status?: string
+    tags?: string[]
+    comments: boolean
+    properties?: Record<string, any>
+  }
+  confirmationRequired: {
+    statusChanges?: string[]
+    priorityChanges?: boolean
+    assigneeChanges?: boolean
+    scopeChanges?: boolean
+  }
+}
+
+const commandConfigs: AutoUpdateConfig[] = [
+  {
+    command: '/product/task-check',
+    autoUpdates: {
+      comments: true, // Sempre
+      tags: ['verified'] // Se verificação passou
+    },
+    confirmationRequired: {
+      statusChanges: ['Done', 'Closed'], // Só com confirmação
+      priorityChanges: true
+    }
+  },
+  {
+    command: '/engineer/pr',
+    autoUpdates: {
+      status: 'In Progress', // Automático
+      tags: ['under-review'], // Automático
+      comments: true // Automático
+    },
+    confirmationRequired: {} // Nenhuma confirmação necessária
+  }
+  // ... outros comandos
+]
+```
+
+## 🎯 **Casos Especiais**
+
+### **1. Task não encontrada na sessão atual**
+```javascript
+// Se comando é executado mas não há task-id na sessão
+if (!currentSessionTaskId && taskIdFromArgs) {
+  // Usar task-id fornecido pelo usuário
+  // Auto-update OK
+} else if (!currentSessionTaskId && !taskIdFromArgs) {
+  // Perguntar qual task atualizar
+  const taskId = await askUser("Qual task ID devo atualizar?")
+}
+```
+
+### **2. Múltiplas tasks em sessão**
+```javascript
+// Se sessão tem task pai + subtasks
+if (sessionHasMultipleTasks) {
+  // Sempre atualizar task principal
+  // Subtasks só com confirmação
+}
+```
+
+### **3. Task já finalizada**
+```javascript
+if (taskStatus === 'Done' || taskStatus === 'Closed') {
+  const confirm = await askUser("Task já está finalizada. Ainda assim atualizar?")
+  if (!confirm) return
+}
+```
+
+## 📝 **Implementação nos Comandos**
+
+Cada comando deve incluir esta seção antes dos argumentos:
+
+```markdown
+## 🔄 **Auto-Update ClickUp**
+
+Este comando **automaticamente atualiza** a task ClickUp quando:
+- ✅ Adiciona comentário com resultados da verificação
+- ✅ Aplica tag 'verified' se verificação passou
+
+Este comando **pede confirmação** para:
+- ⚠️ Mudança de status para 'Done' 
+- ⚠️ Alteração de prioridade baseada na análise
+- ⚠️ Quebra da task em subtasks
+
+### **📋 Identificação da Task:**
+1. **Sessão ativa**: Usa task-id do arquivo `context.md`
+2. **Argumento fornecido**: Usa task-id passado pelo usuário
+3. **Não identificada**: Pergunta ao usuário qual task atualizar
+```
+
+---
+
+**Esta estratégia garante produtividade máxima com controle adequado sobre mudanças críticas! 🚀**