@thatix.io/context-first-agents-cli 0.1.1 → 0.2.1

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

@@ -0,0 +1,205 @@
+# 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.
+
+## 📋 Configuración del Proyecto
+
+**⚠️ IMPORTANTE: ¡Siempre lea los archivos de configuración del proyecto ANTES de ejecutar este comando!**
+
+### Archivos Obligatorios
+
+1. **`context-manifest.json`** (raíz del orchestrator)
+   - Lista de repositorios del proyecto
+   - Roles de cada repositorio (metaspecs, application, etc.)
+   - URLs y dependencias entre repositorios
+
+2. **`ai.properties.md`** (raíz del orchestrator)
+   - Configuraciones del proyecto (`project_name`, `base_path`)
+   - Sistema de gestión de tareas (`task_management_system`)
+   - Credenciales y configuraciones específicas
+
+### Cómo Leer
+
+```bash
+# 1. Leer context-manifest.json
+cat context-manifest.json
+
+# 2. Leer ai.properties.md
+cat ai.properties.md
+```
+
+### Información Esencial
+
+Después de leer los archivos, tendrás:
+- ✅ Lista completa de repositorios del proyecto
+- ✅ Ubicación del repositorio de metaspecs
+- ✅ Base path para localizar repositorios
+- ✅ Sistema de gestión de tareas configurado
+- ✅ Configuraciones específicas del proyecto
+
+**🛑 NO continúe sin leer estos archivos!** Contienen información crítica para la correcta ejecución del comando.
+
+## 📋 Pre-requisitos
+
+- 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 funcionalidad)
+  - 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 pruebas
+
+**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 funcionalidad]
+
+## 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ás:
+- 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,83 @@
+# Calentamiento — Carga de Contexto (índices para RAG)
+
+Prepara el entorno cargando los **índices de las specs** en un mapa de contexto navegable.
+El objetivo NO es volcar las specs en el contexto, sino cargar los **índices** para que los
+comandos siguientes sepan **dónde buscar** cada información, bajo demanda.
+
+**Argumentos**: `#$ARGUMENTS`
+
+---
+
+## 1. Cargar configuración
+
+Lee del orquestador:
+- **`context-manifest.json`** — `repositories[]` (id, role, hints), y el bloque
+  `orchestration` (especialmente `indexes`).
+- **`ai.properties.md`** — `base_path`, `task_management_system`.
+
+Localiza el repo de specs: el de `role: "metaspecs"` (o `"specs-provider"`).
+
+## 2. Descubrir los índices (dinámico — no exige ningún archivo fijo)
+
+Arma la lista de índices a cargar, en este orden de prioridad, **saltando lo que no exista**:
+
+1. Todas las rutas en `orchestration.indexes` del manifiesto (si están definidas).
+2. Si no hay ninguna, o para complementar, **descubre** los índices en el repo de specs:
+   - busca `index.md` / `INDEX.md` bajo `{base_path}/{metaspecs-id}/specs/` y subcarpetas
+     (ej.: `specs/index.md`, `specs/technical/index.md`, `specs/business/index.md`,
+     `specs/business/features/index.md`).
+3. Incluye también, **si existen**, los archivos de `context[]` de cada repositorio del manifiesto.
+
+> Degrada con gracia: si un índice esperado no existe, **sólo regístralo y continúa**.
+> Nunca falles el calentamiento por la ausencia de un archivo específico.
+
+## 3. Construir el Mapa de Contexto (el producto del calentamiento)
+
+Lee SÓLO los índices descubiertos (no los documentos que apuntan). A partir de ellos,
+arma y presenta un **mapa de RAG** — la "tabla de ruteo" del proyecto:
+
+```
+## Mapa de Contexto (RAG)
+
+### Índices cargados
+- specs/index.md            → raíz de navegación
+- specs/technical/index.md  → arquitectura, API, ADRs, convenciones
+- specs/business/index.md   → personas, journey, estrategia
+- ...(sólo los que existen)
+
+### Dónde buscar bajo demanda
+| Necesidad                     | Consultar (vía índice)               |
+|-------------------------------|--------------------------------------|
+| Arquitectura / decisiones     | technical/index.md → ARCHITECTURE / ADRs |
+| Contrato de API               | technical/index.md → API_SPECIFICATION   |
+| Reglas de negocio / feature   | business/index.md → features/...     |
+| Convenciones de código        | technical/index.md → guía de código  |
+
+### Repositorios (del manifiesto)
+- <repo-id> [role] — hints: ...
+```
+
+Si un índice referencia documentos que no existen en disco, márcalos como
+`(referenciado, ausente)` — eso indica una spec incompleta, no un error del calentamiento.
+
+## 4. Verificar repositorios y sesión
+
+- Para cada repo del manifiesto, confirma que existe en `{base_path}/{repo-id}/`
+  (no leas README ni código ahora — eso es bajo demanda).
+- Si se pasó un ISSUE-ID, verifica `.sessions/<ISSUE-ID>/`.
+
+## 5. Cómo los comandos siguientes usan esto
+
+Comandos como `/spec`, `/orchestrate` y los agentes NO deben escanear el repo a ciegas.
+Deben: consultar el Mapa de Contexto → abrir el índice relevante → seguir el link al
+documento específico. El índice es lo que optimiza el RAG: cargar poco, navegar con precisión.
+
+## 6. Principio Jidoka
+
+Si detectas un problema estructural (ningún índice encontrado, specs-provider ausente):
+**DETENTE**, describe qué falta y sugiere cómo corregirlo (ej.: crear `specs/index.md` o
+completar `orchestration.indexes`). No inventes contexto.
+
+---
+
+**Estado**: Índices cargados y Mapa de Contexto armado. Esperando el próximo comando.

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

@@ -0,0 +1,335 @@
+# 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
+
+## 📋 Configuração do Projeto
+
+**⚠️ IMPORTANTE: Sempre leia os arquivos de configuração do projeto ANTES de executar este comando!**
+
+### Arquivos Obrigatórios
+
+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
+
+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
+```
+
+### 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.
+
+
+## 📍 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.