kodelyth-ecc 1.5.10 → 1.7.0

package/docs/replay.md

@@ -0,0 +1,244 @@
+# Kodelyth ECC — Session Replay
+
+Bundle, share, and re-run swarm sessions for regression testing, reproducible bug reports, and A/B testing across harnesses, agents, and base refs.
+
+> **Phase 2.8 of the [Devil Roadmap](../README.md).** Companion to the swarm orchestrator (Phase 2.7) — every swarm coordination dir is portable, replayable, and diff-friendly.
+
+---
+
+## Why replay
+
+Three concrete wins:
+
+1. **Reproducible bug reports.** Bundle a buggy swarm into a single JSON file, ship to maintainers. They `replay --execute` locally and see the same agent behavior.
+2. **Regression testing.** Save a known-good baseline. After an agent prompt rev, replay against the new agent and diff handoffs. Did quality regress?
+3. **Model A/B testing.** Same task, two harnesses. Side-by-side handoff comparison reveals which model handles the swarm better for your codebase.
+
+---
+
+## CLI
+
+| Command | Purpose |
+|---|---|
+| `kodelyth-ecc session-export <session> [flags]` | Bundle a coordination dir to JSON. |
+| `kodelyth-ecc session-import <bundle.json> [flags]` | Restore a bundle to a coordination dir. |
+| `kodelyth-ecc replay <bundle\|session> [flags]` | Re-run a session with variations. |
+
+### `session-export`
+
+```bash
+kodelyth-ecc session-export <session> \
+  [--out file.json] \
+  [--task "..."] [--agents a,b,c] [--harness claude] [--base-ref HEAD] \
+  [--coord-root <dir>]
+```
+
+| Flag | Description |
+|---|---|
+| `<session>` | Required. Directory name under `.orchestration/`. |
+| `--out` | Output JSON path. Default: `.orchestration/<session>.bundle.json`. |
+| `--task "..."` | Enrich `meta.task` for cleaner replays. |
+| `--agents a,b,c` | Enrich `meta.agents`. |
+| `--harness <h>` | Enrich `meta.harness`. |
+| `--base-ref <ref>` | Enrich `meta.base_ref`. |
+| `--coord-root` | Where to look for coordination dirs (default: `<repo>/.orchestration`). |
+
+### `session-import`
+
+```bash
+kodelyth-ecc session-import <bundle.json> \
+  [--target <dir>] [--overwrite] \
+  [--coord-root <dir>]
+```
+
+| Flag | Description |
+|---|---|
+| `<bundle.json>` | Required. Bundle to restore. |
+| `--target` | Output directory. Default: `.orchestration/<session-from-bundle>`. |
+| `--overwrite` | Replace any existing target dir. |
+
+### `replay`
+
+```bash
+kodelyth-ecc replay <bundle.json|session-name> \
+  [--harness h] [--agents a,b,c] [--base-ref ref] [--session NAME] [--replace] \
+  [--execute|--write-only|--json]
+```
+
+| Flag | Description |
+|---|---|
+| `<target>` | Required. Bundle file (ends in `.json`) or session name in `.orchestration/`. |
+| `--harness` | Override launcher harness. |
+| `--agents` | Replace the agent list. |
+| `--base-ref` | Branch base for replay worktrees. |
+| `--session` | Override auto-generated `-replay-N` name. |
+| `--replace` | Tear down any existing session/worktrees with the same names. |
+| `--execute` | Actually spawn worktrees + tmux + agents. |
+| `--write-only` | Just materialize coordination files. |
+| `--json` | Print plan + planConfig. |
+
+Default mode is **dry-run**. Always inspect first.
+
+---
+
+## Bundle format
+
+Stable schema `kodelyth.session-bundle/v1`. Single JSON file:
+
+```json
+{
+  "schema":      "kodelyth.session-bundle/v1",
+  "session":     "swarm-2026-05-10-4a",
+  "exported_at": "2026-05-10T17:30:00Z",
+  "exported_by": "kodelyth-ecc@1.7.0",
+  "meta": {
+    "task":     "audit oauth flow",
+    "agents":   ["security-reviewer", "code-reviewer", "pair-programmer", "tdd-guide"],
+    "harness":  "claude",
+    "base_ref": "HEAD"
+  },
+  "workers": [
+    { "slug": "code-reviewer",     "task": "...", "handoff": "...", "status": "..." },
+    { "slug": "pair-programmer",   "task": "...", "handoff": "...", "status": "..." },
+    { "slug": "security-reviewer", "task": "...", "handoff": "...", "status": "..." },
+    { "slug": "tdd-guide",         "task": "...", "handoff": "...", "status": "..." }
+  ]
+}
+```
+
+Pure JSON. No archives, no binaries. Diff-friendly for `git diff` review of regression bundles.
+
+---
+
+## How replay reconstructs the task
+
+1. **Prefer `meta.task`** if the bundle was exported with `--task "..."`.
+2. **Fallback: parse the first worker's `task.md`** for the `## Shared Task` section (the agent-shaped header from `scripts/swarm/build-plan.js`).
+3. **Final fallback: parse the orchestrator's own `## Objective` block** (works for hand-written tasks).
+
+This means replay works even on bundles that pre-date the `--task` flag — the heuristic recovers the shared task from the first worker.
+
+---
+
+## Replay variations
+
+| Want to test | Flags |
+|---|---|
+| Same task, different model | `--harness claude` vs `--harness codex` (or vary `KODELYTH_ROUTER_*`) |
+| Same task, different agents | `--agents new1,new2,new3` |
+| Same task, new code | `--base-ref refactor-branch` |
+| Custom session name | `--session my-replay-1` |
+| Inspect plan only | (default — dry-run) |
+| Just write coordination files | `--write-only` |
+| Full execute | `--execute` |
+
+---
+
+## Hard rules
+
+1. **Never `--execute` without inspecting the dry-run.** Worktrees mutate disk.
+2. **Replays are auto-named** (`-replay-N`) to avoid collisions. Don't manually reuse the origin name.
+3. **Bundles are public artifacts** — strip secrets before sharing externally. Use `opensource-sanitizer` if needed.
+4. **A/B comparisons require human review.** Never auto-pick a "winner" between two replays.
+5. **Don't replay across incompatible base refs.** A swarm built against `main` may break if replayed against `feature-branch` with conflicting changes.
+
+---
+
+## Pairing with the rest of ECC
+
+| Pairs with | How |
+|---|---|
+| **2.7 swarm orchestrator** | Replay only works on swarm coordination dirs. The two ship together. |
+| **2.4 cost router** | Vary `KODELYTH_ROUTER_*` env vars across replays for A/B model tests. |
+| **2.10 token-budget hook** | Replays open new sessions with fresh budgets — no spillover from the origin. |
+| **2.5 MCP client mode** | Replays inherit the same MCP registry, so tool calls reproduce. |
+| **opensource-sanitizer** | Run on a bundle before sharing externally. |
+
+---
+
+## Examples
+
+### Reproducible bug report
+
+```bash
+# 1. Capture the buggy run
+npx kodelyth-ecc swarm --task "..." --execute
+
+# 2. After it finishes, export with rich meta
+npx kodelyth-ecc session-export swarm-2026-05-10-4a \
+  --task "..." --agents code-reviewer,security-reviewer --harness claude \
+  --out bug-report.bundle.json
+
+# 3. Strip secrets if needed
+# (manually edit bug-report.bundle.json)
+
+# 4. Ship to maintainers
+gh issue create --body "Reproducer attached: bug-report.bundle.json"
+```
+
+### Model A/B test
+
+```bash
+# Run with claude
+npx kodelyth-ecc swarm --task "refactor payments module" --agents 4 --harness claude --execute
+npx kodelyth-ecc session-export swarm-...               --out claude-run.bundle.json
+
+# Replay with codex against the same task
+npx kodelyth-ecc replay claude-run.bundle.json --harness codex --execute
+npx kodelyth-ecc session-export swarm-...-replay-1      --out codex-run.bundle.json
+
+# Compare handoffs
+diff <(jq -r '.workers[] | "\(.slug):\n\(.handoff)"' claude-run.bundle.json) \
+     <(jq -r '.workers[] | "\(.slug):\n\(.handoff)"' codex-run.bundle.json)
+```
+
+### Regression check after agent rev
+
+```bash
+# 1. Save a baseline.
+npx kodelyth-ecc session-export swarm-baseline --out baseline.bundle.json
+
+# 2. After updating an agent prompt, replay.
+npx kodelyth-ecc replay baseline.bundle.json --execute
+npx kodelyth-ecc session-export swarm-baseline-replay-1 --out replay.bundle.json
+
+# 3. Inspect the diff manually — has quality regressed?
+diff <(jq -r '.workers[] | "\(.slug)\n\(.handoff)"' baseline.bundle.json) \
+     <(jq -r '.workers[] | "\(.slug)\n\(.handoff)"' replay.bundle.json)
+```
+
+---
+
+## Programmatic use
+
+```js
+const bundleLib = require('kodelyth-ecc/scripts/replay/bundle.js');
+const replayLib = require('kodelyth-ecc/scripts/replay/replay.js');
+const { buildOrchestrationPlan, executePlan } = require('kodelyth-ecc/scripts/lib/tmux-worktree-orchestrator.js');
+
+// Read a bundle
+const bundle = bundleLib.readBundle('./oauth-audit.bundle.json');
+
+// Build a replay plan with overrides
+const planConfig = replayLib.buildReplayPlanConfig(bundle, {
+  harness: 'codex',
+  baseRef: 'main',
+});
+
+// Execute
+const plan = buildOrchestrationPlan(planConfig);
+const result = executePlan(plan);
+console.log(`replay started: ${result.sessionName}`);
+```
+
+---
+
+## Roadmap interactions
+
+- **Phase 2.3 — local dashboard** will surface replay history and side-by-side handoff diffs for the same task across runs.
+- **Phase 2.6 — sandbox layer** will isolate replay execution in Docker so re-running an external bundle doesn't trust the source.
+- **Phase 2.2 — SWE-Bench harness** will use bundle replay as its evaluation primitive.
+
+---
+
+Built into [Kodelyth ECC](../README.md). MIT licensed.

