context-first-cli 2.3.1 → 2.3.2

package/dist/templates/commands/pt-BR/commands/quality/metrics.md

@@ -0,0 +1,266 @@
+# Métricas de Qualidade
+
+Este comando coleta e analisa métricas de qualidade do código e do processo de desenvolvimento.
+
+## 🎯 Objetivo
+
+Medir e documentar a qualidade da implementação através de métricas objetivas:
+- Cobertura de testes
+- Complexidade do código
+- Dívida técnica
+- Performance
+- Conformidade com padrões
+
+## Configuração
+
+Leia `context-manifest.json` e `ai.properties.md` do orchestrator para obter repositórios, base_path e task_management_system.
+
+## 📋 Pré-requisitos
+
+- Implementação concluída (após `/work`)
+- Testes implementados
+- Build funcionando
+
+## 📊 Métricas a Coletar
+
+### 1. Cobertura de Testes
+
+Para cada repositório modificado:
+
+```bash
+cd <repositório>
+
+# Executar testes com cobertura (exemplos por stack):
+# Node.js: npm run test:coverage / jest --coverage
+# Python: pytest --cov=src tests/
+# Java: mvn jacoco:report / gradle jacocoTestReport
+# Go: go test -cover ./...
+# Ruby: rspec --coverage
+# Rust: cargo tarpaulin
+# PHP: ./vendor/bin/phpunit --coverage-html coverage/
+# C#: dotnet test /p:CollectCoverage=true
+
+# Capturar resultados
+```
+
+Documente:
+```markdown
+## Cobertura de Testes
+
+### <repo-1>
+- **Cobertura Total**: X%
+- **Statements**: X%
+- **Branches**: X%
+- **Functions**: X%
+- **Lines**: X%
+- **Arquivos não cobertos**: [lista]
+
+### <repo-2>
+[Mesmo formato]
+```
+
+### 2. Complexidade do Código
+
+Analise a complexidade ciclomática dos arquivos modificados:
+
+```markdown
+## Complexidade do Código
+
+### Arquivos com Alta Complexidade
+- **arquivo1.ts**: Complexidade 15 (recomendado: < 10)
+- **arquivo2.ts**: Complexidade 12
+
+### Recomendações
+- [Sugestão de refatoração 1]
+- [Sugestão de refatoração 2]
+```
+
+### 3. Qualidade do Código
+
+```bash
+# Executar linting (exemplos por stack):
+# Node.js: npm run lint / eslint .
+# Python: flake8 . / pylint src/
+# Java: mvn checkstyle:check
+# Go: golangci-lint run
+# Ruby: rubocop
+# Rust: cargo clippy
+
+# Verificar formatação (exemplos por stack):
+# Node.js: prettier --check .
+# Python: black --check .
+# Java: mvn formatter:validate
+# Go: gofmt -l .
+# Ruby: rubocop --format-only
+# Rust: cargo fmt --check
+
+# Análise estática (exemplos por stack):
+# Node.js: npm run analyze (se configurado)
+# Python: mypy src/ / bandit -r src/
+# Java: mvn pmd:check / spotbugs:check
+# Go: go vet ./...
+# Ruby: brakeman (para Rails)
+# Rust: cargo audit
+```
+
+Documente:
+```markdown
+## Qualidade do Código
+
+### Linting
+- **Erros**: 0
+- **Warnings**: X
+- **Warnings Justificados**: [lista com justificativas]
+
+### Formatação
+- **Status**: ✅ Conforme / ⚠️ Ajustes necessários
+
+### Análise Estática
+- **Problemas Críticos**: 0
+- **Problemas Médios**: X
+- **Problemas Baixos**: Y
+```
+
+### 4. Performance
+
+Se aplicável, meça performance:
+
+```markdown
+## Performance
+
+### Benchmarks
+- **Operação X**: Yms (baseline: Zms)
+- **Operação Y**: Yms (baseline: Zms)
+
+### Otimizações Aplicadas
+- [Otimização 1 e impacto]
+- [Otimização 2 e impacto]
+
+### Gargalos Identificados
+- [Gargalo 1 e plano de mitigação]
+```
+
+### 5. Tamanho e Impacto
+
+```markdown
+## Tamanho e Impacto
+
+### Linhas de Código
+- **Adicionadas**: +X linhas
+- **Removidas**: -Y linhas
+- **Modificadas**: Z linhas
+
+### Arquivos
+- **Novos**: X arquivos
+- **Modificados**: Y arquivos
+- **Removidos**: Z arquivos
+
+### Dependências
+- **Novas dependências**: [lista]
+- **Tamanho do bundle**: +X KB
+```
+
+### 6. Dívida Técnica
+
+Identifique dívida técnica introduzida ou resolvida:
+
+```markdown
+## Dívida Técnica
+
+### Dívida Introduzida
+- **Item 1**: [Descrição e justificativa]
+  - Severidade: Alta / Média / Baixa
+  - Plano de resolução: [quando e como resolver]
+
+### Dívida Resolvida
+- **Item 1**: [O que foi resolvido]
+  - Impacto: [melhoria obtida]
+```
+
+## 📄 Relatório de Métricas
+
+Crie `./.sessions/<ISSUE-ID>/metrics.md`:
+
+```markdown
+# Relatório de Métricas - [ISSUE-ID]
+
+**Data**: [data/hora]
+**Repositórios**: [lista]
+
+## Resumo Executivo
+
+- **Cobertura de Testes**: X% (meta: Y%)
+- **Qualidade do Código**: ✅ / ⚠️ / ❌
+- **Performance**: ✅ / ⚠️ / ❌
+- **Dívida Técnica**: Baixa / Média / Alta
+
+## Métricas Detalhadas
+
+[Incluir todas as seções acima]
+
+## Comparação com Baseline
+
+| Métrica | Antes | Depois | Variação |
+|---------|-------|--------|----------|
+| Cobertura | X% | Y% | +Z% |
+| Complexidade Média | X | Y | +Z |
+| Bundle Size | X KB | Y KB | +Z KB |
+
+## Ações Recomendadas
+
+1. [Ação 1 - prioridade alta]
+2. [Ação 2 - prioridade média]
+3. [Ação 3 - prioridade baixa]
+
+## Aprovação para Merge
+
+- [ ] Cobertura de testes >= meta
+- [ ] Sem problemas críticos de qualidade
+- [ ] Performance dentro dos requisitos
+- [ ] Dívida técnica documentada e aprovada
+```
+
+## 🎯 Metas de Qualidade
+
+Se o projeto tiver metas definidas nas metaspecs, valide:
+
+```markdown
+## Validação contra Metas
+
+### Metas do Projeto
+- **Cobertura mínima**: 80%
+- **Complexidade máxima**: 10
+- **Performance**: < 100ms
+
+### Status
+- Cobertura: ✅ 85% (meta: 80%)
+- Complexidade: ⚠️ 12 (meta: 10) - Justificado
+- Performance: ✅ 85ms (meta: 100ms)
+```
+
+## 🚨 Alertas
+
+Se alguma métrica estiver fora do aceitável:
+1. 🛑 **DOCUMENTE** o problema
+2. 💬 **ALERTE** o usuário
+3. 🔧 **PROPONHA** ações corretivas
+4. ⏸️ **CONSIDERE** bloquear o merge até resolução
+
+---
+
+**Argumentos fornecidos**:
+
+```
+#$ARGUMENTS
+```
+
+---
+
+## 🎯 Resultado
+
+Após executar este comando, você terá:
+- Relatório completo de métricas
+- Comparação com baseline e metas
+- Identificação de problemas de qualidade
+- Recomendações de ações
+- Base objetiva para aprovação de merge

