context-first-cli 2.1.5 → 2.2.0

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

@@ -1,6 +1,6 @@
 # Start of Development
 
-This command starts the development of a feature in the current workspace.
+This command initiates the development of a feature in the current workspace.
 
 ## 📍 IMPORTANT: Understand the Structure
 
@@ -14,7 +14,7 @@ This command starts the development of a feature in the current workspace.
 └── plan.md          # plan (mutable - created by /plan)
 ```
 
-**Main repositories** (read-only):
+**Main Repositories** (read-only):
 ```
 {base_path}/repo-1/  # main repo (branch main/master)
 {base_path}/repo-2/  # main repo (branch main/master)
@@ -24,7 +24,44 @@ This command starts the development of a feature in the current workspace.
 - ✅ Read metaspecs and code from main repositories (read-only)
 - ✅ Create `context.md` and `architecture.md` in `.sessions/<ISSUE-ID>/`
 - ❌ NEVER checkout main repositories
-- ❌ NEVER modify code in this command (use `/work` afterwards)
+- ❌ NEVER modify code in this command (use `/work` later)
+
+## 📋 Project Configuration
+
+**⚠️ IMPORTANT: Always read the project configuration files BEFORE running this command!**
+
+### Required Files
+
+1. **`context-manifest.json`** (orchestrator root)
+   - List of project repositories
+   - Roles of each repository (metaspecs, application, etc.)
+   - URLs and dependencies among repositories
+
+2. **`ai.properties.md`** (orchestrator root)
+   - Project settings (`project_name`, `base_path`)
+   - Task management system (`task_management_system`)
+   - Credentials and specific configurations
+
+### How to Read
+
+```bash
+# 1. Read context-manifest.json
+cat context-manifest.json
+
+# 2. Read ai.properties.md
+cat ai.properties.md
+```
+
+### Essential Information
+
+After reading the files, you will have:
+- ✅ Complete list of project repositories
+- ✅ Location of the metaspecs repository
+- ✅ Base path to locate repositories
+- ✅ Configured task management system
+- ✅ Project-specific configurations
+
+**🛑 DO NOT proceed without reading these files!** They contain critical information for correct command execution.
 
 ## 📚 Load MetaSpecs
 
@@ -33,7 +70,7 @@ This command starts the development of a feature in the current workspace.
 2. Find the repository with `"role": "metaspecs"`
 3. Read `ai.properties.md` to get the `base_path`
 4. The metaspecs are at: `{base_path}/{metaspecs-repo-id}/`
-5. Read the relevant `index.md` files:
+5. Read relevant `index.md` files:
    - Business context
    - Stack, architecture, and technical patterns
    - Project conventions
@@ -52,7 +89,7 @@ Before starting, load the context by consulting:
    - Confirm you are in the correct workspace (check `workspace directory`)
    - List repositories available in the workspace
 
-2. **Verify Branches**:
+2. **Check Branches**:
    - For each repository in the workspace, check the current branch
    - Confirm all branches are synchronized
 
@@ -73,15 +110,15 @@ Analyze the specification and build a complete understanding by answering:
 - **Which** metric do we want to impact?
 
 ### Functional
-- **What is the expected outcome**? (user behavior, system output)
+- **What is the expected outcome?** (user behavior, system output)
 - **Which components** will be created/modified in each repository?
 - **Which integrations** between repositories are necessary?
 
 ### Technical
-- **Approved stack**? Check against technical specifications
-- **Architectural patterns**? Check ADRs (if available)
-- **New dependencies**? Justify and document
-- **How to test**? (according to project standards)
+- **Approved stack?** Check against technical specifications
+- **Architectural patterns?** Check ADRs (if available)
+- **New dependencies?** Justify and document
+- **How to test?** (according to project standards)
 
 ### Validation against MetaSpecs
 
@@ -97,16 +134,16 @@ After initial analysis, formulate **3-5 most important clarifications**:
 
 **Examples of relevant questions**:
 - Which repository should contain the main logic?
-- How should the repositories communicate?
+- How should repositories communicate?
 - Are there dependencies between changes in different repos?
 - What is the recommended implementation order?
