@thatix.io/context-first-agents-cli 0.1.0 → 0.2.0

package/dist/templates/commands/en/warm-up.md

@@ -0,0 +1,59 @@
+# Warm-up - Context Loading
+
+Prepares the environment by loading optimized project context.
+
+## 1. Load Configuration
+
+Read the orchestrator files:
+- **`context-manifest.json`** - Repositories and roles
+- **`ai.properties.md`** - base_path, task_management_system
+
+## 2. Load Compact Context (OPTIMIZED)
+
+**IMPORTANT**: Use PROGRESSIVE loading to save context window.
+
+### Required (warm-up)
+
+Locate metaspecs via `context-manifest.json` (role: "specs-provider"):
+
+```
+{base_path}/{metaspecs-id}/specs/_meta/WARM_UP_CONTEXT.md  (~100 lines)
+```
+
+This file contains ALL essentials:
+- Technology stack
+- Context hierarchy
+- 5 critical rules
+- Minimal code patterns
+- On-demand loading table
+
+### On Demand (DO NOT load during warm-up)
+
+| Need | Document |
+|------|----------|
+| Generate code | `CLAUDE.meta.md` |
+| Architecture | `ARCHITECTURE.md` |
+| Specific feature | `features/{FEATURE}.md` |
+| Complete anti-patterns | `ANTI_PATTERNS.md` |
+
+## 3. Verify Repositories
+
+For each repository in `context-manifest.json`:
+- Verify existence at `{base_path}/{repo-id}/`
+- **DO NOT** read README.md now (on demand)
+
+## 4. Verify Session (if exists)
+
+```bash
+ls -la .sessions/<ISSUE-ID>/ 2>/dev/null
+```
+
+## 5. Jidoka Principle
+
+If problems detected: **STOP**, document, alert the user.
+
+---
+
+**Arguments**: #$ARGUMENTS
+
+**Status**: Context loaded. Awaiting next command.

package/dist/templates/commands/es/agents/CONTEXT-CONTRACT.md

@@ -0,0 +1,63 @@
+# Contrato de Contexto (forma)
+
+Todo agente efímero se spawnea con un contrato. Este es exactamente el objeto que el
+Orquestador compila por nodo y pega en el prompt del subagente. Es lo que mantiene el
+contexto de cada agente **pequeño, acotado y auditable** — el núcleo de la arquitectura.
+
+```json
+{
+  "agentId": "agent-w001",
+  "archetype": "implementer",
+  "objective": "<objetivo específico y acotado de este worker>",
+  "repository": "<repo-id o null para workers de sesión>",
+  "read": [
+    { "type": "index", "path": "../metaspecs/specs/index.md", "reason": "router de contexto" },
+    { "type": "hint",  "path": "../metaspecs/specs/technical/API_SPECIFICATION.md", "reason": "hint del repo" }
+  ],
+  "mayDiscover": [
+    "referencias alcanzables desde los índices de arriba",
+    "archivos de este repositorio necesarios para el objetivo"
+  ],
+  "mustNotAssume": [
+    "reglas de negocio no dichas",
+    "contratos externos no indexados",
+    "requisitos ausentes en la spec aprobada"
+  ],
+  "writeBoundary": ["worktree asignado del <repo-id>"],
+  "limits": { "policy": "select-do-not-dump", "maxFiles": 20 },
+  "return": ["summary", "changes", "evidence", "tests", "unresolved", "confidence"]
+}
+```
+
+## Reglas que el Orquestador debe garantizar al compilar un contrato
+
+- `read` incluye TODOS los `orchestration.indexes` más el `context[]` del repo — pero sólo
+  rutas que realmente existen en disco. Descarta el resto silenciosamente.
+- Workers de sesión (integrator, tester, reviewer) tienen `repository: null` y
+  `writeBoundary: ["sólo artefactos de la sesión"]`.
+- Nunca expandas `read` a "el repo entero". El descubrimiento está permitido
+  (`mayDiscover`), pero parte de los índices, no de un volcado ciego de directorio.
+- El contrato es el ÚNICO contexto de proyecto que recibe un subagente además del objetivo.
+  No pegues la conversación entera en los subagentes.
+
+## La forma de retorno que todo agente debe producir
+
+```markdown
+### summary
+<un párrafo: qué se hizo>
+
+### changes
+<archivos creados/modificados, por repo>
+
+### evidence
+<comandos corridos, salidas, links>
+
+### tests
+<tests agregados/corridos y su resultado>
+
+### unresolved
+<preguntas, conflictos de spec, stops Jidoka — o "ninguno">
+
+### confidence
+<low | medium | high> + una línea de por qué
+```

package/dist/templates/commands/es/agents/implementer.md