package/dist/templates/commands/pt-BR/commands/quality/observe.md

@@ -0,0 +1,172 @@
+# Observabilidade de Decisões
+
+Este comando registra decisões importantes tomadas durante o desenvolvimento, criando um log auditável para explicabilidade e rastreabilidade.
+
+## 🎯 Objetivo
+
+Criar registro estruturado de decisões técnicas e de produto, garantindo:
+- **Explicabilidade**: Por que cada decisão foi tomada
+- **Rastreabilidade**: Quais fontes (PRD, metaspecs, ADRs) embasaram a decisão
+- **Auditoria**: Histórico completo de escolhas para revisão futura
+- **Aprendizado**: Documentação de trade-offs e alternativas consideradas
+
+**IMPORTANTE**: Este comando NÃO gera decisões novas. Ele apenas REGISTRA decisões que já foram tomadas no processo de desenvolvimento.
+
+## Configuração
+
+Leia `context-manifest.json` e `ai.properties.md` do orchestrator para obter repositórios, base_path e task_management_system.
+
+## 📋 Pré-requisitos
+
+- Executou pelo menos um dos comandos que geram decisões:
+  - `/spec` - gera PRD com decisões de produto
+  - `/plan` - gera plan.md com decisões técnicas
+  - `/work` - implementação gera decisões durante desenvolvimento
+
+## 🔍 Processo de Observação
+
+### 1. Identificar Decisões Relevantes
+
+Analise os arquivos da sessão (`./.sessions/<ISSUE-ID>/`) para identificar decisões:
+
+**Após `/spec`** - Decisões de Produto:
+- Leia `./.sessions/<ISSUE-ID>/prd.md`
+- Identifique decisões em:
+  - Escopo (o que entra/não entra na feature)
+  - Personas atendidas (quem é o público-alvo)
+  - Métricas de sucesso (como medir resultados)
+  - Requisitos não-funcionais (performance, acessibilidade)
+  - Restrições e trade-offs
+
+**Após `/plan`** - Decisões Técnicas:
+- Leia `./.sessions/<ISSUE-ID>/plan.md`
+- Identifique decisões em:
+  - Arquitetura de componentes/módulos
+  - Escolha de bibliotecas ou ferramentas
+  - Padrões de implementação
+  - Estrutura de dados
+  - Estratégia de testes
+
+**Durante `/work`** - Decisões de Implementação:
+- Leia `./.sessions/<ISSUE-ID>/work.md`
+- Identifique decisões em:
+  - Refatorações realizadas
+  - Mudanças de abordagem
+  - Otimizações aplicadas
+  - Tratamento de edge cases
+
+### 2. Documentar Cada Decisão
+
+Para cada decisão identificada, documente:
+
+```markdown
+## Decisão: [Título Claro]
+
+**Contexto**: [Por que precisamos decidir isso? Qual o problema ou necessidade?]
+
+**Opções Consideradas**:
+1. **Opção A**: [Descrição]
+   - Prós: [vantagens]
+   - Contras: [desvantagens]
+2. **Opção B**: [Descrição]
+   - Prós: [vantagens]
+   - Contras: [desvantagens]
+
+**Decisão**: [Opção escolhida]
+
+**Justificativa**: [Por que escolhemos esta opção? Quais critérios foram mais importantes?]
+
+**Fontes**:
+- [PRD seção X]
+- [Metaspec Y]
+- [ADR-00Z]
+
+**Trade-offs Aceitos**: [Quais desvantagens aceitamos conscientemente?]
+
+**Reversibilidade**: Fácil / Média / Difícil
+
+**Data**: [data da decisão]
+```
+
+### 3. Criar Log de Decisões
+
+Salve em `./.sessions/<ISSUE-ID>/decisions.md`:
+
+```markdown
+# Log de Decisões - [ISSUE-ID]
+
+## Resumo
+[Breve resumo das principais decisões tomadas nesta feature]
+
+## Decisões de Produto
+
+### [Decisão 1]
+[Conforme template acima]
+
+### [Decisão 2]
+[Conforme template acima]
+
+## Decisões Técnicas
+
+### [Decisão 3]
+[Conforme template acima]
+
+### [Decisão 4]
+[Conforme template acima]
+
+## Decisões de Implementação
+
+### [Decisão 5]
+[Conforme template acima]
+
+## Lições Aprendidas
+- [Lição 1]
+- [Lição 2]
+
+## Decisões Pendentes
+- [Decisão que ainda precisa ser tomada]
+```
+
+## 📊 Análise de Impacto
+
+Para decisões críticas, documente o impacto:
+
+```markdown
+## Análise de Impacto
+
+**Repositórios Afetados**: [lista]
+
+**Componentes Impactados**: [lista]
+
+**Dependências Criadas**: [lista]
+
+**Riscos Introduzidos**: [lista]
+
+**Mitigações Aplicadas**: [lista]
+```
+
+## 🔄 Revisão de Decisões
+
+Periodicamente, revise as decisões tomadas:
+- Ainda fazem sentido?
+- Os trade-offs se provaram corretos?
+- Há aprendizados para documentar?
+- Alguma decisão precisa ser revertida?
+
+---
+
+**Argumentos fornecidos**:
+
+```
+#$ARGUMENTS
+```
+
+---
+
+## 🎯 Resultado
+
+Após executar este comando, você terá:
+- Log completo de decisões em `./.sessions/<ISSUE-ID>/decisions.md`
+- Rastreabilidade de cada escolha feita
+- Documentação para futuras referências
+- Base para ADRs (se decisões forem de arquitetura)

