context-first-cli 2.0.3 → 2.0.5

package/dist/templates/commands/pt-BR/products/refine.md

@@ -1,209 +1,211 @@
 # Refinamento de Requisitos
 
-Este comando refina uma issue coletada, transformando-a em requisitos claros e validados.
+Você é um especialista em produto encarregado de ajudar a refinar requisitos para o projeto.
 
 ## ⚠️ IMPORTANTE: Este Comando NÃO Implementa Código
 
-**Este comando é APENAS para refinamento de requisitos:**
-- ✅ Refinar e validar requisitos
-- ✅ Atualizar issue no task manager via MCP
-- ✅ **LER** arquivos dos repositórios principais (read-only)
+**Este comando é APENAS para planejamento e documentação:**
+- ✅ Validar requisitos contra metaspecs
+- ✅ Criar especificação refinada
+- ✅ Salvar documentação em `.sessions/`
+- ✅ Atualizar issue no task manager
 - ❌ **NÃO implementar código**
 - ❌ **NÃO fazer edits em arquivos de código**
-- ❌ **NÃO fazer checkout de branches nos repositórios principais**
-- ❌ **NÃO fazer commits**
+- ❌ **NÃO executar testes ou deploy**
 
-**Próximo passo**: `/spec [ISSUE-ID]` para criar a especificação completa (PRD).
+**Próximo passo**: `/spec [ISSUE-ID]` para criar PRD completo baseado nos requisitos refinados.
 
 ---
 
-## 📋 Pré-requisitos
+## Objetivo
 
-- Issue já coletada via `/collect`
-- Contexto do projeto será carregado automaticamente (veja seção "Carregar MetaSpecs" abaixo)
+Transformar um requisito inicial em especificação refinada e validada, pronta para se tornar PRD completo.
 
-## 🎯 Objetivo
+## Processo
 
-Refinar a issue coletada, esclarecendo:
-- Escopo exato (o que entra e o que não entra)
-- Critérios de aceitação claros
-- Impacto em cada repositório
-- Dependências técnicas
-- Riscos e restrições
+### 1. Fase de Esclarecimento
 
-## 📝 Processo de Refinamento
+Leia o requisito inicial e faça perguntas para alcançar clareza total sobre:
+- **Objetivo**: Por que construir isso?
+- **Valor de Negócio**: Qual métrica/persona impacta?
+- **Escopo**: O que inclui e o que NÃO inclui?
+- **Interações**: Quais features/componentes existentes são afetados?
 
-### 1. Carregar Issue
+Continue fazendo perguntas até ter entendimento completo.
 
-**PRIORIDADE 1: Usar MCP (Model Context Protocol)**
+### 2. Validação Contra Metaspecs
 
-- Leia `ai.properties.md` do orchestrator para identificar o `task_management_system`
-- Use o MCP apropriado para buscar a issue:
-  - `task_management_system=jira`: Use MCP do Jira
-  - `task_management_system=linear`: Use MCP do Linear
-  - `task_management_system=github`: Use MCP do GitHub
-- Carregue todos os dados da issue (título, descrição, labels, etc.)
+**IMPORTANTE**: Primeiro leia `ai.properties.md` para obter o `base_path`. Os índices JÁ devem estar em contexto (você rodou `/warm-up`). Consulte os índices e leia APENAS os documentos relevantes para validar o requisito.
 
