context-first-cli 1.8.2 → 2.0.0

package/dist/templates/commands/en/quality/observe.md

@@ -0,0 +1,168 @@
+# Decision Observability
+
+This command records important decisions made during development, creating an auditable log for explainability and traceability.
+
+## 🎯 Objective
+
+Create a structured record of technical and product decisions, ensuring:
+- **Explainability**: Why each decision was made
+- **Traceability**: Which sources (PRD, metaspecs, ADRs) supported the decision
+- **Audit**: Complete history of choices for future review
+- **Learning**: Documentation of trade-offs and alternatives considered
+
+**IMPORTANT**: This command does NOT generate new decisions. It only RECORDS decisions that have already been made during the development process.
+
+## 📋 Prerequisites
+
+- You have run at least one of the commands that generate decisions:
+  - `/spec` - generates PRD with product decisions
+  - `/plan` - generates plan.md with technical decisions
+  - `/work` - implementation generates decisions during development
+
+## 🔍 Observation Process
+
+### 1. Identify Relevant Decisions
+
+Analyze the session files (`./.sessions/<ISSUE-ID>/`) to identify decisions:
+
+**After `/spec`** - Product Decisions:
+- Read `./.sessions/<ISSUE-ID>/prd.md`
+- Identify decisions in:
+  - Scope (what is included/excluded in the feature)
+  - Personas served (who is the target audience)
+  - Success metrics (how to measure results)
+  - Non-functional requirements (performance, accessibility)
+  - Constraints and trade-offs
+
+**After `/plan`** - Technical Decisions:
+- Read `./.sessions/<ISSUE-ID>/plan.md`
+- Identify decisions in:
+  - Component/module architecture
+  - Choice of libraries or tools
+  - Implementation patterns
+  - Data structure
+  - Testing strategy
+
+**During `/work`** - Implementation Decisions:
+- Read `./.sessions/<ISSUE-ID>/work.md`
+- Identify decisions in:
+  - Refactorings performed
+  - Changes in approach
+  - Optimizations applied
+  - Handling of edge cases
+
+### 2. Document Each Decision
+
+For each identified decision, document:
+
+```markdown
+## Decision: [Clear Title]
+
+**Context**: [Why do we need to decide this? What is the problem or need?]
+
+**Options Considered**:
+1. **Option A**: [Description]
+   - Pros: [advantages]
+   - Cons: [disadvantages]
+2. **Option B**: [Description]
+   - Pros: [advantages]
+   - Cons: [disadvantages]
+
+**Decision**: [Chosen option]
+
+**Justification**: [Why did we choose this option? Which criteria were most important?]
+
+**Sources**:
+- [PRD section X]
+- [Metaspec Y]
+- [ADR-00Z]
+
+**Accepted Trade-offs**: [Which disadvantages did we consciously accept?]
+
+**Reversibility**: Easy / Medium / Hard
+
+**Date**: [decision date]
+```
+
+### 3. Create Decision Log
+
+Save in `./.sessions/<ISSUE-ID>/decisions.md`:
+
+```markdown
+# Decision Log - [ISSUE-ID]
+
+## Summary
+[Brief summary of the main decisions made in this feature]
+
+## Product Decisions
+
+### [Decision 1]
+[As per template above]
+
+### [Decision 2]
+[As per template above]
+
+## Technical Decisions
+
+### [Decision 3]
+[As per template above]
+
+### [Decision 4]
+[As per template above]
+
+## Implementation Decisions
+
+### [Decision 5]
+[As per template above]
+
+## Lessons Learned
+- [Lesson 1]
+- [Lesson 2]
+
+## Pending Decisions
+- [Decision that still needs to be made]
+```
+
+## 📊 Impact Analysis
+
+For critical decisions, document the impact:
+
+```markdown
+## Impact Analysis
+
+**Affected Repositories**: [list]
+
+**Impacted Components**: [list]
+
+**Created Dependencies**: [list]
+
+**Introduced Risks**: [list]
+
+**Applied Mitigations**: [list]
+```
+
+## 🔄 Decision Review
+
+Periodically review the decisions made:
+- Do they still make sense?
+- Were the trade-offs proven correct?
+- Are there learnings to document?
+- Does any decision need to be reversed?
+
+---
+
+**Provided arguments**:
+
+```
+#$ARGUMENTS
+```
+
+---
+
+## 🎯 Outcome
+
+After running this command, you will have:
+- Complete decision log in `./.sessions/<ISSUE-ID>/decisions.md`
+- Traceability of every choice made
+- Documentation for future reference
+- Basis for ADRs (if decisions are architectural)

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