-- Is there any impact on APIs or contracts between services?
+- Is there impact on APIs or contracts between services?
 
 ## 💾 Creation of Context.md
 
 **IMPORTANT**: This file is **IMMUTABLE** after approval. It must not be modified by subsequent commands.
 
-Create the file `./.sessions/<ISSUE-ID>/context.md` with:
+Create file `./.sessions/<ISSUE-ID>/context.md` with:
 
 ```markdown
 # Context: [Feature Name]
@@ -135,7 +172,7 @@ Create the file `./.sessions/<ISSUE-ID>/context.md` with:
 [Technical limitations, performance targets, budget]
 
 ## Tests
-[Critical E2E, required unit tests, expected coverage]
+[Critical E2E, necessary unit tests, expected coverage]
 ```
 
 **After creating `context.md`, request user review and approval before proceeding.**
@@ -153,17 +190,17 @@ Create the file `./.sessions/<ISSUE-ID>/context.md` with:
 1. **Read ADRs (Architecture Decision Records)**:
    - List ADRs in metaspecs
    - Read ALL ADRs relevant to the feature
-   - Identify constraints and mandatory patterns
+   - Identify mandatory constraints and patterns
 
 2. **Consult architectural patterns**:
    - Read project structure guides in metaspecs
-   - Read code patterns in metaspecs
+   - Read coding patterns in metaspecs
    - Identify existing patterns in code (use Glob/Grep to find similar examples)
 
 3. **Validate compliance with ADRs**:
-   - For each relevant ADR, verify if the proposed solution respects the decisions
+   - For each relevant ADR, check if the proposed solution respects the decisions
    - Document compliance in architecture.md
-   - If there is violation, justify or propose correction
+   - If violation exists, justify or propose correction
 
 4. **Analyze existing code**:
    - Use Glob/Grep to find similar components/modules
@@ -172,7 +209,7 @@ Create the file `./.sessions/<ISSUE-ID>/context.md` with:
 
 ### Architecture Document Structure
 
-Create the file `./.sessions/<ISSUE-ID>/architecture.md` with:
+Create file `./.sessions/<ISSUE-ID>/architecture.md` with:
 
 ```markdown
 # Architecture: [Feature Name]
@@ -204,7 +241,7 @@ repo-1/
 ```
 
 ## Patterns and Best Practices
-[Patterns that will be maintained or introduced]
+[Patterns to be maintained or introduced]
 
 ## ADR Validation
 [List of consulted ADRs and compliance]
@@ -213,7 +250,7 @@ repo-1/
 - [x] ADR-002: [Name] - Compliant
 
 ## External Dependencies
-[Libraries that will be used or added]
+[Libraries to be used or added]
 
 ## Technical Decisions
 
@@ -226,7 +263,7 @@ repo-1/
 **Justification**: [Why we chose this option]
 
 ## Constraints and Assumptions
-[Technical limitations and assumptions]
+[Technical limitations and premises]
 
 ## Trade-offs
 [Alternatives considered and why they were not chosen]
@@ -262,7 +299,7 @@ repo-1/
 
 ## 🎯 Next Step
 
