/gaia-validate-framework

user-facing
Category:
Validation
Lifecycle phase:
Any
Arguments:
[--report-path]

What it does

/gaia-validate-framework scans the GAIA plugin installation for consistency, broken references, and missing components. It compares the on-disk file inventory against the shipped manifest, verifies that workflows, agents, skills, and knowledge entries all resolve, and checks that configuration resolution works correctly. The output is a severity-grouped findings report.

When to use it

  • After installing or upgrading the GAIA plugin, to verify the installation is complete.
  • When a command fails unexpectedly and you suspect a missing or broken framework file.
  • As part of a periodic health check on your GAIA setup.

Prerequisites

  • The GAIA plugin must be installed. The framework manifest file must be present.

How to invoke

/gaia-validate-framework

Optionally provide --report-path to write the report to a specific file.

What it does step by step

  1. File inventory Scans the plugin directory tree and compares file counts by type against the manifest.
  2. Workflow integrity Verifies every workflow YAML has its companion instruction and validation files.
  3. Agent integrity Checks that agent definition files are well-formed and reference real files.
  4. Manifest integrity Verifies the agent manifest matches the on-disk agent files.
  5. Config resolution Verifies the configuration resolver produces parseable output.
  6. Skill and knowledge index integrity Checks that skill index entries and knowledge fragments point to real files.
  7. Report Emits a PASS/FAIL overall verdict with itemized findings grouped by severity (CRITICAL first).

Inputs

InputSourceDescription
--report-pathCommand argument (optional)Where to write the report. Defaults to .gaia/artifacts/implementation-artifacts/framework-validation-{date}.md.

Outputs

OutputLocationDescription
Validation reportReport path (see above)Severity-grouped findings with suggested fixes.

Example session

> /gaia-validate-framework

Scanning plugin tree...
  127 files found (expected 125 from manifest).

Checking workflows... 32/32 OK.
Checking agents... 18/18 OK.
Checking config resolution... OK.
Checking skill index... 1 WARNING.
Checking knowledge index... OK.

Overall Status: PASS

| Severity | Section         | Finding                                  |
|----------|-----------------|------------------------------------------|
| WARNING  | Skill Index     | Line range [45,92] exceeds file bounds   |
| INFO     | File Inventory  | 2 extra files not in manifest            |

Report written to .gaia/artifacts/implementation-artifacts/framework-validation-2026-05-07.md

What to run next

  • Fix any CRITICAL findings before using other GAIA commands.
  • WARNING and INFO findings do not block usage but should be addressed when convenient.

Troubleshooting

"manifest.yaml missing"

The framework manifest could not be found. This usually means the GAIA plugin is not installed or was installed incorrectly. Reinstall the plugin.

Overall status is FAIL

One or more CRITICAL findings were detected. The report lists each finding with a suggested fix. Address them before relying on the affected commands.