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

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

@@ -0,0 +1,301 @@
+# Technical Planning
+
+This command creates the detailed technical plan for the feature implementation.
+
+## 📋 Prerequisites
+
+- PRD created via `/spec`
+- Initial analysis done via `/start`
+- `context.md` and `architecture.md` files created and approved
+
+## 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**:
+```
+<orchestrator>/.sessions/<ISSUE-ID>/
+├── repo-1/          # worktree (will be used in /work)
+├── repo-2/          # worktree (will be used in /work)
+├── context.md       # context (immutable - READ)
+├── architecture.md  # architecture (immutable - READ)
+└── plan.md          # plan (mutable - CREATE)
+```
+
+**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 `context.md` and `architecture.md` (immutable)
+- ✅ Create `plan.md` in `.sessions/<ISSUE-ID>/`
+- ✅ Read code from main repositories (read-only)
+- ❌ NEVER checkout main repositories
+- ❌ NEVER modify `context.md` or `architecture.md`
+
+## ⚠️ IMPORTANT: Immutable Files
+
+**This command must READ but NOT MODIFY:**
+- ✅ **READ** `.sessions/<ISSUE-ID>/context.md` (immutable)
+- ✅ **READ** `.sessions/<ISSUE-ID>/architecture.md` (immutable)
+- ✅ **CREATE** `.sessions/<ISSUE-ID>/plan.md` (mutable - will be updated during `/work`)
+- ❌ **DO NOT modify `context.md` or `architecture.md`**
+
+## 📚 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 the relevant `index.md` files to ensure compliance with:
+   - System architecture
+   - Design and code patterns
+   - Folder and file structure
+   - Naming conventions
+
+## 🎯 Goal
+
+Create a detailed technical plan that will guide the implementation, dividing the work into smaller, sequential units.
+
+## 📝 Plan Structure
+
+### 1. Technical Overview
+
+```markdown
+# Technical Plan - [Feature Title]
+
+## Summary
+[Brief technical description of what will be implemented]
+
+## Involved Repositories
+- **<repo-1>**: [Role in this feature]
+- **<repo-2>**: [Role in this feature]
+
+## Technical Approach
+[General implementation strategy]
+```
+
+### 2. Solution Architecture
+
+```markdown
+## Architecture
+
+### Component Diagram
+[Textual description or ASCII art of components and their relationships]
+
+### Data Flow
+1. [Step 1 of the flow]
+2. [Step 2 of the flow]
+3. [Step 3 of the flow]
+
+### Integrations
+- **<repo-1> → <repo-2>**: [How they communicate]
+- **System → External API**: [If any]
+```
+
+### 3. Technical Decisions
+
+```markdown
+## Technical Decisions
+
+### Decision 1: [Title]
+**Context**: [Why we need to decide this]
+**Considered options**:
+- Option A: [Pros and cons]
+- Option B: [Pros and cons]
+**Decision**: [Chosen option]
+**Justification**: [Why we chose this option]
+
+### Decision 2: [Title]
+[Same format as above]
+```
+
+### 4. Implementation Plan
+
+Divide the work into small, sequential units:
+
+```markdown
+## Implementation Plan
+
+### Phase 1: [Phase Name]
+**Goal**: [What will be achieved in this phase]
+**Repositories**: [affected repos]
+
+#### Task 1.1: [Description]
+- **Repo**: <repo-1>
+- **Files**: [files to create/modify]
+- **Description**: [What to do]
+- **Tests**: [Tests to implement]
+- **Estimate**: [estimated time]
+
+#### Task 1.2: [Description]
+- **Repo**: <repo-2>
+- **Files**: [files to create/modify]
+- **Description**: [What to do]
+- **Tests**: [Tests to implement]
+- **Estimate**: [estimated time]
+
+### Phase 2: [Phase Name]
+[Same format as above]
+
+### Phase 3: [Phase Name]
+[Same format as above]
+```
+
+### 5. File Structure
+
+For each repository, define the structure:
+
+```markdown
+## File Structure
+
+### <repo-1>
+```
+src/
+├── components/
+│   ├── NewComponent.tsx (CREATE)
+│   └── ExistingComponent.tsx (MODIFY)
+├── services/
+│   └── NewService.ts (CREATE)
+└── tests/
+    └── NewComponent.test.tsx (CREATE)
+```
+
+### <repo-2>
+```
+src/
+├── controllers/
+│   └── NewController.ts (CREATE)
+└── tests/
+    └── NewController.test.ts (CREATE)
+```
+```
+
+### 6. APIs and Contracts
+
+```markdown
+## APIs and Contracts
+
+### New Endpoints
+
+#### POST /api/resource
+**Request**:
+```json
+{
+  "field1": "string",
+  "field2": "number"
+}
+```
+
+**Response**:
+```json
+{
+  "id": "string",
+  "status": "string"
+}
+```
+
+### Modified Endpoints
+
+#### GET /api/resource/:id
+**Changes**: [What changes]
+**Breaking Change**: Yes / No
+```
+
+### 7. Testing Strategy
+
+```markdown
+## Testing Strategy
+
+### Unit Tests
+- **<repo-1>**: [Components/functions to test]
+- **<repo-2>**: [Components/functions to test]
+
+### Integration Tests
+- **Scenario 1**: [Description and involved repos]
+- **Scenario 2**: [Description and involved repos]
+
+### E2E Tests (if applicable)
+- **Flow 1**: [Description]
+- **Flow 2**: [Description]
+```
+
+### 8. Technical Risks
+
+```markdown
+## Technical Risks
+
+### Risk 1: [Description]
+- **Impact**: High / Medium / Low
+- **Probability**: High / Medium / Low
+- **Mitigation**: [How to mitigate]
+- **Plan B**: [Alternative if it occurs]
+
+### Risk 2: [Description]
+[Same format as above]
+```
+
+### 9. Implementation Checklist
+
+```markdown
+## Implementation Checklist
+
+### Phase 1
+- [ ] Task 1.1
+- [ ] Task 1.2
+- [ ] Phase 1 Tests
+
+### Phase 2
+- [ ] Task 2.1
+- [ ] Task 2.2
+- [ ] Phase 2 Tests
+
+### Phase 3
+- [ ] Task 3.1
+- [ ] Task 3.2
+- [ ] Phase 3 Tests
+
+### Finalization
+- [ ] Documentation updated
+- [ ] Code review
+- [ ] Integration tests
+- [ ] PR created
+```
+
+## 📄 Saving the Plan
+
+Save it in `./.sessions/<ISSUE-ID>/plan.md`
+
+## 🔍 Review
+
+Review the plan checking:
+- All tasks are clear and executable
+- Dependencies between tasks are identified
+- Estimates are realistic
+- Risks have been considered
+- Testing strategy is adequate
+
+---
+
+**Provided arguments**:
+
+```
+#$ARGUMENTS
+```
+
+---
+
+## 🎯 Next Step
+
+After plan approval:
+
+```bash
+/work
+```
+
+This command will start executing the first work unit of the plan.

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

