Source: https://www.hype-stack.dev/docs/development/ai-overview

# AI Overview

Hype Stack is built to work well with AI coding assistants. The repo includes structured rules and skills that teach AI
agents how the codebase works, so they produce code that follows your conventions instead of guessing.

## What's included

### Rules for your assistant

When you scaffold a project, the CLI asks which assistants your team uses and writes the rules in each tool's native
format and location:

| Assistant          | Where rules land                                |
| ------------------ | ----------------------------------------------- |
| **Cursor**         | `.cursor/rules/*.mdc`                           |
| **T3 Code**        | `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/*.mdc` |
| **Claude Code**    | `.claude/rules/*.md`                            |
| **Codex**          | `AGENTS.md`                                     |
| **GitHub Copilot** | `.github/instructions/*.instructions.md`        |
| **OpenCode**       | `AGENTS.md`                                     |
| **Windsurf**       | `.windsurf/rules/*.md`                          |

Pick as many as you need. Nobody's team agrees on one editor, and each format lives in its own folder, so several sets
of rules sit in the same repo without conflicting. Pass `--editor cursor,claude,codex` (or repeat `-e`) to skip the
prompt. The rules are authored once as Cursor `.mdc` files and converted on install, so the guidance is identical
whichever tools you pick.

Each format carries the activation mode over, not just the text. An always-on rule stays always on, and a rule scoped to
`apps/backend/**` still only loads when the agent opens a backend file: `paths` frontmatter for Claude Code, `applyTo`
for Copilot, `trigger: glob` for Windsurf.

`AGENTS.md` works differently, because Codex and OpenCode read that one file and nothing else. Always-on rules are
copied into it in full, and scoped rules are listed as links, so they cost nothing until they apply. The links point at
`.cursor/rules` when Cursor is one of your picks, and at `.agents/rules` when it is not. Claude Code shares that file
through `CLAUDE.md` rather than getting a second copy in `.claude/rules`.

They cover every major area of the codebase:

| Area               | Rules                                                                                                                  |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| **Backend**        | Error handling, features structure, route validation, file uploads, deletion cascades, frontend URLs, general patterns |
| **Frontend**       | Feature organization, styling, theming, data fetching                                                                  |
| **Testing**        | Backend testing, frontend testing, workflow conventions                                                                |
| **Code style**     | Human voice, no em-dash, verification after changes                                                                    |
| **Infrastructure** | Permissions, registry, CLI testing, pack SDK types                                                                     |

When an AI agent works in the repo, it follows the same conventions you'd enforce in code review.

### Agent skills (`.agents/skills/`)

`create` installs a starter set of skills from [skills.sh](https://skills.sh) right after the scaffold, fetched fresh
each time rather than copied from the template, and records them in `skills-lock.json` by content hash. They land in
`.agents/skills/`, the shared location from the Agent Skills spec, so Codex, OpenCode, Copilot, and Cursor read it
as-is. Claude Code gets a `.claude/skills` link to the same folder. One copy, every agent, no drift. The set:

| Skill                             | What it does                                              |
| --------------------------------- | --------------------------------------------------------- |
| **find-skills**                   | Looks for an existing skill before improvising a workflow |
| **frontend-design**               | Produces polished, non-generic UI designs                 |
| **web-design-guidelines**         | Accessibility, focus states, and layout rules for the web |
| **vercel-react-best-practices**   | React rendering and data-loading performance patterns     |
| **grill-with-docs**               | Interrogates a plan against the docs before building it   |
| **improve-codebase-architecture** | Finds seams and refactors toward them                     |
| **teach**                         | Explains the change it made instead of just landing it    |
| **landing-page-design**           | Hero, above-the-fold, and CTA rules for landing pages     |
| **better-ui**                     | Border radius, optical alignment, and hit areas           |
| **emil-design-eng**               | Animation and component polish decisions                  |
| **no-ai-slop**                    | Edits copy so it stops reading like AI wrote it           |

Pass `--no-skills` to `create` to skip the install. See [Create a Project](/docs/cli#agent-skills) for how the step
behaves when a source is unreachable.

## MCP server

For agents that should scaffold and compose through the real CLI, install the [MCP server](/docs/cli/mcp). It exposes
eleven tools over MCP instead of asking the model to invent shell flags: catalog search, install planning, scaffolding,
pack and template installs, Docker and migrations, project inspection, env status, and two for writing your own packs.

## Why this matters

Without rules, AI tools generate generic code. With rules, they generate code that fits your architecture. The AI knows
to use `validate()` middleware instead of `ctx.req.json()`, throws `ApplicationError` instead of catching errors
locally, and organizes features in `<domain>/modules/<module>/` folders instead of flat structures.

Practical tips for day-to-day agent use live in [Working with AI](/docs/development/working-with-ai).

## A short feedback loop

An AI agent is only as good as how fast it can check its own work. Write code, typecheck, lint, run tests, read the
error, fix, repeat. The faster that loop, the more the agent gets right before handing back to you. Hype Stack runs the
whole loop on native-speed tooling:

| Tool                  | Job                | Why it's fast                                                                   |
| --------------------- | ------------------ | ------------------------------------------------------------------------------- |
| **TypeScript 6**      | Typecheck          | Current compiler on every app, run per project so Nx caches what did not change |
| **Vite 8** (Rolldown) | Dev server + build | Bundling runs on Rolldown, a Rust bundler built on the oxc engine               |
| **oxlint**            | Lint               | oxc's Rust linter, orders of magnitude faster than ESLint                       |
| **oxfmt**             | Format             | oxc's Rust formatter                                                            |
| **Vitest 5**          | Test               | One runner for backend, web, and (through `vitest-native`) React Native         |

The payoff: agents typecheck and lint in a fraction of the time, so they catch mistakes in the same turn instead of
shipping them to you. Faster tooling means tighter loops and fewer broken diffs.