context-first-cli 1.8.2 → 2.0.0

package/templates/commands/es/quality/observe.md

@@ -0,0 +1,168 @@
+# Observabilidad de Decisiones
+
+Este comando registra decisiones importantes tomadas durante el desarrollo, creando un registro auditable para explicabilidad y trazabilidad.
+
+## 🎯 Objetivo
+
+Crear un registro estructurado de decisiones técnicas y de producto, garantizando:
+- **Explicabilidad**: Por qué se tomó cada decisión
+- **Trazabilidad**: Qué fuentes (PRD, metaspecs, ADRs) fundamentaron la decisión
+- **Auditoría**: Historial completo de elecciones para revisión futura
+- **Aprendizaje**: Documentación de trade-offs y alternativas consideradas
+
+**IMPORTANTE**: Este comando NO genera decisiones nuevas. Solo REGISTRA decisiones que ya fueron tomadas en el proceso de desarrollo.
+
+## 📋 Requisitos previos
+
+- Haber ejecutado al menos uno de los comandos que generan decisiones:
+  - `/spec` - genera PRD con decisiones de producto
+  - `/plan` - genera plan.md con decisiones técnicas
+  - `/work` - implementación genera decisiones durante el desarrollo
+
+## 🔍 Proceso de Observación
+
+### 1. Identificar Decisiones Relevantes
+
+Analice los archivos de la sesión (`./.sessions/<ISSUE-ID>/`) para identificar decisiones:
+
+**Después de `/spec`** - Decisiones de Producto:
+- Lea `./.sessions/<ISSUE-ID>/prd.md`
+- Identifique decisiones en:
+  - Alcance (qué entra/no entra en la feature)
+  - Personas atendidas (quién es el público objetivo)
+  - Métricas de éxito (cómo medir resultados)
+  - Requisitos no funcionales (performance, accesibilidad)
+  - Restricciones y trade-offs
+
+**Después de `/plan`** - Decisiones Técnicas:
+- Lea `./.sessions/<ISSUE-ID>/plan.md`
+- Identifique decisiones en:
+  - Arquitectura de componentes/módulos
+  - Elección de bibliotecas o herramientas
+  - Patrones de implementación
+  - Estructura de datos
+  - Estrategia de tests
+
+**Durante `/work`** - Decisiones de Implementación:
+- Lea `./.sessions/<ISSUE-ID>/work.md`
+- Identifique decisiones en:
+  - Refactorizaciones realizadas
+  - Cambios de enfoque
+  - Optimizaciones aplicadas
+  - Tratamiento de edge cases
+
+### 2. Documentar Cada Decisión
+
+Para cada decisión identificada, documente:
+
+```markdown
+## Decisión: [Título Claro]
+
+**Contexto**: [¿Por qué necesitamos decidir esto? ¿Cuál es el problema o necesidad?]
+
+**Opciones Consideradas**:
+1. **Opción A**: [Descripción]
+   - Pros: [ventajas]
+   - Contras: [desventajas]
+2. **Opción B**: [Descripción]
+   - Pros: [ventajas]
+   - Contras: [desventajas]
+
+**Decisión**: [Opción elegida]
+
+**Justificación**: [¿Por qué elegimos esta opción? ¿Qué criterios fueron más importantes?]
+
+**Fuentes**:
+- [PRD sección X]
+- [Metaspec Y]
+- [ADR-00Z]
+
+**Trade-offs Aceptados**: [¿Qué desventajas aceptamos conscientemente?]
+
+**Reversibilidad**: Fácil / Media / Difícil
+
+**Fecha**: [fecha de la decisión]
+```
+
+### 3. Crear Registro de Decisiones
+
+Guarde en `./.sessions/<ISSUE-ID>/decisions.md`:
+
+```markdown
+# Registro de Decisiones - [ISSUE-ID]
+
+## Resumen
+[Breve resumen de las principales decisiones tomadas en esta feature]
+
+## Decisiones de Producto
+
+### [Decisión 1]
+[Según plantilla arriba]
+
+### [Decisión 2]
+[Según plantilla arriba]
+
+## Decisiones Técnicas
+
+### [Decisión 3]
+[Según plantilla arriba]
+
+### [Decisión 4]
+[Según plantilla arriba]
+
+## Decisiones de Implementación
+
+### [Decisión 5]
+[Según plantilla arriba]
+
+## Lecciones Aprendidas
+- [Lección 1]
+- [Lección 2]
+
+## Decisiones Pendientes
+- [Decisión que aún necesita ser tomada]
+```
+
+## 📊 Análisis de Impacto
+
+Para decisiones críticas, documente el impacto:
+
+```markdown
+## Análisis de Impacto
+
+**Repositorios Afectados**: [lista]
+
+**Componentes Impactados**: [lista]
+
+**Dependencias Creadas**: [lista]
+
+**Riesgos Introducidos**: [lista]
+
+**Mitigaciones Aplicadas**: [lista]
+```
+
+## 🔄 Revisión de Decisiones
+
+Periódicamente, revise las decisiones tomadas:
+- ¿Siguen teniendo sentido?
+- ¿Los trade-offs se demostraron correctos?
+- ¿Hay aprendizajes para documentar?
+- ¿Alguna decisión necesita ser revertida?
+
+---
+
+**Argumentos proporcionados**:
+
+```
+#$ARGUMENTS
+```
+
+---
+
+## 🎯 Resultado
+
+Después de ejecutar este comando, tendrá:
+- Registro completo de decisiones en `./.sessions/<ISSUE-ID>/decisions.md`
+- Trazabilidad de cada elección realizada
+- Documentación para futuras referencias
+- Base para ADRs (si las decisiones son de arquitectura)