-**FALLBACK: Se MCP não estiver disponível ou falhar**
-
-- Leia `./.sessions/<ISSUE-ID>/collect.md`
-- Se o arquivo não existir, informe o erro ao usuário
-
-### 2. Carregar MetaSpecs
-
-**Localizar MetaSpecs automaticamente**:
-1. Leia `context-manifest.json` do orchestrator
-2. Encontre o repositório com `"role": "metaspecs"`
-3. Leia `ai.properties.md` para obter o `base_path`
-4. O metaspecs está em: `{base_path}/{metaspecs-repo-id}/`
-5. Leia os arquivos `index.md` relevantes para entender:
-   - Arquitetura do sistema
-   - Padrões de design
-   - Restrições técnicas
-   - Convenções do projeto
-
-### 3. Análise de Escopo
-
-Defina claramente:
-
-**O que ESTÁ no escopo**:
-- Funcionalidades específicas a serem implementadas
-- Repositórios que serão modificados
-- Integrações necessárias
-
-**O que NÃO ESTÁ no escopo**:
-- Funcionalidades relacionadas mas que ficam para depois
-- Otimizações futuras
-- Features "nice to have"
-
-### 4. Critérios de Aceitação
-
-Defina critérios mensuráveis e testáveis:
-
-```markdown
-## Critérios de Aceitação
-
-### Funcional
-- [ ] [Critério 1 - específico e testável]
-- [ ] [Critério 2 - específico e testável]
-
-### Técnico
-- [ ] [Critério técnico 1]
-- [ ] [Critério técnico 2]
-
-### Qualidade
-- [ ] Testes unitários implementados
-- [ ] Testes de integração implementados
-- [ ] Documentação atualizada
-```
-
-### 5. Análise de Impacto
-
-Para cada repositório afetado:
+**Processo de Validação**:
 
