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

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

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

   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:

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

- 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