APAW/.kilo/rules/evolutionary-sync.md

# 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-meta.json`** is the single source of truth for:
- Agent definitions (models, modes, descriptions)
- Command definitions (models, descriptions)
- Categories and groupings

**CRITICAL**: Also update `kilo.jsonc` manually — the sync script synchronizes `.md` frontmatters FROM `kilo-meta.json`, but does NOT write back to `kilo.jsonc`.

## Files to Synchronize

When agents change, update ALL of these files:

| File | What to Update |
|------|----------------|
| `kilo-meta.json` | Models, modes, descriptions (source of truth) |
| `kilo.jsonc` | Agent model values in `"agent"` block (manual!) |
| `.kilo/agents/*.md` | Model in YAML frontmatter |
| `.kilo/capability-index.yaml` | `model:` field per agent |
| `.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 |
| `agent-evolution/data/model-benchmarks.json` | Model fitness scores, heatmap, recommendations |
| `agent-evolution/data/model-research-latest.json` | Latest research output (overwritten each cycle) |
| `agent-evolution/data/agent-versions.json` | Agent model version history |

## Sync Process (REQUIRED ORDER)

1. **Update `kilo-meta.json`** with new model (source of truth)
2. **Run sync script** — propagates to `.md` files:
   ```bash
   node scripts/sync-agents.js --fix
   ```
3. **Manually update `kilo.jsonc`** — sync script does NOT touch this file
4. **Manually update `.kilo/capability-index.yaml`** — sync script does NOT touch this file
5. **Run sync check** — verify everything:
   ```bash
   node scripts/sync-agents.js --check
   ```
6. **If violations found** → fix them, return to step 2

## Post-Sync Verification Checklist

After running `--fix`, you MUST verify:

```
□ `kilo.jsonc` — all 7 changed agents match kilo-meta.json
□ `kilo-meta.json` — no syntax errors (JSON.parse)
□ `.kilo/agents/*.md` — frontmatter YAML valid
□ `KILO_SPEC.md` — Pipeline Agents table updated
□ `AGENTS.md` — category tables updated
□ `.kilo/capability-index.yaml` — model fields updated
□ No old models leaked (grep for previous model IDs)
□ `ollama-cloud/kimi-k2.6` → always `:cloud` suffix
□ model-benchmarks.json — metadata.generated updated
□ model-research-latest.json — validates against schema
□ agent-versions.json — history entries added for all model changes
□ sync-model-research.ts — dry-run matches expected changes
□ Groq rate limits current (check console.groq.com/docs/models)
□ OpenRouter free tier models current (check openrouter.ai/models)
□ No regressions in IF scores (IF should not decrease from previous)
```

## Findings from Evolution Round 2026-04-27

### kilo.jsonc NOT synced by script
The sync script (`sync-agents.cjs`) reads `kilo.jsonc` to check for mismatches, but only WRITES to:
- `.kilo/agents/*.md` frontmatter
- `KILO_SPEC.md` tables
- `AGENTS.md` tables

**It does NOT write back to `kilo.jsonc`**. This must be done manually.

### Fix: verify kilo.jsonc after every sync
```bash
grep -n 'ollama-cloud/glm-5' kilo.jsonc  # should return nothing
grep -n 'qwen/qwen3.6-plus:free' kilo.jsonc  # should return nothing
grep -n 'ollama-cloud/deepseek-v3.2' kilo.jsonc  # should return nothing
grep -n 'ollama-cloud/nemotron-3-super' kilo.jsonc  # for changed agents only
```

### capability-index.yaml NOT synced
The capability index is not touched by sync script. After model changes, verify with:
```bash
python -c "
import yaml, json
with open('.kilo/capability-index.yaml') as f: ci = yaml.safe_load(f)
with open('kilo-meta.json') as f: meta = json.load(f)
for a in meta['agents']:
    ci_m = ci.get('agents', {}).get(a, {}).get('model')
    meta_m = meta['agents'][a]['model']
    if ci_m and ci_m != meta_m:
        print(f'MISMATCH: {a}: ci={ci_m} meta={meta_m}')
"
```

## Adding New Agent

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

2. Add to `kilo-meta.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. Add to `kilo.jsonc` under `agent`:
   ```jsonc
   "agent-name": {
     "description": "...",
     "mode": "subagent",
     "model": "provider/model-id"
   }
   ```

4. Update `.kilo/capability-index.yaml`:
   ```yaml
   agent-name:
     capabilities: [...]
     model: provider/model-id
   ```

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

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

## Model Research Sync

When `/evolution research` or `/research models` produces new benchmark data:

### Sync Process

```
1. /research models OR /evolution Step 0
   → Produces: agent-evolution/data/model-research-latest.json
   
2. Validate against schema:
   node -e "const Ajv=require('ajv'); const ajv=new Ajv(); const schema=JSON.parse(require('fs').readFileSync('agent-evolution/data/model-research.schema.json','utf8')); const data=JSON.parse(require('fs').readFileSync('agent-evolution/data/model-research-latest.json','utf8')); const valid=ajv.validate(schema,data); console.log(valid?'VALID':'INVALID'); if(!valid) console.log(JSON.stringify(ajv.errors,null,2))"
   
3. Apply recommendations:
   bun run agent-evolution/scripts/sync-model-research.ts
   
4. Or dry-run first:
   bun run agent-evolution/scripts/sync-model-research.ts --dry-run

5. After applying, the script automatically:
   - Updates capability-index.yaml
   - Updates agent-versions.json
   - Updates kilo-meta.json
   - Updates kilo.jsonc (with regex — manual verify still needed)
   - Runs sync-agents.js --fix
   - Runs sync-agents.js --check
```

### Data Freshness Check

```bash
# Check if benchmarks are stale (>7 days)
node -e "
const data = JSON.parse(require('fs').readFileSync('agent-evolution/data/model-benchmarks.json','utf8'));
const gen = new Date(data.metadata.generated);
const daysOld = (Date.now() - gen.getTime()) / (1000*60*60*24);
console.log(daysOld > 7 ? 'STALE' : 'FRESH', '(' + Math.round(daysOld) + ' days old)');
"
```

## Model Changes

When changing a model:

1. Update `kilo-meta.json` (source of truth)
2. Run `node scripts/sync-agents.js --fix`
3. **Manually update `kilo.jsonc` for all 7–8 changed agents**
4. **Manually update `.kilo/capability-index.yaml`**
5. Run `node scripts/sync-agents.js --check` to verify
6. Document reason in commit message

Example:
```
feat: evolutionary agent model upgrades based on recommendation matrix

- devops-engineer: deepseek-v3.2 → kimi-k2.6:cloud (★88)
- browser-automation: glm-5 → kimi-k2.6:cloud (★86)
- ...
```

## Cloud Model Suffix Check

When using `ollama-cloud/kimi-k2.6` models, ALWAYS include `:cloud` suffix:

```yaml
# ✅ Correct
model: ollama-cloud/kimi-k2.6:cloud

# ❌ Wrong — missing cloud suffix
model: ollama-cloud/kimi-k2.6
```

Verification:
```bash
grep -r "kimi-k2\.6[^:]" .kilo/agents/ kilo-meta.json kilo.jsonc
# should return nothing
```

## Verification Commands

Run all checks before commit:

```bash
# 1. JSON valid
node -e "require('./kilo-meta.json')" && echo "kilo-meta.json: OK"

# 2. Sync check
node scripts/sync-agents.js --check

# 3. No stale models in kilo.jsonc
grep -n "ollama-cloud/glm-5" kilo.jsonc || true
grep -n "qwen/qwen3.6-plus:free" kilo.jsonc || true

# 4. Cloud suffix check
grep -r "kimi-k2\.6[^:]" .kilo/agents/ kilo-meta.json kilo.jsonc || true

# 5. YAML frontmatter validity
python -c "
import yaml, glob, sys
errors = []
for path in glob.glob('.kilo/agents/*.md'):
    with open(path) as f:
        content = f.read()
    if not content.startswith('---'): continue
    try:
        fm = yaml.safe_load(content.split('---')[1])
        if not fm.get('model'):
            errors.append(f'{path}: missing model')
    except Exception as e:
        errors.append(f'{path}: {e}')
if errors:
    print('\n'.join(errors))
    sys.exit(1)
print('All frontmatters valid')
"
```

## CI Integration

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

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

- name: Verify JSON Validity
  run: node -e "require('./kilo-meta.json')"

- name: Check for stale models in kilo.jsonc
  run: |
    ! grep -q "qwen/qwen3.6-plus:free" kilo.jsonc
    ! grep -q "ollama-cloud/glm-5\"" kilo.jsonc
```

## Prohibited Actions

- DO NOT update `KILO_SPEC.md` without updating `kilo-meta.json`
- DO NOT update agent model without updating `kilo.jsonc` manually
- DO NOT update agent model without updating `.kilo/capability-index.yaml`
- 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
- DO NOT use `kimi-k2.6` without `:cloud` suffix
- DO NOT commit if `sync-agents.js --check` fails