jmagly/aiwg-utils-quickref

AIWG Core Utilities — Quick Reference

This is your always-loaded core directory for AIWG. It does not list every utility skill. Instead, it teaches the cross-cutting domains and gives you curated search phrases that map to aiwg discover lookups, plus a list of which framework-specific quickrefs are loaded.

How to use this quickref

Walk the action hierarchy in order. The agent always prefers a skill over a raw CLI invocation:

1. Priority 1 — Local skill or agent: check if a skill already in your context handles the need (kernel skills listed below, framework quickrefs, deployed agents like aiwg-steward / aiwg-finder). These cost nothing to invoke.
2. Priority 2 — Discovered skill: if no local match, pick a curated phrase from a capability domain (or paraphrase the user's words), run aiwg discover "<phrase>", surface the top match, and fetch its body with aiwg show <type> <name> — never find / ls / Read.
3. Priority 3 — Raw CLI: only when no skill exists at priorities 1 or 2, OR the command is on the discovery surface (aiwg discover, aiwg show, aiwg list, aiwg version, aiwg runtime-info), OR you are inside a skill that's calling the CLI as its step.

Do not enumerate skills from memory. AIWG ships hundreds of skills; you only see the kernel set in your context. See the cli-secondary rule for the full hierarchy and per-command pairings.

The canonical pipeline: discover → show

Most AIWG skills (~385 of 400) are not in your context and are not in <provider>/skills/ either — they stay at $AIWG_ROOT (no per-project copy by default, #1217). Two commands close the loop:

# 1. Find — returns ranked candidates with absolute paths
aiwg discover "<the user's need, paraphrased>"

# 2. Fetch — streams the SKILL.md body for the chosen candidate
aiwg show skill <name>          # or: agent | command | rule

discover and show are designed to compose. You should never need to navigate the filesystem to read AIWG content. That's the whole point of the CLI.

When the platform Skill tool errors

Most AIWG skills aren't kernel-listed, so the platform's Skill tool will reject them. This is expected behavior, not a bug. The fallback hierarchy:

1. aiwg show <type> <name> — primary fetch. Always works regardless of kernel status.
2. aiwg show <type> <name> --json — same fetch with { path, content } envelope, useful for forwarding to a sub-agent.
3. Read directly from $AIWG_ROOT/agentic/code/ — last-resort fallback. Only if the aiwg CLI itself is broken. The corpus at $AIWG_ROOT/agentic/code/frameworks/<name>/skills/<skill>/SKILL.md and $AIWG_ROOT/agentic/code/addons/<name>/skills/<skill>/SKILL.md is the canonical source — it is always present at the install root and survives any deploy-state corruption.

Forbidden after discover returns a path: running find, ls, Glob, or Read on a <provider>/skills/ directory. Those reflect the kernel-pivot deploy state, not the full surface. Use aiwg show.

This is mandated by the skill-discovery HIGH rule. Surface the top match (or top-3) to the user — the search is auditable.

Framework quickrefs (loaded if framework is installed)

If a user asks about a specific framework's surface, the corresponding quickref is your first stop. These are kernel-resident, so they're already in your context:

• sdlc-quickref — software-development-lifecycle workflows
• forensics-quickref — incident response and digital forensics
• research-quickref — research corpus and citation workflows
• media-curator-quickref — media archive management
• marketing-quickref — marketing operations and campaigns
• ops-quickref — operational infrastructure and runbooks
• security-engineering-quickref — applied security and crypto decisions
• knowledge-base-quickref — wiki and documentation workflows

If a quickref isn't loaded, the framework isn't installed in this project. Use aiwg list to confirm.

Addons & extensions (separate kernel quickref)

For everything outside the framework set — the ~270 skills across 28 addons (loops, voice, memory, color, testing, NLP, etc.) and 7 ops extensions (sys/net/sec/dev/it/stream/api-adapter) — load aiwg-language-map. It's also kernel-resident and acts as the orientation layer for the addon/extension surface, with curated discover phrases per capability domain.

aiwg-language-map  → addon capability domains + extension domains + cheat sheet

Self-maintenance kernel (always loaded)

These ops skills are kernel-resident — already in your context regardless of aiwg discover. They are your primary surface for self-maintenance. Each skill carries the priming the bare CLI cannot — pre-flight checks, dry-run preview, preservation logic, recovery patterns.

Skills first, CLI second. Each row below shows what the skill is for and the CLI command it calls under the hood. Invoke the skill — let it call the CLI. Direct CLI invocation skips the priming and is acceptable only on the discovery surface (Rule 2 of cli-secondary). See cli-secondary rule for the full policy.

| Skill (preferred) | Purpose | CLI it wraps | |---|---|---| | steward | Provider capability awareness + command routing | (no single CLI — orchestrates several) | | aiwg-doctor | Installation health check + remediation | aiwg doctor | | aiwg-refresh | Update CLI + redeploy frameworks with dry-run preview | aiwg refresh (alias: aiwg sync) | | aiwg-regenerate | Regenerate AIWG.md + AGENTS.md preserving team directives | aiwg regenerate | | aiwg-status | Workspace status dashboard | aiwg status | | aiwg-help | List CLI commands, args, examples | aiwg help | | aiwg-issue | Filing AIWG project issues (template, env, duplicate detection) | (no single CLI) | | aiwg-pr / aiwg-delivery-pr | AIWG-specific delivery PRs only (delivery-policy, no-attribution, CI gate); not generic repository PR work | (no single CLI) | | use | Deploy a framework or addon with validation gates | aiwg use <name> |

Pair with the aiwg-steward agent (always-deployed) for orchestrated repair: health check → refresh → re-doctor.

Discovery commands stay direct — aiwg discover, aiwg show, aiwg list, aiwg version, aiwg runtime-info, status/info subcommands. They have no paired "priming skill" because they ARE the priming entry points.

Status intent disambiguation

Route these phrases carefully:

| User intent | Use | |---|---| | Workspace inventory, installed frameworks, deployed provider files | aiwg-status / aiwg status | | Cross-framework project progress, "project-status", "where are we?", "what is next?" | aiwg discover "project status" → aiwg show skill project-status --first | | SDLC-specific project health or lifecycle gate status | aiwg discover "SDLC project health check" and prefer project-health-check or orchestrate-project when those rank above generic workspace inventory |

Do not answer project-status by running only aiwg status; that command reports workspace install/deployment inventory, not project progress.

When a user wants to file an AIWG product issue or open an AIWG delivery PR, route them through aiwg-issue / aiwg-pr (or the explicit alias aiwg-delivery-pr) first. These are AIWG-specific kernel skills and reference steward-prep-delivery where applicable.

For generic repository PR work, use ordinary repository PR tooling and templates. Examples: "open a PR for this repo" → normal git/Gitea/GitHub PR flow; "open an AIWG delivery PR for this change" → aiwg-pr.

aiwg-* skills are AIWG-specific product/workspace capabilities. Do not route general tracker processing through aiwg-issue: use issue-audit / audit-issues for backlog audits and address-issues for implementation loops.

When a user wants to start using issues for their own project, especially local file-system backed issues, route them to the issue-workflow-guide agent or discover/show it if it is not already loaded. The guide helps choose local vs external tracker backends, suggests a project-specific issue key prefix, and explains how local issues feed issue-audit and address-issues. Keep the distinction sharp: aiwg-issue files issues against the AIWG product; issue-workflow-guide helps users operate project issues.

Capability domains

| Domain | Covers | |---|---| | Workspace status & health | Workspace inventory, project status, doctor, version, runtime info | | Lookup & query | Capability discovery, KB query, artifact lookup, AIWG help | | Maintenance | Refresh, deploy, hooks, regenerate context files | | Mentions & traceability | @-mention validation, lint, wiring across files | | Activity & provenance | Activity log, provenance records | | Steward & policy | Provider capability awareness, delivery policy |

Curated discovery phrases

Workspace status & health

aiwg discover "aiwg status"                    # → aiwg-status
aiwg discover "aiwg doctor"                    # → aiwg-doctor
aiwg discover "version"                        # → version
aiwg discover "runtime info"                   # → runtime-info
aiwg discover "project status"                 # → project-status (cross-framework project progress; then `aiwg show skill project-status --first`)
aiwg discover "SDLC project health check"       # → project-health-check / orchestrate-project
aiwg discover "workspace health"               # → workspace-health

Lookup & query

aiwg discover "<capability phrase>"            # itself — discovery is the entry surface
aiwg discover "aiwg help"                      # → aiwg-help
aiwg discover "search aiwg knowledge base"     # → aiwg-kb
aiwg discover "artifact lookup"                # → artifact-lookup
aiwg discover "intake wizard"                  # → intake-wizard

Maintenance

aiwg discover "aiwg refresh"                   # → update / refresh
aiwg discover "deploy framework"               # → use
aiwg discover "regenerate claude.md"           # → aiwg-regenerate-claude
aiwg discover "regenerate AGENTS.md"           # → aiwg-regenerate-agents
aiwg discover "hook enable"                    # → hook-enable
aiwg discover "hook disable"                   # → hook-disable
aiwg discover "hook status"                    # → hook-status

Mentions & traceability

aiwg discover "mention validate"               # → mention-validate
aiwg discover "mention lint"                   # → mention-lint
aiwg discover "mention wire traceability"      # → mention-wire
aiwg discover "mention conventions"            # → mention-conventions
aiwg discover "mention report"                 # → mention-report

Activity & provenance

aiwg discover "activity log"                   # → activity-log
aiwg discover "create provenance record"       # → provenance-create
aiwg discover "auto provenance"                # → auto-provenance

Steward & policy

aiwg discover "aiwg steward"                   # → steward (agent + policy router)
aiwg discover "delivery policy"                # → delivery-policy rule (and related skills)
aiwg discover "start using local issues"       # → issue-workflow-guide
aiwg discover "choose issue tracking backend"  # → issue-workflow-guide
aiwg discover "project-local customization"     # → project-local quickstart / customization docs

Project-local extensions (pilot → promote)

AIWG supports authoring rules/skills/agents per-project under .aiwg/{extensions,addons,frameworks,plugins}/<name>/ — pilot here, promote upstream when mature.

aiwg new-bundle <name>                         # scaffold; auto-builds project graph
aiwg new-extension <name> --starter rule       # extension with a starter rule
aiwg new-bundle <name> --dry-run               # preview without writing
aiwg list --project-local                      # inventory + validation
aiwg doctor --project-local                    # health check (counts, drift, shadows)
aiwg use <name>                                # deploy a single project-local bundle
aiwg promote <name>                            # graduate to upstream (hash-verified copy)
aiwg promote <name> --dry-run                  # preview promotion

After scaffolding, the new bundle is immediately discoverable via aiwg discover "<name>". The framework graph and the project graph search by default; no --graph flag needed.

On-disk layout

agentic/code/        ← framework + addon source (NOT deployed; read-only reference)
.aiwg/               ← project artifacts (use cases, ADRs, test plans, etc.)
.claude/skills/      ← always-loaded "kernel" skills (this skill is here)
.claude/.aiwg/skills/ ← bulk AIWG skills (index-discoverable, not flat-listed)
.claude/agents/      ← AIWG agents (platform-native)
.claude/commands/    ← Generated command stubs for tab completion
.claude/rules/       ← AIWG rules

Same shape on every supported provider — see docs/discovery-and-kernel-skills.md for the full per-provider table.

When to query the index versus answer from kernel

| Situation | Action | |---|---| | User asks "what can AIWG do?" generically | Skim the framework quickrefs above; offer the top 3 most-relevant. | | User asks "find me a skill that does X" | aiwg discover "X" — return ranked candidates. | | User asks "is there a skill for Y?" and it's not in any quickref | aiwg discover "Y" — don't say "no" without checking. | | User asks about a specific framework's catalog | Direct them to that framework's quickref + invite a discover query. | | User asks for AIWG version / config / status | aiwg version, aiwg-status, aiwg doctor. |

When the curated phrases don't fit

aiwg discover "<your need, paraphrased>" --limit 5

If the top-3 results all score below ~0.20, the framework genuinely may not have a curated skill. Then improvise — but always check first.

Anti-patterns

• Do not enumerate skills from memory. Query the index.
• Do not deploy or modify framework source. Files under agentic/code/ are read-only references; project work happens in .aiwg/ and any src/ directories the project owns.
• Do not bypass the steward for cross-provider questions. If the user asks "does this work on Codex?" or "deploy to Cursor", invoke the AIWG Steward — it has the provider-capability matrix you don't.
• Do not fabricate skill names. If aiwg discover doesn't return a match, the skill genuinely may not exist — say so.

When you don't know what to do

aiwg help                          # full CLI surface
aiwg discover "<your need>"        # find the right skill
aiwg-kb "<question>"               # conceptual help

If still stuck, ask the user — but ask narrowly, with options drawn from the index, not blank.