@yycholla/pi-dynamic-workflows 3.3.0

package/dist/workflows-models-command.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `/workflows-models` command handler.
+ *
+ * Uses Pi's built-in `ctx.ui.select()`, `ctx.ui.confirm()`, and `ctx.ui.notify()`
+ * to let users view and manage model tier configuration for workflows.
+ *
+ * Model selection draws from the host session's shared model registry so users
+ * see every provider Pi can reach, including extension-registered providers such
+ * as `ollama-cloud`.
+ *
+ * Each tier holds exactly one model spec string. The string may include Pi
+ * CLI-style thinking suffixes, e.g. `openai-codex/gpt-5.5:xhigh`.
+ * When editing a tier, users pick a model, then an optional thinking level.
+ */
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+/**
+ * Register the `/workflows-models` command with Pi.
+ */
+export declare function registerWorkflowModelsCommand(pi: ExtensionAPI): void;
+/**
+ * Interactive editor for a single tier — scrollable model picker plus optional
+ * thinking-level picker.
+ *
+ * Uses `ctx.ui.custom()` with Pi TUI's `SelectList` for proper scrollable list
+ * with limited visible rows (like `/advisor`). The currently selected base
+ * model is shown in the dialog title. After choosing the model, users can set
+ * a Pi CLI-style thinking suffix or keep the session default.
+ *
+ * Returns the updated tiers object, or null if nothing changed.
+ */
+export declare function editSingleTier(ctx: ExtensionCommandContext, tiers: Record<string, string>, tierName: string): Promise<Record<string, string> | null>;

package/dist/workflows-models-command.js

