APAW/.kilo/KILO_SPEC.md

Kilo Code Specification Reference

Overview

Kilo Code is a customizable AI coding assistant framework. This specification documents all customization capabilities including agents, commands, rules, skills, and configuration files. Kilo Code enables defining custom AI agents with specific models, prompts, permissions, and behaviors through a declarative configuration system.

---

Directory Structure

project/
├── .kilo/
│   ├── agents/           # Custom agent definitions (.md files with YAML frontmatter)
│   ├── commands/         # Workflow commands (.md files, invoked with /command-name)
│   ├── rules/            # Custom rules (loaded via kilo.jsonc instructions)
│   ├── skills/           # Agent skills (SKILL.md format)
│   └── kilo.jsonc        # Main configuration file
├── AGENTS.md             # Project-level instructions for AI agents
└── kilo.jsonc            # (alternative location) Main configuration file

Description

Directory/File	Purpose
.kilo/agents/	Custom agent definitions with YAML frontmatter for model, description, mode, permissions
.kilo/commands/	Workflow commands invoked via /command-name in Kilo interface
.kilo/rules/	Custom rules and guidelines loaded via kilo.jsonc instructions array
.kilo/skills/	Reusable skill modules with SKILL.md entry point
kilo.jsonc	Main configuration: agents, models, instructions, skills
AGENTS.md	Project-level instructions applied to all agents

---

Agent Definition Format

Agents are defined in .md files with YAML frontmatter followed by the prompt body.

YAML Frontmatter Fields

