context-first-cli 2.0.3 → 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,209 +1,211 @@
 # Requirements Refinement
 
-This command refines a collected issue, transforming it into clear and validated requirements.
+You are a product expert tasked with helping to refine requirements for the project.
 
 ## ⚠️ IMPORTANT: This Command DOES NOT Implement Code
 
-**This command is ONLY for requirements refinement:**
-- ✅ Refine and validate requirements
-- ✅ Update issue in the task manager via MCP
-- ✅ **READ** files from main repositories (read-only)
+**This command is ONLY for planning and documentation:**
+- ✅ Validate requirements against metaspecs
+- ✅ Create refined specification
+- ✅ Save documentation in `.sessions/`
+- ✅ Update issue in task manager
 - ❌ **DO NOT implement code**
 - ❌ **DO NOT edit code files**
-- ❌ **DO NOT checkout branches in main repositories**
-- ❌ **DO NOT make commits**
+- ❌ **DO NOT run tests or deploy**
 
-**Next step**: `/spec [ISSUE-ID]` to create the complete specification (PRD).
+**Next step**: `/spec [ISSUE-ID]` to create a complete PRD based on the refined requirements.
 
 ---
 
-## 📋 Prerequisites
+## Objective
 
-- Issue already collected via `/collect`
-- Project context will be loaded automatically (see "Load MetaSpecs" section below)
+Transform an initial requirement into a refined and validated specification, ready to become a complete PRD.
 
-## 🎯 Objective
+## Process
 
-Refine the collected issue, clarifying:
-- Exact scope (what is included and what is not)
-- Clear acceptance criteria
-- Impact on each repository
-- Technical dependencies
-- Risks and constraints
+### 1. Clarification Phase
 
-## 📝 Refinement Process
+Read the initial requirement and ask questions to achieve full clarity about:
+- **Objective**: Why build this?
+- **Business Value**: Which metric/persona does it impact?
+- **Scope**: What is included and what is NOT included?
+- **Interactions**: Which existing features/components are affected?
 
-### 1. Load Issue
+Keep asking questions until you have complete understanding.
 
-**PRIORITY 1: Use MCP (Model Context Protocol)**
+### 2. Validation Against Metaspecs
 
-- Read `ai.properties.md` from the orchestrator to identify the `task_management_system`
-- Use the appropriate MCP to fetch the issue:
-  - `task_management_system=jira`: Use Jira MCP
-  - `task_management_system=linear`: Use Linear MCP
-  - `task_management_system=github`: Use GitHub MCP
-- Load all issue data (title, description, labels, etc.)
+**IMPORTANT**: First read `ai.properties.md` to obtain the `base_path`. The indexes should ALREADY be in context (you ran `/warm-up`). Consult the indexes and read ONLY the relevant documents to validate the requirement.
 
-**FALLBACK: If MCP is unavailable or fails**
-
-- Read `./.sessions/<ISSUE-ID>/collect.md`
-- If the file does not exist, inform the user of the error
-
-### 2. Load MetaSpecs
-
-**Automatically locate MetaSpecs**:
-1. Read `context-manifest.json` from the orchestrator
-2. Find the repository with `"role": "metaspecs"`
-3. Read `ai.properties.md` to get the `base_path`
-4. The metaspecs are located at: `{base_path}/{metaspecs-repo-id}/`
-5. Read relevant `index.md` files to understand:
-   - System architecture
-   - Design patterns
-   - Technical constraints
-   - Project conventions
-
-### 3. Scope Analysis
-
-Clearly define:
-
-**What IS in scope**:
-- Specific functionalities to be implemented
-- Repositories that will be modified
-- Necessary integrations
-
-**What IS NOT in scope**:
-- Related functionalities deferred for later
-- Future optimizations
-- "Nice to have" features
-
-### 4. Acceptance Criteria
-
-Define measurable and testable criteria:
-
-```markdown
-## Acceptance Criteria
-
-### Functional
-- [ ] [Criterion 1 - specific and testable]
-- [ ] [Criterion 2 - specific and testable]
-
-### Technical
-- [ ] [Technical criterion 1]
-- [ ] [Technical criterion 2]
-
-### Quality
-- [ ] Unit tests implemented
-- [ ] Integration tests implemented
-- [ ] Documentation updated
-```
-
-### 5. Impact Analysis
-
-For each affected repository:
+**Validation Process**:
 
+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`
+   - The metaspecs repository is at: `{base_path}/{metaspecs-id}/`
+   - Consult `{base_path}/{metaspecs-id}/index.md` - Project overview
+   - Consult specific indexes (e.g., `specs/business/index.md`, `specs/technical/index.md`)
+
+2. **Identify relevant documents** for this specific requirement:
+   - In `specs/business/`: Which business documents are relevant?
+   - In `specs/technical/`: Which technical documents are relevant?
+
+3. **Read ONLY the identified relevant documents** (do not read everything!)
+
+4. **Validate the requirement** against the read metaspecs:
+   - ✅ Alignment with product strategy and vision
+   - ✅ Meets needs of the correct personas
+   - ✅ Compatible with approved technology stack
+   - ✅ Respects architectural decisions (ADRs)
+   - ✅ Follows existing business rules
+   - ⚠️ Identify conflicts or violations
+
+**If you identify violations**: 🛑 **STOP** and ask the user for clarification before proceeding (Jidoka Principle).
+
+### 3. Summary and Approval Phase
+
+Once you have gathered sufficient information and validated against metaspecs, present a structured summary with:
+- **Feature**: Feature name
+- **Objective**: Why build it (1-2 sentences)
+- **Business Value**: Metric, persona, roadmap phase (consult metaspecs)
+- **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 search the codebase or internet before finalizing, if needed.
+
+### 4. Saving the Refined Requirements
+
+Once the user approves, save the requirements:
+
+**IMPORTANT**: Always create a local backup AND update the task manager (if configured).
+
+**Saving Process**:
+
+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 (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
+   - **Update the BODY (description) of the issue** with a CONCISE version of the refined 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
+     - 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**:
+- The local backup is ALWAYS saved and complete
+- If API error occurs, manually verify if the issue was updated in the task manager
+
+**Output Template**:
+
+**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
+- **🎯 WHY**: Reasons, business value, metric, persona, strategic alignment
+- **📦 WHAT**: Detailed features, affected components, integrations, full negative scope
+- **🔧 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 objectives, enablers, mitigated risks
+- **⚠️ Known Limitations**: MVP limitations
+- **📝 Implementation Checklist**: Tasks by area (backend, frontend, testing, security, etc.)
+
+**Task Manager Template**:
 ```markdown
