APAW/.kilo/rules/agent-frontmatter-validation.md

Agent Frontmatter Validation Rules

Critical rules for modifying agent YAML frontmatter. Violations break Kilo Code.

Color Format

ALWAYS use quoted hex colors in YAML frontmatter. NEVER generate unquoted colors:

# ✅ Good — quoted, safe
model: ollama-cloud/glm-5.1
color: "#DC2626"

# ❌ Bad — breaks YAML parsing, causes startup error
color: #DC2626

# ❌ Bad — partially quoted, still invalid
color: '#DC2626'

Why

Unquoted # starts a YAML comment, making the value empty or invalid. This causes:

• Config file invalid: color: Invalid input
• Agent fails to load
• Entire pipeline stalls

Mode Values

Valid mode values:

Value	Description
subagent	Invoked by other agents (most agents)
all	Can be both primary and subagent (user-facing agents)

Invalid mode values:

• primary (use all instead)
• Any other value

Model Format

Always use exact model IDs from KILO_SPEC.md:

# ✅ Good
model: ollama-cloud/nemotron-3-super
model: ollama-cloud/gpt-oss:120b
model: openrouter/qwen/qwen3.6-plus:free

# ❌ Bad - model not in KILO_SPEC
model: ollama-cloud/nonexistent-model
model: anthropic/claude-3-opus

Available Models

See .kilo/KILO_SPEC.md Model Format section for complete list.

Description

Required field, must be non-empty:

# ✅ Good
description: DevOps specialist for Docker, Kubernetes, CI/CD

# ❌ Bad
description:
description: ""

Permission Structure

Always include all required permission keys:

# ✅ Good
permission:
  read: allow
  edit: allow
  write: allow
  bash: allow
  glob: allow
  grep: allow
  task:
    "*": deny
    "code-skeptic": allow

# ❌ Bad - missing keys
permission:
  read: allow
  # missing edit, write, bash, glob, grep, task

Validation Checklist

Before committing agent changes:

□ color is quoted (e.g., "#DC2626")
□ mode is valid (subagent or all)
□ model exists in KILO_SPEC.md
□ description is non-empty
□ all permission keys present
□ task permissions use deny-by-default
□ No trailing commas in YAML
□ No tabs in YAML (use spaces)

Automated Validation

Run before commit:

# Check all agents for YAML validity
for f in .kilo/agents/*.md; do
  head -20 "$f" | grep -E "^color:" | grep -v '"#' && echo "FAIL: $f color not quoted"
done

Validation Script (Recommended)

node scripts/validate-agents.cjs

This script checks:

• color is double-quoted and starts with "#
• mode is subagent or all
• model exists in kilo-meta.json
• description is non-empty
• All permission keys present
• No duplicate keys
• No trailing commas in YAML

Error Diagnosis

If you see this error on startup:

Config file at .../agents/xxx.md is invalid: color: Invalid input

→ Fix: Wrap color in double quotes: color: "#DC2626"

Common causes:

1. AI generated color: #DC2626 without quotes
2. Copy-paste from documentation lost quotes
3. Editor auto-format stripped quotes

Always verify with: grep -r "^color: #" .kilo/agents/ .kilo/commands/ .kilo/skills/

Common Mistakes

1. Unquoted Color

# ❌ Wrong
color: #DC2626

# ✅ Correct
color: "#DC2626"

2. Invalid Mode

# ❌ Wrong
mode: primary

# ✅ Correct
mode: all

3. Missing Model Provider

# ❌ Wrong
model: qwen3-coder:480b

# ✅ Correct
model: ollama-cloud/qwen3-coder:480b

4. Incomplete Permissions

# ❌ Wrong
permission:
  read: allow
  edit: allow
  # missing write, bash, glob, grep, task

# ✅ Correct
permission:
  read: allow
  edit: allow
  write: allow
  bash: allow
  glob: allow
  grep: allow
  task:
    "*": deny

Prohibited Actions

• DO NOT change color format without testing YAML parsing
• DO NOT use models not listed in KILO_SPEC.md
• DO NOT remove required permission keys
• DO NOT commit agent files with empty descriptions
• DO NOT use tabs in YAML frontmatter