@@ -0,0 +1,27 @@
+# Arquetipo: implementer
+
+Eres un **implementer efímero** para exactamente un repositorio. Serás descartado al
+retornar. La experiencia de dominio viene de tu contrato de contexto, no de una persona.
+
+## Recibes
+- `objective`: el objetivo acotado.
+- `repository`: el id del repo y la ruta del worktree.
+- Un **contrato de contexto** (alcance de lectura, writeBoundary, mustNotAssume, limits, return).
+
+## Haz
+1. Lee SÓLO lo que el `read` del contrato permite; descubre más allá SÓLO desde esos
+   índices/archivos del repo (`mayDiscover`). Respeta `limits.maxFiles`.
+2. Implementa el objetivo dentro de tu `writeBoundary` (el worktree de tu repo). Sigue los
+   patrones que encuentres en el repo y en las specs normativas. No introduzcas stack no
+   documentada en las specs sin señalarlo en `unresolved`.
+3. Agrega/ajusta tests según las convenciones del repo.
+4. Commit atómico dentro del worktree (`feat|fix|refactor|test|docs|chore: … Refs: <ISSUE-ID>`).
+
+## Nunca
+- Leer o modificar otros repositorios.
+- Modificar specs normativas.
+- Asumir algo en `mustNotAssume` — si lo necesitas, detente y ponlo en `unresolved`.
+
+## Retorno (exactamente esta forma)
+summary / changes / evidence / tests / unresolved / confidence
+(ver CONTEXT-CONTRACT.md)

package/dist/templates/commands/es/agents/integrator.md

@@ -0,0 +1,24 @@
+# Arquetipo: integrator
+
+Eres un **integrator efímero**. Corres después de los implementers por repo y verificas
+que sus cambios encajen. Eres de sesión: `repository: null`,
+`writeBoundary: sólo artefactos de la sesión`.
+
+## Recibes
+- Los retornos de todos los implementers (resúmenes y changes por repo).
+- Las secciones de la spec que describen contratos cross-repo (APIs, eventos, tipos, design tokens).
+- Un **contrato de contexto**.
+
+## Haz
+1. Reconstruye el contrato entre los repos que cambiaron (ej.: endpoint del backend ↔
+   consumidor en el frontend, productor ↔ consumidor de un evento, componente compartido ↔
+   sus usos).
+2. Verifica que ambos lados concuerden: nombres/tipos de campos, status codes, forma de
+   error, versiones, nulabilidad, unidades. Señala cada divergencia con precisión (qué lado,
+   qué campo).
+3. Verifica dependencias de orden/deploy (¿un repo debe salir antes que otro?).
+4. NO reimplementes — si hallas divergencia, describe la corrección exacta y de quién es el repo.
+
+## Retorno
+summary / changes(=hallazgos de integración) / evidence / tests(=checks de integración a correr) /
+unresolved / confidence. Marca **CONSISTENT** o **MISMATCH**.

package/dist/templates/commands/es/agents/reviewer.md

@@ -0,0 +1,31 @@
+# Arquetipo: reviewer
+
+Eres un **reviewer efímero**. Tu trabajo es encontrar lo que está mal, no elogiar.
+En tareas `complex` eres **adversarial**: asume que hay un defecto hasta probar lo contrario.
+
+## Recibes
+- `objective`: qué revisar y contra qué spec.
+- Los retornos de los implementers (summary/changes) y las secciones relevantes de la spec.
+- Un **contrato de contexto** limitando el alcance de lectura.
+
+## Foco (pesa por los riskSignals de la tarea)
+- Corrección vs. la **spec normativa** — no vs. tus suposiciones.
+- Reglas de negocio, casos borde e integridad de datos.
+- Seguridad, authz/authn, secretos, inyección, exposición de PII.
+- Migraciones: reversibilidad, backfill, downtime, orden.
+- Contratos cross-repo: ¿el cambio honra la API/interfaz que ambos lados esperan?
+- Premisas ocultas del implementer que no están en la spec.
+
+## Método
+1. Lee los archivos cambiados y las secciones de la spec que los gobiernan.
+2. Para cada hallazgo: indica archivo/línea, por qué está mal y la corrección concreta.
+3. Clasifica cada hallazgo: `blocking` | `should-fix` | `nit`.
+4. Intenta refutar tus propios hallazgos antes de reportar — descarta los que no sostengas.
+
+## Nunca
+- Aprobar por cortesía. Si está correcto, dilo brevemente y sigue.
+- Modificar código (tú revisas; los implementers corrigen).
+
+## Retorno
+summary / changes(=lista de hallazgos) / evidence / tests(=qué testearías) / unresolved / confidence
+Marca claramente **PASS** o **BLOCKED** (cualquier hallazgo blocking ⇒ BLOCKED).

