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

package/templates/.onion/contexts/technical/commands/starter/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.

package/templates/.onion/contexts/technical/commands/starter/pr.md

@@ -0,0 +1,136 @@
+---
+name: pr
+description: Criar Pull Request com integração GitFlow e sync automático.
+model: sonnet
+category: engineer
+tags: [pr, gitflow, workflow]
+version: "4.0.0"
+updated: "2025-12-20"
+level: starter
+context: technical
+---
+
+# 🚀 Engineer PR - GitFlow Integrated
+
+Você é um assistente especializado em **criação de Pull Requests** com integração automática ao novo sistema `/git/sync` otimizado do Sistema Onion.
+
+## 🤖 **Nova Integração GitFlow**
+Este comando agora inclui **sync automático pós-merge** usando:
+- **GitFlow Analysis** via @gitflow-specialist
+- **Performance otimizada** (cache + operações paralelas) 
+- **Cleanup inteligente** baseado na estratégia de branch
+- **Session archiving** automático
+- **ClickUp auto-update** para status "Done"
+
+---
+
+Agora é solicitado que você faça um PR. Siga estes passos cuidadosamente para completar a tarefa:
+
+1. Primeiro, garanta que todos os testes estão funcionando para a branch atual. Execute a suíte de testes apropriada para seu projeto e confirme que todos os testes passam. Se algum teste falhar, corrija os problemas antes de prosseguir.
+
+2. **CRÍTICO - Criar Feature Branch PRIMEIRO:**
+   a. Crie uma feature branch a partir da branch base (develop/main):
+      ```bash
+      git checkout -b feature/[descricao-sucinta]
+      git push -u origin feature/[descricao-sucinta]
+      ```
+   b. Faça commit das mudanças que você fez. Use uma mensagem de commit clara e concisa que resuma as alterações.
+   c. Push dos commits para a feature branch.
+
+3. Mova a task do ClickUp associada com esta tarefa para o status "in progress" e adicione a tag "under-review".
+
+4. Adicione um comentário na task do ClickUp documentando o PR:
+
+**Chamar abstração MCP para comentário automatizado:**
+
+```typescript
+// Ao criar PR, chamar:
+await commentPRCreated(taskId, {
+  prUrl: "[PR_URL]",
+  branch: "[branch-name]",
+  changesDescription: "[descrição das mudanças]",
+  testsStatus: "passing|review|pending"
+});
+```
+
+**Referências:**
+- **Padrão 3 (PR Criada)**: `.cursor/docs/strategies/clickup-comment-patterns.md`
+- **Abstração MCP**: `commentPRCreated()` em `.cursor/utils/clickup-mcp-wrappers.md` (linhas 632-661) 
+
+5. Abra um Pull Request (PR) com os detalhes da implementação:
+
+   Importante: Não mencione nenhum código relacionado a AI ou assistentes de IA no PR.
+
+6. Após abrir o PR, aguarde 3 minutos e então verifique comentários da ferramenta automatizada de code review. Se nenhum comentário aparecer, aguarde mais 3 minutos e verifique novamente.
+
+7. Uma vez que você receba comentários da ferramenta automatizada de code review, analise cada comentário cuidadosamente. Determine quais comentários requerem correções e quais podem ser ignorados com segurança ou explicados. Apresente suas sugestões ao usuário e peça permissão para fazer as mudanças.
+
+8. Para os comentários que requerem correções:
+   a. Faça as mudanças necessárias no código
+   b. Faça commit dessas mudanças com uma mensagem de commit clara
+   c. Faça push do(s) novo(s) commit(s) para a mesma branch
+
+9. Após abordar os comentários e fazer push das atualizações, aguarde a confirmação de merge do PR.
+
+10. **NOVO - Sync Automático Pós-Merge**: Uma vez que o PR for merged, execute automaticamente:
+    ```bash
+    /git/sync
+    ```
+    Este comando agora inclui:
+    - 🤖 **GitFlow Analysis** com @gitflow-specialist 
+    - ⚡ **Performance otimizada** (cache + operações paralelas)
+    - 🧹 **Cleanup inteligente** baseado na estratégia GitFlow
+    - 📁 **Session management** automático com archiving
+    - 🔗 **ClickUp auto-update** para status "Done"
+    
+    O sync será executado automaticamente com a estratégia otimizada baseada no tipo de branch e workflow detectado.
+
+REGRA DE OURO: Sempre faça commit APENAS dos arquivos que você alterou. SE houver mais arquivos, pergunte ao usuário se eels devem ser incluidos. Não use `git add .` para prevenir commits de arquivos que não deveriam ser commitados, a não ser que o usuario confirme.
+
+Seu output final deve ser uma mensagem para o usuário, formatada da seguinte forma:
+
+<task_completion_message>
+Tarefa completada:
+- Testes estão passando
+- Mudanças commitadas
+- Task do ClickUp [INSERT TASK ID] movida para "in progress" com tag "under-review"
+- PR aberto: [INSERT PR TITLE]
+- Comentários do code review automatizado abordados e correções pushed
+- 🤖 GitFlow integration: Auto-sync configurado para pós-merge
+
+O PR está agora pronto para sua revisão final e merge manual.
+
+🚀 APÓS O MERGE: O comando `/git/sync` será executado automaticamente com:
+   ∟ GitFlow analysis via @gitflow-specialist
+   ∟ Performance otimizada (cache + operações paralelas)
+   ∟ Cleanup inteligente baseado na estratégia GitFlow
+   ∟ Session archiving automático
+   ∟ ClickUp auto-update para status "Done"
+
+[INSERT PR LINK]
+</task_completion_message>
+
+
+
+---
+
+## 🚀 Próximos Passos
+
+Após criar o PR:
+
+1. **Sincronizar após merge**:
+   ```bash
+   /technical/sync
+   ```
+   Atualiza sua branch local com as mudanças mergeadas.
+
+2. **Iniciar próxima feature**:
+   ```bash
+   /technical/start "proxima-feature"
+   ```
+   Começa novo ciclo de desenvolvimento.
+
+3. **Documentar em `/technical/docs`**:
+   Se a feature mudou arquitetura ou adicionou APIs, atualize docs técnicos.
+
+💡 **Dica**: O PR inclui automaticamente informações da sessão (context.md, architecture.md, plan.md) na descrição.

