/gaia-fitness

/gaia-fitness checks the health of your project’s Claude integration and repairs what it safely can. One invocation, no flags: calling /gaia-fitness is the statement of intent to be fit. It runs three phases in sequence: triage, heal, verify, and reports a per-category and overall grade from F up to A+.

It checks the Claude surface (hooks, skill/command/agent frontmatter, rule files, CLAUDE.md, .claude/settings.json, GAIA itself, and wiki structure), not your application code. For app code review before merge, use the code-review-audit agent. For knowledge-store bloat, duplication, and contradictions, use /gaia-audit.

When to use it

Run /gaia-fitness after editing under .claude/, such as modifying or adding new commands, skills, agents, hooks, etc.

You can also call it after pulling a GAIA update with /update-gaia if you made any customizations to GAIA, or periodically as a routine check.

How to invoke

/gaia-fitness

No flags. No arguments.

What gets checked

Triage dispatches seven category checks in parallel. Each produces a set of findings, each finding tagged with a severity (info, warning, error):

Category	What it checks
Hook integrity	`.claude/hooks/*` scripts and their wiring in `settings.json`.
Skill / command / agent frontmatter	`.claude/skills/`, `.claude/commands/`, `.claude/agents/**` frontmatter completeness and validity.
Rule hygiene	`.claude/rules/*.md` scope, `paths:` frontmatter, size.
`CLAUDE.md` hygiene	Root and nested `CLAUDE.md` files: size, structure, duplication.
Settings hygiene	`.claude/settings.json`: permission pairs, redundancy, malformed entries.
GAIA-install fitness	Whether the GAIA install is intact and consistent.
Wiki fitness	Wiki structure: state file, manifest, orphans, dead repo-relative paths.

The checks are recall-oriented and over-flag on purpose. Before grading, /gaia-fitness adjudicates each finding against the actual repo and drops the false positives (an unfamiliar-but-valid hook event, a permission pair that only looks redundant, and so on). What survives gets graded.

Grading

Each category gets a letter grade. A+ means zero findings. From there the grade keys off the worst severity present, then the count at that severity:

All findings at info: stays in the A band (A, then A- as the count grows).
A warning is the worst severity: B band.
An error is the worst severity: C band, dropping through D as errors pile up.
A structurally broken category: F.

The overall grade is the floor of the seven category grades. The integration is only as fit as its weakest surface.

An A should be considered a clean bill of health.

The three phases

Triage. Run the seven checks, adjudicate the findings, compute the grades. Each surviving finding is then classified as fixable (a mechanical edit a fixer can apply confidently without product context: a missing frontmatter field, a bad path, a .gitignore line) or unfixable (needs product context or invasive restructuring: splitting an oversized CLAUDE.md, rewriting a rule’s scope, reworking hook logic).

Heal. Fixable findings get repaired by lane-aware fixers running in parallel, one lane per surface area (.claude/ surface and CLAUDE.md; .claude/settings.json; .gitignore; .gaia/manifest.json). Healing runs inside a bounded loop, three cycles by default. After each cycle the affected checks re-run; if a finding survives a fix attempt unchanged, the loop stops chasing it and marks it unresolved. A fixer that judges a repair too invasive to apply without product context leaves it alone and surfaces it in the report with a recommended approach. Nothing is ever committed. The working tree is left for you to review.

Verify. After each heal cycle the affected category checks re-run and the grades recompute. If the overall grade reaches A+, the loop exits clean.

Branch behavior

Where the fixes land depends on which branch you are on when you run it:

On the default branch (main), with at least one fixable finding: /gaia-fitness creates and switches to a new branch named chore/gaia-fitness-<timestamp> before applying anything, so main stays untouched.
On any other branch, with at least one fixable finding: it heals in place on your current branch.
No fixable findings (including a clean A+ run): no branch is created, HEAD stays put, nothing changes.

Unsafe repo state

Before any heal-phase change, /gaia-fitness checks whether the repo is safe to mutate. If HEAD is detached, or a rebase, merge, cherry-pick, or bisect is in progress, it switches to a triage-only path: it runs the checks, prints the grades, tells you heal was skipped and why, gives the resolution steps (for example, git rebase --abort or git checkout <branch>), and stops. No working-tree change, no branch.

After the run

/gaia-fitness renders the result as a deterministic width-aware ASCII card, produced by gaia fitness render-card. The card is pasted directly into the chat reply as a fenced code block.

The card has three sections:

Header row. The command name (/gaia-fitness), the overall grade, and the OVERALL label right-aligned.
Category rows. One row per category, alphabetically sorted. Each row shows the category name, a compact severity note (for example, 2 errors, 1 warning), and the category grade. A clean category shows no note.
FINDINGS block (omitted on a clean run). When there are adjudicated findings, a FINDINGS section follows the category rows. Findings are grouped by category, and each entry shows the severity tag ([error], [warning], or [info]), the file path, and the remediation text, word-wrapped to fit the terminal width. Unresolved or unfixable findings appear here with their recommended approach.

On a clean run (zero adjudicated findings, overall A+), the FINDINGS block is omitted. The card shows only the header and category rows, all graded A+.

The card self-sizes: the box width is clamped to the longest content line, with a hard ceiling of 120 columns and a floor set by the widest category name. Remediation text wraps to fit.

Then, depending on what happened:

A branch was created. Review with git diff main, commit when satisfied, or discard with git checkout main && git branch -D chore/gaia-fitness-<timestamp>.
Healed in place. Review with git diff, commit when satisfied, or discard with git checkout -- ..
Triage-only. Re-run /gaia-fitness after you have resolved the unsafe state.
Zero findings. Nothing to do.

/gaia-fitness checks the Claude integration surface. For knowledge-store duplication, contradictions, and autoload budgets, use /gaia-audit. For wiki-internal redundancy and broken wikilinks, use /gaia-wiki. For your application code on a branch before merge, use the code-review-audit agent.