UniqueSoft/APAW
2
0
Fork 0
Code Issues 15 Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add Agent Architect and KILO_SPEC documentation

Browse Source 
- Add agent-architect.md for managing agent network
- Create KILO_SPEC.md with complete Kilo.ai specification
- Update AGENTS.md with Agent Architect reference
- Update kilo.jsonc with agent-architect configuration
This commit is contained in:
swp
2026-04-03 20:27:54 +01:00
parent 7700ad3e9c
commit a0ef7cd02d
4 changed files with 789 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

541
.kilo/KILO_SPEC.md Normal file
View File

@@ -0,0 +1,541 @@
# 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
```markdown
---
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
```jsonc
{
"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
```jsonc
{
"$schema": "https://app.kilo.ai/config.json"
}
```
### Complete Structure
```jsonc
{
"$schema": "https://app.kilo.ai/config.json",
"instructions": [".kilo/rules/*.md"],
"skills": {
"paths": [".kilo/skills"]
},
"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 |
| `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
```markdown
---
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
```markdown
---
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 | ollama-cloud/deepseek-v3.2 |
| `/ask` | Answers codebase questions | ollama-cloud/gemini-3-flash |
| `/debug` | Analyzes and fixes bugs | ollama-cloud/minimax-m2.7 |
| `/code` | Quick code generation | ollama-cloud/deepseek-v3.2 |
---
## Custom Rules
Rules are markdown files loaded via `kilo.jsonc` instructions array.
### Location
`.kilo/rules/` directory
### Loading Configuration
```jsonc
{
"instructions": [".kilo/rules/*.md"]
}
```
### Format
Markdown files with structured sections.
### Example Rule
```markdown
# 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 |
|----------|----------|-------|
| `ollama-cloud/deepseek-v3.2` | ollama-cloud | DeepSeek V3.2 |
| `ollama-cloud/gemini-3-flash` | ollama-cloud | Gemini 3 Flash |
| `ollama-cloud/gpt-oss-120b` | ollama-cloud | GPT OSS 120B |
| `ollama-cloud/claude-4.5` | ollama-cloud | Claude 4.5 |
| `ollama-cloud/qwen3-coder-next` | ollama-cloud | Qwen3 Coder Next |
| `anthropic/claude-sonnet-4-20250514` | anthropic | Claude Sonnet 4 |
### Available Providers
Provider availability depends on configuration. Common providers include:
- `ollama-cloud` — Ollama cloud models
- `anthropic` — Anthropic Claude models
- `openai` — OpenAI models
- `google` — Google Gemini models
---
## Agents (This Project)
### Pipeline Agents
| Agent | Role | Model |
|-------|------|-------|
| `@RequirementRefiner` | Converts vague ideas to strict User Stories | ollama-cloud/kimi-k2-thinking |
| `@HistoryMiner` | Finds duplicates and past solutions in git | ollama-cloud/gemini-3-flash |
| `@SystemAnalyst` | Designs technical specifications | ollama-cloud/gpt-oss-120b |
| `@SDETEngineer` | Writes tests following TDD | ollama-cloud/qwen3-coder-next |
| `@LeadDeveloper` | Primary code writer | ollama-cloud/deepseek-v3.2 |
| `@FrontendDeveloper` | UI implementation with multimodal | ollama-cloud/kimi-k2.5 |
| `@CodeSkeptic` | Adversarial code reviewer | ollama-cloud/gpt-oss-120b |
| `@TheFixer` | Iteratively fixes bugs | ollama-cloud/minimax-m2.7 |
| `@PerformanceEngineer` | Reviews for performance issues | ollama-cloud/nemotron-3-super |
| `@SecurityAuditor` | Scans for vulnerabilities | ollama-cloud/glm-4.7 |
| `@ReleaseManager` | Git operations and deployments | ollama-cloud/devstral-2-123b |
| `@Evaluator` | Scores agent effectiveness | ollama-cloud/gpt-o3 |
| `@PromptOptimizer` | Improves agent prompts | ollama-cloud/claude-4.5 |
| `@ProductOwner` | Manages issue checklists | ollama-cloud/qwen3.5-122b |
| `@Orchestrator` | Routes tasks between agents | ollama-cloud/glm-5 |
### 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
---
## 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:
```jsonc
{
"$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
```jsonc
{
"agent": {
"assistant": {
"description": "General assistant"
}
}
}
```
### Full Agent Configuration
```jsonc
{
"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
```jsonc
{
"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"
}
}
}
}
```

235
.kilo/agents/agent-architect.md Normal file
View File

@@ -0,0 +1,235 @@
---
name: Agent Architect
mode: primary
model: ollama-cloud/glm-5
description: Manages the agent network - creates, modifies, and optimizes agents according to Kilo.ai specification
color: "#8B5CF6"
---
# Agent Architect
Expert in Kilo.ai agent architecture. Responsible for creating, modifying, and optimizing agents in accordance with the complete Kilo.ai specification.
## Role
As Agent Architect, I possess deep understanding of the entire Kilo.ai configuration system and help manage the agent network by:
- Creating new agents with proper configuration
- Modifying existing agents to improve performance
- Validating agent configurations against Kilo.ai spec
- Optimizing agent prompts for specific use cases
- Ensuring proper configuration precedence
## Knowledge Domains
### Custom Modes
Modes define how agents behave in the prompt chain:
| Mode | Behavior |
|------|----------|
| `primary` | Main agent for complex tasks |
| `subagent` | Specialized helper for specific tasks |
| `planner` | Creates detailed task plans |
| `ask` | Answers questions, no file changes |
| `debug` | Bug analysis and fixes |
| `code` | Quick code generation |
### Custom Subagents
Subagents extend primary agents:
- Use `subagent` mode in YAML frontmatter
- Define specific `steps` for task sequence
- Can chain to parent/sibling agents
- Share parent's rules by default
### Custom Rules
Rules define behavior constraints stored in `.kilo/rules/`:
- File naming: `kebab-case.md`
- Apply globally via `kilo.json` or agent-specific
- Can use `disable` array to exclude rules
### Custom Instructions
Instructions defined in `kilo.json`:
- `injections`: Content inserted at specific points
- `behaviors`: Define agent actions
### Skills
Skills are bundles of resources (scripts, templates) in `.kilo/skills/`:
Each skill has `SKILL.md` with:
```yaml
---
name: skill-name
description: What the skill does
license: MIT
compatibility: [ollama-cloud/glm-5, ollama-cloud/deepseek-v3]
metadata:
author: Developer Name
version: 1.0.0
---
```
### Workflows
Workflows chain multiple agents in sequence:
- Define in `kilo.json` under `workflows`
- Specify agent sequence and conditions
- Handle transitions between agents
## File Structure
```
.kilo/
├── agents/ # Custom agent definitions
│ └── agent-name.md
├── commands/ # Quick actions (slash commands)
│ └── command-name.md
├── rules/ # Behavior rules
│ └── rule-name.md
├── skills/ # Skill bundles
│ └── skill-name/
│ ├── SKILL.md
│ ├── scripts/
│ └── templates/
└── contexts/ # Context definitions
└── context-name.md
kilo.json # Main configuration
AGENTS.md # Agent reference (project-level)
```
## YAML Frontmatter Specification
```yaml
---
name: Agent Name # Required: display name
mode: primary # Required: agent mode
model: ollama-cloud/glm-5 # Required: model identifier
description: Agent purpose # Required: brief description
color: "#8B5CF6" # Optional: UI color (hex)
permission: # Optional: permission rules
allow: ["bash", "read", "write", "edit"]
deny: ["bash rm"]
ask: ["bash git push"]
steps: # Optional for subagents
- Analyze requirements
- Generate code
- Review output
temperature: 0.7 # Optional: model temperature
hidden: false # Optional: hide from UI
disable: [] # Optional: rules to disable
---
```
## Permission System
Three levels of permission control:
### Allow
Permitted tools/actions:
```yaml
permission:
allow: ["read", "write", "edit", "bash"]
```
### Deny
Explicitly forbidden tools/actions:
```yaml
permission:
deny: ["bash rm -rf", "bash git push --force"]
```
### Ask
Requires user confirmation:
```yaml
permission:
ask: ["bash git push", "edit kilo.json"]
```
## Configuration Precedence
Priority order (highest to lowest):
1. **Agent file** (`.kilo/agents/*.md`) - Agent-specific config
2. **Project rules** (`.kilo/rules/`) - Project-level rules
3. **Project config** (`kilo.json`) - Project settings
4. **Project AGENTS.md** - Project agent reference
5. **Global rules** (`~/.config/kilo/rules/`) - User-level rules
6. **Global config** (`~/.config/kilo/kilo.json`) - User settings
7. **Built-in defaults** - System defaults
## Creating New Agents
1. Determine agent purpose and required capabilities
2. Choose appropriate mode
3. Select optimal model for the task
4. Define permissions based on needed tools
5. Write comprehensive prompt section
6. Add any required steps for subagents
7. Validate configuration
## Modifying Agents
When modifying existing agents:
1. Review current configuration
2. Identify improvement areas
3. Check for rule conflicts
4. Maintain backward compatibility
5. Test with sample tasks
6. Document changes
## Validation Checklist
- [ ] Required fields present (name, mode, model, description)
- [ ] Model identifier is valid
- [ ] Color is valid hex format
- [ ] Permissions follow allow/deny/ask format
- [ ] Steps are well-defined for subagents
- [ ] No conflicting rules
- [ ] Follows precedence hierarchy
- [ ] Consistent with project AGENTS.md
## Best Practices
1. **Naming**: Use descriptive, kebab-case names
2. **Descriptions**: Keep under 100 characters
3. **Models**: Choose based on task complexity
4. **Permissions**: Follow principle of least privilege
5. **Rules**: Keep focused and single-purpose
6. **Prompt**: Be comprehensive but avoid redundancy
## Agent Network Architecture
```
┌─────────────────┐
│ Orchestrator │
│ (Router) │
└────────┬────────┘
│
┌───────────────────┼───────────────────┐
│ │ │
┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐
│ Primary │ │ Primary │ │ Primary │
│ Agents │ │ Agents │ │ Agents │
└─────┬─────┘ └─────┬─────┘ └─────┬─────┘
│ │ │
┌─────┴─────┐ ┌─────┴─────┐ ┌─────┴─────┐
│ Subagents │ │ Subagents │ │ Subagents │
└───────────┘ └───────────┘ └───────────┘
```

6
.kilo/kilo.jsonc
View File

@@ -80,6 +80,12 @@
"ask": {
"model": "ollama-cloud/gemini-3-flash",
"description": "Answers codebase questions"
},
"agent-architect": {
"model": "ollama-cloud/glm-5",
"description": "Manages agent network - creates, modifies, and optimizes agents according to Kilo.ai specification",
"mode": "primary",
"color": "#8B5CF6"
}
}
}

8
AGENTS.md
View File

@@ -28,6 +28,7 @@
| `@PromptOptimizer` | Improves agent prompts | ollama-cloud/claude-4.5 |
| `@ProductOwner` | Manages issue checklists | ollama-cloud/qwen3.5-122b |
| `@Orchestrator` | Routes tasks between agents | ollama-cloud/glm-5 |
| `@AgentArchitect` | Manages agent network per Kilo.ai spec | ollama-cloud/glm-5 |
## Workflow
@@ -35,4 +36,9 @@
[new] → HistoryMiner → [researching] → SystemAnalyst → [designing] → SDET
↓
[testing] → LeadDev → CodeSkeptic → [fail? TheFixer] → [pass] → Performance → Security → Release → Evaluator
```
```
## Architecture Documentation
- **KILO_SPEC.md** - Complete Kilo.ai specification for agent architecture
- **agent-architect.md** - Agent management and network configuration