aiwg-utils Agent Worked-Examples Catalog

Discoverable home for the few-shot worked examples, report scaffolds, and on-demand

reference tables that used to live inline in aiwg-utils agent definitions.

Externalizing them keeps agent definitions lean for subagent dispatch (see the

`few-shot-examples` rule and #1587) while preserving the few-shot floor — the examples

still exist, just here instead of bloating every system prompt.

How this works

• Each agent definition keeps at most one compact inline example as an anchor,

plus its routing tables, capability matrices, and gates (those are capabilities,

not examples — they stay inline).

• The remaining worked transcripts, report templates, and on-demand reference tables

live in a per-agent file under `agent-examples/`.

• A lean agent definition links to its example file; the agent reads and follows it on

demand (it is an ancillary reference, not loaded into the prompt budget).

Reaching the examples

# Discover the catalog
aiwg discover "agent worked examples catalog"

# Read a specific agent's examples (ancillary file)
aiwg show ...   # or read docs/agent-examples/<agent-name>-examples.md directly

Per-agent example files

Files are added under `agent-examples/<agent-name>-examples.md` as oversized

definitions are debloated. Each contains the worked examples, report scaffolds, and

reference tables for that agent, with the same structure they had inline.

Index note: this catalog is populated incrementally during the #1587 debloat pass.

An agent without a file here either has its single inline anchor only, or has not yet

been debloated. `aiwg doctor` flags any agent definition over the size ceiling.

Per-agent files present

Agent	File	Contents
aiwg-steward	`agent-examples/aiwg-steward-examples.md`	Worked transcripts, report scaffolds, on-demand troubleshooting reference tables (session-reload, Hermes composition, deploy errata)
aiwg-steward	`agent-examples/aiwg-steward-routing-reference.md`	Reference-grade routing lookups extracted in #1600: full CLI toolset table, kernel-pivot per-provider deploy-path table, command-routing examples, orchestration/loop routing table, invocation patterns, `$AIWG_ROOT` diagnostic + per-project-copy fallback, catalog-search block. Consulted on demand — the steward keeps the decision logic and the #1600-protected routing tables inline.

Note: aiwg-steward dual source

The `aiwg-steward` agent ships as two byte-identical source copies that must be kept

in sync:

Copy	Path	Deployed to
Canonical	`agentic/code/addons/aiwg-utils/agents/aiwg-steward.md`	All standard providers via the manifest-driven deployer (`.claude/agents/`, `.factory/droids/`, etc.)
Mirror	`agentic/code/agents/personas/aiwg-steward.md`	OpenHuman only, as a markdown persona to `.agents/agents/` via `tools/agents/providers/openhuman.mjs`

The personas copy is the OpenHuman markdown-persona deploy mirror of the aiwg-utils

canonical. OpenHuman consumes markdown personas from `agentic/code/agents/personas/`

rather than the manifest-driven addon path, so the steward needs a persona-tree copy.

The two files are kept byte-identical — any edit to one must be applied verbatim to

the other (#1600). Both use the same `addons/aiwg-utils/...` pointer to the steward

worked-examples file, which resolves regardless of which copy is loaded.

References

• `few-shot-examples` rule — the inline ≤1 + catalog requirement and size ceiling
• #1587 — debloat oversized agent definitions
• #1600 — aiwg-steward reconcile + debloat (dual-source byte-identity)
• #193 — original few-shot examples implementation