---
name: using-aw-skills
description: Session-start skill-first routing for the AW SDLC surface. Classify, route, read stage skill, then respond. Plan-first is mandatory.
trigger: Every session start and before every substantive response.
---

# Using AW Skills

Router for the AW SDLC. MANDATORY on every non-trivial request and re-applied on every scope shift.

## Hard Gate (MUST — in order, before any substantive response)

1. **Classify.** Answer out loud:
   - Approved plan exists at `.aw_docs/features/<slug>/`? (if no → likely plan-first)
   - Approved plan has complete Echo Direct HTML companions and remote links when docs mode is `dual` or `html`? Run `aw docs validate --feature <slug> --full` when a feature folder exists; if it fails -> `/aw:plan` repair before build.
   - Bug / alert / unclear failure? (→ `/aw:investigate`)
   - Change touches any plan-first trigger (see list below)? (→ `/aw:plan`, no exceptions)
   - Crosses >1 file AND >1 concern? (→ `/aw:plan`)
   - Qualifies as mechanical per whitelist below? (→ `/aw:build` allowed)
2. **Select route** via decision tree.
3. **Read the stage skill** (`<route>/SKILL.md`). Naming it is not reading it.
4. **Follow the skill's artifacts and contract** — not general-knowledge answers.
5. **Then respond.**

## Route Decision Tree

```
FIRST — Is the user asking you to create, improve, fix, score, or audit
  an agent, skill, command, rule, or eval? These are markdown files that
  live in .aw/.aw_registry/ and define how AI tools behave.
  ├── YES → /aw:adk
  │         The user wants you to write or edit the file itself.
  │         Example: "Create a command for database migration" means
  │         write a command markdown file — not perform an actual
  │         migration. The subject matter inside the artifact doesn't
  │         change the route.
  └── NO  → continue ↓

SECOND — Is the user asking to push registry artifacts (.aw_registry/
  or .aw_rules/) to the remote platform-docs registry?
  Signals: "push this agent/skill/rule to the registry", "publish my
  registry changes", "sync to platform-docs", "aw push", "aw push-rules"
  NOTE: Regular git push, code PRs, and deploys are NOT this route.
  ├── YES → /aw:publish
  │         Always dry-run first, then confirm before pushing.
  └── NO  → continue ↓

Approved plan for this exact work?
├── NO → Bug/alert/unclear failure?
│         ├── YES → /aw:investigate
│         └── NO  → /aw:plan   ← DEFAULT for anything new
└── YES → `aw docs validate --feature <slug> --full` passes and Echo Direct remote links are complete?
          ├── NO  → /aw:plan   ← repair human docs handoff
          └── YES → Implemented & needs test/review?
                    ├── YES → /aw:test or /aw:review
                    └── NO  → Deploy/release action?
                              ├── YES → Single release outcome? → /aw:deploy
                              │         Launch readiness/rollout/rollback? → /aw:ship
                              └── NO  → /aw:build
```

## Plan-First Triggers (exhaustive — ANY of these → `/aw:plan`)

