@onion-architect-ai/cli 4.1.0-beta.4 → 4.1.0-beta.5

package/templates/.cursor/commands/engineer/help.md

@@ -0,0 +1,329 @@
+---
+name: help
+description: Lista comandos disponíveis do contexto Technical organizados por nível de complexidade
+model: sonnet
+category: technical
+tags: [help, discovery, onboarding, levels]
+version: "4.0.0"
+updated: "2025-12-20"
+level: starter
+context: technical
+---
+
+# Technical Context - Help
+
+Lista todos os comandos disponíveis no contexto **Technical**, organizados por nível de complexidade (starter, intermediate, advanced).
+
+---
+
+## 🎯 Uso
+
+```bash
+# Listar comandos starter (padrão - 80% dos casos)
+/technical/help
+
+# Listar comandos de um nível específico
+/technical/help --level=starter
+/technical/help --level=intermediate
+/technical/help --level=advanced
+
+# Listar todos os comandos
+/technical/help --level=all
+```
+
+---
+
+## 📋 Sistema de Níveis
+
+O Sistema Onion organiza comandos em **3 níveis** baseados na frequência de uso:
+
+| Nível | % Uso | Descrição | Onboarding |
+|-------|-------|-----------|------------|
+| **Starter** | 80% | Comandos essenciais para desenvolvimento diário | ~20 min |
+| **Intermediate** | 15% | Workflows avançados e operações especializadas | ~40 min |
+| **Advanced** | 5% | Automações complexas e casos edge | ~60 min |
+
+---
+
+## 📊 Comandos Disponíveis
+
+Você me pediu para executar o comando help. Vou listar os comandos organizados por nível:
+
+### 🌟 STARTER COMMANDS (8 comandos - 80% dos casos)
+**⏱️ Tempo de onboarding: ~20 minutos**
+
+Estes são os comandos que você usará no desenvolvimento diário:
+
+1. **`/technical/work "task-id"`**
+   - Continuar trabalho em feature ativa, lê sessão e identifica próxima fase
+   - Use quando: Retomar desenvolvimento de uma task em progresso
+   - Exemplo: `/technical/work "86adf8jj6"`
+
+2. **`/technical/plan "feature"`**
+   - Criar plano de desenvolvimento detalhado com fases
+   - Use quando: Iniciar nova feature, precisa quebrar em etapas
+   - Exemplo: `/technical/plan "user-authentication"`
+
+3. **`/technical/pr`**
+   - Criar Pull Request com descrição automática da sessão
+   - Use quando: Finalizar feature e submeter para review
+   - Exemplo: `/technical/pr`
+
+4. **`/technical/warm-up`**
+   - Preparar contexto técnico do projeto (stack, arquitetura, padrões)
+   - Use quando: Iniciar desenvolvimento em nova sessão
+   - Exemplo: `/technical/warm-up`
+
+5. **`/technical/docs`**
+   - Gerar/atualizar documentação técnica do projeto
+   - Use quando: Documentar feature implementada ou arquitetura
+   - Exemplo: `/technical/docs`
+
+6. **`/technical/sync`**
+   - Sincronizar branch local com remote, resolver conflitos
+   - Use quando: Atualizar código antes de começar desenvolvimento
+   - Exemplo: `/technical/sync`
+
+7. **`/technical/init`**
+   - Inicializar repositório git com gitflow ou outro workflow
+   - Use quando: Setup inicial de novo projeto
+   - Exemplo: `/technical/init`
+
+8. **`/technical/help`**
+   - Este comando! Lista comandos disponíveis por nível
+   - Use quando: Descobrir comandos ou aprender sistema
+   - Exemplo: `/technical/help --level=intermediate`
+
+---
+
+### 🔧 INTERMEDIATE COMMANDS (13 comandos - 15% dos casos)
+**⏱️ Tempo de onboarding: ~40 minutos**
+
+Comandos para workflows mais avançados:
+
+1. **`/technical/start "feature"`** - Iniciar nova feature (cria sessão, branch, plan)
+2. **`/technical/pre-pr`** - Validar código antes de criar PR (lint, tests, docs)
+3. **`/technical/pr-update`** - Atualizar PR existente com novos commits e descrição
+4. **`/technical/code-review`** - Realizar code review com checklist de qualidade
+5. **`/technical/fast-commit`** - Commit rápido seguindo conventional commits
+6. **`/technical/build-index`** - Construir índice de documentação técnica
+7. **`/technical/build-tech-docs`** - Gerar documentação técnica completa
+8. **`/technical/build-business-docs`** - Gerar documentação de negócio
+9. **`/technical/validate-docs`** - Validar consistência da documentação
+10. **`/technical/docs-health`** - Analisar saúde da documentação (cobertura, atualização)
+11. **`/technical/sync-sessions`** - Sincronizar sessões de desenvolvimento
+12. **`/technical/unit`** - Executar/criar testes unitários
+13. **`/technical/integration`** - Executar/criar testes de integração
+
+---
+
+### ⚡ ADVANCED COMMANDS (14 comandos - 5% dos casos)
+**⏱️ Tempo de onboarding: ~60 minutos**
+
+Comandos especializados para casos específicos:
+
+**Gestão de Releases:**
+1. **`/technical/bump`** - Incrementar versão do projeto (semver)
+2. **`/technical/hotfix`** - Criar branch de hotfix para correção urgente
+3. **`/technical/validate-phase-sync`** - Validar sincronização entre fases de desenvolvimento
+
+**Documentação Avançada:**
+4. **`/technical/refine-vision`** - Refinar visão técnica do projeto
+5. **`/technical/consolidate-documents`** - Consolidar múltiplos documentos
+6. **`/technical/reverse-consolidate`** - Reverter consolidação de documentos
+
+**Testes Avançados:**
+7. **`/technical/e2e`** - Executar/criar testes end-to-end
+
+**Git Workflows (Feature):**
+8. **`/technical/feature-start`** - Iniciar branch de feature (gitflow)
+9. **`/technical/feature-finish`** - Finalizar branch de feature
+10. **`/technical/feature-publish`** - Publicar feature em remote
+
+**Git Workflows (Hotfix):**
+11. **`/technical/hotfix-start`** - Iniciar hotfix
+12. **`/technical/hotfix-finish`** - Finalizar hotfix
+
+**Git Workflows (Release):**
+13. **`/technical/release-start`** - Iniciar release
+14. **`/technical/release-finish`** - Finalizar release
+
+---
+
+## 🚀 Próximos Passos
+
+### Se você é novo no Technical Context:
+
+1. **Comece pelos Starter Commands** (os 8 primeiros)
+   - Foque em `/technical/work` e `/technical/plan`
+   - Pratique criando uma sessão de desenvolvimento
+   - Tempo estimado: 20-30 minutos
+
+2. **Explore Intermediate Commands**
+   - Experimente `/technical/start` para workflow completo
+   - Use `/technical/pre-pr` para validar qualidade
+   - Tempo estimado: +40 minutos
+
+3. **Descubra Agentes Especializados**
+   ```bash
+   @react-developer            # Desenvolvimento React/Frontend
+   @nodejs-specialist          # Backend Node.js
+   @postgres-specialist        # Database PostgreSQL
+   @zen-engine-specialist      # ZenStack ORM
+   @test-engineer              # Testes automatizados
+   @code-reviewer              # Review de código
+   ```
+
+### Workflow Típico de Desenvolvimento:
+
+```bash
+# 1. Iniciar nova feature
+/technical/start "user-dashboard"
+
+# 2. Durante desenvolvimento
+/technical/work "task-id"
+
+# 3. Antes de finalizar
+/technical/pre-pr
+
+# 4. Criar Pull Request
+/technical/pr
+
+# 5. Após merge
+/technical/sync
+```
+
+### Pronto para Business Context?
+
+Para especificações e planejamento de produto:
+```bash
+/business/help               # Comandos de produto/negócio
+/business/spec "feature"     # Criar especificação
+```
+
+---
+
+## 📚 Documentação Relacionada
+
+- **Sistema de Níveis**: `docs/onion/levels-system.md`
+- **READMEs**: `.onion/contexts/technical/README.md`
+- **Agentes**: `.onion/contexts/technical/agents/`
+- **Configuração**: `.onion/contexts/technical/.context-config.yml`
+- **Sessions**: `.cursor/sessions/` (rastreamento de desenvolvimento)
+
+---
+
+## 💡 Dicas Úteis
+
+### Filosofia 80/15/5
+- **80%** do seu tempo: Use apenas comandos **starter**
+- **15%** do seu tempo: Use comandos **intermediate**
+- **5%** do seu tempo: Use comandos **advanced**
+
+### Descoberta Progressiva
+Cada comando inclui seção "🚀 Próximos Passos" sugerindo o que fazer em seguida.
+
+### Sessions & Context Management
+O Onion v4 rastreia suas sessões de desenvolvimento:
+- `.cursor/sessions/[feature]/` contém context.md, plan.md, architecture.md
+- Comandos `/work` e `/start` gerenciam automaticamente
+- Sessions são **CAMADA 5** do ciclo completo Onion
+
+### Flags e Opções
+```bash
+--level=starter       # Filtrar por nível
+--level=all          # Ver todos os níveis
+```
+
+---
+
+## 🎓 Onboarding Recomendado
+
+### Dia 1 (30 minutos)
+1. Execute `/technical/warm-up`
+2. Pratique `/technical/plan "test-feature"`
+3. Teste `/technical/work` em uma task real
+
+### Semana 1 (3 horas)
+- Domine os 8 starter commands
+- Experimente 4-5 intermediate commands
+- Crie sua primeira feature completa (start → work → pr)
+
+### Mês 1 (8 horas)
+- Explore todos os intermediate commands
+- Teste gitflow (feature/hotfix/release)
+- Integre no workflow diário da equipe
+
+---
+
+## 🔄 Integração com Business Context
+
+O Technical Context trabalha em conjunto com Business:
+
+```bash
+# 1. Business: Criar especificação
+/business/spec "dashboard-analytics"
+
+# 2. Business: Estimar complexidade
+/business/estimate "dashboard-analytics"
+
+# 3. Business: Criar task
+/business/task "dashboard-analytics"
+
+# 4. Technical: Iniciar desenvolvimento
+/technical/start "dashboard-analytics"
+
+# 5. Technical: Desenvolver
+/technical/work "task-id"
+
+# 6. Technical: Finalizar
+/technical/pr
+```
+
+---
+
+**📊 Estatísticas do Technical Context:**
+- **Total**: 36 comandos (mais que business!)
+- **Starter**: 8 (22%)
+- **Intermediate**: 13 (36%)
+- **Advanced**: 14 (39%)
+- **Agentes**: 23 especializados
+- **Tempo total onboarding**: ~120 minutos (todos os níveis)
+
+---
+
+## 🏗️ Arquitetura de Sessions
+
+```
+.cursor/sessions/
+├── feature-x/
+│   ├── context.md       # Objetivo, requisitos, decisões
+│   ├── architecture.md  # Design técnico, trade-offs
+│   ├── plan.md          # Fases de implementação
+│   └── notes.md         # Notas de desenvolvimento
+└── feature-y/
+    └── ...
+```
+
+Comandos que gerenciam sessions automaticamente:
+- `/technical/start` - Cria nova session
+- `/technical/work` - Lê e atualiza session ativa
+- `/technical/pr` - Usa session para gerar descrição
+
+---
+
+## 🆘 Precisa de Ajuda?
+
+- **Help de outro contexto**: `/business/help`, `/customer-success/help`
+- **Help global**: `/help`
+- **Agente de ajuda**: `@onion` (orquestrador principal)
+- **Documentação**: `docs/onion/`
+- **Agentes especializados**: 
+  - `@cursor-specialist` - Problemas com IDE
+  - `@gitflow-specialist` - Workflows git
+  - `@nx-monorepo-specialist` - Monorepo NX
+
+---
+
+**Sistema Onion v4.0** - Multi-Context Development Orchestrator 🧅
+

