# AGENTS Guide — grok-toolkit

This repo provides curated skills and conventions for Grok. It is intentionally thin as a control plane and thick as a quality and knowledge layer.

From the repo root, read in this order when you need to understand routing, boundaries, or workspace rules.

## What each document owns

1. `reference/routing-guidance.md` — the authoritative local map for request shape → recommended starting skill(s), when to layer refinement packs (impeccable, critique, distill, etc.), and helper fit.
2. `reference/support-policy.md` + `reference/workflow-catalog.md` + `reference/capability-matrix.json` — support tier definitions and the current validated workflow inventory. Never widen public claims beyond what the manifest declares.
3. `reference/quality-gates.md` and `reference/design-anti-slop.md` — the non-negotiable quality bar and the shared ban list for sloppy output.
4. `reference/workspace-model.md` and `reference/project-setup-policy.md` — workspace placement and the strong preference for refining existing projects before greenfield creation.
5. `reference/grok-native-behavior.md` (or equivalent) — notes on what Grok provides natively (tools, subagents, MCP, project rules, plugin system) versus what this bundle layers on top.

## 5-step operational checklist (for this repo and for projects that adopt the managed block)

1. Read `reference/routing-guidance.md` first to classify the work and choose the primary skill.
2. Check `reference/support-policy.md`, `reference/workflow-catalog.md`, and `reference/capability-matrix.json` before making any "supported" or "validated" claim.
3. For any UI, visual, or documentation-heavy task, re-read `reference/design-anti-slop.md` and `reference/quality-gates.md`.
4. When language consistency or product surface registers matter, bring in `service-vernacular`.
5. Before writing new greenfield code or docs, check whether an existing project should be refined instead (see `reference/project-setup-policy.md`).

## Design intent checkpoint (non-negotiable here)

For greenfield UI work or when adopting this toolkit mid-project:

- Inspect project-local design sources first: root `DESIGN.md`, `.impeccable.md`, tokens, themes, component primitives, representative screens, existing usage of `impeccable` or `critique`.
- If those sources are missing, conflicting, or too vague to choose typography, color, spacing, motion, hierarchy, or component affordance, ask **one focused Question** to define the missing intent instead of guessing.
- Keep the question concrete: target audience, primary use case, brand personality/tone, reference products, accessibility/platform constraints, and whether the project should create or update a local `DESIGN.md`.

Once the answer exists, route through the primary skill (`frontend-web`, `mobile-app`, `architecture-integration`, etc.) and only then layer `impeccable`, `critique`, or other refinement skills on purpose.

This checkpoint does not create a new route. It protects quality.

## Workspace reminder

New greenfield outputs default to `workspace/{project-name}-{domain}`. Existing work stays in place. See `reference/workspace-model.md` for the full convention and rationale.

## Separate axes, kept distinct

- Request shape / bucket (from routing-guidance)
- Primary skill (the expert pack chosen for the core work)
- Refinement layer (impeccable, critique, distill, service-vernacular, etc. — invoked explicitly when the task calls for it)
- Support tier (`validated` / `guided` / `planned` — authority lives in capability-matrix + support-policy)

Do not collapse these.

If a request needs concrete routing or skill selection, go to `reference/routing-guidance.md`. If it needs a public support statement, check the support and workflow references first.

This file stays short on purpose. The real operating system lives in `reference/`.