package/templates/.onion/contexts/technical/commands/starter/sync.md

@@ -0,0 +1,228 @@
+---
+name: sync
+description: |
+  Sincronização automática de branches com GitFlow e proteção de branches críticas.
+  Use após merge de PRs para manter branches atualizadas.
+model: sonnet
+
+parameters:
+  - name: branch
+    description: Branch alvo para sincronização (default: develop)
+    required: false
+    default: develop
+
+category: git
+tags:
+  - sync
+  - gitflow
+  - branch-protection
+
+version: "4.0.0"
+updated: "2025-12-20"
+
+related_commands:
+  - /engineer/pr
+  - /git/feature/finish
+
+related_agents:
+  - gitflow-specialist
+level: starter
+context: technical
+---
+
+# 🔄 Git Sync - Sincronização com GitFlow
+
+Sincronização pós-merge de branches com proteção automática.
+
+## 🎯 Objetivo
+
+Automatizar sincronização após merge de PRs seguindo GitFlow.
+
+## 🛡️ Branches Protegidas
+
+| Branch | Push Direto | Fast-Forward |
+|--------|-------------|--------------|
+| `main` | ❌ Bloqueado | ✅ Permitido |
+| `master` | ❌ Bloqueado | ✅ Permitido |
+| `develop` | ❌ Bloqueado | ✅ Permitido |
+
+## ⚡ Fluxo de Execução
+
+### Passo 1: Detectar Contexto
+
+```bash
+# Branch atual
+CURRENT=$(git branch --show-current)
+
+# Target branch
+TARGET="${{branch:-develop}}"
+
+# Verificar se target é protegida
+if [[ "$TARGET" =~ ^(main|master|develop)$ ]]; then
+  PROTECTED=true
+fi
+```
+
+### Passo 2: Validar Estado
+
+```bash
+# Verificar alterações não commitadas
+if [[ -n $(git status --porcelain) ]]; then
+  echo "⚠️ Alterações não commitadas"
+  echo "Commit ou stash antes de continuar"
+  exit 1
+fi
+
+# Fetch remoto
+git fetch origin --prune
+```
+
+### Passo 3: Análise GitFlow
+
+Consultar @gitflow-specialist para estratégia:
+
+| Branch Atual | Target | Estratégia |
+|--------------|--------|------------|
+| `feature/*` | `develop` | `feature-cleanup` |
+| `release/*` | `main` | `release-sync` |
+| `hotfix/*` | `main` | `hotfix-sync` |
+| `develop` | `main` | `protected-sync` |
+
+Referência: `common/prompts/git-workflow-patterns.md`
+
+### Passo 4: Executar Sync
+
+#### Para Branches Normais
+
+```bash
+git checkout $TARGET
+git pull origin $TARGET
+git checkout $CURRENT
+git merge $TARGET --no-edit
+```
+
+#### Para Branches Protegidas
+
+```bash
+# Apenas fast-forward permitido
+git checkout $TARGET
+git merge origin/$TARGET --ff-only
+
+# Se falhar, instruir PR workflow
+if [[ $? -ne 0 ]]; then
+  echo "❌ Fast-forward não possível"
+  echo "Use PR workflow: /engineer/pr"
+fi
+```
+
+### Passo 5: Cleanup (se feature finalizada)
+
+```bash
+# Se branch feature foi merged
+if git branch -r | grep -q "origin/$CURRENT"; then
+  echo "Branch $CURRENT ainda existe no remote"
+else
+  echo "✅ Branch $CURRENT deletada no remote"
+  # Perguntar se quer deletar local
+fi
+```
+
+### Passo 6: Atualizar ClickUp
+
+SE sessão ativa com task_id:
+- Comentário de sync realizado
+- Atualizar status se necessário
+
+## 📤 Output Esperado
+
+### Sync Sucesso
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ SYNC CONCLUÍDO
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📊 Resumo:
+∟ Branch atual: feature/user-auth
+∟ Sincronizado com: develop
+∟ Commits atualizados: 5
+∟ Conflitos: 0
+
+🚀 Próximo: /engineer/work
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Branch Protegida - Bloqueio
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🛡️ BRANCH PROTEGIDA
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+❌ Push direto em 'develop' bloqueado
+
+📋 Workflow Correto:
+1. git checkout -b feature/my-changes
+2. [fazer alterações]
+3. /engineer/pr
+4. [merge via GitHub/GitLab]
+5. /git/sync develop
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Conflito Detectado
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚠️ CONFLITOS DETECTADOS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📁 Arquivos em conflito:
+∟ src/components/Button.tsx
+∟ src/utils/helpers.ts
+
+💡 Resolução:
+1. Editar arquivos manualmente
+2. git add [arquivos]
+3. git commit
+4. /git/sync (novamente)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## 🔗 Referências
+
+- Padrões: `common/prompts/git-workflow-patterns.md`
+- Agente: @gitflow-specialist
+
+## ⚠️ Notas
+
+- Sempre fazer `git fetch` antes
+- Branches protegidas só aceitam fast-forward
+- Em caso de conflito, resolver manualmente
+
+
+---
+
+## 🚀 Próximos Passos
+
+Após sincronizar:
+
+1. **Iniciar novo trabalho**:
+   ```bash
+   /technical/start "feature-name"
+   ```
+   Começa nova feature com código atualizado.
+
+2. **Ou retomar trabalho pausado**:
+   ```bash
+   /technical/work "task-id"
+   ```
+   Continua desenvolvimento existente.
+
+3. **Se houve conflitos complexos**:
+   ```bash
+   /technical/pre-pr
+   ```
+   Valida que tudo ainda funciona após resolução.
+
+💡 **Dica**: Sincronize frequentemente (manhã, antes de PRs) para minimizar conflitos.

