# Evolutionary Mode Rules

When agents are modified, created, or updated during evolutionary improvement, this rule ensures all related files stay synchronized.

## Source of Truth

**`kilo.json`** is the single source of truth for:
- Agent definitions (models, modes, descriptions)
- Command definitions (models, descriptions)
- Categories and groupings

## Files to Synchronize

When agents change, update ALL of these files:

| File | What to Update |
|------|----------------|
| `kilo.json` | Models, modes, descriptions (source of truth) |
| `.kilo/agents/*.md` | Model in YAML frontmatter |
| `.kilo/KILO_SPEC.md` | Pipeline Agents table, Workflow Commands table |
| `AGENTS.md` | Pipeline Agents tables by category |
| `.kilo/agents/orchestrator.md` | Task Tool Invocation table |

## Sync Checklist

When modifying agents:

```
□ Update kilo.json with new model/description
□ Update agent .md file frontmatter
□ Update KILO_SPEC.md Pipeline Agents table
□ Update AGENTS.md category tables
□ Update orchestrator.md subagent_type mappings (if new agent)
□ Run scripts/sync-agents.js --check to verify
```

## Adding New Agent

1. Create `.kilo/agents/agent-name.md` with frontmatter:
   ```yaml
   ---
   description: Agent description
   mode: subagent|primary|all
   model: provider/model-id
   color: #HEX
   permission:
     read: allow
     edit: allow
     ...
   ---
   ```

2. Add to `kilo.json` under `agents`:
   ```json
   "agent-name": {
     "file": ".kilo/agents/agent-name.md",
     "description": "Full description",
     "model": "provider/model-id",
     "mode": "subagent",
     "category": "core|quality|meta|cognitive|testing"
   }
   ```

3. If subagent, add to `orchestrator.md`:
   - Add to permission list
   - Add to Task Tool Invocation table

4. Run sync script:
   ```bash
   node scripts/sync-agents.js --fix
   ```

## Model Changes

When changing a model:

1. Update agent file frontmatter
2. Update `kilo.json`
3. Update `KILO_SPEC.md`
4. Document reason in commit message

Example:
```
fix: update LeadDeveloper model from qwen3-coder:free to qwen3-coder:480b

Reason: Better code generation quality, supports larger context
```

## Verification

Run sync verification before commits:

```bash
# Check only (CI mode)
node scripts/sync-agents.js --check

# Fix discrepancies
node scripts/sync-agents.js --fix
```

## CI Integration

Add to `.github/workflows/ci.yml`:

```yaml
- name: Verify Agent Sync
  run: node scripts/sync-agents.js --check
```

## Prohibited Actions

- DO NOT update KILO_SPEC.md without updating kilo.json
- DO NOT update agent model without updating all sync targets
- DO NOT add new agent without updating orchestrator permissions
- DO NOT skip running sync script after changes