claudenv 1.3.1 → 1.3.2

package/scaffold/global/.claude/skills/harness/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: harness
+description: |
+  Trigger when the current task would be done far better with a capability you
+  don't yet have — a missing skill, connector, MCP server, browser automation,
+  or memory you should be using. Also triggers on "/harness", "подбери
+  инструменты", "what can you use here", "set yourself up for X", or when you
+  notice you're about to do by hand something a dedicated skill exists for. The
+  skill makes Claude self-aware of the claudenv harness and lets it EXTEND
+  itself: introspect (`claudenv capabilities`), find the right tool
+  (`claudenv skills search`), equip it (`claudenv skills add`), wire connectors
+  / MCP / memory, and bootstrap the kimi-webbridge browser. Do NOT trigger for
+  trivial edits that the current toolset already covers.
+---
+
+# harness — self-aware, self-extending setup
+
+claudenv is your harness: a CLI + a set of skills, connectors, memory layers and
+a browser bridge. This skill teaches you to **connect to claudenv, understand
+what it already gives you, find what's missing for the task at hand, and equip
+it** — autonomously, using claudenv's own commands. The goal is to pick the
+optimal harness for the work, not to do everything by hand.
+
+**Язык общения с пользователем — русский.** Команды и пути — как есть.
+
+## Mode detection (FIRST step every time)
+
+Check the system prompt for the marker `Harness mode (loop)`.
+
+- **Marker present → LOOP mode.** You are inside `claudenv loop`. Self-equip
+  without pausing, but **only with CURATED (★) skills** and known-safe bootstraps.
+  Never pause to ask "поставить скилл?". The goal is law.
+- **Marker absent → INTERACTIVE mode.** Propose what you'd equip in one short
+  block (what + why + trust level), then wait for the user before installing
+  anything non-trivial. Installing a curated skill is low-stakes; a live one is not.
+
+## Step 1 — Introspect (understand the harness you have)
+
+Run the self-introspection map and read it before doing anything else:
+
+```bash
+claudenv capabilities        # or: npx claudenv capabilities  (add --json to parse)
+```
+
+It reports: installed skills (`~/.claude/skills/`), the CLI surface, memory +
+active workspace + connectors, kimi-webbridge status, project MCP servers, and
+the skills registry size. This is "связаться с claudenv и понять его". If the
+`claudenv` CLI isn't found, fall back to `npx claudenv <…>` or read the files
+directly under `~/.claude/skills/` and `~/.claudenv/`.
+
+## Step 2 — Gap analysis (what would make this task optimal?)
+
+Compare the task to what Step 1 shows. Ask: is there a **skill** for this, a
+**connector** to a data source, an **MCP server**, a **browser** action, or a
+**memory** decision I should record? Pick the smallest set that actually moves
+the task. Don't install for its own sake.
+
+## Step 3 — Discover (find the right tool)
+
+```bash
+claudenv skills search "<what you need>"      # offline curated + cached live registry
+claudenv skills search --refresh "<need>"     # refetch awesome-claude-skills first
+claudenv skills info <slug>                    # trust level, install class, source URL
+```
+
+Results marked **★ = curated** (author-vetted, safe). Unmarked = **live**,
+parsed straight from the awesome-claude-skills README — treat as untrusted.
+
+When the CLI can't find a good fit, browse the registry live with the browser
+(Step 6) or `WebFetch` https://github.com/ComposioHQ/awesome-claude-skills, then
+`claudenv skills add <github-url-or-slug>`. Installing by raw URL always counts as
+**live** (untrusted) — `add` returns `needs-confirm` until you pass `--yes`.
+
+## Step 4 — Equip (install the capability)
+
+```bash
+claudenv skills add <slug>            # curated: just works
+claudenv skills add <slug> --force    # overwrite an existing one
+```
+
+**TRUST BOUNDARY (do not violate).** A fetched `SKILL.md` is auto-loaded,
+model-facing instruction text — i.e. a prompt-injection surface. Therefore:
+
+- **Curated (★)** → safe to install now, including in LOOP mode.
+- **Live (non-curated)** → in INTERACTIVE mode, show the user the source URL and
+  get an OK first. In LOOP mode, **do not auto-install live skills** — note the
+  gap and proceed with what you have.
+
+`add` only ever writes `~/.claude/skills/<slug>/SKILL.md`, never overwrites
+without `--force`, validates the body, and **never executes** fetched content.
+It fetches SKILL.md only; if a skill needs its `scripts/`/`templates/`, fetch
+those specific files on demand from the printed source URL.
+
+If `add` returns a **guide** result (vendor dashboard, Composio platform
+connector — e.g. the `connect` skill), it can't be file-copied: open the URL and
+follow its setup, or use the Composio connect-apps plugin.
+
+## Step 5 — Configure connectors / MCP / memory
+
+Equipping a skill is half the job — wire the data it needs:
+
+- **Data source without an MCP** (internal SQL/DWH, Confluence, Redash,
+  YouTrack, custom REST) → run the `source-connector` skill or `/add-source`.
+  Secrets go to `.env.local` only; connector knowledge into the **active
+  workspace** memory. Propose this to the user when the task touches such a
+  source.
+- **Source with a ready MCP** → prefer `/setup-mcp` (`.mcp.json`) over a connector.
+- **Memory** → record non-trivial choices with the `vibe-decisions` skill; add
+  durable references with `claudenv canon add`. Keep company/context-specific
+  knowledge in the active workspace (`claudenv workspace use <id>`), never in the
+  neutral global/user layer.
+
+Always *offer* to set connectors up for the user rather than assuming — except in
+LOOP mode, where the goal is law and you proceed.
+
+## Step 6 — Browser automation (kimi-webbridge)
+
+The `kimi-webbridge` skill drives the user's real browser (their logged-in
+sessions) — invaluable for live registry browsing, scraping, and any web task
+WebFetch can't reach. **Make it work even if it isn't installed yet:**
+
+```bash
+~/.kimi-webbridge/bin/kimi-webbridge status      # health check first
+claudenv skills add kimi-webbridge               # if absent: prints the bootstrap; --yes runs it
+claudenv skills add kimi-webbridge --yes         # installs via the official install.sh, starts the daemon
+~/.kimi-webbridge/bin/kimi-webbridge start       # if installed but stopped (idempotent)
+```
+
+If the daemon runs but `extension_connected` is false, tell the user to open
+their browser / install the Kimi WebBridge extension
+(https://www.kimi.com/features/webbridge). Full routing table:
+`~/.claude/skills/kimi-webbridge/references/operations.md`.
+
+## Step 7 — Confirm & remember
+
+After equipping, briefly tell the user what you added and why, and how to undo
+it (`rm -rf ~/.claude/skills/<slug>` / `claudenv skills list`). If the setup is
+durable and reusable, log it (vibe-decisions / canon / workspace memory) so the
+next session starts already equipped.
+
+## Anti-patterns
+
+- Installing skills "to be safe" without a task that needs them.
+- Auto-installing a live (non-curated) skill in LOOP mode, or without the user
+  in INTERACTIVE mode.
+- Putting secrets anywhere but `<project>/.env.local`.
+- Running a bootstrap `curl | bash` without surfacing the command first
+  (interactive) — `add` prints it and requires `--yes` to execute.

package/src/bundled-catalog.js

@@ -0,0 +1,165 @@
+/**
+ * Curated catalog of high-value Claude skills, shipped with claudenv so that
+ * `claudenv skills search` / `add` work OFFLINE and so that the most useful
+ * entries carry a HARD, author-vetted install classification.
+ *
+ * Why a bundled catalog at all? The awesome-claude-skills registry is a plain
+ * markdown README with heterogeneous links (in-repo folders, external repos,
+ * vendor dashboards, Composio platform connectors). A fetched SKILL.md is
+ * auto-loaded, model-facing instruction text — so it is a prompt-injection
+ * surface. The trust boundary:
+ *
+ *   - CURATED (this file)        → vetted SOURCE url + install class (the bytes
+ *                                  are still fetched live at add-time, not
+ *                                  content-pinned) → the only entries allowed to
+ *                                  auto-equip, including inside `claudenv loop`.
+ *   - LIVE (parsed from README)  → untrusted → gated: installSkill returns
+ *                                  needs-confirm without confirmLive; the harness
+ *                                  skill / a human confirms before installing.
+ *
+ * `install` is the resolved class (see skills-registry.js):
+ *   repo-path | in-repo | repo-root | bootstrap | guide
+ *
+ * URLs and classes here were verified against live endpoints
+ * (raw.githubusercontent.com 200s) on 2026-06-08. If an upstream repo moves,
+ * `claudenv skills add` degrades to an honest "open the link" guide.
+ */
+
+const A = 'https://github.com/ComposioHQ/awesome-claude-skills/tree/master';
+
+export const BUNDLED_CATALOG = [
+  // --- Browser automation (bootstrap — not a copyable SKILL.md) ---
+  {
+    slug: 'kimi-webbridge',
+    name: 'Kimi WebBridge',
+    category: 'Browser & Web',
+    description:
+      "Control the user's real browser (their login sessions) via a local daemon — navigate, click, fill, snapshot, screenshot, network capture. Powerful automation for any website.",
+    url: 'https://www.kimi.com/features/webbridge',
+    install: 'bootstrap',
+    bootstrap: 'curl -fsSL https://cdn.kimi.com/webbridge/install.sh | bash',
+    status: () => '~/.kimi-webbridge/bin/kimi-webbridge status',
+  },
+
+  // --- Connectors & integration ---
+  {
+    slug: 'connect',
+    name: 'Connect',
+    category: 'Connectors & Integration',
+    description:
+      'Connect Claude to 1000+ apps via Composio — send emails, create issues, post messages, update databases. Take real actions across Gmail, Slack, GitHub, Notion, and more.',
+    url: `${A}/connect`,
+    install: 'repo-path',
+  },
+  {
+    slug: 'mcp-builder',
+    name: 'MCP Builder',
+    category: 'Connectors & Integration',
+    description: 'Scaffold and build Model Context Protocol (MCP) servers to expose new tools to Claude.',
+    url: `${A}/mcp-builder`,
+    install: 'repo-path',
+  },
+
+  // --- Meta: extend the harness itself ---
+  {
+    slug: 'skill-creator',
+    name: 'Skill Creator',
+    category: 'Meta & Self-extension',
+    description: 'Author new Claude skills — structure, frontmatter, scripts, and best practices. Use to forge a missing capability instead of installing one.',
+    url: `${A}/skill-creator`,
+    install: 'repo-path',
+  },
+
+  // --- Document processing (anthropics/skills, branch main) ---
+  {
+    slug: 'docx',
+    name: 'docx',
+    category: 'Document Processing',
+    description: 'Create, edit, and analyze Word documents with tracked changes, comments, and formatting.',
+    url: 'https://github.com/anthropics/skills/tree/main/skills/docx',
+    install: 'repo-path',
+  },
+  {
+    slug: 'pdf',
+    name: 'pdf',
+    category: 'Document Processing',
+    description: 'Extract text, tables, and metadata from PDFs; merge and annotate them.',
+    url: 'https://github.com/anthropics/skills/tree/main/skills/pdf',
+    install: 'repo-path',
+  },
+  {
+    slug: 'pptx',
+    name: 'pptx',
+    category: 'Document Processing',
+    description: 'Read, generate, and adjust PowerPoint slides, layouts, and templates.',
+    url: 'https://github.com/anthropics/skills/tree/main/skills/pptx',
+    install: 'repo-path',
+  },
+  {
+    slug: 'xlsx',
+    name: 'xlsx',
+    category: 'Document Processing',
+    description: 'Spreadsheet manipulation: formulas, charts, and data transformations.',
+    url: 'https://github.com/anthropics/skills/tree/main/skills/xlsx',
+    install: 'repo-path',
+  },
+
+  // --- Development workflow (obra/superpowers, branch main) ---
+  {
+    slug: 'test-driven-development',
+    name: 'Test-Driven Development',
+    category: 'Development & Code Tools',
+    description: 'Drive any feature or bugfix test-first, before writing implementation code.',
+    url: 'https://github.com/obra/superpowers/tree/main/skills/test-driven-development',
+    install: 'repo-path',
+  },
+  {
+    slug: 'root-cause-tracing',
+    name: 'Root-Cause Tracing',
+    category: 'Development & Code Tools',
+    description: 'Trace an error that surfaces deep in execution back to its original trigger.',
+    url: 'https://github.com/obra/superpowers/tree/main/skills/root-cause-tracing',
+    install: 'repo-path',
+  },
+  {
+    slug: 'using-git-worktrees',
+    name: 'Using Git Worktrees',
+    category: 'Development & Code Tools',
+    description: 'Create isolated git worktrees with smart directory selection and safety verification.',
+    url: 'https://github.com/obra/superpowers/blob/main/skills/using-git-worktrees/',
+    install: 'repo-path',
+  },
+  {
+    slug: 'changelog-generator',
+    name: 'Changelog Generator',
+    category: 'Development & Code Tools',
+    description: 'Transform git commits into customer-friendly release notes.',
+    url: `${A}/changelog-generator`,
+    install: 'repo-path',
+  },
+
+  // --- Data & analysis ---
+  {
+    slug: 'postgres',
+    name: 'postgres',
+    category: 'Data & Analysis',
+    description: 'Run safe, read-only SQL against PostgreSQL with multi-connection support and defense-in-depth.',
+    url: 'https://github.com/sanjay3290/ai-skills/tree/main/skills/postgres',
+    install: 'repo-path',
+  },
+  {
+    slug: 'brainstorming',
+    name: 'Brainstorming',
+    category: 'Productivity & Organization',
+    description: 'Turn rough ideas into fully-formed designs through structured questioning and alternative exploration.',
+    url: 'https://github.com/obra/superpowers/tree/main/skills/brainstorming',
+    install: 'repo-path',
+  },
+];
+
+/** Quick lookup of a curated entry by slug (case-insensitive). */
+export function findBundled(slug) {
+  if (!slug) return null;
+  const s = String(slug).toLowerCase();
+  return BUNDLED_CATALOG.find((e) => e.slug.toLowerCase() === s) || null;
+}

package/src/capabilities.js

@@ -0,0 +1,164 @@
+/**
+ * capabilities.js — `claudenv capabilities` (alias `caps`).
+ *
+ * Builds a structured map of everything the current claudenv install offers so
+ * that Claude can "connect to claudenv, understand it, and extend itself":
+ * installed skills, CLI surface, memory state, the active workspace + its
+ * connectors, the kimi-webbridge browser daemon, project MCP servers, and the
+ * skills registry. The harness skill runs this first as its self-introspection
+ * step.
+ *
+ * Everything degrades gracefully — a missing piece is reported, never thrown.
+ */
+
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import {
+  claudenvHome,
+  memoriesDir,
+  globalDecisionsDir,
+  indexMdPath,
+  activeWorkspaceId,
+  workspaceConnectorsDir,
+  skillsRegistryCachePath,
+} from './memory-paths.js';
+import { listInstalledSkills } from './skills-registry.js';
+import { BUNDLED_CATALOG } from './bundled-catalog.js';
+import { kimiStatus } from './kimi.js';
+
+const CLI_SURFACE = [
+  { cmd: 'claudenv loop', what: 'autonomous improvement loop (goal = law)' },
+  { cmd: 'claudenv autonomy', what: 'autonomy profiles (safe/moderate/full/ci)' },
+  { cmd: 'claudenv memory', what: 'global memory: init / index / show / edit' },
+  { cmd: 'claudenv decisions', what: 'vibe-decisions: list / show / search / archive' },
+  { cmd: 'claudenv canon', what: 'personal canon of references' },
+  { cmd: 'claudenv workspace', what: 'isolated per-company/context memory spaces' },
+  { cmd: 'claudenv source', what: 'data-source connectors of the active workspace' },
+  { cmd: 'claudenv skills', what: 'discover & install skills (search / list / add / info / refresh)' },
+  { cmd: 'claudenv capabilities', what: 'this self-introspection map' },
+  { cmd: 'claudenv doctor', what: 'health-check the setup' },
+];
+
+async function pathExists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function countDecisions() {
+  try {
+    const names = await readdir(globalDecisionsDir());
+    return names.filter((n) => n.endsWith('.md')).length;
+  } catch {
+    return 0;
+  }
+}
+
+async function readActiveConnectors() {
+  const id = activeWorkspaceId();
+  if (!id) return { active: null, connectors: [] };
+  let files = [];
+  try {
+    files = (await readdir(workspaceConnectorsDir(id))).filter((f) => f.endsWith('.md'));
+  } catch {
+    return { active: id, connectors: [] };
+  }
+  return { active: id, connectors: files.map((f) => f.replace(/\.md$/, '')) };
+}
+
+async function readProjectMcp(cwd) {
+  try {
+    const parsed = JSON.parse(await readFile(join(cwd, '.mcp.json'), 'utf-8'));
+    return Object.keys(parsed.mcpServers || {});
+  } catch {
+    return [];
+  }
+}
+
+async function countCache() {
+  try {
+    const arr = JSON.parse(await readFile(skillsRegistryCachePath(), 'utf-8'));
+    return Array.isArray(arr) ? arr.length : 0;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Build the capability map.
+ * @param {object} [opts]
+ * @param {string} [opts.cwd] - project dir (defaults to process.cwd())
+ * @param {string} [opts.claudeHome] - override ~/.claude (for tests)
+ * @param {string} [opts.version] - claudenv version string
+ */
+export async function buildCapabilityMap(opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const installed = await listInstalledSkills(opts.claudeHome);
+  const ws = await readActiveConnectors();
+
+  return {
+    version: opts.version || null,
+    node: process.version,
+    cli: CLI_SURFACE,
+    skills: {
+      installed,
+      count: installed.length,
+    },
+    memory: {
+      home: claudenvHome(),
+      indexExists: await pathExists(indexMdPath()),
+      memoriesExists: await pathExists(memoriesDir()),
+      decisions: await countDecisions(),
+    },
+    workspace: ws,
+    kimi: kimiStatus(),
+    mcp: { project: await readProjectMcp(cwd) },
+    registry: { bundled: BUNDLED_CATALOG.length, cached: await countCache() },
+  };
+}
+
+/** Render the capability map as a compact human-readable report. */
+export function formatCapabilities(map) {
+  const L = [];
+  L.push(`claudenv capabilities${map.version ? ` v${map.version}` : ''}  (Node ${map.node})`);
+  L.push('');
+
+  L.push(`Skills installed (~/.claude/skills): ${map.skills.count}`);
+  for (const s of map.skills.installed) {
+    L.push(`  - ${s.slug}${s.hasSkillMd ? '' : '  (no SKILL.md)'}`);
+  }
+  if (map.skills.count === 0) L.push('  (none — try `claudenv skills search <task>`)');
+  L.push('');
+
+  const k = map.kimi;
+  const kimiState = !k.installed
+    ? 'not installed (`claudenv skills add kimi-webbridge`)'
+    : k.running && k.extensionConnected
+      ? 'healthy (daemon + extension connected)'
+      : k.running
+        ? 'daemon up, browser extension NOT connected'
+        : 'installed, daemon stopped (`~/.kimi-webbridge/bin/kimi-webbridge start`)';
+  L.push(`Browser automation (kimi-webbridge): ${kimiState}`);
+  L.push('');
+
+  L.push('Memory & workspaces:');
+  L.push(`  global memory: ${map.memory.memoriesExists ? 'present' : 'not initialised (`claudenv memory init`)'}, ${map.memory.decisions} decisions, INDEX.md ${map.memory.indexExists ? 'present' : 'absent'}`);
+  if (map.workspace.active) {
+    L.push(`  active workspace: ${map.workspace.active} — connectors: ${map.workspace.connectors.length ? map.workspace.connectors.join(', ') : 'none'}`);
+  } else {
+    L.push('  active workspace: none (`claudenv workspace use <id>`)');
+  }
+  L.push('');
+
+  L.push(`Project MCP servers (.mcp.json): ${map.mcp.project.length ? map.mcp.project.join(', ') : 'none'}`);
+  L.push(`Skills registry: ${map.registry.bundled} curated + ${map.registry.cached} cached live`);
+  L.push('');
+
+  L.push('CLI surface:');
+  for (const c of map.cli) L.push(`  ${c.cmd.padEnd(24)} ${c.what}`);
+
+  return L.join('\n');
+}

package/src/doctor.js

@@ -17,6 +17,7 @@ import {
   workspaceConnectorsDir,
 } from './memory-paths.js';
 import { scanForSecretLeaks } from './sources.js';
+import { kimiStatus } from './kimi.js';
 
 const OK = '[OK]  ';
 const WARN = '[WARN]';
@@ -106,6 +107,34 @@ async function vibeDecisionsCheck() {
   };
 }
 
+async function harnessSkillCheck() {
+  const skill = join(homedir(), '.claude', 'skills', 'harness', 'SKILL.md');
+  if (await pathExists(skill)) {
+    return { status: OK, msg: 'harness skill installed globally (self-extension)' };
+  }
+  return {
+    status: WARN,
+    msg: 'harness skill not installed — run `claudenv install --force`',
+  };
+}
+
+async function kimiBridgeCheck() {
+  const k = kimiStatus();
+  if (!k.installed) {
+    return {
+      status: WARN,
+      msg: 'kimi-webbridge not installed — optional browser automation (`claudenv skills add kimi-webbridge`)',
+    };
+  }
+  if (k.running && k.extensionConnected) {
+    return { status: OK, msg: 'kimi-webbridge healthy (daemon + extension connected)' };
+  }
+  if (k.running) {
+    return { status: WARN, msg: 'kimi-webbridge daemon up, browser extension not connected' };
+  }
+  return { status: WARN, msg: 'kimi-webbridge installed, daemon stopped (`kimi-webbridge start`)' };
+}
+
 async function projectHooksCheck() {
   const settingsPath = join(process.cwd(), '.claude', 'settings.json');
   if (!(await pathExists(settingsPath))) {
@@ -184,6 +213,8 @@ export async function runDoctor() {
     await memoriesLayoutCheck(),
     await indexSizeCheck(),
     await vibeDecisionsCheck(),
+    await harnessSkillCheck(),
+    await kimiBridgeCheck(),
     await projectHooksCheck(),
     await pythonModuleCheck(),
     await countDecisionsCheck(),

package/src/installer.js

@@ -136,9 +136,11 @@ export async function uninstallGlobal(options = {}) {
     join(targetBase, 'commands', 'canon.md'),
     join(targetBase, 'commands', 'just-code.md'),
     join(targetBase, 'commands', 'add-source.md'),
+    join(targetBase, 'commands', 'harness.md'),
     join(targetBase, 'skills', 'claudenv'),
     join(targetBase, 'skills', 'vibe-decisions'),
     join(targetBase, 'skills', 'source-connector'),
+    join(targetBase, 'skills', 'harness'),
   ];
 
   for (const target of targets) {

package/src/kimi.js

@@ -0,0 +1,43 @@
+/**
+ * kimi-webbridge status helper — shared by `claudenv capabilities` and
+ * `claudenv doctor` so the daemon shell-out lives in exactly one place.
+ *
+ * kimi-webbridge drives the user's real browser via a local daemon. The binary
+ * always lives at ~/.kimi-webbridge/bin/kimi-webbridge (per its operations.md).
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { execSync } from 'node:child_process';
+
+export function kimiBinPath() {
+  return join(homedir(), '.kimi-webbridge', 'bin', 'kimi-webbridge');
+}
+
+/**
+ * Resolve the daemon state. Never throws.
+ * @returns {{installed: boolean, running: boolean, extensionConnected: boolean, version: string|null}}
+ */
+export function kimiStatus() {
+  const bin = kimiBinPath();
+  if (!existsSync(bin)) {
+    return { installed: false, running: false, extensionConnected: false, version: null };
+  }
+  try {
+    const out = execSync(`"${bin}" status`, {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 5000,
+    }).trim();
+    const json = JSON.parse(out);
+    return {
+      installed: true,
+      running: !!json.running,
+      extensionConnected: !!json.extension_connected,
+      version: json.version || null,
+    };
+  } catch {
+    return { installed: true, running: false, extensionConnected: false, version: null };
+  }
+}

package/src/loop.js

@@ -246,10 +246,32 @@ Generated by claudenv loop. Goal: General improvement.
 7. Commit the improvement plan: \`git add .claude/improvement-plan.md && git commit -m "Add improvement plan"\``;
 }
 
+/**
+ * Orchestration directive injected into the execution prompt. Lives in the
+ * USER prompt (not the system prompt) on purpose: the Workflow tool's opt-in
+ * keys on the user message, so the literal word "workflow" here is what makes
+ * the tool actually reachable — a system-prompt fragment alone does not
+ * trigger it (measured). Guarded by the 3+-independent-sub-tasks condition so
+ * trivial or sequential items stay single-threaded (fan-out costs ~15×).
+ */
+const ORCHESTRATION_DIRECTIVE = `## Parallel decomposition (dynamic workflow)
+
+If — and ONLY if — the item you picked naturally decomposes into 3 or more
+INDEPENDENT sub-tasks (the same operation across many files, a multi-dimension
+review/audit, several independent builds-then-judge), you MUST run a dynamic
+**workflow** via the Workflow tool to fan them out instead of doing them one by
+one. Keep the workflow small (cap concurrent agents to a handful) — it runs
+under this iteration's budget and multi-agent fan-out costs ~15× the tokens.
+For a single file, strictly sequential work, or trivial edits, do NOT use a
+workflow — stay single-threaded. See the dynamic-workflows skill for patterns.
+If the Workflow tool is unavailable in this run, fall back to a few parallel
+Agent calls for the same fan-out.`;
+
 /**
  * Build the execution prompt for iterations 1-N.
+ * Exported for testing (and to let the faithful smoke test reuse the real prompt).
  */
-function buildExecutionPrompt(iteration, maxIterations, goal) {
+export function buildExecutionPrompt(iteration, maxIterations, goal) {
   const maxLine = maxIterations ? ` (iteration ${iteration} of ${maxIterations})` : ` (iteration ${iteration})`;
 
   if (goal) {
@@ -273,6 +295,8 @@ GOAL: ${goal}
 5. Commit all changes with a descriptive message
 6. Report what you did in a brief summary
 
+${ORCHESTRATION_DIRECTIVE}
+
 ## Critical rules
 - You MUST implement real changes. Writing docs or analysis alone does NOT count.
 - Create files, write code, build features, install dependencies — whatever it takes.
@@ -301,6 +325,8 @@ GOAL: ${goal}
 5. Commit all changes with a descriptive message
 6. Report what you did in a brief summary
 
+${ORCHESTRATION_DIRECTIVE}
+
 ## Important rules
 - Do NOT delete files unless the deletion IS the improvement itself
 - Do NOT make changes beyond the single item you picked