package/templates/.cursor/commands/engineer/hotfix.md

@@ -0,0 +1,186 @@
+---
+name: hotfix
+description: |
+  Emergency workflow completo: task ClickUp + branch hotfix + desenvolvimento.
+  Use para correções urgentes em produção.
+model: sonnet
+
+parameters:
+  - name: description
+    description: Descrição do hotfix
+    required: true
+  - name: related_tasks
+    description: IDs de tasks relacionadas (comma-separated)
+    required: false
+  - name: tags
+    description: Tags adicionais (comma-separated)
+    required: false
+
+category: engineer
+tags:
+  - hotfix
+  - emergency
+  - gitflow
+
+version: "4.0.0"
+updated: "2025-12-20"
+
+related_commands:
+  - /git/hotfix/start
+  - /git/hotfix/finish
+  - /product/task
+
+related_agents:
+  - gitflow-specialist
+  - clickup-specialist
+level: advanced
+context: technical
+---
+
+# 🔥 Engineer Hotfix
+
+Emergency workflow completo: Task + Branch + Desenvolvimento.
+
+## 🎯 Objetivo
+
+Executar workflow de hotfix end-to-end em um único comando.
+
+## ⚡ Fluxo de Execução
+
+### Passo 1: Validar Input
+
+```bash
+# Verificar descrição
+if [ -z "{{description}}" ]; then
+  echo "❌ Descrição obrigatória"
+  exit 1
+fi
+
+# Verificar branch atual
+CURRENT=$(git branch --show-current)
+if [[ ! "$CURRENT" =~ ^(main|master|develop)$ ]]; then
+  echo "⚠️ Recomendado: iniciar de main/master"
+fi
+```
+
+### Passo 2: Criar Task Emergencial
+
+Via ClickUp MCP:
+
+```yaml
+name: "🔥 HOTFIX: {{description}}"
+list_id: [lista de hotfixes]
+priority: urgent
+tags:
+  - hotfix
+  - urgent
+  - {{tags}}
+status: "In Progress"
+markdown_description: |
+  ## 🚨 Emergency Hotfix
+  
+  **Descrição**: {{description}}
+  
+  ## 📋 Checklist
+  - [ ] Diagnóstico
+  - [ ] Implementação
+  - [ ] Testes
+  - [ ] Deploy
+```
+
+### Passo 3: Criar Branch Hotfix
+
+```bash
+# Garantir main atualizada
+git checkout main
+git pull origin main
+
+# Criar hotfix branch
+VERSION=$(cat package.json | grep version | head -1 | awk -F'"' '{print $4}')
+PATCH=$(echo $VERSION | awk -F. '{print $1"."$2"."$3+1}')
+BRANCH="hotfix/$PATCH-$(echo '{{description}}' | tr ' ' '-' | tr '[:upper:]' '[:lower:]' | head -c 30)"
+
+git checkout -b $BRANCH
+```
+
+### Passo 4: Setup Session
+
+```bash
+# Criar sessão de desenvolvimento
+mkdir -p .cursor/sessions/hotfix-$(date +%Y%m%d)/
+
+# Criar context.md
+cat > .cursor/sessions/hotfix-$(date +%Y%m%d)/context.md << EOF
+# Hotfix Context
+
+## Task
+- ID: [task_id criado]
+- URL: [url do clickup]
+
+## Branch
+- Nome: $BRANCH
+- Base: main
+
+## Descrição
+{{description}}
+EOF
+```
+
+### Passo 5: Iniciar Desenvolvimento
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🔥 HOTFIX INICIADO
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 Task: [URL do ClickUp]
+🌿 Branch: hotfix/X.X.X-description
+
+⚡ Próximos Passos:
+1. Implementar correção
+2. Testar localmente
+3. /engineer/pre-pr
+4. /git/hotfix/finish
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## 📤 Output Esperado
+
+### Sucesso
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ HOTFIX SETUP COMPLETO
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 ClickUp:
+∟ Task: 🔥 HOTFIX: {{description}}
+∟ ID: 86adfxxxx
+∟ Status: In Progress
+∟ Priority: Urgent
+
+🌿 Git:
+∟ Branch: hotfix/1.2.3-fix-description
+∟ Base: main
+∟ Remote: origin
+
+📁 Session:
+∟ Path: .cursor/sessions/hotfix-20251124/
+
+🚀 Comandos:
+∟ Desenvolver: /engineer/work
+∟ Pre-PR: /engineer/pre-pr
+∟ Finalizar: /git/hotfix/finish
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## 🔗 Referências
+
+- Padrões: `common/prompts/git-workflow-patterns.md`
+- Agente: @gitflow-specialist
+
+## ⚠️ Notas
+
+- Sempre parte de `main` ou `master`
+- Task criada com prioridade máxima
+- Merge automático para main E develop no finish

