# Routing Guidance

From the repo root (or any project that adopts the grok-toolkit managed block), this document is the primary local map for turning a request into the right starting skill(s) + optional refinement layers.

Grok skills are primarily **description-driven and auto-invoked**. You do not need to manually "route" the way a command-table system does. However, teams still benefit from explicit guidance on:

- Which skill to prefer for a given shape of work
- When to layer refinement skills (impeccable, critique, distill, service-vernacular, etc.)
- Workspace and setup conventions
- Support boundaries (what we claim as validated today)

## How Grok selects skills

1. The skill's `description` (and optional `when-to-use`) in its SKILL.md frontmatter is the main signal.
2. Explicit `/skill-name` or `/skills skill-name` forces inclusion.
3. AGENTS.md (including the grok-toolkit managed block) provides persistent project-level routing preferences and quality expectations.
4. You can (and should) combine skills in one session: a domain skill + a refinement skill + a built-in like the `review` or `implement` skill.

## Recommended starting skills by request shape

### Architecture, boundaries, cross-stack integration
- Primary: `architecture-integration`
- Often pair with: the owning backend/frontend skill for the concrete endpoints or components
- Refinement: `compass` (if goal framing or option comparison is needed first)

### Browser / web UI, interaction, design systems, browser-3D
- Primary: `frontend-web`
- Overlays (choose the narrowest that matches the dominant tech): nextjs, react-web, vue-nuxt, svelte-astro, angular, browser-3d-platform, threejs-react-three-fiber, babylon-playcanvas, shader-material-workflows, gltf-asset-pipeline
- Refinement (layer explicitly when the task includes polish, anti-slop review, or visual QA): `impeccable`, `critique`, `polish`, `typeset`, `colorize`, `adapt`

### Mobile apps
- Primary: `mobile-app`
- Overlays: react-native, flutter, swiftui, jetpack-compose
- Same refinement pattern as web

### Backend services (any family)
- Primary: the matching pack — `backend-node`, `backend-python`, `backend-jvm`, `backend-dotnet`, `backend-go`, `systems-rust`, `systems-c-cpp`, `functional-platform`, `php-ruby-platform`
- Pair with: `database-engineering`, `security-engineering`, `devops-platform`, `architecture-integration` as needed
- Refinement: `distill` (for complex logic or docs), `critique`

### Data, ML, analytics platforms
- Primary: `data-ml-platform`
- Pair with: `database-engineering`, `devops-platform`

### DevOps, platform, release, observability
- Primary: `devops-platform`
- Pair with: `release-engineering`, `qa-validation`, `security-engineering`

### Quality, validation, accessibility, performance
- Primary: `qa-validation`
- Strong companions: `impeccable` (for visual + interaction QA), built-in review skills

### Language, tone, product surface registers (UI copy, errors, docs, release notes, onboarding, support)
- Companion: `service-vernacular` (use alongside the primary implementation skill; it maintains the LANGUAGE.md dossier)

### Strategic framing, goal definition, option comparison before implementation
- `compass` (not a replacement for the primary domain skill; use it to bound the problem and choose the route)

## Refinement layer guidance

Invoke these **explicitly** when the request includes quality, polish, or anti-slop work. Do not make them the default first route for new feature work.

- `impeccable` — the broadest and deepest design quality system (includes many sub-concepts via its reference/ and the consolidated command model)
- `critique` — structured critique with personas, cognitive load, and heuristics scoring
- `distill`, `extract` — for turning complexity or raw material into clear, usable form
- `polish`, `typeset`, `colorize`, `adapt`, `bolder`, `delight`, `harden`, `normalize`, `onboard`, `optimize`, `overdrive`, `quieter`, `shape`, `teach-impeccable` — focused tools for specific quality dimensions

See the individual skill docs for exact triggers.

## Workspace & setup conventions (bundle-wide)

- New greenfield work started from the active repo or worktree defaults to `workspace/{project-name}-{domain}`.
- Prefer refining an existing project in place over direct `create` / `init` / `new` flows unless the request is explicitly greenfield-only.
- Full details: `reference/workspace-model.md` and `reference/project-setup-policy.md`.

## Support tiers (do not over-claim)

This bundle uses three tiers, declared in `reference/capability-matrix.json`:

- `validated` — flagship workflows with proof expectations. Currently limited to four (see `reference/workflow-catalog.md` and `reference/support-policy.md`).
- `guided` — current skill or overlay coverage with routing and reference support, but no blanket "supported now" public claim.
- `planned` — named future surface, not a present claim.

Only `validated` capabilities may be summarized as "supported now" in README or public materials.

## Failure modes to avoid

- Treating every routed skill as equally validated.
- Letting refinement layers (impeccable etc.) become the primary route instead of the implementation skill.
- Inventing new top-level packs when an overlay inside an existing pack would suffice (e.g. keep browser-3D inside `frontend-web`).
- Copying external DESIGN.md examples instead of extracting transferable patterns.

When in doubt, read the checklist in the root `AGENTS.md`, then the specific skill + the relevant reference/ docs.

This guidance is intentionally lighter than a command-table routing system because Grok's skill invocation model is description-driven and compositional. The value is in the curated knowledge and the explicit quality bar, not in bureaucratic routing.