package/templates/.onion/contexts/technical/commands/starter/warm-up.md

@@ -0,0 +1,173 @@
+---
+name: warm-up
+description: |
+  Preparação de contexto técnico e de engenharia.
+  Foca em arquitetura, padrões de código, estrutura do projeto, comandos de desenvolvimento e frameworks técnicos.
+model: sonnet
+category: engineer
+tags: [warmup, context, engineering, technical]
+version: "4.0.0"
+updated: "2025-12-20"
+level: starter
+context: technical
+---
+
+# 🔥 Warm-up de Engenharia
+
+Preparação específica para trabalho técnico e de desenvolvimento.
+
+## 🎯 Objetivo
+
+Estabelecer contexto focado em:
+- Arquitetura técnica do projeto
+- Padrões de código e convenções
+- Estrutura de código e organização
+- Comandos e workflows de desenvolvimento
+- Frameworks técnicos e ferramentas
+- Sistema de testes e validação
+
+## 📋 Checklist de Preparação
+
+### 1. Contexto Geral (Base)
+- ✅ Revisar `README.md` para visão geral do Sistema Onion
+- ✅ Entender estrutura de documentação em `docs/`
+
+### 2. Meta Especificações Técnicas
+- ✅ Revisar `docs/meta-specs/index.md`
+- ✅ Focar em:
+  - `architecture.md` (quando disponível) - Padrões arquiteturais
+  - `code-standards.md` (quando disponível) - Padrões de código
+  - `agents.md` (quando disponível) - Padrões para agentes
+  - `commands.md` (quando disponível) - Padrões para comandos
+- ✅ Entender hierarquia de especificações para decisões técnicas
+
+### 3. Documentação Técnica
+- ✅ Revisar `docs/onion/commands-guide.md` - Seção "Comandos de Engenharia"
+- ✅ Revisar `docs/onion/engineering-flows.md` - Fluxos de desenvolvimento
+- ✅ Revisar `docs/onion/testing-validation-system.md` - Sistema de testes
+- ✅ Mapear comandos de engenharia:
+  - `/engineer/start` - Iniciar desenvolvimento (valida story points)
+  - `/engineer/work` - Trabalhar em feature
+  - `/engineer/plan` - Planejar implementação
+  - `/engineer/pre-pr` - Preparar Pull Request
+  - `/engineer/pr` - Criar Pull Request
+  - `/engineer/docs` - Documentar código
+  - `/engineer/warm-up` - Este comando
+
+### 4. Estrutura do Projeto
+- ✅ Mapear estrutura de diretórios do código
+- ✅ Entender organização de módulos/pacotes
+- ✅ Identificar tecnologias principais (linguagens, frameworks)
+- ✅ Localizar arquivos de configuração importantes
+
+### 5. Padrões de Código
+- ✅ Revisar convenções de nomenclatura
+- ✅ Entender estilo de código esperado
+- ✅ Conhecer ferramentas de linting/formatting
+- ✅ Verificar arquivos de configuração (.eslintrc, .prettierrc, etc)
+
+### 6. Knowledge Bases Técnicas
+- ✅ Revisar `docs/knowbase/concepts/spec-as-code-strategy.md`
+- ✅ Revisar `docs/knowbase/concepts/ai-agent-design-patterns.md`
+- ✅ Revisar `docs/knowbase/concepts/abstraction-patterns-catalog.md`
+- ✅ Revisar `docs/knowbase/frameworks/framework_testes.md`
+- ✅ Revisar `docs/knowbase/concepts/context-window-optimization.md`
+
+### 7. Agentes de Desenvolvimento
+- ✅ Conhecer agentes especializados:
+  - `@react-developer` - Desenvolvimento React
+  - `@python-developer` - Desenvolvimento Python
+  - `@nodejs-specialist` - Backend Node.js
+  - `@nx-monorepo-specialist` - Monorepos NX
+  - `@c4-architecture-specialist` - Arquitetura C4
+  - `@test-engineer` - Testes e QA
+  - `@code-reviewer` - Code review
+
+### 8. Sistema de Testes
+- ✅ Revisar `docs/onion/testing-validation-system.md`
+- ✅ Entender comandos de teste:
+  - `/test/unit` - Testes unitários (White-box)
+  - `/test/integration` - Testes de integração (Grey-box)
+  - `/test/e2e` - Testes end-to-end (Black-box)
+- ✅ Conhecer frameworks de teste utilizados
+
+### 9. Git e Versionamento
+- ✅ Revisar comandos Git disponíveis:
+  - `/git/feature/start` - Criar branch de feature
+  - `/git/sync` - Sincronizar após merge
+- ✅ Entender workflow Git do projeto
+- ✅ Conhecer convenções de branching
+
+### 10. Validação de Story Points
+- ✅ Entender que `/engineer/start` valida estimativas
+- ✅ Conhecer processo de validação antes de iniciar desenvolvimento
+- ✅ Saber como lidar com tasks sem estimativas
+
+## 🔍 Contexto Específico de Engenharia
+
+### Documentação Essencial
+- `docs/onion/engineering-flows.md` - Fluxos de desenvolvimento
+- `docs/onion/testing-validation-system.md` - Sistema de testes
+- `docs/onion/commands-guide.md` - Comandos de engenharia
+- `docs/knowbase/frameworks/framework_testes.md` - Framework de testes
+
+### Workflows de Desenvolvimento
+1. **Iniciar**: `/engineer/start` → Valida story points, cria branch, sessão
+2. **Trabalhar**: `/engineer/work` → Loop de desenvolvimento
+3. **Planejar**: `/engineer/plan` → Planejar implementação detalhada
+4. **Pre-PR**: `/engineer/pre-pr` → Preparar Pull Request
+5. **PR**: `/engineer/pr` → Criar Pull Request (testes, build, PR)
+6. **Sync**: `/git/sync` → Sincronizar após merge
+
+### Estrutura de Sessões
+- ✅ Entender `.cursor/sessions/<feature>/` para contexto de trabalho
+- ✅ Conhecer formato de arquivos de sessão
+
+## 💡 Quando Usar Este Warm-up
+
+- ✅ Início de desenvolvimento de feature
+- ✅ Retorno a trabalho técnico após período ausente
+- ✅ Mudança de contexto técnico (nova tecnologia/framework)
+- ✅ Necessidade de entender arquitetura do projeto
+- ✅ Preparação para code review ou refatoração
+
+## 🔗 Integração com Produto
+
+- Tasks vêm de `/product/task` com story points
+- Especificações vêm de `/product/spec`
+- Validação de estimativas antes de iniciar
+- Sincronização com Task Manager durante desenvolvimento
+
+## ⚠️ Notas
+
+- Foco em contexto técnico e de código
+- Mantenha conhecimento de padrões e convenções no contexto
+- Use agentes especializados para tecnologias específicas
+- Sempre valide story points antes de iniciar (`/engineer/start`)
+- Mantenha código sincronizado com Task Manager durante desenvolvimento
+
+---
+
+## 🚀 Próximos Passos
+
+Agora que você preparou o contexto técnico:
+
+1. **Planejar nova feature**:
+   ```bash
+   /technical/plan "feature-name"
+   ```
+   Cria plano de desenvolvimento estruturado.
+
+2. **Ou retomar trabalho existente**:
+   ```bash
+   /technical/work "task-id"
+   ```
+   Continua desenvolvimento de feature em progresso.
+
+3. **Resolver conflitos se necessário**:
+   ```bash
+   /technical/sync
+   ```
+   Sincroniza com remote antes de começar novo trabalho.
+
+💡 **Dica**: Warm-up carrega contexto sobre stack, arquitetura e padrões do projeto - essencial após pausas longas.