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

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

@@ -0,0 +1,273 @@
+# Specification Creation (PRD)
+
+This command creates the complete specification (Product Requirements Document) for the feature.
+
+## ⚠️ IMPORTANT: This Command DOES NOT Implement Code
+
+**This command is ONLY for requirements documentation:**
+- ✅ Create PRD (Product Requirements Document)
+- ✅ Update issue in the task manager via MCP
+- ✅ **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**: `/orchestrate <ISSUE-ID>` to derive the agent graph and execute (recommended). `/start` remains a manual escape hatch.
+
+---
+
+## Configuration
+
+Read `context-manifest.json` and `ai.properties.md` from the orchestrator to get repositories, base_path, and task_management_system.
+
+## 📋 Prerequisites
+
+- Issue refined via `/refine`
+- Approval to proceed with the feature
+
+## 📚 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 ensure compliance with:
+   - System architecture
+   - Design patterns
+   - Technical constraints
+   - Project conventions
+
+## 🎯 Objective
+
+Create a complete PRD that will serve as the single source of truth for implementation.
+
+## 📝 PRD Structure
+
+### 1. Overview
+
+```markdown
+# [Feature Title]
+
+## Context
+[Why are we building this? What problem does it solve?]
+
+## Objective
+[What do we want to achieve with this feature?]
+
+## Success Metrics
+- [Metric 1]: [How to measure]
+- [Metric 2]: [How to measure]
+```
+
+### 2. Functional Requirements
+
+```markdown
+## Functional Requirements
+
+### RF-01: [Requirement Name]
+**Description**: [Detailed description]
+**Priority**: Must Have / Should Have / Could Have
+**Repositories**: [affected repos]
+
+### RF-02: [Requirement Name]
+**Description**: [Detailed description]
+**Priority**: Must Have / Should Have / Could Have
+**Repositories**: [affected repos]
+```
+
+### 3. Non-Functional Requirements
+
+```markdown
+## Non-Functional Requirements
+
+### Performance
+- [Performance requirement]
+
+### Security
+- [Security requirement]
+
+### Accessibility
+- [Accessibility requirement]
+
+### Scalability
+- [Scalability requirement]
+```
+
+### 4. User Flows
+
+```markdown
+## User Flows
+
+### Main Flow
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+### Alternative Flows
+**Scenario**: [Scenario name]
+1. [Step 1]
+2. [Step 2]
+
+### Error Handling
+**Error**: [Error type]
+**Behavior**: [How the system should react]
+```
+
+### 5. Technical Specification
+
+```markdown
+## Technical Specification
+
+### Architecture
+
+#### <repo-1>
+- **New components**: [list]
+- **Modified components**: [list]
+- **APIs**: [new/modified endpoints]
+
+#### <repo-2>
+- **New components**: [list]
+- **Modified components**: [list]
+- **APIs**: [new/modified endpoints]
+
+### Integrations
+- **Between repos**: [how repos communicate]
+- **External**: [external APIs, if any]
+
+### Data Model
+[Describe changes to data model, if any]
+```
+
+### 6. Acceptance Criteria
+
+```markdown
+## Acceptance Criteria
+
+### Functional
+- [ ] [Specific and testable criterion]
+- [ ] [Specific and testable criterion]
+
+### Technical
+- [ ] Unit tests with coverage >= X%
+- [ ] Integration tests implemented
+- [ ] Performance within requirements
+- [ ] Documentation updated
+
+### Quality
+- [ ] Code review approved
+- [ ] No regressions
+- [ ] Accessibility validated
+```
+
+### 7. Out of Scope
+
+```markdown
+## Out of Scope
+
+Features that will NOT be implemented in this version:
+- [Item 1]
+- [Item 2]
+
+Justification: [Why these are deferred]
+```
+
+### 8. Risks and Mitigations
+
+```markdown
+## Risks and Mitigations
+
+### Risk 1: [Description]
+- **Probability**: High / Medium / Low
+- **Impact**: High / Medium / Low
+- **Mitigation**: [How to mitigate]
+
+### Risk 2: [Description]
+- **Probability**: High / Medium / Low
+- **Impact**: High / Medium / Low
+- **Mitigation**: [How to mitigate]
+```
+
+### 9. Dependencies
+
+```markdown
+## Dependencies
+
+### Technical
+- [Technical dependency 1]
+- [Technical dependency 2]
+
+### Business
+- [Business dependency 1]
+- [Business dependency 2]
+
+### Blockers
+- [Blocker 1 and plan to resolve]
+```
+
+### 10. Test Plan
+
+```markdown
+## Test Plan
+
+### Unit Tests
+- [Area 1 to be tested]
+- [Area 2 to be tested]
+
+### Integration Tests
+- [Scenario 1]
+- [Scenario 2]
+
+### Manual Tests
+- [Scenario 1]
+- [Scenario 2]
+```
+
+## 📄 Saving the PRD
+
+**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 update the issue with the PRD:
+  - Add the complete PRD as a comment on the issue
+  - Or attach as a file (if the task manager supports it)
+  - Update status/labels (e.g., "spec-ready", "ready-for-dev")
+- Inform the user: "✅ PRD added to issue [ID]"
+
+**FALLBACK: Create .md file only if MCP fails**
+
+If MCP is unavailable or fails:
+- Save to `./.sessions/<ISSUE-ID>/prd.md`
+- Inform the user: "⚠️ PRD saved locally in .sessions/ (task manager not available)"
+
+## 🔍 Review and Approval
+
+Before finishing:
+1. Review the PRD with stakeholders
+2. Validate against metaspecs (if available)
+3. Obtain approval to start implementation
+4. **Via MCP**: Update the issue in the task manager with status "Ready for Development"
+5. **Fallback**: Document approval in `./.sessions/<ISSUE-ID>/prd.md`
+
+---
+
+**Provided arguments**:
+
+```
+#$ARGUMENTS
+```
+
+---
+
+## 🎯 Next Step
+
+After PRD approval, run:
+
+```bash
+/orchestrate <ISSUE-ID>
+```
+
+This derives the minimum agent graph from the spec and executes it. `/start` + `/plan` + `/work` remain available as manual escape hatches.
+
+This command will start feature development.