package/dist/templates/commands/pt-BR/commands/warm-up.md

@@ -0,0 +1,59 @@
+# Aquecimento - Carregamento de Contexto
+
+Prepara o ambiente carregando o contexto otimizado do projeto.
+
+## 1. Carregar Configuração
+
+Leia os arquivos do orchestrator:
+- **`context-manifest.json`** - Repositórios e roles
+- **`ai.properties.md`** - base_path, task_management_system
+
+## 2. Carregar Contexto Compacto (OTIMIZADO)
+
+**IMPORTANTE**: Use carregamento PROGRESSIVO para economizar janela de contexto.
+
+### Obrigatório (warm-up)
+
+Localize metaspecs via `context-manifest.json` (role: "specs-provider"):
+
+```
+{base_path}/{metaspecs-id}/specs/_meta/WARM_UP_CONTEXT.md  (~100 linhas)
+```
+
+Este arquivo contém TODOS os essenciais:
+- Stack tecnológica
+- Hierarquia de contexto
+- 5 regras críticas
+- Padrões de código mínimos
+- Tabela de carregamento sob demanda
+
+### Sob Demanda (NÃO carregar durante warm-up)
+
+| Necessidade | Documento |
+|-------------|-----------|
+| Gerar código | `CLAUDE.meta.md` |
+| Arquitetura | `ARCHITECTURE.md` |
+| Feature específica | `features/{FEATURE}.md` |
+| Anti-patterns completos | `ANTI_PATTERNS.md` |
+
+## 3. Verificar Repositórios
+
+Para cada repositório no `context-manifest.json`:
+- Verificar existência em `{base_path}/{repo-id}/`
+- **NÃO** ler README.md agora (sob demanda)
+
+## 4. Verificar Sessão (se existir)
+
+```bash
+ls -la .sessions/<ISSUE-ID>/ 2>/dev/null
+```
+
+## 5. Princípio Jidoka
+
+Se problemas detectados: **PARE**, documente, alerte o usuário.
+
+---
+
+**Argumentos**: #$ARGUMENTS
+
+**Status**: Contexto carregado. Aguardando próximo comando.