package/docs/supply-chain.md

@@ -0,0 +1,207 @@
+# Supply chain — SBOM, manifest, SLSA provenance
+
+> Phase 2.9 of the Devil Roadmap. Every kodelyth-ecc release ships with three independent supply-chain artifacts so any consumer (audit team, downstream agent, security tool) can answer "where does this code come from, can I trust it, and has it been tampered" without trusting kodelyth-ecc.
+
+---
+
+## What ships with every release
+
+| Artifact | Format | Where to find it | Issued by |
+|---|---|---|---|
+| **SLSA build provenance** | sigstore-signed npm provenance | npmjs.com/package/kodelyth-ecc → "Provenance" tab | npm + GitHub OIDC (`npm publish --provenance`) |
+| **CycloneDX SBOM** | CycloneDX 1.5 JSON | GitHub release page → `kodelyth-ecc-sbom.cdx.json` | `kodelyth-ecc sbom` |
+| **Content manifest** | sha256 manifest JSON | GitHub release page → `kodelyth-ecc-manifest.json` | `kodelyth-ecc manifest` |
+
+All three are emitted by `.github/workflows/publish.yml` on every tagged release.
+
+---
+
+## CLI
+
+### `kodelyth-ecc sbom`
+
+```
+kodelyth-ecc sbom [--root DIR] [--out FILE] [--json]
+```
+
+Generates a CycloneDX 1.5 software bill of materials.
+
+| Field | Source | Notes |
+|---|---|---|
+| `metadata.component` | `package.json` | The kodelyth-ecc package itself |
+| `components[]` | `package-lock.json` v3 | One entry per locked dependency, including dev + transitive |
+| `purl` | `pkg:npm/<name>@<version>` | scoped packages keep the leading `@` |
+| `licenses` | lockfile `license` | normalized to CycloneDX shape |
+| `hashes` | npm SRI (`integrity`) | base64 → hex, algo mapped to `SHA-256/384/512` |
+| `dependencies[]` | root entry's `dependencies` + `optionalDependencies` | Direct edges only |
+| `serialNumber` | `urn:uuid:<sha256("name@version|timestamp")>` | Stable for same inputs |
+
+**Pure function. No network. No exec.**
+
+### `kodelyth-ecc manifest`
+
+```
+kodelyth-ecc manifest [--root DIR] [--out FILE] [--json]
+```
+
+Generates a sha256 content manifest of every shipped asset.
+
+```json
+{
+  "schema": "kodelyth.content-manifest/v1",
+  "package": "kodelyth-ecc",
+  "pkg_version": "1.7.0",
+  "generated_at": "2026-05-10T17:00:00Z",
+  "file_count": 730,
+  "digest": "20813125…",
+  "files": [
+    { "path": "agents/code-reviewer.md", "size": 4521, "sha256": "…" }
+  ]
+}
+```
+
+Walks: `agents/`, `skills/`, `commands/`, `rules/`, `hooks/`, `scripts/`, `bin/`, `parallel-commands/`, `bundles/`, plus root files (`package.json`, `README.md`, `CHANGELOG.md`, `VERSION`, `install.sh`, `install.ps1`).
+
+Skips: `node_modules/`, `.git/`, `.DS_Store`, `__pycache__/`, `*.pyc`.
+
+The top-level `digest` is the sha256 over the deterministic JSON of `files[]`. Two runs against the same source state produce the same digest.
+
+### `kodelyth-ecc verify`
+
+```
+kodelyth-ecc verify [--root DIR] [--manifest FILE] [--json]
+```
+
+Compares disk against the manifest:
+
+| Category | Means | Fails verify? |
+|---|---|---|
+| `ok` | sha256 matches | No |
+| `modified` | hash differs | **Yes** |
+| `missing` | not on disk | **Yes** |
+| `extra` | on disk but not in manifest | No (advisory) |
+
+Exits `0` on `ok=true`, `1` otherwise. With `--json`, prints the full report:
+
+```json
+{
+  "ok": false,
+  "summary": { "total_in_manifest": 730, "ok": 729, "modified": 1, "missing": 0, "extra": 0 },
+  "details": {
+    "ok": ["agents/api-guardian.md", …],
+    "modified": [{ "path": "agents/code-reviewer.md", "expected_sha256": "…", "actual_sha256": "…" }],
+    "missing": [],
+    "extra": []
+  }
+}
+```
+
+---
+
+## Verifying a downstream install
+
+```bash
+# 1) Download the manifest from the GitHub release that matches your installed version.
+gh release download v1.7.0 -p kodelyth-ecc-manifest.json -O /tmp/manifest.json
+
+# 2) Run verify against your installed copy.
+npx kodelyth-ecc verify --root "$(npm root -g)/kodelyth-ecc" --manifest /tmp/manifest.json
+```
+
+Or, if you cloned the repo:
+
+```bash
+cd ~/path/to/kodelyth-ecc
+node bin/kodelyth-ecc.js verify --manifest /tmp/manifest.json
+```
+
+A successful run looks like:
+
+```
+Kodelyth ECC supply-chain verify
+  package:           kodelyth-ecc@1.7.0
+  manifest digest:   20813125baad127bb578e4cbad6b72e2c4721d71cd236b6c039e7c155cd322ef
+  files in manifest: 730
+    ✓ ok:       730
+    ✗ modified: 0
+    ✗ missing:  0
+    ⚠ extra:    0 (advisory)
+
+✓ verify OK
+```
+
+---
+
+## SLSA provenance
+
+`.github/workflows/publish.yml` runs `npm publish --provenance --access public`. This requires `id-token: write` (set on the job) and uses GitHub's OIDC token to sign a sigstore-backed provenance statement that:
+
+1. Pins the workflow file SHA + commit SHA that produced the build.
+2. Pins the GitHub repo + ref.
+3. Pins the npm package name + version.
+
+Result: **SLSA Level 3** by npm's published criteria (hosted build platform, signed provenance, verifiable from npm registry metadata).
+
+To verify a downloaded tarball matches the npm-published provenance:
+
+```bash
+npm audit signatures kodelyth-ecc
+# or
+npm view kodelyth-ecc --json | jq .dist.signatures
+```
+
+---
+
+## Programmatic API
+
+```js
+const { generateSBOM }          = require('kodelyth-ecc/scripts/supply-chain/sbom.js');
+const { generateManifest }      = require('kodelyth-ecc/scripts/supply-chain/manifest.js');
+const { verifyAgainstManifest } = require('kodelyth-ecc/scripts/supply-chain/verify.js');
+
+const bom      = generateSBOM({ rootDir });
+const manifest = generateManifest({ rootDir });
+const report   = verifyAgainstManifest({ rootDir, manifest });
+```
+
+All three are pure functions. Safe to call from a CI step, an MCP tool, or any external automation. They never spawn subprocesses, never make network calls, and never write to disk.
+
+---
+
+## When to call which surface
+
+| Situation | Use |
+|---|---|
+| Compliance team wants an SBOM for Dependency-Track / Snyk ingestion | `sbom --out` |
+| Need to ship a tamper-detection seal with a release artifact | `manifest --out` |
+| Validating a downstream install hasn't been edited | `verify` |
+| CI gate that should fail on tamper | `verify --json` + script that checks `.ok` |
+| Reproducibility check between two release archives | `manifest` on both, diff `digest` |
+
+---
+
+## Composition with other phases
+
+| Pair | Effect |
+|---|---|
+| **2.7 swarm + verify** | Run `verify` as a pre-flight before spawning workers. Refuse to spawn from a tampered toolkit. |
+| **2.8 replay + manifest** | Embed the manifest digest of the producing toolkit into a session bundle. Replays then verify they're being run by the same toolkit version. |
+| **2.10 safety hooks + verify** | The token-budget hook can read the manifest digest at session start to surface a "you're running tampered tooling" warning. |
+| **2.1 MCP server + verify** | Expose `verify` as an MCP tool. Downstream agents can call it before trusting any other ECC tool's output. |
+
+---
+
+## Hard rules
+
+1. Treat the manifest published with a release as authoritative. **Do not** regenerate locally and pretend it's the same.
+2. **Do not** suppress a non-zero exit from `verify` in CI. Modified or missing files mean a tamper or a partial install — both are blocking.
+3. **Do not** include `node_modules/` or `.git/` in the manifest. The skip list is in `scripts/supply-chain/manifest.js`; extend deliberately if needed.
+4. **Do not** store secrets in any file under the shipped directory list. Anything that's manifested gets its sha256 published.
+
+---
+
+## See also
+
+- `skills/supply-chain-verification/SKILL.md` — explicit-invocation skill
+- `commands/verify-supply-chain.md` — `/verify-supply-chain` slash command
+- `.github/workflows/publish.yml` — release pipeline (npm provenance + SBOM + manifest upload)