-**After user approval of the files `context.md` and `architecture.md`**:
+**After user approval of `context.md` and `architecture.md` files**:
 
 ```bash
 /plan

package/templates/commands/en/engineer/work.md

@@ -7,11 +7,49 @@ This command executes a unit of work in the current workspace, implementing part
 Before executing, make sure that:
 - You have run `/start` and `/plan` to have the technical plan
 - You are in the correct workspace: `<orchestrator>/.sessions/<ISSUE-ID>/`
-- You have the `.sessions/<ISSUE-ID>/` files available:
+- You have the files `.sessions/<ISSUE-ID>/` available:
   - `context.md` (immutable)
   - `architecture.md` (immutable)
   - `plan.md` (mutable)
 
+## 📋 Project Configuration
+
+**⚠️ IMPORTANT: Always read the project configuration files BEFORE running this command!**
+
+### Required Files
+
+1. **`context-manifest.json`** (orchestrator root)
+   - List of project repositories
+   - Roles of each repository (metaspecs, application, etc.)
+   - URLs and dependencies between repositories
+
+2. **`ai.properties.md`** (orchestrator root)
+   - Project settings (`project_name`, `base_path`)
+   - Task management system (`task_management_system`)
+   - Credentials and specific configurations
+
+### How to Read
+
+```bash
+# 1. Read context-manifest.json
+cat context-manifest.json
+
+# 2. Read ai.properties.md
+cat ai.properties.md
+```
+
+### Essential Information
+
+After reading the files, you will have:
+- ✅ Complete list of project repositories
+- ✅ Location of the metaspecs repository
+- ✅ Base path to locate repositories
+- ✅ Configured task management system
+- ✅ Project-specific configurations
+
+**🛑 DO NOT proceed without reading these files!** They contain critical information for the correct execution of the command.
+
+
 ## 📍 IMPORTANT: Understand the Structure
 
 **Workspace** (where you work):
@@ -32,7 +70,7 @@ Before executing, make sure that:
 
 **GOLDEN RULE**:
 - ✅ Work ONLY inside `<orchestrator>/.sessions/<ISSUE-ID>/`
-- ✅ Make commits in the worktrees inside the workspace
+- ✅ Commit in the worktrees inside the workspace
 - ❌ NEVER checkout branches in the main repositories
 - ❌ NEVER navigate to `{base_path}/{repo-id}/`
 
@@ -57,7 +95,7 @@ Before executing, make sure that:
 **ABSOLUTE RULE**:
 - 🛑 **EVERY code file** (`.ts`, `.js`, `.py`, `.java`, etc.) **MUST be inside** `<orchestrator>/.sessions/<ISSUE-ID>/<repo-name>/`
 - 🛑 **NEVER create code** directly in `<orchestrator>/.sessions/` or `<orchestrator>/.sessions/<ISSUE-ID>/`
-- ✅ **Only valid place**: Inside the specific repository worktree
+- ✅ **Only valid place**: Inside the repository’s worktree
 
 ## ⚠️ IMPORTANT: Immutable Files
 
@@ -67,8 +105,8 @@ Before executing, make sure that:
 - ✅ **UPDATE** `.sessions/<ISSUE-ID>/plan.md` (mark progress)
 - ✅ **IMPLEMENT** code **INSIDE THE WORKTREE**: `.sessions/<ISSUE-ID>/<repo-name>/`
 - ✅ **MAKE COMMITS** in the worktrees: `.sessions/<ISSUE-ID>/<repo-name>/`
-- ❌ **DO NOT modify `context.md` or `architecture.md`**
-- ❌ **DO NOT checkout branches in the main repositories (outside the workspace)**
+- ❌ **Do NOT modify `context.md` or `architecture.md`**
+- ❌ **Do NOT checkout branches in the main repositories (outside workspace)**
 - 🛑 **NEVER create code directly in `.sessions/` or `.sessions/<ISSUE-ID>/`**
 
 ## 📚 Load MetaSpecs
@@ -83,7 +121,7 @@ Before executing, make sure that:
    - Respect defined architecture
    - Use correct conventions
 
-## 🎯 Goal
+## 🎯 Objective
 
 Implement a specific unit of work from the plan, which may involve:
 - Creating new files/components
@@ -124,7 +162,7 @@ Based on the technical plan (`./.sessions/<ISSUE-ID>/plan.md`), identify:
 
 
 
-**IMPORTANT**: Work ONLY inside the workspace in `.sessions/<ISSUE-ID>/`
+**IMPORTANT**: Work ONLY inside the workspace `.sessions/<ISSUE-ID>/`
 
 For each repository in the workspace:
 

package/templates/commands/en/products/check.md

@@ -12,6 +12,43 @@ This command validates requirements, decisions, or implementations against the p
 - ❌ **DO NOT modify code**
 - ❌ **DO NOT modify `context.md` or `architecture.md`**
 
+## 📋 Project Configuration
+
+**⚠️ IMPORTANT: Always read the project configuration files BEFORE running this command!**
+
+### Required Files
+
+1. **`context-manifest.json`** (root of the orchestrator)
+   - List of project repositories
+   - Roles of each repository (metaspecs, application, etc.)
+   - URLs and dependencies between repositories
+
+2. **`ai.properties.md`** (root of the orchestrator)
+   - Project settings (`project_name`, `base_path`)
+   - Task management system
+   - Credentials and specific configurations
+
+### How to Read
+
+```bash
+# 1. Read context-manifest.json
+cat context-manifest.json
+
+# 2. Read ai.properties.md
+cat ai.properties.md
+```
+
+### Essential Information
+
+After reading the files, you will have:
+- ✅ Complete list of project repositories
+- ✅ Location of the metaspecs repository
+- ✅ Base path to locate repositories
+- ✅ Configured task management system
+- ✅ Specific project configurations
+
+**🛑 DO NOT proceed without reading these files!** They contain critical information for the correct execution of the command.
+
 ## 🎯 Objective
 
 Ensure alignment with:
@@ -34,7 +71,7 @@ Run this command:
 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}/
+4. The metaspecs are located at: `{base_path}/{metaspecs-repo-id}/`
 
 ## 🔍 Validation Process
 
@@ -48,7 +85,7 @@ ls -la {base_path}/{metaspecs-repo-id}/
 
 ### 2. Business Validation
 
-If there are business metaspecs (`MetaSpecs repository (business section)`):
+If business metaspecs exist (`MetaSpecs repository (business section)`):
 
 ```markdown
 ## Business Validation
