@thatix.io/context-first-agents-cli 0.1.1 → 0.2.1

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

@@ -0,0 +1,256 @@
+# 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)
+
+## Configuration
+
+Read `context-manifest.json` and `ai.properties.md` from the orchestrator to get repositories, base_path, and task_management_system.
+
+## 📍 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>/`
+- ✅ Commit in the worktrees inside the workspace
+- ❌ NEVER checkout branches in the main repositories
+- ❌ NEVER navigate to `{base_path}/{repo-id}/`
+
+## 🛑 CRITICAL: WHERE TO CREATE CODE
+
+**⚠️ ATTENTION: ALL CODE MUST BE CREATED INSIDE THE REPOSITORY WORKTREE!**
+
+**✅ CORRECT** - Create code inside the worktree:
+```
+<orchestrator>/.sessions/<ISSUE-ID>/<repo-name>/src/file.ts  ✅
+<orchestrator>/.sessions/<ISSUE-ID>/<repo-name>/tests/test.ts  ✅
+<orchestrator>/.sessions/<ISSUE-ID>/<repo-name>/package.json  ✅
+```
+
+**❌ WRONG** - NEVER create code directly in .sessions:
+```
+<orchestrator>/.sessions/src/file.ts  ❌
+<orchestrator>/.sessions/<ISSUE-ID>/src/file.ts  ❌
+<orchestrator>/.sessions/<ISSUE-ID>/file.ts  ❌
+```
+
+**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 repository's worktree
+
+## ⚠️ 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 **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 workspace)**
+- 🛑 **NEVER create code directly in `.sessions/` or `.sessions/<ISSUE-ID>/`**
+
+## 📚 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 at: `{base_path}/{metaspecs-repo-id}/`
+5. Read 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
+
+**⚠️ IMPORTANT: PROGRESS CONTROL**
+
+This command executes the work in **incremental phases**. After completing each **MAIN PHASE** (e.g., Phase 1 → Phase 2):
+
+1. 🛑 **STOP** execution
+2. 📊 **PRESENT** a summary of what was done
+3. ❓ **ASK** the developer if they want to:
+   - Review the implemented code
+   - Make adjustments before continuing
+   - Proceed to the next phase
+
+**IMPORTANT**:
+- ✅ **PAUSE** between main phases (Phase 1 → Phase 2 → Phase 3)
+- ❌ **DO NOT pause** between subphases (Phase 1.1 → Phase 1.2 → Phase 1.3)
+
+**DO NOT implement everything at once**. Work main phase by main phase, awaiting developer confirmation.
+
+---
+
+### 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 repository(ies) of the workspace
+- Which files will be created/modified
+- Dependencies with other tasks
+
+### 2. Implementation
+
+
+
+**IMPORTANT**: Work ONLY inside the workspace `.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
+```
+
+Execute 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 no existing functionality is broken
+
+
+
+### 4. Commit
+
+For each repository modified **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`
+
+**⚠️ MANDATORY PAUSE**: After completing the ENTIRE main phase (identification + implementation + validation + commit + plan.md update), **STOP** and show the developer:
+- Complete summary of the phase
+- Files created/modified
+- Commits made
+- Ask if they want to review or proceed to the next phase
+
+### 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,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/dist/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.