package/docs/swarm.md

@@ -0,0 +1,243 @@
+# Kodelyth ECC — Swarm Orchestrator
+
+Run N ECC specialist agents in parallel inside isolated git worktrees, coordinated by a tmux session.
+
+> **Phase 2.7 of the [Devil Roadmap](../README.md).** Promotes the existing tmux-worktree orchestrator infrastructure to a first-class CLI surface. The generalized form of `/devil-mode` — pick any task, pick any agents, get N panes ready to attach.
+
+---
+
+## Why swarm
+
+A single specialist agent has tunnel vision. A pre-flight production change usually needs:
+
+- Code quality review (`code-reviewer`)
+- Security audit (`security-reviewer`)
+- API contract check (`api-guardian`)
+- Test coverage check (`tdd-guide`)
+- UX/a11y pass (`ux-reviewer`)
+- Performance check (`performance-optimizer`)
+- Doc update (`doc-updater`)
+- Release readiness (`release-captain`)
+
+Sequential = 2 hours. Parallel = 15 minutes. Each runs in its own git worktree so their changes don't collide; their handoffs merge into one folder for human review.
+
+---
+
+## CLI quick reference
+
+```bash
+# Auto-pick from task signals
+npx kodelyth-ecc swarm --task "audit oauth flow for security regressions" --agents 4
+
+# Explicit agent list
+npx kodelyth-ecc swarm \
+  --task "ship v2.0" \
+  --agents release-captain,security-reviewer,e2e-runner,code-reviewer \
+  --execute
+
+# Power-user plan.json
+npx kodelyth-ecc swarm --plan plan.json --execute
+```
+
+| Flag | Description |
+|---|---|
+| `--task "..."` | Required (unless using `--plan`). The shared task all workers receive. |
+| `--agents N` | Smart-pick N specialists from task signals + baseline + rotation. |
+| `--agents name1,name2,...` | Explicit agent list. |
+| `--harness <h>` | `claude` / `codex` / `opencode` / `windsurf` / `echo`. Default `claude`. |
+| `--launcher-cmd "<tmpl>"` | Custom launcher template (overrides `--harness`). |
+| `--seed <path>` | Overlay a path from the main repo into each worktree. Repeatable. |
+| `--session <name>` | Override the auto-generated tmux session name. |
+| `--worktree-root <dir>` | Where to create worktrees. Default: parent of repo. |
+| `--coordination-root <dir>` | Where to write coordination files. Default: `<repo>/.orchestration/`. |
+| `--base-ref <ref>` | Branch base for all worktrees. Default: `HEAD`. |
+| `--replace` | Tear down any existing session/worktrees/branches with the same names. |
+| `--execute` | Actually create worktrees + tmux + launch. |
+| `--write-only` | Just write coordination files. |
+| `--json` | Print the full plan as JSON. |
+| `--plan plan.json` | Use a hand-written plan (skips auto-build). |
+
+Default mode is **dry-run** — prints a summary and does NOT spawn anything. Always inspect first.
+
+---
+
+## Smart agent picking
+
+When you pass `--agents N` (a number), the swarm picks specialists in this priority order:
+
+### 1. Signal-driven (highest priority)
+
+Task text is scanned for 14 signal classes. Each match adds a specialist. Examples:
+
+| Task contains | Picks |
+|---|---|
+| `security`, `auth`, `vuln`, `cve`, `injection`, `owasp` | `security-reviewer` |
+| `perf`, `slow`, `p99`, `latency`, `bottleneck` | `performance-optimizer` |
+| `load test`, `stress test`, `capacity`, `k6` | `load-tester` |
+| `architect`, `design`, `ADR`, `RFC`, `trade-off` | `architect` |
+| `api`, `endpoint`, `contract`, `breaking change` | `api-guardian` |
+| `test`, `tdd`, `coverage`, `spec` | `tdd-guide` |
+| `refactor`, `tech debt`, `code smell` | `refactor-cleaner` |
+| `ux`, `accessibility`, `wcag`, `a11y` | `ux-reviewer` |
+| `doc`, `readme`, `guide`, `tutorial` | `doc-updater` |
+| `release`, `ship`, `tag`, `semver` | `release-captain` |
+| `incident`, `outage`, `down`, `P0`, `P1` | `incident-commander` |
+| `debug`, `why is`, `stack trace`, `silent fail` | `debug-detective` |
+| `database`, `sql`, `postgres`, `index`, `n+1` | `database-reviewer` |
+| `devil-mode`, `adversarial`, `red team` | `prompt-injection-hunter` |
+
+### 2. Baseline anchors
+
+`code-reviewer` and `pair-programmer` are added if not already picked — every task benefits from generalist eyes.
+
+### 3. Rotation fill
+
+If we still need more, fills from a tuned default rotation:
+
+| Count | Rotation |
+|---|---|
+| 4 | code-reviewer, security-reviewer, pair-programmer, tdd-guide |
+| 6 | + performance-optimizer, api-guardian |
+| 8 | + ux-reviewer, doc-updater |
+
+You can always override the picker with `--agents code-reviewer,security-reviewer,architect`.
+
+---
+
+## Coordination protocol
+
+Each worker gets three files in `<coord-root>/<session>/<worker-slug>/`:
+
+### `task.md` (auto-generated)
+
+Agent-shaped task with required handoff sections:
+
+```
+# <agent> — swarm task
+
+You are running as the ECC `<agent>` specialist in a parallel swarm. Other agents
+are running the same shared task in sibling worktrees. Stay strictly inside your
+specialty — do not duplicate what other agents will cover. Produce a focused
+handoff that names exactly which findings are yours and yours alone.
+
+## Shared Task
+<your task>
+
+## Required handoff sections
+1. Summary
+2. Files Changed
+3. Validation
+4. Remaining Risks
+```
+
+### `handoff.md` (worker fills in)
+
+Where the worker's output lands. Watched by the launcher.
+
+### `status.md` (launcher updates)
+
+`running` / `completed` / `failed` plus timestamp + branch + worktree path.
+
+Monitor a swarm in flight:
+
+```bash
+# All worker statuses
+cat .orchestration/<session>/*/status.md
+
+# Specific handoff
+cat .orchestration/<session>/security-reviewer/handoff.md
+```
+
+---
+
+## Harness adapters
+
+| `--harness` | Launcher template |
+|---|---|
+| `claude` | `claude --print --dangerously-skip-permissions "$(cat {task_file_sh})" 2>&1 \| tee -a {handoff_file_sh}; ...` |
+| `codex` | `bash {repo_root}/scripts/orchestrate-codex-worker.sh {task_file_sh} {handoff_file_sh} {status_file_sh}` |
+| `opencode` | `opencode run --task-file {task_file_sh} --output {handoff_file_sh} --status {status_file_sh}` |
+| `windsurf` | `windsurf-cli run --task-file {task_file_sh} --output {handoff_file_sh}` |
+| `echo` | `printf 'demo {worker_slug}\n' >> {handoff_file_sh}; printf 'state: completed\n' >> {status_file_sh}` |
+
+Custom harness via `--launcher-cmd`. Available placeholders:
+
+```
+{worker_name} {worker_slug} {session_name} {repo_root}
+{worktree_path} {branch_name} {task_file} {handoff_file} {status_file}
+```
+
+Suffix with `_sh` for shell-quoted variants: `{task_file_sh}`, `{handoff_file_sh}`, etc.
+
+---
+
+## Worktree lifecycle
+
+1. **Pre-flight** — verify `git rev-parse --is-inside-work-tree` and `tmux -V`.
+2. **Cleanup** — if `--replace`, tear down any existing session, worktrees, branches.
+3. **Materialize** — write coordination files for every worker.
+4. **Branch + worktree** — `git worktree add -b orchestrator-<session>-<slug> <path> <base-ref>`.
+5. **Seed overlay** — copy any `--seed` paths into each worktree.
+6. **Tmux session** — `tmux new-session -d -s <session> -n orchestrator -c <repo>`.
+7. **Per-worker pane** — `tmux split-window` + `select-pane` + `send-keys` to launch.
+
+On failure, automatic rollback removes worktrees, branches, and the tmux session in reverse order.
+
+Manually clean up later:
+
+```bash
+tmux kill-session -t <session>
+git worktree list                    # verify
+git worktree remove <path>
+git branch -D orchestrator-<session>-<slug>
+rm -rf .orchestration/<session>
+```
+
+---
+
+## Pairing with the rest of ECC
+
+| Pairs with | How |
+|---|---|
+| **`/devil-mode`** | Devil-mode is a hardcoded swarm of adversarial agents. Swarm generalizes it. |
+| **Phase 2.4 cost router** | Each worker classifies its own task tier; security/incident workers force hard. |
+| **Phase 2.10 token-budget hook** | Each worker has its own token budget — one rogue worker can't blow the cap. |
+| **Phase 2.5 MCP client mode** | Workers can call registered external MCP servers (github, postgres, brave, redis). |
+| **kodelyth-memory** | Save the merged handoff bundle: `kodelyth-ecc remember "..." --approach "..."`. |
+| **`release-captain`** | After a swarm, run `release-captain` to merge the best work and ship. |
+
+---
+
+## Hard rules
+
+1. **Never `--execute` without inspecting the dry-run first.** Worktree creation mutates the repo.
+2. **Don't mix incompatible agents.** `release-captain` + `migration-guide` in the same swarm produces conflicting handoffs.
+3. **Cap N at 8 for a single repo.** Past 8, worktree contention + pane crowding hurts.
+4. **Never share tmux sessions.** Use `--session NAME` explicitly when running multiple swarms.
+5. **Always human-merge handoffs.** Don't auto-apply changes from N parallel agents.
+
+---
+
+## Troubleshooting
+
+**`tmux session already exists`** — pass `--replace` to tear it down, or `--session <new-name>`.
+
+**`Worker X is missing a launcherCommand`** — pass `--harness <name>` or `--launcher-cmd "<template>"`.
+
+**`seedPaths entries must stay inside repoRoot`** — the seed must be a subpath of the repo, not an absolute external path.
+
+**Worktrees have stale state** — `--replace` cleans them. Or manually: `git worktree prune --expire now`.
+
+**A worker stalled** — `tmux attach -t <session>` and inspect its pane. Or `cat .orchestration/<session>/<slug>/status.md`.
+
+---
+
+## Roadmap interactions
+
+- **Phase 2.3 — local dashboard** will surface live swarm status (running / completed / failed per worker, latency, token usage).
+- **Phase 2.6 — sandbox layer** will optionally Docker-isolate each worker.
+- **Phase 2.8 — replay** will let you replay a finished swarm from its coordination files.
+
+---
+
+Built into [Kodelyth ECC](../README.md). MIT licensed.