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

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,6 +100,37 @@ 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):**
+
+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:
+   - 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.
+
+`/plan` and `/work` from the classic flow can still exist as manual escape hatches — but
+for most tasks `/orchestrate` replaces `start → plan → work`.
+
 ## Commands (Node — scaffold/management only)
 
 | Command | Purpose |
@@ -113,6 +190,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/package.json

@@ -1,7 +1,9 @@
 {
   "name": "@thatix.io/context-first-agents-cli",
-  "version": "0.1.0",
-  "publishConfig": { "access": "public" },
+  "version": "0.1.1",
+  "publishConfig": {
+    "access": "public"
+  },
   "description": "Evolution of context-first-cli: manage the Context-First methodology across any project AND orchestrate dynamic, ephemeral AI agents from specs. All agent orchestration lives in .md command templates; the Node layer only scaffolds and manages.",
   "type": "module",
   "main": "dist/index.js",
@@ -37,7 +39,9 @@
   ],
   "author": "Thiago Abreu <thiagoabreu.dev>",
   "license": "MIT",
-  "engines": { "node": ">=18.0.0" },
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "dependencies": {
     "chalk": "^5.6.2",
     "commander": "^14.0.2",