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

package/README.md

@@ -15,6 +15,39 @@ spec → complexity → execution DAG → context contract per node → ephemera
 
 ---
 
+## What is this for?
+
+You have a **multi-repository product** (say a backend, a web client, a mobile app, a
+shared UI library, a specs repo) and you drive development with an **AI coding tool**
+through slash commands.
+
+The problem: doing a feature that touches several repos with **one AI agent** means
+stuffing every repo, every spec, and the whole plan into **one giant context**. It
+saturates, loses the thread, and there's no parallelism — you babysit it phase by phase.
+
+This tool fixes that by moving one level up. You write an approved spec; the AI runs
+`/orchestrate`, which:
+
+1. **reads your `context-manifest.json`** to know your repos,
+2. **figures out how big the task is** (which repos it touches, whether it's risky),
+3. **builds the minimum graph of ephemeral agents** — e.g. one implementer per impacted
+   repo (in parallel), then an integrator, then a tester, plus an adversarial reviewer
+   when the task is risky,
+4. **gives each agent a tiny, bounded "context contract"** (only the files it may read,
+   only the repo it may write) and spawns them as subagents,
+5. **collects their reports** and summarizes what changed.
+
+Each agent is **ephemeral**: it does one bounded job with a clean, small context, returns
+a structured report, and is discarded. The orchestrator stays light — it coordinates, it
+doesn't implement. That's what keeps large, multi-repo work from collapsing under its own
+context.
+
+**Who it's for:** teams using an AI tool (Claude Code, Cursor, etc.) across several repos
+who want spec-driven, parallel, context-isolated feature development — without hand-wiring
+which agent runs when.
+
+---
+
 ## What's new vs. context-first-cli
 
 | | context-first-cli | context-first-agents-cli |
@@ -33,14 +66,27 @@ Everything specific lives in `context-manifest.json`.
 ## Install
 
 ```bash
-npm install -g context-first-agents-cli
+npm install -g @thatix.io/context-first-agents-cli
 # binaries: context-agents  (alias: cfa)
 ```
 
+## Concepts (30 seconds)
+
+- **Orchestrator** — a small control repo (the folder you run the CLI in). Holds
+  `context-manifest.json` and the installed `.md` commands. It is the single source of
+  truth for your dev process.
+- **Repositories** — your actual code repos, listed in the manifest, sitting next to the
+  orchestrator (`../service-a`, `../client-b`, …).
+- **Metaspecs** — the repo holding your normative specs (the `role: metaspecs` entry).
+- **Session** — one feature/issue. Lives in `.sessions/<ISSUE-ID>/` with the plan and each
+  agent's report.
+- **Ephemeral agent** — a subagent compiled on the fly from
+  `archetype + objective + repository + context contract`, run once, then discarded.
+
 ## Quick start
 
 ```bash
-# 1. Create an orchestrator
+# 1. Create an orchestrator (or run `init` inside an existing one)
 context-agents create:orchestrator my-orchestrator
 cd my-orchestrator
 
@@ -54,18 +100,62 @@ context-agents doctor
 /orchestrate <ISSUE-ID or path/to/spec.md>
 ```
 
+## The development flow after install
+
+Setup happens **once**; then it's the same short loop per feature.
+
+**One-time setup (Node CLI):**
+
+1. `create:orchestrator my-orchestrator` (or `cd` into an existing orchestrator and run
+   `init`).
+2. Edit `ai.properties.md` → set `base_path` to where your repos live.
+3. `add:repo` for each repository. Give each one **`hints`** (keywords that mean "this repo
+   is impacted"), an optional **`context`** list (files an agent here may read), and a
+   **`testCommand`**.
+4. Fill `orchestration.riskSignals` (keywords like `migration`, `payment`, `auth`) and
+   `orchestration.indexes` (your spec index files).
+5. `doctor` until it's all green.
+
+**Per feature (in your AI tool) — the full command flow:**
+
+```
+/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.
+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`).
+
+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)
 
@@ -113,6 +203,98 @@ additive fields). See `templates/orchestrator/context-manifest.example.json`.
 tester) · `complex` (medium + adversarial reviewer). A spec may force it via
 `complexity:` frontmatter. Small tasks stay small by design.
 
+---
+
+## End-to-end example
+
+Assume this manifest (two code repos + a specs repo):
+
+```jsonc
+{
+  "project": "example",
+  "repositories": [
+    { "id": "metaspecs", "role": "metaspecs", "hints": ["spec", "adr"] },
+    { "id": "service-a", "role": "service", "hints": ["api", "backend"],
+      "context": ["../metaspecs/specs/api.md"], "testCommand": "npm test" },
+    { "id": "client-b", "role": "application", "hints": ["ui", "client"],
+      "context": ["../metaspecs/specs/design.md"], "testCommand": "npm test" }
+  ],
+  "orchestration": {
+    "riskSignals": ["migration", "payment", "security"],
+    "indexes": ["../metaspecs/specs/index.md"],
+    "parallelism": { "maxWorkers": 8, "maxPerRepository": 2 }
+  }
+}
+```
+
+### 1. Write a spec — `.sessions/ISSUE-42/spec.md`
+
+```markdown
+---
+id: ISSUE-42
+---
+# Add a `discountRate` field to the order
+
+Expose `discountRate` in the **service-a** order API and show it on the
+order screen in the **client-b** UI.
+```
+
+### 2. Run the command
+
+```
+/orchestrate .sessions/ISSUE-42/spec.md
+```
+
+### 3. What the orchestrator does
+
+**Classification** — the spec text mentions `service-a`/`api` and `client-b`/`ui` →
+**repoHits = 2**, no risk signals → **medium**.
+
+**Proposed graph (shown for approval):**
+
+| id | archetype | repository | dependsOn |
+|----|-----------|------------|-----------|
+| W1 | implementer | service-a | — |
+| W2 | implementer | client-b | — |
+| W3 | integrator | (session) | W1, W2 |
+| W4 | tester | (session) | W3 |
+
+**Execution** — after you approve:
+
+- **Wave 1 (parallel):** W1 and W2 are spawned as subagents in one shot. Each gets ONLY
+  its context contract — e.g. W1 may read `../metaspecs/specs/index.md` +
+  `../metaspecs/specs/api.md`, may write only in `service-a`'s worktree, and is told not
+  to assume anything outside the spec.
+- **Wave 2:** W3 (integrator) checks that the API field W1 added matches what W2 consumes
+  (name, type, nullability).
+- **Wave 3:** W4 (tester) runs `npm test` in each impacted repo and maps the acceptance
+  criterion ("field visible on the order screen") to a check.
+
+**Result** — written to `.sessions/ISSUE-42/`:
+
+```
+.sessions/ISSUE-42/
+├── spec.md
+├── execution-plan.md         # the DAG above
+└── workers/
+    ├── agent-w1.md           # contract + report (service-a)
+    ├── agent-w2.md           # contract + report (client-b)
+    ├── agent-w3.md           # integration findings
+    └── agent-w4.md           # test results
+```
+
+Each report follows a fixed shape: `summary / changes / evidence / tests / unresolved /
+confidence`.
+
+### If the task were risky
+
+Change the spec to *"…behind a **payment** flow with a DB **migration**"*. Now
+**risks = 2** → **complex**, and the graph gains a **W5 reviewer** (dependsOn integrator)
+that adversarially checks business rules, security, and the migration's reversibility
+before you ship. You didn't have to remember to add it — the `riskSignals` did.
+
+---
+
 ## Design rules
 
 - **No catalog of domain agents.** Expertise comes from selected context, not personas.

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.