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

package/templates/.cursor/docs/product/story-points-integration.md

@@ -0,0 +1,254 @@
+# 📊 Integração Automática de Story Points
+
+Documentação da integração automática de estimativas de story points nos comandos do Sistema Onion.
+
+## 🎯 Objetivo
+
+Automaticamente calcular e atualizar story points em todas as tarefas criadas ou modificadas pelos comandos do Sistema Onion, garantindo:
+- Estimativas precisas baseadas no Framework de Story Points
+- Rastreabilidade de mudanças (histórico)
+- Consistência entre task principal e subtasks
+- Alertas para épicos (>13 pontos)
+
+## 🔄 Comandos Integrados
+
+### ✅ `/product/task`
+**Quando:** Ao criar task com decomposição hierárquica
+
+**Ações:**
+1. Estima story points para **task principal** após decomposição
+2. Estima story points para **cada subtask** individualmente
+3. Valida consistência (soma subtasks vs task principal)
+4. Alerta se task > 13 pontos (épico)
+5. Insere estimativas em custom fields e descrições
+6. Adiciona comentário com análise completa
+
+**Output:**
+```
+🎲 STORY POINTS:
+∟ Task Principal: [X] pontos
+∟ Subtasks: [Y] pontos ([N] subtasks)
+∟ Total: [Z] pontos
+```
+
+### ✅ `/product/collect`
+**Quando:** Ao coletar nova ideia/feature/bug
+
+**Ações:**
+1. Estima story points após criar task
+2. Atualiza custom field "Story Points"
+3. Adiciona comentário com análise inicial
+4. Alerta se > 13 pontos (pode precisar refinement)
+
+**Nota:** Estimativa inicial pode ser refinada posteriormente.
+
+### ✅ `/product/refine`
+**Quando:** Ao refinar requisitos de uma task existente
+
+**Ações:**
+1. **Lê estimativa anterior** (custom field + comentários)
+2. **Recalcula** story points com requisitos refinados
+3. **Compara** estimativa anterior vs nova
+4. **Documenta histórico** de mudanças
+5. **Atualiza** custom field com nova estimativa
+6. **Adiciona comentário** com:
+   - Estimativa anterior
+   - Nova estimativa
+   - Delta (mudança)
+   - Motivo da mudança
+   - Análise atualizada
+
+**Template de Histórico:**
+```
+📊 HISTÓRICO DE ESTIMATIVAS:
+| Data | Estimativa | Mudança | Motivo |
+|------|------------|---------|--------|
+| [data inicial] | [X] pontos | - | Criação inicial |
+| [data refinamento] | [Y] pontos | [+/-Z] | Refinamento de requisitos |
+```
+
+### ✅ `/product/feature`
+**Quando:** Ao criar feature de backlog
+
+**Ações:**
+1. Estima story points após criar task
+2. Atualiza custom field "Story Points"
+3. Adiciona comentário com estimativa inicial
+4. Nota que estimativa pode ser refinada
+
+**Nota:** Features de backlog têm estimativas iniciais para planejamento.
+
+## 🔧 Agente Utilizado
+
+**@story-points-framework-specialist**
+
+Este agente é invocado automaticamente pelos comandos para:
+- Análise de domínio (técnico/negócio/infra/integração)
+- Seleção metodológica (Planning Poker / T-Shirt / Decomposição)
+- Aplicação de checklists (3/5/8/13 pontos)
+- Contextualização por senioridade
+- Detecção de épicos
+
+**Base de Conhecimento:**
+- `docs/knowbase/frameworks/framework_story_points.md`
+
+## 📋 Fluxo de Estimativa
+
+### 1. Criação de Task (`/product/task`)
+
+```
+1. Decompor hierarquicamente (task → subtasks → action items)
+2. Estimar task principal
+   └─ @story-points-framework-specialist
+3. Estimar cada subtask
+   └─ @story-points-framework-specialist (para cada)
+4. Validar consistência
+   └─ Se soma(subtasks) > principal: ajustar
+   └─ Se principal > 13: alertar épico
+5. Criar task com estimativas
+   └─ Custom field "Story Points"
+   └─ Descrição com análise
+   └─ Comentário inicial
+```
+
+### 2. Refinamento (`/product/refine`)
+
+```
+1. Ler estimativa anterior
+   └─ Custom field atual
+   └─ Comentários anteriores
+2. Recalcular com requisitos refinados
+   └─ @story-points-framework-specialist
+3. Comparar e documentar
+   └─ Calcular delta
+   └─ Identificar mudanças que afetaram
+4. Atualizar task
+   └─ Custom field atualizado
+   └─ Comentário com histórico
+   └─ Descrição atualizada
+```
+
+## 📊 Estrutura de Dados
+
+### Custom Field "Story Points"
+- **Tipo:** Number
+- **Localização:** Task principal e subtasks
+- **Atualização:** Automática em criação e refinamento
+
+### Comentários de Estimativa
+
+**Formato Padrão:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📊 ESTIMATIVA DE STORY POINTS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🎲 Story Points: [X] pontos
+
+⚡ ANÁLISE:
+∟ Complexidade: [alta/média/baixa]
+∟ Risco: [alto/médio/baixo]
+∟ Incerteza: [alta/média/baixa]
+
+💡 RECOMENDAÇÕES:
+[lista de recomendações]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Formato de Histórico (Refine):**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🔄 ESTIMATIVA ATUALIZADA APÓS REFINAMENTO
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📅 Data: [data]
+
+📊 HISTÓRICO:
+∟ Estimativa anterior: [X] pontos
+∟ Nova estimativa: [Y] pontos
+∟ Mudança: [+/-Z] pontos
+
+📝 MUDANÇAS QUE AFETARAM A ESTIMATIVA:
+- [mudança 1]
+- [mudança 2]
+
+💡 RECOMENDAÇÕES:
+[recomendações atualizadas]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## ⚠️ Regras e Validações
+
+### Validação de Consistência
+
+**Regra:** Soma das subtasks não deve ser muito diferente da task principal
+
+```typescript
+if (sum(subtasks) > mainTask * 1.5) {
+  // Ajustar task principal para soma das subtasks
+  mainTask = sum(subtasks);
+  log("⚠️ Ajustada estimativa da task principal para consistência");
+}
+```
+
+### Detecção de Épicos
+
+**Regra:** Tasks > 13 pontos devem ser alertadas
+
+```typescript
+if (storyPoints > 13) {
+  alert("⚠️ Task identificada como ÉPICO");
+  suggest("Quebrar em múltiplas tasks menores");
+  log("Recomendação: usar estratégia de quebra por camadas/funcionalidades");
+}
+```
+
+### Histórico Obrigatório
+
+**Regra:** Mudanças de estimativa devem sempre manter histórico
+
+```typescript
+const history = {
+  date: new Date(),
+  previous: previousEstimate,
+  current: newEstimate,
+  delta: newEstimate - previousEstimate,
+  reason: "Refinamento de requisitos",
+  changes: identifiedChanges
+};
+
+// Sempre adicionar ao histórico antes de atualizar
+addToHistory(taskId, history);
+updateEstimate(taskId, newEstimate);
+```
+
+## 🔗 Comandos Relacionados
+
+- `/product/estimate` - Estimativa manual/standalone
+- `/product/task` - Criação com estimativa automática
+- `/product/collect` - Coleta com estimativa inicial
+- `/product/refine` - Refinamento com recalculo automático
+- `/product/feature` - Feature backlog com estimativa
+
+## 📚 Referências
+
+- **Agente:** @story-points-framework-specialist
+- **Framework:** `docs/knowbase/frameworks/framework_story_points.md`
+- **Comando de Estimativa:** `/product/estimate`
+- **Padrões ClickUp:** `.cursor/docs/clickup/clickup-auto-update-strategy.md`
+
+## 🚀 Próximos Passos
+
+1. **Configurar Custom Field:** Garantir que "Story Points" existe no ClickUp/Asana
+2. **Calibrar Baseline:** Estabelecer histórias de referência
+3. **Tracking de Velocity:** Implementar dashboard de velocity
+4. **Accuracy Rate:** Calcular precisão das estimativas ao longo do tempo
+
+---
+
+**Versão:** 3.0.0  
+**Última atualização:** 2025-11-24  
+**Mantido por:** Sistema Onion
+

