Validate afi-config codex and governance configuration for structural consistency, broken references, and schema alignment, without changing protocol semantics. This skill performs read-only validation and produces a human-readable report of issues found, without attempting automatic fixes.
Use this skill when you need to validate the structural integrity and consistency of afi-config's codex, governance artifacts, and schema definitions.
This skill ensures:
npm run validate, npm test).afi-codex.json metadata is accurate (reflects actual capabilities)This skill is primarily used by config-keeper-droid and can be called when:
Before using this skill, the droid must:
Read:
afi-config/AGENTS.mdafi-config/codex/governance/droids/AFI_DROID_CHARTER.v0.1.md)afi-config/codex/governance/droids/AFI_DROID_PLAYBOOK.v0.1.md)Confirm:
afi-config reponode --version, npm --version)npm install if needed)Understand afi-config structure:
Understand validation commands:
npm run validate — Run schema validation testsnpm test — Run all tests (Vitest)npm run typecheck — Validate TypeScript typesnpm run build — Compile TypeScriptIf any requirement is unclear or appears to violate AGENTS.md or Charter, STOP and ask for human clarification.
The caller should provide, in natural language or structured form:
full — Validate all codex, schemas, and governance filescodex — Validate only codex filesschemas — Validate only schema filesgovernance — Validate only governance artifactsmetadata — Validate only .afi-codex.jsonsyntax — JSON/YAML syntax validationreferences — File reference validationschema-compliance — JSON Schema compliance validationtests — Run validation commands (npm run validate, npm test)all — Run all checksOptional:
schemas/pipeline.schema.json)summary, detailed, json)If no inputs are provided, use conservative defaults:
fullallsummaryWhen this skill is invoked, follow this sequence:
In your own words, summarize:
This summary should be short and precise, so humans can quickly confirm the intent.
Navigate to afi-config/ and list files based on scope:
Full validation (default):
find codex -type f \( -name "*.md" -o -name "*.json" -o -name "*.yaml" \)find schemas -type f -name "*.json"find codex/governance -type f -name "*.md".afi-codex.jsonCodex only:
find codex -type f \( -name "*.md" -o -name "*.json" -o -name "*.yaml" \)Schemas only:
find schemas -type f -name "*.json"Governance only:
find codex/governance -type f -name "*.md"Metadata only:
.afi-codex.jsonFiltered:
Based on the checks input, run the following:
For each JSON file:
# Validate JSON syntax
node -e "JSON.parse(require('fs').readFileSync('path/to/file.json', 'utf8'))"
For each YAML file (if any):
# Validate YAML syntax (requires js-yaml or similar)
# Or use a simple parser check
Capture:
For each codex file and governance doc:
Extract file references:
[text](path/to/file.md)"path": "schemas/pipeline.schema.json"Validate each reference:
test -f path/to/fileCapture:
For each schema file in schemas/:
Parse as JSON (already done in Check 1)
Validate against JSON Schema meta-schema:
$schema field is presenttype, properties, etc.Check schema structure:
$id is present and unique$ref references are resolvableCapture:
Execute validation commands defined in package.json:
npm run validate:
cd afi-config
npm run validate
Capture:
npm test:
cd afi-config
npm test
Capture:
npm run typecheck (optional):
cd afi-config
npm run typecheck
Capture:
.afi-codex.json metadataRead .afi-codex.json and validate:
Required fields:
codexVersion (should be "2.0.0")module.name (should be "afi-config")module.role (should be "config-schema-library")provides (array of capabilities)consumers (array of consuming repos)entrypoints (array of entry points)Consistency checks:
configSchemas → schemas/ directory existsdroidCharter → codex/governance/droids/AFI_DROID_CHARTER.v0.1.md existsschemas/ → directory existstemplates/ → directory existscodex/ → directory existsafi-core, afi-reactor, afi-skills, afi-ops, afi-token, etc.Capture:
Organize findings by severity:
ERRORS (must fix):
npm run validate, npm test).afi-codex.jsonWARNINGS (should fix):
.afi-codex.json metadataINFO (nice to have):
Generate a concise, human-readable report:
Summary format (default):
## Codex Validation Report
**Scope**: Full validation (codex/, schemas/, governance/, metadata)
**Timestamp**: 2025-11-28 14:30:00 UTC
**Files Scanned**:
- Codex files: 4 (codex/governance/droids/*.md, codex/governance/README.md)
- Schema files: 7 (schemas/*.json, schemas/usignal/v1/*.json)
- Governance files: 3 (codex/governance/droids/*.md)
- Metadata: 1 (.afi-codex.json)
**Validation Results**:
- ✅ JSON/YAML syntax: PASS (12/12 files valid)
- ✅ File references: PASS (0 broken references)
- ✅ Schema compliance: PASS (7/7 schemas valid)
- ✅ `npm run validate`: PASS (20/20 tests)
- ✅ `npm test`: PASS (20/20 tests)
- ✅ `.afi-codex.json`: PASS (all required fields present)
**Issues Found**: None
**Overall Status**: ✅ CLEAN
Detailed format (if requested):
Include full list of files scanned, detailed error messages, and suggested fixes.
JSON format (if requested):
{
"timestamp": "2025-11-28T14:30:00Z",
"scope": "full",
"files_scanned": {
"codex": 4,
"schemas": 7,
"governance": 3,
"metadata": 1
},
"checks": {
"syntax": { "status": "PASS", "errors": [] },
"references": { "status": "PASS", "errors": [] },
"schema_compliance": { "status": "PASS", "errors": [] },
"validation_commands": { "status": "PASS", "errors": [] },
"metadata": { "status": "PASS", "errors": [] }
},
"overall_status": "CLEAN"
}
If validation reveals critical issues, escalate:
Schema breaking changes:
Governance inconsistencies:
Systemic validation failures:
Unclear requirements:
When using this skill, you MUST NOT:
Modify any files:
.afi-codex.jsonModify governance artifacts:
Change protocol semantics:
Touch other repos:
If a request forces you towards any of the above, STOP and escalate.
At the end of a successful validate-codex-config operation, produce a summary that includes:
Validation Scope:
Files Scanned:
Validation Results:
Issues Found:
Overall Status:
Next Steps:
Request:
"Validate the entire afi-config codex to make sure there are no broken references or invalid schemas."
Inputs:
fullallsummaryImplementation:
npm run validate and npm test → All pass.afi-codex.json → All required fields present## Codex Validation Report
**Scope**: Full validation (codex/, schemas/, governance/, metadata)
**Files Scanned**: 15 total
- Codex files: 4
- Schema files: 7
- Governance files: 3
- Metadata: 1
**Validation Results**:
- ✅ JSON/YAML syntax: PASS (15/15 files valid)
- ✅ File references: PASS (0 broken references)
- ✅ Schema compliance: PASS (7/7 schemas valid)
- ✅ `npm run validate`: PASS (20/20 tests)
- ✅ `npm test`: PASS (20/20 tests)
- ✅ `.afi-codex.json`: PASS (all required fields present)
**Issues Found**: None
**Overall Status**: ✅ CLEAN
**Next Steps**: No action required. All validation checks passed.
Request:
"Check that all schemas in
schemas/are valid JSON Schema Draft 2020-12."
Inputs:
schemasschema-compliancesummaryImplementation:
schemas/ for JSON Schema Draft 2020-12 compliance."## Schema Validation Report
**Scope**: Schema validation only (schemas/)
**Files Scanned**: 7 schemas
- blueprint.schema.json
- character.schema.json
- pipeline.schema.json
- plugin-manifest.schema.json
- repo-metadata.schema.json
- vault.schema.json
- usignal/v1/*.json
**Validation Results**:
- ✅ Schema compliance: PASS (7/7 schemas valid JSON Schema Draft 2020-12)
**Issues Found**: None
**Overall Status**: ✅ CLEAN
**Next Steps**: No action required. All schemas are valid.
Request:
"Validate codex and report any broken file references."
Inputs:
codexreferencesdetailedImplementation:
codex/governance/README.md line 15: [Charter](droids/AFI_DROID_CHARTER.v0.2.md) → File does not exist## Codex Validation Report
**Scope**: Codex validation (codex/)
**Files Scanned**: 4 codex files
**Validation Results**:
- ❌ File references: FAIL (1 broken reference)
**Issues Found**:
### ERRORS (1)
1. **Broken file reference** in `codex/governance/README.md` (line 15):
- Reference: `[Charter](droids/AFI_DROID_CHARTER.v0.2.md)`
- Expected file: `codex/governance/droids/AFI_DROID_CHARTER.v0.2.md`
- Status: File does not exist
- **Suggested fix**: Change to `[Charter](droids/AFI_DROID_CHARTER.v0.1.md)` (actual file)
**Overall Status**: ❌ ERRORS
**Next Steps**:
1. Fix broken reference in `codex/governance/README.md` line 15
2. Re-run validation to confirm fix
Use this skill when:
This skill is read-only validation only:
This skill can be integrated into CI/CD pipelines:
# .github/workflows/validate-config.yml