+1. **Consulte os índices carregados** pelo `/warm-up`:
+   - Leia `context-manifest.json` para encontrar o repositório com `role: "metaspecs"`
+   - Obtenha o `id` desse repositório (ex: "my-project-metaspecs")
+   - Leia `ai.properties.md` para obter o `base_path`
+   - O repositório de metaspecs está em: `{base_path}/{metaspecs-id}/`
+   - Consulte `{base_path}/{metaspecs-id}/index.md` - Visão geral do projeto
+   - Consulte índices específicos (ex: `specs/business/index.md`, `specs/technical/index.md`)
+
+2. **Identifique documentos relevantes** para este requisito específico:
+   - Em `specs/business/`: Quais documentos de negócio são relevantes?
+   - Em `specs/technical/`: Quais documentos técnicos são relevantes?
+
+3. **Leia APENAS os documentos relevantes** identificados (não leia tudo!)
+
+4. **Valide o requisito** contra as metaspecs lidas:
+   - ✅ Alinhamento com estratégia e visão de produto
+   - ✅ Atende necessidades das personas corretas
+   - ✅ Compatível com stack tecnológica aprovada
+   - ✅ Respeita decisões arquiteturais (ADRs)
+   - ✅ Segue regras de negócio existentes
+   - ⚠️ Identifique conflitos ou violações
+
+**Se identificar violações**: 🛑 **PARE** e peça esclarecimento ao usuário antes de prosseguir (Princípio Jidoka).
+
+### 3. Fase de Resumo e Aprovação
+
+Uma vez que tenha coletado informações suficientes e validado contra metaspecs, apresente um resumo estruturado com:
+- **Feature**: Nome da funcionalidade
+- **Objetivo**: Por que construir (1-2 frases)
+- **Valor de Negócio**: Métrica, persona, fase do roadmap (consulte metaspecs)
+- **Escopo**: O que INCLUI e o que NÃO INCLUI
+- **Componentes Afetados**: Lista baseada na arquitetura atual (consulte metaspecs técnicas)
+- **Validação contra Metaspecs**: ✅ Aprovado / ⚠️ Atenção necessária
+- **Estimativa de Esforço**: Pequeno (< 1 dia) / Médio (1-3 dias) / Grande (3-5 dias) / Muito Grande (> 5 dias)
+
+**Avaliação de Complexidade e Sugestão de Quebra**:
+
+**Se a implementação parecer grande** (> 5 dias de esforço estimado):
+- 🚨 **Sugira quebrar em múltiplas issues menores**
+- Explique o racional da quebra (ex: "Esta feature envolve 3 áreas distintas que podem ser implementadas independentemente")
+- Proponha uma quebra **lógica** baseada em:
+  - Funcionalidades independentes
+  - Repositórios diferentes
+  - Camadas da aplicação (backend, frontend, infra)
+  - Fases de implementação (MVP, melhorias, otimizações)
+- Exemplo de quebra:
+  ```
+  Issue Original: "Sistema de notificações multi-canal"
+  
+  Quebra Sugerida:
+  - FIN-201: Infraestrutura de filas e workers (backend)
+  - FIN-202: Notificações por email (backend + templates)
+  - FIN-203: Notificações push (backend + mobile)
+  - FIN-204: Preferências de notificação (frontend + backend)
+  ```
+- **Importante**: A decisão final é do usuário - ele pode aceitar a quebra ou manter como issue única
+
+**Se o usuário aceitar a quebra**:
+- Documente cada issue separadamente
+- Adicione referências cruzadas entre as issues relacionadas
+- Sugira ordem de implementação se houver dependências
+- Cada issue quebrada deve passar pelo mesmo processo de refinamento
+
+Peça aprovação do usuário e incorpore feedback se necessário.
+
+**Dica**: Você pode pesquisar no código-base ou internet antes de finalizar, se necessário.
+
+### 4. Salvamento dos Requisitos Refinados
+
+Uma vez que o usuário aprove, salve os requisitos:
+
+**IMPORTANTE**: Sempre crie backup local E atualize o task manager (se configurado).
+
+**Processo de Salvamento**:
+
+1. **SEMPRE criar backup local primeiro**:
+   - Crie arquivo completo em `./.sessions/<ISSUE-ID>/refined.md` (ex: `./.sessions/FIN-5/refined.md`)
+   - Onde `<ISSUE-ID>` é o ID da issue (ex: FIN-5, FIN-123)
+   - Inclua TODOS os detalhes do refinamento (backup completo)
+
+2. **Se task manager estiver configurado** (leia `ai.properties.md` para identificar `task_management_system`):
+   - Identifique a ferramenta MCP do task manager
+   - **Atualize o BODY (description) da issue** com versão CONCISA dos requisitos refinados
+     - Para Jira: Use MCP do Jira com campo `description`
+     - Para Linear: Use MCP do Linear com campo `description`
+     - Para GitHub: Use MCP do GitHub com campo `body`
+     - Inclua todo o conteúdo refinado no campo description/body da issue
+     - Se o conteúdo for muito extenso e houver erro de API, considere criar versão resumida
+   - **SEMPRE sobrescrever** o body existente (não adicionar ao final)
+
+**Observação**:
+- O backup local SEMPRE está salvo e completo
+- Se houver erro de API, verifique manualmente se a issue foi atualizada no task manager
+
+**Template de Saída**:
+
+**IMPORTANTE**: O template padrão para requisitos refinados pode estar documentado no repositório de metaspecs. Consulte `{base_path}/{metaspecs-id}/specs/refined/` ou similar.
+
+**Template COMPLETO** (para backup local `.sessions/<ISSUE-ID>/refined.md`):
+- **Metadados**: Issue, ID, Task Manager, Projeto, Data, Sprint, Prioridade
+- **🎯 POR QUE**: Razões, valor de negócio, métrica, persona, alinhamento estratégico
+- **📦 O QUE**: Funcionalidades detalhadas, componentes afetados, integrações, escopo negativo completo
+- **🔧 COMO**: Stack, padrões de código, estrutura de arquivos, dependências, ordem de implementação, failure modes, considerações de performance/custo/UX
+- **✅ Validação contra Metaspecs**: Documentos consultados (business e technical), ADRs verificados, resultado da validação
+- **📊 Métricas de Sucesso**: Técnicas, produto/UX, critérios de aceitação
+- **🔄 Impacto no Produto**: Alinhamento com objetivos, habilitadores, riscos mitigados
+- **⚠️ Limitações Conhecidas**: Limitações do MVP
+- **📝 Checklist de Implementação**: Tarefas por área (backend, frontend, testes, segurança, etc.)
+
+**Template para Task Manager**:
 ```markdown
-## Impacto por Repositório
-
-### <repo-1>
-- **Componentes afetados**: [lista]
-- **Tipo de mudança**: Nova feature / Modificação / Refatoração
-- **Complexidade estimada**: Baixa / Média / Alta
-- **Riscos**: [riscos específicos]
-
-### <repo-2>
-- **Componentes afetados**: [lista]
-- **Tipo de mudança**: Nova feature / Modificação / Refatoração
-- **Complexidade estimada**: Baixa / Média / Alta
-- **Riscos**: [riscos específicos]
-```
-
-### 6. Dependências e Restrições
-
-Identifique:
-- Dependências entre repositórios
-- Dependências de outras features/issues
-- Restrições técnicas
-- Restrições de negócio
-- Bloqueadores conhecidos
-
-### 7. Estimativa Inicial
+# [Nome Feature] - Requisitos Refinados
 