package/templates/.cursor/docs/product/story-points-validation.md

@@ -0,0 +1,224 @@
+# 🎲 Validação de Story Points no `/engineer/start`
+
+Documentação sobre a validação automática de story points antes de iniciar desenvolvimento.
+
+## 🎯 Objetivo
+
+Garantir que tasks tenham estimativas de story points antes de iniciar desenvolvimento, melhorando:
+- Planejamento de sprints
+- Tracking de velocity
+- Previsibilidade de entrega
+- Consistência nas estimativas
+
+## ⚡ Quando Ocorre
+
+A validação acontece automaticamente no comando `/engineer/start` após:
+1. Carregar task do gerenciador configurado
+2. Ler custom field "Story Points"
+3. Antes de iniciar análise e arquitetura
+
+## 🔍 Tipos de Validação
+
+### 1. Task Sem Estimativa
+
+**Condição:** `storyPoints === null || storyPoints === 0 || storyPoints === undefined`
+
+**Ação:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚠️ ATENÇÃO: TASK SEM ESTIMATIVA DE STORY POINTS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 Task: [nome da task]
+🎲 Story Points: Não estimado
+
+💡 RECOMENDAÇÕES:
+∟ Estimar antes de iniciar desenvolvimento
+∟ Usar: /product/estimate "[nome da task]"
+∟ Ou: @story-points-framework-specialist
+
+⚠️ Continuar sem estimativa pode afetar:
+   - Planejamento de sprint
+   - Tracking de velocity
+   - Previsibilidade de entrega
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Comportamento:**
+- ⚠️ **Alerta** (não bloqueia)
+- 💡 **Oferece** estimar agora
+- ✅ **Permite** continuar sem estimativa (com aviso)
+
+### 2. Task Identificada como Épico
+
+**Condição:** `storyPoints > 13`
+
+**Ação:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚠️ ALERTA: TASK IDENTIFICADA COMO ÉPICO
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 Task: [nome da task]
+🎲 Story Points: [X] pontos (> 13)
+
+💡 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
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Comportamento:**
+- ⚠️ **Alerta** sobre riscos
+- 💡 **Sugere** quebrar task
+- ❓ **Pergunta** se deseja continuar mesmo assim
+- ✅ **Permite** continuar após confirmação
+
+### 3. Task com Estimativa Válida
+
+**Condição:** `storyPoints >= 1 && storyPoints <= 13`
+
+**Ação:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ VALIDAÇÃO DE ESTIMATIVA
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 Task: [nome da task]
+🎲 Story Points: [X] pontos
+
+✅ Estimativa válida para desenvolvimento
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Comportamento:**
+- ✅ **Confirma** estimativa válida
+- 🚀 **Prossegue** normalmente
+
+## 🔧 Implementação
+
+### Código de Validação
+
+```typescript
+// No comando /engineer/start, após carregar task
+const task = await taskManager.getTask(taskId);
+const storyPoints = task.customFields?.find(f => f.name === 'Story Points')?.value;
+
+if (!storyPoints || storyPoints === 0) {
+  // Validação 1: Sem estimativa
+  await showWarningNoEstimate(task);
+  const shouldEstimate = await askUser('Deseja estimar story points agora? (s/n)');
+  if (shouldEstimate) {
+    await invokeStoryPointsEstimation(task);
+  }
+} else if (storyPoints > 13) {
+  // Validação 2: Épico
+  await showWarningEpic(task, storyPoints);
+  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 {
+  // Validação 3: OK
+  await showSuccessEstimate(task, storyPoints);
+}
+```
+
+### Integração com Agente
+
+```typescript
+async function invokeStoryPointsEstimation(task: Task) {
+  // Invocar agente de estimativa
+  const estimate = await invokeAgent('story-points-framework-specialist', {
+    taskDescription: task.name + '\n' + task.description,
+    assigneeLevel: task.assignee?.level || 'pleno'
+  });
+  
+  // Atualizar task com estimativa
+  await taskManager.updateTask(task.id, {
+    customFields: {
+      'Story Points': estimate.points
+    }
+  });
+  
+  // Adicionar comentário
+  await taskManager.addComment(task.id, formatEstimateComment(estimate));
+}
+```
+
+## 📊 Fluxo Completo
+
+```mermaid
+graph TD
+    A[/engineer/start] --> B[Carregar Task]
+    B --> C{Task tem Story Points?}
+    C -->|Não| D[Alerta: Sem Estimativa]
+    D --> E{Deseja estimar?}
+    E -->|Sim| F[Invocar @story-points-framework-specialist]
+    E -->|Não| G[Continuar com aviso]
+    F --> H[Atualizar Task]
+    H --> I[Prosseguir]
+    C -->|Sim| J{Story Points > 13?}
+    J -->|Sim| K[Alerta: Épico]
+    K --> L{Deseja continuar?}
+    L -->|Sim| I
+    L -->|Não| M[Sugerir refinement]
+    J -->|Não| N[Validar Estimativa]
+    N --> I
+    G --> I
+```
+
+## ⚠️ Regras Importantes
+
+### Não Bloqueia Desenvolvimento
+
+**Princípio:** Validação é **informativa**, não bloqueante.
+
+- ⚠️ Alerta sobre problemas
+- 💡 Oferece soluções
+- ✅ Permite continuar após confirmação
+
+### Estimativa Opcional mas Recomendada
+
+**Princípio:** Estimativas melhoram planejamento, mas não são obrigatórias.
+
+- Tasks sem estimativa podem ser desenvolvidas
+- Sistema alerta sobre impacto
+- Usuário decide se estima ou não
+
+### Épicos Podem Ser Desenvolvidos
+
+**Princípio:** Tasks grandes podem existir, mas devem ser conscientes.
+
+- Sistema alerta sobre riscos
+- Sugere quebra quando apropriado
+- Permite continuar após confirmação
+
+## 🔗 Comandos Relacionados
+
+- `/product/estimate` - Estimar task manualmente
+- `/product/refine` - Refinar e recalcular estimativa
+- `/product/task` - Criar task com estimativa automática
+
+## 📚 Referências
+
+- **Agente:** @story-points-framework-specialist
+- **Framework:** `docs/knowbase/frameworks/framework_story_points.md`
+- **Integração:** `.cursor/docs/product/story-points-integration.md`
+
+---
+
+**Versão:** 3.0.0  
+**Última atualização:** 2025-11-24  
+**Mantido por:** Sistema Onion
+

