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

package/README.md

@@ -116,33 +116,46 @@ Setup happens **once**; then it's the same short loop per feature.
    `orchestration.indexes` (your spec index files).
 5. `doctor` until it's all green.
 
-**Per feature (in your AI tool):**
+**Per feature (in your AI tool) — the full command flow:**
 
-1. Write/approve a spec (a `.md` with the requirements, or an issue in your tracker).
-2. Run **`/orchestrate <ISSUE-ID or path/to/spec.md>`**. The command will:
+```
+/warm-up → /collect → /refine → /spec → /orchestrate
+   load       gather      shape     approve    derive agent graph
+  context      idea       scope      the spec    + execute
+```
+
+1. **`/warm-up`** — load project context (manifest, specs, conventions).
+2. **`/collect`** → **`/refine`** → **`/spec`** — turn an idea into an **approved,
+   normative spec** (PRD). These are the "product" commands.
+3. **`/orchestrate <ISSUE-ID or path/to/spec.md>`** — the new engine. It will:
    - classify complexity and **show you the agent graph**,
    - wait for your **approval**,
    - spawn the ephemeral agents wave by wave (implementers in parallel, then
      integrator/tester, plus a reviewer if risky),
    - write everything to `.sessions/<ISSUE-ID>/` and summarize the result.
-3. Review the summary. If the reviewer flagged blockers, fix and re-run the affected part.
-4. Open the PR(s) from the per-repo worktrees.
+4. Review the summary. If the reviewer flagged blockers, fix and re-run the affected part.
+5. Open the PR(s) from the per-repo worktrees (or use `/pre-pr` / `/pr`).
 
-`/plan` and `/work` from the classic flow can still exist as manual escape hatches — but
-for most tasks `/orchestrate` replaces `start → plan → work`.
+The classic **`/start` → `/plan` → `/work`** commands are still installed as **manual
+escape hatches** — for most tasks `/orchestrate` replaces that whole sequence. Quality
+commands `/observe` and `/metrics` are also included.
 
 ## Commands (Node — scaffold/management only)
 
 | Command | Purpose |
 |---|---|
-| `create:orchestrator [name]` | New orchestrator (manifest + `.md` commands) |
-| `init` | Install/refresh agent commands in an existing orchestrator |
+| `create:orchestrator [name]` | New orchestrator (manifest + full `.md` command flow) |
+| `init` | Install/refresh the full command flow in an existing orchestrator |
 | `add:repo` | Add a repo to the manifest (id, role, **hints**, context, testCommand) |
-| `update:commands` | Overwrite the agent command templates |
-| `doctor` | Validate manifest, hints, indexes, installed commands |
+| `update:commands` | Overwrite the command templates |
+| `doctor` | Validate manifest, hints, indexes, and installed flow commands |
 | `status` | Show repos, risk signals, and active sessions |
 
-`--lang en|pt-BR` selects the language of the installed `.md` commands.
+`--lang en|es|pt-BR` selects the language of the installed `.md` commands.
+
+**Installed `.md` commands** (into `.claude/commands/`): `warm-up`,
+`products/{collect,refine,spec,check}`, **`orchestrate`** (+ `agents/`),
+`engineer/{start,plan,work,pre-pr,pr}` (escape hatches), `quality/{observe,metrics}`.
 
 ## The `.md` orchestration layer (the engine)
 

package/dist/commands/create-orchestrator.js

@@ -83,5 +83,8 @@ export async function createOrchestratorCommand(name, opts) {
     console.log(chalk.gray('\nNext steps:'));
     console.log(chalk.gray(`  cd ${dirName}`));
     console.log(chalk.gray('  context-agents add:repo        # register your repositories'));
-    console.log(chalk.gray('  # then in your AI tool:  /orchestrate <ISSUE-ID>\n'));
+    console.log(chalk.gray('  context-agents doctor          # validate the setup'));
+    console.log(chalk.gray('\nThen, in your AI tool, the full flow:'));
+    console.log(chalk.gray('  /warm-up → /collect → /refine → /spec → /orchestrate <ISSUE-ID>'));
+    console.log(chalk.gray('  (/plan, /work, /pre-pr remain as manual escape hatches)\n'));
 }

package/dist/commands/doctor.js

@@ -15,15 +15,31 @@ export async function doctorCommand() {
         return;
     }
     console.log(chalk.green(`✓ Manifest OK — ${manifest.project} (${manifest.repositories.length} repos)`));
-    // Commands installed?
+    // Commands installed? Check the full flow (product → orchestrate → engineer escape hatches).
     const commandsDir = path.join(cwd, '.claude', 'commands');
-    if (await pathExists(path.join(commandsDir, 'orchestrate.md'))) {
-        console.log(chalk.green('✓ /orchestrate command installed'));
+    const flow = [
+        { file: 'warm-up.md', label: '/warm-up' },
+        { file: 'products/collect.md', label: '/collect' },
+        { file: 'products/refine.md', label: '/refine' },
+        { file: 'products/spec.md', label: '/spec' },
+        { file: 'orchestrate.md', label: '/orchestrate', required: true },
+    ];
+    const missing = [];
+    for (const step of flow) {
+        if (!(await pathExists(path.join(commandsDir, step.file))))
+            missing.push(step.label);
     }
-    else {
-        console.log(chalk.red('✗ orchestrate.md missing — run `context-agents init`'));
+    if (!missing.length) {
+        console.log(chalk.green('✓ Full command flow installed (warm-up → collect → refine → spec → orchestrate)'));
+    }
+    else if (missing.includes('/orchestrate')) {
+        console.log(chalk.red(`✗ Core command /orchestrate missing — run \`context-agents init\``));
         problems++;
     }
+    else {
+        console.log(chalk.yellow(`! Some flow commands missing (${missing.join(', ')}) — run \`context-agents init\` to install them`));
+        warnings++;
+    }
     // Orchestration block
     const orch = manifest.orchestration;
     if (!orch?.riskSignals?.length) {

package/dist/commands/init.js

@@ -18,5 +18,7 @@ export async function initCommand(opts) {
     console.log(chalk.bold('\nInstalling agent command templates:'));
     const written = await installCommands(cwd, { lang: opts.lang, force: opts.force });
     console.log(chalk.green(`\n✓ Installed ${written.length} command file(s).`));
-    console.log(chalk.gray('\nNext: open your AI tool and run  /orchestrate <ISSUE-ID>\n'));
+    console.log(chalk.gray('\nFull flow in your AI tool:'));
+    console.log(chalk.gray('  /warm-up → /collect → /refine → /spec → /orchestrate <ISSUE-ID>'));
+    console.log(chalk.gray('  (/plan, /work, /pre-pr remain as manual escape hatches)\n'));
 }

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