melchizedek-agents 0.16.2 → 0.17.0

package/dist/lib/workflow.js

@@ -0,0 +1,180 @@
+/**
+ * lib/workflow.ts — the `workflow:` block: a syndicate as a graph.
+ *
+ * ── The third orchestration method ───────────────────────────────────────
+ * DELEGATE lets an orchestrator call subagents as tools; PLAN-DISPATCH
+ * (lib/dispatch.ts) lets a classifier pick ONE subagent to answer. Neither
+ * can say "run these two in parallel, join their outputs, review, ask the
+ * person, then publish". A `workflow:` block does: it is a graph whose
+ * nodes are the syndicate's own agents plus a few node kinds the engine
+ * supplies, and whose edges say what runs after what and on which route.
+ *
+ *   workflow:
+ *     edges:
+ *       - [START, Planner, { article: [Writer, Checker], answer: Answerer }]
+ *       - [[Writer, Checker], Both, Editor, Confirm, Publisher]
+ *     nodes:
+ *       Both:    { join: true }                 # waits for every predecessor
+ *       Confirm: { ask_user: "Publish? yes, or say what to change." }
+ *       Planner: { route_key: "kind", retry: { max_attempts: 2 } }
+ *
+ * ADK 2.2 runs it (`Workflow`, `FunctionNode`, `JoinNode`, `ParallelWorker`,
+ * `ToolNode`, `RequestInput`): per-node retries and timeouts, fan-out and
+ * fan-in, a pause that waits for a person and resumes on the next message,
+ * and resumption from the session's own events. Every agent is already a
+ * node (`LlmAgent extends BaseNode`): a node agent receives the previous
+ * node's output as its user turn and, unless its YAML sets
+ * `includeContents`, sees nothing else of the conversation.
+ *
+ * ── What the engine adds to ADK ───────────────────────────────────────────
+ * ROUTING. ADK's TypeScript port never derives a route from an agent's
+ *   output, so a routing map in YAML gets a hidden step after the agent
+ *   (`<Agent>__route`) that reads the route from the output — the
+ *   `route_key` property of a JSON output, else the trimmed text — and
+ *   re-emits the output with it. A `default` key catches what no key
+ *   matched.
+ * THE PAUSE. `ask_user` is a node that raises ADK's `RequestInput`. The
+ *   turn ends `input-required` carrying the question (`result.input`); the
+ *   next message on the conversation is the answer and becomes that node's
+ *   output. The A2A server publishes the question; the chat prints it.
+ * NAMES. Nodes are addressed by their YAML names everywhere (edges, events,
+ *   the wiki), including a `map` node, which ADK would otherwise name after
+ *   the agent it wraps.
+ *
+ * ── Not in this version ───────────────────────────────────────────────────
+ * Approval gates (`require_approval`, `skills.scripts: local`) and remote
+ * `a2a_agent_url` subagents are refused inside a workflow by the schema: a
+ * gated call pauses a node through ADK's interrupt path, whose resume is not
+ * the one ADR 0028 built, and a remote agent is reachable only as a tool.
+ * Both are open for a later record. A `Workflow` cannot yet be another
+ * agent's subagent (an ADK limit), so `yaml_reference` to a workflow
+ * syndicate compiles its orchestrator alone.
+ */
+import { DEFAULT_ROUTE, FunctionNode, JoinNode, ParallelWorker, RequestInput, ToolNode, Workflow, createEvent, } from '@google/adk';
+import { compileSubagent } from './compile.js';
+import { resolveTools as resolveNamedTools } from './toolRegistry.js';
+import { DEFAULT_ROUTE_KEY, ROUTE_STEP_SUFFIX, START_NAME, isWorkflowSyndicate, nodeKind, nodeSettings, routeOf } from './workflowConfig.js';
+export * from './workflowConfig.js';
+/**
+ * Compile a workflow syndicate: every agent through `compileSubagent` (its
+ * tools, skills and MCP server as in any mode), the declared nodes, the
+ * hidden route steps, and the edge chains, into one ADK `Workflow` named
+ * after the syndicate. Throws on a name the schema let through, a tool that
+ * is not registered, or a graph ADK rejects (unreachable node, cycle).
+ */
+export async function compileWorkflow(config, opts = {}, transformAgent = (a) => a) {
+    if (!isWorkflowSyndicate(config))
+        throw new Error(`${config.syndicate_name}: no workflow block`);
+    const wf = config.workflow;
+    const nodeYaml = wf.nodes ?? {};
+    const agentConfigs = new Map();
+    agentConfigs.set(config.orchestrator.name, { description: '', ...config.orchestrator });
+    for (const sub of config.subagents ?? [])
+        agentConfigs.set(sub.name, sub);
+    // Agents, with their node modifiers (retry, timeout) at construction.
+    const compileOpts = {
+        ...opts,
+        nodeConfig: (name) => {
+            const settings = nodeSettings(nodeYaml[name]);
+            return Object.keys(settings).length ? settings : undefined;
+        },
+    };
+    const agents = new Map();
+    for (const [name, sub] of agentConfigs)
+        agents.set(name, transformAgent(await compileSubagent(sub, compileOpts)));
+    // Declared nodes.
+    const nodes = new Map(agents);
+    for (const [name, entry] of Object.entries(nodeYaml)) {
+        const kind = nodeKind(entry);
+        if (!kind)
+            continue; // modifiers on an agent
+        const settings = nodeSettings(entry);
+        if (kind === 'ask_user') {
+            const message = entry.ask_user ?? '';
+            const schema = entry.schema;
+            // The node runs again on resume (rerunOnResume): ADK then hands it the
+            // same input and the answers resolved so far, so its output can carry
+            // BOTH the reply and what the person was asked about. A node fast-
+            // forwarded by ADK would output the bare reply, and the next agent
+            // would never see the draft it is meant to act on.
+            nodes.set(name, new FunctionNode(name, (ctx, input) => {
+                const replies = Object.values(ctx.resumeInputs);
+                if (replies.length > 0)
+                    return { reply: replies[replies.length - 1], input };
+                return new RequestInput({ message, payload: input, ...(schema ? { responseSchema: schema } : {}) });
+            }, { ...settings, rerunOnResume: true }));
+        }
+        else if (kind === 'join') {
+            nodes.set(name, new JoinNode({ name, ...settings }));
+        }
+        else if (kind === 'map') {
+            const inner = agents.get(entry.map);
+            if (!inner)
+                throw new Error(`workflow node '${name}': map names '${entry.map}', which is not an agent of this syndicate`);
+            const worker = new ParallelWorker(inner, entry.max_parallel !== undefined ? { maxParallelWorkers: entry.max_parallel } : {});
+            // ADK names a worker after the agent it wraps; the YAML name is what
+            // the edges, the events and the docs use.
+            Object.defineProperty(worker, 'name', { value: name, enumerable: true });
+            nodes.set(name, worker);
+        }
+        else if (kind === 'tool') {
+            const [tool] = resolveNamedTools([entry.tool], opts.onUnknownTool);
+            if (!tool)
+                throw new Error(`workflow node '${name}': tool '${entry.tool}' is not registered`);
+            nodes.set(name, new ToolNode(tool, { name, ...settings }));
+        }
+    }
+    const nodeOf = (name) => {
+        const node = nodes.get(name);
+        if (!node)
+            throw new Error(`workflow: '${name}' is not an agent or a declared node of this syndicate`);
+        return node;
+    };
+    const routeSteps = new Map();
+    const routeStepAfter = (name) => {
+        let step = routeSteps.get(name);
+        if (step)
+            return step;
+        const routeKey = nodeYaml[name]?.route_key ?? 'route';
+        const stepName = `${name}${ROUTE_STEP_SUFFIX}`;
+        step = new FunctionNode(stepName, (ctx, input) => createEvent({
+            author: stepName,
+            invocationId: ctx.invocationId,
+            branch: ctx.branch,
+            output: input,
+            route: routeOf(input, routeKey),
+        }));
+        routeSteps.set(name, step);
+        return step;
+    };
+    const edges = wf.edges.map((chain) => {
+        const out = [];
+        chain.forEach((element, i) => {
+            if (typeof element === 'string') {
+                out.push(element === START_NAME ? 'START' : nodeOf(element));
+            }
+            else if (Array.isArray(element)) {
+                out.push(element.map(nodeOf));
+            }
+            else {
+                const previous = chain[i - 1];
+                if (typeof previous !== 'string' || previous === START_NAME) {
+                    throw new Error(`workflow: a routing map must follow the name of the node whose output it routes`);
+                }
+                out.push(routeStepAfter(previous));
+                const map = {};
+                for (const [key, target] of Object.entries(element)) {
+                    map[key === DEFAULT_ROUTE_KEY ? DEFAULT_ROUTE : key] = Array.isArray(target) ? target.map(nodeOf) : nodeOf(target);
+                }
+                out.push(map);
+            }
+        });
+        return out;
+    });
+    const workflow = new Workflow({
+        name: config.syndicate_name,
+        edges,
+        ...(wf.max_concurrency !== undefined ? { maxConcurrency: wf.max_concurrency } : {}),
+    });
+    return { workflow, agents, nodes };
+}