@@ -56,25 +93,25 @@ If there are business metaspecs (`MetaSpecs repository (business section)`):
 ### Product Strategy
 - **File**: `MetaSpecs repository (business section)PRODUCT_STRATEGY.md`
 - **Validation**: [Is this feature aligned with the strategy?]
-- **Status**: ✅ Aligned / ⚠️ Partially / ❌ Not aligned
+- **Status**: ✅ Aligned / ⚠️ Partial / ❌ Misaligned
 - **Notes**: [Observations]
 
 ### Personas
 - **File**: `MetaSpecs repository (business section)CUSTOMER_PERSONAS.md`
 - **Validation**: [Does it meet the correct persona?]
-- **Status**: ✅ Aligned / ⚠️ Partially / ❌ Not aligned
+- **Status**: ✅ Aligned / ⚠️ Partial / ❌ Misaligned
 - **Notes**: [Observations]
 
 ### Metrics
 - **File**: `MetaSpecs repository (business section)PRODUCT_METRICS.md`
 - **Validation**: [Is the success metric documented?]
-- **Status**: ✅ Aligned / ⚠️ Partially / ❌ Not aligned
+- **Status**: ✅ Aligned / ⚠️ Partial / ❌ Misaligned
 - **Notes**: [Observations]
 ```
 
 ### 3. Technical Validation
 
-If there are technical metaspecs (`MetaSpecs repository (technical section)`):
+If technical metaspecs exist (`MetaSpecs repository (technical section)`):
 
 ```markdown
 ## Technical Validation
@@ -128,14 +165,14 @@ If there are technical metaspecs (`MetaSpecs repository (technical section)`):
 
 ### 5. Conflict Identification
 