-Forneça estimativa de esforço:
-- **Pequeno**: < 1 dia
-- **Médio**: 1-3 dias
-- **Grande**: 3-5 dias
-- **Muito Grande**: > 5 dias (considere quebrar em issues menores)
+**Sprint X** | **Y dias** | **Prioridade**
 
-### 8. Perguntas Pendentes
+## Objetivo
+[1-2 parágrafos: o que é e por que fazer]
 
-Liste perguntas que ainda precisam ser respondidas antes de iniciar a implementação.
-
-## 📄 Salvamento do Refinamento
+## Escopo
 
-**PRIORIDADE 1: Atualizar via MCP**
+### Principais Funcionalidades
+- Funcionalidade 1: [resumo]
+- Funcionalidade 2: [resumo]
+- Validações/Guards: [resumo]
 
-- Use o MCP do task manager para atualizar a issue
-- Adicione os critérios de aceitação como comentário ou campo customizado
-- Atualize labels/tags se necessário (ex: "refined", "ready-for-spec")
-- Adicione estimativa se o task manager suportar
-- Informe ao usuário: "✅ Issue [ID] atualizada com refinamento"
+### Componentes Afetados
+- Componente 1: [tipo de mudança]
+- Componente 2: [tipo de mudança]
 
-**FALLBACK: Criar arquivo .md apenas se MCP falhar**
+### Segurança
+✅ [item 1] ✅ [item 2] ✅ [item 3]
 
-Se o MCP não estiver disponível ou falhar, crie/atualize `./.sessions/<ISSUE-ID>/refine.md`:
+## Escopo Negativo
+❌ [item 1] ❌ [item 2] ❌ [item 3]
 
-```markdown
-# [Título da Issue] - Refinamento
+## Stack
+[Tech stack resumida por área]
 
-## Escopo
+## Estrutura
+[Árvore de arquivos RESUMIDA - principais módulos apenas]
 
-### Incluído
-- [Item 1]
-- [Item 2]
-
-### Excluído
-- [Item 1]
-- [Item 2]
+## Failure Modes (Evitar)
+🔴 [crítico 1] 🔴 [crítico 2]
+🟡 [médio 1] 🟡 [médio 2]
 
 ## Critérios de Aceitação
-[Conforme seção 3 acima]
-
-## Impacto por Repositório
-[Conforme seção 4 acima]
-
-## Dependências
-- [Dependência 1]
-- [Dependência 2]
-
-## Restrições
-- [Restrição 1]
-- [Restrição 2]
+- [ ] [item 1]
+- [ ] [item 2]
+- [ ] [item 3]
 
-## Estimativa
-[Pequeno/Médio/Grande/Muito Grande] - [Justificativa]
+## Validação
+**ADRs**: [lista]
+**Specs**: [principais]
+**Status**: ✅ Aprovado
 
-## Perguntas Pendentes
-1. [Pergunta 1]
-2. [Pergunta 2]
+**Impacto**: [resumo]
+**Limitações**: [resumo]
 
-## Riscos Identificados
-- [Risco 1 e mitigação]
-- [Risco 2 e mitigação]
+---
+📄 **Documento completo**: `.sessions/<ISSUE-ID>/refined.md`
 ```
 
-Informe ao usuário: "⚠️ Refinamento salvo localmente em .sessions/ (task manager não disponível)"
-
-## 🔍 Validação
-
-Valide o refinamento contra:
-- Estratégia do produto (se documentada)
-- Arquitetura técnica (se documentada)
-- Capacidade do time
-- Prioridades do roadmap
+**Audiência**: Desenvolvedor IA com capacidades similares às suas. Seja conciso mas completo.
 
 ---
 
