The Discipline of GAIA
GAIA's discipline is structural. Claude works inside it.
Hooks intercept the tool call. Rules shape the writing. Gates hold the commit. Audits guard the merge. Maintenance keeps the project current.
Discipline is leverage. Each layer turns Claude's capability into work that ships.
Trustworthy by default
You can't trust output you can't predict. On its own, AI's output isn't.
GAIA's coding style is what you actually want Claude matching. With GAIA, Claude writes code that follows best practices on day one, and can't ship code that doesn't.
- Coding principles
Four coding principles encoded as rules and loaded automatically. Every session starts from the same disciplined baseline. See the principles below.
- Guardrails against technical debt
Rules steer Claude away from debt-accumulating patterns as it writes, and the commit gate blocks the ones that slip through. Untyped objects, untested components, hardcoded strings, a11y gaps.
- Bundled skills wired in for write-time quality
Scoped skills load on demand when Claude edits matching files. They apply project conventions without re-deriving them each session.
- Verified before it’s built
Before any code, GAIA turns adversarial agents on its own spec and plan. They try to refute each decision and dependency against the real repo, so a flawed assumption surfaces at planning time, not in review.
- Test-driven development
Specs become Playwright E2E tests before code is written. The first task in any feature is turning red tests green, and the red has to be real. A test that can’t fail proves nothing.
- Code review before every merge
In Claude Code, the Code Audit Team reviews every pull request for security, performance, architecture, code smells, and antipatterns. A small change can get a lighter review, and any change not proven small gets the full one. Real problems it finds beyond the PR’s scope aren’t dropped or used to block your merge. The audit files them as tracked, deduplicated issues, and
/gaia-debtdrains them one reviewed PR at a time.
A React app slows down one wasted render at a time. From the outside the app just feels slow. From the inside, you are guessing which component, and why. The profiler shows you every render and ranks none of them.
/gaia-react-perf drives the interaction you point it at and captures real per-render attribution. The capture runs on the same React instrumentation that powers react-scan, wired into Claude, not a browser overlay. It surfaces two failure modes: a memoized component that re-renders anyway because a prop or context value it depends on is a new object or callback every render, and any component whose render crosses a 16 ms frame budget, memo or not. It skips the cheap re-renders that push you toward memoizing everything, then names the structural fix for what is left.
Ranked findings
11 renders · 11 memo-defeated
unstable props: columns, onRowSelect
react-doctor · jsx-no-new-object-as-prop
6 renders · 6 memo-defeated
unstable context: DashboardContext
react-doctor · jsx-no-constructed-context-values
8 renders
Diagnosis
Two findings cross the 16 ms frame budget, and the fixes differ. Give OrdersTable stable props so its memo holds, then cut the per-render work in RevenueChart, which has no memo at all.
Measure-only: GAIA diagnoses, Claude applies the fix you approve, then re-runs /gaia-react-perf to confirm the finding drops to zero.
- Measure-only by design
- It emits a ranked diagnosis and stops. Claude applies the fix you approve in conversation, never an automatic rewrite, so the call on what changes stays yours.
- The raw capture stays on disk
- A bippy harness records every render to disk, then a deterministic CLI reduces tens of thousands of tokens of raw capture to the small ranked summary the model reads. The raw dump never enters context.
- Two signals, not noise
- It flags a memoized component that re-renders anyway when its props or context arrive as a new object or callback every render, and any component whose render crosses the frame budget, memo or not. A cheap re-render with real changes is left alone, so nothing pushes you toward memoizing everything.
- Ranked by what users feel
- Findings lead with the memoized components that re-render anyway, then rank by wasted cost: how often each one re-renders times how long a render takes. A barely perceptible render-count win never outranks a memo that keeps re-rendering an expensive subtree on every parent update.
Load on demand
Three intercepts keep Claude's working surface lean. Rules sit dormant until you touch matching files. Bulk reads go to sub-agents, and only the conclusion comes back. A cleanse prunes what accumulates.
Scoped rules
Each rule declares the file patterns it cares about via paths: frontmatter. The Tailwind rule loads when you edit a .tsx or .css file. The Storybook rule loads only on .stories.tsx files. The rest stay dormant until matching files are touched.
Lean main thread
The main thread decides and synthesizes. It never reads in bulk. Read-heavy, low-yield work fans out to sub-agents in fresh contexts. Each writes its full result to a file and returns a short summary, so the session making the call carries the conclusion, not the file dumps.
Knowledge cleanse
/gaia-cleanse sweeps memory and autoloaded files against the wiki for duplication, stale entries, and rules over budget. It catches contradictions, not just copies. One review gate stands between the findings and your files, and GAIA flags when a sweep is worth running.
State lives on disk
Long sessions accumulate state. Context grows each turn, memory carries between turns, and every new session starts cold. That is how any conversation works. GAIA's workflow commands write durable artifacts to disk, then read them on demand. State persists. The conversation stays small.
Browse cards in a grid. Selection opens a detail pane.
- ✓3 cols at viewport ≥ 1024px
- ✓Enter on focus opens detail
- ✓Esc closes the detail pane
One question at a time. Discovery state lives in a draft cache, then becomes an immutable artifact. The next step reads the file, not the chat.
Planning runs in a spawned subagent. Your main session sees file paths, not the plan. Execution starts cold from KICKOFF.md.
Agentic design
GAIA wires design patterns into hooks, agents, rules, commands, and wiki conventions, so they run the same way every session, every agent, every model variant. Not emergent behavior. Not prompts you repeat. The discipline lives in the project.
Planning
Plans are durable artifacts requiring user approval, produced before any work begins: task graph, execution playbook, kickoff prompt.
Memory & Knowledge Base
Layers so Claude stops relearning the codebase: the wiki, specs and plans in the notebook, run state for paused work, and Claude’s own memory.
Resource-Aware Optimization
Mechanical work runs on Sonnet or Haiku. Heavier reasoning routes to Opus when the cost is merited.
Session Isolation
Sub-agents run in fresh contexts so shared state can't corrupt their work. Git-worktree branches add filesystem-level isolation when needed.
Lean Main Thread
The main thread decides and synthesizes. Read-heavy work fans out to sub-agents, which write their full result to a file and return a short summary.
Skill Activation
Skills load by trigger, not by default. They sit on disk without burning a token until the matching phrase appears.
Knowledge Retrieval
Claude pulls facts from the wiki on demand. The wiki stays on disk until a task needs it; each question triggers explicit retrieval.
Routing
Path-scoped rules auto-load only when Claude reads or edits matching files. Conditional hooks route commands to the right gate.
Human-in-the-Loop
Six checkpoints between Claude's intent and impact. Quality gate, Code Audit Team branch checkpoint, plan approval, phase gates, destructive-command block, merge confirmation.
Guardrails & Safety
Defense in depth. Secrets blocked from read or write. Debt patterns rejected at the source. The audit covers XSS, SSRF, IDOR, and dep vulns.
Parallelization
Independent work runs concurrently. Audit subagents fan out from a single dispatch. Plan phases run in parallel where dependencies allow.
Tool Use
A curated React-specific tool surface. Linting, types, unit and E2E tests, visual regression, mocking, the GitHub CLI, the wiki.
- Simplicity First
- Write the minimum that works.
- Surgical Changes
- Touch only what is needed.
- Always Use TDD
- Tests before code, always.
- Always Verify Your Work
- Pass the gates before reporting done.
A second brain for Claude
With an Obsidian wiki, Claude understands what you are actually building, not just the code in front of it. Product features, user flows, design rationale, business decisions, architecture, and dependencies all live as focused markdown pages committed to git, not CLAUDE.md, not chat history, not machine-local memory.
The wiki is an Obsidian vault committed to git. GAIA's tooling keeps it organized as your project grows: a statusline nudge says when it needs attention, and one /gaia-wiki command brings it current.
- A knowledge base that stays current
Claude writes to the wiki as work lands. When planned work merges, what it settled goes into the wiki in the same pull request. A quick fix or a decision changed along the way can still slip past, and the statusline flags the drift. /gaia-wiki catches the wiki up, consolidates redundancy and reversed decisions before they compound, and fixes orphan pages and dead links, all in one pull request.
- Token costs don’t balloon
Token costs do not balloon as the wiki gets richer. Claude only reads the specific information a task needs, so a project with 1,000 pages of context is no more expensive to work in than one with 100.
- Why Obsidian?
A local markdown vault means the project’s knowledge persists, compounds, and stays yours, not held in a vendor’s database or trapped in chat history.
- Domain isolation is mandatory
Technical, branding, and business knowledge stay siloed. GAIA keeps the domains separate, loading across them only when a task genuinely spans more than one.
All Dependabot and Renovate do is open a PR with a version bump, leaving the actual upgrade work for a human to figure out.
GAIA makes sure Claude does that work. Codemods, source migrations, conflict resolution, all resolved before the PR opens. What you review is a finished change, not half-done work.
- · read changelog
- · update call sites
- · run codemods
- · fix breakages
- Security advisories resolved first
/update-depslists open security advisories first and resolves each one you accept: a refresh within range, a bump of the package that pulls it in, or a security-floor override.- Codemods and migrations applied
- When a new dependency version requires a codemod or breaking-change migration, GAIA makes sure Claude handles it. The PR includes the bump and the migration together.
- Call sites updated when APIs change
- When the new version moves or renames public API surface,
/update-depsupdates the call sites. Grep-replace-with-context work, automated. - Conflicts resolved before the PR opens
- When two simultaneous upgrades touch the same code path,
/update-depsresolves the overlap before opening the PR. No conflicting PRs that fight at merge. - Iterates until the upgrade lands clean
- Runs the upgrade, runs the suite, sees what breaks, fixes it, and runs the suite again. The PR doesn't open until the upgrade is working.
As a project grows, its Claude integration drifts. New hooks, new rules, edited skills, a CLAUDE.md that creeps past its budget, settings that collect redundant permissions. Every bit of that drift makes your Claude integration a little less effective and a little more expensive to run.
/gaia-fitness lints the whole surface, grades it F to A+, and heals what it can, keeping your Claude integration lean and current as the project grows.
Findings
CLAUDE.md: A
frontmatter: B+
Fitness healed 1 finding. Publish, open a draft PR only, or keep it for review.
- Graded by rules, not by mood
- A fixed rule catalog grades the files your project owns, so the same tree earns the same grade every run. An advisory judgment pass reads descriptions, trigger overlap, and rule scope, and never moves the grade.
- Heals per file, on your say
- Each fix is shown as a diff and applied only on a yes, one file at a time. Then you choose: publish through the merge gate, open a draft PR only, or keep the changes for review.
- Your files and GAIA’s stay apart
- Findings in files GAIA ships are listed on their own and fixed by /update-gaia, never edited in place.
- Won’t touch an unsafe tree
- Detached HEAD, or a rebase, merge, or cherry-pick in progress: it grades, prints the card, and stops. No mutation on a state it can’t safely touch.
- Exceptions carry a reason
- A finding you accept on purpose is suppressed in .claude/gaia-fitness.json by rule id and path, with the reason written down beside it.
Bugs happen
GAIA is open source, written by one developer (so far). Contributors and sponsors welcome.
/gaia-forensics turns “this didn’t work” into a complete report: redacted, classified, ready to file. User-config issues return the fix inline. Probable GAIA bugs file to the GAIA repository once you confirm, with the same redacted body as the local report, so they can be fixed fast.
A professional
frontend stack
Industry-standard tools, each a default in production React projects. Refined over years. The same tools humans rely on to ship reliable code. Claude works with them, just faster.
Package management runs on pnpm. Faster installs. Smaller node_modules. Stricter dependency resolution that blocks phantom imports and the easiest path for npm supply-chain attacks.
Discipline you can install.
You direct. Claude implements.
GAIA enforces.