package/templates/.cursor/commands/engineer/plan.md

@@ -0,0 +1,111 @@
+---
+name: plan
+description: Planejamento de feature. Analisa e cria plano estruturado.
+model: sonnet
+category: engineer
+tags: [planning, architecture, design]
+version: "4.0.0"
+updated: "2025-12-20"
+level: starter
+context: technical
+---
+
+# Engineer Reason
+
+Este é o comando para iniciar o planejamento de uma funcionalidade.
+
+<arguments>
+#$ARGUMENTS
+</arguments>
+
+## Análise
+
+Leia os arquivos context.md e architecture.md na pasta .cursor/sessions/<feature-slug> se ainda não tiver feito.
+
+Sua tarefa agora é criar um plano de implementação detalhado (plan.md) para esta funcionalidade. O objetivo desta documentação é criar uma abordagem de implementação faseada que nos permita construir a funcionalidade incrementalmente, testando cada fase conforme avançamos. E também deve tornar possível retomar o trabalho caso nossa sessão seja interrompida.
+
+O plan.md deve dividir a implementação em fases, cada fase com um pedaço do trabalho que pode ser realizado por um humano em 2 horas.
+
+O template para o plan.md é:
+
+<plan>
+# [NOME DA FUNCIONALIDADE]
+
+Se você está trabalhando nesta funcionalidade, certifique-se de atualizar este arquivo plan.md conforme progride.
+
+## FASE 1 [Completada ✅]
+
+Detalhes desta parte da funcionalidade
+
+### Uma tarefa que foi feita [Completada ✅]
+
+Detalhes sobre a tarefa
+
+### Uma tarefa que foi feita [Completada ✅]
+
+Detalhes sobre a tarefa
+
+### Comentários:
+- Algo que aconteceu e nos forçou a mudar de direção
+- Algo que aprendemos durante o desenvolvimento
+- Algo que discutimos e concordamos
+
+## FASE 2 [Em Progresso ⏰]
+
+### Uma tarefa que precisa ser feita [Em Progresso ⏰]
+
+Detalhes sobre a tarefa
+
+### Uma tarefa que precisa ser feita [Não Iniciada ⏳]
+
+Detalhes sobre a tarefa
+
+## FASE 3 [Não Iniciada ⏳]
+
+### Uma tarefa que precisa ser feita [Não Iniciada ⏳]
+
+Detalhes sobre a tarefa
+
+### Uma tarefa que precisa ser feita [Não Iniciada ⏳]
+
+Detalhes sobre a tarefa
+
+</plan>
+
+
+Dicas:
+   - Use repoprompt:search (se disponível) para encontrar arquivos específicos baseados nas respostas de descoberta
+   - Use repoprompt:set_selection e repoprompt:read_selected_files (se disponível) para ler código relevante em batch
+   - Analise detalhes específicos de implementação
+   - Use WebSearch e ou context7 para melhores práticas ou documentação de bibliotecas (se necessário)
+
+No caso desta pesquisa levantar uma nova decisão arquitetural ou contradição com as decisões anteriores, você iniciará uma discussão sobre isso com o humano, concordará com as mudanças e atualizará o documento architecture.md para aquela funcionalidade se necessário.
+
+Este documento também deve anotar quais tarefas precisam ser feitas sequencialmente ou em paralelo.
+
+Uma vez que o plan.md esteja finalizado, informe ao humano que você está pronto para prosseguir para o próximo passo.
+
+
+
+---
+
+## 🚀 Próximos Passos
+
+Agora que você tem um plano, execute:
+
+1. **Iniciar desenvolvimento**:
+   ```bash
+   /technical/work "feature-name"
+   ```
+   Começa implementação seguindo o plano criado.
+
+2. **Se precisar de estrutura completa**:
+   ```bash
+   /technical/start "feature-name"
+   ```
+   Cria sessão, branch git e documentação de arquitetura além do plano.
+
+3. **Documentar decisões técnicas**:
+   Edite `.cursor/sessions/[feature]/architecture.md` conforme implementa para registrar trade-offs.
+
+💡 **Dica**: Planeje antes de implementar! Um bom plano reduz retrabalho e facilita code review.