Field	Required	Type	Description
name	Yes	string	Agent identifier (from filename, max 64 chars)
description	Yes	string	Brief description (max 1024 chars)
model	No	string	Model in provider/model-id format
prompt	Yes	string	Agent instructions (markdown body after frontmatter)
mode	No	enum	Visibility mode: primary, subagent, all
permission	No	object	Tool permissions configuration
color	No	string	Hex color for UI display (e.g., #DC2626)
steps	No	array	List of agent activation steps
temperature	No	number	Model temperature (0.0-2.0)
top_p	No	number	Model top_p parameter
variant	No	string	Model variant identifier
hidden	No	boolean	Hide from UI (default: false)
disable	No	boolean	Disable agent (default: false)

Mode Types

Mode	Description
primary	User-facing, shown in agent picker
subagent	Only invocable via Task tool or @agent-name mentions
all	Both user-facing and invokable as subagent

Example Agent Definition

---
description: Primary code writer for backend and core logic
mode: primary
model: ollama-cloud/deepseek-v3.2
color: "#DC2626"
---

# Kilo Code: Lead Developer

## Role Definition

You are **Lead Developer** — the primary code writer...

## Behavior Guidelines

1. **Follow tests** — make code pass the tests
2. **Write clean code** — follow Style Guide
...

---

Permission System

Permissions control which tools an agent can use. Defined per-agent in permission object.

Permission Values

Value	Behavior
allow	Tool can be used without prompting
deny	Tool cannot be used
ask	User is prompted before each use

Per-Tool Permissions

Tool	Description
read	Read files and directories
edit	Edit existing files
write	Create new files
bash	Execute shell commands
glob	File pattern matching
grep	Content search
task	Delegate to subagents
webfetch	Fetch web content
skill	Load specialized skills

Example Permission Configuration

{
  "permission": {
    "read": "allow",
    "edit": "allow",
    "write": "ask",
    "bash": "ask",
    "glob": "allow",
    "grep": "allow",
    "task": "allow"
  }
}

---

kilo.jsonc Configuration

Main configuration file with JSON Schema support.

Schema Reference

{
  "$schema": "https://app.kilo.ai/config.json"
}

Complete Structure

{
  "$schema": "https://app.kilo.ai/config.json",
  "instructions": [".kilo/rules/*.md"],
  "skills": {
    "paths": [".kilo/skills"],
    "urls": ["https://example.com/.well-known/skills/"]
  },
  "model": "qwen/qwen3.6-plus:free",
  "small_model": "openai/llama-3.1-8b-instant",
  "default_agent": "orchestrator",
  "agent": {
    "agent-name": {
      "description": "Agent description",
      "model": "provider/model-id",
      "mode": "primary",
      "color": "#FFFFFF",
      "permission": {
        "read": "allow",
        "edit": "allow",
        "bash": "ask"
      },
      "temperature": 0.7,
      "top_p": 0.9
    }
  }
}

Field Reference

Field	Type	Description
$schema	string	JSON Schema URL for validation
instructions	array	Glob patterns for rule files to load
skills.paths	array	Directories containing skill modules
skills.urls	array	URLs to fetch skills from
model	string	Global default model (provider/model-id)
small_model	string	Small model for titles/subtasks
default_agent	string	Default agent when none specified (must be primary)
agent	object	Agent definitions keyed by agent name

Agent Configuration Fields

Field	Type	Required	Description
description	string	Yes	Agent description
model	string	No	Model identifier (provider/model-id)
mode	enum	No	Visibility: primary, subagent, all
color	string	No	Hex color for UI
permission	object	No	Tool permissions
temperature	number	No	Model temperature
top_p	number	No	Model top_p
variant	string	No	Model variant
hidden	boolean	No	Hide from UI
disable	boolean	No	Disable agent

---

SKILL.md Format

Skills are reusable modules loaded via the Skill tool.

Required Fields

Field	Type	Constraints
name	string	Required, max 64 characters
description	string	Required, max 1024 characters

Optional Fields

Field	Type	Description
license	string	License identifier
compatibility	string	Version compatibility
metadata	object	Additional metadata

Example SKILL.md

---
name: gitea
description: Work with Gitea repositories - commit, push, create PR, manage issues
---

# Gitea Integration Skill

## Purpose
Automate all git operations with Gitea without requiring manual console input.

## Capabilities

### Repository Detection
- Detect Gitea remote from `git remote -v`
- Extract owner/repo from remote URL
- Check authenticated user permissions

### Git Operations
- `git status` - check working tree status
- `git add` - stage changes
- `git commit` - create commits
- `git push` - push to remote

## Workflow

1. **Before Commit**
   - Run `git status` to see changes
   - Run `git diff` to review changes
   - Run `git log --oneline -5` to match style
...

---

Workflows (Commands)

Commands are workflow shortcuts invoked via /command-name in the Kilo interface.

Location

.kilo/commands/ directory

Format

.md files with optional YAML frontmatter.

Example Command

---
description: Creates detailed task plans
mode: plan
model: ollama-cloud/deepseek-v3.2
color: "#3B82F6"
---

# Plan Command

Generates detailed implementation plans with task breakdown.

Invocation

User types /plan in Kilo interface to activate the command.

Available Commands (This Project)

Command	Description	Model
/plan	Creates detailed task plans	qwen/qwen3-coder:free
/ask	Answers codebase questions	openai/qwen3-32b
/debug	Analyzes and fixes bugs	openai/gpt-oss-20b
/code	Quick code generation	qwen/qwen3-coder:free

---

Custom Rules

Rules are markdown files loaded via kilo.jsonc instructions array.

Location

.kilo/rules/ directory

Loading Configuration

{
  "instructions": [".kilo/rules/*.md"]
}

Format

Markdown files with structured sections.

Example Rule

# Lead Developer Rules

- Write clean, maintainable code following project conventions
- NEVER add comments unless explicitly asked
- Check existing dependencies before adding new ones
- Follow existing code patterns and style in the codebase

## Code Quality

- Use early returns to reduce nesting
- Prefer immutable data structures
- Write self-documenting code with clear names
- Handle edge cases and errors appropriately
...

Available Rules (This Project)

Rule File	Purpose
global.md	Global rules applied to all agents
lead-developer.md	Lead Developer specific rules
code-skeptic.md	Code review guidelines
sdet-engineer.md	Test writing guidelines
history-miner.md	Git history search rules
release-manager.md	Git operations and deployment rules

---

Configuration Precedence

Configurations are merged in the following order (later overrides earlier):

1. Built-in defaults — Kilo Code default configuration
2. Global config — ~/.config/kilo/kilo.jsonc
3. Project config — kilo.jsonc in project root or .kilo/
4. Agent .md files — Individual agent definitions in .kilo/agents/

Merge Behavior

• Agent definitions merge by agent name
• Later configurations override earlier ones
• Arrays are concatenated, not replaced
• Object properties deep merge

---

Model Format

Models are specified in provider/model-id format.

Format

provider/model-id

Examples

Model ID	Provider	Model
openrouter/qwen/qwen3-coder:free	openrouter	Qwen3 Coder (Free)
openrouter/qwen/qwen3.6-plus:free	openrouter	Qwen3.6 Plus (Free)
openrouter/minimax/minimax-m2.5:free	openrouter	MiniMax M2.5 (Free)
openai/qwen3-32b	openai (groq)	Qwen3 32B
openai/llama-3.1-8b-instant	openai (groq)	Llama 3.1 8B Instant
openai/llama-4-scout-17b-16e-instruct	openai (groq)	Llama 4 Scout 17B
ollama-cloud/kimi-k2-thinking	ollama-cloud	Kimi K2 Thinking
ollama-cloud/kimi-k2.5	ollama-cloud	Kimi K2.5
ollama-cloud/nemotron-3-super	ollama-cloud	Nemotron 3 Super
ollama-cloud/nemotron-3-nano:30b	ollama-cloud	Nemotron 3 Nano 30B
ollama-cloud/qwen3-coder:480b	ollama-cloud	Qwen3 Coder 480B
ollama-cloud/gpt-oss:20b	ollama-cloud	GPT OSS 20B
ollama-cloud/gpt-oss:120b	ollama-cloud	GPT OSS 120B
ollama-cloud/minimax-m2.5	ollama-cloud	MiniMax M2.5
ollama-cloud/glm-5	ollama-cloud	GLM-5
ollama-cloud/deepseek-v3.2	ollama-cloud	DeepSeek V3.2
ollama-cloud/devstral-2	ollama-cloud	Devstral 2
anthropic/claude-sonnet-4-20250514	anthropic	Claude Sonnet 4

Available Providers

Provider availability depends on configuration. Common providers include:

• ollama-cloud — Ollama cloud models (subscription)
• openrouter — OpenRouter API models (free tier available)
• openai — OpenAI-compatible API (используется для Groq: openai/qwen3-32b и др.)
• anthropic — Anthropic Claude models
• google — Google Gemini models

---

Agents (This Project)

Pipeline Agents

Agent	Role	Model	Variant
@AgentArchitect	Creates, modifies, and reviews new agents, workflows, and skills based on capability gap analysis.	ollama-cloud/glm-5.1	thinking
@BackendDeveloper	Backend specialist for Node.js, Express, APIs, and database integration.	ollama-cloud/qwen3-coder:480b	thinking
@BrowserAutomation	Browser automation agent using Playwright MCP for E2E testing, form filling, navigation, and web interaction.	ollama-cloud/qwen3-coder:480b	—
@CapabilityAnalyst	Analyzes task requirements against available agents, workflows, and skills.	ollama-cloud/glm-5.1	—
@CodeSkeptic	Adversarial code reviewer.	ollama-cloud/minimax-m2.5	—
@DevopsEngineer	DevOps specialist for Docker, Kubernetes, CI/CD pipeline automation, and infrastructure management.	ollama-cloud/nemotron-3-super	—
@Evaluator	Scores agent effectiveness after task completion for continuous improvement.	ollama-cloud/glm-5.1	thinking
@FrontendDeveloper	Handles UI implementation with multimodal capabilities.	ollama-cloud/qwen3-coder:480b	—
@GoDeveloper	Go backend specialist for Gin, Echo, APIs, and database integration.	ollama-cloud/qwen3-coder:480b	—
@HistoryMiner	Analyzes git history to find duplicates and past solutions, preventing regression and duplicate work.	ollama-cloud/nemotron-3-super	—
@LeadDeveloper	Primary code writer for backend and core logic.	ollama-cloud/qwen3-coder:480b	thinking
@MarkdownValidator	Validates and corrects Markdown descriptions for Gitea issues.	ollama-cloud/nemotron-3-nano:30b	—
@MemoryManager	Manages agent memory systems - short-term (context), long-term (vector store), and episodic (experiences).	ollama-cloud/nemotron-3-super	—
@Orchestrator	Main dispatcher. Routes tasks between agents based on Issue status.	ollama-cloud/glm-5.1	thinking
@PerformanceEngineer	Reviews code for performance issues.	ollama-cloud/nemotron-3-super	—
@Planner	Advanced task planner using Chain of Thought, Tree of Thoughts, and Plan-Execute-Reflect.	ollama-cloud/nemotron-3-super	—
@PipelineJudge	Automated pipeline judge. Evaluates workflow execution, produces objective fitness scores.	ollama-cloud/glm-5.1	—
@ProductOwner	Manages issue checklists, status labels, tracks progress and coordinates with human users.	ollama-cloud/glm-5.1	—
@PromptOptimizer	Improves agent system prompts based on performance failures.	ollama-cloud/glm-5.1	instant
@Reflector	Self-reflection agent using Reflexion pattern - learns from mistakes.	ollama-cloud/nemotron-3-super	—
@ReleaseManager	Manages git operations, semantic versioning, branching, and deployments.	ollama-cloud/glm-5.1	—
@RequirementRefiner	Converts vague ideas and bug reports into strict User Stories with acceptance criteria checklists.	ollama-cloud/glm-5.1	thinking
@SdetEngineer	Writes tests following TDD methodology.	ollama-cloud/qwen3-coder:480b	thinking
@SecurityAuditor	Scans for security vulnerabilities, OWASP Top 10, dependency CVEs, and hardcoded secrets.	ollama-cloud/nemotron-3-super	—
@SystemAnalyst	Designs technical specifications, data schemas, and API contracts before implementation.	ollama-cloud/glm-5.1	thinking
@TheFixer	Iteratively fixes bugs based on specific error reports and test failures.	ollama-cloud/minimax-m2.5	—
@VisualTester	Visual regression testing agent that compares screenshots and detects UI differences using pixelmatch and image diff.	ollama-cloud/qwen3-coder:480b	—
@WorkflowArchitect	Creates and maintains workflow definitions with complete architecture, Gitea integration, and quality gates.	ollama-cloud/glm-5.1	thinking

Note: All agents above are accessible via Task tool with their own subagent_type matching the agent name (e.g., subagent_type: "agent-architect").

Workflow Commands

Command	Description	Model
/landing-page	Create landing page CMS from HTML mockups	ollama-cloud/kimi-k2.5
/commerce	Create e-commerce site with products, cart, payments	qwen/qwen3-coder:free
/blog	Create blog/CMS with posts, comments, SEO	qwen/qeen3-coder:free
/booking	Create booking system for services/appointments	qwen/qwen3-coder:free
/workflow	Run complete workflow with quality gates	ollama-cloud/glm-5
/pipeline	Run full agent pipeline for issue	-
/feature	Full feature development pipeline	qwen/qwen3-coder:free
/code	Quick code generation	qwen/qwen3-coder:free
/debug	Analyzes and fixes bugs	openai/gpt-oss-20b
/ask	Answers codebase questions	openai/qwen3-32b
/plan	Creates detailed task plans	qwen/qwen3-coder:free
/e2e-test	Run E2E tests with browser automation	-
/status	Check pipeline status for issue	-
/evaluate	Generate performance report	-
/review	Code review workflow	-
/review-watcher	Auto-validate review results	-
/hotfix	Hotfix workflow	-

Workflow Pipeline

[new] → HistoryMiner → [researching] → SystemAnalyst → [designing] → SDET
                                                                          ↓
[testing] → LeadDev → CodeSkeptic → [fail? TheFixer] → [pass] → Performance → Security → Release → Evaluator

---

Skills (This Project)

Gitea Integration

Location: .kilo/skills/gitea/SKILL.md

Purpose: Automate git operations with Gitea without manual console input.

Capabilities:

• Repository detection from remote URLs
• Git operations: status, add, commit, push, pull
• Branch management: create, detect, switch
• Pull request creation via API
• Issue integration and auto-close

E-commerce Domain

Location: .kilo/skills/ecommerce/SKILL.md

Purpose: Domain knowledge for building e-commerce systems.

Capabilities:

• Product catalog management
• Shopping cart implementation
• Order processing workflow
• Payment integration (Stripe, PayPal)
• Inventory management
• Database schemas for products, orders, payments

Blog/CMS Domain

Location: .kilo/skills/blog/SKILL.md

Purpose: Domain knowledge for building blog and content management systems.

Capabilities:

• Post CRUD with draft/publish states
• Categories and tags (hierarchical and flat)
• Comment moderation with spam detection
• SEO optimization (meta, Open Graph, Schema.org)
• RSS/Atom feeds and sitemap generation
• Media library management

Booking System Domain

Location: .kilo/skills/booking/SKILL.md

Purpose: Domain knowledge for building booking and appointment systems.

Capabilities:

• Service management with categories and pricing
• Staff scheduling and availability
• Real-time slot calculation
• Booking flow (service → staff → date/time → customer)
• Status management (pending, confirmed, completed, cancelled)
• Email/SMS notifications
• Calendar integration (Google, iCal)
• Revenue and utilization reports

Quality Controller Domain

Location: .kilo/skills/quality-controller/SKILL.md

Purpose: Ensures all workflows follow closed-loop process with Gitea integration.

Capabilities:

• Quality gates for each workflow step
• Artifact verification
• Gitea issue tracking
• Progress comments
• Error blocking and recovery
• Final delivery validation
• Client-ready checklist

Gitea Workflow Domain

Location: .kilo/skills/gitea-workflow/SKILL.md

Purpose: Complete Gitea integration for closed-loop workflow execution.

Capabilities:

• Issue creation before any work starts
• Progress comments after each step
• Quality gate validation
• Error blocking (no partial results)
• Final delivery validation
• Client handoff checklist
• Status label management

---

File Naming Conventions

Type	Convention	Example
Agent	kebab-case.md	lead-developer.md
Command	kebab-case.md	plan.md
Rule	kebab-case.md	release-manager.md
Skill	SKILL.md	SKILL.md (inside directory)

---

Validation

JSON Schema

Use $schema field for IDE validation:

{
  "$schema": "https://app.kilo.ai/config.json"
}

Common Errors

1. Missing required field: description is required for agents
2. Invalid model format: Use provider/model-id format
3. Invalid mode: Must be primary, subagent, or all
4. Invalid permission value: Must be allow, deny, or ask

---

Examples

Minimal Agent Configuration

{
  "agent": {
    "assistant": {
      "description": "General assistant"
    }
  }
}

Full Agent Configuration

{
  "agent": {
    "senior-developer": {
      "description": "Senior developer with full permissions",
      "model": "ollama-cloud/deepseek-v3.2",
      "mode": "primary",
      "color": "#10B981",
      "temperature": 0.7,
      "top_p": 0.9,
      "permission": {
        "read": "allow",
        "edit": "allow",
        "write": "allow",
        "bash": "ask",
        "glob": "allow",
        "grep": "allow",
        "task": "allow"
      }
    }
  }
}

Restricted Agent Configuration

{
  "agent": {
    "viewer": {
      "description": "Read-only agent",
      "model": "ollama-cloud/gemini-3-flash",
      "mode": "subagent",
      "permission": {
        "read": "allow",
        "edit": "deny",
        "write": "deny",
        "bash": "deny",
        "glob": "allow",
        "grep": "allow"
      }
    }
  }
}