/component-validate

Validate CODITECT components against schema requirements, naming conventions, and quality standards.

Syntax

/component-validate [path] [options]

Options

Option	Description	Example
--type <type>	Validate only specific type	--type agent
--strict	Fail on warnings (not just errors)	--strict
--fix	Auto-fix simple issues	--fix
--schema	Validate frontmatter schema	--schema
--links	Check for broken links	--links
--orphans	Find orphaned components	--orphans
--duplicates	Check for duplicate IDs	--duplicates
--format <fmt>	Output format: text, json, sarif	--format json
--output <file>	Write results to file	--output report.json
--verbose	Show detailed validation	--verbose

Validation Checks

Schema Validation

Check	Description	Severity
frontmatter_required	YAML frontmatter exists	ERROR
title_required	Title field present	ERROR
component_type_valid	Valid component_type	ERROR
version_format	Semantic version format	WARNING
status_valid	Status in allowed values	WARNING
summary_length	Summary under 200 chars	INFO

Naming Conventions

Check	Description	Severity
lowercase_filename	Filename is lowercase	ERROR
kebab_case	Uses kebab-case	WARNING
no_special_chars	No special characters	ERROR
skill_structure	Skills use SKILL.md	ERROR
unique_id	No duplicate IDs	ERROR

Quality Standards

Check	Description	Severity
description_present	Has description	WARNING
examples_present	Has usage examples	INFO
tags_present	Has tags array	INFO
created_date	Has creation date	INFO
no_todo_markers	No TODO/FIXME markers	INFO

Examples

Basic Validation

# Validate all components
/component-validate

# Validate specific directory
/component-validate agents/

# Validate single file
/component-validate commands/component-search.md

Type-Specific

# Validate only agents
/component-validate --type agent

# Validate only skills
/component-validate --type skill --strict

Quality Checks

# Check for broken links
/component-validate --links

# Find orphaned components (not indexed)
/component-validate --orphans

# Find duplicate component IDs
/component-validate --duplicates

Auto-Fix

# Fix simple issues automatically
/component-validate --fix

# Dry-run fix
/component-validate --fix --dry-run

CI/CD Integration

# Strict mode for CI
/component-validate --strict --format sarif --output validation.sarif

# JSON output for processing
/component-validate --format json | jq '.errors'

Output

Text Format (Default)

Component Validation Report
===========================

Validating 3,027 components...

ERRORS (3):
  agents/bad-agent.md:1
    ✗ frontmatter_required: Missing YAML frontmatter

  commands/my command.md:1
    ✗ no_special_chars: Filename contains spaces

  skills/nested/deep/SKILL.md:1
    ✗ skill_structure: Skills cannot be nested (Claude Code requirement)

WARNINGS (12):
  agents/legacy-agent.md:5
    ⚠ version_format: Invalid version "v1" (use semantic: 1.0.0)
  ...

INFO (45):
  commands/old-cmd.md:10
    ℹ no_todo_markers: Contains TODO marker

Summary:
  Total:    3,027
  Valid:    3,024
  Errors:   3
  Warnings: 12
  Info:     45

Status: FAILED (3 errors)

JSON Format

{
  "summary": {
    "total": 3027,
    "valid": 3024,
    "errors": 3,
    "warnings": 12,
    "info": 45
  },
  "issues": [
    {
      "file": "agents/bad-agent.md",
      "line": 1,
      "severity": "error",
      "rule": "frontmatter_required",
      "message": "Missing YAML frontmatter",
      "fixable": false
    }
  ],
  "status": "failed"
}

Auto-Fix Capabilities

The --fix option can automatically fix:

Issue	Fix Applied
Missing frontmatter	Add template frontmatter
Invalid status	Set to "active"
Missing created date	Add current date
Uppercase filename	Rename to lowercase
Missing newline at EOF	Add newline

Exit Codes

Code	Meaning
0	All validations passed
1	Errors found
2	Warnings found (with --strict)
3	Validation system error

Implementation

# Underlying script
python3 scripts/component-db-cli.py validate [path] [options]

# Python API
from scripts.component_validator import validate_components
results = validate_components(path="agents/", strict=True)

Pre-Commit Hook

Add to .git/hooks/pre-commit:

#!/bin/bash
# Validate changed component files
CHANGED=$(git diff --cached --name-only | grep -E '\.(md|json)$')
if [ -n "$CHANGED" ]; then
  python3 scripts/component-db-cli.py validate $CHANGED --strict
  if [ $? -ne 0 ]; then
    echo "Component validation failed. Fix errors before committing."
    exit 1
  fi
fi

Related Commands

Command	Purpose
/component-index	Rebuild index
/component-search	Search components
/component-stats	View statistics
/classify	Auto-classify documents

---

Script: scripts/component-db-cli.py Config: ~/.coditect/config/validation-rules.json