Why This Exists

The problem with "just wing it"

Out of the box, every AI assistant starts from scratch on every session. It doesn't know your naming conventions, your accessibility requirements, your branching strategy, or which patterns your team has decided to avoid. So it guesses — and the guesses are sometimes good, often generic, and occasionally harmful.

Multiply that across a team of engineers using Copilot, Cursor, Claude Code, or Gemini CLI, and you get a different implicit rulebook for every developer. Code review becomes a game of catching AI-generated patterns that don't match your standards. Onboarding stays slow because the AI doesn't reinforce your conventions — it introduces its own.

The fix: explicit, versioned governance

The Awesome GitHub control plane makes AI behaviour predictable by shipping structured governance files alongside your code. Instead of hoping the model infers your standards from examples, you write them down once in machine-readable formats and let every tool consume them.

Instructions tell the model what standards to follow. Agents narrow the scope to a specific role. Hooks catch violations before they land in a PR. Workflows orchestrate multi-step tasks that would otherwise require manual coordination. Prompts give the team reusable starting points that skip the "how do I ask for this?" overhead.

Why not just use a linter?

Linters are mechanical — they check syntax and pattern matches. AI governance is semantic — it shapes reasoning before code is written. A linter can't tell the model "preferwp_safe_redirect() over wp_redirect() and always check the return value." An instruction can. They're complementary, not competing.

The hooks in this catalogue bridge the two: they use the linter as a guardrail but give the AI enough context to avoid the violation in the first place, rather than just flagging it after the fact.

Awesome GitHub vs. awesome lists

The "Awesome" naming is intentional but ironic. Traditional awesome lists are curated links to third-party resources. This project is different: everything here lives in the repository, is versioned with the codebase, and is immediately usable — not a reading list.

The catalogue is the repository. The instructions are deployed. The agents are running. The workflows are wired into CI. If it's in this catalogue, it's production.

Designed for every AI tool

The assets here are deliberately tool-agnostic. Instructions follow the.github/instructions/ convention that GitHub Copilot reads natively. Agents are specified in a portable YAML-like format that Claude Code, Gemini CLI, and custom runners all understand. Skills have SKILL.md entrypoints that any model can follow.

We maintain canonical configurations for Claude (ai/Claude.md), Gemini (ai/Gemini.md), and GitHub Actions runners (ai/RUNNERS.md) so you can adopt whichever tool fits the task.

A living system

The control plane is not documentation you write once and forget. It evolves with the team. When a new pattern emerges in code review, someone writes an instruction. When a workflow saves three hours of manual work, it goes in the catalogue. When an agent proves its value, it gets a version bump and a changelog entry.

The goal is a feedback loop: better governance → better AI output → faster development → time to improve governance. That's the flywheel.