@@ -0,0 +1,194 @@
+# Pull Request Creation
+
+This command creates Pull Requests for all modified repositories in the workspace.
+
+## 📋 Prerequisites
+
+Before creating PRs, make sure that:
+- You have run `/pre-pr` and all validations passed
+- All commits have been made
+- All tests are passing
+- Documentation is up to date
+
+## Configuration
+
+Read `context-manifest.json` and `ai.properties.md` from the orchestrator to get repositories, base_path, and task_management_system.
+
+## 🛑 CRITICAL: WHERE TO WORK
+
+**⚠️ ATTENTION: If you need to make last-minute adjustments, ALL CODE MUST BE CREATED INSIDE THE WORKTREE!**
+
+**✅ CORRECT** - Work inside the worktree:
+```
+<orchestrator>/.sessions/<ISSUE-ID>/<repo-name>/src/file.ts  ✅
+<orchestrator>/.sessions/<ISSUE-ID>/<repo-name>/README.md  ✅
+<orchestrator>/.sessions/<ISSUE-ID>/<repo-name>/CHANGELOG.md  ✅
+```
+
+**❌ WRONG** - NEVER create code outside the worktree:
+```
+<orchestrator>/.sessions/file.ts  ❌
+<orchestrator>/.sessions/<ISSUE-ID>/file.ts  ❌
+{base_path}/<repo-name>/file.ts  ❌ (main repository!)
+```
+
+**ABSOLUTE RULE**:
+- 🛑 **Any code adjustment** (docs, changelog, fixes) **MUST be in** `<orchestrator>/.sessions/<ISSUE-ID>/<repo-name>/`
+- 🛑 **NEVER modify** the main repository at `{base_path}/<repo-name>/`
+- ✅ **Work ONLY** inside the worktree of the specific repository
+
+## 🎯 PR Creation Process
+
+### 1. Identify Modified Repositories
+
+For each repository in the workspace, check:
+```bash
+cd <repository>
+git status
+git log origin/main..HEAD  # See unpushed commits
+```
+
+### 2. Push Branches
+
+For each modified repository:
+```bash
+cd <repository>
+git push origin <branch-name>
+```
+
+### 3. Create Pull Requests
+
+For each repository, create a PR using GitHub CLI or web interface:
+
+**Using GitHub CLI**:
+```bash
+cd <repository>
+gh pr create --title "[ISSUE-ID] Feature Title" \
+  --body "$(cat ../.sessions/<ISSUE-ID>/pr-description.md)" \
+  --base main
+```
+
+**PR Description Template**:
+
+```markdown
+## 🎯 Objective
+
+[Brief description of what this PR does]
+
+## 📝 Changes
+
+### Repository: <repo-name>
+
+- [Change 1]
+- [Change 2]
+- [Change 3]
+
+## 🔗 Relationships
+
+- **Issue**: <ISSUE-ID>
+- **Related PRs**:
+  - <repo-1>#<PR-number>
+  - <repo-2>#<PR-number>
+
+## ✅ Checklist
+
+- [ ] Code implemented and tested
+- [ ] Unit tests added/updated
+- [ ] Integration tests passing
+- [ ] Documentation updated
+- [ ] No breaking changes (or documented)
+- [ ] Peer reviewed (after PR creation)
+
+## 🧪 How to Test
+
+1. [Step 1]
+2. [Step 2]
+3. [Expected result]
+
+## 📸 Screenshots/Demos
+
+[If applicable, add screenshots or links to demos]
+
+## 🔍 Notes for Reviewers
+
+- [Point of attention 1]
+- [Point of attention 2]
+```
+
+### 4. Link PRs
+
+If there are multiple PRs (one per repository):
+- Add cross-links between PRs
+- Document the recommended merge order
+- Indicate dependencies between PRs
+
+### 5. Update Issue in Task Manager
+
+If task manager is configured:
+- Move the issue to "In Review" or "PR Open"
+- Add PR links to the issue
+- Add a comment summarizing the changes
+
+### 6. Session Documentation
+
+Update `./.sessions/<ISSUE-ID>/pr.md`:
+
+```markdown
+# [Feature Title] - Pull Requests
+
+## Created PRs
+
+### <repo-1>
+- **Link**: <PR URL>
+- **Status**: Open
+- **Commits**: X commits
+
+### <repo-2>
+- **Link**: <PR URL>
+- **Status**: Open
+- **Commits**: Y commits
+
+## Recommended Merge Order
+
+1. <repo-1> - [Justification]
+2. <repo-2> - [Justification]
+
+## Merge Notes
+
+- [Important note 1]
+- [Important note 2]
+```
+
+## 🔍 Final Checklist
+
+Before requesting review:
+- [ ] All PRs created
+- [ ] Complete and clear descriptions
+- [ ] PRs linked to each other
+- [ ] Issue updated in task manager
+- [ ] Tests passing in CI/CD
+- [ ] Complete session documentation
+
+## 📢 Communication
+
+Notify the team about the PRs:
+- Mention relevant reviewers
+- Highlight critical or breaking changes
+- Indicate urgency if applicable
+
+---
+
+**Provided arguments**:
+
+```
+#$ARGUMENTS
+```
+
+---
+
+## 🎯 Next Steps
+
+1. Await PR reviews
+2. Respond to comments and make adjustments
+3. After approval, merge in the recommended order
+4. Run `context-cli feature:end <ISSUE-ID>` to clean the workspace