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:

   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:

   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

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:

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:

   ---
   description: Agent description
   mode: subagent
   model: provider/model-id
   color: "#HEX"
   permission:
     read: allow
     edit: allow
     ...
   ---
   

2. Add to kilo-meta.json under agents:

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

   "agent-name": {
     "description": "...",
     "mode": "subagent",
     "model": "provider/model-id"
   }
   

4. Update .kilo/capability-index.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:

   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

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

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

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

Verification:

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

Verification Commands

Run all checks before commit:

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

- 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