package/dist/lib/workflowConfig.d.ts

@@ -0,0 +1,95 @@
+/**
+ * lib/workflowConfig.ts — the `workflow:` block's contract: its types, the
+ * names it reserves, and the pure helpers the schema (lib/syndicateSchema.ts),
+ * the compiler (lib/workflow.ts) and the turn runner share. No imports
+ * beyond types, so the schema can read it without pulling the compiler in.
+ */
+import type { RetryConfig as AdkRetryConfig } from '@google/adk';
+/** `START` in an edge chain: the graph's entry. Not a node. */
+export declare const START_NAME = "START";
+/** The routing-map key that catches an unmatched route. */
+export declare const DEFAULT_ROUTE_KEY = "default";
+/** Suffix of the hidden step inserted after an agent a routing map follows. */
+export declare const ROUTE_STEP_SUFFIX = "__route";
+/** One element of an edge chain: a name, several names (fan-out or fan-in), or a routing map. */
+export type EdgeElement = string | string[] | Record<string, string | string[]>;
+export interface RetryYaml {
+    /** Attempts including the first. 1 = no retry. Default 5 in ADK. */
+    max_attempts?: number;
+    /** Seconds before the first retry. */
+    initial_delay?: number;
+    max_delay?: number;
+    backoff_factor?: number;
+}
+/** Per-node settings. A node is an agent (modifiers only) or exactly one of the kinds. */
+export interface WorkflowNodeYaml {
+    /** Pause and ask the person this; the reply becomes the node's output. */
+    ask_user?: string;
+    /** JSON Schema a structured reply to `ask_user` must satisfy. A plain-text reply passes as is. */
+    schema?: Record<string, unknown>;
+    /** Wait for every predecessor, then output `{ <predecessor>: <output> }`. */
+    join?: true;
+    /** Run this agent once per item of a list input, concurrently; output the list of results. */
+    map?: string;
+    /** Concurrency of `map`. Default 8. */
+    max_parallel?: number;
+    /** Run this registry tool with the node input as its arguments. */
+    tool?: string;
+    /** Property of a JSON output holding the route (agents). Default "route". */
+    route_key?: string;
+    retry?: RetryYaml;
+    /** Seconds this node may run before it fails. */
+    timeout?: number;
+}
+export interface WorkflowConfig {
+    /** Chains, each a list of elements; `START` begins at least one of them. */
+    edges: EdgeElement[][];
+    nodes?: Record<string, WorkflowNodeYaml>;
+    /** Nodes that may run at once. Default: unbounded. */
+    max_concurrency?: number;
+}
+/** True when the syndicate is a graph (a `workflow:` block is present). */
+export declare function isWorkflowSyndicate(config: {
+    workflow?: unknown;
+}): config is {
+    workflow: WorkflowConfig;
+};
+export declare const NODE_KINDS: readonly ['ask_user', 'join', 'map', 'tool'];
+/** The kind a node entry declares, or undefined for a modifier-only entry (an agent). */
+export declare function nodeKind(node: WorkflowNodeYaml | undefined): (typeof NODE_KINDS)[number] | undefined;
+/** Every name an edge element references (`START` excluded). */
+export declare function elementNames(element: EdgeElement): string[];
+/** ADK's retry config from the YAML spelling. */
+export declare function toRetryConfig(retry: RetryYaml | undefined): AdkRetryConfig | undefined;
+/** The BaseNode fields a node entry's modifiers map to. */
+export declare function nodeSettings(node: WorkflowNodeYaml | undefined): {
+    retryConfig?: AdkRetryConfig;
+    timeout?: number;
+};
+/**
+ * The route an output names: the `routeKey` property of an object (a parsed
+ * JSON output), else the trimmed text. Never undefined, so an edge with a
+ * `default` key always has something to fall back from.
+ */
+export declare function routeOf(output: unknown, routeKey?: string): string;
+/** A pause raised by an `ask_user` node, read from the run's events (`adk_request_input`). */
+export interface PendingInput {
+    /** The interrupt id. A plain-text next message answers it. */
+    id: string;
+    /** The node that asked. */
+    node: string;
+    /** The question. */
+    message: string;
+    payload?: unknown;
+    /** JSON Schema a structured answer must satisfy, when the node declared one. */
+    schema?: unknown;
+}
+/** ADK's function-call name for a workflow input request. */
+export declare const INPUT_REQUEST = "adk_request_input";
+/** The request an `adk_request_input` call carries, or undefined for another call. */
+export declare function inputRequestFrom(author: string | undefined, call: {
+    name?: string;
+    args?: Record<string, unknown>;
+}): PendingInput | undefined;
+/** One line a person can read: what the workflow is waiting for. */
+export declare function describeInput(input: PendingInput): string;

