validate-frontmatter

Validate Frontmatter

You are tasked with validating frontmatter consistency across all agents and skills in the workspace, and fixing any issues found.

Purpose

This command ensures all workflows follow the workspace frontmatter standard, making them easier to maintain, discover, and integrate.

Initial Response

When invoked:

I'll validate frontmatter across all workflows.

Checking:
- agents/ directory
- skills/ directory

What would you like to do?
1. Validate all workflows (report issues only)
2. Validate and auto-fix issues
3. Validate specific workflow
4. Generate frontmatter standard document

Process

Step 1: Determine Scope

Get user selection:

• All workflows: Check everything
• Auto-fix: Fix issues automatically
• Specific workflow: Validate one file
• Generate standard: Create reference document

Step 2: Parallel Validation

IMPORTANT: Spawn parallel validation tasks for efficiency.

Use TodoWrite to track parallel validation tasks.

For "Validate All" mode:

Task 1 - Validate Agents:

Use codebase-analyzer agent:
"Validate frontmatter in all files matching agents/*.md. For each file, check:
1. Required fields present (name, description, tools, model, version)
2. Name field matches filename (kebab-case)
3. Tools list contains valid Claude Code tools
4. Category is one of: research, analysis, search, execution, validation, general
5. Version follows semver (e.g., 1.0.0)
6. Description is clear and informative
Return: List of all validation issues found with file:line references"

Tools: Glob, Grep, Read
Path: $(git rev-parse --show-toplevel)/plugins/*/agents/
Return: Validation report for all agents

Task 2 - Validate Skills:

Use codebase-analyzer agent:
"Validate frontmatter in all files matching skills/*/SKILL.md. For each file, check:
1. Required fields present (name, description)
2. User-invoked skills have disable-model-invocation: false
3. CI/background skills have user-invocable: false
4. Uses allowed-tools (not tools) for tool restrictions
5. Does NOT include model or category in frontmatter
6. Description is clear and concise
Return: List of all validation issues found with file:line references"

Tools: Glob, Grep, Read
Path: $(git rev-parse --show-toplevel)/plugins/*/skills/
Return: Validation report for all skills

Task 3 - Extract Tool References:

Use codebase-pattern-finder agent:
"Extract all unique tool names referenced in frontmatter across plugins/*/agents/*.md and plugins/*/skills/*/SKILL.md. Return a sorted list of all tools used."

Tools: Glob, Grep
Path: $(git rev-parse --show-toplevel)/plugins/
Return: Complete list of tools referenced

WAIT for all 3 tasks to complete.

Step 3: Aggregate Validation Results

Combine results from parallel tasks:

• Agent issues (Task 1)
• Skill issues (Task 2)
• Tool inventory (Task 3)

Mark all tasks complete in TodoWrite.

Analyze:

1. Critical issues: Missing required fields, invalid formats
2. Warnings: Unusual patterns, potential improvements
3. Tool usage: Are all tools valid?
4. Category distribution: Are categories being used correctly?

Step 4: Present Validation Report

Show comprehensive report:

# Frontmatter Validation Report

**Validated**: {date} **Scope**: {agents-count} agents, {skills-count} skills **Status**:
{PASS/FAIL}

## Summary

- ✅ **Passed**: {pass-count} workflows
- ⚠️ **Warnings**: {warning-count} workflows
- ❌ **Failed**: {fail-count} workflows

## Critical Issues

### {workflow-name}.md

- ❌ Missing required field: `version`
- ❌ Invalid category: "misc" (should be one of: general, research, analysis...)

### {workflow-name}.md

- ❌ Name field "{name}" doesn't match filename "{filename}"
- ❌ Invalid tool reference: "SearchFiles" (not a valid Claude Code tool)

## Warnings

### {workflow-name}.md

- ⚠️ Description is very short (< 20 chars)
- ⚠️ No category specified (defaulting to "general")

### {workflow-name}.md

- ⚠️ Using old version format: "v1.0" (should be "1.0.0")

## Tool Inventory

**Total unique tools**: {tool-count} **Valid tools**: {valid-count} **Invalid references**:
{invalid-count}

### Used Tools:

- Read ({usage-count} workflows)
- Write ({usage-count} workflows)
- Edit ({usage-count} workflows)
- Grep ({usage-count} workflows)
- Glob ({usage-count} workflows) [... more tools ...]

### Invalid References:

- SearchFiles (used in {workflow-name}.md) → Should be: Grep or Glob
- FindFile (used in {workflow-name}.md) → Should be: Glob

## Category Distribution

### Agents:

- research: {count}
- analysis: {count}
- search: {count}
- execution: {count}
- validation: {count}
- general: {count}

### Commands:

- workflow: {count}
- planning: {count}
- implementation: {count}
- validation: {count}
- linear: {count}
- git: {count}
- workflow-discovery: {count}
- general: {count}

## Recommendations

1. **Fix critical issues first**: {count} workflows need immediate attention
2. **Standardize versions**: {count} workflows use non-semver format
3. **Update tool references**: {count} invalid tool names found
4. **Add descriptions**: {count} workflows have minimal descriptions

---

Next steps:

- Run with `--fix` to auto-correct issues
- Review and approve fixes before applying
- Re-validate after fixes

Step 5: Auto-Fix Mode (if requested)

If user chose auto-fix:

1. Create fix plan:
2. List all fixable issues
3. Show what will be changed
4. Ask for confirmation

1. Present fix plan:

```markdown # Auto-Fix Plan

I can automatically fix {fixable-count} issues:

## {workflow-name}.md

• Add missing version: 1.0.0
• Fix category: "misc" → "general"
• Standardize tool name: "SearchFiles" → "Grep"

## {workflow-name}.md

• Fix version format: "v1.0" → "1.0.0"
• Add missing model: inherit

Cannot auto-fix ({manual-count} issues):

• {workflow-name}.md: Description too short (needs human review)
• {workflow-name}.md: Unclear category (analysis vs research?)

Proceed with auto-fix? (Y/n) ```

1. Apply fixes (after confirmation):
2. Use Edit tool to fix each issue
3. Track all changes made
4. Preserve original formatting and comments

1. Report results:

```markdown ✅ Auto-fix complete!

Fixed: {fixed-count} issues across {file-count} files

### Changes Made:

#### agents/codebase-locator.md

• Added version: 1.0.0
• Standardized category: "search"

#### skills/create_plan/SKILL.md

• Fixed version: "v1.0" → "1.0.0"
• Updated tool reference: "SearchFiles" → "Grep"

[... more changes ...]

Still needs manual review:

• {workflow-name}.md: {issue description}

Re-run validation to verify: /catalyst-meta:validate-frontmatter ```

Step 6: Generate Standard Document (if requested)

If user chose to generate standard:

Create docs/frontmatter-standard.md:

# Frontmatter Standard

This document defines the frontmatter standard for all agents and commands in this workspace.

## Agent Frontmatter

### Required Fields

name: { agent-name } # Agent identifier (kebab-case, must match filename) description: | # Multi-line description {What this agent does}

Use this agent when:

• {Use case 1}
• {Use case 2}

tools: { tool-list } # Array of Claude Code tools model: inherit # Always "inherit" category: { category } # One of: research, analysis, search, execution, validation, general version: 1.0.0 # Semantic version

Optional Fields

source: { repo-url } # If imported/adapted
adapted: { date } # Date of adaptation
original-author: { name } # Original creator

Valid Categories

• research: Finding and gathering information
• analysis: Deep code/data analysis
• search: Locating files/patterns/content
• execution: Running commands/operations
• validation: Checking and verifying
• general: Multi-purpose or