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/agents/*.md frontmatter is the single source of truth for:

• Agent definitions (models, modes, descriptions)
• Permissions and tool access

DO NOT create config files in root directory - this breaks Kilo Code.

Files to Synchronize

When agents change, update ALL of these files:

File	What to Update
.kilo/agents/agent-name.md	Model in YAML frontmatter (source of truth)
.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 (if new subagent)

Sync Checklist

When modifying agents:

□ Update agent .md file frontmatter (model, description, mode)
□ Run: node scripts/sync-agents.cjs --fix
□ Verify KILO_SPEC.md and AGENTS.md updated
□ Update orchestrator.md subagent_type mappings (if new agent)
□ Commit all changes together

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. If subagent, add to orchestrator.md:

   • Add to permission list under task:
   • Add to Task Tool Invocation table

3. Run sync:

   node scripts/sync-agents.cjs --fix
   

4. Commit all changes:

   git add .kilo/agents/new-agent.md .kilo/KILO_SPEC.md AGENTS.md .kilo/agents/orchestrator.md
   git commit -m "feat: add new-agent agent"
   

Model Changes

When changing a model:

1. Update .kilo/agents/agent-name.md frontmatter model: field
2. Run node scripts/sync-agents.cjs --fix
3. Document reason in commit message

Example:

fix: update LeadDeveloper model to qwen3-coder:480b

Reason: Better code generation quality, supports larger context

Available Models

Use exact model IDs from .kilo/KILO_SPEC.md Model Format section:

Model ID	Use Case
ollama-cloud/kimi-k2-thinking	Complex reasoning, requirements
ollama-cloud/qwen3-coder:480b	Code generation
ollama-cloud/deepseek-v3.2	Backend, DevOps
ollama-cloud/minimax-m2.5	Code review, fixing
ollama-cloud/nemotron-3-super	Performance, evaluation
ollama-cloud/nemotron-3-nano:30b	Lightweight tasks
ollama-cloud/glm-5	Orchestration
ollama-cloud/gpt-oss:120b	Large context tasks
qwen/qwen3.6-plus:free	Planning (free tier)

Verification

Run sync verification before commits:

# Check only (CI mode)
node scripts/sync-agents.cjs --check

# Fix discrepancies
node scripts/sync-agents.cjs --fix

CI Integration

Add to .github/workflows/ci.yml:

- name: Verify Agent Sync
  run: node scripts/sync-agents.cjs --check

Prohibited Actions

• DO NOT create kilo.json or kilo-meta.json in root (breaks Kilo Code)
• DO NOT update KILO_SPEC.md without updating agent files first
• DO NOT add new agent without updating orchestrator permissions
• DO NOT skip running sync script after changes
• DO NOT commit only partial files (always commit all sync targets)