package/templates/commands/es/warm-up.md

@@ -0,0 +1,78 @@
+# Calentamiento - Carga de Contexto
+
+Este comando prepara el entorno cargando el contexto completo del proyecto y del workspace actual.
+
+## 1. Identificar Workspace Actual
+
+Verifique si está dentro de un workspace creado por `context-cli`:
+
+```bash
+# Verificar si está en un directorio de workspace
+pwd
+# El workspace generalmente está en ~/workspaces/<ISSUE-ID>/
+```
+
+Si no está en un workspace, pregunte al usuario qué workspace usar o si debe crear uno nuevo con `feature:start`.
+
+## 2. Cargar Configuración del Proyecto
+
+Identifique el orchestrator del proyecto:
+
+1. **Busque el archivo `.contextrc.json`** en cualquiera de los repositorios del workspace
+2. Este archivo contiene la URL del repositorio orchestrator
+3. Si el orchestrator aún no está clonado localmente, clónelo
+
+## 3. Cargar Manifiesto del Proyecto
+
+Lea el `context-manifest.json` del orchestrator para entender:
+- Lista completa de repositorios del ecosistema
+- URL del repositorio de MetaSpecs
+- Dependencias entre repositorios
+- Roles de cada repositorio (application, library, service, specs-provider)
+
+## 4. Cargar MetaSpecs
+
+El repositorio de MetaSpecs está definido en `context-manifest.json` (generalmente con `role: "specs-provider"`).
+
+**Lea siempre los archivos de índice primero:**
+
+1. **`README.md`** - Visión general del proyecto y estructura de documentación
+2. **`index.md`** (en la raíz o en subcarpetas) - Índice de especificaciones disponibles
+
+**Use los índices como referencia** para navegar hasta las especificaciones específicas que necesita. No asuma que archivos específicos existen - siempre consulte los índices primero.
+
+## 5. Cargar Sesión Actual (si existe)
+
+Verifique si existe una sesión guardada para este workspace:
+
+```bash
+# Buscar sesión en orchestrator
+ls -la .sessions/<ISSUE-ID>/ 2>/dev/null
+```
+
+Si existe, lea los archivos de sesión para recuperar el contexto de la última ejecución.
+
+## 6. Contexto de los Repositorios
+
+Para cada repositorio presente en el workspace, lea:
+- `README.md` - Propósito y visión general del repositorio
+- Archivo de configuración principal (`package.json`, `pom.xml`, `requirements.txt`, etc.)
+
+## 7. Navegación Inteligente
+
+- **Código**: Use herramientas de búsqueda (glob, grep) para localizar archivos relevantes
+- **Documentación**: Use los índices de MetaSpecs como referencia
+- **Espere Instrucciones**: NO lea otros archivos ahora. Espere el próximo comando.
+
+## 8. Principio Jidoka (Parar al Detectar Problemas)
+
+Si detecta desalineamiento, conflictos o problemas:
+1. 🛑 **PARE** inmediatamente
+2. 📝 **DOCUMENTE** el problema encontrado
+3. 💬 **ALERTE** al usuario antes de proceder
+
+---
+
+**Argumentos proporcionados**: #$ARGUMENTS
+
+**Estado**: Contexto cargado. Esperando próximo comando.

