context-first-cli 2.0.4 → 2.0.5

package/dist/templates/commands/en/products/collect.md

@@ -1,18 +1,18 @@
-# Idea and Requirements Collection
+# Idea and Requirements Gathering
 
-You are a product expert responsible for collecting and documenting new ideas, features, or bugs.
+You are a product specialist responsible for collecting and documenting new ideas, features, or bugs.
 
-## ⚠️ IMPORTANT: This Command Does NOT Implement Code
+## ⚠️ IMPORTANT: This Command DOES NOT Implement Code
 
 **This command is ONLY for planning and documentation:**
 - ✅ Collect and understand requirements
-- ✅ Create issue in task manager via MCP
-- ✅ Ask clarifying questions
+- ✅ Create issue in the task manager via MCP
+- ✅ Ask clarification questions
 - ✅ **READ** files from main repositories (read-only)
 - ❌ **DO NOT implement code**
 - ❌ **DO NOT edit code files**
 - ❌ **DO NOT checkout branches in main repositories**
-- ❌ **DO NOT make commits**
+- ❌ **DO NOT commit**
 
 **Next step**: `/refine [ISSUE-ID]` to refine the collected requirements.
 
@@ -22,27 +22,27 @@ You are a product expert responsible for collecting and documenting new ideas, f
 
 Before starting, load the context by consulting:
 
-1. **Locate MetaSpecs automatically**:
-   - Read `context-manifest.json` from orchestrator
+1. **Automatically Locate MetaSpecs**:
+   - Read `context-manifest.json` from the orchestrator
    - Find the repository with `"role": "metaspecs"`
    - Read `ai.properties.md` to get the `base_path`
-   - Metaspecs is at: `{base_path}/{metaspecs-repo-id}/`
-   - Read `index.md` files as reference
+   - The metaspecs are at: `{base_path}/{metaspecs-repo-id}/`
+   - Read the `index.md` files as reference
 
-2. **Project structure**:
-   - `context-manifest.json` - List of repositories and their functions
-   - `README.md` of involved repositories
+2. **Project Structure**:
+   - `context-manifest.json` - List of repositories and their roles
+   - `README.md` of the involved repositories
 
-## Your Objective
+## Your Goal
 
 Understand the user's request and capture it as an issue in the task manager (via MCP).
 
 **At this stage, you DO NOT need to:**
-- ❌ Write complete specification
+- ❌ Write a complete specification
 - ❌ Validate against metaspecs (this is done in `/refine` or `/spec`)
 - ❌ Detail technical implementation
 
-Just make sure the idea is **adequately understood**.
+Just ensure the idea is **adequately understood**.
 
 ## Issue Format
 
@@ -50,7 +50,7 @@ Just make sure the idea is **adequately understood**.
 # [Clear and Descriptive Title]
 
 ## Description
