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

package/templates/commands/es/engineer/pre-pr.md

@@ -0,0 +1,359 @@
+# Preparación para Pull Request
+
+Este comando valida que todo está listo para crear Pull Requests.
+
+## 📋 Requisitos Previos
+
+- Implementación completa (todas las tareas del `/plan` ejecutadas)
+- Todos los commits realizados
+- Workspace limpio y organizado
+
+## 📋 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 orquestador)
+   - Lista de repositorios del proyecto
+   - Roles de cada repositorio (metaspecs, application, etc.)
+   - URLs y dependencias entre repositorios
+
+2. **`ai.properties.md`** (raíz del orquestador)
+   - 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!
+
+
+## 🎯 Objetivo
+
+Garantizar que la implementación está completa, probada y lista para revisión antes de crear los PRs.
+
+## 🛑 CRÍTICO: DÓNDE TRABAJAR
+
+**⚠️ ATENCIÓN: TODO CÓDIGO (tests, fixes, ajustes) DEBE SER CREADO DENTRO DEL WORKTREE!**
+
+**✅ CORRECTO** - Trabajar dentro del worktree:
+```
+<orchestrator>/.sessions/<ISSUE-ID>/<repo-name>/src/file.ts  ✅
+<orchestrator>/.sessions/<ISSUE-ID>/<repo-name>/tests/test.ts  ✅
+<orchestrator>/.sessions/<ISSUE-ID>/<repo-name>/.eslintrc.js  ✅
+```
+
+**❌ INCORRECTO** - NUNCA crear código fuera del worktree:
+```
+<orchestrator>/.sessions/test.ts  ❌
+<orchestrator>/.sessions/<ISSUE-ID>/test.ts  ❌
+{base_path}/<repo-name>/test.ts  ❌ (¡repositorio principal!)
+```
+
+**REGLA ABSOLUTA**:
+- 🛑 **TODO código** (tests, fixes, configuraciones) **DEBE estar en** `<orchestrator>/.sessions/<ISSUE-ID>/<repo-name>/`
+- 🛑 **NUNCA modifique** el repositorio principal en `{base_path}/<repo-name>/`
+- ✅ **Trabaje SOLO** dentro del worktree del repositorio específico
+
+## ✅ Checklist de Validación
+
+### 1. Completitud de la Implementación
+
+```markdown
+## Verificación de Completitud
+
+- [ ] Todas las tareas del plan fueron ejecutadas
+- [ ] Todos los requisitos funcionales del PRD fueron implementados
+- [ ] Todos los criterios de aceptación fueron cumplidos
+- [ ] Ninguna funcionalidad quedó incompleta
+```
+
+### 2. Calidad del Código
+
+Para cada repositorio modificado:
+
+```bash
+cd <repositorio>
+
+# Verificar estado
+git status
+
+# Verificar linting (ejemplos por stack):
+# Node.js: npm run lint / yarn lint / pnpm lint
+# Python: flake8 . / pylint src/ / black --check .
+# Java: mvn checkstyle:check / gradle check
+# Go: golangci-lint run / go vet ./...
+# Ruby: rubocop
+# Rust: cargo clippy
+# PHP: ./vendor/bin/phpcs
+# C#: dotnet format --verify-no-changes
+
+# Verificar formateo (ejemplos por stack):
+# Node.js: npm run format:check / prettier --check .
+# Python: black --check . / autopep8 --diff .
+# Java: mvn formatter:validate
+# Go: gofmt -l . / go fmt ./...
+# Ruby: rubocop --format-only
+# Rust: cargo fmt --check
+
+# Verificar build (ejemplos por stack):
+# Node.js: npm run build / yarn build
+# Python: python setup.py build
+# Java: mvn compile / gradle build
+# Go: go build ./...
+# Ruby: rake build
+# Rust: cargo build
+```
+
+Checklist:
+```markdown
+## Calidad del Código
+
+### <repo-1>
+- [ ] Linting sin errores
+- [ ] Formateo correcto
+- [ ] Build sin errores
+- [ ] Sin warnings críticos
+
+### <repo-2>
+- [ ] Linting sin errores
+- [ ] Formateo correcto
+- [ ] Build sin errores
+- [ ] Sin warnings críticos
+```
+
+### 3. Tests
+
+Para cada repositorio:
+
+```bash
+cd <repositorio>
+
+# Ejecutar tests unitarios (ejemplos por stack):
+# Node.js: npm run test:unit / jest / vitest
+# Python: pytest tests/unit / python -m unittest
+# Java: mvn test / gradle test
+# Go: go test ./... -short
+# Ruby: rspec spec/unit / rake test:unit
+# Rust: cargo test --lib
+# PHP: ./vendor/bin/phpunit --testsuite=unit
+# C#: dotnet test --filter Category=Unit
+
+# Ejecutar tests de integración (ejemplos por stack):
+# Node.js: npm run test:integration
+# Python: pytest tests/integration
+# Java: mvn verify / gradle integrationTest
+# Go: go test ./... -run Integration
+# Ruby: rspec spec/integration
+# Rust: cargo test --test '*'
+# PHP: ./vendor/bin/phpunit --testsuite=integration
+
+# Verificar cobertura (ejemplos 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/
+```
+
+Checklist:
+```markdown
+## Tests
+
+### <repo-1>
+- [ ] Todos los tests unitarios pasan
+- [ ] Todos los tests de integración pasan
+- [ ] Cobertura de tests adecuada (>= X%)
+- [ ] Nuevos tests añadidos para nuevas funcionalidades
+
+### <repo-2>
+- [ ] Todos los tests unitarios pasan
+- [ ] Todos los tests de integración pasan
+- [ ] Cobertura de tests adecuada (>= X%)
+- [ ] Nuevos tests añadidos para nuevas funcionalidades
+```
+
+### 4. Documentación
+
+```markdown
+## Documentación
+
+- [ ] README actualizado (si es necesario)
+- [ ] Comentarios de código adecuados
+- [ ] Documentación de APIs actualizada (si hubo cambios)
+- [ ] Changelog actualizado
+- [ ] Documentación técnica actualizada en las metaspecs (si aplica)
+```
+
+### 5. Commits
+
+```markdown
+## Commits
+
+- [ ] Todos los commits tienen mensajes claros y descriptivos
+- [ ] Los commits siguen el estándar del proyecto (conventional commits, etc.)
+- [ ] No hay commits con mensajes genéricos ("fix", "update", etc.)
+- [ ] Los commits están organizados lógicamente
+- [ ] No hay commits de debug o temporales
+```
+
+### 6. Sincronización
+
+```markdown
+## Sincronización
+
+- [ ] Las ramas están actualizadas con la rama base (main/develop)
+- [ ] No hay conflictos de merge
+- [ ] Cambios entre repositorios están sincronizados
+- [ ] Dependencias entre repos fueron probadas
+```
+
+### 7. Seguridad
+
+```markdown
+## Seguridad
+
+- [ ] No hay credenciales o secretos en el código
+- [ ] No hay datos sensibles en logs
+- [ ] Dependencias de seguridad fueron verificadas
+- [ ] No se introdujeron vulnerabilidades conocidas
+```
+
+### 8. Performance
+
+```markdown
+## Performance
+
+- [ ] No hay regresiones de performance evidentes
+- [ ] Queries/operaciones costosas fueron optimizadas
+- [ ] No se introdujeron memory leaks
+- [ ] Requisitos de performance del PRD fueron cumplidos
+```
+
+## 🔍 Validación Cruzada
+
+Si se modificaron múltiples repositorios:
+
+```markdown
+## Validación Cruzada
+
+- [ ] Probé la integración entre los repositorios localmente
+- [ ] APIs/contratos entre repos están consistentes
+- [ ] No hay breaking changes no documentados
+- [ ] El orden de deploy/merge está claro
+```
+
+## 📄 Preparación de la Descripción del PR
+
+Cree `./.sessions/<ISSUE-ID>/pr-description.md`:
+
+```markdown
+## 🎯 Objetivo
+[Breve descripción de lo que hace esta feature]
+
+## 📝 Cambios Principales
+- [Cambio 1]
+- [Cambio 2]
+- [Cambio 3]
+
+## 🔗 Links
+- **Issue**: [ISSUE-ID]
+- **PRD**: [link o ruta]
+- **Plan Técnico**: [link o ruta]
+
+## ✅ Checklist
+- [x] Código implementado y probado
+- [x] Tests unitarios añadidos/actualizados
+- [x] Tests de integración pasando
+- [x] Documentación actualizada
+- [x] Linting y formateo OK
+- [x] Build sin errores
+
+## 🧪 Cómo Probar
+1. [Paso 1]
+2. [Paso 2]
+3. [Resultado esperado]
+
+## 🔍 Notas para Revisores
+- [Punto de atención 1]
+- [Punto de atención 2]
+```
+
+## 🚨 Problemas Encontrados
+
+Si alguna validación falla:
+1. 🛑 **PARE** el proceso de creación de PR
+2. 📝 **DOCUMENTE** el problema
+3. 🔧 **CORRIJA** el problema
+4. 🔄 **EJECUTE** `/pre-pr` nuevamente
+
+## 📊 Reporte de Validación
+
+Cree `./.sessions/<ISSUE-ID>/pre-pr-report.md`:
+
+```markdown
+# Reporte de Validación Pre-PR
+
+**Fecha**: [fecha/hora]
+**Issue**: [ISSUE-ID]
+
+## Estado General
+✅ Listo para PR / ⚠️ Pendientes / ❌ Bloqueado
+
+## Repositorios Validados
+- **<repo-1>**: ✅ OK
+- **<repo-2>**: ✅ OK
+
+## Resumen de Tests
+- **Tests Unitarios**: X/X pasando
+- **Tests de Integración**: Y/Y pasando
+- **Cobertura**: Z%
+
+## Pendientes (si hay)
+- [Pendiente 1]
+- [Pendiente 2]
+
+## Próximos Pasos
+- [x] Todas las validaciones pasaron
+- [ ] Ejecutar `/pr` para crear Pull Requests
+```
+
+---
+
+**Argumentos proporcionados**:
+
+```
+#$ARGUMENTS
+```
+
+---
+
+## 🎯 Próximo Paso
+
+Si todas las validaciones pasaron:
+
+```bash
+/pr
+```
+
+Este comando creará los Pull Requests para todos los repositorios modificados.