package/dist/templates/commands/en/quality/metrics.md

@@ -0,0 +1,266 @@
+# Quality Metrics
+
+This command collects and analyzes quality metrics of the code and the development process.
+
+## 🎯 Objective
+
+Measure and document the quality of the implementation through objective metrics:
+- Test coverage
+- Code complexity
+- Technical debt
+- Performance
+- Compliance with standards
+
+## Configuration
+
+Read `context-manifest.json` and `ai.properties.md` from the orchestrator to get repositories, base_path, and task_management_system.
+
+## 📋 Prerequisites
+
+- Implementation completed (after `/work`)
+- Tests implemented
+- Build working
+
+## 📊 Metrics to Collect
+
+### 1. Test Coverage
+
+For each modified repository:
+
+```bash
+cd <repository>
+
+# Run tests with coverage (examples by stack):
+# Node.js: npm run test:coverage / jest --coverage
+# Python: pytest --cov=src tests/
+# Java: mvn jacoco:report / gradle jacocoTestReport
+# Go: go test -cover ./...
+# Ruby: rspec --coverage
+# Rust: cargo tarpaulin
+# PHP: ./vendor/bin/phpunit --coverage-html coverage/
+# C#: dotnet test /p:CollectCoverage=true
+
+# Capture results
+```
+
+Document:
+```markdown
+## Test Coverage
+
+### <repo-1>
+- **Total Coverage**: X%
+- **Statements**: X%
+- **Branches**: X%
+- **Functions**: X%
+- **Lines**: X%
+- **Uncovered Files**: [list]
+
+### <repo-2>
+[Same format]
+```
+
+### 2. Code Complexity
+
+Analyze the cyclomatic complexity of modified files:
+
+```markdown
+## Code Complexity
+
+### Files with High Complexity
+- **file1.ts**: Complexity 15 (recommended: < 10)
+- **file2.ts**: Complexity 12
+
+### Recommendations
+- [Refactoring suggestion 1]
+- [Refactoring suggestion 2]
+```
+
+### 3. Code Quality
+
+```bash
+# Run linting (examples by stack):
+# Node.js: npm run lint / eslint .
+# Python: flake8 . / pylint src/
+# Java: mvn checkstyle:check
+# Go: golangci-lint run
+# Ruby: rubocop
+# Rust: cargo clippy
+
+# Check formatting (examples by stack):
+# Node.js: prettier --check .
+# Python: black --check .
+# Java: mvn formatter:validate
+# Go: gofmt -l .
+# Ruby: rubocop --format-only
+# Rust: cargo fmt --check
+
+# Static analysis (examples by stack):
+# Node.js: npm run analyze (if configured)
+# Python: mypy src/ / bandit -r src/
+# Java: mvn pmd:check / spotbugs:check
+# Go: go vet ./...
+# Ruby: brakeman (for Rails)
+# Rust: cargo audit
+```
+
+Document:
+```markdown
+## Code Quality
+
+### Linting
+- **Errors**: 0
+- **Warnings**: X
+- **Justified Warnings**: [list with justifications]
+
+### Formatting
+- **Status**: ✅ Compliant / ⚠️ Adjustments needed
+
+### Static Analysis
+- **Critical Issues**: 0
+- **Medium Issues**: X
+- **Low Issues**: Y
+```
+
+### 4. Performance
+
+If applicable, measure performance:
+
+```markdown
+## Performance
+
+### Benchmarks
+- **Operation X**: Yms (baseline: Zms)
+- **Operation Y**: Yms (baseline: Zms)
+
+### Applied Optimizations
+- [Optimization 1 and impact]
+- [Optimization 2 and impact]
+
+### Identified Bottlenecks
+- [Bottleneck 1 and mitigation plan]
+```
+
+### 5. Size and Impact
+
+```markdown
+## Size and Impact
+
+### Lines of Code
+- **Added**: +X lines
+- **Removed**: -Y lines
+- **Modified**: Z lines
+
+### Files
+- **New**: X files
+- **Modified**: Y files
+- **Removed**: Z files
+
+### Dependencies
+- **New dependencies**: [list]
+- **Bundle size**: +X KB
+```
+
+### 6. Technical Debt
+
+Identify technical debt introduced or resolved:
+
+```markdown
+## Technical Debt
+
+### Debt Introduced
+- **Item 1**: [Description and justification]
+  - Severity: High / Medium / Low
+  - Resolution plan: [when and how to resolve]
+
+### Debt Resolved
+- **Item 1**: [What was resolved]
+  - Impact: [improvement achieved]
+```
+
+## 📄 Metrics Report
+
+Create `./.sessions/<ISSUE-ID>/metrics.md`:
+
+```markdown
+# Metrics Report - [ISSUE-ID]
+
+**Date**: [date/time]
+**Repositories**: [list]
+
+## Executive Summary
+
+- **Test Coverage**: X% (goal: Y%)
+- **Code Quality**: ✅ / ⚠️ / ❌
+- **Performance**: ✅ / ⚠️ / ❌
+- **Technical Debt**: Low / Medium / High
+
+## Detailed Metrics
+
+[Include all sections above]
+
+## Comparison with Baseline
+
+| Metric | Before | After | Variation |
+|--------|--------|-------|-----------|
+| Coverage | X% | Y% | +Z% |
+| Average Complexity | X | Y | +Z |
+| Bundle Size | X KB | Y KB | +Z KB |
+
+## Recommended Actions
+
+1. [Action 1 - high priority]
+2. [Action 2 - medium priority]
+3. [Action 3 - low priority]
+
+## Approval for Merge
+
+- [ ] Test coverage >= goal
+- [ ] No critical quality issues
+- [ ] Performance within requirements
+- [ ] Technical debt documented and approved
+```
+
+## 🎯 Quality Goals
+
+If the project has goals defined in metaspecs, validate:
+
+```markdown
+## Validation against Goals
+
+### Project Goals
+- **Minimum coverage**: 80%
+- **Maximum complexity**: 10
+- **Performance**: < 100ms
+
+### Status
+- Coverage: ✅ 85% (goal: 80%)
+- Complexity: ⚠️ 12 (goal: 10) - Justified
+- Performance: ✅ 85ms (goal: 100ms)
+```
+
+## 🚨 Alerts
+
+If any metric is out of acceptable range:
+1. 🛑 **DOCUMENT** the issue
+2. 💬 **ALERT** the user
+3. 🔧 **PROPOSE** corrective actions
+4. ⏸️ **CONSIDER** blocking the merge until resolution
+
+---
+
+**Provided arguments**:
+
+```
+#$ARGUMENTS
+```
+
+---
+
+## 🎯 Outcome
+
+After running this command, you will have:
+- Complete metrics report
+- Comparison with baseline and goals
+- Identification of quality issues
+- Recommendations for actions
+- Objective basis for merge approval