@@ -0,0 +1,78 @@
+# Warm-up - Context Loading
+
+This command prepares the environment by loading the complete context of the project and current workspace.
+
+## 1. Identify Current Workspace
+
+Check if you are inside a workspace created by `context-cli`:
+
+```bash
+# Check if you're in a workspace directory
+pwd
+# The workspace is usually at ~/workspaces/<ISSUE-ID>/
+```
+
+If you're not in a workspace, ask the user which workspace to use or if you should create a new one with `feature:start`.
+
+## 2. Load Project Configuration
+
+Identify the project's orchestrator:
+
+1. **Look for the `.contextrc.json` file** in any of the workspace repositories
+2. This file contains the orchestrator repository URL
+3. If the orchestrator is not cloned locally yet, clone it
+
+## 3. Load Project Manifest
+
+Read the `context-manifest.json` from the orchestrator to understand:
+- Complete list of ecosystem repositories
+- MetaSpecs repository URL
+- Dependencies between repositories
+- Role of each repository (application, library, service, specs-provider)
+
+## 4. Load MetaSpecs
+
+The MetaSpecs repository is defined in `context-manifest.json` (usually with `role: "specs-provider"`).
+
+**Always read the index files first:**
+
+1. **`README.md`** - Project overview and documentation structure
+2. **`index.md`** (in root or subfolders) - Index of available specifications
+
+**Use the indexes as reference** to navigate to the specific specifications you need. Don't assume specific files exist - always consult the indexes first.
+
+## 5. Load Current Session (if exists)
+
+Check if there's a saved session for this workspace:
+
+```bash
+# Look for session in orchestrator
+ls -la .sessions/<ISSUE-ID>/ 2>/dev/null
+```
+
+If it exists, read the session files to recover the context from the last execution.
+
+## 6. Repository Context
+
+For each repository present in the workspace, read:
+- `README.md` - Repository purpose and overview
+- Main configuration file (`package.json`, `pom.xml`, `requirements.txt`, etc.)
+
+## 7. Smart Navigation
+
+- **Code**: Use search tools (glob, grep) to locate relevant files
+- **Documentation**: Use MetaSpecs indexes as reference
+- **Wait for Instructions**: DO NOT read other files now. Wait for the next command.
+
+## 8. Jidoka Principle (Stop When Detecting Problems)
+
+If you detect misalignment, conflicts, or problems:
+1. 🛑 **STOP** immediately
+2. 📝 **DOCUMENT** the problem found
+3. 💬 **ALERT** the user before proceeding
+
+---
+
+**Provided arguments**: #$ARGUMENTS
+
+**Status**: Context loaded. Waiting for next command.

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

