Kilo Framework

AI agent framework for MikeLegal engineering teams. Built for Kilo Code with multi-agent orchestration.

Overview

Kilo Framework provides a cohesive multi-agent system for engineering teams using Kilo Code. It delivers specialized agents for different aspects of software development, from architecture planning to code implementation, testing, and documentation.

Features

• 13 Specialized Agents - Purpose-built agents for architecture, implementation, testing, review, and debugging
• 10 MCP Integrations - GitHub, Tavily, Sentry, GrepApp, and more connected via Model Context Protocol
• 6 Lifecycle Hooks - Protect production configs, enforce linting, prevent unsafe migrations
• 10 Rule Sets - Universal and stack-specific conventions loaded based on file patterns
• 8 Skills (internal) - On-demand instructions for testing, patterns, and debugging
• Multi-Agent Orchestration - Automatic task delegation and parallel execution
• Auto-Updates - Framework updates automatically on Kilo Code restart
• Zero Configuration - Works out of the box with sensible defaults
• Customizable - Extend with your own skills, rules, and agent configurations

Quick Start

Add the plugin to your Kilo Code configuration:

~/.config/kilo/kilo.json

{
  "plugin": ["@mikelegal/kilo-framework"]
}

Add required environment variables to your shell profile:

# GitHub (https://github.com/settings/tokens)
export KILO_GITHUB_TOKEN="ghp_your_token"

# Tavily (https://tavily.com/api-keys)
export KILO_TAVILY_API_KEY="tvly_your_key"

# Sentry (https://sentry.io/settings/account/api/auth-tokens/)
export KILO_SENTRY_AUTH_TOKEN="your_token"

# Ref (https://ref.ai/settings/api-keys)
export KILO_REF_API_KEY="ref_your_key"

# Coda (https://coda.io/account/settings/api-tokens)
export KILO_CODA_API_TOKEN="coda_your_key"

Optional MCPs: Figma and Playwright MCPs are disabled by default — enable them via the Kilo Code UI when needed for specific tasks. All other MCPs (including Sentry) are enabled automatically.

Restart Kilo Code and all agents are available immediately.

The framework updates automatically when you restart Kilo Code.

Installation

Add to your ~/.config/kilo/kilo.json:

{
  "plugin": ["@mikelegal/kilo-framework"]
}

Restart Kilo Code to install and activate the framework.

Architecture

The framework consists of 13 specialized agents, 10 MCP integrations, 6 lifecycle hooks, 10 rule sets, and 8 skills working together.

flowchart TB
    subgraph "User Layer"
        User(["User"])
    end

    subgraph "Kilo Code"
        Kilo["Kilo Code CLI/Extension"]
        PluginSystem["Plugin System"]
    end

    subgraph "Kilo Framework"
        direction TB
        
        subgraph "Primary Agents"
            Architect["architect<br/>Planning & Specs"]
            Coder["coder<br/>Orchestrator"]
            Refactor["refactor<br/>Quality"]
        end

        subgraph "Implementation Agents"
            Backend["backend<br/>Django/Python"]
            Frontend["frontend<br/>React/TypeScript"]
        end

        subgraph "Testing Agents"
            TestBackend["test-backend<br/>pytest"]
            TestFrontend["test-frontend<br/>Vitest"]
        end

        subgraph "Review Agents"
            CodeReview["code-review<br/>Quality Review"]
            SecurityReview["security-review<br/>Security Audit"]
        end

        subgraph "Utility Agents"
            Explorer["explorer<br/>Codebase Navigation"]
            Researcher["researcher<br/>External Research"]
            DocWriter["doc-writer<br/>Documentation"]
            Bugfix["bugfix<br/>Debugging"]
        end

        subgraph "Configuration & Context"
            PluginConfig["Plugin Config Hook"]
            subgraph "Rules (Always Loaded)"
                UnivRules["Universal (4)"]
                StackRules["Stack-Specific (6)"]
            end
            subgraph "Skills (On-Demand)"
                IntSkills["Internal (8)"]
            end
            subgraph "Hooks (Lifecycle)"
                SafetyHooks["Safety (3)"]
                QualityHooks["Quality (3)"]
            end
        end
    end

    subgraph "MCP Servers"
        GitHub["GitHub MCP"]
        Tavily["Tavily MCP"]
        Sentry["Sentry MCP"]
        GrepApp["GrepApp MCP"]
        Figma["Figma MCP"]
    end

    User --> Kilo
    Kilo --> PluginSystem
    PluginSystem --> PluginConfig
    PluginConfig --> Architect
    PluginConfig --> Coder
    PluginConfig --> Refactor

    Coder --> Backend
    Coder --> Frontend
    Coder --> TestBackend
    Coder --> TestFrontend
    Coder --> CodeReview
    Coder --> SecurityReview
    Coder --> Explorer
    Coder --> Researcher
    Coder --> DocWriter
    Coder --> Bugfix

    Backend --> GitHub
    Frontend --> Figma
    Researcher --> Tavily
    Explorer --> GrepApp
    Coder --> Sentry