package/dist/templates/commands/en/quality/observe.md

@@ -0,0 +1,172 @@
+# Decision Observability
+
+This command records important decisions made during development, creating an auditable log for explainability and traceability.
+
+## 🎯 Objective
+
+Create a structured record of technical and product decisions, ensuring:
+- **Explainability**: Why each decision was made
+- **Traceability**: Which sources (PRD, metaspecs, ADRs) supported the decision
+- **Audit**: Complete history of choices for future review
+- **Learning**: Documentation of trade-offs and alternatives considered
+
+**IMPORTANT**: This command DOES NOT generate new decisions. It only RECORDS decisions that have already been made during the development process.
+
+## Configuration
+
+Read `context-manifest.json` and `ai.properties.md` from the orchestrator to get repositories, base_path, and task_management_system.
+
+## 📋 Prerequisites
+
+- Have executed at least one of the commands that generate decisions:
+  - `/spec` - generates PRD with product decisions
+  - `/plan` - generates plan.md with technical decisions
+  - `/work` - implementation generates decisions during development
+
+## 🔍 Observation Process
+
+### 1. Identify Relevant Decisions
+
+Analyze the session files (`./.sessions/<ISSUE-ID>/`) to identify decisions:
+
+**After `/spec`** - Product Decisions:
+- Read `./.sessions/<ISSUE-ID>/prd.md`
+- Identify decisions in:
+  - Scope (what is included/excluded in the feature)
+  - Personas served (who is the target audience)
+  - Success metrics (how to measure results)
+  - Non-functional requirements (performance, accessibility)
+  - Constraints and trade-offs
+
+**After `/plan`** - Technical Decisions:
+- Read `./.sessions/<ISSUE-ID>/plan.md`
+- Identify decisions in:
+  - Component/module architecture
+  - Choice of libraries or tools
+  - Implementation patterns
+  - Data structure
+  - Testing strategy
+
+**During `/work`** - Implementation Decisions:
+- Read `./.sessions/<ISSUE-ID>/work.md`
+- Identify decisions in:
+  - Refactorings performed
+  - Approach changes
+  - Applied optimizations
+  - Edge case handling
+
+### 2. Document Each Decision
+
+For each identified decision, document:
+
+```markdown
+## Decision: [Clear Title]
+
+**Context**: [Why do we need to decide this? What is the problem or need?]
+
+**Options Considered**:
+1. **Option A**: [Description]
+   - Pros: [advantages]
+   - Cons: [disadvantages]
+2. **Option B**: [Description]
+   - Pros: [advantages]
+   - Cons: [disadvantages]
+
+**Decision**: [Chosen option]
+
+**Justification**: [Why did we choose this option? Which criteria were most important?]
+
+**Sources**:
+- [PRD section X]
+- [Metaspec Y]
+- [ADR-00Z]
+
+**Accepted Trade-offs**: [Which disadvantages did we consciously accept?]
+
+**Reversibility**: Easy / Medium / Hard
+
+**Date**: [decision date]
+```
+
+### 3. Create Decision Log
+
+Save in `./.sessions/<ISSUE-ID>/decisions.md`:
+
+```markdown
+# Decision Log - [ISSUE-ID]
+
+## Summary
+[Brief summary of the main decisions made in this feature]
+
+## Product Decisions
+
+### [Decision 1]
+[As per template above]
+
+### [Decision 2]
+[As per template above]
+
+## Technical Decisions
+
+### [Decision 3]
+[As per template above]
+
+### [Decision 4]
+[As per template above]
+
+## Implementation Decisions
+
+### [Decision 5]
+[As per template above]
+
+## Lessons Learned
+- [Lesson 1]
+- [Lesson 2]
+
+## Pending Decisions
+- [Decision that still needs to be made]
+```
+
+## 📊 Impact Analysis
+
+For critical decisions, document the impact:
+
+```markdown
+## Impact Analysis
+
+**Affected Repositories**: [list]
+
+**Impacted Components**: [list]
+
+**Created Dependencies**: [list]
+
+**Introduced Risks**: [list]
+
+**Applied Mitigations**: [list]
+```
+
+## 🔄 Decision Review
+
+Periodically review the decisions made:
+- Do they still make sense?
+- Have the trade-offs proven correct?
+- Are there learnings to document?
+- Does any decision need to be reversed?
+
+---
+
+**Provided arguments**:
+
+```
+#$ARGUMENTS
+```
+
+---
+
+## 🎯 Outcome
+
+After running this command, you will have:
+- Complete decision log in `./.sessions/<ISSUE-ID>/decisions.md`
+- Traceability of every choice made
+- Documentation for future reference
+- Basis for ADRs (if decisions are architectural)