package/dist/templates/commands/es/agents/tester.md

@@ -0,0 +1,22 @@
+# Arquetipo: tester
+
+Eres un **tester efímero**. Validas criterios de aceptación y riesgo de regresión usando
+los comandos del propio proyecto. De sesión: `repository: null`.
+
+## Recibes
+- Los criterios de aceptación del objetivo (de la spec).
+- La lista de repos impactados y el `testCommand` de cada uno (del manifiesto).
+- Un **contrato de contexto**.
+
+## Haz
+1. Para cada repo impactado, corre el `testCommand` dentro del worktree. Si no hay, usa el
+   enfoque de test documentado en el proyecto y di qué asumiste.
+2. Mapea cada criterio de aceptación a un check concreto (test existente, test nuevo o
+   evidencia manual). Anota cualquier criterio que no pudiste verificar.
+3. Reporta fallas con el comando exacto, la salida y el archivo/área implicada.
+4. NO corrijas código — reporta para que un implementer corrija.
+
+## Retorno
+summary / changes(=ninguno, o tests nuevos) / evidence(=comandos + salidas) /
+tests(=pass/fail por repo + cobertura de criterios) / unresolved / confidence.
+Marca **GREEN** (todo pasa, criterios cubiertos) o **RED** (fallas / criterios sin cubrir).

package/dist/templates/commands/es/engineer/plan.md

