# grok-toolkit

Curated high-signal skills, design quality systems, and team conventions for Grok.

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](#license) [![Grok Plugin](https://img.shields.io/badge/Grok-plugin-5b5bd6.svg)](https://github.com/xai-org/grok) [![Companion to Grok TUI](https://img.shields.io/badge/companion-Grok%20TUI-2d7a46.svg)]()

`grok-toolkit` is a project-local and user-installable bundle of expert skills and operating conventions for Grok (the xAI agent TUI and environment). It gives teams and individuals a stronger local operating layer: domain-specific expertise, anti-slop discipline, refinement workflows, and explicit support boundaries — without pretending to be a second control plane.

Install it once as a Grok plugin and the skills become available everywhere. Add the managed block to a project's `AGENTS.md` and the whole team inherits the conventions.

## What this bundle is

A practical collection of 45+ reusable skills plus a governance and quality layer, built for Grok's native plugin, skill, and project-rules systems.

| Layer | What it supplies |
| --- | --- |
| Grok (base) | Orchestration, tools, subagents, MCP servers, project rules (AGENTS.md), plugin system |
| grok-toolkit | Domain skill packs, refinement layers (impeccable, critique, distill...), service language companion, workspace + quality conventions, and a visible managed block for team alignment |

The split is simple: Grok stays general-purpose and powerful. `grok-toolkit` makes it domain-aware, quality-obsessed, and easier for teams to explain and adopt.

## Who this is for

- Individual developers who want stronger, more consistent results from Grok on real product work.
- Teams that want shared conventions, a visible "we use these standards" marker in AGENTS.md, and a high bar for UI, architecture, language, and delivery.
- Anyone who has felt the pain of slop, inconsistent product language, or "it works but the design is off" and wants a systematic way to raise the floor.

## Quick start

### 1. Install as a Grok plugin (recommended)

```sh
# From GitHub (once published)
grok plugin install HanTechnology/grok-toolkit

# During development / local testing
grok plugin install /path/to/grok-toolkit --trust
```

Then verify:

```sh
grok inspect
/skills
```

You should see skills such as `impeccable`, `critique`, `frontend-web`, `architecture-integration`, `service-vernacular`, and many domain packs.

### 2. Adopt the conventions in a project (via CLI)

From the project root:

```sh
npx grok-toolkit init
```

This creates the necessary `.grok/` structure and safely inserts a **GROK-TOOLKIT MANAGED BLOCK** into your `AGENTS.md` (project content outside the markers is never touched).

See `INSTALL.md` for more CLI options (`doctor`, `validate`).

### 3. Start working

- For UI work: start with `frontend-web` (or `mobile-app`), then layer `/impeccable` or `critique` explicitly when you need polish or anti-slop review.
- For architecture / cross-stack: `architecture-integration` + the relevant backend/frontend skill.
- For product language consistency: `service-vernacular`.
- When you want stronger goal framing before coding: `compass`.

See `reference/routing-guidance.md` for the current recommended starting points and boundaries.

## What it adds

- 45+ top-level skills covering web/mobile, multiple backend families, data/ML, devops, security, QA, architecture, and refinement.
- The Impeccable v3.1.1 design refinement layer (vendored with its Apache 2.0 license) for systematic anti-slop UI and docs work.
- A living reference layer: quality gates, design anti-slop rules, workspace conventions, support boundaries, and a curated DESIGN.md catalog.
- `service-vernacular`: a companion for consistent, repo-backed product language across UI, docs, errors, release notes, etc.
- Explicit "validated / guided / planned" tiers so you know what is battle-tested versus aspirational.

## What this is not

- An official xAI product or distribution.
- A replacement for Grok's own capabilities (tools, subagents, built-in review/implement/design skills, MCP, etc.).
- A second runtime or mandatory control plane. The skills are opt-in and description-driven.

## Validated surface (current)

The initial validated workflows are intentionally narrow:

- `frontend-product-delivery`
- `backend-service-delivery`
- `cloud-release-readiness`
- `ai-data-product-delivery`

Broader skill coverage exists and is documented as `guided`. Only the four above are summarized as "supported now" in public-facing materials until the manifest promotes more.

See `reference/support-policy.md`, `reference/workflow-catalog.md`, and `reference/capability-matrix.json`.

## Workspace convention

New greenfield work started from a repo or worktree defaults to `workspace/{project-name}-{domain}`. Existing projects stay in place.

See `reference/workspace-model.md` and `reference/project-setup-policy.md`.

## Acknowledgements

This toolkit carries forward and adapts excellent work from the `oh-my-openagent-toolkit` project (https://github.com/HanTechnology/oh-my-openagent-toolkit), which itself built on `oh-my-openagent` and the Impeccable design system (v3.1.1, Apache 2.0).

The migration to Grok preserves the spirit and most of the substance while making everything a native Grok citizen (plugins, project rules, skill descriptions, subagent-friendly workflows).

## License

MIT for the toolkit glue, documentation, and original skills.

Impeccable v3.1.1 and its supporting files are carried under their original Apache 2.0 license (see `skills/impeccable/LICENSE`).

## Contributing

Issues and PRs welcome. Keep the tone humble, explicit about boundaries, and focused on raising the quality floor for agent-assisted engineering work.

## Support the project

Optional funding links (do not create paid support obligations or change validation boundaries):

(Stripe links will be added here after publication, modeled on the source.)

---

**Status**: Early migration in progress. Skills and reference docs are being ported and adapted. The plugin install path and core governance layer are the current focus.

See [MIGRATION-PLAN.md](MIGRATION-PLAN.md) for the detailed roadmap.