aiwg-utils Agent Worked-Examples Catalog

Execution note: Commands on this page beyond installation and bootstrap are operational detail for your agent or an advanced operator. If you are working through an agent, describe the outcome you want; the agent should explain material changes, request any needed approval, and report evidence when it finishes.

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 only Tier-1 routing logic and guardrails. Detailed tables move behind quickrefs and references when they are not needed for default dispatch.

• 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`	Tier-3 routing lookups: full CLI toolset table, kernel-pivot per-provider deploy-path table, issue workflow routes, project-local routes, 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 only Tier-1 decision logic inline.

Note: aiwg-steward dual source

The `aiwg-steward` agent ships as two closely related source copies that must preserve the same Tier-1 routing contract:

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.)
Persona	`agentic/code/agents/personas/aiwg-steward.md`	OpenHuman/persona selection surface

The persona copy carries persona-specific frontmatter/triggers, so it is not byte-identical to the addon agent. Keep the body behaviorally aligned: Tier-1 role, guardrails, discover/show routes, and Tier-3 pointers must remain equivalent. Both copies use the same `addons/aiwg-utils/...` reference files, which resolve 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)
• #1661 — steward Tier-1/2/3 split for sub-12 KB dispatch
• #193 — original few-shot examples implementation