-## Impact by Repository
-
-### <repo-1>
-- **Affected components**: [list]
-- **Type of change**: New feature / Modification / Refactoring
-- **Estimated complexity**: Low / Medium / High
-- **Risks**: [specific risks]
-
-### <repo-2>
-- **Affected components**: [list]
-- **Type of change**: New feature / Modification / Refactoring
-- **Estimated complexity**: Low / Medium / High
-- **Risks**: [specific risks]
-```
-
-### 6. Dependencies and Constraints
-
-Identify:
-- Dependencies between repositories
-- Dependencies on other features/issues
-- Technical constraints
-- Business constraints
-- Known blockers
-
-### 7. Initial Estimate
+# [Feature Name] - Refined Requirements
 
-Provide effort estimate:
-- **Small**: < 1 day
-- **Medium**: 1-3 days
-- **Large**: 3-5 days
-- **Very Large**: > 5 days (consider breaking into smaller issues)
+**Sprint X** | **Y days** | **Priority**
 
-### 8. Pending Questions
+## Objective
+[1-2 paragraphs: what it is and why]
 
-List questions that still need answers before starting implementation.
-
-## 📄 Saving the Refinement
+## Scope
 
-**PRIORITY 1: Update via MCP**
+### Main Features
+- Feature 1: [summary]
+- Feature 2: [summary]
+- Validations/Guards: [summary]
 
-- Use the task manager MCP to update the issue
-- Add acceptance criteria as a comment or custom field
-- Update labels/tags if necessary (e.g., "refined", "ready-for-spec")
-- Add estimate if supported by the task manager
-- Inform the user: "✅ Issue [ID] updated with refinement"
+### Affected Components
+- Component 1: [type of change]
+- Component 2: [type of change]
 
-**FALLBACK: Create .md file only if MCP fails**
+### Security
+✅ [item 1] ✅ [item 2] ✅ [item 3]
 
-If MCP is unavailable or fails, create/update `./.sessions/<ISSUE-ID>/refine.md`:
+## Negative Scope
+❌ [item 1] ❌ [item 2] ❌ [item 3]
 
-```markdown
-# [Issue Title] - Refinement
+## Stack
+[Tech stack summary by area]
 
-## Scope
+## Structure
+[SUMMARIZED file tree - main modules only]
 
-### Included
-- [Item 1]
-- [Item 2]
-
-### Excluded
-- [Item 1]
-- [Item 2]
+## Failure Modes (To Avoid)
+🔴 [critical 1] 🔴 [critical 2]
+🟡 [medium 1] 🟡 [medium 2]
 
 ## Acceptance Criteria
-[As per section 3 above]
-
-## Impact by Repository
-[As per section 4 above]
-
-## Dependencies
-- [Dependency 1]
-- [Dependency 2]
-
-## Constraints
-- [Constraint 1]
-- [Constraint 2]
+- [ ] [item 1]
+- [ ] [item 2]
+- [ ] [item 3]
 
-## Estimate
-[Small/Medium/Large/Very Large] - [Justification]
+## Validation
+**ADRs**: [list]
+**Specs**: [main]
+**Status**: ✅ Approved
 
-## Pending Questions
-1. [Question 1]
-2. [Question 2]
+**Impact**: [summary]
+**Limitations**: [summary]
 
-## Identified Risks
-- [Risk 1 and mitigation]
-- [Risk 2 and mitigation]
+---
+📄 **Full document**: `.sessions/<ISSUE-ID>/refined.md`
 ```
 
-Inform the user: "⚠️ Refinement saved locally in .sessions/ (task manager not available)"
-
-## 🔍 Validation
-
-Validate the refinement against:
-- Product strategy (if documented)
-- Technical architecture (if documented)
-- Team capacity
-- Roadmap priorities
+**Audience**: AI Developer with capabilities similar to yours. Be concise but complete.
 
 ---
 
-**Provided arguments**:
+**Requirement to Refine**:
 
 ```
 #$ARGUMENTS
@@ -213,10 +215,12 @@ Validate the refinement against:
 
 ## 🎯 Next Step
 
-After approved refinement:
+**After user approval and saving the refined requirements**, the natural flow is:
 
 ```bash
 /spec [ISSUE-ID]
 ```
 
-This command will create the complete feature specification (PRD).
+**Example**: `/spec FIN-3`
+
+This command will create a complete PRD (Product Requirements Document) based on the refined requirements, detailing features, user stories, acceptance criteria, and final validations.