@@ -0,0 +1,335 @@
+# Planificación Técnica
+
+Este comando crea el plan técnico detallado para la implementación de la funcionalidad.
+
+## 📋 Requisitos Previos
+
+- PRD creado vía `/spec`
+- Análisis inicial realizado vía `/start`
+- Archivos `context.md` y `architecture.md` creados y aprobados
+
+## 📋 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.
+
+
+## 📍 IMPORTANTE: Entienda la Estructura
+
+**Workspace**:
+```
+<orchestrator>/.sessions/<ISSUE-ID>/
+├── repo-1/          # worktree (se usará en /work)
+├── repo-2/          # worktree (se usará en /work)
+├── context.md       # contexto (inmutable - LEER)
+├── architecture.md  # arquitectura (inmutable - LEER)
+└── plan.md          # plan (mutable - CREAR)
+```
+
+**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 `context.md` y `architecture.md` (inmutables)
+- ✅ Cree `plan.md` en `.sessions/<ISSUE-ID>/`
+- ✅ Lea código de los repositorios principales (solo lectura)
+- ❌ NUNCA haga checkout en los repositorios principales
+- ❌ NUNCA modifique `context.md` o `architecture.md`
+
+## ⚠️ IMPORTANTE: Archivos Inmutables
+
+**Este comando debe LEER pero NO MODIFICAR:**
+- ✅ **LEER** `.sessions/<ISSUE-ID>/context.md` (inmutable)
+- ✅ **LEER** `.sessions/<ISSUE-ID>/architecture.md` (inmutable)
+- ✅ **CREAR** `.sessions/<ISSUE-ID>/plan.md` (mutable - se actualizará durante `/work`)
+- ❌ **NO modificar `context.md` o `architecture.md`**
+
+## 📚 Cargar MetaSpecs
+
+**Localizar MetaSpecs automáticamente**:
+1. Lea `context-manifest.json` del orquestador
+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 para asegurar conformidad con:
+   - Arquitectura del sistema
+   - Patrones de diseño y código
+   - Estructura de carpetas y archivos
+   - Convenciones de nomenclatura
+
+## 🎯 Objetivo
+
+Crear un plan técnico detallado que guiará la implementación, dividiendo el trabajo en unidades más pequeñas y secuenciales.
+
+## 📝 Estructura del Plan
+
+### 1. Visión General Técnica
+
+```markdown
+# Plan Técnico - [Título de la Funcionalidad]
+
+## Resumen
+[Breve descripción técnica de lo que se implementará]
+
+## Repositorios Involucrados
+- **<repo-1>**: [Rol en esta funcionalidad]
+- **<repo-2>**: [Rol en esta funcionalidad]
+
+## Enfoque Técnico
+[Estrategia general de implementación]
+```
+
+### 2. Arquitectura de la Solución
+
+```markdown
+## Arquitectura
+
+### Diagrama de Componentes
+[Descripción textual o arte ASCII de los componentes y sus relaciones]
+
+### Flujo de Datos
+1. [Paso 1 del flujo]
+2. [Paso 2 del flujo]
+3. [Paso 3 del flujo]
+
+### Integraciones
+- **<repo-1> → <repo-2>**: [Cómo se comunican]
+- **Sistema → API Externa**: [Si aplica]
+```
+
+### 3. Decisiones Técnicas
+
+```markdown
+## 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]
+
+### Decisión 2: [Título]
+[Mismo formato anterior]
+```
+
+### 4. Plan de Implementación
+
+Divida el trabajo en unidades pequeñas y secuenciales:
+
+```markdown
+## Plan de Implementación
+
+### Fase 1: [Nombre de la Fase]
+**Objetivo**: [Qué se logrará en esta fase]
+**Repositorios**: [repos afectados]
+
+#### Tarea 1.1: [Descripción]
+- **Repo**: <repo-1>
+- **Archivos**: [archivos a crear/modificar]
+- **Descripción**: [Qué hacer]
+- **Pruebas**: [Pruebas a implementar]
+- **Estimación**: [tiempo estimado]
+
+#### Tarea 1.2: [Descripción]
+- **Repo**: <repo-2>
+- **Archivos**: [archivos a crear/modificar]
+- **Descripción**: [Qué hacer]
+- **Pruebas**: [Pruebas a implementar]
+- **Estimación**: [tiempo estimado]
+
+### Fase 2: [Nombre de la Fase]
+[Mismo formato anterior]
+
+### Fase 3: [Nombre de la Fase]
+[Mismo formato anterior]
+```
+
+### 5. Estructura de Archivos
+
+Para cada repositorio, defina la estructura:
+
+```markdown
+## Estructura de Archivos
+
+### <repo-1>
+```
+src/
+├── components/
+│   ├── NewComponent.tsx (CREAR)
+│   └── ExistingComponent.tsx (MODIFICAR)
+├── services/
+│   └── NewService.ts (CREAR)
+└── tests/
+    └── NewComponent.test.tsx (CREAR)
+```
+
+### <repo-2>
+```
+src/
+├── controllers/
+│   └── NewController.ts (CREAR)
+└── tests/
+    └── NewController.test.ts (CREAR)
+```
+```
+
+### 6. APIs y Contratos
+
+```markdown
+## APIs y Contratos
+
+### Endpoints Nuevos
+
+#### POST /api/resource
+**Request**:
+```json
+{
+  "field1": "string",
+  "field2": "number"
+}
+```
+
+**Response**:
+```json
+{
+  "id": "string",
+  "status": "string"
+}
+```
+
+### Endpoints Modificados
+
+#### GET /api/resource/:id
+**Cambios**: [Qué cambia]
+**Breaking Change**: Sí / No
+```
+
+### 7. Estrategia de Pruebas
+
+```markdown
+## Estrategia de Pruebas
+
+### Pruebas Unitarias
+- **<repo-1>**: [Componentes/funciones a probar]
+- **<repo-2>**: [Componentes/funciones a probar]
+
+### Pruebas de Integración
+- **Escenario 1**: [Descripción y repos involucrados]
+- **Escenario 2**: [Descripción y repos involucrados]
+
+### Pruebas E2E (si aplica)
+- **Flujo 1**: [Descripción]
+- **Flujo 2**: [Descripción]
+```
+
+### 8. Riesgos Técnicos
+
+```markdown
+## Riesgos Técnicos
+
+### Riesgo 1: [Descripción]
+- **Impacto**: Alto / Medio / Bajo
+- **Probabilidad**: Alta / Media / Baja
+- **Mitigación**: [Cómo mitigar]
+- **Plan B**: [Alternativa si ocurre]
+
+### Riesgo 2: [Descripción]
+[Mismo formato anterior]
+```
+
+### 9. Checklist de Implementación
+
+```markdown
+## Checklist de Implementación
+
+### Fase 1
+- [ ] Tarea 1.1
+- [ ] Tarea 1.2
+- [ ] Pruebas de la Fase 1
+
+### Fase 2
+- [ ] Tarea 2.1
+- [ ] Tarea 2.2
+- [ ] Pruebas de la Fase 2
+
+### Fase 3
+- [ ] Tarea 3.1
+- [ ] Tarea 3.2
+- [ ] Pruebas de la Fase 3
+
+### Finalización
+- [ ] Documentación actualizada
+- [ ] Code review
+- [ ] Pruebas de integración
+- [ ] PR creado
+```
+
+## 📄 Guardado del Plan
+
+Guarde en `./.sessions/<ISSUE-ID>/plan.md`
+
+## 🔍 Revisión
+
+Revise el plan verificando:
+- Todas las tareas están claras y ejecutables
+- Dependencias entre tareas están identificadas
+- Las estimaciones son realistas
+- Los riesgos fueron considerados
+- La estrategia de pruebas es adecuada
+
+---
+
+**Argumentos proporcionados**:
+
+```
+#$ARGUMENTS
+```
+
+---
+
+## 🎯 Próximo Paso
+
+Después de la aprobación del plan:
+
+```bash
+/work
+```
+
+Este comando iniciará la ejecución de la primera unidad de trabajo del plan.