Workflow

sequenceDiagram
    participant User
    participant Kilo as Kilo Code
    participant Architect as architect
    participant Coder as coder
    participant Backend as backend
    participant Frontend as frontend
    participant Test as test-*
    participant Review as code-review
    participant Security as security-review

    User->>Kilo: New Feature Request
    Kilo->>Architect: Create spec
    Architect-->>Kilo: spec.md
    
    User->>Kilo: Approve spec
    Kilo->>Coder: Start implementation
    
    par Parallel Implementation
        Coder->>Backend: Implement API
        Coder->>Frontend: Implement UI
    end
    
    Backend-->>Coder: Complete
    Frontend-->>Coder: Complete
    
    par Parallel Testing
        Coder->>Test: Test backend
        Coder->>Test: Test frontend
    end
    
    Test-->>Coder: Tests pass
    
    Coder->>Review: Quality review
    Coder->>Security: Security audit
    
    Review-->>Coder: Approved
    Security-->>Coder: Approved
    
    Coder-->>Kilo: PR ready
    Kilo-->>User: Implementation complete

Agent Reference

Primary Agents

| Agent | Role | Mode | Description | |-------|------|------|-------------| | architect | Technical Planning | primary | Transforms GitHub issues into detailed technical specs | | coder | Orchestrator | primary | Coordinates all subagents for implementation | | refactor | Quality | primary | Improves code quality without changing behavior |

Implementation Agents

| Agent | Role | Mode | Description | |-------|------|------|-------------| | backend | Django/Python | subagent | Implements backend features, APIs, models | | frontend | React/TypeScript | subagent | Implements React components, hooks, and UI |

Testing Agents

| Agent | Role | Mode | Description | |-------|------|------|-------------| | test-backend | pytest | subagent | Writes Django/Python tests | | test-frontend | Vitest | subagent | Writes React/TypeScript tests |

Review Agents

| Agent | Role | Mode | Description | |-------|------|------|-------------| | code-review | Quality Review | subagent | Reviews code for quality and best practices | | security-review | Security Audit | subagent | Audits code for security vulnerabilities |

Utility Agents

| Agent | Role | Mode | Description | |-------|------|------|-------------| | explorer | Codebase Navigation | subagent | Fast codebase exploration and navigation | | researcher | External Research | subagent | Researches APIs, documentation, best practices | | doc-writer | Documentation | subagent | Updates documentation after implementation | | bugfix | Debugging | subagent | Investigates and fixes bugs with Sentry integration |

Slash Commands

| Command | Trigger | Description | |---------|---------|-------------| | /fix-pr-comments [pr-number] | coder agent | Read and fix CRITICAL/MAJOR PR review comments | | /onboard-repo | architect agent | Initialize new repo with hierarchical AGENTS.md files | | /tech-debt-scan | refactor agent | Scan for technical debt and generate prioritized report | | /research [topic] | researcher agent | External research on libraries, APIs, and documentation |

Command Details

/fix-pr-comments

Fetches all open CRITICAL and MAJOR review comments on a PR and implements fixes automatically. Commits changes with descriptive messages.

Usage:

/fix-pr-comments 123

/onboard-repo

Deep scans repository structure and creates hierarchical AGENTS.md files:

• Root AGENTS.md with project overview
• App-level AGENTS.md for Django apps
• Component-level AGENTS.md for frontend features
• Bruno API collection structure (for backend repos)

Usage:

/onboard-repo

/tech-debt-scan

Analyzes codebase for technical debt:

• Linter violations (ruff, eslint)
• Test coverage gaps
• TODO/FIXME comments
• Outdated dependencies
• Code complexity issues

Generates report at .kilo/plans/tech-debt-{date}.md and creates GitHub issue.

Usage:

/tech-debt-scan

/research

Performs external research using Tavily and Ref MCP:

• Library documentation and changelogs
• API specifications
• Best practices and patterns
• Version compatibility

Usage:

