context-first-cli 1.8.2 → 2.0.0

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

@@ -0,0 +1,167 @@
+# 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
+
+## 🎯 PR Creation Process
+
+### 1. Identify Modified Repositories
+
+For each repository in the workspace, check:
+```bash
+cd <repositório>
+git status
+git log origin/main..HEAD  # View unpushed commits
+```
+
+### 2. Push Branches
+
+For each modified repository:
+```bash
+cd <repositório>
+git push origin <branch-name>
+```
+
+### 3. Create Pull Requests
+
+For each repository, create a PR using GitHub CLI or the web interface:
+
+**Using GitHub CLI**:
+```bash
+cd <repositório>
+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: <nome-do-repo>
+
+- [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 the PRs
+- Document the recommended merge order
+- Indicate dependencies between PRs
+
+### 5. Update Issue in Task Manager
+
+If the task manager is configured:
+- Move the issue to "In Review" or "PR Open"
+- Add PR links in 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
+- [ ] Session documentation complete
+
+## 📢 Communication
+
+Notify the team about the PRs:
+- Mention relevant reviewers
+- Highlight critical changes or breaking changes
+- Indicate urgency if applicable
+
+---
+
+**Provided arguments**:
+
+```
+#$ARGUMENTS
+```
+
+---
+
+## 🎯 Next Steps
+
+1. Await PR review
+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

package/dist/templates/commands/en/engineer/pre-pr.md

@@ -0,0 +1,262 @@
+# Preparation for Pull Request
+
+This command validates that everything is ready to create Pull Requests.
+
+## 📋 Prerequisites
+
+- Complete implementation (all `/plan` tasks executed)
+- All commits made
+- Clean and organized workspace
+
+## 🎯 Objective
+
+Ensure that the implementation is complete, tested, and ready for review before creating the PRs.
+
+## ✅ Validation Checklist
+
+### 1. Implementation Completeness
+
+```markdown
+## Completeness Check
+
+- [ ] All plan tasks have been executed
+- [ ] All functional requirements from the PRD have been implemented
+- [ ] All acceptance criteria have been met
+- [ ] No functionality is left half-done
+```
+
+### 2. Code Quality
+
+For each modified repository:
+
+```bash
+cd <repositório>
+
+# Check status
+git status
+
+# Check linting
+npm run lint  # or equivalent command
+
+# Check formatting
+npm run format:check  # or equivalent command
+
+# Check build
+npm run build  # or equivalent command
+```
+
+Checklist:
+```markdown
+## Code Quality
+
+### <repo-1>
+- [ ] Linting without errors
+- [ ] Correct formatting
+- [ ] Build without errors
+- [ ] No critical warnings
+
+### <repo-2>
+- [ ] Linting without errors
+- [ ] Correct formatting
+- [ ] Build without errors
+- [ ] No critical warnings
+```
+
+### 3. Tests
+
+For each repository:
+
+```bash
+cd <repositório>
+
+# Run unit tests
+npm run test:unit  # or equivalent command
+
+# Run integration tests
+npm run test:integration  # or equivalent command
+
+# Check coverage
+npm run test:coverage  # or equivalent command
+```
+
+Checklist:
+```markdown
+## Tests
+
+### <repo-1>
+- [ ] All unit tests passing
+- [ ] All integration tests passing
+- [ ] Adequate test coverage (>= X%)
+- [ ] New tests added for new features
+
+### <repo-2>
+- [ ] All unit tests passing
+- [ ] All integration tests passing
+- [ ] Adequate test coverage (>= X%)
+- [ ] New tests added for new features
+```
+
+### 4. Documentation
+
+```markdown
+## Documentation
+
+- [ ] README updated (if necessary)
+- [ ] Appropriate code comments
+- [ ] API documentation updated (if there are changes)
+- [ ] Changelog updated
+- [ ] Technical documentation updated in metaspecs (if applicable)
+```
+
+### 5. Commits
+
+```markdown
+## Commits
+
+- [ ] All commits have clear and descriptive messages
+- [ ] Commits follow the project standard (conventional commits, etc.)
+- [ ] No commits with generic messages ("fix", "update", etc.)
+- [ ] Commits are logically organized
+- [ ] No debug or temporary commits
+```
+
+### 6. Synchronization
+
+```markdown
+## Synchronization
+
+- [ ] Branches are up to date with the base branch (main/develop)
+- [ ] No merge conflicts
+- [ ] Changes between repositories are synchronized
+- [ ] Dependencies between repos have been tested
+```
+
+### 7. Security
+
+```markdown
+## Security
+
+- [ ] No credentials or secrets in the code
+- [ ] No sensitive data in logs
+- [ ] Security dependencies have been checked
+- [ ] No known vulnerabilities introduced
+```
+
+### 8. Performance
+
+```markdown
+## Performance
+
+- [ ] No obvious performance regressions
+- [ ] Costly queries/operations have been optimized
+- [ ] No memory leaks introduced
+- [ ] PRD performance requirements have been met
+```
+
+## 🔍 Cross Validation
+
+If multiple repositories were modified:
+
+```markdown
+## Cross Validation
+
+- [ ] Tested integration between repositories locally
+- [ ] APIs/contracts between repos are consistent
+- [ ] No undocumented breaking changes
+- [ ] Deployment/merge order is clear
+```
+
+## 📄 PR Description Preparation
+
+Create `./.sessions/<ISSUE-ID>/pr-description.md`:
+
+```markdown
+## 🎯 Objective
+[Brief description of what this feature does]
+
+## 📝 Main Changes
+- [Change 1]
+- [Change 2]
+- [Change 3]
+
+## 🔗 Links
+- **Issue**: [ISSUE-ID]
+- **PRD**: [link or path]
+- **Technical Plan**: [link or path]
+
+## ✅ Checklist
+- [x] Code implemented and tested
+- [x] Unit tests added/updated
+- [x] Integration tests passing
+- [x] Documentation updated
+- [x] Linting and formatting OK
+- [x] Build without errors
+
+## 🧪 How to Test
+1. [Step 1]
+2. [Step 2]
+3. [Expected result]
+
+## 🔍 Notes for Reviewers
+- [Attention point 1]
+- [Attention point 2]
+```
+
+## 🚨 Issues Found
+
+If any validation fails:
+1. 🛑 **STOP** the PR creation process
+2. 📝 **DOCUMENT** the issue
+3. 🔧 **FIX** the issue
+4. 🔄 **RUN** `/pre-pr` again
+
+## 📊 Validation Report
+
+Create `./.sessions/<ISSUE-ID>/pre-pr-report.md`:
+
+```markdown
+# Pre-PR Validation Report
+
+**Date**: [date/time]
+**Issue**: [ISSUE-ID]
+
+## Overall Status
+✅ Ready for PR / ⚠️ Pending / ❌ Blocked
+
+## Validated Repositories
+- **<repo-1>**: ✅ OK
+- **<repo-2>**: ✅ OK
+
+## Test Summary
+- **Unit Tests**: X/X passing
+- **Integration Tests**: Y/Y passing
+- **Coverage**: Z%
+
+## Pending Items (if any)
+- [Pending item 1]
+- [Pending item 2]
+
+## Next Steps
+- [x] All validations passed
+- [ ] Run `/pr` to create Pull Requests
+```
+
+---
+
+**Provided arguments**:
+
+```
+#$ARGUMENTS
+```
+
+---
+
+## 🎯 Next Step
+
+If all validations passed:
+
+```bash
+/pr
+```
+
+This command will create the Pull Requests for all modified repositories.

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

@@ -0,0 +1,281 @@
+# Start of Development
+
+This command starts 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` afterwards)
+
+## 📚 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:
+   - 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. **Verify 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 the repositories communicate?
+- Are there dependencies between changes in different repos?
+- What is the recommended implementation order?
+- Is there any 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 the 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, required 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 constraints and mandatory patterns
+
+2. **Consult architectural patterns**:
+   - Read project structure guides in metaspecs
+   - Read code patterns in metaspecs
+   - Identify existing patterns in code (use Glob/Grep to find similar examples)
+
+3. **Validate compliance with ADRs**:
+   - For each relevant ADR, verify if the proposed solution respects the decisions
+   - Document compliance in architecture.md
+   - If there is violation, 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 the 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 that will 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 that will 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 assumptions]
+
+## 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 the files `context.md` and `architecture.md`**:
+
+```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