gaia

GAIA

Claude is raw power. GAIA is order and focus.

A serious harness for Claude Code. It keeps Claude-shipped code production-grade as your team scales. The React frontend is handled. You build the rest of your app on top. Claude can't commit code that fails lint, type checks or the unit tests it affects, can't skip those checks with --no-verify, and can't merge a source change until the Code Audit Team clears it.

Quick Start · What Breaks Claude · Trust · Token Economics · Tech Debt · Tech Stack · Claude Workflow · Feedback · History

Who It's For

• Engineering teams whose AI output is outpacing their review process
• Engineering leads standardizing how Claude works across the org
• Teams adopting AI-assisted development who want production-grade defaults from the first commit
• Individuals building apps with Claude

Quick Start

npx create-gaia@latest my-app

One command. GAIA handles the rest, then /gaia-init finishes the last-mile setup (below).

[!NOTE] Start projects with npx create-gaia@latest my-app rather than cloning or forking. The CLI sets up your project for you, strips the GAIA branding and release tooling, etc. A clone leaves all of that in place and pointed at the wrong repo.

Requirements: Node.js >= 22.22.0 (nvm recommended). macOS or Linux; on Windows, run inside WSL2 (the hooks and CLI need bash and POSIX file paths, and native Windows isn't exercised in CI).

Learn more about GAIA →

Then: /gaia-init

GAIA ships clean. /gaia-init does the last-mile setup:

• Configures the project. Title, package name, docs title, CODEOWNERS, localized site titles.
• Installs dependencies. Bootstraps pnpm via corepack, runs pnpm install.
• Configures i18n. Prompts for your language set, scaffolds the matching language files, updates the component and Storybook wiring.
• Installs the React Doctor skill. React Doctor, first, so it is ready in the same session.

When it finishes, it continues straight into /setup-gaia in the same Claude session, which installs Playwright CLI and the typescript-lsp plugin, provisions the GitHub repository (for a repo admin, branch protection with the GAIA-Audit required check and squash-only merges) and asks the per-machine sandbox and statusline choices; it ends without a restart, suggesting /clear to start your first feature with a fresh context. /setup-gaia runs only the steps a clone still owes, so any developer can re-run it safely.

You end up with a clean app shell and a fully-configured Claude workflow.

Repository layout

GAIA is a monorepo. The harness (.claude/, .gaia/, .githooks/, .github/, wiki/) lives at the repo root and the React app lives in frontend/. Launch Claude at the root for harness workflows (audits, merges, releases, /gaia-* commands); a launch inside frontend/ supports frontend work through commit. Upgrading a 1.6.1 project? Open Claude Code in the 1.6.1 project and ask it to fetch, verify and follow the bundled 2.0.0 migration note, as the first line of the v2.0.0 release describes.

What Breaks Claude on Real Projects

Most setups treat Claude as a tool you hold: bolt a CLAUDE.md onto the root and hope the model figures out the rest. GAIA treats Claude as an engineer you manage. That shift exposes three failure modes the bolt-on approach papers over.

Trust. You can't manage an engineer you can't predict. Without enforceable conventions, Claude reverts to its training distribution: an average of every codebase on the internet, bad code and all. GAIA's codebase is what you actually want Claude matching, and the rules make sure it can't ship code that doesn't.

Token economics. Context bloat isn't just CLAUDE.md sprawl. Instructions get dropped into global memory, forgotten, and accumulate into redundancies and conflicts that compound every session. GAIA keeps token usage minimal by design.

Compounding tech debt. Dependencies fall behind, vulnerabilities sit unpatched, dead code piles up, and the wiki drifts from the code while you ship features. Left alone, the project rots in the background. GAIA runs maintenance continuously so it doesn't.

How GAIA Makes Claude Trustworthy

• Coding principles, enforced. GAIA keeps four coding principles current models still need, all its own: Simplicity First, Surgical Changes, Always Use Test Driven Development, and Always Verify Your Work.
• Best practices baked in, debt blocked at the source. Rules encode the conventions directly instead of hoping Claude infers them from whatever's already in the repo, and block debt-accumulating patterns from being written at all: untyped exports, untested components, hardcoded strings, a11y gaps.
• Consistently clean code. Over 1,200 lint rules, strict TypeScript, Prettier, and Knip enforce style, correctness, and dead-code detection across every file Claude touches, and every commit message follows Conventional Commits.
• Bundled skills wired in for write-time quality. typescript, react-code, tailwind, tdd, playwright-cli, skeleton-loaders, eslint-fixes, and a11y-fixes load on demand when Claude edits matching files or a tool reports a fixable violation. The tdd skill drives a red-green-refactor loop tailored for Vitest, Storybook story tests, and MSW.
• Specs that turn into tests. /gaia-spec authors an immutable SPEC artifact through Socratic discovery. The SPEC's UATs are written before any source code, and /gaia-plan's orchestrator renders them as red-state Playwright e2e specs automatically before the first implementation phase; the owning phase turns each one green. The implementer's first job is turning red green. The PO writes acceptance criteria in plain language, and the test harness is generated from them.
• Code Audit Team before every merge. Each member of the Code Audit Team owns the files its roster entry claims, and a diff dispatches only the members whose files it touches. The frontend member reviews for security (XSS, SSRF, IDOR, secret exposure, timing attacks, vulnerable dependencies), performance, architecture, and defects that lint and types miss, with line-level rule specialists, react-doctor, and knip running alongside it and extension files in frontend/.claude/agents/code-audit-frontend/ injecting library-specific rules at runtime. A proven-small change since a member's last full review can route to a cheaper light review. Findings are tiered Critical, Major, and Minor, and the self-running audit loop fixes them round by round in a subagent, so your session holds only a short report. The merge blocks until every dispatched member clears. Runs locally.
• Quality gate before commit. Typecheck, lint, unit and Storybook tests, Playwright E2E, a dev-server smoke test, and the production build must all pass. Not "mostly clean." Actually clean.
• Guardrails against destructive moves. A read guard hook and the sandbox's filesystem deny list block reads of .env files, key and certificate files, credential-named files (TypeScript source excepted), and anything under a secrets/ directory. A tool allow list scopes Bash and Edit surfaces. Pre-tool-use hooks reject dangerous commands at the source: destructive git on main, eslint.config edits, rm -rf, and writes to env/secret files. All in .claude/hooks/, wired through .claude/settings.json, whose permissions deny list also blocks edits to pnpm-lock.yaml.

How GAIA Keeps Claude Token-Efficient

• Rules scoped to activate only when needed. Claude loads the ones that match what it's editing. Nothing else.
• Tiers of memory, each scoped and self-maintaining. Claude stops relearning the codebase every session:
  • Wiki (repo): architecture, modules, decisions, flows, concepts as focused, linked Markdown committed to git and shared across the team. Claude opens the one page it needs ("How does dark mode wire through?") instead of preloading the whole manual. A statusline nudge flags when the wiki trails HEAD; a SPEC's outcomes promote into wiki pages before its PR merges; a consolidate pass catches redundancy and contradiction as SPECs accumulate. /gaia-wiki runs sync, consolidate, and lint on demand, each step's heavy reading in a fresh subagent context, and lands them as one commit. Open wiki/ in Obsidian for graph view, backlinks, and search. GAIA owns log.md and index.md: gaia wiki log-prepend writes log.md and /gaia-wiki maintains index.md.
  • Agent memory (per-agent): what a subagent you give persistent memory keeps between runs, inventoried by /gaia-cleanse with the rest.
  • User memory (global): your preferences, style, and defaults, carried across projects.
• Periodic knowledge cleanse. /gaia-cleanse sweeps memory and autoloaded files (CLAUDE.md, rules) for duplication with the wiki, contradictions with it, and stale content before they start costing tokens.
• Task orchestration in clean subagent contexts. /gaia-plan spawns each phase as a focused subagent with only the context it needs. No accumulated history, no stale assumptions. Spec discovery (/gaia-spec) runs in its own context too, separate from implementation; the immutable SPEC artifact is the handoff, not accumulated context.

How GAIA Keeps Tech Debt From Compounding

The quality gate keeps each commit clean and Knip keeps dead code out (see Tech Stack). The rest runs over the life of the project:

• /update-deps. Dependency remediation: discovers every outdated package and open security advisory, audits version overrides, applies codemods and breaking-change migrations for major bumps, resolves conflicts between simultaneous upgrades, fixes advisories by the least invasive method that clears them (or dismisses the alert when you accept one), then runs the quality gate before reporting done. Dependabot only supplies the alerts.
• /update-gaia. Pulls the latest GAIA release into the project without clobbering your work: a three-way merge per file (your version, the release baseline, the new release) governed by ownership classes in .gaia/manifest.json, prompting only where your changes and GAIA's collide. Both updates surface as passive statusline indicators at session start.
• /gaia-debt. The pre-merge audit may discover tech-debt outside the scope of what it's reviewing. Rather than let it slip, GAIA logs it as a tracked issue, and /gaia-debt works through that backlog one item at a time, most important first. A statusline indicator shows how much is waiting.

Tech Stack

Every piece of GAIA's tech stack is pre-configured and wired into the Claude layer.

• Over 1,200 lint rules via ESLint, Stylelint, and commitlint that catch the patterns Claude drifts into first: complexity creep, architectural shortcuts, mismatched filenames, broken CSS, inconsistent commit messages. Prettier formats every file, and Knip detects unused files, exports, and dependencies.
• Pre-commit hooks (native git hooks + lint-staged): typecheck, lint, and test before CI.
• Testing via Vitest running Storybook stories as component tests in headless Chromium (CSF Next .test() behaviors, with an axe check on every story; see Stories as Tests), Playwright for E2E, and Chromatic for visual regression, with MSW seed data shared across them.
• Storybook with React Router + i18n + dark mode + MSW integration.
• Internationalization via remix-i18next with working examples.
• A shadcn/ui component layer vendored into your project: the components are yours, token-themed, and axe-checked in light and dark.
• Forms with validation composed from those components using Conform + Zod.
• Dark mode end-to-end. Cookie, CSS, and Storybook all in sync.
• API mocking with Mock Service Worker and msw/data: working handlers for tests and Storybook.
• Toast notifications with remix-toast and a shadcn/ui toast built on Base UI.
• Built with React Router 8, Tailwind, shadcn/ui components, and lucide-react icons.

GAIA also wires agentic-design patterns into the project structure rather than the prompt, so they run the same way every session and every model variant: stop hooks, a blocking pre-merge audit, multi-agent review, spec-driven development, a committed knowledge base, a filesystem deny list, and more. The features page walks through all twelve, grouped as workflow control, context engineering, and tooling and safety.

Claude Workflow

GAIA ships a complete, opinionated Claude Code workflow. Everything is wired in .claude/ and visible in the repo.

Commands

Rules, Hooks, Skills

• Path-scoped rules cover TypeScript, React, Tailwind, testing, i18n, accessibility, and state management. They live in frontend/.claude/rules/ (harness rules are in .claude/rules/); ask Claude about any of them.
• Hooks guard the quality gate and keep the wiki fresh. They live in .claude/hooks/.
• Bundled skills (typescript, react-code, tailwind, tdd, playwright-cli, skeleton-loaders, eslint-fixes, a11y-fixes) autoload for matching tasks. Scaffolding skills (new-component, new-hook, new-route, new-service) fire on natural-language asks.

Working in a GAIA Project

GAIA is driven through Claude. Ask for what you need.

Build things:

• "Add a new route for settings." → triggers /new-route, applies routing + i18n + test rules.
• "Add German as a supported language." → Claude walks the i18n setup.
• "Add a zip-code field to the address form with validation." → Claude uses the form patterns from the wiki.

Ask about the codebase:

• "How does dark mode wire through?" → Claude fetches the wiki page on demand.
• "What state patterns do we use?" → one-page lookup, no context bloat.
• "Explain the form-submit flow." → direct answer from the wiki.

Test: Ask Claude to run, add, or debug tests. Vitest, Storybook + Chromatic, and Playwright are wired up.

Deploy: GAIA isn't prescriptive about hosting. Ask Claude to set up deployment for your target (Vercel, Cloudflare, Fly, AWS, a bare Node host, a Docker container, anywhere React Router runs). Claude wires up the build, environment variables, and any CI/CD you need.

Extend: Rules, hooks, skills, and commands live in .claude/. Ask Claude to add, modify, or explain any of them.

Feedback

Questions, ideas, and reports of what worked and what didn't go to the Feedback discussions. It is GAIA's one community channel. When a GAIA workflow misfires, /gaia-forensics turns it into a filing-ready bug report.

History

The GAIA Flash Framework was Flash's most popular framework. Its killer feature was automation. It collapsed repetitive Flash plumbing into a few declarative patterns so engineers could focus on the product, and was used on over 100,000 sites at every major digital agency worldwide.

GAIA carries that automation philosophy into the AI-native era. Where the original automated Flash boilerplate, the GAIA harness automates the Claude workflow (conventions, rules, hooks, gates, wiki) so you can ship features end-to-end without wiring the scaffolding every time.