package/templates/commands/es/engineer/start.md

@@ -0,0 +1,318 @@
+# Inicio del Desarrollo
+
+Este comando inicia el desarrollo de una funcionalidad en el workspace actual.
+
+## 📍 IMPORTANTE: Entienda la Estructura
+
+**Workspace** (donde trabajará):
+```
+<orchestrator>/.sessions/<ISSUE-ID>/
+├── repo-1/          # worktree con branch feature/<ISSUE-ID>
+├── repo-2/          # worktree con branch feature/<ISSUE-ID>
+├── context.md       # contexto (inmutable - creado por este comando)
+├── architecture.md  # arquitectura (inmutable - creado por este comando)
+└── plan.md          # plan (mutable - creado por /plan)
+```
+
+**Repositorios principales** (solo lectura):
+```
+{base_path}/repo-1/  # repo principal (branch main/master)
+{base_path}/repo-2/  # repo principal (branch main/master)
+```
+
+**REGLA DE ORO**:
+- ✅ Lea metaspecs y código de los repositorios principales (read-only)
+- ✅ Cree `context.md` y `architecture.md` en `.sessions/<ISSUE-ID>/`
+- ❌ NUNCA haga checkout en los repositorios principales
+- ❌ NUNCA modifique código en este comando (use `/work` después)
+
+## 📋 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á:
+- ✅ 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.
+
+## 📚 Cargar MetaSpecs
+
+**Localizar MetaSpecs automáticamente**:
+1. Lea `context-manifest.json` del orchestrator
+2. Encuentre el repositorio con `"role": "metaspecs"`
+3. Lea `ai.properties.md` para obtener el `base_path`
+4. El metaspecs está en: `{base_path}/{metaspecs-repo-id}/`
+5. Lea los archivos `index.md` relevantes:
+   - Contexto de negocio
+   - Stack, arquitectura y patrones técnicos
+   - Convenciones del proyecto
+   - ADRs (Architecture Decision Records)
+
+## 🎯 Contexto del Proyecto
+
+Antes de iniciar, cargue el contexto consultando:
+- `context-manifest.json` - Estructura de repositorios
+- MetaSpecs (ubicado arriba) - Arquitectura y patrones
+- `directorio del workspace` - Información del workspace actual
+
+## ⚙️ Configuración Inicial
+
+1. **Verificar Workspace**:
+   - Confirme que está en el workspace correcto (verifique `directorio del workspace`)
+   - Liste los repositorios disponibles en el workspace
+
+2. **Verificar Branches**:
+   - Para cada repositorio en el workspace, verifique la branch actual
+   - Confirme que todas las branches están sincronizadas
+
+3. **Cargar Especificación**:
+   - **Si el task manager está configurado**: Lea la issue usando el MCP apropiado
+   - **Si no**: Pida al usuario el archivo de especificación o descripción de la feature
+
+4. **Actualizar Estado** (si el task manager está configurado):
+   - Mueva la issue a "En Progreso"
+
+## 📋 Análisis y Entendimiento
+
+Analice la especificación y construya un entendimiento completo respondiendo:
+
+### Negocio
+- **¿Por qué** se está construyendo esto?
+- **¿Quién** se beneficia?
+- **¿Qué** métrica queremos impactar?
+
+### Funcional
+- **¿Cuál es el resultado esperado**? (comportamiento del usuario, output del sistema)
+- **¿Qué componentes** serán creados/modificados en cada repositorio?
+- **¿Qué integraciones** entre repositorios son necesarias?
+
+### Técnico
+- **¿Stack aprobada**? Verificar contra especificaciones técnicas
+- **¿Patrones arquitectónicos**? Verificar ADRs (si están disponibles)
+- **¿Dependencias nuevas**? Justificar y documentar
+- **¿Cómo probar**? (según patrones del proyecto)
+
+### Validación contra MetaSpecs
+
+Si metaspecs están disponibles, validar:
+- ¿Está alineado con estrategia y roadmap?
+- ¿Usa stack tecnológica aprobada?
+- ¿Respeta Architecture Decision Records?
+- ¿Sigue reglas de negocio documentadas?
+
+## 🤔 Preguntas de Aclaración
+
+Después del análisis inicial, formule **3-5 aclaraciones más importantes**:
+
+**Ejemplos de preguntas relevantes**:
+- ¿Qué repositorio debe contener la lógica principal?
+- ¿Cómo deben comunicarse los repositorios?
+- ¿Hay dependencias entre los cambios en los diferentes repos?
+- ¿Cuál es el orden de implementación recomendado?
+- ¿Hay impacto en APIs o contratos entre servicios?
+
+## 💾 Creación del Context.md
+
+**IMPORTANTE**: Este archivo es **INMUTABLE** tras la aprobación. No debe ser modificado por comandos subsecuentes.
+
+Cree el archivo `./.sessions/<ISSUE-ID>/context.md` con:
+
+```markdown
+# Context: [Nombre de la Feature]
+
+## Por Qué
+[Valor de negocio, persona atendida, métrica impactada]
+
+## Qué
+[Funcionalidades principales, comportamiento esperado]
+
+## Cómo
+[Enfoque técnico, componentes, repositorios afectados]
+
+## Validación contra MetaSpecs
+- [x] Alineado con estrategia de producto
+- [x] Atiende a la persona correcta
+- [x] Métrica impactada documentada
+- [x] Usa stack aprobada
+- [x] Respeta ADRs
+- [x] Sin conflictos con limitaciones conocidas
+
+## Dependencias
+[Bibliotecas, APIs, componentes existentes]
+
+## Restricciones
+[Limitaciones técnicas, objetivos de performance, presupuesto]
+
+## Pruebas
+[E2E críticos, pruebas unitarias necesarias, cobertura esperada]
+```
+
+**Después de crear `context.md`, solicite revisión y aprobación del usuario antes de continuar.**
+
+---
+
+## 🏗️ Creación del Architecture.md
+
+**IMPORTANTE**: Este archivo es **INMUTABLE** tras la aprobación. No debe ser modificado por comandos subsecuentes.
+
+### Principios Arquitectónicos (OBLIGATORIO)
+
+**ANTES de crear la arquitectura, DEBE:**
+
+1. **Leer ADRs (Architecture Decision Records)**:
+   - Liste ADRs en metaspecs
+   - Lea TODOS los ADRs relevantes para la feature
+   - Identifique restricciones y patrones obligatorios
+
+2. **Consultar patrones arquitectónicos**:
+   - Lea guías de estructura del proyecto en metaspecs
+   - Lea patrones de código en metaspecs
+   - Identifique patrones existentes en el código (use Glob/Grep para encontrar ejemplos similares)
+
+3. **Validar cumplimiento con ADRs**:
+   - Para cada ADR relevante, verifique si la solución propuesta respeta las decisiones
+   - Documente el cumplimiento en architecture.md
+   - Si hay violación, justifique o proponga corrección
+
+4. **Analizar código existente**:
+   - Use Glob/Grep para encontrar componentes/módulos similares
+   - Entienda patrones y estructuras existentes
+   - Alinee nueva implementación con patrones del proyecto
+
+### Estructura del Documento de Arquitectura
+
+Cree el archivo `./.sessions/<ISSUE-ID>/architecture.md` con:
+
+```markdown
+# Architecture: [Nombre de la Feature]
+
+## Visión General
+[Visión de alto nivel del sistema antes y después del cambio]
+
+## Componentes Afectados
+[Lista de componentes y sus relaciones, dependencias]
+
+### Diagrama de Componentes
+[Descripción textual o diagrama Mermaid de los componentes]
+
+### Flujo de Datos
+1. [Paso 1 del flujo]
+2. [Paso 2 del flujo]
+3. [Paso 3 del flujo]
+
+## Estructura de Directorios Propuesta
+[Basada en patrones del proyecto]
+
+```
+repo-1/
+├── src/
+│   ├── components/
+│   │   └── NewComponent.tsx (CREAR)
+│   └── services/
+│       └── NewService.ts (CREAR)
+```
+
+## Patrones y Mejores Prácticas
+[Patrones que serán mantenidos o introducidos]
+
+## Validación de ADRs
+[Lista de ADRs consultados y cumplimiento]
+
+- [x] ADR-001: [Nombre] - Cumple
+- [x] ADR-002: [Nombre] - Cumple
+
+## Dependencias Externas
+[Bibliotecas que serán usadas o añadidas]
+
+## Decisiones Técnicas
+
+### Decisión 1: [Título]
+**Contexto**: [Por qué necesitamos decidir esto]
+**Opciones consideradas**:
+- Opción A: [Pros y contras]
+- Opción B: [Pros y contras]
+**Decisión**: [Opción elegida]
+**Justificación**: [Por qué elegimos esta opción]
+
+## Restricciones y Suposiciones
+[Limitaciones técnicas y premisas]
+
+## Trade-offs
+[Alternativas consideradas y por qué no fueron elegidas]
+
+## Consecuencias
+**Positivas**:
+- [Beneficio 1]
+- [Beneficio 2]
+
+**Negativas**:
+- [Costo/limitación 1]
+- [Costo/limitación 2]
+
+## Archivos Principales
+[Lista de los principales archivos a editar/crear]
+
+- `repo-1/src/components/NewComponent.tsx` (CREAR)
+- `repo-1/src/services/NewService.ts` (CREAR)
+- `repo-2/src/controllers/NewController.ts` (CREAR)
+```
+
+**Después de crear `architecture.md`, solicite revisión y aprobación del usuario antes de continuar.**
+
+---
+
+**Argumentos proporcionados**:
+
+```
+#$ARGUMENTS
+```
+
+---
+
+## 🎯 Próximo Paso
+
+**Después de la aprobación del usuario de los archivos `context.md` y `architecture.md`**:
+
+```bash
+/plan
+```
+
+Este comando creará la planificación técnica detallada de la implementación.
+
+---
+
+## ⚠️ IMPORTANTE: Archivos Inmutables
+
+**`context.md` y `architecture.md` son INMUTABLES tras la aprobación.**
+
+- ✅ Pueden ser LEÍDOS por comandos subsecuentes (`/plan`, `/work`)
+- ❌ NO deben ser MODIFICADOS por ningún comando
+- ❌ Si hay necesidad de cambio, discútalo con el usuario y cree nuevos archivos o actualice la issue en el task manager