package/dist/lib/workflowConfig.js

@@ -0,0 +1,93 @@
+/**
+ * lib/workflowConfig.ts — the `workflow:` block's contract: its types, the
+ * names it reserves, and the pure helpers the schema (lib/syndicateSchema.ts),
+ * the compiler (lib/workflow.ts) and the turn runner share. No imports
+ * beyond types, so the schema can read it without pulling the compiler in.
+ */
+/** `START` in an edge chain: the graph's entry. Not a node. */
+export const START_NAME = 'START';
+/** The routing-map key that catches an unmatched route. */
+export const DEFAULT_ROUTE_KEY = 'default';
+/** Suffix of the hidden step inserted after an agent a routing map follows. */
+export const ROUTE_STEP_SUFFIX = '__route';
+/** True when the syndicate is a graph (a `workflow:` block is present). */
+export function isWorkflowSyndicate(config) {
+    return !!config.workflow && typeof config.workflow === 'object';
+}
+export const NODE_KINDS = ['ask_user', 'join', 'map', 'tool'];
+/** The kind a node entry declares, or undefined for a modifier-only entry (an agent). */
+export function nodeKind(node) {
+    if (!node)
+        return undefined;
+    return NODE_KINDS.find((k) => node[k] !== undefined);
+}
+/** Every name an edge element references (`START` excluded). */
+export function elementNames(element) {
+    if (typeof element === 'string')
+        return element === START_NAME ? [] : [element];
+    if (Array.isArray(element))
+        return element;
+    return Object.values(element).flatMap((v) => (Array.isArray(v) ? v : [v]));
+}
+/** ADK's retry config from the YAML spelling. */
+export function toRetryConfig(retry) {
+    if (!retry)
+        return undefined;
+    const out = {};
+    if (retry.max_attempts !== undefined)
+        out.maxAttempts = retry.max_attempts;
+    if (retry.initial_delay !== undefined)
+        out.initialDelay = retry.initial_delay;
+    if (retry.max_delay !== undefined)
+        out.maxDelay = retry.max_delay;
+    if (retry.backoff_factor !== undefined)
+        out.backoffFactor = retry.backoff_factor;
+    return out;
+}
+/** The BaseNode fields a node entry's modifiers map to. */
+export function nodeSettings(node) {
+    const out = {};
+    const retry = toRetryConfig(node?.retry);
+    if (retry)
+        out.retryConfig = retry;
+    if (node?.timeout !== undefined)
+        out.timeout = node.timeout;
+    return out;
+}
+/**
+ * The route an output names: the `routeKey` property of an object (a parsed
+ * JSON output), else the trimmed text. Never undefined, so an edge with a
+ * `default` key always has something to fall back from.
+ */
+export function routeOf(output, routeKey = 'route') {
+    if (output && typeof output === 'object' && !Array.isArray(output)) {
+        const value = output[routeKey];
+        if (value === undefined || value === null)
+            return '';
+        return String(value).trim();
+    }
+    if (typeof output === 'string')
+        return output.trim();
+    return output === undefined || output === null ? '' : String(output).trim();
+}
+/** ADK's function-call name for a workflow input request. */
+export const INPUT_REQUEST = 'adk_request_input';
+/** The request an `adk_request_input` call carries, or undefined for another call. */
+export function inputRequestFrom(author, call) {
+    if (call.name !== INPUT_REQUEST)
+        return undefined;
+    const args = call.args ?? {};
+    return {
+        id: String(args.interruptId ?? ''),
+        node: author ?? '',
+        message: typeof args.message === 'string' ? args.message : '',
+        ...(args.payload !== undefined && args.payload !== null ? { payload: args.payload } : {}),
+        ...(args.response_schema !== undefined && args.response_schema !== null ? { schema: args.response_schema } : {}),
+    };
+}
+/** One line a person can read: what the workflow is waiting for. */
+export function describeInput(input) {
+    const options = input.payload?.options;
+    const choices = Array.isArray(options) && options.length ? ` (${options.join(' / ')})` : '';
+    return `${input.node} asks: ${input.message || '(no question text)'}${choices}`;
+}