- new/modified endpoints, services, schemas, migrations, workers, queues
- architecture or layer-boundary changes
- integrations (third-party APIs, external registries, upstream-sourced skills/agents)
- **router / routing rules / skill orchestration** changes
- **new/modified skills, agents, commands, rule-manifest entries** (exception: if the user wants to create or edit an agent, skill, command, rule, or eval — the files in `.aw/.aw_registry/` that define AI behavior — that's `/aw:adk`. The gate above catches this before you get here.)
- **`state.json` / `verification.md` / review-or-build contract** changes
- missing, stale, local-only, fallback-only (including legacy uncontrolled fallback status), blocked, or unpublished Echo Direct HTML companions or remote links for an existing AW artifact folder
- **cross-registry propagation** (mirroring into platform-core, GitHub→local, etc.)
- **model assignment changes across multiple agents**
- security-sensitive work (auth, tokens, permissions, tenant scoping)
- public API / interface contract changes
- config changes that alter runtime behavior or feature flags

## Mechanical-Change Whitelist (ONLY bypass of plan-first — ALL must hold)

- single file OR verbatim rename across files
- no new public contract, schema, state-field, workflow step, or registry entry
- no behavior change beyond a named bug fix
- no cross-registry propagation
- no new agent / skill / command / rule / reference

If ANY condition fails → plan-first. "Just a config tweak" / "just a skill edit" does NOT qualify.

## Compound-Request Guard

Per-turn edits that *individually* look mechanical but *cumulatively* form a feature. ANY signal → pause, route to `/aw:plan`, retro-capture under `.aw_docs/features/<slug>/`:

- second consecutive edit touches a new file or concern
- any edit adds a field to a state/schema/contract already edited this session
- any edit mirrors content from an external source
- user says "also do X" after an initial edit

## Pre-Edit Checklist (before the first `Edit`/`Write`/side-effecting `Bash` of a logical change)

- [ ] classification completed
- [ ] route selected and named
- [ ] stage skill read
- [ ] plan exists when plan-first applies
- [ ] all 5 mechanical conditions verified when whitelist is claimed
- [ ] compound-request signals checked against prior turns

## Re-Route Mid-Session

If a follow-up changes the nature of the work (e.g. review session becomes "patch this skill too"), **re-run the Hard Gate for the new scope**. Do not carry old route forward by inertia.

## Public Surface

`/aw:plan` · `/aw:build` (alias: `/aw:execute`) · `/aw:investigate` · `/aw:test` (alias: `/aw:verify`) · `/aw:review` · `/aw:deploy` · `/aw:ship` · `/aw:feature` · `/aw:adk` · `/aw:publish`

Honor explicit `/aw:<command>` the user types; do not reinterpret.

## Public Command Roles

| Command | Role | Primary artifacts |
|---|---|---|
| `/aw:plan` | Minimum correct planning | `prd.md`, `design.md`, `spec.md`, `tasks.md`, `state.json` |
| `/aw:build` | Implement approved work in reversible slices | `execution.md`, `state.json`, code/config |
| `/aw:investigate` | Reproduce, localize, confirm failure | `investigation.md`, `state.json` |
| `/aw:test` | Produce fresh QA evidence | `verification.md`, `state.json` |
| `/aw:review` | Findings, governance, readiness | `verification.md`, `state.json` |
| `/aw:deploy` | One release outcome for verified work | `release.md`, `state.json` |
| `/aw:ship` | Launch readiness, rollout safety, rollback, closeout | `release.md`, `state.json`, rollback notes |
| `/aw:feature` | Guided phase-by-phase SDLC (18 phases) | `state.json`, delegates to stage skills |
| `/aw:adk` | Author, score, fix, audit any registry artifact (command, agent, skill, rule, eval) | Registry artifacts, evals, `aw link` sync |
| `/aw:publish` | Push local artifacts to remote registry via PR (dry-run + confirm gate) | PR to platform-docs |

## Intent Routing (quick map)

| Intent signals | Route |
|---|---|
| PRD, design, spec, task breakdown, architecture, "build-ready" | `/aw:plan` |
| "implement", "apply", "fix", "continue" w/ approved scope | `/aw:build` |
| "reproduce", "why is X failing", alert, incident | `/aw:investigate` |
| "run tests", "produce evidence", QA proof | `/aw:test` |
| "review", "is this ready", PR checks, findings, readiness | `/aw:review` |
| "create PR", "deploy to staging/prod" (single outcome) | `/aw:deploy` |
| "is this ready to launch", rollout, rollback plan, release closeout | `/aw:ship` |
| "idea → production", "do the whole flow", "PR AND deploy" | `aw-yolo` (internal, not a public route — user should stage explicitly) |
| "create an agent/skill/command/rule/eval", "score my skill", "audit all agents", "ADK", "developer kit" | `/aw:adk` |
| "push this agent/skill/rule to the registry", "publish registry changes", "sync to platform-docs", "aw push" (NOT regular git push or code PRs) | `/aw:publish` |

## Scope Guardrails

- code request ≠ design/product work; design ≠ coding
- deploy does not reopen planning; review does not silently implement
- planning request already well-defined does not need a forced PRD
- do not produce substantive non-routing output before skill selection
- local repo AW routing is not skipped because a parent workspace has rules
- every first destructive tool call in a turn re-confirms the route

## Red Flags (stop and re-classify)

| Thought | Reality |
|---|---|
| "I can answer quickly first" | Quick answers still need skill context. |
| "Just exploring a little" | Exploration is work — load the skill first. |
| "Just a clarifying question" | Clarify after skill selection. |
| "I know the route" | Knowing ≠ loading. |
| "User said 'yes do it' — I can skip plan" | Approval for an edit ≠ approval to skip routing. |
| "It's just a skill/config tweak" | Skills/routers/agents/registries are plan-first. |
| "Each turn was small" | Compound guard triggers on accumulation. |
| "Planning now is late" | Retro-plan before the next edit. |
| "Entered under /aw:review so route is locked" | Scope shift → re-route. |
| "Just mirroring upstream" | Cross-registry propagation is plan-first. |

## Always-On Activation

Before any substantive response, this router must select the smallest correct AW skill stack and matching public route.

- explicit user command → honor and load the mapped stage skill first
- clear process need → load the needed internal process skill first
- otherwise choose the smallest correct AW primary stage skill by intent
- only after the required AW skills are selected, load deeper domain skills or ask clarifying questions

Do not start with generic implementation, review, or deploy advice before skill selection.

## The Rule

If there is even a small chance that an AW process skill, stage skill, or required domain skill applies, load it before responding.

## Skill Priority

1. process skills (`aw-brainstorm`, `aw-debug`, `aw-review`, `aw-prepare`)
2. primary stage skill (`aw-plan`, `aw-build`, `aw-test`, `aw-review`, `aw-deploy`, `aw-ship`)
3. domain skills (`platform-services/frontend/data/infra/sdet/review/design/mobile:*`) — delegated to `using-platform-skills`

## Cross-Cutting Engineering Skills

Load across stages when context applies: `incremental-implementation`, `context-engineering`, `api-and-interface-design`, `git-workflow-and-versioning`, `ci-cd-and-automation`, `deprecation-and-migration`, `documentation-and-adrs`, `frontend-ui-engineering`, `browser-testing-with-devtools`, `idea-refine`, `aw-adk`

## Cross-Cutting Deepening Skills

| Skill | Load when |
|---|---|
| `grill-with-docs` | Inside every `/aw:plan` as the Decision Confidence Gate. It classifies planning intake as `clear`, `confirm`, or `grill`: clear low-risk plans state assumptions and proceed, mostly-clear plans ask one confirmation question, and high-impact/fuzzy/hidden-decision/contradictory-docs plans show a numbered mode picker: `1` auto-answer recommended defaults, `2` quick grill, `3` deep grill. Deep grill runs the full one-question-at-a-time interview only when the user selects `3` or explicitly asks for it. |
| `to-prd` | Inside `/aw:plan` for product/full mode or when missing product assumptions must be frozen into `prd.md`; do not require it for already-clear technical plans. |
| `to-issues` | Inside `/aw:plan` before `tasks.md` when a PRD/spec needs vertical tracer-bullet slices; remote issue publishing requires an explicit user request. |
| `tdd` | Inside `/aw:build` as a companion to `tdd-workflow` when behavior-test, mocking, or tracer-bullet judgement needs more depth. |
| `diagnose` | Inside `/aw:investigate` when the failure is unclear, hard to reproduce, performance-related, or vulnerable to speculative patching. |
| `zoom-out` | Any stage when unfamiliar code needs a higher-level module map before local edits or review. |
| `improve-codebase-architecture` | Standalone or before planning/building architecture-heavy changes where shallow modules, bad seams, or poor testability are the core concern. |
| `grill-me` | Product, design, architecture, or decision review when the user explicitly wants to be questioned before committing to a path. |

## Internal Helpers (not public routes)

`aw:brainstorm` (discovery only) · `aw:finish` (legacy) · `aw:code-review` → alias of `/aw:review` · `aw:tdd` → alias of `/aw:build` · `aw-yolo` (internal power workflow for autonomous end-to-end orchestration — never advertise as public route)

## Rules Always Active

Relevant `.aw_rules/` and platform docs remain constraints regardless of route — never a reason to broaden scope.

## Harness Activation (one line per harness)

- Claude / hook-capable plugins → global plugin install
- Cursor native / headless → `~/.cursor/hooks.json`
- Cursor plugin → `hooks/hooks-cursor.json`
- Codex → global `~/.codex/` install (launcher fallback)
- Cursor repo without plugin → `.cursor/rules/aw-sdlc-router.mdc`

## References

- [context-loading-and-intake](../../references/context-loading-and-intake.md)
- [route-selection-patterns](../../references/route-selection-patterns.md)
- [domain-skill-loading](../../references/domain-skill-loading.md)
