melchizedek-agents 0.16.2 → 0.17.0

package/skills/melchizedek/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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."
 ---
 
 ## Where the syndicates are
@@ -24,6 +24,9 @@ To modify an example, copy it into `config/agents/` in your project and edit it.
 ## What each starter-pack syndicate does
 
 - `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 reaches 85 or higher (three rounds at most); gemini.

package/skills/melchizedek-author/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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."
 ---
 
 ## Where the file goes
@@ -9,7 +9,7 @@ Your syndicates live at the root of `config/agents/` in your project. The file n
 
 The environment variable `MELCHIZEDEK_AGENTS_DIR` points the loader at another directory. The schema file `syndicateSchema.yaml` sits beside the examples and 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, and fill in the fields.
+A minimal template ships with this skill at `assets/minimal.yaml` relative to this skill's directory. Copy it, rename it, and fill in the fields.
 
 ## Start from the closest example
 
@@ -31,6 +31,7 @@ Top-level keys:
 - `variables:`: default values for `{{token}}` placeholders used across the file. Override them at run time with `--bind key=value` or `--bindings '{"key":"value"}'`. The loader injects `{{current_date}}` fresh on every load; omit static date strings.
 - `memory_extraction_rules:`: domain rules appended to the shared fact-extraction prompt in `long-term` mode, such as what to store and what to skip.
 - `dispatch:`: switches the syndicate from delegate mode to plan-dispatch routing where a classifier picks a route. In delegate mode, subagents act as tools the orchestrator calls, and the orchestrator re-emits the chosen answer. The `dispatch:` block requires `default_route` naming a declared subagent that can answer any message. It accepts `route_key`, `reason_key`, and `route_overrides` (a list of `{route, pattern, flags, reason}`). A regex match in `route_overrides` pins the route and skips the classifier.
+- `workflow:`: makes the syndicate a graph instead of a delegation: `edges` lists chains of agent names (`START` opens one; a list fans out or in; a map `{route: Agent, default: Agent}` routes on the previous node's output), and `nodes` declares `join`, `map`, `tool` and `ask_user` nodes plus `retry` and `timeout` modifiers. Every node receives the previous node's output as its message. Cannot be combined with `dispatch:`. Read `pipeline.yaml` for the worked example.
 - `orchestrator:`: required orchestrator block.
 - `subagents:`: list of subagent blocks; omit it (or pass `[]`) for a single-agent syndicate.
 
@@ -39,7 +40,10 @@ Agent block keys for the orchestrator and each subagent:
 - `description`: one line. For a subagent, this acts as the routing API: the orchestrator decides whom to call by reading descriptions, so state what to pass and when to call.
 - `model`: model identifier, required on the orchestrator. Subagents inherit this model when unset. The melchizedek-models skill covers provider prefixes. Use `gemini-3.8-flash` or `gemini-3.5-flash-lite` for Gemini. The model `gemini-2.5-flash` fails with a 400 error about tool call context circulation.
 - `instruction`: required system prompt.
-- `tools:`: 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`. The loader warns on an unknown name and skips it. Server-side search tools run natively only on providers that offer them; `npx melchizedek-doctor` reports per agent which tools stay or drop.
+- `tools:`: 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). The loader warns on an unknown name and skips it. Server-side search tools run natively only on providers that offer them; `npx melchizedek-doctor` reports per agent which tools stay or drop.
+- `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:`: URL on a subagent to discover MCP tools at start. The melchizedek-serve skill covers MCP servers.
 - `generateContentConfig:`: per-agent options: `temperature`, `maxOutputTokens`, `responseMimeType: "application/json"`, and `thinkingConfig: { thinkingLevel: MEDIUM, includeThoughts: false }` on Gemini models that think. Thinking tokens count against `maxOutputTokens`. The Scribe uses 24576 for `maxOutputTokens`.
 - `outputSchema:`: a JSON schema using uppercase types (`OBJECT`, `STRING`, `INTEGER`, `BOOLEAN`, `ARRAY`) that the agent reply must satisfy.

package/skills/melchizedek-memory/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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."
 ---
 
 ## The three memory modes

package/skills/melchizedek-models/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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."
 ---
 
 ## How a model id routes

package/skills/melchizedek-scribe/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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."
 ---
 
 ## What the Scribe is
@@ -20,7 +20,7 @@ A brief is plain text. The brief contains these parts, in any order, under any h
 - LIMITS: word or line caps, required headings, and forbidden constructions.
 - SOURCE MATERIAL: optional pasted text that the Scribe may quote.
 
-You gather facts from the code, the manifest, and the documentation at hand before running. Place the exact command with its flags under FACTS, and list the exact command again under IDENTIFIERS. A brief template ships with this skill at `templates/brief.md`.
+You gather facts from the code, the manifest, and the documentation at hand before running. Place the exact command with its flags under FACTS, and list the exact command again under IDENTIFIERS. A brief template ships with this skill at `assets/brief.md`.
 
 ## Run it and capture the document
 
@@ -64,7 +64,7 @@ The Auditor catches most discrepancies. A person still reads the final result. I
 ## Writing a SKILL.md with it
 
 When you write a SKILL.md file with the Scribe, place these constraints under LIMITS:
-- The exact frontmatter block, with `name` equal to the directory name in lowercase with hyphens, and `description` under 1024 characters stating when to use the skill.
+- The exact frontmatter block, with `name` equal to the directory name in lowercase with hyphens, and `description` in double quotes, under 1024 characters, stating when to use the skill.
 - The `##` headings in order.
 - A line cap.
 - The instruction: "every command in a fenced bash block".

package/skills/melchizedek-serve/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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."
 ---
 
 ## Serve a syndicate over A2A