coalesce-labs/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:

   • List all fixable issues
   • Show what will be changed
   • Ask for confirmation

2. Present fix plan:

   # 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)
   

3. Apply fixes (after confirmation):

   • Use Edit tool to fix each issue
   • Track all changes made
   • Preserve original formatting and comments

4. Report results:

   ✅ 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

```yaml
---
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 uncategorized

Example

---
name: codebase-analyzer
description: |
  Analyzes codebases to understand implementation details and patterns.

  Use this agent when:
  - You need to understand how a feature is implemented
  - You want to trace data flow through the system
  - You need to find patterns and conventions
tools: Read, Grep, Glob
model: inherit
category: analysis
version: 1.0.0
---

Command Frontmatter

Required Fields

---
description: { one-line-summary } # Brief description (no name field!)
category: { category } # Command category
tools: { tool-list } # Array of Claude Code tools
model: inherit # Always "inherit"
version: 1.0.0 # Semantic version
---

Optional Fields

argument-hint: { hint } # Hint for command arguments
source: { repo-url } # If imported/adapted
adapted: { date } # Date of adaptation
original-author: { name } # Original creator

Valid Categories

• workflow: Development workflows
• planning: Planning and design
• implementation: Code changes
• validation: Testing and verification
• linear: Linear integration
• git: Version control
• workflow-discovery: Meta-workflows
• general: Miscellaneous

Example

---
description: Create detailed implementation plans through interactive process
category: planning
argument-hint: [ticket-file | ticket-reference]
tools: Read, Write, Edit, Grep, Glob, Task, TodoWrite
model: inherit
version: 1.0.0
---

Valid Tools

Claude Code provides these tools:

File Operations

• Read - Read file contents
• Write - Write files
• Edit - Edit existing files

Search

• Grep - Search file contents (regex)
• Glob - Find files by pattern

Execution

• Bash - Run shell commands
• Task - Spawn sub-agents

Management

• TodoWrite - Manage todo lists

External

• WebFetch - Fetch web content
• WebSearch - Search the web

Code Understanding (Serena MCP)

• mcp__serena__activate_project - Activate the repo so language servers target it
• mcp__serena__list_memories / mcp__serena__read_memory - Read persisted project orientation
• mcp__serena__get_symbols_overview - Map a file's top-level symbols
• mcp__serena__find_symbol - Jump to a symbol's definition (semantic, not grep)
• mcp__serena__find_referencing_symbols - Find callers/references of a symbol
• mcp__serena__search_for_pattern / mcp__serena__find_file / mcp__serena__list_dir - Search/list

Linear Integration

• linear_get_ticket - Get Linear ticket details
• linear_create_ticket - Create Linear tickets
• linear_update_ticket - Update Linear tickets

(Check official Claude Code docs for complete list)

Validation Rules

All Workflows

1. Required fields must be present
2. Version must follow semver: X.Y.Z (not vX.Y)
3. Model must be "inherit" (unless specific reason)
4. Tools must be valid Claude Code tools
5. Category must be from valid list

Agents Specifically

1. Must have name field matching filename
2. Name must be kebab-case
3. Description should be multi-line with use cases

Commands Specifically

1. Must NOT have name field (use filename)
2. Description should be one-line summary
3. Use argument-hint if command takes arguments

Common Mistakes

❌ Wrong: Command with name field

---
name: create-plan # Commands don't have name field
description: Create plans
---

✅ Correct: Command without name

---
description: Create detailed implementation plans
category: planning
---

❌ Wrong: Invalid tool reference

tools: SearchFiles, FindFile # These aren't real tools

✅ Correct: Valid tools

tools: Grep, Glob # Correct tool names

❌ Wrong: Version format

version: v1.0 # Should be semver

✅ Correct: Semver version

version: 1.0.0 # Proper semver

Updating the Standard

When adding new categories or patterns:

1. Update this document
2. Validate all existing workflows
3. Fix any inconsistencies
4. Document the change in git commit

See Also

• /catalyst-meta:validate-frontmatter - Validate workflows against this standard
• /catalyst-meta:create-workflow - Create new workflows with correct frontmatter
• /catalyst-meta:import-workflow - Import external workflows and adapt frontmatter

Save and report:

✅ Frontmatter standard documented!

Saved to: docs/frontmatter-standard.md

This document now serves as the canonical reference for all frontmatter in this workspace.

Next steps:

1. Review the standard
2. Share with team
3. Use /catalyst-meta:validate-frontmatter to check compliance
4. Reference when creating new workflows

## Advanced Usage

### Validate Specific Workflow

/catalyst-meta:validate-frontmatter agents/codebase-analyzer.md

Validates just one file.

### Auto-Fix Everything

/catalyst-meta:validate-frontmatter --fix

Automatically fixes all issues without prompting.

### Generate Report Only

/catalyst-meta:validate-frontmatter --report-only > frontmatter-report.md

Saves report to file for review.

### Validate by Category

/catalyst-meta:validate-frontmatter --category research

Only validates workflows in "research" category.

## Validation Categories

### Critical Issues (Must Fix)

- Missing required fields
- Invalid field values
- Name/filename mismatch (agents)
- Invalid tool references
- Malformed YAML

### Warnings (Should Fix)

- Short descriptions (< 20 chars)
- Missing optional but recommended fields
- Unusual category choices
- Non-standard patterns

### Info (Nice to Have)

- Could add more detail
- Could specify argument-hint
- Could add source attribution
- Could improve formatting

## Auto-Fix Capabilities

### What Can Be Auto-Fixed

✅ Missing version field → Add `version: 1.0.0`
✅ Wrong version format → Convert to semver
✅ Missing model field → Add `model: inherit`
✅ Common tool typos → Fix to correct names
✅ Category typos → Fix to valid category
✅ YAML formatting → Standardize indentation

### What Requires Manual Review

❌ Ambiguous categories → Needs human judgment
❌ Short descriptions → Needs content creation
❌ Complex tool issues → May need workflow redesign
❌ Missing description → Needs understanding of purpose

## Important Notes

- **Non-destructive**: Auto-fix preserves content, only fixes frontmatter
- **Safe**: Always shows plan before applying fixes
- **Trackable**: Reports all changes made
- **Reversible**: Changes are standard edits, can be reverted via git
- **Standard-based**: Uses workspace-specific conventions

## Integration with Other Commands

- **Discover**: `/catalyst-meta:discover-workflows` → uses this for validation
- **Import**: `/catalyst-meta:import-workflow` → validates imported workflows
- **Create**: `/catalyst-meta:create-workflow` → ensures new workflows are valid
- **Validate**: `/catalyst-meta:validate-frontmatter` (this command) → checks everything

## Error Handling

### Malformed YAML
- Report syntax errors
- Show line number
- Suggest fixes
- Cannot auto-fix (manual correction needed)

### Unknown Fields
- Report unexpected fields
- Ask: Keep / Remove?
- Could be custom extensions

### Missing Files
- Skip files that don't exist
- Report which files were skipped
- Continue validation

### Permission Errors
- Report read/write issues
- Skip files that can't be accessed
- Provide error details

This command ensures workspace consistency and quality!