/research Django 5.0 migration from 4.2
/research React Query v5 best practices

Hooks

Lifecycle automations that protect the codebase and enforce quality gates.

| Hook | Trigger | Description | |------|---------|-------------| | production-guard | beforeEdit | Warns when editing production config files | | migration-gate | beforeEdit/beforeBash | Blocks risky migrations, requires approval for makemigrations | | read-before-write | beforeEdit | Warns when editing files without reading related files first | | auto-ruff | afterEdit | Runs ruff linter on Python files after edit | | auto-eslint | afterEdit | Runs ESLint on JS/TS files after edit | | auto-prettier | afterEdit | Formats code with Prettier after edit |

Hooks intercept file operations and bash commands to enforce team standards and prevent common mistakes.

Rules

Always-loaded context that provides conventions and standards. Rules are pattern-matched to files.

Universal Rules (always loaded)

| Rule | Description | |------|-------------| | git-workflow | Git command allowlist and commit conventions | | security-rules | Security best practices and prohibited patterns | | testing-standards | Testing requirements and coverage expectations | | code-review-standards | Review criteria and approval requirements |

Stack-Specific Rules (pattern-matched)

| Rule | Pattern | Description | |------|---------|-------------| | env-rules | manage.py, pyproject.toml | Environment variable handling | | django-conventions | **/*.py | Django/GraphQL backend patterns | | react-conventions | **/*.tsx | React/TypeScript frontend patterns | | graphql-conventions | **/schema/**/* | GraphQL schema conventions | | nx-conventions | nx.json | Nx monorepo patterns | | vite-conventions | vite.config.* | Vite build tool conventions |

Skills

On-demand instructions invoked by agents for specific tasks. Unlike rules (always loaded), skills are loaded only when needed.

Internal Skills (included)

| Skill | Description | |-------|-------------| | django-testing | pytest, factory_boy, and GraphQL test patterns | | react-testing | Vitest, React Testing Library, and component tests | | django-graphene-patterns | GraphQL resolver and mutation patterns | | react-graphql-patterns | Apollo Client and GraphQL integration | | migration-safety | Safe database migration practices | | celery-patterns | Background task and Celery patterns | | sentry-debug | Error debugging with Sentry integration | | playwright-cli | E2E testing automation |

Agents invoke skills automatically based on context, or you can request them explicitly: Use skill: django-testing.

Configuration

The framework registers agents, MCPs, rules, and skills programmatically via the plugin's config hook.

1. ~/.config/kilo/kilo.json - Main Kilo config (minimal, just plugin reference)
2. ~/.config/kilo/kilo-framework.json - (Optional) User configuration for extra_mcps, extra_skills, and extra_rules

Rules are loaded based on file patterns (e.g., django-conventions only loads for *.py files). See AGENTS.md for detailed configuration documentation.

MCP Configuration

Required environment variables:

| Variable | Source | Required For | |----------|--------|--------------| | KILO_GITHUB_TOKEN | https://github.com/settings/tokens | GitHub integration | | KILO_TAVILY_API_KEY | https://tavily.com/api-keys | Web search | | KILO_SENTRY_AUTH_TOKEN | https://sentry.io/settings/account/api/auth-tokens/ | Error tracking | | KILO_REF_API_KEY | https://ref.ai/settings/api-keys | Documentation search | | KILO_CODA_API_TOKEN | https://coda.io/account/settings/api-tokens | Documentation access |

Development

Project Structure

kilo-framework/
├── src/
│   ├── agents/          # Agent prompt definitions
│   ├── commands/        # Slash command definitions
│   ├── skills/          # Skill definitions
│   ├── rules/           # Rule files
│   └── hooks/           # Lifecycle hooks
├── dist/                # Built plugin code
├── prompts/             # Prompt templates (empty)
├── scripts/             # Build and utility scripts (empty)
├── docs/                # Documentation
│   └── npm-publishing.md
├── package.json
├── README.md
└── AGENTS.md

Scripts

bun run build          # Build the project
bun run typecheck      # Type checking
npm test               # Run tests
npm run lint           # Run linting
npm run clean          # Clean build artifacts

Publishing

See docs/npm-publishing.md for detailed publishing instructions.

License

Non-Commercial Use Only

This software is available for:

• ✅ Open source projects
• ✅ Personal/non-commercial use
• ✅ Educational purposes

Not available for commercial use without explicit permission.

See LICENSE for full terms.

Acknowledgments

This framework was built for the MikeLegal engineering team to standardize AI-assisted development workflows using Kilo Code.