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

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

@@ -0,0 +1,285 @@
+# Start Development
+
+This command initiates the development of a feature in the current workspace.
+
+## 📍 IMPORTANT: Understand the Structure
+
+**Workspace** (where you will 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 - created by this command)
+├── architecture.md  # architecture (immutable - created by this command)
+└── plan.md          # plan (mutable - created by /plan)
+```
+
+**Main Repositories** (read-only):
+```
+{base_path}/repo-1/  # main repo (branch main/master)
+{base_path}/repo-2/  # main repo (branch main/master)
+```
+
+**GOLDEN RULE**:
+- ✅ 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` later)
+
+## Configuration
+
+Read `context-manifest.json` and `ai.properties.md` from the orchestrator to get repositories, base_path, and task_management_system.
+
+## 📚 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:
+   - Business context
+   - Stack, architecture, and technical patterns
+   - Project conventions
+   - ADRs (Architecture Decision Records)
+
+## 🎯 Project Context
+
+Before starting, load the context by consulting:
+- `context-manifest.json` - Repository structure
+- MetaSpecs (located above) - Architecture and patterns
+- `workspace directory` - Current workspace information
+
+## ⚙️ Initial Setup
+
+1. **Verify Workspace**:
+   - Confirm you are in the correct workspace (check `workspace directory`)
+   - List repositories available in the workspace
+
+2. **Check Branches**:
+   - For each repository in the workspace, check the current branch
+   - Confirm all branches are synchronized
+
+3. **Load Specification**:
+   - **If task manager configured**: Read the issue using the appropriate MCP
+   - **Otherwise**: Ask the user for the specification file or feature description
+
+4. **Update Status** (if task manager configured):
+   - Move the issue to "In Progress"
+
+## 📋 Analysis and Understanding
+
+Analyze the specification and build a complete understanding by answering:
+
+### Business
+- **Why** is this being built?
+- **Who** benefits?
+- **Which** metric do we want to impact?
+
+### Functional
+- **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)
+
+### Validation against MetaSpecs
+
+If metaspecs are available, validate:
+- Aligned with strategy and roadmap?
+- Uses approved technology stack?
+- Respects Architecture Decision Records?
+- Follows documented business rules?
+
+## 🤔 Clarification Questions
+
+After initial analysis, formulate **3-5 most important clarifications**:
+
+**Examples of relevant questions**:
+- Which repository should contain the main logic?
+- How should repositories communicate?
+- Are there dependencies between changes in different repos?
+- What is the recommended implementation order?
+- 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 file `./.sessions/<ISSUE-ID>/context.md` with:
+
+```markdown
+# Context: [Feature Name]
+
+## Why
+[Business value, persona served, impacted metric]
+
+## What
+[Main functionalities, expected behavior]
+
+## How
+[Technical approach, components, affected repositories]
+
+## Validation against MetaSpecs
+- [x] Aligned with product strategy
+- [x] Serves correct persona
+- [x] Impacted metric documented
+- [x] Uses approved stack
+- [x] Respects ADRs
+- [x] No conflicts with known limitations
+
+## Dependencies
+[Libraries, APIs, existing components]
+
+## Constraints
+[Technical limitations, performance targets, budget]
+
+## Tests
+[Critical E2E, necessary unit tests, expected coverage]
+```
+
+**After creating `context.md`, request user review and approval before proceeding.**
+
+---
+
+## 🏗️ Creation of Architecture.md
+
+**IMPORTANT**: This file is **IMMUTABLE** after approval. It must not be modified by subsequent commands.
+
+### Architectural Principles (MANDATORY)
+
+**BEFORE creating the architecture, you MUST:**
+
+1. **Read ADRs (Architecture Decision Records)**:
+   - List ADRs in metaspecs
+   - Read ALL ADRs relevant to the feature
+   - Identify mandatory constraints and patterns
+
+2. **Consult architectural patterns**:
+   - Read project structure guides 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, check if the proposed solution respects the decisions
+   - Document compliance in architecture.md
+   - If violation exists, justify or propose correction
+
+4. **Analyze existing code**:
+   - Use Glob/Grep to find similar components/modules
+   - Understand existing patterns and structures
+   - Align new implementation with project standards
+
+### Architecture Document Structure
+
+Create file `./.sessions/<ISSUE-ID>/architecture.md` with:
+
+```markdown
+# Architecture: [Feature Name]
+
+## Overview
+[High-level view of the system before and after the change]
+
+## Affected Components
+[List of components and their relationships, dependencies]
+
+### Component Diagram
+[Textual description or Mermaid diagram of components]
+
+### Data Flow
+1. [Step 1 of the flow]
+2. [Step 2 of the flow]
+3. [Step 3 of the flow]
+
+## Proposed Directory Structure
+[Based on project patterns]
+
+```
+repo-1/
+├── src/
+│   ├── components/
+│   │   └── NewComponent.tsx (CREATE)
+│   └── services/
+│       └── NewService.ts (CREATE)
+```
+
+## Patterns and Best Practices
+[Patterns to be maintained or introduced]
+
+## ADR Validation
+[List of consulted ADRs and compliance]
+
+- [x] ADR-001: [Name] - Compliant
+- [x] ADR-002: [Name] - Compliant
+
+## External Dependencies
+[Libraries to be used or added]
+
+## Technical Decisions
+
+### Decision 1: [Title]
+**Context**: [Why we need to decide this]
+**Options considered**:
+- Option A: [Pros and cons]
+- Option B: [Pros and cons]
+**Decision**: [Chosen option]
+**Justification**: [Why we chose this option]
+
+## Constraints and Assumptions
+[Technical limitations and premises]
+
+## Trade-offs
+[Alternatives considered and why they were not chosen]
+
+## Consequences
+**Positive**:
+- [Benefit 1]
+- [Benefit 2]
+
+**Negative**:
+- [Cost/limitation 1]
+- [Cost/limitation 2]
+
+## Main Files
+[List of main files to be edited/created]
+
+- `repo-1/src/components/NewComponent.tsx` (CREATE)
+- `repo-1/src/services/NewService.ts` (CREATE)
+- `repo-2/src/controllers/NewController.ts` (CREATE)
+```
+
+**After creating `architecture.md`, request user review and approval before proceeding.**
+
+---
+
+**Provided arguments**:
+
+```
+#$ARGUMENTS
+```
+
+---
+
+## 🎯 Next Step
+
+**After user approval of `context.md` and `architecture.md` files**:
+
+```bash
+/plan
+```
+
+This command will create the detailed technical implementation plan.
+
+---
+
+## ⚠️ IMPORTANT: Immutable Files
+
+**`context.md` and `architecture.md` are IMMUTABLE after approval.**
+
+- ✅ They can be READ by subsequent commands (`/plan`, `/work`)
+- ❌ They MUST NOT be MODIFIED by any command
+- ❌ If changes are needed, discuss with the user and create new files or update the issue in the task manager

package/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