@thatix.io/context-first-agents-cli 0.1.0 → 0.2.0

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

@@ -0,0 +1,237 @@
+# 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`**
+
+## Configuration
+
+Read `context-manifest.json` and `ai.properties.md` from the orchestrator to get repositories, base_path, and task_management_system.
+
+## 🎯 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 business metaspecs exist (`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 / ⚠️ Partial / ❌ Misaligned
+- **Notes**: [Observations]
+
+### Personas
+- **File**: `MetaSpecs repository (business section)CUSTOMER_PERSONAS.md`
+- **Validation**: [Does it meet the correct persona?]
+- **Status**: ✅ Aligned / ⚠️ Partial / ❌ Misaligned
+- **Notes**: [Observations]
+
+### Metrics
+- **File**: `MetaSpecs repository (business section)PRODUCT_METRICS.md`
+- **Validation**: [Is the success metric documented?]
+- **Status**: ✅ Aligned / ⚠️ Partial / ❌ Misaligned
+- **Notes**: [Observations]
+```
+
+### 3. Technical Validation
+
+If technical metaspecs exist (`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 conflicts or misalignments exist:
+
+```markdown
+## Identified Conflicts
+
+### Conflict 1: [Description]
+- **Severity**: Critical / High / Medium / Low
+- **Metaspec**: [Violated file]
+- **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**: [Deviated file]
+- **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 critical conflicts exist, 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** 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/templates/commands/en/products/collect.md

@@ -0,0 +1,170 @@
+# Idea and Requirements Gathering
+
+You are a product specialist 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 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 commit**
+
+**Next step**: `/refine [ISSUE-ID]` to refine the collected requirements.
+
+---
+
+## Configuration
+
+Read `context-manifest.json` and `ai.properties.md` from the orchestrator to get repositories, base_path, and task_management_system.
+
+## 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 a complete specification
+- ❌ Validate against metaspecs (this is done in `/refine` or `/spec`)
+- ❌ Detail technical implementation
+
+Just ensure 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 is important]
+
+## Type
+- [ ] New Feature
+- [ ] Existing Feature Improvement
+- [ ] Bug
+- [ ] Tech Debt
+- [ ] Documentation
+
+## Additional Context
+[Relevant information: where the bug occurs, inspiration for the feature, etc.]
+
+## Affected Repositories
+[List which project repositories will be impacted]
+
+## Suggested Priority
+- [ ] 🔴 Critical
+- [ ] 🟡 High
+- [ ] 🟢 Medium
+- [ ] ⚪ Low (Backlog)
+```
+
+## Collection Process
+
+1. **Initial Understanding**
+   - Ask clarification questions if needed
+   - Identify: Is it a new feature? Improvement? Bug?
+   - Identify which repositories will be affected
+
+2. **Issue Draft**
+   - Clear title (max 10 words)
+   - Objective description (2-3 paragraphs)
+   - Relevant additional context
+   - Affected repositories
+   - 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 the split (e.g., "This feature involves 3 distinct areas: authentication, processing, and notification")
+   - Propose a **logical** split (by functionality, repository, layer, etc.)
+   - Example split:
+     ```
+     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 according to feedback
+   - Obtain final approval
+
+5. **Issue Saving**
+
+   **PRIORITY 1: Use MCP (Model Context Protocol)**
+
+   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
+   - If `task_management_system=azure`: Use Azure Boards MCP to create the issue
+
+   **When using MCP:**
+   - Create the issue directly in the task manager
+   - Obtain the created issue ID (e.g., FIN-123, LIN-456)
+   - Inform the user: "✅ Issue [ID] created in [task manager]"
+   - **DO NOT create a .md file**
+
+   **FALLBACK: Create .md file only if MCP fails**
+
+   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)"
+
+## Clarification Questions
+
+**For Features**:
+- What problem does it solve?
+- Who benefits?
+- Is it a visible functionality or infrastructure?
+- Is it related to any existing feature?
+- Which repositories need modification?
+
+**For Bugs**:
+- Where does the bug occur? (repository, component, flow)
+- How to reproduce?
+- Expected vs current behavior?
+- Severity of impact?
+
+**For Improvements**:
+- What is working but can be improved?
+- Which metric do we want to impact?
+- Is it a technical or business optimization?
+
+---
+
+**Provided arguments**:
+
+```
+#$ARGUMENTS
+```
+
+---
+
+## 🎯 Next Step
+
+After approval and saving the issue:
+
+```bash
+/refine [ISSUE-ID]
+```
+
+This command will transform the collected issue into refined and validated requirements.

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

@@ -0,0 +1,231 @@
+# Requirements Refinement
+
+You are a product expert responsible for helping to refine requirements for the project.
+
+## ⚠️ IMPORTANT: This Command DOES NOT Implement Code
+
+**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 run tests or deploy**
+
+**Next step**: `/spec [ISSUE-ID]` to create a complete PRD based on the refined requirements.
+
+---
+
+## Configuration
+
+Read `context-manifest.json` and `ai.properties.md` from the orchestrator to get repositories, base_path, and task_management_system.
+
+## Objective
+
+Transform an initial requirement into a refined and validated specification, ready to become a complete PRD.
+
+## Process
+
+### 1. Clarification Phase
+
+Read the initial requirement and ask questions to achieve full clarity about:
+- **Goal**: 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?
+
+Keep asking questions until you have complete understanding.
+
+### 2. Validation Against Metaspecs
+
+**IMPORTANT**: First read `ai.properties.md` to get the `base_path`. The indexes should ALREADY be in context (you ran `/warm-up`). Consult the indexes and read ONLY relevant documents to validate the requirement.
+
+**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 violations are identified**: 🛑 **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
+- **Goal**: Why build it (1-2 sentences)
+- **Business Value**: Metric, persona, roadmap phase (consult metaspecs)
+- **Scope**: What IS included and what IS NOT included
+- **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 Split**:
+
+**If 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 that can be implemented independently")
+- Propose a **logical** split based on:
+  - Independent functionalities
+  - Different repositories
+  - Application layers (backend, frontend, infra)
+  - Implementation phases (MVP, improvements, optimizations)
+- Example split:
+  ```
+  Original Issue: "Multi-channel notification system"
+
+  Suggested Split:
+  - 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**: Final decision is the user's - they may accept the split or keep it as a single issue
+
+**If the user accepts the split**:
+- Document each issue separately
+- Add cross-references between related issues
+- Suggest implementation order if dependencies exist
+- Each split issue must go through the same refinement process
+
+Request user approval and incorporate feedback if needed.
+
+**Tip**: You may search the codebase or internet before finalizing, if necessary.
+
+### 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
+     - For Azure Boards: Use Azure Boards MCP with `description` 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**:
+- 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. Consult `{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 patterns, 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, tests, security, etc.)
+
+**Task Manager Template**:
+```markdown
+# [Feature Name] - Refined Requirements
+
+**Sprint X** | **Y days** | **Priority**
+
+## Goal
+[1-2 paragraphs: what it is and why]
+
+## Scope
+
+### Main Features
+- Feature 1: [summary]
+- Feature 2: [summary]
+- Validations/Guards: [summary]
+
+### Affected Components
+- Component 1: [type of change]
+- Component 2: [type of change]
+
+### Security
+✅ [item 1] ✅ [item 2] ✅ [item 3]
+
+## Negative Scope
+❌ [item 1] ❌ [item 2] ❌ [item 3]
+
+## Stack
+[Tech stack summarized by area]
+
+## Structure
+[SUMMARIZED file tree - main modules only]
+
+## Failure Modes (Avoid)
+🔴 [critical 1] 🔴 [critical 2]
+🟡 [medium 1] 🟡 [medium 2]
+
+## Acceptance Criteria
+- [ ] [item 1]
+- [ ] [item 2]
+- [ ] [item 3]
+
+## Validation
+**ADRs**: [list]
+**Specs**: [main]
+**Status**: ✅ Approved
+
+**Impact**: [summary]
+**Limitations**: [summary]
+
+---
+📄 **Full document**: `.sessions/<ISSUE-ID>/refined.md`
+```
+
+**Audience**: AI Developer with capabilities similar to yours. Be concise but complete.
+
+---
+
+**Requirement to Refine**:
+
+```
+#$ARGUMENTS
+```
+
+---
+
+## 🎯 Next Step
+
+**After user approval and saving the refined requirements**, the natural flow is:
+
+```bash
+/spec [ISSUE-ID]
+```
+
+**Example**: `/spec FIN-3`
+
+This command will create a PRD (Product Requirements Document) complete based on the refined requirements, detailing features, user stories, acceptance criteria, and final validations.