From a0ef7cd02d3579883287ff0ffc23d1e5932c703a Mon Sep 17 00:00:00 2001 From: swp Date: Fri, 3 Apr 2026 20:27:54 +0100 Subject: [PATCH] feat: add Agent Architect and KILO_SPEC documentation - 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 --- .kilo/KILO_SPEC.md | 541 ++++++++++++++++++++++++++++++++ .kilo/agents/agent-architect.md | 235 ++++++++++++++ .kilo/kilo.jsonc | 6 + AGENTS.md | 8 +- 4 files changed, 789 insertions(+), 1 deletion(-) create mode 100644 .kilo/KILO_SPEC.md create mode 100644 .kilo/agents/agent-architect.md diff --git a/.kilo/KILO_SPEC.md b/.kilo/KILO_SPEC.md new file mode 100644 index 0000000..35b5882 --- /dev/null +++ b/.kilo/KILO_SPEC.md @@ -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" + } + } + } +} +``` \ No newline at end of file diff --git a/.kilo/agents/agent-architect.md b/.kilo/agents/agent-architect.md new file mode 100644 index 0000000..92281f8 --- /dev/null +++ b/.kilo/agents/agent-architect.md @@ -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 │ + └───────────┘ └───────────┘ └───────────┘ +``` \ No newline at end of file diff --git a/.kilo/kilo.jsonc b/.kilo/kilo.jsonc index fbfd133..357fe0c 100644 --- a/.kilo/kilo.jsonc +++ b/.kilo/kilo.jsonc @@ -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" } } } \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index 73ae421..f9a9e9e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 -``` \ No newline at end of file +``` + +## Architecture Documentation + +- **KILO_SPEC.md** - Complete Kilo.ai specification for agent architecture +- **agent-architect.md** - Agent management and network configuration \ No newline at end of file