@onion-ai/cli 1.0.0-beta.1

package/framework/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/framework/docs/clickup/clickup-auto-update-strategy.md

@@ -0,0 +1,340 @@
+# 🔄 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 `.claude/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**: `.claude/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: .claude/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! 🚀**