package/templates/.cursor/docs/reviews/task-manager-docs-review-2025-11-24.md

@@ -0,0 +1,167 @@
+# 📋 Revisão de Documentação - Task Manager
+**Data**: 2025-11-24  
+**Revisado por**: Sistema Onion  
+**Escopo**: Documentos relacionados ao Task Manager
+
+---
+
+## ✅ **PROBLEMAS CORRIGIDOS**
+
+### 1. **Referências Incorretas de Arquivos**
+
+#### Problema Identificado
+Múltiplos documentos referenciavam `.cursor/utils/clickup-formatting.md`, mas o arquivo correto está em `.cursor/docs/clickup/clickup-formatting.md`.
+
+#### Arquivos Corrigidos
+- ✅ `.cursor/commands/product/task.md` (linha 545)
+- ✅ `.cursor/docs/tools/rules.md` (linhas 143 e 168)
+- ✅ `.cursor/commands/git/README.md` (linha 359)
+- ✅ `.cursor/utils/date-time-standards.md` (linha 123)
+
+#### Correção Aplicada
+```diff
+- **Formatação:** `.cursor/utils/clickup-formatting.md`
++ **Formatação:** `.cursor/docs/clickup/clickup-formatting.md`
+```
+
+---
+
+## 📊 **VALIDAÇÃO DE ESTRUTURA**
+
+### Documentos do Task Manager
+
+#### ✅ **Interface e Tipos**
+- `.cursor/utils/task-manager/interface.md` ✅ Bem formatado
+- `.cursor/utils/task-manager/types.md` ✅ Bem formatado
+- `.cursor/utils/task-manager/detector.md` ✅ Bem formatado
+- `.cursor/utils/task-manager/factory.md` ✅ Bem formatado
+- `.cursor/utils/task-manager/README.md` ✅ Bem formatado
+
+#### ✅ **Adapters**
+- `.cursor/utils/task-manager/adapters/clickup.md` ✅ Bem formatado
+- `.cursor/utils/task-manager/adapters/asana.md` ✅ Bem formatado
+- `.cursor/utils/task-manager/adapters/linear.md` ✅ Bem formatado (stub)
+
+#### ✅ **Formatação ClickUp**
+- `.cursor/docs/clickup/clickup-formatting.md` ✅ Bem formatado
+- `.cursor/commands/common/prompts/clickup-patterns.md` ✅ Bem formatado
+
+#### ✅ **Comando Principal**
+- `.cursor/commands/product/task.md` ✅ Referências corrigidas
+
+---
+
+## 🔍 **ANÁLISE DE CONSISTÊNCIA**
+
+### Padrões de Formatação
+
+#### ✅ **Estratégia Dual Documentada Corretamente**
+- **Descriptions**: Markdown nativo (`markdown_description`)
+- **Comments**: Unicode visual (`comment_text`)
+
+Ambos os documentos (`clickup-formatting.md` e `clickup-patterns.md`) estão alinhados com esta estratégia.
+
+#### ✅ **Templates Consistentes**
+- Templates de descriptions seguem padrão markdown
+- Templates de comments seguem padrão Unicode visual
+- Separadores consistentes: `━━━━━━━━━━━━━━` (22 caracteres)
+
+#### ✅ **Referências Cruzadas**
+- Comando `/product/task.md` referencia corretamente:
+  - Interface do Task Manager ✅
+  - Adapters específicos ✅
+  - Padrões de formatação ✅
+
+---
+
+## 📚 **ESTRUTURA DE DOCUMENTAÇÃO**
+
+### Hierarquia Validada
+
+```
+.cursor/
+├── utils/task-manager/          ✅ Abstração do Task Manager
+│   ├── interface.md             ✅ Contrato ITaskManager
+│   ├── types.md                 ✅ Tipos compartilhados
+│   ├── detector.md              ✅ Detecção de provedor
+│   ├── factory.md               ✅ Factory de adapters
+│   ├── README.md                ✅ Visão geral
+│   └── adapters/
+│       ├── clickup.md           ✅ Adapter ClickUp
+│       ├── asana.md             ✅ Adapter Asana
+│       └── linear.md            ✅ Adapter Linear (stub)
+│
+├── docs/clickup/                ✅ Documentação ClickUp
+│   └── clickup-formatting.md    ✅ Templates e padrões
+│
+└── commands/
+    ├── product/task.md          ✅ Comando principal
+    └── common/prompts/
+        └── clickup-patterns.md  ✅ Padrões de formatação
+```
+
+---
+
+## ✅ **CHECKLIST DE VALIDAÇÃO**
+
+### Formatação
+- [x] Todos os documentos seguem padrão markdown consistente
+- [x] Emojis usados de forma consistente
+- [x] Separadores Unicode padronizados
+- [x] Tabelas formatadas corretamente
+
+### Referências
+- [x] Todas as referências de arquivos estão corretas
+- [x] Links cruzados funcionam
+- [x] Referências a adapters estão corretas
+- [x] Referências a templates estão corretas
+
+### Conteúdo
+- [x] Estratégia dual bem documentada
+- [x] Templates completos e consistentes
+- [x] Exemplos de uso presentes
+- [x] Mapeamentos de status documentados
+
+### Estrutura
+- [x] Hierarquia de arquivos lógica
+- [x] Organização por responsabilidade
+- [x] READMEs informativos
+- [x] Documentação completa
+
+---
+
+## 🎯 **RECOMENDAÇÕES**
+
+### ✅ **Nenhuma Ação Necessária**
+Todos os documentos estão bem formatados e consistentes após as correções de referências.
+
+### 📝 **Observações**
+1. **Linear Adapter**: Documentado como stub - correto para implementação futura
+2. **Formatação Dual**: Estratégia bem documentada em múltiplos lugares
+3. **Templates**: Padrões consistentes entre documentos
+
+---
+
+## 📊 **ESTATÍSTICAS**
+
+- **Documentos revisados**: 12
+- **Referências corrigidas**: 4
+- **Problemas encontrados**: 4
+- **Problemas corrigidos**: 4
+- **Taxa de sucesso**: 100%
+
+---
+
+## 🚀 **PRÓXIMOS PASSOS**
+
+Nenhuma ação adicional necessária. Todos os documentos estão:
+- ✅ Bem formatados
+- ✅ Consistentes entre si
+- ✅ Com referências corretas
+- ✅ Estruturados logicamente
+
+---
+
+**Revisão concluída**: 2025-11-24  
+**Status**: ✅ APROVADO
+