package/templates/commands/pt-BR/engineer/plan.md

@@ -0,0 +1,297 @@
+# Planejamento Técnico
+
+Este comando cria o plano técnico detalhado para implementação da feature.
+
+## 📋 Pré-requisitos
+
+- PRD criado via `/spec`
+- Análise inicial feita via `/start`
+- Arquivos `context.md` e `architecture.md` criados e aprovados
+
+## 📍 IMPORTANTE: Entenda a Estrutura
+
+**Workspace**:
+```
+<orchestrator>/.sessions/<ISSUE-ID>/
+├── repo-1/          # worktree (será usado no /work)
+├── repo-2/          # worktree (será usado no /work)
+├── context.md       # contexto (imutável - LER)
+├── architecture.md  # arquitetura (imutável - LER)
+└── plan.md          # plano (mutável - CRIAR)
+```
+
+**Repositórios principais** (apenas leitura):
+```
+{base_path}/repo-1/  # repo principal (branch main/master)
+{base_path}/repo-2/  # repo principal (branch main/master)
+```
+
+**REGRA DE OURO**:
+- ✅ Leia `context.md` e `architecture.md` (imutáveis)
+- ✅ Crie `plan.md` em `.sessions/<ISSUE-ID>/`
+- ✅ Leia código dos repositórios principais (read-only)
+- ❌ NUNCA faça checkout nos repositórios principais
+- ❌ NUNCA modifique `context.md` ou `architecture.md`
+
+## ⚠️ IMPORTANTE: Arquivos Imutáveis
+
+**Este comando deve LER mas NÃO MODIFICAR:**
+- ✅ **LER** `.sessions/<ISSUE-ID>/context.md` (imutável)
+- ✅ **LER** `.sessions/<ISSUE-ID>/architecture.md` (imutável)
+- ✅ **CRIAR** `.sessions/<ISSUE-ID>/plan.md` (mutável - será atualizado durante `/work`)
+- ❌ **NÃO modificar `context.md` ou `architecture.md`**
+
+## 📚 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 garantir conformidade com:
+   - Arquitetura do sistema
+   - Padrões de design e código
+   - Estrutura de pastas e arquivos
+   - Convenções de nomenclatura
+
+## 🎯 Objetivo
+
+Criar um plano técnico detalhado que guiará a implementação, dividindo o trabalho em unidades menores e sequenciais.
+
+## 📝 Estrutura do Plano
+
+### 1. Visão Geral Técnica
+
+```markdown
+# Plano Técnico - [Título da Feature]
+
+## Resumo
+[Breve descrição técnica do que será implementado]
+
+## Repositórios Envolvidos
+- **<repo-1>**: [Papel nesta feature]
+- **<repo-2>**: [Papel nesta feature]
+
+## Abordagem Técnica
+[Estratégia geral de implementação]
+```
+
+### 2. Arquitetura da Solução
+
+```markdown
+## Arquitetura
+
+### Diagrama de Componentes
+[Descrição textual ou ASCII art dos componentes e suas relações]
+
+### Fluxo de Dados
+1. [Passo 1 do fluxo]
+2. [Passo 2 do fluxo]
+3. [Passo 3 do fluxo]
+
+### Integrações
+- **<repo-1> → <repo-2>**: [Como se comunicam]
+- **Sistema → API Externa**: [Se houver]
+```
+
+### 3. Decisões Técnicas
+
+```markdown
+## Decisões Técnicas
+
+### Decisão 1: [Título]
+**Contexto**: [Por que precisamos decidir isso]
+**Opções consideradas**:
+- Opção A: [Prós e contras]
+- Opção B: [Prós e contras]
+**Decisão**: [Opção escolhida]
+**Justificativa**: [Por que escolhemos esta opção]
+
+### Decisão 2: [Título]
+[Mesmo formato acima]
+```
+
+### 4. Plano de Implementação
+
+Divida o trabalho em unidades pequenas e sequenciais:
+
+```markdown
+## Plano de Implementação
+
+### Fase 1: [Nome da Fase]
+**Objetivo**: [O que será alcançado nesta fase]
+**Repositórios**: [repos afetados]
+
+#### Tarefa 1.1: [Descrição]
+- **Repo**: <repo-1>
+- **Arquivos**: [arquivos a criar/modificar]
+- **Descrição**: [O que fazer]
+- **Testes**: [Testes a implementar]
+- **Estimativa**: [tempo estimado]
+
+#### Tarefa 1.2: [Descrição]
+- **Repo**: <repo-2>
+- **Arquivos**: [arquivos a criar/modificar]
+- **Descrição**: [O que fazer]
+- **Testes**: [Testes a implementar]
+- **Estimativa**: [tempo estimado]
+
+### Fase 2: [Nome da Fase]
+[Mesmo formato acima]
+
+### Fase 3: [Nome da Fase]
+[Mesmo formato acima]
+```
+
+### 5. Estrutura de Arquivos
+
+Para cada repositório, defina a estrutura:
+
+```markdown
+## Estrutura de Arquivos
+
+### <repo-1>
+```
+src/
+├── components/
+│   ├── NewComponent.tsx (CRIAR)
+│   └── ExistingComponent.tsx (MODIFICAR)
+├── services/
+│   └── NewService.ts (CRIAR)
+└── tests/
+    └── NewComponent.test.tsx (CRIAR)
+```
+
+### <repo-2>
+```
+src/
+├── controllers/
+│   └── NewController.ts (CRIAR)
+└── tests/
+    └── NewController.test.ts (CRIAR)
+```
+```
+
+### 6. APIs e Contratos
+
+```markdown
+## APIs e Contratos
+
+### Endpoints Novos
+
+#### POST /api/resource
+**Request**:
+```json
+{
+  "field1": "string",
+  "field2": "number"
+}
+```
+
+**Response**:
+```json
+{
+  "id": "string",
+  "status": "string"
+}
+```
+
+### Endpoints Modificados
+
+#### GET /api/resource/:id
+**Mudanças**: [O que muda]
+**Breaking Change**: Sim / Não
+```
+
+### 7. Estratégia de Testes
+
+```markdown
+## Estratégia de Testes
+
+### Testes Unitários
+- **<repo-1>**: [Componentes/funções a testar]
+- **<repo-2>**: [Componentes/funções a testar]
+
+### Testes de Integração
+- **Cenário 1**: [Descrição e repos envolvidos]
+- **Cenário 2**: [Descrição e repos envolvidos]
+
+### Testes E2E (se aplicável)
+- **Fluxo 1**: [Descrição]
+- **Fluxo 2**: [Descrição]
+```
+
+### 8. Riscos Técnicos
+
+```markdown
+## Riscos Técnicos
+
+### Risco 1: [Descrição]
+- **Impacto**: Alto / Médio / Baixo
+- **Probabilidade**: Alta / Média / Baixa
+- **Mitigação**: [Como mitigar]
+- **Plano B**: [Alternativa se ocorrer]
+
+### Risco 2: [Descrição]
+[Mesmo formato acima]
+```
+
+### 9. Checklist de Implementação
+
+```markdown
+## Checklist de Implementação
+
+### Fase 1
+- [ ] Tarefa 1.1
+- [ ] Tarefa 1.2
+- [ ] Testes da Fase 1
+
+### Fase 2
+- [ ] Tarefa 2.1
+- [ ] Tarefa 2.2
+- [ ] Testes da Fase 2
+
+### Fase 3
+- [ ] Tarefa 3.1
+- [ ] Tarefa 3.2
+- [ ] Testes da Fase 3
+
+### Finalização
+- [ ] Documentação atualizada
+- [ ] Code review
+- [ ] Testes de integração
+- [ ] PR criado
+```
+
+## 📄 Salvamento do Plano
+
+Salve em `./.sessions/<ISSUE-ID>/plan.md`
+
+## 🔍 Revisão
+
+Revise o plano verificando:
+- Todas as tarefas estão claras e executáveis
+- Dependências entre tarefas estão identificadas
+- Estimativas são realistas
+- Riscos foram considerados
+- Estratégia de testes é adequada
+
+---
+
+**Argumentos fornecidos**:
+
+```
+#$ARGUMENTS
+```
+
+---
+
+## 🎯 Próximo Passo
+
+Após aprovação do plano:
+
+```bash
+/work
+```
+
+Este comando iniciará a execução da primeira unidade de trabalho do plano.