@@ -0,0 +1,156 @@
+/**
+ * `/workflows-models` command handler.
+ *
+ * Uses Pi's built-in `ctx.ui.select()`, `ctx.ui.confirm()`, and `ctx.ui.notify()`
+ * to let users view and manage model tier configuration for workflows.
+ *
+ * Model selection draws from the host session's shared model registry so users
+ * see every provider Pi can reach, including extension-registered providers such
+ * as `ollama-cloud`.
+ *
+ * Each tier holds exactly one model spec string. The string may include Pi
+ * CLI-style thinking suffixes, e.g. `openai-codex/gpt-5.5:xhigh`.
+ * When editing a tier, users pick a model, then an optional thinking level.
+ */
+import { Container, SelectList, Spacer, Text, } from "@earendil-works/pi-tui";
+import { listAvailableModelSpecs, listAvailableModels } from "./agent.js";
+import { formatModelSpecWithThinking, splitModelSpecThinking, THINKING_LEVELS, } from "./model-spec.js";
+import { buildDefaultTierConfig, loadModelTierConfig, saveModelTierConfig, sortedTierNames, } from "./model-tier-config.js";
+/**
+ * Register the `/workflows-models` command with Pi.
+ */
+export function registerWorkflowModelsCommand(pi) {
+    pi.registerCommand("workflows-models", {
+        description: "View and edit model tiers used by workflows (small/medium/big)",
+        handler: async (_args, ctx) => {
+            await ctx.waitForIdle();
+            // Load the saved config, or build an in-memory default spread across the
+            // available models. If the model registry is empty, fall back to the
+            // current Pi model so the tiers are still usable. Pass the host session's
+            // registry explicitly: since pi 0.80.8 the no-registry fallback inside
+            // listAvailableModels() initializes asynchronously and reports [] on the
+            // first call, which would rank defaults from an empty model list.
+            const currentModel = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
+            let config = loadModelTierConfig() ?? buildDefaultTierConfig(currentModel, listAvailableModels(ctx.modelRegistry));
+            let dirty = false;
+            const ensureFresh = (cfg) => {
+                config = cfg;
+                dirty = true;
+            };
+            // eslint-disable-next-line no-constant-condition
+            while (true) {
+                const tiers = sortedTierNames(config);
+                const menuOptions = [];
+                menuOptions.push("─".repeat(30));
+                for (const name of tiers) {
+                    const model = config.tiers[name];
+                    menuOptions.push(`${name} tier → ${model}`);
+                }
+                menuOptions.push("─".repeat(30));
+                menuOptions.push("Reset to defaults");
+                menuOptions.push(dirty ? "Save and exit" : "Exit");
+                const choice = await ctx.ui.select("Model tier configuration", menuOptions);
+                if (!choice)
+                    break;
+                // Handle "<tier> → [model]" selections
+                for (const name of tiers) {
+                    if (choice.startsWith(`${name} tier →`)) {
+                        const updatedTiers = await editSingleTier(ctx, config.tiers, name);
+                        if (updatedTiers !== null) {
+                            ensureFresh({ ...config, tiers: updatedTiers });
+                        }
+                        break;
+                    }
+                }
+                if (choice === "Reset to defaults") {
+                    const confirmed = await ctx.ui.confirm("Reset model tiers", "This will reset tiers from your available model list. Continue?");
+                    if (confirmed) {
+                        ensureFresh(buildDefaultTierConfig(currentModel, listAvailableModels(ctx.modelRegistry)));
+                        ctx.ui.notify("Tiers reset to defaults. Use 'Save and exit' to persist.", "info");
+                    }
+                }
+                if (choice === "Save and exit" || choice === "Exit") {
+                    if (choice === "Save and exit") {
+                        saveModelTierConfig(config);
+                        ctx.ui.notify("Model tiers saved.", "info");
+                    }
+                    break;
+                }
+            }
+        },
+    });
+}
+const DEFAULT_THINKING_CHOICE = "Default thinking (session setting)";
+const THINKING_CHOICES = [DEFAULT_THINKING_CHOICE, ...THINKING_LEVELS];
+function fromThinkingChoice(choice) {
+    return THINKING_LEVELS.find((level) => level === choice);
+}
+/**
+ * Interactive editor for a single tier — scrollable model picker plus optional
+ * thinking-level picker.
+ *
+ * Uses `ctx.ui.custom()` with Pi TUI's `SelectList` for proper scrollable list
+ * with limited visible rows (like `/advisor`). The currently selected base
+ * model is shown in the dialog title. After choosing the model, users can set
+ * a Pi CLI-style thinking suffix or keep the session default.
+ *
+ * Returns the updated tiers object, or null if nothing changed.
+ */
+export async function editSingleTier(ctx, tiers, tierName) {
+    const available = listAvailableModelSpecs(ctx.modelRegistry);
+    const knownSpecs = available.length > 0 ? available : undefined;
+    const current = tiers[tierName];
+    const currentParts = splitModelSpecThinking(current, knownSpecs);
+    // Build SelectItems: all available models as scrollable list
+    const items = available.map((m) => ({ value: m, label: m }));
+    const selectedModel = await ctx.ui.custom((tui, theme, _keybindings, done) => {
+        const container = new Container();
+        // Title showing current model
+        const titleText = current
+            ? `Pick a model for "${tierName}" (current: ${current})`
+            : `Pick a model for "${tierName}"`;
+        container.addChild(new Text(theme.fg("accent", titleText), 1, 0));
+        container.addChild(new Spacer(1));
+        // SelectList theme
+        const selectTheme = {
+            selectedPrefix: (t) => theme.bg("selectedBg", theme.fg("accent", t)),
+            selectedText: (t) => theme.bg("selectedBg", theme.bold(t)),
+            description: (t) => theme.fg("muted", t),
+            scrollInfo: (t) => theme.fg("dim", t),
+            noMatch: (t) => theme.fg("warning", t),
+        };
+        const selectList = new SelectList(items, 12, selectTheme);
+        // Preselect the current base model even when the stored tier has :thinking.
+        if (currentParts.modelSpec) {
+            const idx = items.findIndex((i) => i.value === currentParts.modelSpec);
+            if (idx >= 0)
+                selectList.setSelectedIndex(idx);
+        }
+        // Wire up callbacks
+        selectList.onSelect = (item) => done(item.value);
+        selectList.onCancel = () => done(null);
+        container.addChild(selectList);
+        container.addChild(new Spacer(1));
+        container.addChild(new Text(theme.fg("dim", "↑↓ navigate  enter select  esc cancel  · thinking is chosen next"), 1, 0));
+        return {
+            render: (w) => container.render(w),
+            invalidate: () => container.invalidate(),
+            handleInput: (data) => {
+                selectList.handleInput(data);
+                tui.requestRender();
+            },
+        };
+    });
+    if (!selectedModel)
+        return null;
+    const currentThinkingLabel = currentParts.thinkingLevel ?? DEFAULT_THINKING_CHOICE;
+    const thinkingChoice = await ctx.ui.select(`Thinking for "${tierName}" tier (current: ${currentThinkingLabel})`, THINKING_CHOICES.map((choice) => String(choice)));
+    if (!thinkingChoice)
+        return null;
+    const thinkingLevel = fromThinkingChoice(thinkingChoice);
+    const result = formatModelSpecWithThinking(selectedModel, thinkingLevel);
+    if (result === current)
+        return null;
+    ctx.ui.notify(`"${tierName}" tier → ${result}`, "info");
+    return { ...tiers, [tierName]: result };
+}