@@ -0,0 +1,297 @@
+# Planificación Técnica
+
+Este comando crea el plan técnico detallado para la implementación de la feature.
+
+## 📋 Prerrequisitos
+
+- PRD creado vía `/spec`
+- Análisis inicial hecho vía `/start`
+- Archivos `context.md` y `architecture.md` creados y aprobados
+
+## 📍 IMPORTANTE: Entienda la Estructura
+
+**Workspace**:
+```
+<orchestrator>/.sessions/<ISSUE-ID>/
+├── repo-1/          # worktree (será usado no /work)
+├── repo-2/          # worktree (será usado no /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 (read-only)
+- ❌ 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 - será actualizado durante `/work`)
+- ❌ **NO modificar `context.md` o `architecture.md`**
+
+## 📚 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 para garantizar 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 Feature]
+
+## Resumen
+[Breve descripción técnica de lo que se implementará]
+
+## Repositorios Involucrados
+- **<repo-1>**: [Papel en esta feature]
+- **<repo-2>**: [Papel en esta feature]
+
+## Enfoque Técnico
+[Estrategia general de implementación]
+```
+
+### 2. Arquitectura de la Solución
+
+```markdown
+## Arquitectura
+
+### Diagrama de Componentes
+[Descripción textual o ASCII art 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 hay]
+```
+
+### 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 arriba]
+```
+
+### 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 arriba]
+
+### Fase 3: [Nombre de la Fase]
+[Mismo formato arriba]
+```
+
+### 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 arriba]
+```
+
+### 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
+- Estimaciones son realistas
+- Riesgos fueron considerados
+- Estrategia de pruebas es adecuada
+
+---
+
+**Argumentos proporcionados**:
+
+```
+#$ARGUMENTS
+```
+
+---
+
+## 🎯 Próximo Paso
+
+Tras la aprobación del plan:
+
+```bash
+/work
+```
+
+Este comando iniciará la ejecución de la primera unidad de trabajo del plan.

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

@@ -0,0 +1,167 @@
+# Creación de Pull Request
+
+Este comando crea Pull Requests para todos los repositorios modificados en el workspace.
+
+## 📋 Requisitos previos
+
+Antes de crear PRs, asegúrate de que:
+- Has ejecutado `/pre-pr` y todas las validaciones pasaron
+- Todos los commits fueron realizados
+- Todas las pruebas están pasando
+- La documentación está actualizada
+
+## 🎯 Proceso de Creación de PRs
+
+### 1. Identificar Repositorios Modificados
+
+Para cada repositorio en el workspace, verifica:
+```bash
+cd <repositório>
+git status
+git log origin/main..HEAD  # Ver commits no pushados
+```
+
+### 2. Push de las Branches
+
+Para cada repositorio modificado:
+```bash
+cd <repositório>
+git push origin <branch-name>
+```
+
+### 3. Crear Pull Requests
+
+Para cada repositorio, crea un PR usando el GitHub CLI o la interfaz web:
+
+**Usando GitHub CLI**:
+```bash
+cd <repositório>
+gh pr create --title "[ISSUE-ID] Título de la Feature" \
+  --body "$(cat ../.sessions/<ISSUE-ID>/pr-description.md)" \
+  --base main
+```
+
+**Plantilla de Descripción del PR**:
+
+```markdown
+## 🎯 Objetivo
+
+[Breve descripción de lo que hace este PR]
+
+## 📝 Cambios
+
+### Repositorio: <nome-do-repo>
+
+- [Cambio 1]
+- [Cambio 2]
+- [Cambio 3]
+
+## 🔗 Relaciones
+
+- **Issue**: <ISSUE-ID>
+- **PRs Relacionados**: 
+  - <repo-1>#<PR-number>
+  - <repo-2>#<PR-number>
+
+## ✅ Checklist
+
+- [ ] Código implementado y probado
+- [ ] Pruebas unitarias añadidas/actualizadas
+- [ ] Pruebas de integración pasando
+- [ ] Documentación actualizada
+- [ ] Sin breaking changes (o documentados)
+- [ ] Revisado por pares (después de crear el PR)
+
+## 🧪 Cómo Testear
+
+1. [Paso 1]
+2. [Paso 2]
+3. [Resultado esperado]
+
+## 📸 Screenshots/Demos
+
+[Si aplica, añade capturas de pantalla o enlaces a demos]
+
+## 🔍 Notas para Revisores
+
+- [Punto de atención 1]
+- [Punto de atención 2]
+```
+
+### 4. Vincular PRs
+
+Si hay múltiples PRs (uno por repositorio):
+- Añade enlaces cruzados entre los PRs
+- Documenta el orden de merge recomendado
+- Indica dependencias entre PRs
+
+### 5. Actualizar Issue en el Task Manager
+
+Si el task manager está configurado:
+- Mueve la issue a "En Revisión" o "PR Abierto"
+- Añade enlaces de los PRs en la issue
+- Añade comentario con resumen de los cambios
+
+### 6. Documentación de la Sesión
+
+Actualiza `./.sessions/<ISSUE-ID>/pr.md`:
+
+```markdown
+# [Título de la Feature] - Pull Requests
+
+## PRs Creados
+
+### <repo-1>
+- **Link**: <URL del PR>
+- **Estado**: Abierto
+- **Commits**: X commits
+
+### <repo-2>
+- **Link**: <URL del PR>
+- **Estado**: Abierto
+- **Commits**: Y commits
+
+## Orden de Merge Recomendado
+
+1. <repo-1> - [Justificación]
+2. <repo-2> - [Justificación]
+
+## Notas para Merge
+
+- [Nota importante 1]
+- [Nota importante 2]
+```
+
+## 🔍 Checklist Final
+
+Antes de solicitar revisión:
+- [ ] Todos los PRs creados
+- [ ] Descripciones completas y claras
+- [ ] PRs vinculados entre sí
+- [ ] Issue actualizada en el task manager
+- [ ] Pruebas pasando en CI/CD
+- [ ] Documentación de la sesión completa
+
+## 📢 Comunicación
+
+Notifica al equipo sobre los PRs:
+- Menciona revisores relevantes
+- Destaca cambios críticos o breaking changes
+- Indica urgencia si aplica
+
+---
+
+**Argumentos proporcionados**:
+
+```
+#$ARGUMENTS
+```
+
+---
+
+## 🎯 Próximos Pasos
+
+1. Esperar revisión de los PRs
+2. Responder comentarios y hacer ajustes
+3. Tras la aprobación, hacer merge en el orden recomendado
+4. Ejecutar `context-cli feature:end <ISSUE-ID>` para limpiar el workspace