package/templates/commands/pt-BR/engineer/pr.md

@@ -0,0 +1,167 @@
+# Criação de Pull Request
+
+Este comando cria Pull Requests para todos os repositórios modificados no workspace.
+
+## 📋 Pré-requisitos
+
+Antes de criar PRs, certifique-se de que:
+- Executou `/pre-pr` e todas as validações passaram
+- Todos os commits foram feitos
+- Todos os testes estão passando
+- A documentação está atualizada
+
+## 🎯 Processo de Criação de PRs
+
+### 1. Identificar Repositórios Modificados
+
+Para cada repositório no workspace, verifique:
+```bash
+cd <repositório>
+git status
+git log origin/main..HEAD  # Ver commits não pushados
+```
+
+### 2. Push das Branches
+
+Para cada repositório modificado:
+```bash
+cd <repositório>
+git push origin <branch-name>
+```
+
+### 3. Criar Pull Requests
+
+Para cada repositório, crie um PR usando o GitHub CLI ou interface web:
+
+**Usando GitHub CLI**:
+```bash
+cd <repositório>
+gh pr create --title "[ISSUE-ID] Título da Feature" \
+  --body "$(cat ../.sessions/<ISSUE-ID>/pr-description.md)" \
+  --base main
+```
+
+**Template de Descrição do PR**:
+
+```markdown
+## 🎯 Objetivo
+
+[Breve descrição do que esta PR faz]
+
+## 📝 Mudanças
+
+### Repositório: <nome-do-repo>
+
+- [Mudança 1]
+- [Mudança 2]
+- [Mudança 3]
+
+## 🔗 Relacionamentos
+
+- **Issue**: <ISSUE-ID>
+- **PRs Relacionados**: 
+  - <repo-1>#<PR-number>
+  - <repo-2>#<PR-number>
+
+## ✅ Checklist
+
+- [ ] Código implementado e testado
+- [ ] Testes unitários adicionados/atualizados
+- [ ] Testes de integração passando
+- [ ] Documentação atualizada
+- [ ] Sem breaking changes (ou documentados)
+- [ ] Revisado por pares (após criação do PR)
+
+## 🧪 Como Testar
+
+1. [Passo 1]
+2. [Passo 2]
+3. [Resultado esperado]
+
+## 📸 Screenshots/Demos
+
+[Se aplicável, adicione screenshots ou links para demos]
+
+## 🔍 Notas para Revisores
+
+- [Ponto de atenção 1]
+- [Ponto de atenção 2]
+```
+
+### 4. Vincular PRs
+
+Se houver múltiplos PRs (um por repositório):
+- Adicione links cruzados entre os PRs
+- Documente a ordem de merge recomendada
+- Indique dependências entre PRs
+
+### 5. Atualizar Issue no Task Manager
+
+Se task manager estiver configurado:
+- Mova a issue para "Em Revisão" ou "PR Aberto"
+- Adicione links dos PRs na issue
+- Adicione comentário com resumo das mudanças
+
+### 6. Documentação da Sessão
+
+Atualize `./.sessions/<ISSUE-ID>/pr.md`:
+
+```markdown
+# [Título da Feature] - Pull Requests
+
+## PRs Criados
+
+### <repo-1>
+- **Link**: <URL do PR>
+- **Status**: Aberto
+- **Commits**: X commits
+
+### <repo-2>
+- **Link**: <URL do PR>
+- **Status**: Aberto
+- **Commits**: Y commits
+
+## Ordem de Merge Recomendada
+
+1. <repo-1> - [Justificativa]
+2. <repo-2> - [Justificativa]
+
+## Notas para Merge
+
+- [Nota importante 1]
+- [Nota importante 2]
+```
+
+## 🔍 Checklist Final
+
+Antes de solicitar revisão:
+- [ ] Todos os PRs criados
+- [ ] Descrições completas e claras
+- [ ] PRs vinculados entre si
+- [ ] Issue atualizada no task manager
+- [ ] Testes passando em CI/CD
+- [ ] Documentação da sessão completa
+
+## 📢 Comunicação
+
+Notifique o time sobre os PRs:
+- Mencione revisores relevantes
+- Destaque mudanças críticas ou breaking changes
+- Indique urgência se aplicável
+
+---
+
+**Argumentos fornecidos**:
+
+```
+#$ARGUMENTS
+```
+
+---
+
+## 🎯 Próximos Passos
+
+1. Aguardar revisão dos PRs
+2. Responder comentários e fazer ajustes
+3. Após aprovação, fazer merge na ordem recomendada
+4. Executar `context-cli feature:end <ISSUE-ID>` para limpar o workspace