claudenv 1.3.1 → 1.3.2

package/README.md

@@ -2,9 +2,11 @@
 
 [![npm](https://img.shields.io/npm/v/claudenv.svg)](https://www.npmjs.com/package/claudenv)
 
-Set up [Claude Code](https://docs.anthropic.com/en/docs/claude-code) in any project with one command. claudenv analyzes your codebase and generates everything Claude needs to work effectively — documentation, rules, hooks, MCP servers, slash commands, **plus cross-session memory and vibe-decisions logging (1.3.0).**
+Set up [Claude Code](https://docs.anthropic.com/en/docs/claude-code) in any project with one command. claudenv analyzes your codebase and generates everything Claude needs to work effectively — documentation, rules, hooks, MCP servers, slash commands, **cross-session memory, and a self-extending harness that equips Claude with new skills on demand (1.3.2).**
 
-> **New in 1.3.0** — split memory layout (`~/.claudenv/memories/` global + `.claude/memories/` project), `vibe-decisions` skill (auto-log in loop, pause-and-ask interactive), new CLI: `memory`, `decisions`, `canon`, `doctor`. Companion Python package `claudenv-memory` on PyPI (alpha). See [CHANGELOG.md](./CHANGELOG.md).
+> **New in 1.3.2 — self-extending harness.** Claude can now introspect what claudenv gives it (`claudenv capabilities`), find what's missing for the task, and equip it from the [awesome-claude-skills](https://github.com/ComposioHQ/awesome-claude-skills) registry (`claudenv skills search|add`) — plus first-class **kimi-webbridge** browser automation. New `/harness` command + skill drive it autonomously. See [CHANGELOG.md](./CHANGELOG.md).
+>
+> **1.3.0** — split memory layout, `vibe-decisions` skill, CLI: `memory`, `decisions`, `canon`, `doctor`. Companion Python package `claudenv-memory` on PyPI (alpha).
 
 ## Quick Start
 
@@ -214,6 +216,72 @@ claudenv doctor                          # OK/WARN/FAIL check
 
 After each iteration, `claudenv loop` regenerates `INDEX.md` so the next iteration's briefing reflects what was just decided.
 
+## Self-extending harness (1.3.2)
+
+claudenv is Claude's *harness* — a CLI plus skills, connectors, memory, and a
+browser bridge. The `harness` skill makes Claude **self-aware** of it and lets it
+**extend itself**: understand what it already has, find what's missing for the
+task, and equip it — autonomously.
+
+```bash
+claudenv capabilities          # self-introspection: skills, memory, workspace,
+                               # connectors, kimi-webbridge, MCP, registry
+claudenv skills search "pdf"   # find a skill (curated + awesome-claude-skills)
+claudenv skills add docx       # install it into ~/.claude/skills/
+claudenv skills add kimi-webbridge   # bootstrap browser automation
+```
+
+In Claude Code, `/harness` (or just describe a task that needs a capability you
+lack) runs the whole flow: introspect → gap-analysis → discover → equip →
+configure connectors/MCP/memory → bootstrap the browser.
+
+### Skills registry
+
+`claudenv skills` discovers skills from
+[awesome-claude-skills](https://github.com/ComposioHQ/awesome-claude-skills). The
+registry is a heterogeneous markdown README, so each entry is resolved by **install
+class**:
+
+| Class | Example | Behavior |
+|---|---|---|
+| `repo-path` | `github.com/anthropics/skills/tree/main/skills/docx` | fetch raw `SKILL.md` |
+| `in-repo` | a `./folder/` link in the README | fetch from the awesome repo |
+| `repo-root` | `github.com/user/skill` | best-effort probe, else guide |
+| `bootstrap` | kimi-webbridge | run an install command (e.g. `install.sh`) |
+| `guide` | a vendor dashboard / Composio connector | open the link to set up |
+
+A curated **bundled catalog** ships with claudenv, so `search`/`add` work
+**offline**; `claudenv skills refresh` parses and caches the live registry.
+
+### Trust & safety
+
+A fetched `SKILL.md` is auto-loaded, model-facing instruction text — a
+prompt-injection surface. So:
+
+- **Curated (★)** entries have a vetted source URL + install class (the bytes are
+  fetched live, not content-pinned) → the only entries allowed to auto-equip,
+  including inside `claudenv loop`.
+- **Live** entries (parsed from the README or a raw URL) are gated in code:
+  `skills add` writes nothing without `--yes`. `claudenv loop` never passes it.
+
+`skills add` only ever writes under `~/.claude/skills/<slug>/`, never overwrites
+without `--force`, validates the body, and **never executes** fetched content.
+Bootstrap installers are printed first and run only with `--yes`.
+
+### Browser automation (kimi-webbridge)
+
+`claudenv skills add kimi-webbridge` makes browser automation work even if it
+isn't installed yet — it detects an existing daemon and starts it, or surfaces the
+official bootstrap. `claudenv capabilities` and `claudenv doctor` report its
+health. Once up, Claude drives your real browser (with your login sessions) via
+the `kimi-webbridge` skill.
+
+## Dynamic workflows
+
+`/claudenv` installs a `dynamic-workflows` skill that teaches Claude when to reach for the built-in **Workflow** tool — deterministic multi-agent orchestration (fan-out, pipelines, adversarial-verify, multi-file migrations) — and when to stay single-threaded. It triggers on wide, decomposable work (reviewing/migrating across many files, research over many sources, generate-N-then-judge) and stays out of the way for single-file or sequential edits.
+
+`claudenv loop` drives the same capability: alongside the no-pause loop-mode fragment, it injects a guarded **Parallel decomposition** directive into the execution prompt that tells the loop to run a dynamic workflow when the picked plan item splits into 3+ independent sub-tasks (and to stay single-threaded otherwise). Fan-out is hard-capped (multi-agent work costs ~15× the tokens and runs under the per-iteration budget); if the Workflow runtime is unavailable it degrades to parallel `Agent` calls. The directive lives in the user prompt because the Workflow tool's opt-in keys on the user message — a system-prompt hint alone won't trigger it.
+
 ### Python companion: `claudenv-memory`
 
 Building your own agent on Claude Agent SDK and want the same memory layout?
@@ -311,6 +379,16 @@ claudenv memory init|index|show|edit  Manage ~/.claudenv/memories/ (1.3.0+)
 claudenv decisions list|show|search   Logged vibe-decisions (1.3.0+)
 claudenv canon add|list|search|prune  Personal canon (1.3.0+)
 claudenv doctor                       Health check (1.3.0+)
+
+claudenv workspace add|list|use|show  Isolated per-company memory spaces (1.3.1+)
+claudenv source list|show             Data-source connectors of active workspace (1.3.1+)
+
+claudenv capabilities [--json] [-d <dir>]  Self-introspection map (1.3.2+)
+claudenv skills search <query>        Find skills (curated + awesome-claude-skills) (1.3.2+)
+claudenv skills list                  Skills installed under ~/.claude/skills/ (1.3.2+)
+claudenv skills info <name>           Trust level, install class, source (1.3.2+)
+claudenv skills add <name> [--force]  Install a skill (--yes to run bootstraps) (1.3.2+)
+claudenv skills refresh               Refetch the live registry into cache (1.3.2+)
 ```
 
 ## Run Without Installing

package/bin/cli.js

@@ -571,6 +571,200 @@ srcCmd
     console.log(text);
   });
 
+// =============================================
+// Skills (discover & install from awesome-claude-skills + curated catalog)
+// =============================================
+const skillsCmd = program
+  .command('skills')
+  .description('Discover & install Claude skills (awesome-claude-skills + curated catalog)');
+
+skillsCmd
+  .command('search')
+  .description('Find skills matching a need (curated catalog + cached live registry)')
+  .argument('[query...]', 'What capability you need (free text)')
+  .option('--refresh', 'Refetch the live registry before searching')
+  .option('--limit <n>', 'Max results', '15')
+  .action(async (queryParts, opts) => {
+    const { loadCatalog, searchCatalog } = await import('../src/skills-registry.js');
+    const query = (queryParts || []).join(' ');
+    const catalog = await loadCatalog({ refresh: opts.refresh });
+    const hits = searchCatalog(catalog, query).slice(0, parseInt(opts.limit, 10) || 15);
+    if (hits.length === 0) {
+      console.log('  No matching skills. Try `claudenv skills search --refresh <query>`.');
+      return;
+    }
+    console.log();
+    for (const e of hits) {
+      const tag = e.curated ? '★' : ' ';
+      console.log(`  ${tag} ${e.slug}  [${e.install}]${e.category ? `  ${e.category}` : ''}`);
+      if (e.description) console.log(`      ${e.description}`);
+    }
+    console.log(`\n  ★ = curated (vetted, safe to auto-install). Install: claudenv skills add <slug>`);
+  });
+
+skillsCmd
+  .command('list')
+  .description('List skills installed under ~/.claude/skills/')
+  .action(async () => {
+    const { listInstalledSkills } = await import('../src/skills-registry.js');
+    const installed = await listInstalledSkills();
+    if (installed.length === 0) {
+      console.log('  No skills installed yet — `claudenv skills search <task>`');
+      return;
+    }
+    console.log();
+    for (const s of installed) {
+      console.log(`  ${s.slug}${s.hasSkillMd ? '' : '  (no SKILL.md)'}`);
+      if (s.description) console.log(`      ${s.description.split('\n')[0].slice(0, 100)}`);
+    }
+  });
+
+skillsCmd
+  .command('info')
+  .description('Show trust level, install class, and source for a skill')
+  .argument('<name>', 'Skill slug or name')
+  .option('--refresh', 'Refetch the live registry first')
+  .action(async (name, opts) => {
+    const { loadCatalog, findEntry, resolveSkillSource } = await import('../src/skills-registry.js');
+    const catalog = await loadCatalog({ refresh: opts.refresh });
+    const e = findEntry(catalog, name);
+    if (!e) {
+      console.error(`  No catalog entry for "${name}". Try \`claudenv skills search ${name}\`.`);
+      process.exit(1);
+    }
+    const src = resolveSkillSource(e);
+    console.log(`\n  ${e.name}  (${e.slug})`);
+    if (e.category) console.log(`  category: ${e.category}`);
+    console.log(`  trust:    ${e.curated ? 'curated (vetted)' : 'live (confirm before installing)'}`);
+    console.log(`  install:  ${e.install} → ${src.kind}`);
+    if (src.kind === 'bootstrap') console.log(`  command:  ${src.command}`);
+    console.log(`  url:      ${e.url}`);
+    if (e.description) console.log(`\n  ${e.description}`);
+    console.log();
+  });
+
+skillsCmd
+  .command('add')
+  .description('Install a skill into ~/.claude/skills/ (curated = safe; live = confirm)')
+  .argument('<name>', 'Skill slug or name to install')
+  .option('-f, --force', 'Overwrite an already-installed skill')
+  .option('--refresh', 'Refetch the live registry first')
+  .option('-y, --yes', 'Confirm a live (non-curated) install and run bootstrap installers')
+  .action(async (name, opts) => {
+    const { loadCatalog, findEntry, makeEntryFromUrl, classifyUrl, installSkill } = await import('../src/skills-registry.js');
+    const catalog = await loadCatalog({ refresh: opts.refresh });
+    let entry = findEntry(catalog, name);
+    // Allow `skills add <github-url-or-relative-path>` (always treated as live).
+    if (!entry && (/^https?:\/\//i.test(name) || /^\.?\//.test(name)) && classifyUrl(name) !== 'guide') {
+      entry = makeEntryFromUrl(name);
+      console.log(`  resolving URL as a live skill (${entry.install}): ${name}`);
+    }
+    if (!entry) {
+      console.error(`  No catalog entry for "${name}". Try \`claudenv skills search ${name}\`.`);
+      process.exit(1);
+    }
+    if (entry.curated !== true) {
+      console.log(`  ⚠ "${entry.slug}" is a LIVE (non-curated) entry. A SKILL.md is auto-loaded,`);
+      console.log(`    model-facing instructions — review ${entry.url} before relying on it.`);
+    }
+
+    const result = await installSkill(entry, { force: opts.force, confirmLive: !!opts.yes });
+
+    switch (result.action) {
+      case 'installed':
+        console.log(`  + installed ${result.slug} → ${result.path}`);
+        console.log(`    source: ${result.source}`);
+        console.log(`    note: only SKILL.md was fetched; for scripts/templates see ${entry.url}`);
+        break;
+      case 'exists':
+        console.log(`  ~ ${result.slug} already installed (${result.path}) — use --force to overwrite`);
+        break;
+      case 'needs-confirm':
+        console.log(`  ⛔ "${result.slug}" is live (untrusted) — not installed.`);
+        console.log(`    Review ${result.url}, then re-run with --yes to confirm.`);
+        break;
+      case 'bootstrap':
+        await handleBootstrap(result, opts);
+        break;
+      case 'guide':
+        console.log(`  i ${result.slug} can't be auto-copied: ${result.reason}`);
+        console.log(`    open: ${result.url}`);
+        break;
+      case 'invalid':
+        console.error(`  ! ${result.slug} fetch rejected: ${result.reason}`);
+        console.error(`    source: ${result.url}`);
+        process.exit(2);
+        break;
+      default:
+        console.error(`  ! unexpected result: ${JSON.stringify(result)}`);
+        process.exit(2);
+    }
+  });
+
+skillsCmd
+  .command('refresh')
+  .description('Refetch the awesome-claude-skills registry into the local cache')
+  .action(async () => {
+    const { refreshCatalog } = await import('../src/skills-registry.js');
+    const { skillsRegistryCachePath } = await import('../src/memory-paths.js');
+    try {
+      const entries = await refreshCatalog();
+      console.log(`  cached ${entries.length} registry entries → ${skillsRegistryCachePath()}`);
+    } catch (err) {
+      console.error(`  Could not refresh registry: ${err.message}`);
+      process.exit(2);
+    }
+  });
+
+async function handleBootstrap(result, opts) {
+  const { existsSync } = await import('node:fs');
+  const { homedir } = await import('node:os');
+  const { execSync } = await import('node:child_process');
+  const bin = join(homedir(), '.kimi-webbridge', 'bin', 'kimi-webbridge');
+
+  if (result.slug === 'kimi-webbridge' && existsSync(bin)) {
+    console.log('  kimi-webbridge already installed — ensuring the daemon is running...');
+    try {
+      execSync(`"${bin}" start`, { stdio: 'inherit' });
+    } catch { /* start is idempotent; ignore */ }
+    return;
+  }
+
+  console.log(`\n  ${result.slug} installs via a shell command (not a copyable SKILL.md):\n`);
+  console.log(`    ${result.command}\n`);
+  if (!opts.yes) {
+    console.log('  Review it, then re-run with --yes to execute, or run it yourself.');
+    return;
+  }
+  console.log('  Running (--yes given)...\n');
+  try {
+    execSync(result.command, { stdio: 'inherit', shell: '/bin/bash' });
+  } catch (err) {
+    console.error(`  Bootstrap failed: ${err.message}`);
+    process.exit(2);
+  }
+}
+
+// --- capabilities (self-introspection: "connect to claudenv, understand it") ---
+program
+  .command('capabilities')
+  .alias('caps')
+  .description('Print a map of everything this claudenv install offers')
+  .option('--json', 'Emit the raw capability map as JSON')
+  .option('-d, --dir <path>', 'Project directory')
+  .action(async (opts) => {
+    const { buildCapabilityMap, formatCapabilities } = await import('../src/capabilities.js');
+    const map = await buildCapabilityMap({
+      cwd: opts.dir ? resolve(opts.dir) : process.cwd(),
+      version: pkgJson.version,
+    });
+    if (opts.json) {
+      console.log(JSON.stringify(map, null, 2));
+      return;
+    }
+    console.log('\n' + formatCapabilities(map) + '\n');
+  });
+
 // --- doctor ---
 program
   .command('doctor')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudenv",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "One command to integrate Claude Code into any project — installs /claudenv command for AI-powered documentation generation",
   "type": "module",
   "bin": {

package/scaffold/.claude/skills/dynamic-workflows/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: dynamic-workflows
+description: |
+  Trigger when a task naturally decomposes into many independent sub-tasks
+  that benefit from deterministic multi-agent orchestration: reviewing or
+  migrating across many files, research over many sources, multi-dimension
+  audits, generate-N-then-judge, or "find all X" with verification. Use the
+  Workflow tool (agent()/parallel()/pipeline()). Also triggers on the word
+  "workflow"/"workflows" or an explicit ask to fan out / orchestrate
+  subagents. Do NOT trigger for single-file edits, strictly sequential work,
+  or anything one or two Agent calls already cover.
+---
+
+# Dynamic workflows
+
+Deterministic multi-agent orchestration via the built-in **Workflow** tool —
+a JavaScript script that fans work out across subagents (`agent()`),
+pipelines it (`pipeline()`), or barriers on it (`parallel()`). This skill
+decides *when* orchestration earns its cost and gives the minimal scaffold to
+launch one. The Workflow tool's own description carries the full API — lean on
+it; don't reproduce it here.
+
+## Mode detection (FIRST step every time)
+
+Check the system prompt for the marker `Dynamic-workflows mode (loop)`.
+
+- **Marker present** → LOOP mode. You are inside `claudenv loop`. Orchestrate
+  without pausing, but only for plan items that genuinely split into
+  independent sub-tasks, and keep fan-out narrow (see Cost discipline). The
+  goal is law — never pause to ask "запустить workflow?".
+- **Marker absent** → INTERACTIVE mode. Propose a one-line orchestration plan
+  (how many agents, what each does, pipeline vs parallel) and wait for the
+  user before launching.
+
+## When to orchestrate (triggers)
+
+Reach for a workflow when the work is *wide* — many items, each handled the
+same way, with little cross-talk:
+
+- **Review / audit** a diff across several dimensions (bugs, perf, security,
+  style), then adversarially verify each finding.
+- **Migrate / edit a pattern** across many files (worktree isolation per
+  agent when they mutate in parallel).
+- **Research** a question over many sources, then synthesize.
+- **Generate N independent attempts** (different angles), judge, synthesize
+  from the winner.
+- **"Find all X"** with a verification pass and loop-until-dry.
+
+## When NOT to orchestrate (anti-triggers)
+
+Stay single-threaded — a workflow is pure overhead here:
+
+- A single file, or a change that must happen in strict sequence.
+- Trivial edits, renames, formatting.
+- Anything one or two plain `Agent` calls already cover — prefer those.
+
+**Cost discipline.** Multi-agent fan-out costs roughly an order of magnitude
+more tokens than single-threaded work (~15×; see `claudenv-update-plan.md`).
+Single-threaded is the default. Orchestrate only when the width is real, and
+cap the number of concurrent agents to what the task needs.
+
+## How to launch (minimal scaffold)
+
+Every script starts with a pure-literal `meta`, then uses `pipeline()` as the
+default and `parallel()` only as a barrier when you genuinely need all
+prior-stage results at once. Pattern — review each dimension, verify each
+finding as soon as it lands:
+
+```js
+export const meta = {
+  name: 'review-diff',
+  description: 'Review the diff across dimensions and verify each finding',
+  phases: [{ title: 'Review' }, { title: 'Verify' }],
+}
+const DIMENSIONS = [
+  { key: 'bugs', prompt: 'Find correctness bugs in the diff…' },
+  { key: 'perf', prompt: 'Find performance regressions in the diff…' },
+]
+const results = await pipeline(
+  DIMENSIONS,
+  d => agent(d.prompt, { label: `review:${d.key}`, phase: 'Review', schema: FINDINGS }),
+  review => parallel(review.findings.map(f => () =>
+    agent(`Adversarially verify, default to refuted if unsure: ${f.title}`,
+      { label: `verify:${f.file}`, phase: 'Verify', schema: VERDICT })
+      .then(v => ({ ...f, verdict: v }))))
+)
+const confirmed = results.flat().filter(Boolean).filter(f => f.verdict?.isReal)
+return { confirmed }
+```
+
+Useful patterns (compose as the task needs): **adversarial-verify** (N
+skeptics per finding, kill on majority-refute), **loop-until-dry** (keep
+finding until K empty rounds), **judge panel** (N attempts → score →
+synthesize). Scale the agent count to the ask — a few for "quick check",
+more for "thorough audit".
+
+## Notes
+
+- `agent(prompt, { schema })` returns the validated object; without a schema
+  it returns the agent's final text.
+- Use `isolation: 'worktree'` only when agents mutate files in parallel and
+  would otherwise conflict — it is expensive.
+- In LOOP mode, if the Workflow tool's background completion does not resolve
+  under headless `claude -p`, fall back to plain parallel `Agent` calls for
+  the same fan-out — same spirit, no dependency on the background runtime.

package/scaffold/global/.claude/commands/claudenv.md

@@ -96,7 +96,7 @@ Copy the following scaffold files from the global skill directory into this proj
 
 ```bash
 # Create directories
-mkdir -p .claude/commands .claude/skills/doc-generator/scripts .claude/skills/doc-generator/templates .claude/agents
+mkdir -p .claude/commands .claude/skills/doc-generator/scripts .claude/skills/doc-generator/templates .claude/skills/dynamic-workflows .claude/agents
 
 # Copy project-level scaffold from global skill
 cp ~/.claude/skills/claudenv/scaffold/.claude/commands/init-docs.md .claude/commands/init-docs.md
@@ -108,6 +108,7 @@ cp ~/.claude/skills/claudenv/scaffold/.claude/skills/doc-generator/templates/det
 cp ~/.claude/skills/claudenv/scaffold/.claude/skills/doc-generator/templates/mcp-servers.md .claude/skills/doc-generator/templates/mcp-servers.md
 cp ~/.claude/skills/claudenv/scaffold/.claude/commands/setup-mcp.md .claude/commands/setup-mcp.md
 cp ~/.claude/skills/claudenv/scaffold/.claude/commands/improve.md .claude/commands/improve.md
+cp ~/.claude/skills/claudenv/scaffold/.claude/skills/dynamic-workflows/SKILL.md .claude/skills/dynamic-workflows/SKILL.md
 cp ~/.claude/skills/claudenv/scaffold/.claude/agents/doc-analyzer.md .claude/agents/doc-analyzer.md
 chmod +x .claude/skills/doc-generator/scripts/validate.sh
 ```
@@ -179,6 +180,7 @@ Created:
   + .claude/commands/setup-mcp.md
   + .claude/commands/improve.md
   + .claude/skills/doc-generator/
+  + .claude/skills/dynamic-workflows/
   + .claude/agents/doc-analyzer.md
   + .mcp.json (if MCP servers were configured)
 

package/scaffold/global/.claude/commands/harness.md

@@ -0,0 +1,29 @@
+---
+description: Подобрать и установить оптимальный harness для текущей задачи — интроспекция claudenv, поиск/установка скиллов, коннекторы, MCP, браузер, память
+allowed-tools: Bash, Read, Write, Edit, WebFetch, Skill
+argument-hint: [<задача или нужная возможность>]
+---
+
+# /harness — самонастройка под задачу
+
+Запускает skill `harness`: ты понимаешь, что уже даёт claudenv, чего не хватает
+под задачу, и автономно дооснащаешься — ставишь скиллы из awesome-claude-skills,
+настраиваешь коннекторы/MCP, поднимаешь браузер kimi-webbridge, управляешь памятью.
+
+## Routing
+
+1. Активируй skill `harness`.
+2. Сначала интроспекция: `claudenv capabilities` (или `npx claudenv capabilities`).
+3. Если в `$ARGUMENTS` есть задача/возможность — используй как цель gap-анализа и
+   поиска (`claudenv skills search "<...>"`). Если аргументов нет — спроси, подо
+   что настраиваемся, и предложи варианты из каталога.
+
+## Инварианты
+
+- **Trust boundary:** курируемые (★) скиллы ставим сразу; live (не-курируемые) —
+  только после подтверждения пользователя (SKILL.md = авто-загружаемые инструкции,
+  это поверхность для prompt-injection).
+- Секреты — только в `.env.local`. Знание о коннекторе — в активный workspace.
+- Bootstrap-установщики (`curl | bash`, напр. kimi-webbridge) — сначала показать
+  команду, выполнять с явным согласием.
+- Не ставь скиллы «про запас» — только то, что реально двигает задачу.

package/scaffold/global/.claude/skills/claudenv/scaffold/.claude/skills/dynamic-workflows/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: dynamic-workflows
+description: |
+  Trigger when a task naturally decomposes into many independent sub-tasks
+  that benefit from deterministic multi-agent orchestration: reviewing or
+  migrating across many files, research over many sources, multi-dimension
+  audits, generate-N-then-judge, or "find all X" with verification. Use the
+  Workflow tool (agent()/parallel()/pipeline()). Also triggers on the word
+  "workflow"/"workflows" or an explicit ask to fan out / orchestrate
+  subagents. Do NOT trigger for single-file edits, strictly sequential work,
+  or anything one or two Agent calls already cover.
+---
+
+# Dynamic workflows
+
+Deterministic multi-agent orchestration via the built-in **Workflow** tool —
+a JavaScript script that fans work out across subagents (`agent()`),
+pipelines it (`pipeline()`), or barriers on it (`parallel()`). This skill
+decides *when* orchestration earns its cost and gives the minimal scaffold to
+launch one. The Workflow tool's own description carries the full API — lean on
+it; don't reproduce it here.
+
+## Mode detection (FIRST step every time)
+
+Check the system prompt for the marker `Dynamic-workflows mode (loop)`.
+
+- **Marker present** → LOOP mode. You are inside `claudenv loop`. Orchestrate
+  without pausing, but only for plan items that genuinely split into
+  independent sub-tasks, and keep fan-out narrow (see Cost discipline). The
+  goal is law — never pause to ask "запустить workflow?".
+- **Marker absent** → INTERACTIVE mode. Propose a one-line orchestration plan
+  (how many agents, what each does, pipeline vs parallel) and wait for the
+  user before launching.
+
+## When to orchestrate (triggers)
+
+Reach for a workflow when the work is *wide* — many items, each handled the
+same way, with little cross-talk:
+
+- **Review / audit** a diff across several dimensions (bugs, perf, security,
+  style), then adversarially verify each finding.
+- **Migrate / edit a pattern** across many files (worktree isolation per
+  agent when they mutate in parallel).
+- **Research** a question over many sources, then synthesize.
+- **Generate N independent attempts** (different angles), judge, synthesize
+  from the winner.
+- **"Find all X"** with a verification pass and loop-until-dry.
+
+## When NOT to orchestrate (anti-triggers)
+
+Stay single-threaded — a workflow is pure overhead here:
+
+- A single file, or a change that must happen in strict sequence.
+- Trivial edits, renames, formatting.
+- Anything one or two plain `Agent` calls already cover — prefer those.
+
+**Cost discipline.** Multi-agent fan-out costs roughly an order of magnitude
+more tokens than single-threaded work (~15×; see `claudenv-update-plan.md`).
+Single-threaded is the default. Orchestrate only when the width is real, and
+cap the number of concurrent agents to what the task needs.
+
+## How to launch (minimal scaffold)
+
+Every script starts with a pure-literal `meta`, then uses `pipeline()` as the
+default and `parallel()` only as a barrier when you genuinely need all
+prior-stage results at once. Pattern — review each dimension, verify each
+finding as soon as it lands:
+
+```js
+export const meta = {
+  name: 'review-diff',
+  description: 'Review the diff across dimensions and verify each finding',
+  phases: [{ title: 'Review' }, { title: 'Verify' }],
+}
+const DIMENSIONS = [
+  { key: 'bugs', prompt: 'Find correctness bugs in the diff…' },
+  { key: 'perf', prompt: 'Find performance regressions in the diff…' },
+]
+const results = await pipeline(
+  DIMENSIONS,
+  d => agent(d.prompt, { label: `review:${d.key}`, phase: 'Review', schema: FINDINGS }),
+  review => parallel(review.findings.map(f => () =>
+    agent(`Adversarially verify, default to refuted if unsure: ${f.title}`,
+      { label: `verify:${f.file}`, phase: 'Verify', schema: VERDICT })
+      .then(v => ({ ...f, verdict: v }))))
+)
+const confirmed = results.flat().filter(Boolean).filter(f => f.verdict?.isReal)
+return { confirmed }
+```
+
+Useful patterns (compose as the task needs): **adversarial-verify** (N
+skeptics per finding, kill on majority-refute), **loop-until-dry** (keep
+finding until K empty rounds), **judge panel** (N attempts → score →
+synthesize). Scale the agent count to the ask — a few for "quick check",
+more for "thorough audit".
+
+## Notes
+
+- `agent(prompt, { schema })` returns the validated object; without a schema
+  it returns the agent's final text.
+- Use `isolation: 'worktree'` only when agents mutate files in parallel and
+  would otherwise conflict — it is expensive.
+- In LOOP mode, if the Workflow tool's background completion does not resolve
+  under headless `claude -p`, fall back to plain parallel `Agent` calls for
+  the same fan-out — same spirit, no dependency on the background runtime.