-**Argumentos fornecidos**:
+**Requisito para Refinar**:
 
 ```
 #$ARGUMENTS
@@ -213,10 +215,12 @@ Valide o refinamento contra:
 
 ## 🎯 Próximo Passo
 
-Após refinamento aprovado:
+**Após aprovação do usuário e salvamento dos requisitos refinados**, o fluxo natural é:
 
 ```bash
 /spec [ISSUE-ID]
 ```
 
-Este comando criará a especificação completa (PRD) da feature.
+**Exemplo**: `/spec FIN-3`
+
+Este comando irá criar um PRD (Product Requirements Document) completo baseado nos requisitos refinados, detalhando funcionalidades, user stories, critérios de aceitação e validações finais.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-first-cli",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "description": "A generic CLI to manage the Context-First development methodology across any project.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/templates/commands/en/products/collect.md

@@ -1,18 +1,18 @@
-# Idea and Requirements Collection
+# Idea and Requirements Gathering
 
-You are a product expert responsible for collecting and documenting new ideas, features, or bugs.
+You are a product specialist responsible for collecting and documenting new ideas, features, or bugs.
 
-## ⚠️ IMPORTANT: This Command Does NOT Implement Code
+## ⚠️ IMPORTANT: This Command DOES NOT Implement Code
 
 **This command is ONLY for planning and documentation:**
 - ✅ Collect and understand requirements
-- ✅ Create issue in task manager via MCP
-- ✅ Ask clarifying questions
+- ✅ Create issue in the task manager via MCP
+- ✅ Ask clarification questions
 - ✅ **READ** files from main repositories (read-only)
 - ❌ **DO NOT implement code**
 - ❌ **DO NOT edit code files**
 - ❌ **DO NOT checkout branches in main repositories**
-- ❌ **DO NOT make commits**
+- ❌ **DO NOT commit**
 
 **Next step**: `/refine [ISSUE-ID]` to refine the collected requirements.
 
@@ -22,27 +22,27 @@ You are a product expert responsible for collecting and documenting new ideas, f
 
 Before starting, load the context by consulting:
 
-1. **Locate MetaSpecs automatically**:
-   - Read `context-manifest.json` from orchestrator
+1. **Automatically Locate MetaSpecs**:
+   - Read `context-manifest.json` from the orchestrator
    - Find the repository with `"role": "metaspecs"`
    - Read `ai.properties.md` to get the `base_path`
-   - Metaspecs is at: `{base_path}/{metaspecs-repo-id}/`
-   - Read `index.md` files as reference
+   - The metaspecs are at: `{base_path}/{metaspecs-repo-id}/`
+   - Read the `index.md` files as reference
 
-2. **Project structure**:
-   - `context-manifest.json` - List of repositories and their functions
-   - `README.md` of involved repositories
+2. **Project Structure**:
+   - `context-manifest.json` - List of repositories and their roles
+   - `README.md` of the involved repositories
 
-## Your Objective
+## Your Goal
 
 Understand the user's request and capture it as an issue in the task manager (via MCP).
 
 **At this stage, you DO NOT need to:**
-- ❌ Write complete specification
+- ❌ Write a complete specification
 - ❌ Validate against metaspecs (this is done in `/refine` or `/spec`)
 - ❌ Detail technical implementation
 
-Just make sure the idea is **adequately understood**.
+Just ensure the idea is **adequately understood**.
 
 ## Issue Format
 
@@ -50,7 +50,7 @@ Just make sure the idea is **adequately understood**.
 # [Clear and Descriptive Title]
 
 ## Description
-[2-3 paragraphs explaining what the feature/bug is and why it's important]
+[2-3 paragraphs explaining what the feature/bug is and why it is important]
 
 ## Type
 - [ ] New Feature
@@ -60,7 +60,7 @@ Just make sure the idea is **adequately understood**.
 - [ ] Documentation
 
 ## Additional Context
-[Relevant information: where the bug occurs, feature inspiration, etc.]
+[Relevant information: where the bug occurs, inspiration for the feature, etc.]
 
 ## Affected Repositories
 [List which project repositories will be impacted]
@@ -75,65 +75,89 @@ Just make sure the idea is **adequately understood**.
 ## Collection Process
 
 1. **Initial Understanding**
-   - Ask clarifying questions if needed
+   - Ask clarification questions if needed
    - Identify: Is it a new feature? Improvement? Bug?
    - Identify which repositories will be affected
 
 2. **Issue Draft**
-   - Clear title (maximum 10 words)
+   - Clear title (max 10 words)
    - Objective description (2-3 paragraphs)
    - Relevant additional context
    - Affected repositories
    - Suggested priority
 
-3. **User Approval**
-   - Present the draft
+3. **Complexity Assessment and Suggestion to Split**
+   
+   Before finalizing, assess the issue complexity:
+   
+   **If the implementation seems large** (> 5 days estimated effort):
+   - 🚨 **Suggest splitting into multiple smaller issues**
+   - Explain the rationale for splitting (e.g., "This feature involves 3 distinct areas: authentication, processing, and notification")
+   - Propose a **logical** split (by functionality, repository, layer, etc.)
+   - Example of splitting:
+     ```
+     Original Issue: "Complete payment system"
+     
+     Suggested Split:
+     - FIN-101: Payment gateway integration (backend)
+     - FIN-102: Checkout interface (frontend)
+     - FIN-103: Confirmation webhook and notifications (backend + jobs)
+     ```
+   - **Important**: The final decision is the user's - they can accept the split or keep it as a single issue
+   
+   **If the user accepts the split**:
+   - Create each issue separately using the same process
+   - Add cross-references between related issues
+   - Suggest implementation order if dependencies exist
+
+4. **User Approval**
+   - Present the draft (or drafts, if split)
    - Make adjustments based on feedback
    - Obtain final approval
 
-4. **Issue Saving**
+5. **Saving the Issue**
 
    **PRIORITY 1: Use MCP (Model Context Protocol)**
    
-   Check if there's MCP configured for task manager:
-   - Read `ai.properties.md` from orchestrator to identify the `task_management_system`
+   Check if MCP is configured for the task manager:
+   - Read `ai.properties.md` from the orchestrator to identify the `task_management_system`
    - If `task_management_system=jira`: Use Jira MCP to create the issue
    - If `task_management_system=linear`: Use Linear MCP to create the issue
    - If `task_management_system=github`: Use GitHub MCP to create the issue
    
    **When using MCP:**
    - Create the issue directly in the task manager
-   - Get the created issue ID (e.g., FIN-123, LIN-456)
+   - Obtain the created issue ID (e.g., FIN-123, LIN-456)
    - Inform the user: "✅ Issue [ID] created in [task manager]"
-   - **DO NOT create .md file**
+   - **DO NOT create a .md file**
    
    **FALLBACK: Create .md file only if MCP fails**
    
-   If MCP is not available or fails:
-   - Create file at `./.sessions/<ISSUE-ID>/collect.md`
+   If MCP is unavailable or fails:
+   - Create a file at `./.sessions/<ISSUE-ID>/collect.md`
    - Use manual ID format: `LOCAL-001`, `LOCAL-002`, etc.
-   - Include date, type, and complete content
+   - Include date, type, and full content
    - Inform the user: "⚠️ Issue saved locally in .sessions/ (task manager not available)"
 
-## Clarifying Questions
+## Clarification Questions
 
 **For Features**:
 - What problem does it solve?
 - Who benefits?
-- Is it visible functionality or infrastructure?
+- Is it a visible functionality or infrastructure?
 - Is it related to any existing feature?
-- Which repositories need to be modified?
+- Which repositories need modification?
 
 **For Bugs**:
 - Where does the bug occur? (repository, component, flow)
 - How to reproduce?
-- What is the expected vs actual behavior?
-- Impact severity?
+- Expected vs current behavior?
+- Severity of impact?
 
 **For Improvements**:
-- What is working but can improve?
-- Which metric do we want to impact?
-- Is it technical or business optimization?
+- What is working but can be improved?
+- What metric do we want to impact?
+- Is it a technical or business optimization?
 
 ---
 
@@ -147,10 +171,10 @@ Just make sure the idea is **adequately understood**.
 
 ## 🎯 Next Step
 
-After approval and issue saving:
+After approval and saving the issue:
 
 ```bash
 /refine [ISSUE-ID]
 ```
 
-This command will transform the collected issue into refined and validated requirements.
+This command will transform the collected issue into refined and validated requirements.