CODITECT Frontmatter Standard

Purpose

This standard defines YAML frontmatter requirements for all CODITECT documents, enabling automated classification, search, and organization through the MoE (Mixture of Experts) system.

Scope

Applies to:

• All Markdown documents (.md)
• Agent definitions
• Skill definitions
• Command definitions
• Workflow documents
• Documentation files

---

1. Frontmatter Basics

1.1 Format

Frontmatter is YAML enclosed in triple dashes at the top of the file:

---
type: document
title: Document Title
version: 1.0.0
---

# Document Content Starts Here

1.2 Requirements by Component Type

Component	Frontmatter	Required Fields
Agent	MANDATORY	type, name, description, tools, model
Skill	MANDATORY	type, name, description, version
Command	MANDATORY	type, name, description
Workflow	MANDATORY	type, title, status
Documentation	RECOMMENDED	type, title, status
README	OPTIONAL	type, title

---

2. Core Fields

2.1 Universal Fields

Field	Type	Description	Required
type	string	Document type (see §3)	Yes
title	string	Human-readable title	Yes
version	string	Semantic version	Recommended
status	string	active/draft/deprecated	Recommended

2.2 MoE Classification Fields

Field	Type	Description	Auto-generated
component_type	string	Component category	Yes
keywords	array	Search keywords	Yes
tags	array	Classification tags	Yes
moe_confidence	float	Classification confidence (0-1)	Yes
moe_classified	boolean	Whether MoE classified	Yes

2.3 Metadata Fields

Field	Type	Description
created	string	Creation date (YYYY-MM-DD)
updated	string	Last update date
author	string	Author name/identifier
audience	string	Target audience (user/contributor/admin)
summary	string	Brief description
tokens	string	Estimated token count

---

3. Type Values

3.1 Component Types

type: agent          # AI agent definition
type: skill          # Reusable skill
type: command        # Slash command
type: hook           # Event hook
type: script         # Automation script
type: workflow       # Process workflow
type: prompt         # AI prompt template

3.2 Documentation Types

type: standard       # Standard/specification
type: guide          # How-to guide
type: reference      # Reference documentation
type: tutorial       # Step-by-step tutorial
type: adr            # Architecture Decision Record
type: plan           # Project plan
type: checklist      # Validation checklist
type: index          # Index/navigation document

---

4. Component-Specific Fields

4.1 Agent Fields

---
type: agent
name: agent-name
description: Brief description of what agent does
tools: [Read, Write, Edit, Bash, Grep, Glob]
model: sonnet  # or opus, haiku
context_awareness:
  project_state: true
  file_system: true
  git_state: true
triggers:
  - pattern: "keyword"
    priority: 1
---

4.2 Skill Fields

---
type: skill
name: skill-name
description: What this skill does
version: 1.0.0
status: active
difficulty: beginner  # beginner/intermediate/advanced
estimated_tokens: 500
prerequisites:
  - prerequisite-skill
related_skills:
  - related-skill
---

4.3 Command Fields

---
type: command
name: command-name
description: What this command does
usage: /command-name [options]
arguments:
  - name: arg1
    type: string
    required: true
    description: Argument description
options:
  - name: --flag
    type: boolean
    default: false
    description: Flag description
---

4.4 Workflow Fields

---
type: workflow
title: Workflow Name
status: active
complexity: high  # low/medium/high
estimated_time: 30m
phases:
  - name: Phase 1
    steps: 5
  - name: Phase 2
    steps: 3
---

---

5. Examples

5.1 Minimal Frontmatter

---
type: guide
title: Getting Started Guide
---

5.2 Standard Frontmatter

---
type: guide
title: Getting Started Guide
version: 1.0.0
status: active
audience: user
summary: Quick introduction to the project
keywords: [getting-started, setup, installation]
tags: [documentation, onboarding]
---

5.3 Full Frontmatter (Auto-classified)

---
type: guide
component_type: documentation
title: Getting Started Guide
version: 1.0.0
status: active
audience: user
summary: Quick introduction to the project
keywords: [getting-started, setup, installation, beginner]
tags: [documentation, onboarding, guide]
tokens: ~800
created: '2026-01-02'
updated: '2026-01-02'
moe_confidence: 0.92
moe_classified: true
---

---

6. Validation

6.1 Required Field Validation

# Agent - MUST have these fields:
type: agent ✓
name: string ✓
description: string ✓
tools: array ✓
model: string ✓

# Skill - MUST have these fields:
type: skill ✓
name: string ✓
description: string ✓
version: string ✓

6.2 Automated Validation

# Validate frontmatter
/validate-frontmatter path/to/file.md

# Batch validate directory
/validate-frontmatter path/to/directory/ --recursive

# Auto-fix common issues
/validate-frontmatter --fix

6.3 CI/CD Integration

- name: Validate Frontmatter
  run: python scripts/validate-frontmatter.py --strict

---

7. MoE Classification

7.1 Automatic Classification

The MoE classifier automatically adds:

• component_type - Inferred from content
• keywords - Extracted from content
• tags - Categorization tags
• moe_confidence - Classification confidence
• moe_classified - Classification flag

7.2 Classification Command

# Classify single file
/classify path/to/file.md

# Classify directory
/classify path/to/directory/

# Reclassify with force
/classify --force path/to/file.md

7.3 Confidence Thresholds

Confidence	Action
≥0.85	Auto-apply classification
0.70-0.84	Apply with review flag
<0.70	Manual classification needed

---

8. Anti-Patterns

8.1 Avoid These

Anti-Pattern	Problem	Solution
Missing frontmatter	Cannot be classified	Add required fields
Invalid YAML	Parse errors	Validate YAML syntax
Wrong type value	Misclassification	Use standard types
Missing required fields	Incomplete metadata	Add all required fields
Inconsistent format	Search/filter issues	Follow standards

8.2 Common Mistakes

❌ WRONG - Invalid YAML
---
type: agent
description: "This has "quotes" inside"
---

✅ CORRECT - Escaped quotes
---
type: agent
description: "This has 'quotes' inside"
---

❌ WRONG - Missing required fields
---
type: agent
name: my-agent
---

✅ CORRECT - All required fields
---
type: agent
name: my-agent
description: Does something useful
tools: [Read, Write]
model: sonnet
---

---

9. Templates

9.1 Document Template

---
type: guide
title: Title Here
version: 1.0.0
status: draft
audience: user
summary: Brief summary
keywords: []
tags: []
---

9.2 Agent Template

---
type: agent
name: agent-name
description: Agent description
tools: [Read, Write, Edit, Grep, Glob, Bash]
model: sonnet
context_awareness:
  project_state: true
  file_system: true
triggers:
  - pattern: "keyword"
    priority: 1
---

9.3 Skill Template

---
type: skill
name: skill-name
description: Skill description
version: 1.0.0
status: active
difficulty: beginner
prerequisites: []
related_skills: []
---

---

10. Frontmatter in Context

10.1 How Claude Uses Frontmatter

Claude Code reads frontmatter for:

• Agent selection: Matching task to agent capabilities
• Tool access: Determining available tools
• Model selection: Choosing appropriate model
• Context building: Understanding document relationships

10.2 Search and Discovery

Frontmatter enables:

• Keyword search across documents
• Type-based filtering
• Status tracking
• Version management

---

References

• MoE Classification System
• FILE-NAMING-CONVENTIONS.md
• CODITECT-STANDARD-AGENTS.md
• CODITECT-STANDARD-SKILLS.md

---

Version: 1.0.0 Status: Active Owner: CODITECT Core Team Last Updated: 2026-01-02