xcaffold validate

Performs a dry-run validation of your .xcaf configuration. It checks for syntax errors, broken references, policy violations, and structural invariants without writing any files to the provider directories.

Usage

xcaffold validate [flags]

Flags

Note: Global scope (--global) is not yet fully implemented. Running xcaffold validate --global will return an error.

Behavior

Validation Tiers

1. Syntax and Schema: Checks that all .xcaf files are valid YAML and adhere to the latest schema version (e.g., version: "1.0").
2. Cross-References: Ensures that all resource links (e.g., an agent referencing a skill) resolve to valid resource IDs. Unresolved cross-references are reported as non-fatal warnings and do not cause a non-zero exit code.
3. Directory Integrity: Validates that all referenced supporting files (scripts, references, artifacts) exist on the filesystem. Checked separately for skill directories and hook directories.
4. Structural Checks: Runs invariant checks. The only structural check is: warning if an agent has the Bash tool enabled without a PreToolUse hook for command validation.
5. Policy Evaluation: Evaluates all project and global policies against the resources. This includes a simulated compilation to check for output-level policy violations. Policies are aggregated and reported as a single count.
6. Field Validation: If --target is specified, checks for missing required fields or unsupported field types for that provider.

Examples

Run a full validation of the project:

xcaffold validate

Validate field support for Claude:

xcaffold validate --target claude

Load variables from a custom file:

xcaffold validate --var-file ./custom.vars

Sample Output

xcaffold-project  ·  validating 14 resources

  ✓  syntax and schema (22 files)
  ✓  skill directories
  ✓  hook directories
  ✓  policies (2 checked)

✓  Validation passed.  14 .xcaf files checked.

Exit Codes