-If there are conflicts or misalignments:
+If conflicts or misalignments exist:
 
 ```markdown
 ## Identified Conflicts
 
 ### Conflict 1: [Description]
 - **Severity**: Critical / High / Medium / Low
-- **Metaspec**: [File being violated]
+- **Metaspec**: [Violated file]
 - **Description**: [Conflict details]
 - **Recommendation**: [How to resolve]
 
@@ -151,7 +188,7 @@ If there are justified deviations:
 ## Justified Exceptions
 
 ### Exception 1: [Description]
-- **Metaspec**: [File being deviated]
+- **Metaspec**: [Deviated file]
 - **Deviation**: [What is different]
 - **Justification**: [Why it is necessary]
 - **Approval**: [Who approved]
@@ -166,7 +203,7 @@ If there are justified deviations:
 - Use the appropriate MCP to add the report to the issue:
   - Add as a comment on the issue
   - Update labels/tags according to the result (e.g., "validated", "needs-adjustment", "blocked")
-  - If there are critical conflicts, update the issue status
+  - If critical conflicts exist, update the issue status
 - Inform the user: "✅ Validation report added to issue [ID]"
 
 **FALLBACK: Create .md file only if MCP fails**
@@ -212,7 +249,7 @@ If critical conflicts are found:
 2. 📝 **DOCUMENT** all conflicts
 3. 💬 **ALERT** the user and stakeholders
 4. **Via MCP**: Update issue status to "Blocked" or "Requires Adjustments"
-5. 🔄 **ADJUST** the plan/implementation as needed
+5. 🔄 **ADJUST** plan/implementation as needed
 6. ✅ **REVALIDATE** after adjustments
 
 ---

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

@@ -18,20 +18,57 @@ You are a product specialist responsible for collecting and documenting new idea
 
 ---
 
+## 📋 Project Setup
+
+**⚠️ IMPORTANT: Always read the project configuration files BEFORE running this command!**
+
+### Mandatory Files
+
+1. **`context-manifest.json`** (orchestrator root)
+   - List of project repositories
+   - Roles of each repository (metaspecs, application, etc.)
+   - URLs and dependencies between repositories
+
+2. **`ai.properties.md`** (orchestrator root)
+   - Project settings (`project_name`, `base_path`)
+   - Task management system (`task_management_system`)
+   - Credentials and specific configurations
+
+### How to Read
+
+```bash
+# 1. Read context-manifest.json
+cat context-manifest.json
+
+# 2. Read ai.properties.md
+cat ai.properties.md
+```
+
+### Essential Information
+
+After reading the files, you will have:
+- ✅ Complete list of project repositories
+- ✅ Location of the metaspecs repository
+- ✅ Base path to locate repositories
+- ✅ Configured task management system
+- ✅ Project-specific configurations
+
+**🛑 DO NOT proceed without reading these files!** They contain critical information for the correct execution of the command.
+
 ## Project Context
 
 Before starting, load the context by consulting:
 
-1. **Automatically Locate MetaSpecs**:
+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`
-   - The metaspecs are at: `{base_path}/{metaspecs-repo-id}/`
+   - The metaspecs are located at: `{base_path}/{metaspecs-repo-id}/`
    - Read the `index.md` files as reference
 
-2. **Project Structure**:
+2. **Project structure**:
    - `context-manifest.json` - List of repositories and their roles
-   - `README.md` of the involved repositories
+   - `README.md` of involved repositories
 
 ## Your Goal
 
@@ -87,14 +124,14 @@ Just ensure the idea is **adequately understood**.
    - Suggested priority
 
 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")
+   - Explain the rationale for the split (e.g., "This feature involves 3 distinct areas: authentication, processing, and notification")
    - Propose a **logical** split (by functionality, repository, layer, etc.)
-   - Example of splitting:
+   - Example split:
      ```
      Original Issue: "Complete payment system"
      
@@ -104,7 +141,7 @@ Just ensure the idea is **adequately understood**.
      - 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
@@ -112,10 +149,10 @@ Just ensure the idea is **adequately understood**.
 
 4. **User Approval**
    - Present the draft (or drafts, if split)
-   - Make adjustments based on feedback
+   - Make adjustments according to feedback
    - Obtain final approval
 
-5. **Saving the Issue**
+5. **Issue Saving**
 
    **PRIORITY 1: Use MCP (Model Context Protocol)**
    
@@ -134,8 +171,8 @@ Just ensure the idea is **adequately understood**.
    
    **FALLBACK: Create .md file only if MCP fails**
    
-   If MCP is unavailable or fails:
-   - Create a file at `./.sessions/<ISSUE-ID>/collect.md`
+   If MCP is not available or fails:
+   - Create a file in `./.sessions/<ISSUE-ID>/collect.md`
    - Use manual ID format: `LOCAL-001`, `LOCAL-002`, etc.
    - Include date, type, and full content
    - Inform the user: "⚠️ Issue saved locally in .sessions/ (task manager not available)"
@@ -157,7 +194,7 @@ Just ensure the idea is **adequately understood**.
 
 **For Improvements**:
 - What is working but can be improved?
-- What metric do we want to impact?
+- Which metric do we want to impact?
 - Is it a technical or business optimization?
 
 ---