package/dist/templates/commands/pt-BR/warm-up.md

@@ -1,123 +1,59 @@
 # Aquecimento - Carregamento de Contexto
 
-Este comando prepara o ambiente carregando o contexto completo do projeto e do workspace atual.
+Prepara o ambiente carregando o contexto otimizado do projeto.
 
-## 1. Identificar Workspace Atual
+## 1. Carregar Configuração
 
-Verifique se você está dentro de um workspace criado pelo `context-cli`:
+Leia os arquivos do orchestrator:
+- **`context-manifest.json`** - Repositórios e roles
+- **`ai.properties.md`** - base_path, task_management_system
 
-```bash
-# Verificar se está em um diretório de workspace
-pwd
-# O workspace geralmente está em ~/workspaces/<ISSUE-ID>/
-```
-
-Se não estiver em um workspace, pergunte ao usuário qual workspace usar ou se deve criar um novo com `feature:start`.
-
-## 📋 Configuração do Projeto
+## 2. Carregar Contexto Compacto (OTIMIZADO)
 
-**⚠️ IMPORTANTE: Sempre leia os arquivos de configuração do projeto ANTES de executar este comando!**
+**IMPORTANTE**: Use carregamento PROGRESSIVO para economizar janela de contexto.
 
-### Arquivos Obrigatórios
+### Obrigatório (warm-up)
 
-1. **`context-manifest.json`** (raiz do orchestrator)
-   - Lista de repositórios do projeto
-   - Roles de cada repositório (metaspecs, application, etc.)
-   - URLs e dependências entre repositórios
+Localize metaspecs via `context-manifest.json` (role: "specs-provider"):
 
