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:**

```yaml
# ✅ 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:**

```yaml
# ✅ 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:**

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

# ❌ Bad
description:
description: ""
```

## Permission Structure

**Always include all required permission keys:**

```yaml
# ✅ 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:

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

```bash
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

```yaml
# ❌ Wrong
color: #DC2626

# ✅ Correct
color: "#DC2626"
```

### 2. Invalid Mode

```yaml
# ❌ Wrong
mode: primary

# ✅ Correct
mode: all
```

### 3. Missing Model Provider

```yaml
# ❌ Wrong
model: qwen3-coder:480b

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

### 4. Incomplete Permissions

```yaml
# ❌ 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