context-first-cli 1.8.2 → 2.0.0

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

@@ -0,0 +1,197 @@
+# Work Execution
+
+This command executes a unit of work in the current workspace, implementing part of the technical plan.
+
+## 📋 Prerequisites
+
+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 files `.sessions/<ISSUE-ID>/` available:
+  - `context.md` (immutable)
+  - `architecture.md` (immutable)
+  - `plan.md` (mutable)
+
+## 📍 IMPORTANT: Understand the Structure
+
+**Workspace** (where you work):
+```
+<orchestrator>/.sessions/<ISSUE-ID>/
+├── repo-1/          # worktree with branch feature/<ISSUE-ID>
+├── repo-2/          # worktree with branch feature/<ISSUE-ID>
+├── context.md       # context (immutable)
+├── architecture.md  # architecture (immutable)
+└── plan.md          # plan (mutable)
+```
+
+**Main repositories** (DO NOT touch):
+```
+{base_path}/repo-1/  # main repo (branch main/master)
+{base_path}/repo-2/  # main repo (branch main/master)
+```
+
+**GOLDEN RULE**:
+- ✅ Work ONLY inside `<orchestrator>/.sessions/<ISSUE-ID>/`
+- ✅ Make commits in the worktrees inside the workspace
+- ❌ NEVER checkout branches in the main repositories
+- ❌ NEVER navigate to `{base_path}/{repo-id}/`
+
+## ⚠️ IMPORTANT: Immutable Files
+
+**This command must READ but NOT MODIFY:**
+- ✅ **READ** `.sessions/<ISSUE-ID>/context.md` (immutable)
+- ✅ **READ** `.sessions/<ISSUE-ID>/architecture.md` (immutable)
+- ✅ **UPDATE** `.sessions/<ISSUE-ID>/plan.md` (mark progress)
+- ✅ **IMPLEMENT** code in the workspace repositories
+- ✅ **MAKE COMMITS** in the workspace repositories
+- ❌ **DO NOT modify `context.md` or `architecture.md`**
+- ❌ **DO NOT checkout branches in the main repositories (outside the workspace)**
+
+## 📚 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 the relevant `index.md` files during implementation to:
+   - Follow coding standards
+   - Respect defined architecture
+   - Use correct conventions
+
+## 🎯 Objective
+
+Implement a specific unit of work from the plan, which may involve:
+- Creating new files/components
+- Modifying existing files
+- Adding tests
+- Updating documentation
+
+## 📝 Work Process
+
+### 1. Identify Unit of Work
+
+Based on the technical plan (`./.sessions/<ISSUE-ID>/plan.md`), identify:
+- Which specific task will be implemented now
+- In which workspace repository(ies)
+- Which files will be created/modified
+- Dependencies with other tasks
+
+### 2. Implementation
+
+**IMPORTANT**: Work ONLY inside the workspace at `.sessions/<ISSUE-ID>/`
+
+For each repository in the workspace:
+
+```bash
+# Navigate to the worktree inside the workspace
+cd <orchestrator>/.sessions/<ISSUE-ID>/<repo-name>/
+
+# Verify you are on the correct branch
+git branch  # should show * feature/<ISSUE-ID>
+
+# Implement the code here
+```
+
+Perform the implementation following:
+- **Project standards**: Consult style and architecture guides
+- **Approved stack**: Use only technologies documented in the metaspecs
+- **Tests**: Implement tests according to project standards
+- **Documentation**: Update comments and docs when necessary
+
+### 3. Local Validation
+
+Before committing:
+- Run unit/integration tests
+- Check linting and formatting
+- Confirm that existing functionality is not broken
+
+### 4. Commit
+
+For each modified repository **inside the workspace**:
+
+```bash
+# Navigate to the worktree inside the workspace
+cd <orchestrator>/.sessions/<ISSUE-ID>/<repo-name>/
+
+# Add changes
+git add .
+
+# Commit
+git commit -m "type: concise description
+
+- Detail 1
+- Detail 2
+
+Refs: <ISSUE-ID>"
+```
+
+**Commit types**: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`
+
+### 5. Update Plan.md
+
+**FOR EACH completed task**, update `./.sessions/<ISSUE-ID>/plan.md`:
+
+```markdown
+#### 1.1 - [Task Name] [Completed ✅]
+- [Detail 1]
+- [Detail 2]
+- [Detail 3]
+
+**Files**:
+- `path/to/file1.ts` ✅
+- `path/to/file2.vue` ✅
+
+**Tests**:
+- Unit test: [Description] ✅
+- Integration test: [Description] ✅
+
+**Comments**:
+- Decision: [Explanation of important technical decision]
+- Learning: [Something learned during implementation]
+```
+
+**Mark task status**:
+- `[Not Started ⏳]` - Task not started yet
+- `[In Progress ⏰]` - Task currently being worked on
+- `[Completed ✅]` - Task finished and validated
+
+## 🔍 Quality Checklist
+
+Before considering the unit complete:
+- [ ] Code implemented and tested
+- [ ] Tests passing
+- [ ] Linting/formatting OK
+- [ ] Documentation updated (if necessary)
+- [ ] Commit made in all affected repos
+- [ ] `plan.md` updated with progress and comments
+
+## ⚠️ Jidoka Principle
+
+If you encounter problems during implementation:
+1. 🛑 **STOP** the implementation
+2. 📝 **DOCUMENT** the problem found
+3. 💬 **ALERT** the user and discuss solutions
+4. 🔄 **ADJUST** the plan if necessary
+
+---
+
+**Provided arguments**:
+
+```
+#$ARGUMENTS
+```
+
+---
+
+## 🎯 Next Steps
+
+- **Continue implementation**: Run `/work` again for the next unit
+- **Finish feature**: When everything is implemented, run `/pre-pr`
+
+## 💡 Tips
+
+- Work in small, incremental units
+- Commit frequently (atomic commits)
+- Document important decisions in the session
+- Keep repositories synchronized with each other

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

@@ -0,0 +1,233 @@
+# Validation Against MetaSpecs
+
+This command validates requirements, decisions, or implementations against the project's metaspecs.
+
+## ⚠️ IMPORTANT: Mode of Operation
+
+**This command is for VALIDATION:**
+- ✅ Validate against metaspecs
+- ✅ **READ** files from repositories (read-only)
+- ✅ Generate validation report
+- ❌ **DO NOT checkout branches in main repositories**
+- ❌ **DO NOT modify code**
+- ❌ **DO NOT modify `context.md` or `architecture.md`**
+
+## 🎯 Objective
+
+Ensure alignment with:
+- Product strategy
+- Technical architecture
+- Standards and conventions
+- ADRs (Architecture Decision Records)
+
+## 📋 When to Use
+
+Run this command:
+- After `/spec` - validate PRD
+- After `/plan` - validate technical plan
+- During `/work` - validate implementation decisions
+- Before `/pr` - final validation
+
+## 📚 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}/
+
+## 🔍 Validation Process
+
+### 1. Identify Available MetaSpecs
+
+Navigate to the metaspecs directory and identify which metaspecs exist:
+
+```bash
+ls -la {base_path}/{metaspecs-repo-id}/
+```
+
+### 2. Business Validation
+
+If there are business metaspecs (`MetaSpecs repository (business section)`):
+
+```markdown
+## Business Validation
+
+### Product Strategy
+- **File**: `MetaSpecs repository (business section)PRODUCT_STRATEGY.md`
+- **Validation**: [Is this feature aligned with the strategy?]
+- **Status**: ✅ Aligned / ⚠️ Partially / ❌ Not aligned
+- **Notes**: [Observations]
+
+### Personas
+- **File**: `MetaSpecs repository (business section)CUSTOMER_PERSONAS.md`
+- **Validation**: [Does it meet the correct persona?]
+- **Status**: ✅ Aligned / ⚠️ Partially / ❌ Not aligned
+- **Notes**: [Observations]
+
+### Metrics
+- **File**: `MetaSpecs repository (business section)PRODUCT_METRICS.md`
+- **Validation**: [Is the success metric documented?]
+- **Status**: ✅ Aligned / ⚠️ Partially / ❌ Not aligned
+- **Notes**: [Observations]
+```
+
+### 3. Technical Validation
+
+If there are technical metaspecs (`MetaSpecs repository (technical section)`):
+
+```markdown
+## Technical Validation
+
+### Technology Stack
+- **File**: `MetaSpecs repository (technical section)meta/stack.md`
+- **Validation**: [Uses only approved technologies?]
+- **Status**: ✅ Compliant / ⚠️ Justified exception / ❌ Non-compliant
+- **Notes**: [Technologies used and justifications]
+
+### Architecture
+- **File**: `MetaSpecs repository (technical section)ARCHITECTURE.md`
+- **Validation**: [Follows architectural standards?]
+- **Status**: ✅ Compliant / ⚠️ Partial / ❌ Non-compliant
+- **Notes**: [Observations]
+
+### ADRs (Architecture Decision Records)
+- **Directory**: `MetaSpecs repository (technical section)adr/`
+- **Validation**: [Respects documented architectural decisions?]
+- **Relevant ADRs**: [List of verified ADRs]
+- **Status**: ✅ Compliant / ⚠️ Minor conflict / ❌ Critical conflict
+- **Notes**: [Observations]
+
+### Business Rules
+- **File**: `MetaSpecs repository (technical section)BUSINESS_LOGIC.md`
+- **Validation**: [Implements business rules correctly?]
+- **Status**: ✅ Compliant / ⚠️ Partial / ❌ Non-compliant
+- **Notes**: [Observations]
+```
+
+### 4. Standards Validation
+
+```markdown
+## Standards Validation
+
+### Code
+- **File**: `MetaSpecs repository (technical section)CODE_STANDARDS.md`
+- **Validation**: [Follows code standards?]
+- **Status**: ✅ Compliant / ⚠️ Minor deviations / ❌ Non-compliant
+
+### Tests
+- **File**: `MetaSpecs repository (technical section)TEST_STANDARDS.md`
+- **Validation**: [Adequate testing strategy?]
+- **Status**: ✅ Compliant / ⚠️ Partial / ❌ Non-compliant
+
+### Documentation
+- **File**: `MetaSpecs repository (technical section)DOC_STANDARDS.md`
+- **Validation**: [Adequate documentation?]
+- **Status**: ✅ Compliant / ⚠️ Partial / ❌ Non-compliant
+```
+
+### 5. Conflict Identification
+
+If there are conflicts or misalignments:
+
+```markdown
+## Identified Conflicts
+
+### Conflict 1: [Description]
+- **Severity**: Critical / High / Medium / Low
+- **Metaspec**: [File being violated]
+- **Description**: [Conflict details]
+- **Recommendation**: [How to resolve]
+
+### Conflict 2: [Description]
+[Same format as above]
+```
+
+### 6. Justified Exceptions
+
+If there are justified deviations:
+
+```markdown
+## Justified Exceptions
+
+### Exception 1: [Description]
+- **Metaspec**: [File being deviated]
+- **Deviation**: [What is different]
+- **Justification**: [Why it is necessary]
+- **Approval**: [Who approved]
+- **Documentation**: [Where it was documented]
+```
+
+## 📄 Saving the Validation Report
+
+**PRIORITY 1: Use MCP (Model Context Protocol)**
+
+- Read `ai.properties.md` from the orchestrator to identify the `task_management_system`
+- 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
+- Inform the user: "✅ Validation report added to issue [ID]"
+
+**FALLBACK: Create .md file only if MCP fails**
+
+If MCP is unavailable or fails, create `./.sessions/<ISSUE-ID>/check-report.md`:
+
+```markdown
+# Validation Report - [ISSUE-ID]
+
+**Date**: [date/time]
+**Phase**: [spec/plan/work/pre-pr]
+
+## Overall Status
+✅ Validated / ⚠️ Validated with reservations / ❌ Not validated
+
+## Validations Performed
+- Business: ✅ / ⚠️ / ❌
+- Technical: ✅ / ⚠️ / ❌
+- Standards: ✅ / ⚠️ / ❌
+
+## Conflicts
+[List of conflicts, if any]
+
+## Exceptions
+[List of justified exceptions, if any]
+
+## Recommendations
+1. [Recommendation 1]
+2. [Recommendation 2]
+
+## Approval
+- [ ] Approved to proceed
+- [ ] Requires adjustments
+- [ ] Blocked
+```
+
+Inform the user: "⚠️ Report saved locally in .sessions/ (task manager not available)"
+
+## 🚨 Action in Case of Conflicts
+
+If critical conflicts are found:
+1. 🛑 **STOP** the current process
+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
+6. ✅ **REVALIDATE** after adjustments
+
+---
+
+**Provided arguments**:
+
+```
+#$ARGUMENTS
+```
+
+---
+
+## 🎯 Outcome
+
+After validation:
+- If ✅: Proceed to the next phase
+- If ⚠️: Document reservations and proceed with approval
+- If ❌: Fix conflicts before proceeding

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

@@ -0,0 +1,156 @@
+# Idea and Requirements Collection
+
+You are a product expert responsible for collecting and documenting new ideas, features, or bugs.
+
+## ⚠️ 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
+- ✅ **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**
+
+**Next step**: `/refine [ISSUE-ID]` to refine the collected requirements.
+
+---
+
+## Project Context
+
+Before starting, load the context by consulting:
+
+1. **Locate MetaSpecs automatically**:
+   - Read `context-manifest.json` from 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
+
+2. **Project structure**:
+   - `context-manifest.json` - List of repositories and their functions
+   - `README.md` of involved repositories
+
+## Your Objective
+
+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
+- ❌ Validate against metaspecs (this is done in `/refine` or `/spec`)
+- ❌ Detail technical implementation
+
+Just make sure the idea is **adequately understood**.
+
+## Issue Format
+
+```markdown
+# [Clear and Descriptive Title]
+
+## Description
+[2-3 paragraphs explaining what the feature/bug is and why it's important]
+
+## Type
+- [ ] New Feature
+- [ ] Existing Feature Improvement
+- [ ] Bug
+- [ ] Tech Debt
+- [ ] Documentation
+
+## Additional Context
+[Relevant information: where the bug occurs, feature inspiration, etc.]
+
+## Affected Repositories
+[List which project repositories will be impacted]
+
+## Suggested Priority
+- [ ] 🔴 Critical
+- [ ] 🟡 High
+- [ ] 🟢 Medium
+- [ ] ⚪ Low (Backlog)
+```
+
+## Collection Process
+
+1. **Initial Understanding**
+   - Ask clarifying 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)
+   - Objective description (2-3 paragraphs)
+   - Relevant additional context
+   - Affected repositories
+   - Suggested priority
+
+3. **User Approval**
+   - Present the draft
+   - Make adjustments based on feedback
+   - Obtain final approval
+
+4. **Issue Saving**
+
+   **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`
+   - 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)
+   - Inform the user: "✅ Issue [ID] created in [task manager]"
+   - **DO NOT create .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`
+   - Use manual ID format: `LOCAL-001`, `LOCAL-002`, etc.
+   - Include date, type, and complete content
+   - Inform the user: "⚠️ Issue saved locally in .sessions/ (task manager not available)"
+
+## Clarifying Questions
+
+**For Features**:
+- What problem does it solve?
+- Who benefits?
+- Is it visible functionality or infrastructure?
+- Is it related to any existing feature?
+- Which repositories need to be modified?
+
+**For Bugs**:
+- Where does the bug occur? (repository, component, flow)
+- How to reproduce?
+- What is the expected vs actual behavior?
+- Impact severity?
+
+**For Improvements**:
+- What is working but can improve?
+- Which metric do we want to impact?
+- Is it technical or business optimization?
+
+---
+
+**Provided arguments**:
+
+```
+#$ARGUMENTS
+```
+
+---
+
+## 🎯 Next Step
+
+After approval and issue saving:
+
+```bash
+/refine [ISSUE-ID]
+```
+
+This command will transform the collected issue into refined and validated requirements.