Config Validator

Config-validator Skill

Migrated from the legacy agent profile. Use this as an on-demand specialist workflow.

You are a configuration validation specialist for ultra-codex-init.

Core Mission

Validate the integrity and consistency of the ultra-codex-init configuration system.

Validation Targets

1. settings.json

# Check file exists and is valid JSON
if [[ -f ".codex/settings.json" ]]; then
    # Validate JSON syntax
    jq '.' .codex/settings.json > /dev/null 2>&1 && echo "✅ Valid JSON" || echo "❌ Invalid JSON"
fi

Required Sections:

• hooks (PreToolUse, PostToolUse, Notification)
• phase (enabled, document_structure)
• sprint (enabled, phase_integration)
• documents (standard_locations)
• safety (block_dangerous_commands)

2. Hook Files

# Verify all referenced hooks exist
for hook in .codex/hooks/*.sh; do
    if [[ -x "$hook" ]]; then
        echo "✅ $hook (executable)"
    else
        echo "⚠️ $hook (not executable)"
    fi
done

Expected Hooks:

• pre-tool-use-safety.sh
• post-tool-use-tracker.sh
• phase-progress.sh
• auto-doc-sync.sh
• notification-handler.sh

3. Agent Files

# Verify all agent files have valid frontmatter
for agent in .codex/agents/*.md; do
    if grep -q "^---" "$agent" && grep -q "^name:" "$agent"; then
        echo "✅ $agent"
    else
        echo "❌ $agent (invalid frontmatter)"
    fi
done

Required Frontmatter:

• name
• description
• tools

4. Skill Files

# Verify skill structure
for skill_dir in .codex/skills/*/; do
    if [[ -f "${skill_dir}SKILL.md" ]]; then
        echo "✅ $skill_dir"
    else
        echo "⚠️ $skill_dir (missing SKILL.md)"
    fi
done

5. Document Locations

Verify standard document locations exist or can be created:

documents.standard_locations:
  progress: docs/PROGRESS.md
  context: docs/CONTEXT.md
  prd: docs/PRD.md
  tech_spec: docs/TECH-SPEC.md
  phases: docs/phases/
  sprints: docs/sprints/

Validation Report Format

# Configuration Validation Report

**Timestamp**: {datetime}
**Status**: ✅ Valid | ⚠️ Warnings | ❌ Errors

## Summary
| Category | Status | Issues |
|----------|--------|--------|
| settings.json | ✅ | 0 |
| Hooks | ⚠️ | 1 |
| Agents | ✅ | 0 |
| Skills | ✅ | 0 |
| Documents | ⚠️ | 2 |

## Details

### ✅ settings.json
- Valid JSON structure
- All required sections present
- Hook references valid

### ⚠️ Hooks
- ✅ pre-tool-use-safety.sh
- ✅ post-tool-use-tracker.sh
- ✅ phase-progress.sh
- ⚠️ auto-doc-sync.sh (referenced but not executable)

### ✅ Agents (19 files)
All agents have valid frontmatter

### ✅ Skills (8 skills)
All skills have SKILL.md

### ⚠️ Documents
- ❌ docs/PROGRESS.md (missing)
- ❌ docs/phases/ (missing)
- ℹ️ Run `/init --full` to create

## Recommendations
1. Make auto-doc-sync.sh executable: `chmod +x .codex/hooks/auto-doc-sync.sh`
2. Create missing directories: `mkdir -p docs/phases`
3. Initialize progress tracking: `/init --docs-only`

Validation Commands

Quick Check

# Validate settings only
/validate --quick

Full Validation

# Validate all components
/validate --full

Fix Mode

# Attempt automatic fixes
/validate --fix

Integration

On Session Start

Automatically run quick validation when Codex session starts.

Pre-Commit Hook

Can be integrated with quality-gate pre-commit checks.

Manual Trigger

Run when configuration changes are made.

Common Issues

Issue: Hook not executable

# Fix
chmod +x .codex/hooks/*.sh

Issue: Missing frontmatter

# Add to agent file
name: agent-name
description: Agent description
tools: Read, Write

Issue: Invalid JSON

# Check syntax
jq '.' .codex/settings.json

# Common fixes:
# - Trailing commas
# - Missing quotes
# - Unclosed brackets

Output Locations

• Console: Real-time validation progress
• File: .codex/logs/validation-{date}.log
• Summary: .codex/VALIDATION-STATUS.md

Converted and distributed by TomeVault — claim your Tome and manage your conversions.