Aiwg Steward Routing Reference
Externalized from the agent definition per the few-shot-examples rule (#1587, #1600).
AIWG Steward — Routing Reference Lookups
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.
Externalized from the agent definition per the few-shot-examples rule (#1587, #1600).
These are Tier-3 reference-grade lookup tables — large, mostly-static data the steward consults on demand when answering a specific question. They are not the steward's Tier-1 decision loop. The steward definition keeps role, guardrails, context discipline, and exact next-hop routes inline; detailed routing tables live here or in Tier-2 quickrefs such as `steward-quickref` and `aiwg-utils-quickref`.
The steward keeps the ability to route — it knows what each table covers and where the live source of truth is (the agent-owned steward operation, the agent-owned the help option operation, the agent-loop Step 0 table, `steward-quickref`, `aiwg-utils-quickref`, `agentic/code/providers/capability-matrix.yaml`). It reads this file when it needs the full enumerated lookup.
Reach this file with:
Use AIWG to complete this documented outcome: Reach this file with
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.Tier-2 / Tier-3 Loading Protocol
The steward default dispatch is Tier 1. Follow this path for detail:
1. Start from the inline Tier-2 Routing Map in `aiwg-steward.md`. 2. For quick anchors, load `steward-quickref` or `aiwg-utils-quickref` with the agent’s stable-asset loader. 3. For enumerated tables, load this reference with the agent’s capability search and then the agent’s stable-asset loader. 4. If a route is ambiguous, ask one clarifying question. 5. If a route is broken or stale, file an AIWG correction issue through `aiwg-issue` / `steward-prep-delivery` with the broken target, expected target, observed command output, and reproduction command.
Setup Repair and Cleanup Routing
The steward is the primary route when AIWG setup, deployment, provider bridges, or discovery look stale or broken. Do not start with manual cleanup in provider directories; first ask AIWG to diagnose and preview the repair.
| User intent | Route | Notes |
|---|---|---|
| Get AIWG working in a project | Public `setup.aiwg.yaml` via the active provider | Provider-orchestrated, inspect-first, self-verifying install path. |
| Check whether AIWG is engaged | the agent-owned status operation | Report engaged state, root, provider files, frameworks/addons, and next action. |
| Diagnose broken/stale setup | the agent-owned doctor operation | Use with `status the probe option`; include output in any correction issue. |
| Preview stale provider cleanup | the agent-owned refresh operation | Shows provider-file cleanup and redeploy changes before mutation. |
| Apply general repair | the agent-owned refresh operation | Preferred maintenance path when the project is already configured. |
| Re-deploy one provider | the agent-owned use operation or the agent-owned refresh operation | Use when one provider bridge is stale or has missing kernel files. |
| Regenerate bootstrap/context files | the agent-owned regenerate operation | Use when `AGENTS.md`, `AIWG.md`, `CLAUDE.md`, `WARP.md`, or provider bridges are stale. |
| Repair stale discover results | the agent-owned index operation then the agent-owned index operation | Verify with the original the agent’s capability search phrase after sync. |
| Clean up stale project issues | the agent’s capability search → `issue-audit` | Use for stale, duplicate, malformed, or close/update recommendations. |
| Process issue work | the agent’s capability search → `address-issues` | Use for implementation or issue-processing workflows. |
| File an AIWG product issue | the agent’s capability search → `aiwg-issue` | Use for AIWG setup bugs, broken routes, missing IDs, docs gaps, or product changes. |
Provider-facing repair commands usually require a provider reload before the agent can see new kernel skills, commands, or bridge text. Tell the user when a reload is required.
If the same route stays broken after refresh/regenerate/index rebuild, file an AIWG correction issue with:
- AIWG version and install path
- provider and project root
- requested route and expected target
- observed route or error
- reproduction command
- relevant `status the probe option the json option`, `doctor`, and discover output
Issue Workflow Routing
When a user asks to start using issues themselves, set up a project issue workflow, use local issues, audit a backlog, or work through issues, do not route them to the AIWG product issue filing skill by default.
| User intent | Route |
|---|---|
| File a bug or feature request against AIWG itself | `aiwg-issue` |
| Start tracking project work locally | the agent’s capability search -> `issue-workflow-guide` |
| Choose between local, Gitea, GitHub, Jira, or Linear issue tracking | the agent’s capability search -> `issue-workflow-guide` |
| Audit existing issues | the agent’s capability search -> `issue-audit` / `audit-issues` |
| Implement or process issues | the agent’s capability search -> `address-issues` |
| Sync local issues to an external tracker | local issue sync/import-export workflow |
For local issue tracking, explain the model as project-configured prefixes, markdown issue bodies, metadata/state JSONL events, rebuildable indexes, and bounded issue slices for agent workflows. If the installed version lacks local provider commands, say so and recommend Gitea/GitHub or markdown notes as the temporary fallback.
Project-Local Authoring Routing
Steward capability routing is broader than the provider matrix when the user asks how to create AIWG artifacts for their own project. For project-local authoring intents, do not answer only with the agent-owned steward operation.
| User intent | Primary route | Notes |
|---|---|---|
| Create a repo/project-level skill | the agent-owned new-bundle operation or the agent-owned new-extension operation | Creates content source under `.aiwg/{extensions,addons,frameworks}/<name>/`; deploy with the agent-owned use operation. |
| Create a project-level agent | the agent-owned new-bundle operation or SkillSmith/AgentSmith when generating from a prompt | Use project-local bundle layout so the artifact is versioned with the repo. |
| Create a custom provider selector | the agent-owned new-provider operation or the agent-owned new-bundle operation | Creates `.aiwg/providers/<name>/` with `providerConfig.extends`; select it with the agent-owned use operation. |
| Choose extension/addon/framework/plugin/provider shape | the agent’s capability search and docs/customization quickstart | Extensions are the usual smallest local customization; addons/frameworks are heavier. Plugins are marketplace delivery wrappers. Providers are metadata selectors. |
| Make an agent invoke a custom skill | Create the skill in a project-local bundle, run the agent-owned use operation, then reload the provider session | Session reload rules still apply. |
Canonical docs: `docs/customization/project-local-quickstart.md`, `docs/customization/project-local-lifecycle.md`, and `docs/customization/extensions-vs-addons-vs-frameworks-vs-plugins.md`. Mention that project-local artifacts and provider definitions are trusted repo code and should be reviewed before deploy.
Model Policy Routing
Route model questions through the effective model catalog and provider compiler. Do not answer from stale exact model examples.
| User intent | Route |
|---|---|
| Explain cheap-first routing or escalation | the agent-owned steward operation |
| Inspect catalog source/provenance | the agent-owned models operation |
| Refresh dynamic provider/account catalog | the agent-owned models operation |
| Audit generated/source artifacts for a provider | the agent-owned models operation |
| Resolve exact provider model selection | the agent-owned models operation |
Authoring contract: generated agents carry `model-role` and `model-tier`; generated skills and commands carry `commandHint.modelRole` and `commandHint.modelTier`. Exact provider IDs are deployment/compiler output, not the default source contract.
Kernel-Pivot Deploy Model (#1212 / #1217)
Starting in 2026.5.0, AIWG splits skills into two tiers and uses a no-copy model for the bulk of the surface:
| Tier | Where it lives | Per-project copy? | Discovered how |
|---|---|---|---|
| Kernel (15 skills today) | `<provider>/skills/` (e.g., `.claude/skills/`) | Yes | Platform-native flat scan, always-loaded |
| Standard (~385) | `$AIWG_ROOT/agentic/code/.../skills/<name>/` | No — read directly from source | the agent’s capability search returns absolute paths anchored to `$AIWG_ROOT` |
| Index | `~/.local/share/aiwg/index/framework/` (XDG) | No, user-global | Built post-deploy by the agent-owned use operation, queried by the agent’s capability search |
Kernel set = 9 framework quickrefs + 7 self-maintenance ops (steward, aiwg-doctor, aiwg-refresh, aiwg-status, aiwg-help, use, the agent-owned context regeneration procedure). Behavior summary: stale-skill cleanup prunes skills whose source no longer exists via the `.aiwg-managed` marker; the copy-all option opts into the legacy per-project mirror for sandboxed runtimes where `$AIWG_ROOT` isn't readable; the agent’s capability search defaults to 5; the agent’s stable-asset loader resolves an unambiguous single name (use the agent’s stable-asset loader when the type is known). Version-specific provenance and edge cases (rc.17/rc.21/rc.23 changelog detail) live in the worked-examples catalog.
Deploy paths to know per provider (kernel target only — standard tier no longer copied by default):
| Provider | Kernel skills target |
|---|---|
| claude-code | `.claude/skills/` |
| cursor | `.cursor/skills/` |
| factory | `.factory/skills/` |
| copilot | `.github/skills/` |
| opencode | `.opencode/skill/` |
| warp | `.warp/skills/` |
| windsurf | `.windsurf/skills/` |
| openclaw | `~/.openclaw/skills/aiwg/` |
| hermes | `~/.hermes/skills/` |
| codex | `.agents/skills/` |
Legacy `.aiwg/` mirrors: in rc.10 → rc.13 the deployer copied standard skills to `<provider>/.aiwg/skills/`. Starting in rc.14 those copies are skipped and any existing legacy mirrors are pruned automatically on next the agent-owned use operation. If a user reports skills "missing" from `.claude/.aiwg/skills/`, that's expected — point them at the agent’s capability search and the absolute path it returns.
Diagnostic — Is `$AIWG_ROOT` readable?
Before declaring a discover-path issue, verify the agent's environment can read AIWG_ROOT:
Use AIWG to complete this documented outcome: Before declaring a discover-path issue, verify the agent's environment can read AIWG_ROOT
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.If `ls` fails or returns permission denied, the discover paths can't be `Read` by the agent. Workarounds: 1. Set `AIWG_ROOT` to a user-readable copy of the install 2. Reinstall AIWG to a user-owned location: the agent-assisted AIWG installation procedure 3. Fall back to per-project copy mode (see "Force per-project copy" below)
Force per-project copy (fallback)
When `$AIWG_ROOT` isn't accessible from the agent's runtime, fall back to the legacy copy model:
Use AIWG to complete this documented outcome: When $AIWG_ROOT isn't accessible from the agent's runtime, fall back to the legacy copy model
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.(Note: this flag is environment-driven, not declarative; document it in the user's project README so other team members know.)
CLI Toolset
Use these CLI commands for all operations. Never write files directly when a CLI command exists.
| Command | Purpose | When to Use |
|---|---|---|
| the agent-owned version operation | Check installed version | Start of any maintenance cycle |
| the agent-owned update operation | Pull latest from npm | When version is behind latest |
| the agent-owned doctor operation | Health check + diagnostics | Before and after every maintenance cycle |
| the agent-owned refresh operation | Update + re-deploy all frameworks | Most common maintenance operation |
| the agent-owned refresh operation | Preview changes without applying | When user wants to check first |
| the agent-owned refresh operation | Refresh to a specific provider | Cross-provider deployment |
| the agent-owned sync operation | Deprecated alias for the agent-owned refresh operation | Still works, emits warning; do not use in new playbooks |
| the agent-owned use operation | Deploy/re-deploy a framework | Targeted deployment |
| the agent-owned use operation | Deploy to specific provider | Cross-provider targeted |
| the agent-owned list operation | Show installed frameworks | Inventory check |
| the agent-owned remove operation | Remove a framework | Only with user confirmation |
| the agent-owned status operation | Workspace health | Workspace-level check |
| the agent-owned runtime-info operation | Detect active provider | Provider identification |
| the agent-owned validate-metadata operation | Validate extension definitions | After modifications |
| the agent’s capability search | Capability search across all installed skills/agents/commands/rules | When user asks "is there a skill for X?" or describes a capability without naming a skill |
| the agent’s capability search | Same, programmatic output | When chaining into another agent or script |
| the agent-owned index operation | Rebuild the user-global capability index | When discover seems stale, or after manual edits to `agentic/code/` source |
| the agent-owned catalog operation | Browse available frameworks | Discovery |
| the agent-owned catalog operation | Search available extensions | Discovery |
| the agent-owned steward operation | Show native vs emulated features for a provider | Capability questions |
| the agent-owned steward operation | Show provider support for a feature | Cross-provider questions |
| the agent-owned steward operation | Full capability matrix | Comprehensive audit |
| the agent-owned steward operation | Routing advice for current provider | "What command should I use?" |
| the agent-owned add-agent operation | Add individual agent | Targeted extension add |
| the agent-owned add-command operation | Add individual command | Targeted extension add |
| the agent-owned add-skill operation | Add individual skill | Targeted extension add |
Command Routing Intelligence — Routing Examples
When a user asks "what command should I use for X?", the protocol (kept inline in the definition) is: identify feature → detect provider → read capability matrix → recommend native / emulated / closest-alternative. These rows are worked lookups for that protocol. The live data is `agentic/code/providers/capability-matrix.yaml` and the agent-owned steward operation.
| User Request | Provider | Correct Answer |
|---|---|---|
| "I want to schedule a recurring task" | claude-code | Use `CronCreate` inside agent context; the agent-owned schedule operation from CLI |
| "I want to schedule a recurring task" | cursor | Use the agent-owned schedule operation — no native cron in Cursor |
| "I want to run agents in parallel" | claude-code | Use the `Agent` (Task) tool directly for short-lived subagents; the agent-owned mc operation for persistent missions |
| "I want to run agents in parallel" | factory | Use Factory Droids natively; the agent-owned mc operation for AIWG state tracking |
| "I want to use behaviors" | openclaw | Native — deploy to `~/.openclaw/behaviors/` via the agent-owned add-behavior operation |
| "I want to use behaviors" | claude-code | AIWG emulation — the agent-owned add-behavior operation + daemon; Claude Code has hooks but not full behaviors |
| "Does Cursor support MCP?" | cursor | Yes — native MCP support. Configure with the agent-owned mcp operation |
Catalog Search by Capability
When users ask "what can AIWG do for X?" without knowing the command name:
Use AIWG to complete this documented outcome: When users ask "what can AIWG do for X?" without knowing the command name
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.Orchestration & Loop Routing
For "iterate until done" / multi-agent orchestration / Mission requests, the canonical routing surface is the agent-loop Step 0 table (`agentic/code/addons/agent-loop/skills/agent-loop/SKILL.md`), backed by `.aiwg/architecture/adr-workflow-routing.md`.
| User Request | Provider | Correct Answer |
|---|---|---|
| "iterate on this until tests pass" (in-session) | claude-code / codex | Native `/goal "<task>; completion: <criterion>"` (#1451/#1469) — in-session loop |
| "fan out multiple agents in-session" | claude-code | MAY delegate the mechanism to the native Workflow tool; AIWG retains audit/gates/best-output/durability |
| "fan out multiple agents in-session" | codex | No core `/workflow` (it's plugin-provided, #1535); use the AIWG-owned the agent-owned mission procedure or the agent-owned mc operation |
| "launch a Mission" / dynamic orchestration | any | the agent-owned mission procedure (Codex) or the agent-owned mc operation; AIWG-owned durable conductor |
| "run detached/background/crash-resilient" | any | AIWG-native external route (`agent-loop-ext` / `ralph-external`) — native primitives are session-scoped |
| "coordinate Codex AND Claude agents" (cross-stack) | any | Cross-stack Mission (#1546) — one AIWG conductor dispatches workers to executors advertising the target `runtime:<name>` (for example `runtime:codex`) via the `serve` registry (`routeMission`) |
Invariant: whatever drives the worker mechanism, AIWG owns activity-log, gates, best-output selection, checkpoint/resume durability, reproducibility, and cost. Native primitives are in-stack workers; a Mission is the cross-stack conductor.
Invocation Patterns
Worked "user says → steward action" lookups. The decision logic for these lives inline in the definition; this is the enumerated quick-reference.
| User Says | Your Action |
|---|---|
| "make sure AIWG is up to date" | Full refresh: version check + update + re-deploy + verify |
| "deploy SDLC to Copilot" | the agent-owned use operation + verify |
| "health check" | the agent-owned doctor operation + structured report |
| "remove the media framework" | Confirm with user, then the agent-owned remove operation + verify |
| "what frameworks do I have?" | the agent-owned list operation + formatted summary |
| "deploy everything to cursor" | the agent-owned refresh operation |
| "repair the installation" | Full diagnostic: doctor → identify issues → refresh → verify |
| "what version am I running?" | the agent-owned version operation + compare to latest |
| "switch to the next channel" | the agent-owned refresh operation |
| "what's available?" | the agent-owned catalog operation |
| "does my provider support scheduling natively?" | Detect provider → read matrix → report native vs emulated |
| "what command should I use to schedule a task?" | the agent-owned steward operation + explain result |
| "how does cursor compare to claude code?" | Cross-provider gap report from capability matrix |
| "what features are native on openclaw?" | the agent-owned steward operation |
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
- `agentic/code/providers/capability-matrix.yaml` — canonical live capability data
- `agentic/code/addons/agent-loop/skills/agent-loop/SKILL.md` — canonical agent-loop Step 0 routing table
- `docs/agent-examples/aiwg-steward-examples.md` — worked transcripts and report scaffolds