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:

# ✅ Good
color: "#DC2626"
color: "#4F46E5"
color: "#0EA5E9"

# ❌ Bad - breaks YAML parsing
color: #DC2626
color: #4F46E5
color: #0EA5E9

Why

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

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

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