package/dist/worktree.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Per-agent git worktree isolation. When an agent requests `isolation: "worktree"`,
+ * it runs in a throwaway worktree on its own branch so parallel agents can edit the
+ * same files without conflict. Results are NOT auto-merged — the path is surfaced for
+ * the caller to inspect. Falls back to a logged no-op when isolation isn't possible.
+ */
+export interface Worktree {
+    /** True when a real worktree was created; false means "ran in the shared tree". */
+    isolated: boolean;
+    /** cwd the agent should run in (worktree path when isolated, else the base cwd). */
+    cwd: string;
+    branch?: string;
+    /** Repo root the worktree was added to (for teardown). */
+    repoRoot?: string;
+    /** Why isolation was skipped, when isolated === false. */
+    reason?: string;
+}
+/**
+ * Create an isolated worktree under `<repoRoot>/.pi/worktrees/<name>` on branch
+ * `pi/wf/<name>`. The `name` must be deterministic (derived from runId + call index,
+ * never wall-clock) so resume keys stay stable. Returns a no-op Worktree on any failure.
+ */
+export declare function createWorktree(baseCwd: string, name: string): Promise<Worktree>;
+/** Remove a worktree and its branch. Best-effort; safe to call on a no-op Worktree. */
+export declare function removeWorktree(wt: Worktree): Promise<void>;

package/dist/worktree.js

