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. CI 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. Without enforceable conventions, Claude reverts to its training distribution, an average of every codebase on the internet, bad code and all.
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
Six 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 block debt-accumulating patterns from being written in the first place: 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.
- Test-driven development
Specs become Playwright E2E tests before code is written. The first task in any feature is turning red tests green.
- Code review before every merge
The code-review-audit agent scans for security, performance, architecture, code smells, and antipatterns. Extendable with custom rules.
Load on demand
Three intercepts keep Claude's working surface lean. Rules sit dormant until you touch matching files. Symbol queries return one answer, not every match. Periodic audits prune 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.
Symbol search
Serena MCP gives Claude LSP-backed code intelligence. A query for createSession returns one canonical definition. A grep returns every line that mentions the name, and Claude reads each match to triage. Symbol search returns the answer, not the noise.
Knowledge audit
/gaia audit sweeps memory, the wiki, and autoloaded files for cross-store duplication, stale entries, and rules that drift over budget. Two stages: a report with sha256 drift checks, then a mechanical apply. Anything that changed since the report gets skipped.
State lives on disk
Long Claude sessions bloat. Context piles up each turn, memory accumulates between turns, every new session starts cold and burns tokens re-briefing. GAIA's four 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.
- · Grid shipped (a1b2c3d)
- · Detail pane wired
Synthesized from the conversation, not dumped. References stay as pointers to file lines, never inlined.
- · Grid shipped (a1b2c3d)
- · Detail pane wired
- · Mobile breakpoint @ 640px
Reads the handoff, prints 15 lines, archives it after commit. No transcript replay.
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
Five tiers so Claude stops relearning the codebase: wiki, hot cache, handoff snapshots, per-agent memory, cross-project 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.
Symbol-Aware Retrieval
Serena MCP gives Claude LSP-backed symbol search. A query returns the one definition, not every line that mentions the name.
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. A hot cache primes at session start; deeper questions trigger explicit retrieval.
Routing
Path-scoped rules auto-load only when Claude is editing 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-review audit, 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.
- Think Before Coding
- Surface assumptions. Ask when unclear.
- Simplicity First
- Write the minimum that works.
- Surgical Changes
- Touch only what is needed.
- Goal-Driven Execution
- Define done. Loop until verified.
- Always Use TDD
- Tests before code, always.
- Always Verify 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.
GAIA ships with the claude-obsidian integration wired up. The vault structure, the ingestion commands, and the maintenance skills are configured before you write your first page.
- Self-maintaining knowledge base
GAIA keeps the wiki current without you managing it. Commits are evaluated for wiki-worthy content and synced automatically. Consolidation passes catch redundancy and reversed decisions before they compound. Lint sweeps flag orphan pages, dead links, and drift. None of this is a feature you invoke. It is a discipline you get.
- 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 are kept siloed, and Claude does not cross-load between them unless a task genuinely spans more than one.
GAIA's continuous integration layer keeps the project healthy between sessions. The wiki stays in sync with the code. Dependencies stay current and tested. Security findings get patched. Stale branches don't pile up.
Claude handles the safe cases. Humans only see the ones it can't recover from.
- Auto-merge on green, auto-revert on failure
- Every workflow opens a labeled PR and auto-merges on green CI. If post-merge CI fails, the bot opens one revert PR. The hard cap is one revert attempt. A second failure escalates to a priority issue and the bot stops.
- Cost-capped by design
- GAIA CI runs against your Claude Code Pro/Max subscription or your Anthropic API key. A $5 hard ceiling per run caps API spend.
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
- 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 Deps updates 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 Deps resolves 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 Claude a little less effective and a little more expensive to run.
/gaia fitness audits the whole surface, grades it F to A+, and heals what it can, keeping your Claude integration lean and current as the project grows.
- Heals on a branch, waits for your commit
- Fixes land on a branch (a fresh chore/gaia-fitness branch if you’re on main, your current branch otherwise). You review the diff and the report, then commit when you’re satisfied.
- Won’t touch an unsafe tree
- Detached HEAD, or a rebase, merge, or cherry-pick in progress: it runs triage, prints the grades, and stops. No mutation on a state it can’t safely touch.
- Yours to extend
- Add project-specific graded check categories. /gaia fitness runs whatever you define alongside the built-in seven.
- Survives /update-gaia
- The check protocol three-way-merges on upgrade, so the checks you add to it carry forward.
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 straight to my GitHub with one prompt. Same body byte-for-byte, so I can fix them fast.
A professional frontend stack
Industry-standard tools, each a default in serious 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.