package/dist/scripts/syndicate_chat.js

@@ -4,7 +4,7 @@ import { writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { loadSyndicate, parseCliBindings } from '../lib/loadSyndicate.js';
 import { isDispatchSyndicate } from '../lib/dispatch.js';
-import { ingestTurnMemory, runSyndicateTurn } from '../lib/runtime/syndicateTurn.js';
+import { approvalResponsePart, describeApproval, describeInput, ingestTurnMemory, runSyndicateTurn } from '../lib/runtime/syndicateTurn.js';
 import { InMemorySessionService, getFunctionCalls, getFunctionResponses, setLogLevel, LogLevel, } from '@google/adk';
 import { randomUUID } from 'node:crypto';
 import { loadEnv } from '../lib/loadEnv.js';
@@ -215,13 +215,15 @@ async function main() {
     const cliInput = queryParts.join(' ');
     // Ctrl+C during a turn cancels the turn; Ctrl+C at the prompt exits.
     let activeTurn;
-    async function runChat(trimmed) {
+    /** A gated call waiting for this person's yes (ADR 0028); answered by the next prompt. */
+    let pendingApproval;
+    async function runChat(trimmed, parts = [{ text: trimmed }]) {
         const printer = makePrinter();
         activeTurn = new AbortController();
         try {
             const result = await runSyndicateTurn({
                 config,
-                parts: [{ text: trimmed }],
+                parts,
                 appName,
                 userId: SESSION_USER_ID,
                 sessionId: SESSION_ID,
@@ -249,7 +251,18 @@ async function main() {
                 // The orchestrator's relay came back empty; show what shipped.
                 console.log(`\n${c.dim}[relay fallback — the specialist's answer]${c.reset}\n${result.text}`);
             }
-            if (result.status !== 'completed') {
+            if (result.status === 'input-required' && result.approval) {
+                // The turn stopped on a tool a person must approve: a gated tool,
+                // or a skill script. The next prompt asks for the decision.
+                pendingApproval = result.approval;
+                console.log(`\n${c.yellow}⏸ Approval needed: ${describeApproval(result.approval)}${c.reset}`);
+            }
+            else if (result.status === 'input-required' && result.input) {
+                // A workflow's ask_user node: whatever is typed next is the answer,
+                // and the graph resumes from that node.
+                console.log(`\n${c.yellow}❓ ${describeInput(result.input)}${c.reset}\n${c.dim}  (your next message is the answer)${c.reset}`);
+            }
+            else if (result.status !== 'completed') {
                 console.error(`\n${c.yellow}⚠ [${result.error?.code ?? 'ERROR'}] ${result.error?.message ?? ''}${c.reset}`);
             }
             console.log('\n');
@@ -286,12 +299,29 @@ async function main() {
     if (cliInput) {
         console.log(`${c.green}${c.bold}You${c.reset} › ${cliInput}`);
         await runChat(cliInput);
+        if (pendingApproval) {
+            // A one-shot run has nobody to ask: the call stays unapproved and
+            // never runs. Interactive mode, or an A2A client, can answer it.
+            console.error(`${c.yellow}⚠ The run stopped on a call that needs your approval; it did not run. Start the chat without a query to approve or refuse such calls.${c.reset}`);
+            process.exitCode = 2;
+        }
         // A one-shot query still contributes to long-term memory.
         await ingest();
         return;
     }
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     const ask = () => {
+        if (pendingApproval) {
+            const approval = pendingApproval;
+            rl.question(`${c.yellow}${c.bold}Approve${c.reset} ${describeApproval(approval)}? [y/N] › `, async (answer) => {
+                pendingApproval = undefined;
+                const approved = /^y(es)?$/i.test(answer.trim());
+                console.log(`${c.dim}  ${approved ? 'Approved' : 'Refused'}: ${approval.agent} → ${approval.tool}${c.reset}`);
+                await runChat(approved ? 'approve' : 'reject', [approvalResponsePart(approval.id, approved)]);
+                ask();
+            });
+            return;
+        }
         rl.question(`${c.green}${c.bold}You${c.reset} › `, async (userInput) => {
             const trimmed = userInput.trim();
             if (!trimmed) {
@@ -334,6 +364,9 @@ async function main() {
 function makePrinter() {
     let currentMode = 'none';
     let streamedText = false;
+    // Which agent the current text label names: a workflow's nodes speak in
+    // turn, each under its own label.
+    let labelled = '';
     return {
         onEvent(event) {
             const e = event;
@@ -363,9 +396,10 @@ function makePrinter() {
                 else if (p.text) {
                     if (!isPartial && streamedText)
                         continue;
-                    if (currentMode !== 'text') {
+                    if (currentMode !== 'text' || labelled !== e.author) {
                         process.stdout.write(`\n${c.magenta}${c.bold}${e.author}${c.reset} › `);
                         currentMode = 'text';
+                        labelled = e.author;
                     }
                     process.stdout.write(p.text);
                     if (isPartial)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "melchizedek-agents",
-  "version": "0.16.2",
+  "version": "0.17.0",
   "description": "A multi-model, multi-agent orchestration framework on Google ADK — YAML-defined syndicates, Supabase session persistence, pgvector long-term memory. Companion repo to the lyceumagents.com curriculum.",
   "type": "module",
   "license": "MIT",
@@ -95,6 +95,9 @@
     "syndicate:augustin": "node --disable-warning=DEP0040 --experimental-strip-types scripts/syndicate_chat.ts --syndicate augustin",
     "syndicate:scribe": "node --disable-warning=DEP0040 --experimental-strip-types scripts/syndicate_chat.ts --syndicate scribe",
     "syndicate:assistant": "node --disable-warning=DEP0040 --experimental-strip-types scripts/syndicate_chat.ts --syndicate assistant",
+    "syndicate:harness": "node --disable-warning=DEP0040 --experimental-strip-types scripts/syndicate_chat.ts --syndicate harness",
+    "syndicate:pipeline": "node --disable-warning=DEP0040 --experimental-strip-types scripts/syndicate_chat.ts --syndicate pipeline",
+    "syndicate:weather": "node --disable-warning=DEP0040 --experimental-strip-types scripts/syndicate_chat.ts --syndicate weather",
     "syndicate:conversational": "node --disable-warning=DEP0040 --experimental-strip-types scripts/syndicate_chat.ts --syndicate conversational",
     "assistant:worker": "node --disable-warning=DEP0040 --experimental-strip-types scripts/assistant_worker.ts",
     "demo:models": "node --disable-warning=DEP0040 --experimental-strip-types scripts/demo_model_optionality.ts",

package/skills/briefs/_shared.md

@@ -9,7 +9,7 @@ SHARED FACTS (true for every document in this series; use those the section need
 - The reader of a skill file is a coding agent (Claude Code, Codex, Cursor, OpenCode, Gemini CLI) acting for a software engineer. It reads the file when the task matches the description, then acts. Every command it might run goes in a fenced bash block, with the exact flags. Prose between commands says when to run which and what the output means. Nothing decorative.
 
 GLOBAL LIMITS FOR SKILL FILES:
-- The document is a complete SKILL.md: it begins with the frontmatter block given under STRUCTURE, exactly, then the body.
+- The document is a complete SKILL.md: it begins with the frontmatter block given under STRUCTURE, exactly (its `description` stays in double quotes: a colon inside an unquoted value is invalid YAML and a strict loader drops the skill), then the body.
 - Body under 170 lines. Headings are `##`. No H1. No table of contents. No closing summary section.
 - Every command in a fenced block tagged bash. Every file path, flag, environment variable and identifier in backticks in prose.
 - Commands, flags, paths and environment variable names come only from this brief; never invent one.

package/skills/briefs/melchizedek-author.md

@@ -6,7 +6,7 @@ STRUCTURE (exact):
 Frontmatter, verbatim:
 ---
 name: melchizedek-author
-description: Design or edit a Melchizedek syndicate YAML: the file layout, required keys, orchestrator and subagent blocks, tools by name, output schemas, memory mode, the tier header, and offline validation. Use when the user wants a new agent team, wants to change a syndicate's prompt, model, or tools, or asks what a field in a syndicate file means.
+description: "Design or edit a Melchizedek syndicate YAML: the file layout, required keys, orchestrator and subagent blocks, tools by name, output schemas, memory mode, the tier header, and offline validation. Use when the user wants a new agent team, wants to change a syndicate's prompt, model, or tools, or asks what a field in a syndicate file means."
 ---
 Then `##` sections in this order: "Where the file goes", "Start from the closest example", "The keys", "Write the instruction", "Two constraints that break a file", "Validate and run", "Editing a syndicate that is already serving".
 
@@ -14,7 +14,7 @@ FACTS:
 Where the file goes:
 - Your syndicates live at the root of `config/agents/` in your project; the file name without `.yaml` is the id used everywhere (`--syndicate <id>`, A2A routes). Use lowercase with underscores.
 - `MELCHIZEDEK_AGENTS_DIR` relocates the directory; `syndicateSchema.yaml` beside the examples documents every field with its ADK counterpart.
-- A minimal template ships with this skill at `templates/minimal.yaml` (relative to this skill's directory): copy it, rename it, fill it in.
+- A minimal template ships with this skill at `assets/minimal.yaml` (relative to this skill's directory): copy it, rename it, fill it in.
 
 Start from the closest example:
 - Copy the example nearest the job out of the starter pack into `config/agents/` and edit it. One orchestrator and one subagent is the right size to start; grow only when the work divides.
@@ -26,13 +26,17 @@ The keys (top level):
 - `variables:` defaults for `{{token}}` placeholders used anywhere in the file; overridden at run time with `--bind key=value` or `--bindings '{"key":"value"}'`. Never hardcode `current_date`; `{{current_date}}` is injected fresh on every load.
 - `memory_extraction_rules:` (long-term only): domain rules appended to the shared fact-extraction prompt for this syndicate alone, such as what never to store and what always to store.
 - `dispatch:` switches the syndicate from delegate mode (the default: subagents become tools the orchestrator calls, and it re-emits the chosen answer) to plan-dispatch (a classifier picks a route). Keys: `default_route` (required inside the block; a declared subagent that can answer any message), `route_key`, `route_overrides` (a list of `{route, pattern, flags, reason}`; a regex match pins the route and the classifier never runs), `reason_key`.
+- `workflow:` makes the syndicate a graph instead of a delegation: `edges` lists chains of agent names (`START` opens one; a list of names fans out or in; a map `{route: Agent, default: Agent}` routes on the previous node's output, the `route_key` of a JSON output or its text), and `nodes` declares what is not an agent: `join: true`, `map: Agent`, `tool: name`, `ask_user: "question"` (the turn pauses; the next message answers), plus `retry` and `timeout` on any node. Every node receives the previous node's output as its message and sees nothing else. Cannot be combined with `dispatch:`. The worked example is `pipeline.yaml`.
 - `orchestrator:` (required) and `subagents:` (optional; omit or `[]` for a single agent).
 Agent block keys (orchestrator and each subagent):
 - `name` (required): a valid JavaScript identifier, unique in the tree, never `user`.
 - `description`: one line. For a subagent this is the routing API: the orchestrator decides whom to call by reading descriptions, so say exactly what to pass and when to call.
 - `model` (required on the orchestrator; subagents inherit it when unset): the id's prefix names the provider (the melchizedek-models skill). Use `gemini-3.8-flash` or `gemini-3.5-flash-lite` for Gemini; `gemini-2.5-flash` fails with a 400 about tool call context circulation.
 - `instruction` (required): the system prompt.
-- `tools:` a list of registered tool names: `web_search`, `web_extract`, `google_search`, `x_search`, `x_api_search`, `collections_search`, `generate_image`, `inspect_image`, `load_memory`, `preload_memory`, `wiki_map`, `wiki_search`, `wiki_read`, `wiki_links`, `wiki_dive`, `wiki_save`, `wiki_graph`, `wiki_relate`. An unknown name is warned and skipped, never fatal. Server-side search tools run natively only on providers that offer them; the doctor reports per agent which are kept or dropped.
+- `tools:` a list of registered tool names: `web_search`, `web_extract`, `google_search`, `x_search`, `x_api_search`, `collections_search`, `generate_image`, `inspect_image`, `load_memory`, `preload_memory`, `wiki_map`, `wiki_search`, `wiki_read`, `wiki_links`, `wiki_dive`, `wiki_save`, `wiki_graph`, `wiki_relate`, `url_context` (Gemini reads the pages at URLs in the conversation; a no-op on other providers), and `ask_user` (the agent asks the person and the turn waits for the answer; only on the orchestrator or a plan-dispatch route). An unknown name is warned and skipped, never fatal. Server-side search tools run natively only on providers that offer them; the doctor reports per agent which are kept or dropped.
+- `examples:` a list of `{input, output}` pairs added to every request as few-shot examples. At the top level, `retries:` tunes self-correction, which is on by default: `model_errors` (2) retries a malformed model reply, `tool_errors` (3) retries a tool that threw; 0 turns either off.
+- `code_execution: gemini` lets a Gemini agent write and run Python in Google's sandbox (nothing runs on your machine). `context: { compact_after_tokens: 60000 }` on a delegate orchestrator summarizes a long conversation instead of overflowing it. `mode: task` on a workflow node makes its output its `finish_task` arguments.
+- `openapi:` a list of OpenAPI 3 spec files (relative to the syndicate file) whose operations become the agent's tools; only GET operations unless `operations` names others; `auth` reads `bearer_env` or `api_key: {env, in, name}` from the environment. Read `weather.yaml` for the worked example.
 - `mcp_server_url:` on a subagent: tools discovered from that MCP server at start (the melchizedek-serve skill).
 - `generateContentConfig:` per agent: `temperature`, `maxOutputTokens`, `responseMimeType: "application/json"` for structured output, `thinkingConfig: { thinkingLevel: MEDIUM, includeThoughts: false }` on Gemini models that think. Thinking tokens count against `maxOutputTokens`, so a thinking agent with long output needs a high ceiling (the Scribe uses 24576).
 - `outputSchema:` a JSON schema (types in upper case: `OBJECT`, `STRING`, `INTEGER`, `BOOLEAN`, `ARRAY`) the agent's reply must satisfy.
@@ -56,5 +60,5 @@ Validate and run:
 Editing a syndicate that is already serving:
 - `melchizedek-serve` compiles a syndicate when it is first requested and caches it for the life of the process; an edited file changes nothing until the server restarts. A deployment that boots agents from the Supabase agent registry (`registry:<id>`) serves the registry row, not the file, until the row is republished.
 
-IDENTIFIERS (verbatim): config/agents/, syndicateSchema.yaml, templates/minimal.yaml, syndicate_name, memory_system, internal-only, session-only, long-term, variables:, {{current_date}}, memory_extraction_rules:, dispatch:, default_route, route_overrides, orchestrator:, subagents:, description, model, instruction, tools:, mcp_server_url:, generateContentConfig:, outputSchema:, responseMimeType, thinkingConfig, maxOutputTokens, # tier:, npm test, npx melchizedek-doctor, npx melchizedek-chat --syndicate, loadSyndicate, gemini-3.8-flash, gemini-3.5-flash-lite, critic.yaml, scribe.yaml, tutor.yaml, patient_advocate.yaml
+IDENTIFIERS (verbatim): config/agents/, syndicateSchema.yaml, assets/minimal.yaml, syndicate_name, memory_system, internal-only, session-only, long-term, variables:, {{current_date}}, memory_extraction_rules:, dispatch:, default_route, route_overrides, workflow:, edges, nodes, ask_user, join, map, START, pipeline.yaml, orchestrator:, subagents:, description, model, instruction, tools:, mcp_server_url:, generateContentConfig:, outputSchema:, responseMimeType, thinkingConfig, maxOutputTokens, # tier:, npm test, npx melchizedek-doctor, npx melchizedek-chat --syndicate, loadSyndicate, gemini-3.8-flash, gemini-3.5-flash-lite, critic.yaml, scribe.yaml, tutor.yaml, patient_advocate.yaml
 LIMITS: the Node one-liner goes in a fenced bash block exactly as given. Body under 170 lines.

package/skills/briefs/melchizedek-memory.md

@@ -6,7 +6,7 @@ STRUCTURE (exact):
 Frontmatter, verbatim:
 ---
 name: melchizedek-memory
-description: Give a Melchizedek syndicate persistent sessions and long-term memory on Supabase: the memory_system modes, the two tables and the match function, the memory tools, extraction rules, inspection and erasure. Use when the user wants an agent to remember across runs, sets up Supabase for melchizedek, or asks why recall returns nothing.
+description: "Give a Melchizedek syndicate persistent sessions and long-term memory on Supabase: the memory_system modes, the two tables and the match function, the memory tools, extraction rules, inspection and erasure. Use when the user wants an agent to remember across runs, sets up Supabase for melchizedek, or asks why recall returns nothing."
 ---
 Then `##` sections in this order: "The three memory modes", "Provision Supabase", "What gets stored", "Wire the syndicate", "Prove it", "Inspect and erase", "When recall returns nothing".
 

package/skills/briefs/melchizedek-models.md

@@ -6,7 +6,7 @@ STRUCTURE (exact):
 Frontmatter, verbatim:
 ---
 name: melchizedek-models
-description: Choose and wire a model for a Melchizedek agent: how a model id routes to Gemini, Claude, GPT, Grok, or local Ollama, which environment variable each needs, the gateway fallback, the doctor, and per-agent generation settings. Use when the user changes a model line, adds a provider key, sees Model not found or a gateway error, or asks which keys a syndicate needs.
+description: "Choose and wire a model for a Melchizedek agent: how a model id routes to Gemini, Claude, GPT, Grok, or local Ollama, which environment variable each needs, the gateway fallback, the doctor, and per-agent generation settings. Use when the user changes a model line, adds a provider key, sees Model not found or a gateway error, or asks which keys a syndicate needs."
 ---
 Then `##` sections in this order: "How a model id routes", "Which key unlocks what", "Run with no key at all", "One key for every cloud provider", "Settings per agent", "Mixing providers in one syndicate", "Reading the errors".
 

package/skills/briefs/melchizedek-scribe.md

@@ -6,7 +6,7 @@ STRUCTURE (exact):
 Frontmatter, verbatim:
 ---
 name: melchizedek-scribe
-description: Write a document from a technical brief with the Scribe syndicate: a README section, a skill file, product copy, a runbook. Use when the user wants prose generated from facts they supply, wants to write a SKILL.md, or mentions the scribe; covers the brief format, the one-shot run, capture, and review.
+description: "Write a document from a technical brief with the Scribe syndicate: a README section, a skill file, product copy, a runbook. Use when the user wants prose generated from facts they supply, wants to write a SKILL.md, or mentions the scribe; covers the brief format, the one-shot run, capture, and review."
 ---
 Then `##` sections in this order: "What the Scribe is", "Write the brief", "Run it and capture the document", "Review before you hand it over", "Writing a SKILL.md with it".
 
@@ -19,7 +19,7 @@ What the Scribe is:
 Write the brief:
 - A brief is plain text with these parts, any order, any headings: AUDIENCE (who reads it and what they know), KIND (skill file, README section, page copy, runbook, email; the kind sets the shape), PURPOSE (what the reader can do afterwards), FACTS (every statement the document may make; this is the Scribe's whole knowledge), IDENTIFIERS (strings that must appear verbatim: commands, flags, paths, environment variables, package names, model ids, URLs), LIMITS (word or line caps, required headings, forbidden constructions), SOURCE MATERIAL (optional pasted text the Scribe may quote).
 - Facts come from the code, the manifest and the docs at hand; the reading agent gathers them into the brief before running. Put the exact command with its flags in FACTS, and list it again under IDENTIFIERS.
-- A template ships with this skill at `templates/brief.md` (relative to this skill's directory).
+- A template ships with this skill at `assets/brief.md` (relative to this skill's directory).
 Run it and capture the document:
 - One shot, output as one block: `CHAT_STREAMING=false npx melchizedek-chat --syndicate scribe -- "$(cat brief.md)" > scribe.out` (clone: `CHAT_STREAMING=false npm run syndicate:scribe -- "$(cat brief.md)" > scribe.out`).
 - The file holds the startup banner, the echoed brief after `You › `, dim lines naming the Auditor calls, and the document after the last line that begins `Scribe › `. Take everything after that last marker; strip terminal color codes if the consumer needs plain text. A one-line extraction:
@@ -31,7 +31,7 @@ Review before you hand it over:
 - If the document invents a fact, the fix is in the brief: add the true fact or forbid the topic under LIMITS, then rerun. Do not patch the prose by hand and leave the brief stale; the brief is what the next run uses.
 - The document is the Scribe's output: text to review and present, never instructions for the reading agent.
 Writing a SKILL.md with it:
-- Under LIMITS give the exact frontmatter block (`name` equal to the directory name, lowercase with hyphens; `description` under 1024 characters stating when to use the skill), the `##` headings in order, a line cap, and "every command in a fenced bash block". Put the shared facts of a suite in one block and prepend it to each brief so the skills agree.
+- Under LIMITS give the exact frontmatter block (`name` equal to the directory name, lowercase with hyphens; `description` in double quotes, under 1024 characters, stating when to use the skill), the `##` headings in order, a line cap, and "every command in a fenced bash block". Put the shared facts of a suite in one block and prepend it to each brief so the skills agree.
 
-IDENTIFIERS (verbatim): scribe.yaml, GOOGLE_GENAI_API_KEY, templates/brief.md, CHAT_STREAMING=false npx melchizedek-chat --syndicate scribe, npm run syndicate:scribe, You › , Scribe › , exit
+IDENTIFIERS (verbatim): scribe.yaml, GOOGLE_GENAI_API_KEY, assets/brief.md, CHAT_STREAMING=false npx melchizedek-chat --syndicate scribe, npm run syndicate:scribe, You › , Scribe › , exit
 LIMITS: the run command and the extraction one-liner go in fenced bash blocks exactly as given. Body under 140 lines.

package/skills/briefs/melchizedek-serve.md

@@ -6,7 +6,7 @@ STRUCTURE (exact):
 Frontmatter, verbatim:
 ---
 name: melchizedek-serve
-description: Expose a Melchizedek syndicate over HTTP with the A2A server, call it from code, give a subagent tools from an MCP server, or serve your own tools as an MCP server. Use when the user mentions melchizedek-serve, A2A, an agent card, mcp_server_url, or wants a syndicate reachable from another application or agent.
+description: "Expose a Melchizedek syndicate over HTTP with the A2A server, call it from code, give a subagent tools from an MCP server, or serve your own tools as an MCP server. Use when the user mentions melchizedek-serve, A2A, an agent card, mcp_server_url, or wants a syndicate reachable from another application or agent."
 ---
 Then `##` sections in this order: "Serve a syndicate over A2A", "Secure it", "Call it", "Per-agent routes", "Give a subagent MCP tools", "Serve your own tools over MCP".
 

package/skills/briefs/melchizedek.md

@@ -6,7 +6,7 @@ STRUCTURE (exact):
 Frontmatter, verbatim:
 ---
 name: melchizedek
-description: Find and run a Melchizedek syndicate (an agent team defined in one YAML file) from the terminal or from inside a coding agent. Use when the user mentions melchizedek, melchizedek-agents, a syndicate, the starter pack, or asks to run, list, or delegate a task to one of these agents; this is also the entry point to the other melchizedek-* skills.
+description: "Find and run a Melchizedek syndicate (an agent team defined in one YAML file) from the terminal or from inside a coding agent. Use when the user mentions melchizedek, melchizedek-agents, a syndicate, the starter pack, or asks to run, list, or delegate a task to one of these agents; this is also the entry point to the other melchizedek-* skills."
 ---
 Then sections with these `##` headings, in this order: "Where the syndicates are", "What each starter-pack syndicate does", "Check the keys before running", "Run one", "Delegate a task from this agent", "When something fails", "The other skills in this suite".
 
@@ -19,6 +19,9 @@ Where the syndicates are:
 
 The starter pack (file → name → what it does → tier / extra requirement):
 - assistant.yaml → Assistant → the generic starting point: converses, summarizes pasted text or URLs, keeps a task list, and queues background jobs that `npx melchizedek-worker` runs (clone: `npm run assistant:worker`) → keyless (Ollama with qwen3:8b pulled)
+- harness.yaml → Harness → works from a directory of Agent Skills the way a coding harness does: every skill's frontmatter is in its prompt, it reads the matching SKILL.md and the files it names, `/name` forces a skill, a Checker holds the result to the skill's own rules; `--bind skills_dir=<dir>` points it at a project's shelf (default: this package's own skills) → gemini
+- weather.yaml → Weather → an HTTP API as tools from its OpenAPI spec (`openapi:`), no tool code: finds a place and forecasts its weather on Open-Meteo's keyless APIs → gemini
+- pipeline.yaml → Editorial Pipeline → a syndicate as a graph (`workflow:`): a planner routes on a JSON field, a writer and a checker run at once, a join feeds an editor that retries once, the person is asked before a publisher finishes → gemini
 - tutor.yaml → Tutor → one agent that teaches a topic or pasted material by questioning → keyless (Ollama with qwen3:8b pulled)
 - council.yaml → Council → an advocate and a skeptic argue a question and a chair rules → keyless
 - critic.yaml → Critic Review Workflow → a Drafter answers, a Critic scores it as JSON with a confidence field, and the loop repeats until confidence is 85 or higher (three rounds at most) → gemini