@@ -0,0 +1,61 @@
+/**
+ * Per-agent git worktree isolation. When an agent requests `isolation: "worktree"`,
+ * it runs in a throwaway worktree on its own branch so parallel agents can edit the
+ * same files without conflict. Results are NOT auto-merged — the path is surfaced for
+ * the caller to inspect. Falls back to a logged no-op when isolation isn't possible.
+ */
+import { execFile } from "node:child_process";
+import { join } from "node:path";
+import { promisify } from "node:util";
+const exec = promisify(execFile);
+function slug(name) {
+    return (name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 32) || "agent");
+}
+/**
+ * Create an isolated worktree under `<repoRoot>/.pi/worktrees/<name>` on branch
+ * `pi/wf/<name>`. The `name` must be deterministic (derived from runId + call index,
+ * never wall-clock) so resume keys stay stable. Returns a no-op Worktree on any failure.
+ */
+export async function createWorktree(baseCwd, name) {
+    const id = slug(name);
+    let repoRoot;
+    try {
+        const { stdout } = await exec("git", ["-C", baseCwd, "rev-parse", "--show-toplevel"]);
+        repoRoot = stdout.trim();
+    }
+    catch {
+        return { isolated: false, cwd: baseCwd, reason: "not a git repository" };
+    }
+    const path = join(repoRoot, ".pi", "worktrees", id);
+    const branch = `pi/wf/${id}`;
+    try {
+        await exec("git", ["-C", repoRoot, "worktree", "add", "-b", branch, path, "HEAD"]);
+        return { isolated: true, cwd: path, branch, repoRoot };
+    }
+    catch (error) {
+        return { isolated: false, cwd: baseCwd, reason: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** Remove a worktree and its branch. Best-effort; safe to call on a no-op Worktree. */
+export async function removeWorktree(wt) {
+    if (!wt.isolated || !wt.repoRoot)
+        return;
+    try {
+        await exec("git", ["-C", wt.repoRoot, "worktree", "remove", "--force", wt.cwd]);
+    }
+    catch {
+        // already gone / locked — fall through
+    }
+    if (wt.branch) {
+        try {
+            await exec("git", ["-C", wt.repoRoot, "branch", "-D", wt.branch]);
+        }
+        catch {
+            // branch already deleted
+        }
+    }
+}

package/extensions/workflow.ts

@@ -0,0 +1,151 @@
+import { createCodingTools, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  claimWorkflowRuntime,
+  discardWorkflowRuntime,
+  handoffWorkflowRuntime,
+  pauseVersionMismatchWorkflowRuntime,
+  WORKFLOW_EXTENSION_VERSION,
+  type WorkflowReloadRuntime,
+} from "../src/extension-reload.js";
+import {
+  createEffortState,
+  createWebTools,
+  createWorkflowControlTool,
+  createWorkflowStorage,
+  createWorkflowTool,
+  installResultDelivery,
+  installTaskPanel,
+  installWorkflowKeywordArming,
+  loadWorkflowSettings,
+  registerAllSavedWorkflows,
+  registerBuiltinWorkflows,
+  registerEffortCommand,
+  registerWorkflowCommands,
+  registerWorkflowModelsCommand,
+  saveWorkflowSettingsForCwd,
+  UsageLimitScheduler,
+  WorkflowManager,
+} from "../src/index.js";
+
+export default function extension(pi: ExtensionAPI) {
+  // Single manager shared by the workflow tool and /workflows command. Pi loads
+  // a fresh extension factory for /reload, so explicitly claim the old live
+  // manager when session_shutdown staged one; otherwise in-flight promises,
+  // controls, event delivery, and live UI updates would stay on an unreachable
+  // manager even though their persisted snapshots remained visible on disk.
+  const cwd = process.cwd();
+  const storage = createWorkflowStorage(cwd);
+  const settings = loadWorkflowSettings({ cwd });
+  const managerOptions = {
+    loadSavedWorkflow: (name: string) => storage.load(name)?.script,
+    // Named toolsets survive on the persisted run (the tag, not the functions),
+    // so a resumed run re-resolves the tools it started with — e.g. a paused
+    // /deep-research keeps web access instead of degrading to coding tools.
+    toolsets: {
+      "web-research": () => [...createCodingTools(cwd), ...createWebTools()],
+    },
+    // On top of the always-on workflow/workflow_control denial in subagents
+    // (#107), let users block additional recursive-orchestration tools.
+    excludeSubagentTools: settings.excludeSubagentTools,
+    defaultAgentTimeoutMs: settings.defaultAgentTimeoutMs ?? null,
+    defaultTokenBudget: settings.defaultTokenBudget ?? null,
+    concurrency: settings.defaultConcurrency,
+    defaultAgentRetries: settings.defaultAgentRetries,
+    persistAgentSessions: settings.persistAgentSessions,
+  };
+  const runtimeClaim = claimWorkflowRuntime(cwd);
+  const previousRuntime = runtimeClaim.compatible;
+  const pausedForVersionChange = runtimeClaim.versionMismatch
+    ? pauseVersionMismatchWorkflowRuntime(runtimeClaim.versionMismatch)
+    : 0;
+  const manager = previousRuntime?.manager ?? new WorkflowManager({ cwd, ...managerOptions });
+  if (previousRuntime) manager.reconfigureAfterReload(managerOptions);
+  // /effort is independent of the manager implementation and can safely
+  // survive an extension-version fallback to a fresh manager.
+  const effort = (previousRuntime ?? runtimeClaim.versionMismatch)?.effort ?? createEffortState();
+  const runtime: WorkflowReloadRuntime = {
+    cwd,
+    extensionVersion: WORKFLOW_EXTENSION_VERSION,
+    manager,
+    effort,
+  };
+  // Refresh the delivery holder immediately after claiming the manager. On a
+  // reload handoff its listener survives, but Pi invalidates the old ExtensionAPI
+  // before loading this generation.
+  installResultDelivery(pi, manager, { loadSettings: () => loadWorkflowSettings({ cwd }) });
+
+  const workflowTool = createWorkflowTool({ cwd, manager, storage });
+  const workflowControlTool = createWorkflowControlTool({ manager });
+  pi.registerTool(workflowTool);
+  pi.registerTool(workflowControlTool);
+  // Auto-resume runs that paused on a provider usage limit once the quota is
+  // likely refilled. Standalone: only consumes the manager's public surface, so
+  // it stays decoupled from manager/persistence internals. Its constructor also
+  // re-arms any run that was already paused-on-usage_limit before this process
+  // started (cold start), so restarting pi doesn't strand a paused run.
+  const usageLimitScheduler = new UsageLimitScheduler(manager);
+  pi.on("session_shutdown", (event?: { reason?: string }) => {
+    usageLimitScheduler.dispose();
+    if (event?.reason === "reload") {
+      handoffWorkflowRuntime(runtime);
+    } else {
+      discardWorkflowRuntime(cwd, runtime);
+    }
+  });
+  // Standing /effort opt-in (off|high|ultra): auto-arms a workflow for substantive
+  // messages, like CC's ultracode. Shared with the editor's input hook below and
+  // with the explicit /workflows run <prompt> manual trigger. It is part of the
+  // reload handoff so /reload does not silently turn the selected effort off.
+  registerWorkflowCommands(pi, manager, { storage, cwd, effort });
+  registerWorkflowModelsCommand(pi);
+  registerBuiltinWorkflows(pi, { cwd, manager, storage });
+  registerAllSavedWorkflows(pi, cwd, storage, manager);
+  registerEffortCommand(pi, effort);
+  // "Workflows mode": type `workflow(s)` to arm a forced workflow at submit
+  // time. Installed once (guarded below) inside session_start alongside the
+  // other per-session installers.
+  let armingInstalled = false;
+
+  pi.on("session_start", (_event: unknown, ctx: ExtensionContext) => {
+    if (pausedForVersionChange > 0) {
+      ctx.ui.notify(
+        `Workflow extension updated during /reload; paused ${pausedForVersionChange} active workflow(s) for safe resume.`,
+        "warning",
+      );
+    }
+    // Tell the manager the session's main model so "explore" agents auto-tier
+    // down to a lighter same-family sibling (e.g. Claude → Haiku).
+    manager.setMainModel(ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined);
+    // Share the host session's model registry so tier/phase routing resolves
+    // extension-registered providers (e.g. ollama-cloud) consistently. Set it
+    // before activating the tool: the tool's promptGuidelines read the
+    // manager's registry lazily, so tool-registry refreshes from here on
+    // advertise the shared registry's models.
+    manager.setModelRegistry(ctx.modelRegistry);
+    const active = pi.getActiveTools();
+    const workflowTools = [workflowTool.name, workflowControlTool.name];
+    const missing = workflowTools.filter((name) => !active.includes(name));
+    if (missing.length) pi.setActiveTools([...active, ...missing]);
+    // Scope the /workflows history to this session: runs persist on disk across
+    // sessions, but the navigator/task panel show only the current session's runs.
+    // Switching back to a previous session re-shows that session's runs.
+    try {
+      manager.setSessionId(ctx.sessionManager?.getSessionId());
+    } catch {
+      // sessionManager may be unavailable in some contexts — fall back to global history.
+    }
+    // Live "workflows running" panel below the input (focus + enter to open).
+    // Pass a live settings loader so /workflows-progress (compact|detailed) takes
+    // effect without a restart.
+    installTaskPanel(pi, manager, ctx.ui, { storage, cwd, loadSettings: () => loadWorkflowSettings({ cwd }) });
+    if (!armingInstalled) {
+      installWorkflowKeywordArming(pi, effort, {
+        settingsStore: {
+          load: () => loadWorkflowSettings({ cwd }),
+          save: (nextSettings) => saveWorkflowSettingsForCwd(nextSettings, cwd),
+        },
+      });
+      armingInstalled = true;
+    }
+  });
+}

package/package.json

@@ -0,0 +1,104 @@
+{
+  "name": "@yycholla/pi-dynamic-workflows",
+  "version": "3.3.0",
+  "description": "Fork of QuitinShaw/pi-dynamic-workflows improving pager and workflow persistance",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "extensions/",
+    "skills/",
+    "src/",
+    "assets/readme/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "npm run check && npm run release:check",
+    "test:unit": "tsx --test tests/**/*.test.ts",
+    "release:check": "npm run build && npm run docs:check && npm run context:check && npm run test:unit && npm run release:verify",
+    "release:verify": "tsx scripts/check-workflow-release.ts",
+    "check": "biome check . && npm run check:scripts",
+    "check:scripts": "tsc -p tsconfig.scripts.json",
+    "format": "biome format --write .",
+    "lint": "biome lint .",
+    "build": "tsc",
+    "docs:generate": "tsx scripts/generate-workflow-capabilities.ts",
+    "docs:check": "tsx scripts/generate-workflow-capabilities.ts --check",
+    "context:generate": "tsx scripts/generate-workflow-context-measurement.ts",
+    "context:check": "tsx scripts/generate-workflow-context-measurement.ts --check",
+    "guidance:generate": "tsx scripts/generate-workflow-guidance-baseline.ts",
+    "guidance:check": "tsx scripts/generate-workflow-guidance-baseline.ts --check",
+    "guidance:accept": "tsx scripts/accept-workflow-guidance.ts",
+    "comprehension": "tsx scripts/run-workflow-comprehension.ts",
+    "delivery-choice": "tsx scripts/run-workflow-delivery-choice.ts",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run release:check"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "workflow",
+    "workflows",
+    "dynamic-workflows",
+    "orchestration",
+    "subagents",
+    "multi-agent",
+    "agents",
+    "ai-agents",
+    "parallel",
+    "fan-out",
+    "claude-code",
+    "deep-research",
+    "code-review",
+    "llm"
+  ],
+  "pi": {
+    "extensions": [
+      "extensions/workflow.ts"
+    ],
+    "skills": [
+      "skills/workflow-authoring",
+      "skills/workflow-patterns"
+    ],
+    "image": "https://raw.githubusercontent.com/QuintinShaw/pi-dynamic-workflows/main/assets/readme/package-cover.png"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yycholla/pi-dynamic-workflows.git"
+  },
+  "author": "yycholla",
+  "contributors": [
+    "michaelliv (original author)",
+    "QuintinShaw"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "acorn": "^8.16.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.80.8",
+    "@earendil-works/pi-tui": ">=0.80.6",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.16",
+    "@earendil-works/pi-ai": "latest",
+    "@earendil-works/pi-coding-agent": "latest",
+    "@earendil-works/pi-tui": "latest",
+    "fast-check": "^4.8.0",
+    "tsx": "latest",
+    "typebox": "latest",
+    "typescript": "latest"
+  }
+}

package/skills/workflow-authoring/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: workflow-authoring
+description: Guidance for writing, editing, reviewing, and debugging JavaScript workflow code for pi-dynamic-workflows. Use when authoring or changing workflow scripts; not for merely running an existing workflow.
+metadata:
+  version: "3.3.0"
+---
+
+# Workflow authoring
+
+Load this skill when workflow JavaScript changes. Running an existing workflow needs no authoring reference.
+
+## Choose a branch
+
+Read only what the task needs:
+
+- **Write or edit:** start with [runtime](references/runtime.md). Add [pattern selection](references/pattern-selection.md) for topology, [lifecycle](references/lifecycle.md) for limits or resume, and [focused recipes](references/focused-recipes.md) for the matching concern.
+- **Helper task:** read [quality helpers](references/quality-helpers.md) only for `verify` or `judgePanel`, the [retry helper](references/retry-helper.md) only for `retry`, and [specialized helpers](references/specialized-helpers.md) only for `completenessCheck`, `loopUntilDry`, `gate`, or `checkpoint`.
+- **Review:** use the [review checklist](references/review.md), plus only the matching [quality](references/quality-helpers.md) or [specialized](references/specialized-helpers.md) helper contracts.
+- **Debug:** use the [debugging map](references/debugging.md).
+- **Routing:** read [registry ownership](references/registry-ownership.md) before using `model`, `tier`, phase models, or `agentType`; use environment-specific names only when context supplies them.
+- **Exact lookup or portability:** start with the generated [capability index](references/capabilities.md). Follow its exhaustive-facts pointer only for constraints or support boundaries. Use [versions](references/versions.md) when moving scripts between installations.
+
+## Invariants
+
+- Start with literal `export const meta = { name, description }`; declare phases as an array of used `{ title }` objects and enter each named phase.
+- Call `agent()` at least once, give every call a short unique `label`, and return plain JSON data explicitly.
+- Pair ordered results with stable work IDs before filtering. When one agent consumes another's selected result, include both its stable ID and actual data in the downstream prompt. Treat recoverable `null` as missing coverage and report it.
+- Bound fan-out, loops, retries, agents, concurrency, time, and token spend to the task.
+- Use `log()` for new code; `console` is compatibility-only.
+- Write plain JavaScript without imports or filesystem modules. Pass nondeterminism through `args`; `Date.now()`, `Math.random()`, and no-argument `new Date()` are unavailable.

package/skills/workflow-authoring/examples/adversarial-verification.js

@@ -0,0 +1,63 @@
+export const meta = {
+  name: "adversarial_verification",
+  description: "Produce claims and challenge them in separate skeptical contexts",
+  phases: [{ title: "Produce" }, { title: "Verify" }],
+};
+
+// ADAPT: validate and bound topics; define the evidence standard and schemas.
+const topics =
+  args && Array.isArray(args.topics) ? args.topics : [{ id: "sample", topic: "Verify one sample claim" }];
+const rubric = args && typeof args.rubric === "string" ? args.rubric : "Evidence is direct and sufficient";
+const productionSchema = {
+  type: "object",
+  properties: {
+    claim: { type: "string" },
+    evidence: { type: "array", items: { type: "string" } },
+  },
+  required: ["claim", "evidence"],
+};
+const verdictSchema = {
+  type: "object",
+  properties: { upheld: { type: "boolean" }, reason: { type: "string" } },
+  required: ["upheld", "reason"],
+};
+
+phase("Produce");
+const productions = await parallel(
+  topics.map((topic, index) => () =>
+    agent(`Develop a claim and cite its evidence.\n\n${JSON.stringify(topic)}`, {
+      label: `produce:${index}:${String(topic.id)}`,
+      schema: productionSchema,
+    }),
+  ),
+);
+const producerFailures = topics.flatMap((topic, index) =>
+  productions[index] === null ? [String(topic.id)] : [],
+);
+const reviewable = topics.flatMap((topic, index) =>
+  productions[index] === null ? [] : [{ topic, production: productions[index] }],
+);
+
+phase("Verify");
+// INVARIANT: each skeptic is a fresh agent call, never the producer reviewing itself.
+const verdicts = await parallel(
+  reviewable.map(({ topic, production }, index) => () =>
+    agent(
+      `Act as a skeptic. Try to refute this production under the rubric.\nRubric: ${rubric}\nProduction: ${JSON.stringify(production)}`,
+      { label: `skeptic:${index}:${String(topic.id)}`, schema: verdictSchema },
+    ),
+  ),
+);
+const skepticFailures = reviewable.flatMap(({ topic }, index) =>
+  verdicts[index] === null ? [String(topic.id)] : [],
+);
+
+return {
+  reviewed: reviewable.flatMap(({ topic, production }, index) =>
+    verdicts[index] === null
+      ? []
+      : [{ id: String(topic.id), production, verdict: verdicts[index] }],
+  ),
+  failed: { producers: producerFailures, skeptics: skepticFailures },
+  complete: producerFailures.length === 0 && skepticFailures.length === 0,
+};