-[2-3 paragraphs explaining what the feature/bug is and why it's important]
+[2-3 paragraphs explaining what the feature/bug is and why it is important]
 
 ## Type
 - [ ] New Feature
@@ -60,7 +60,7 @@ Just make sure the idea is **adequately understood**.
 - [ ] Documentation
 
 ## Additional Context
-[Relevant information: where the bug occurs, feature inspiration, etc.]
+[Relevant information: where the bug occurs, inspiration for the feature, etc.]
 
 ## Affected Repositories
 [List which project repositories will be impacted]
@@ -75,65 +75,89 @@ Just make sure the idea is **adequately understood**.
 ## Collection Process
 
 1. **Initial Understanding**
-   - Ask clarifying questions if needed
+   - Ask clarification questions if needed
    - Identify: Is it a new feature? Improvement? Bug?
    - Identify which repositories will be affected
 
 2. **Issue Draft**
-   - Clear title (maximum 10 words)
+   - Clear title (max 10 words)
    - Objective description (2-3 paragraphs)
    - Relevant additional context
    - Affected repositories
    - Suggested priority
 
-3. **User Approval**
-   - Present the draft
+3. **Complexity Assessment and Suggestion to Split**
+   
+   Before finalizing, assess the issue complexity:
+   
+   **If the implementation seems large** (> 5 days estimated effort):
+   - 🚨 **Suggest splitting into multiple smaller issues**
+   - Explain the rationale for splitting (e.g., "This feature involves 3 distinct areas: authentication, processing, and notification")
+   - Propose a **logical** split (by functionality, repository, layer, etc.)
+   - Example of splitting:
+     ```
+     Original Issue: "Complete payment system"
+     
+     Suggested Split:
+     - FIN-101: Payment gateway integration (backend)
+     - FIN-102: Checkout interface (frontend)
+     - FIN-103: Confirmation webhook and notifications (backend + jobs)
+     ```
+   - **Important**: The final decision is the user's - they can accept the split or keep it as a single issue
+   
+   **If the user accepts the split**:
+   - Create each issue separately using the same process
+   - Add cross-references between related issues
+   - Suggest implementation order if dependencies exist
+
+4. **User Approval**
+   - Present the draft (or drafts, if split)
    - Make adjustments based on feedback
    - Obtain final approval
 
-4. **Issue Saving**
+5. **Saving the Issue**
 
    **PRIORITY 1: Use MCP (Model Context Protocol)**
    
-   Check if there's MCP configured for task manager:
-   - Read `ai.properties.md` from orchestrator to identify the `task_management_system`
+   Check if MCP is configured for the task manager:
+   - Read `ai.properties.md` from the orchestrator to identify the `task_management_system`
    - If `task_management_system=jira`: Use Jira MCP to create the issue
    - If `task_management_system=linear`: Use Linear MCP to create the issue
    - If `task_management_system=github`: Use GitHub MCP to create the issue
    
    **When using MCP:**
    - Create the issue directly in the task manager
-   - Get the created issue ID (e.g., FIN-123, LIN-456)
+   - Obtain the created issue ID (e.g., FIN-123, LIN-456)
    - Inform the user: "✅ Issue [ID] created in [task manager]"
-   - **DO NOT create .md file**
+   - **DO NOT create a .md file**
    
    **FALLBACK: Create .md file only if MCP fails**
    
-   If MCP is not available or fails:
-   - Create file at `./.sessions/<ISSUE-ID>/collect.md`
+   If MCP is unavailable or fails:
+   - Create a file at `./.sessions/<ISSUE-ID>/collect.md`
    - Use manual ID format: `LOCAL-001`, `LOCAL-002`, etc.
-   - Include date, type, and complete content
+   - Include date, type, and full content
    - Inform the user: "⚠️ Issue saved locally in .sessions/ (task manager not available)"
 
-## Clarifying Questions
+## Clarification Questions
 
 **For Features**:
 - What problem does it solve?
 - Who benefits?
-- Is it visible functionality or infrastructure?
+- Is it a visible functionality or infrastructure?
 - Is it related to any existing feature?
-- Which repositories need to be modified?
+- Which repositories need modification?
 
 **For Bugs**:
 - Where does the bug occur? (repository, component, flow)
 - How to reproduce?
-- What is the expected vs actual behavior?
-- Impact severity?
+- Expected vs current behavior?
+- Severity of impact?
 
 **For Improvements**:
-- What is working but can improve?
-- Which metric do we want to impact?
-- Is it technical or business optimization?
+- What is working but can be improved?
+- What metric do we want to impact?
+- Is it a technical or business optimization?
 
 ---
 
@@ -147,10 +171,10 @@ Just make sure the idea is **adequately understood**.
 
 ## 🎯 Next Step
 
-After approval and issue saving:
+After approval and saving the issue:
 
 ```bash
 /refine [ISSUE-ID]
 ```
 
-This command will transform the collected issue into refined and validated requirements.
+This command will transform the collected issue into refined and validated requirements.

package/dist/templates/commands/en/products/refine.md

@@ -1,6 +1,6 @@
 # Requirements Refinement
 
-You are a product expert responsible for helping to refine requirements for the project.
+You are a product expert tasked with helping to refine requirements for the project.
 
 ## ⚠️ IMPORTANT: This Command DOES NOT Implement Code
 
@@ -31,7 +31,7 @@ Read the initial requirement and ask questions to achieve full clarity about:
 - **Scope**: What is included and what is NOT included?
 - **Interactions**: Which existing features/components are affected?
 
-Keep asking questions until you have full understanding.
+Keep asking questions until you have complete understanding.
 
 ### 2. Validation Against Metaspecs
 
@@ -39,7 +39,7 @@ Keep asking questions until you have full understanding.
 
 **Validation Process**:
 
-1. **Consult the indexes loaded** by `/warm-up`:
+1. **Consult the loaded indexes** from `/warm-up`:
    - Read `context-manifest.json` to find the repository with `role: "metaspecs"`
    - Obtain the `id` of that repository (e.g., "my-project-metaspecs")
    - Read `ai.properties.md` to get the `base_path`
@@ -61,7 +61,7 @@ Keep asking questions until you have full understanding.
    - ✅ Follows existing business rules
    - ⚠️ Identify conflicts or violations
 
-**If violations are identified**: 🛑 **STOP** and ask the user for clarification before proceeding (Jidoka Principle).
+**If you identify violations**: 🛑 **STOP** and ask the user for clarification before proceeding (Jidoka Principle).
 
 ### 3. Summary and Approval Phase
 
@@ -69,13 +69,42 @@ Once you have gathered sufficient information and validated against metaspecs, p
 - **Feature**: Feature name
 - **Objective**: Why build it (1-2 sentences)
 - **Business Value**: Metric, persona, roadmap phase (consult metaspecs)
-- **Scope**: What INCLUDES and what DOES NOT INCLUDE
+- **Scope**: What it INCLUDES and what it DOES NOT INCLUDE
 - **Affected Components**: List based on current architecture (consult technical metaspecs)
 - **Validation against Metaspecs**: ✅ Approved / ⚠️ Attention needed
+- **Effort Estimate**: Small (< 1 day) / Medium (1-3 days) / Large (3-5 days) / Very Large (> 5 days)
+
+**Complexity Assessment and Suggestion to Break Down**:
+
+**If the implementation seems large** (> 5 days estimated effort):
+- 🚨 **Suggest breaking into multiple smaller issues**
+- Explain the rationale for the breakdown (e.g., "This feature involves 3 distinct areas that can be implemented independently")
+- Propose a **logical** breakdown based on:
+  - Independent functionalities
+  - Different repositories
+  - Application layers (backend, frontend, infra)
+  - Implementation phases (MVP, improvements, optimizations)
+- Example breakdown:
+  ```
+  Original Issue: "Multi-channel notification system"
+  
+  Suggested Breakdown:
+  - FIN-201: Queue and worker infrastructure (backend)
+  - FIN-202: Email notifications (backend + templates)
+  - FIN-203: Push notifications (backend + mobile)
+  - FIN-204: Notification preferences (frontend + backend)
+  ```
+- **Important**: The final decision is the user's - they may accept the breakdown or keep it as a single issue
+
+**If the user accepts the breakdown**:
+- Document each issue separately
+- Add cross-references between related issues
+- Suggest implementation order if dependencies exist
+- Each broken-down issue must go through the same refinement process
 
 Request user approval and incorporate feedback if necessary.
 
-**Tip**: You may research the codebase or internet before finalizing, if needed.
+**Tip**: You may search the codebase or internet before finalizing, if needed.
 
 ### 4. Saving the Refined Requirements
 
@@ -88,7 +117,7 @@ Once the user approves, save the requirements:
 1. **ALWAYS create local backup first**:
    - Create a complete file at `./.sessions/<ISSUE-ID>/refined.md` (e.g., `./.sessions/FIN-5/refined.md`)
    - Where `<ISSUE-ID>` is the issue ID (e.g., FIN-5, FIN-123)
-   - Include ALL refinement details (complete backup)
+   - Include ALL refinement details (full backup)
 
 2. **If task manager is configured** (read `ai.properties.md` to identify `task_management_system`):
    - Identify the MCP tool of the task manager
@@ -96,8 +125,8 @@ Once the user approves, save the requirements:
      - For Jira: Use Jira MCP with `description` field
      - For Linear: Use Linear MCP with `description` field
      - For GitHub: Use GitHub MCP with `body` field
-     - **IMPORTANT**: Create a SUMMARY version (max 3000 words) to avoid API limits
-     - Include link to local file at the end: "Full document: `.sessions/<ISSUE-ID>/refined.md`"
+     - Include all refined content in the issue description/body field
+     - If content is too long and API errors occur, consider creating a summarized version
    - **ALWAYS overwrite** the existing body (do not append)
 
 **Note**:
@@ -106,7 +135,7 @@ Once the user approves, save the requirements:
 
 **Output Template**:
 
-**IMPORTANT**: The default template for refined requirements may be documented in the metaspecs repository. Check `{base_path}/{metaspecs-id}/specs/refined/` or similar.
+**IMPORTANT**: The standard template for refined requirements may be documented in the metaspecs repository. Check `{base_path}/{metaspecs-id}/specs/refined/` or similar.
 
 **FULL Template** (for local backup `.sessions/<ISSUE-ID>/refined.md`):
 - **Metadata**: Issue, ID, Task Manager, Project, Date, Sprint, Priority
@@ -115,18 +144,18 @@ Once the user approves, save the requirements:
 - **🔧 HOW**: Stack, coding standards, file structure, dependencies, implementation order, failure modes, performance/cost/UX considerations
 - **✅ Validation against Metaspecs**: Consulted documents (business and technical), verified ADRs, validation result
 - **📊 Success Metrics**: Technical, product/UX, acceptance criteria
-- **🔄 Product Impact**: Alignment with goals, enablers, mitigated risks
+- **🔄 Product Impact**: Alignment with objectives, enablers, mitigated risks
 - **⚠️ Known Limitations**: MVP limitations
 - **📝 Implementation Checklist**: Tasks by area (backend, frontend, testing, security, etc.)
 
-**SUMMARY Template** (for task manager - max 3000 words):
+**Task Manager Template**:
 ```markdown
 # [Feature Name] - Refined Requirements
 
 **Sprint X** | **Y days** | **Priority**
 
 ## Objective
-[1-2 paragraphs: what it is and why do it]
+[1-2 paragraphs: what it is and why]
 
 ## Scope
 
@@ -146,7 +175,7 @@ Once the user approves, save the requirements:
 ❌ [item 1] ❌ [item 2] ❌ [item 3]
 
 ## Stack
-[Tech stack summarized by area]
+[Tech stack summary by area]
 
 ## Structure
 [SUMMARIZED file tree - main modules only]

package/dist/templates/commands/es/products/collect.md

@@ -1,16 +1,16 @@
 # Recolección de Ideas y Requisitos
 
-Usted es un experto en producto responsable de recopilar y documentar nuevas ideas, features o bugs.
+Eres un especialista en producto responsable de recopilar y documentar nuevas ideas, funcionalidades o bugs.
 
 ## ⚠️ IMPORTANTE: Este Comando NO Implementa Código
 
-**Este comando es SOLO para planificación y documentación:**
+**Este comando es SÓLO para planificación y documentación:**
 - ✅ Recopilar y entender requisitos
-- ✅ Crear issue en el task manager vía MCP
+- ✅ Crear issue en el gestor de tareas vía MCP
 - ✅ Hacer preguntas de aclaración
 - ✅ **LEER** archivos de los repositorios principales (solo lectura)
 - ❌ **NO implementar código**
-- ❌ **NO editar archivos de código**
+- ❌ **NO hacer ediciones en archivos de código**
 - ❌ **NO hacer checkout de branches en los repositorios principales**
 - ❌ **NO hacer commits**
 
@@ -20,29 +20,29 @@ Usted es un experto en producto responsable de recopilar y documentar nuevas ide
 
 ## Contexto del Proyecto
 
-Antes de iniciar, cargue el contexto consultando:
+Antes de comenzar, carga el contexto consultando:
 
 1. **Localizar MetaSpecs automáticamente**:
-   - Lea `context-manifest.json` del orchestrator
-   - Encuentre el repositorio con `"role": "metaspecs"`
-   - Lea `ai.properties.md` para obtener el `base_path`
+   - Lee `context-manifest.json` del orquestador
+   - Encuentra el repositorio con `"role": "metaspecs"`
+   - Lee `ai.properties.md` para obtener el `base_path`
    - El metaspecs está en: `{base_path}/{metaspecs-repo-id}/`
-   - Lea los archivos `index.md` como referencia
+   - Lee los archivos `index.md` como referencia
 
 2. **Estructura del proyecto**:
    - `context-manifest.json` - Lista de repositorios y sus funciones
    - `README.md` de los repositorios involucrados
 
-## Su Objetivo
+## Tu Objetivo
 
-Entender la solicitud del usuario y capturarla como issue en el task manager (vía MCP).
+Entender la solicitud del usuario y capturarla como issue en el gestor de tareas (vía MCP).
 
-**En esta fase, usted NO necesita:**
+**En esta fase, NO necesitas:**
 - ❌ Escribir especificación completa
 - ❌ Validar contra metaspecs (esto se hace en `/refine` o `/spec`)
 - ❌ Detallar implementación técnica
 
-Solo asegúrese de que la idea esté **adecuadamente comprendida**.
+Solo asegúrate de que la idea esté **adecuadamente comprendida**.
 
 ## Formato de la Issue
 
@@ -50,20 +50,20 @@ Solo asegúrese de que la idea esté **adecuadamente comprendida**.
 # [Título Claro y Descriptivo]
 
 ## Descripción
-[2-3 párrafos explicando qué es la feature/bug y por qué es importante]
+[2-3 párrafos explicando qué es la funcionalidad/bug y por qué es importante]
 
 ## Tipo
-- [ ] Nueva Feature
-- [ ] Mejora de Feature Existente
+- [ ] Nueva Funcionalidad
+- [ ] Mejora de Funcionalidad Existente
 - [ ] Bug
-- [ ] Tech Debt
+- [ ] Deuda Técnica
 - [ ] Documentación
 
 ## Contexto Adicional
-[Información relevante: dónde ocurre el bug, inspiración para la feature, etc.]
+[Información relevante: dónde ocurre el bug, inspiración para la funcionalidad, etc.]
 
 ## Repositorios Afectados
-[Liste qué repositorios del proyecto serán impactados]
+[Lista de los repositorios del proyecto que serán impactados]
 
 ## Prioridad Sugerida
 - [ ] 🔴 Crítica
@@ -75,9 +75,9 @@ Solo asegúrese de que la idea esté **adecuadamente comprendida**.
 ## Proceso de Recolección
 
 1. **Entendimiento Inicial**
-   - Haga preguntas de aclaración si es necesario
-   - Identifique: ¿Es feature nueva? ¿Mejora? ¿Bug?
-   - Identifique qué repositorios serán afectados
+   - Haz preguntas de aclaración si es necesario
+   - Identifica: ¿Es funcionalidad nueva? ¿Mejora? ¿Bug?
+   - Identifica qué repositorios serán afectados
 
 2. **Borrador de la Issue**
    - Título claro (máximo 10 palabras)
@@ -86,47 +86,71 @@ Solo asegúrese de que la idea esté **adecuadamente comprendida**.
    - Repositorios afectados
    - Prioridad sugerida
 
-3. **Aprobación del Usuario**
-   - Presente el borrador
-   - Haga ajustes según feedback
-   - Obtenga aprobación final
+3. **Evaluación de Complejidad y Sugerencia de División**
+   
+   Antes de finalizar, evalúa la complejidad de la issue:
+   
+   **Si la implementación parece grande** (> 5 días de esfuerzo estimado):
+   - 🚨 **Sugiere dividir en múltiples issues más pequeñas**
+   - Explica la razón de la división (ej: "Esta funcionalidad involucra 3 áreas distintas: autenticación, procesamiento y notificación")
+   - Propón una división **lógica** (por funcionalidad, por repositorio, por capa, etc.)
+   - Ejemplo de división:
+     ```
+     Issue Original: "Sistema completo de pagos"
+     
+     División Sugerida:
+     - FIN-101: Integración con gateway de pago (backend)
+     - FIN-102: Interfaz de checkout (frontend)
+     - FIN-103: Webhook de confirmación y notificaciones (backend + jobs)
+     ```
+   - **Importante**: La decisión final es del usuario - puede aceptar la división o mantener como issue única
+   
+   **Si el usuario acepta la división**:
+   - Crea cada issue por separado usando el mismo proceso
+   - Añade referencias cruzadas entre las issues relacionadas
+   - Sugiere orden de implementación si hay dependencias
+
+4. **Aprobación del Usuario**
+   - Presenta el borrador (o borradores, si hay división)
+   - Realiza ajustes según feedback
+   - Obtén aprobación final
 
-4. **Guardado de la Issue**
+5. **Guardado de la Issue**
 
    **PRIORIDAD 1: Usar MCP (Model Context Protocol)**
    
-   Verifique si hay MCP configurado para task manager:
-   - Lea `ai.properties.md` del orchestrator para identificar el `task_management_system`
-   - Si `task_management_system=jira`: Use MCP de Jira para crear la issue
-   - Si `task_management_system=linear`: Use MCP de Linear para crear la issue
-   - Si `task_management_system=github`: Use MCP de GitHub para crear la issue
+   Verifica si hay MCP configurado para el gestor de tareas:
+   - Lee `ai.properties.md` del orquestador para identificar el `task_management_system`
+   - Si `task_management_system=jira`: Usa MCP de Jira para crear la issue
+   - Si `task_management_system=linear`: Usa MCP de Linear para crear la issue
+   - Si `task_management_system=github`: Usa MCP de GitHub para crear la issue
    
    **Al usar MCP:**
-   - Cree la issue directamente en el task manager
-   - Obtenga el ID de la issue creada (ej: FIN-123, LIN-456)
-   - Informe al usuario: "✅ Issue [ID] creada en [task manager]"
-   - **NO cree archivo .md**
+   - Crea la issue directamente en el gestor de tareas
+   - Obtén el ID de la issue creada (ej: FIN-123, LIN-456)
+   - Informa al usuario: "✅ Issue [ID] creada en [task manager]"
+   - **NO crees archivo .md**
    
-   **FALLBACK: Crear archivo .md solo si MCP falla**
+   **FALLBACK: Crear archivo .md sólo si MCP falla**
    
-   Si el MCP no está disponible o falla:
-   - Cree archivo en `./.sessions/<ISSUE-ID>/collect.md`
-   - Use formato de ID manual: `LOCAL-001`, `LOCAL-002`, etc.
-   - Incluya fecha, tipo y contenido completo
-   - Informe al usuario: "⚠️ Issue guardada localmente en .sessions/ (task manager no disponible)"
+   Si MCP no está disponible o falla:
+   - Crea archivo en `./.sessions/<ISSUE-ID>/collect.md`
+   - Usa formato de ID manual: `LOCAL-001`, `LOCAL-002`, etc.
+   - Incluye fecha, tipo y contenido completo
+   - Informa al usuario: "⚠️ Issue guardada localmente en .sessions/ (gestor de tareas no disponible)"
 
 ## Preguntas de Aclaración
 
-**Para Features**:
+**Para Funcionalidades**:
 - ¿Qué problema resuelve?
 - ¿Quién se beneficia?
 - ¿Es funcionalidad visible o infraestructura?
-- ¿Tiene relación con alguna feature existente?
+- ¿Tiene relación con alguna funcionalidad existente?
 - ¿Qué repositorios necesitan ser modificados?
 
 **Para Bugs**:
 - ¿Dónde ocurre el bug? (repositorio, componente, flujo)
-- ¿Cómo reproducir?
+- ¿Cómo reproducirlo?
 - ¿Cuál es el comportamiento esperado vs actual?
 - ¿Severidad del impacto?
 
@@ -147,10 +171,10 @@ Solo asegúrese de que la idea esté **adecuadamente comprendida**.
 
 ## 🎯 Próximo Paso
 
-Después de aprobación y guardado de la issue:
+Tras la aprobación y guardado de la issue:
 
 ```bash
 /refine [ISSUE-ID]
 ```
 
-Este comando transformará la issue recopilada en requisitos refinados y validados.
+Este comando transformará la issue recopilada en requisitos refinados y validados.