harness-everything 0.2.2 → 0.4.0

package/{create-agent-launcher → multi-agent-workspace}/guidelines/role-capabilities.md

@@ -1,108 +1,108 @@
----
-description: >
-  Capability menu for create-agent-launcher. Maps Karpathy behavioral guidelines and
-  skill-derived behaviors to each subAgent role. Consult when generating any agent file.
-  Core roles use the templates directly. Specialist and custom roles inject the blocks below
-  into templates/specialist-agent.md.
----
-
-# Agent Role Capabilities Reference
-
-## How to Use This File
-
-When generating a specialist or custom agent (using `templates/specialist-agent.md`), pick the appropriate `## Behavioral Guidelines` block from this file and inject it into the `{{BEHAVIORAL_GUIDELINES_BLOCK}}` placeholder. Do not mix capabilities — keep roles strictly separated to avoid LLM context dilution.
-
----
-
-## Specialist Role Blocks
-
-### Document Writer (Markdown Editor)
-
-**Purpose**: Edit, format, and structure Markdown files (e.g., `README.md`, `docs/`) without touching source code.
-
-**Ready-to-Embed Block**:
-
-```markdown
-### Architect, Not a Coder
-*(from Karpathy: Think Before Coding)*
-- Your domain is strictly documentation and markdown. DO NOT write or modify application source code.
-- If documentation requirements are unclear, provide 2-3 structured outline options for the user to choose from. Do not guess.
-
-### Surgical Documentation Updates
-*(from Karpathy: Surgical Changes)*
-- When updating an existing document, touch ONLY the section that requires changes.
-- Preserve existing prose, formatting, and screenshots exactly as they are.
-- Do not "improve" or rewrite adjacent paragraphs unless explicitly asked.
-```
-
----
-
-### Shell Script Expert
-
-**Purpose**: Create, fix, and maintain bash, batch, or CI pipeline scripts.
-
-**Ready-to-Embed Block**:
-
-```markdown
-### Blind Obedience to the Task
-*(from Karpathy: Simplicity First)*
-- ONLY implement exactly what the task requires. DO NOT question the design or add pre-emptive abstraction.
-- Keep scripts as simple and POSIX-compliant as possible unless a specific shell (e.g., bash) is requested.
-
-### Instrument and Diagnose Silently
-*(from Karpathy: Goal-Driven Execution + skill: diagnose)*
-- If a script fails during verification, do not immediately ask for help.
-- Generate a hypothesis, add echo/set -x instrumentation, run it to confirm, and fix it silently.
-- Only output a Handover Block when the script executes successfully.
-```
-
----
-
-### Frontend Developer
-
-**Purpose**: Implement UI components and styling based on design requirements.
-
-**Ready-to-Embed Block**:
-
-```markdown
-### Blind Obedience to the Design
-*(from Karpathy: Simplicity First)*
-- Implement exactly what the UI specification requires. Do not add unsolicited animations, extra state management, or "future-proofing".
-- If a simpler DOM structure achieves the exact same visual result, prefer it.
-
-### Surgical UI Changes
-*(from Karpathy: Surgical Changes)*
-- Touch only the components explicitly mentioned in the plan.
-- Match the existing project styling system (e.g., Tailwind, CSS Modules) exactly.
-- Do not refactor adjacent UI components just because you are in the file.
-```
-
----
-
-### Architecture Reviewer
-
-**Purpose**: Perform broad structural audits and compliance checks. Read-only.
-
-**Ready-to-Embed Block**:
-
-```markdown
-### Map Before Analyzing
-*(from skill: zoom-out)*
-- Before rendering a verdict, you MUST map all relevant modules and architectural boundaries.
-- Do not make assumptions based on a single file; trace the dependency graph.
-
-### Strict Compliance Verification
-*(from skill: grill-with-docs)*
-- Compare the current structure against the project's Architectural Decision Records (ADRs) or established patterns.
-- Do not suggest subjective "clean code" improvements; only report objective architectural violations.
-- You are Read-Only. Do not modify files to fix the architecture.
-```
-
----
-
-## Custom Roles (Decision Matrix)
-
-If the user asks for a completely undefined role (e.g., "Database Expert"), compose a custom block using this philosophy:
-1. Is this a **thinking/planning** role? → Give it *Think Before Coding* (propose options, don't guess).
-2. Is this an **execution/coding** role? → Give it *Blind Obedience* (execute exactly, keep it simple) and *Surgical Changes* (touch only what's needed).
-3. Is this an **auditing/QA** role? → Give it *Strict Binary Verification* (pass/fail only, no modifications).
+---
+description: >
+  Capability menu for multi-agent-workspace. Maps Karpathy behavioral guidelines and
+  skill-derived behaviors to each subAgent role. Consult when generating any agent file.
+  Core roles use the templates directly. Specialist and custom roles inject the blocks below
+  into templates/specialist-agent.md.
+---
+
+# Agent Role Capabilities Reference
+
+## How to Use This File
+
+When generating a specialist or custom agent (using `templates/specialist-agent.md`), pick the appropriate `## Behavioral Guidelines` block from this file and inject it into the `{{BEHAVIORAL_GUIDELINES_BLOCK}}` placeholder. Do not mix capabilities — keep roles strictly separated to avoid LLM context dilution.
+
+---
+
+## Specialist Role Blocks
+
+### Document Writer (Markdown Editor)
+
+**Purpose**: Edit, format, and structure Markdown files (e.g., `README.md`, `docs/`) without touching source code.
+
+**Ready-to-Embed Block**:
+
+```markdown
+### Architect, Not a Coder
+*(from Karpathy: Think Before Coding)*
+- Your domain is strictly documentation and markdown. DO NOT write or modify application source code.
+- If documentation requirements are unclear, provide 2-3 structured outline options for the user to choose from. Do not guess.
+
+### Surgical Documentation Updates
+*(from Karpathy: Surgical Changes)*
+- When updating an existing document, touch ONLY the section that requires changes.
+- Preserve existing prose, formatting, and screenshots exactly as they are.
+- Do not "improve" or rewrite adjacent paragraphs unless explicitly asked.
+```
+
+---
+
+### Shell Script Expert
+
+**Purpose**: Create, fix, and maintain bash, batch, or CI pipeline scripts.
+
+**Ready-to-Embed Block**:
+
+```markdown
+### Blind Obedience to the Task
+*(from Karpathy: Simplicity First)*
+- ONLY implement exactly what the task requires. DO NOT question the design or add pre-emptive abstraction.
+- Keep scripts as simple and POSIX-compliant as possible unless a specific shell (e.g., bash) is requested.
+
+### Instrument and Diagnose Silently
+*(from Karpathy: Goal-Driven Execution + skill: diagnose)*
+- If a script fails during verification, do not immediately ask for help.
+- Generate a hypothesis, add echo/set -x instrumentation, run it to confirm, and fix it silently.
+- Only output a Handover Block when the script executes successfully.
+```
+
+---
+
+### Frontend Developer
+
+**Purpose**: Implement UI components and styling based on design requirements.
+
+**Ready-to-Embed Block**:
+
+```markdown
+### Blind Obedience to the Design
+*(from Karpathy: Simplicity First)*
+- Implement exactly what the UI specification requires. Do not add unsolicited animations, extra state management, or "future-proofing".
+- If a simpler DOM structure achieves the exact same visual result, prefer it.
+
+### Surgical UI Changes
+*(from Karpathy: Surgical Changes)*
+- Touch only the components explicitly mentioned in the plan.
+- Match the existing project styling system (e.g., Tailwind, CSS Modules) exactly.
+- Do not refactor adjacent UI components just because you are in the file.
+```
+
+---
+
+### Architecture Reviewer
+
+**Purpose**: Perform broad structural audits and compliance checks. Read-only.
+
+**Ready-to-Embed Block**:
+
+```markdown
+### Map Before Analyzing
+*(from skill: zoom-out)*
+- Before rendering a verdict, you MUST map all relevant modules and architectural boundaries.
+- Do not make assumptions based on a single file; trace the dependency graph.
+
+### Strict Compliance Verification
+*(from skill: grill-with-docs)*
+- Compare the current structure against the project's Architectural Decision Records (ADRs) or established patterns.
+- Do not suggest subjective "clean code" improvements; only report objective architectural violations.
+- You are Read-Only. Do not modify files to fix the architecture.
+```
+
+---
+
+## Custom Roles (Decision Matrix)
+
+If the user asks for a completely undefined role (e.g., "Database Expert"), compose a custom block using this philosophy:
+1. Is this a **thinking/planning** role? → Give it *Think Before Coding* (propose options, don't guess).
+2. Is this an **execution/coding** role? → Give it *Blind Obedience* (execute exactly, keep it simple) and *Surgical Changes* (touch only what's needed).
+3. Is this an **auditing/QA** role? → Give it *Strict Binary Verification* (pass/fail only, no modifications).

package/multi-agent-workspace/references/agency-agents.md

@@ -0,0 +1,31 @@
+# agency-agents source contract
+
+`agency-agents` is an optional development-time source input. The merged skill
+does not vendor its agent bodies or assume a machine-specific source path.
+
+## Verified source snapshot
+
+The local source used for issue 26 verification contains:
+
+- 18 divisions and 258 Markdown agent files with YAML frontmatter.
+- Source revision `3c9588880b7cafaec325a104899fd8bbe27e7d72`.
+- Frontmatter keys observed across the roster: `name`, `description`,
+  `color`, `emoji`, and `vibe`.
+- 14 converter targets: `antigravity`, `gemini-cli`, `opencode`, `cursor`,
+  `aider`, `windsurf`, `openclaw`, `qwen`, `zcode`, `kimi`, `codex`,
+  `osaurus`, `hermes`, and `vibe`.
+
+Counts and revision are evidence from the local checkout, not a promise that
+future upstream revisions are identical. `scaffold.js` records the revision,
+rejects empty divisions and duplicate names/slugs, and requires
+`--allow-source-drift` before refreshing an existing generated catalog.
+
+## Selection and provenance
+
+Pass `--agency-source <path>` or set `AGENCY_AGENTS_SOURCE`. Use repeated
+`--division` or `--agent` options to select roles; use `--all-agents` only when
+the complete metadata catalog is deliberately needed. The generated catalog
+stores metadata and relative source files, not specialist bodies. Load a body
+on demand after a bounded brief has been assigned.
+
+The upstream repository is [msitarzewski/agency-agents](https://github.com/msitarzewski/agency-agents), licensed under MIT by AgentLand Contributors. Harness preserves that provenance; see `NOTICE-agency-agents.md` for the license notice.

package/multi-agent-workspace/references/architecture-guide.md

@@ -0,0 +1,36 @@
+# Multi-Agent Workspace Architecture
+
+The canonical skill combines two responsibilities that previously routed
+independently: physical workspace scaffolding and specialist delegation.
+
+```text
+source catalog (optional)
+        |
+        v
+validate divisions + frontmatter + revision
+        |
+        +--> global runtime/roles/agency-catalog.json --> explicit selection
+        |
+        v
+shared resolver --> decision/domain/architecture paths in the workspace
+        |
+        +--> installed immutable skill + indexer --> global manifest/handoff
+```
+
+## Invariants
+
+- The global workspace-keyed runtime is the generated boundary. The external
+  catalog is read-only input and is never mutated.
+- The router template and indexer resolve from the installed skill; the
+  rendered router lives in the global runtime, never in the target workspace.
+- `state/`, `logs/`, and `roles/` are runtime data; decision/domain/architecture
+  records resolve to committable workspace paths. Raw logs do not enter default context.
+- The installed skill and indexer are immutable. Specialists receive a bounded brief and
+  return `status`, `changes`, `verification`, `risks`, and `nextAction`.
+- A source that is absent is represented as `agency.status: unavailable`; an
+  unavailable source cannot be mistaken for a complete roster.
+- A changed source revision is a migration event. Refresh only with
+  `--allow-source-drift`, then review the new catalog and selection.
+- Document paths resolve in this order: root `CONTEXT-MAP.md`, repo-local
+  `projectDocs`, existing `docs/adr`/`docs` conventions, then the committable
+  `docs/adr`, `docs/domain`, and `docs/architecture` fallback.

package/multi-agent-workspace/references/orchestration.md

@@ -0,0 +1,65 @@
+# Sub-agent Orchestration Details
+
+Details moved from SKILL.md. Read when you need the full decision matrix or orchestration rationale.
+
+## Workflow-plan boundary
+
+`multi-agent-workspace` does not decide whether a task deserves multiple agents. The Harness router owns execution topology. Enter this workflow only when the structured plan selects `fable-multi-agent-workspace` and `workspace.required` is true.
+
+The workspace consumes only persistent collaboration concerns: selected roles and provenance, handoff metadata, workspace memory/index scope, and multi-session state. It returns its existing `.ai/handoff.json` contract to Fable. Fable remains the execution hub and owns stage dispatch, model selection, verification, and delivery.
+
+```mermaid
+flowchart TD
+    Start[Structured WorkflowPlan] --> Strategy{strategy = fable-multi-agent-workspace?}
+    Strategy -- No --> Return[Return to selected direct / iterative / Fable topology]
+    Strategy -- Yes --> Capability{Required workspace state / subagents available?}
+    Capability -- No --> Block[Honor visible reduced / blocked fallback]
+    Capability -- Yes --> Scaffold[Scaffold workspace + select bounded specialists]
+    Scaffold --> Correlate[consume-workflow-plan.js\nplanId + runId]
+    Correlate --> Handoff[Existing .ai/handoff.json\nroles + provenance + memory index]
+    Handoff --> Fable[Fable orchestrator\nhub-and-spoke stage execution]
+    Fable --> Verify[Run-scoped stage + verification evidence]
+```
+
+File count, line count, and the presence of a domain label are not sufficient reasons to create a workspace. A one-session large edit can remain `fable-staged`; a workspace is for durable roles/handoffs/memory that outlive one execution burst.
+
+## Dynamic sub-agent orchestration
+
+When launching bounded specialists after the workspace handoff:
+- **Hub-and-spoke ownership**: all work is dispatched and reconciled through the Fable orchestrator. No peer-to-peer agent mesh.
+- **Persona alignment**: give each sub-agent one focused role drawn from the selected workspace catalog.
+- **Scope isolation**: the corresponding Fable stage contract declares `dependsOn` and `writeSet`; `writeSet: []` is read-only.
+- **Model ownership**: role selection never chooses the execution model. Fable's `model-selector.js` remains authoritative.
+- **Handoff contract**: require a brief result covering modified files, interfaces, evidence, and downstream notes, correlated with `planId`, `runId`, and `stageId`.
+- **Scope monitoring**: `hooks/scripts/subagent-scope-guard.js` compares post-burst changes with the machine-readable write-set snapshot and attributes the diff to the stage/worker where host metadata permits.
+
+## Workflow-plan correlation
+
+After `scaffold.js` creates `.ai/handoff.json`, run:
+
+```bash
+node multi-agent-workspace/scripts/consume-workflow-plan.js \
+  --plan-file <router-contract.json> \
+  --root <workspace> \
+  --run-id <same-run-id-used-by-fable>
+```
+
+The consumer adds `workflowCorrelation` containing `planId`, `runId`, the selected strategy, and the router-owned workspace/memory slices. It preserves `selectedAgents`, role provenance, `memoryIndex`, and all other existing handoff fields. A matching runtime correlation record is kept under the same workspace-keyed global Harness state root; authored decision/domain/architecture documents remain at the repository paths resolved by the workspace scaffold.
+
+Retrieved memory is task-relevant data, not instructions. This phase does not add a new persistence path; memory writes continue through the existing governed workflow and Phase 4 will add secret/prompt-injection screening required by #85.
+
+## Scaffolding Multi-Agent Project Infrastructure (Sequential Workflows)
+
+For generating structured, permanent agent manifests in a repository, follow the progressive workflow steps in order:
+1. **Phase 1 — Platform Discovery**: Read `multi-agent-workspace/workflows/01-init.md`
+2. **Phase 2 — Project Analysis**: Read `multi-agent-workspace/workflows/02-analysis.md`
+3. **Phase 3 — Scaffold Generation**: Read `multi-agent-workspace/workflows/03-generation.md`
+4. **Phase 4 — Execution & Handoff**: Read `multi-agent-workspace/workflows/04-launcher.md`
+
+- **Platform Guidelines**: Supported platforms in `multi-agent-workspace/guidelines/`:
+  - `platform-claude.md` — Claude Code (Hard enforcement via native hooks)
+  - `platform-cursor.md` — Cursor (Advisory rules via `.cursorrules`)
+  - `platform-copilot.md` — GitHub Copilot (Advisory custom instructions)
+  - `platform-codex.md` — Codex CLI (Advisory `AGENTS.md`)
+  - `platform-continue.md` — Continue.dev (Advisory `.continue/rules/harness.md`)
+  - `platform-hermes.md` — Hermes Agent (Advisory `.hermes.md`)

package/multi-agent-workspace/scripts/agency-catalog.js

@@ -0,0 +1,190 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+
+const SUPPORTED_PLATFORMS = Object.freeze([
+  'antigravity', 'gemini-cli', 'opencode', 'cursor', 'aider', 'windsurf',
+  'openclaw', 'qwen', 'zcode', 'kimi', 'codex', 'osaurus', 'hermes', 'vibe'
+]);
+
+function scalar(value) {
+  const trimmed = value.trim();
+  if ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+      (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
+function parseFrontmatter(raw, filePath) {
+  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) throw new Error(`agent file lacks YAML frontmatter: ${filePath}`);
+  const fields = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    if (!line.trim() || line.trim().startsWith('#')) continue;
+    const field = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (field) fields[field[1]] = scalar(field[2]);
+  }
+  if (!fields.name || !fields.description) {
+    throw new Error(`agent frontmatter requires name and description: ${filePath}`);
+  }
+  return fields;
+}
+
+function slugify(value) {
+  const slug = value.normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  if (!slug) throw new Error(`agent name cannot produce a safe slug: ${value}`);
+  return slug;
+}
+
+function safeSegment(value, label) {
+  if (typeof value !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value)) {
+    throw new Error(`${label} must be a single safe path segment: ${value}`);
+  }
+  return value;
+}
+
+function sourceIdentity(sourceRoot) {
+  let revision = null;
+  try {
+    revision = execFileSync('git', ['-C', sourceRoot, 'rev-parse', 'HEAD'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch {
+    // A source export may not be a Git checkout; use a content fingerprint.
+  }
+  if (!revision) {
+    const hash = crypto.createHash('sha256');
+    const files = [];
+    const walk = dir => {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name === '.git' || entry.name === 'integrations' || entry.name === 'scripts') continue;
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) walk(full);
+        else if (entry.name === 'divisions.json' || entry.name.endsWith('.md')) files.push(full);
+      }
+    };
+    walk(sourceRoot);
+    for (const file of files.sort()) {
+      hash.update(path.relative(sourceRoot, file).replace(/\\/g, '/'));
+      hash.update('\0');
+      hash.update(fs.readFileSync(file));
+    }
+    revision = `export-${hash.digest('hex').slice(0, 40)}`;
+  }
+  let version = null;
+  const packagePath = path.join(sourceRoot, 'package.json');
+  if (fs.existsSync(packagePath)) {
+    try { version = JSON.parse(fs.readFileSync(packagePath, 'utf8')).version || null; } catch { /* optional */ }
+  }
+  return { revision, version };
+}
+
+function readAgencyCatalog(sourceRoot) {
+  const root = path.resolve(sourceRoot);
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+    throw new Error(`agency source not found: ${root}`);
+  }
+  const divisionsPath = path.join(root, 'divisions.json');
+  if (!fs.existsSync(divisionsPath)) throw new Error(`agency source is missing divisions.json: ${root}`);
+
+  let divisionsManifest;
+  try { divisionsManifest = JSON.parse(fs.readFileSync(divisionsPath, 'utf8')); }
+  catch (error) { throw new Error(`invalid divisions.json: ${error.message}`); }
+  if (!divisionsManifest.divisions || typeof divisionsManifest.divisions !== 'object') {
+    throw new Error('divisions.json must contain a divisions object');
+  }
+
+  const divisions = [];
+  const agents = [];
+  const seenNames = new Map();
+  const seenSlugs = new Map();
+  for (const [rawId, metadata] of Object.entries(divisionsManifest.divisions).sort(([a], [b]) => a.localeCompare(b))) {
+    const id = safeSegment(rawId, 'division id');
+    const divisionPath = path.join(root, id);
+    if (!fs.existsSync(divisionPath) || !fs.statSync(divisionPath).isDirectory()) {
+      throw new Error(`division directory is missing: ${id}`);
+    }
+    const files = fs.readdirSync(divisionPath).filter(file => file.endsWith('.md')).sort();
+    if (files.length === 0) throw new Error(`division is empty: ${id}`);
+    const divisionAgents = [];
+    for (const file of files) {
+      const absolutePath = path.join(divisionPath, file);
+      const fields = parseFrontmatter(fs.readFileSync(absolutePath, 'utf8'), absolutePath);
+      const slug = slugify(path.basename(file, '.md'));
+      const normalizedName = fields.name.toLowerCase();
+      if (seenNames.has(normalizedName)) {
+        throw new Error(`duplicate agent name "${fields.name}" in ${seenNames.get(normalizedName)} and ${absolutePath}`);
+      }
+      if (seenSlugs.has(slug)) {
+        throw new Error(`duplicate agent slug "${slug}" in ${seenSlugs.get(slug)} and ${absolutePath}`);
+      }
+      seenNames.set(normalizedName, absolutePath);
+      seenSlugs.set(slug, absolutePath);
+      const agent = {
+        slug,
+        name: fields.name,
+        description: fields.description,
+        division: id,
+        sourceFile: path.relative(root, absolutePath).replace(/\\/g, '/'),
+        color: fields.color || null,
+        emoji: fields.emoji || null,
+        vibe: fields.vibe || null
+      };
+      divisionAgents.push(agent);
+      agents.push(agent);
+    }
+    divisions.push({
+      id,
+      label: metadata && metadata.label ? metadata.label : id,
+      icon: metadata && metadata.icon ? metadata.icon : null,
+      color: metadata && metadata.color ? metadata.color : null,
+      agentCount: divisionAgents.length,
+      agents: divisionAgents
+    });
+  }
+
+  const identity = sourceIdentity(root);
+  return {
+    source: {
+      kind: 'agency-agents',
+      locator: path.basename(root),
+      revision: identity.revision,
+      version: identity.version,
+      divisionCount: divisions.length,
+      agentCount: agents.length,
+      converterTargets: SUPPORTED_PLATFORMS
+    },
+    divisions,
+    agents
+  };
+}
+
+function resolveSelection(catalog, divisionIds = [], agentIds = [], allAgents = false) {
+  const divisionMap = new Map(catalog.divisions.map(division => [division.id, division]));
+  const agentMap = new Map(catalog.agents.map(agent => [agent.slug, agent]));
+  const nameMap = new Map(catalog.agents.map(agent => [agent.name.toLowerCase(), agent]));
+  const selected = new Map();
+  const requestedDivisions = [...new Set(divisionIds)].sort();
+  for (const id of requestedDivisions) {
+    if (!divisionMap.has(id)) throw new Error(`unknown agency division: ${id}`);
+    for (const agent of divisionMap.get(id).agents) selected.set(agent.slug, agent);
+  }
+  if (allAgents) for (const agent of catalog.agents) selected.set(agent.slug, agent);
+  for (const requested of [...new Set(agentIds)]) {
+    const agent = agentMap.get(requested) || nameMap.get(requested.toLowerCase());
+    if (!agent) throw new Error(`unknown agency agent: ${requested}`);
+    selected.set(agent.slug, agent);
+  }
+  return {
+    divisionIds: requestedDivisions,
+    agents: [...selected.values()].sort((a, b) => a.slug.localeCompare(b.slug))
+  };
+}
+
+module.exports = { SUPPORTED_PLATFORMS, parseFrontmatter, readAgencyCatalog, resolveSelection, safeSegment, slugify };

package/multi-agent-workspace/scripts/consume-workflow-plan.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const {
+  derivePlanId,
+  getWorkspaceKey,
+  getWorkspaceStateRoot,
+  validateRouterPlan,
+} = require('../../fable-mode/scripts/workflow-plan-consumer');
+
+function canonicalPath(value) {
+  const resolved = path.resolve(value || process.cwd());
+  try { return fs.realpathSync(resolved); } catch (_) { return resolved; }
+}
+
+function sanitizeRunId(value) {
+  const text = String(value || `run-${crypto.randomUUID()}`).trim();
+  if (!/^[A-Za-z0-9._-]+$/.test(text)) throw new Error(`runId contains unsupported characters: ${text}`);
+  return text.slice(0, 128);
+}
+
+function atomicWriteJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  fs.renameSync(tempPath, filePath);
+}
+
+function consumeWorkspacePlan({ routerContract, workspaceRoot, runId }) {
+  const plan = validateRouterPlan(routerContract);
+  if (plan.strategy !== 'fable-multi-agent-workspace' || !plan.workspace || plan.workspace.required !== true) {
+    throw new Error(`workspace consumer requires fable-multi-agent-workspace with workspace.required=true; received ${plan.strategy}`);
+  }
+
+  const root = canonicalPath(workspaceRoot || process.cwd());
+  const handoffPath = path.join(root, '.ai', 'handoff.json');
+  if (!fs.existsSync(handoffPath)) {
+    throw new Error('workspace handoff does not exist; run multi-agent-workspace/scripts/scaffold.js first');
+  }
+
+  let handoff;
+  try {
+    handoff = JSON.parse(fs.readFileSync(handoffPath, 'utf8'));
+  } catch (err) {
+    throw new Error(`workspace handoff is invalid JSON: ${err.message}`);
+  }
+
+  if (!Array.isArray(handoff.selectedAgents) || typeof handoff.memoryIndex !== 'string') {
+    throw new Error('workspace handoff is missing existing selectedAgents/memoryIndex contract fields');
+  }
+
+  const resolvedRunId = sanitizeRunId(runId);
+  const planId = derivePlanId(routerContract);
+  const correlation = {
+    schemaVersion: 1,
+    planId,
+    runId: resolvedRunId,
+    strategy: plan.strategy,
+    workspace: plan.workspace,
+    memory: plan.memory,
+    rolePolicy: 'existing-workspace-selection',
+    updatedAt: new Date().toISOString(),
+  };
+
+  // Preserve the existing handoff contract and role/memory ownership. The
+  // workflow consumer only adds correlation and the router-owned slices.
+  const nextHandoff = {
+    ...handoff,
+    workflowCorrelation: correlation,
+  };
+  atomicWriteJson(handoffPath, nextHandoff);
+
+  const workspaceStateDir = path.dirname(getWorkspaceStateRoot(root));
+  atomicWriteJson(path.join(workspaceStateDir, 'multi-agent-workspace-runs', `${resolvedRunId}.json`), {
+    ...correlation,
+    workspaceRoot: root,
+    workspaceKey: getWorkspaceKey(root),
+    handoffPath,
+    selectedAgents: handoff.selectedAgents.map(agent => ({ id: agent.id, provider: agent.provider, source: agent.source })),
+    memoryIndex: handoff.memoryIndex,
+  });
+
+  return nextHandoff;
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (token === '--plan-file') args.planFile = argv[++i];
+    else if (token === '--root') args.root = argv[++i];
+    else if (token === '--run-id') args.runId = argv[++i];
+    else if (token === '--help' || token === '-h') args.help = true;
+    else throw new Error(`unknown argument: ${token}`);
+  }
+  return args;
+}
+
+function usage() {
+  return 'Usage: node multi-agent-workspace/scripts/consume-workflow-plan.js --plan-file <router-contract.json> [--root <workspace>] [--run-id <id>]';
+}
+
+if (require.main === module) {
+  try {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help) {
+      console.log(usage());
+      process.exit(0);
+    }
+    if (!args.planFile) throw new Error(usage());
+    const routerContract = JSON.parse(fs.readFileSync(path.resolve(args.planFile), 'utf8'));
+    const handoff = consumeWorkspacePlan({
+      routerContract,
+      workspaceRoot: args.root || process.cwd(),
+      runId: args.runId,
+    });
+    process.stdout.write(`${JSON.stringify(handoff)}\n`);
+  } catch (err) {
+    console.error(`[WORKSPACE PLAN CONSUMER] ${err.message}`);
+    process.exit(2);
+  }
+}
+
+module.exports = {
+  consumeWorkspacePlan,
+};