aiwg-utils Agent Worked-Examples Catalog

Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.

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

Use AIWG to complete this documented outcome: Reaching the examples
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

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. the agent-owned doctor operation 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