-2. **`ai.properties.md`** (raiz do orchestrator)
-   - Configurações do projeto (`project_name`, `base_path`)
-   - Sistema de gerenciamento de tarefas (`task_management_system`)
-   - Credenciais e configurações específicas
-
-### Como Ler
-
-```bash
-# 1. Ler context-manifest.json
-cat context-manifest.json
-
-# 2. Ler ai.properties.md
-cat ai.properties.md
+```
+{base_path}/{metaspecs-id}/specs/_meta/WARM_UP_CONTEXT.md  (~100 linhas)
 ```
 
-### Informações Essenciais
-
-Após ler os arquivos, você terá:
-- ✅ Lista completa de repositórios do projeto
-- ✅ Localização do repositório de metaspecs
-- ✅ Base path para localizar repositórios
-- ✅ Sistema de task management configurado
-- ✅ Configurações específicas do projeto
-
-**🛑 NÃO prossiga sem ler estes arquivos!** Eles contêm informações críticas para a execução correta do comando.
-
-
-## 2. Carregar Configuração do Projeto
-
-Você já está no orchestrator do projeto (raiz do repositório atual).
-
-1. **Verifique se está na raiz do orchestrator**: `pwd` deve mostrar o diretório do orchestrator
-2. **Leia o arquivo `context-manifest.json`** na raiz do orchestrator
-3. **Leia o arquivo `ai.properties.md`** para obter configurações locais (base_path, etc.)
-
-## 3. Carregar Manifesto do Projeto
-
-Leia o `context-manifest.json` do orchestrator para entender:
-- Lista completa de repositórios do ecossistema
-- URL do repositório de MetaSpecs
-- Dependências entre repositórios
-- Roles de cada repositório (application, library, service, specs-provider)
-
-## 4. Carregar MetaSpecs
-
-O repositório de MetaSpecs é **separado** e está definido no `context-manifest.json` com `role: "metaspecs"`.
-
-**Localize o repositório de metaspecs:**
-
-1. Leia `context-manifest.json` e encontre o repositório com `role: "metaspecs"`
-2. Obtenha o `id` desse repositório (ex: "my-project-metaspecs")
-3. Leia `ai.properties.md` para obter o `base_path`
-4. O repositório de metaspecs está em: `{base_path}/{metaspecs-id}/`
+Este arquivo contém TODOS os essenciais:
+- Stack tecnológica
+- Hierarquia de contexto
+- 5 regras críticas
+- Padrões de código mínimos
+- Tabela de carregamento sob demanda
 
-**Leia sempre os arquivos de índice primeiro:**
+### Sob Demanda (NÃO carregar durante warm-up)
 
-1. **`README.md`** - Visão geral do projeto e estrutura de documentação
-2. **`index.md`** (na raiz ou em subpastas) - Índice de especificações disponíveis
+| Necessidade | Documento |
+|-------------|-----------|
+| Gerar código | `CLAUDE.meta.md` |
+| Arquitetura | `ARCHITECTURE.md` |
+| Feature específica | `features/{FEATURE}.md` |
+| Anti-patterns completos | `ANTI_PATTERNS.md` |
 
-**Use os índices como referência** para navegar até as especificações específicas que você precisa. Não assuma que arquivos específicos existem - sempre consulte os índices primeiro.
+## 3. Verificar Repositórios
 
-## 5. Carregar Sessão Atual (se existir)
+Para cada repositório no `context-manifest.json`:
+- Verificar existência em `{base_path}/{repo-id}/`
+- **NÃO** ler README.md agora (sob demanda)
 
-Verifique se existe uma sessão salva para este workspace:
+## 4. Verificar Sessão (se existir)
 
 ```bash
-# Procurar por sessão no orchestrator
 ls -la .sessions/<ISSUE-ID>/ 2>/dev/null
 ```
 
-Se existir, leia os arquivos de sessão para recuperar o contexto da última execução.
-
-## 6. Contexto dos Repositórios
-
-Para cada repositório presente no workspace, leia:
-- `README.md` - Propósito e visão geral do repositório
-- Arquivo de configuração principal (`package.json`, `pom.xml`, `requirements.txt`, etc.)
-
-## 7. Navegação Inteligente
-
-- **Código**: Use ferramentas de busca (glob, grep) para localizar arquivos relevantes
-- **Documentação**: Use os índices dos MetaSpecs como referência
-- **Aguarde Instruções**: NÃO leia outros arquivos agora. Aguarde o próximo comando.
-
-## 8. Princípio Jidoka (Parar ao Detectar Problemas)
+## 5. Princípio Jidoka
 
-Se detectar desalinhamento, conflitos ou problemas:
-1. 🛑 **PARE** imediatamente
-2. 📝 **DOCUMENTE** o problema encontrado
-3. 💬 **ALERTE** o usuário antes de prosseguir
+Se problemas detectados: **PARE**, documente, alerte o usuário.
 
 ---
 
-**Argumentos fornecidos**: #$ARGUMENTS
+**Argumentos**: #$ARGUMENTS
 
 **Status**: Contexto carregado. Aguardando próximo comando.

package/package.json

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