Kilo-Kit: Autonomous Cognitive Flow & Quality Engine for AI Coding Agents
Version: 1.9.1
Author: Kilo-Kit Team
License: Apache 2.0
Kilo-Kit is an agentic MCP runtime and curated 180-skill catalog designed to enforce grounded diagnosis, Tree-of-Thoughts architectural planning, adversarial red-teaming, 4D quality verification, and continuous SQLite self-improvement for AI coding assistants.
🧠 Core Architectural Pillars:
- Division of Labor (Cortex vs Limbs): Kilo-Kit acts as the high-level cognitive brain (Tree of Thoughts, 5-Whys root cause analysis, adversarial stress-testing, context compaction) while host clients handle surgical I/O.
- Kilo-Sentinel Supervisor & Circuit Breaker: Real-time middleware enforcing Pre-flight Grounding Locks (no editing unread files), loop tripwires (identical call and edit-thrashing detection), and SQLite trajectory logging (
katl_trajectories).
- Triangulated Cognitive Synthesis & Low-Confidence Escalation: Combines internal SQLite memory recall, GitHub 10k+ stars patterns, and ToT DAG benchmarking (
kilo_triangulate_research), with automatic subagent delegation when confidence < 0.70.
- Fuzzy Skill & Alias Resolver: Instant, resilient skill loading with support for aliases (
brainstorming, diagnose, playwright, clean-code, tdd, grounded-research-benchmark).
- 4D Quality Assurance & Playwright E2E Gate: Validates Given-When-Then acceptance criteria, clean code interfaces, UI/UX aesthetics, and automated Playwright browser/DOM verification before work is marked complete.
🏛️ System Architecture & Division of Labor
Kilo-Kit enforces a strict architectural boundary between High-Level Cognitive Reasoning (Cortex) and Surgical I/O Execution (Limbs):
flowchart TD
Clients["🖥️ Host AI Clients<br/>(Claude Code / Antigravity / Cursor / Gemini CLI)"]
Sentinel["🛡️ Kilo-Sentinel Supervisor & Circuit Breaker<br/>(Pre-flight Grounding Lock • Loop Tripwire • Step Budget)"]
subgraph Cortex["🧠 Kilo-Kit Cognitive Cortex (MCP Runtime)"]
direction TB
C4["🏛️ C4 5-Gate Lifecycle Controller"]
Engines["⚙️ 6 Cognitive Engines<br/>(ToT DAG • Adversarial Grill • 5-Whys • Grounded Synthesis)"]
Skills["📚 180 Curated Skills Catalog"]
Limbs["🛠️ Safe Execution Limbs<br/>(Atomic Write • AST Edit • Security Filtered Exec)"]
C4 --> Engines
C4 --> Skills
C4 --> Limbs
end
DB[("💾 SQLite Atomic Memory<br/>(cognitive_triangulations • katl_trajectories • facts)")]
Clients <-->|MCP Protocol / stdio| Sentinel
Sentinel <--> Cortex
Cortex <--> DB
🔄 C4 Cognitive Lifecycle & Low-Confidence Escalator
All agent tasks flow through a deterministic 5-Gate state machine. Unauthorized file mutations prior to Gate 3 approval are blocked at the server level:
flowchart LR
G1["<b>Gate 1: Grounded Probe</b><br/>• Memory Recall<br/>• Codebase Probe"]
G2["<b>Gate 2: Cognitive Reasoning</b><br/>• 3-Option ToT DAG<br/>• Adversarial Grill<br/>• Low-Confidence Escalator"]
G3["<b>Gate 3: Approval</b><br/>• Plan Locked<br/>• Skills Injected"]
G4["<b>Gate 4: Execution</b><br/>• Defense-in-Depth<br/>• Sentinel Guarded"]
G5["<b>Gate 5: 4D QA</b><br/>• Playwright E2E<br/>• SQLite Reflection"]
G1 --> G2
G2 -->|Confidence >= 0.70| G3
G2 -.->|Confidence < 0.70<br/>Escalation| Subagent["🔬 Research Subagent<br/>(GitHub & Docs Sandbox)"]
Subagent -.-> G2
G3 --> G4
G4 --> G5
G4 -.->|3x Loop Detected| Breaker["🛑 Circuit Breaker<br/>(Supervised Reset)"]
Breaker -.-> G1
🛡️ Protocol-Level Hard-Gate Enforcement
Traditional prompt rules (.cursorrules, CLAUDE.md) suffer from prompt drift. Kilo-Kit enforces safety via JSON-RPC Interceptor Middleware:
flowchart TD
Req["👤 User Prompt"] --> Agent["🤖 Host AI Agent"]
Agent -->|1. Unauthorized Edit Attempt| GateCheck{"🛡️ Kilo-Sentinel<br/>Pre-Flight Lock"}
GateCheck -->|❌ Uninitialized / Unread File| Blocked["🛑 403 Hard-Gate Blocked<br/>(Forces Planning First)"]
Blocked --> Plan["🧠 Gate 1 & 2: C4 Planning<br/>(kilo_orchestrate_task + kilo_triangulate_research)"]
Plan --> SaveDB[("💾 Commit CoT to SQLite")]
SaveDB --> Approval["👤 User Approves Plan"]
Approval -->|2. Authorized Execution| GateCheck
GateCheck -->|✅ State = READY| Exec["🚀 Gate 4: Safe Execution<br/>(kilo_write_file / kilo_edit_file)"]
Exec --> Verify["✅ Gate 5: 4D Verification & SQLite Reflection"]
Kilo-Kit provides a complete, self-contained execution and cognitive runtime:
📚 180 Curated Skills Catalog Taxonomy
Skills are organized into 6 functional modules with instant alias mapping:
skills/
├── 🏗️ engineering/ (39 skills)
│ ├── backend-development, codebase-design, api-patterns, database-design
│ ├── nextjs-best-practices, react-patterns, tailwind-patterns, aspnet-core, better-auth
├── 🧩 problem-solving/ (24 skills)
│ ├── sequential-thinking, root-cause-tracing, systematic-debugging
│ ├── collision-zone-thinking, scale-game, simplification-cascades, inversion-exercise
├── 📋 productivity/ (33 skills)
│ ├── brainstorming, spec-driven-development, tdd-workflow, code-review
│ ├── grounded-research-benchmark, verification-before-completion, grill-me, subagent-driven-development
├── 🤖 agent-frameworks/ (26 skills)
│ ├── workflow-state-machines, agent-memory, agentic-rag, multi-agent-orchestration
│ ├── mcp-agent-patterns, code-agent-patterns, context-optimization
├── 🛡️ security/ (22 skills)
│ ├── ai-guardrails, red-team-tactics, security-best-practices, vulnerability-scanner
└── ☁️ devops-cloud/ (36 skills)
├── devops, server-management, chrome-devtools, performance-profiling, render-deploy
Fuzzy Alias Resolution: Calling kilo_get_skill("brainstorming") automatically loads productivity/brainstorming/SKILL.md.
⚡ Quick Start
1. Fast Setup (Recommended)
Install globally and automatically configure all detected AI clients (Cursor, Claude, Windsurf, Antigravity, Gemini):
npm install -g @vodailocz/kilo-kit-mcp
kilo-kit-init global
Verify system health:
kilo-kit-doctor
2. Zero-Install NPX (IDE Direct Integration)
Add Kilo-Kit directly to your client's MCP configuration without installing globally:
{
"mcpServers": {
"kilo-kit": {
"command": "npx",
"args": ["-y", "@vodailocz/kilo-kit-mcp"]
}
}
}
Supported in Cursor (.cursor/mcp.json), Claude Desktop (claude_desktop_config.json), Windsurf, and Antigravity / Gemini CLI.
3. Team Repository Rollout
Bootstrap the Kilo-Kit C4 Cognitive Protocol into your project repository (CLAUDE.md, AGENTS.md, GEMINI.md):
kilo-kit-init init --client all
git add CLAUDE.md AGENTS.md GEMINI.md
git commit -m "chore: configure Kilo-Kit C4 protocol"
Or use the global git alias: git kilo-init
📊 Empirical Verification & Quality Benchmarks
📖 Documentation Directory Index
For detailed specifications, protocol definitions, and developer guides, explore the docs/ directory:
🧪 Development, Testing & Verification
# Clone repository
git clone https://github.com/VoDaiLocz/KILO-KIT.git
cd KILO-KIT
npm install
# Run unit test suites (15/15 test files, 68/68 tests passing)
npm test
# Run full health diagnostics
npm run doctor
# Validate 100% of 180 skills against structural quality gates
node src/tools/validate-skill.js --all skills
📄 License
Distributed under the Apache 2.0 License. See LICENSE for more details.
