@vodailoc/kilo-kit-mcp 1.1.0

package/README.md

@@ -0,0 +1,395 @@
+# 🚀 Kilo-Kit: Professional AI Agent Development Framework
+
+> **Version:** 1.0.0  
+> **Author:** Kilo-Kit Team  
+> **License:** Apache 2.0
+
+## 🎯 What is Kilo-Kit?
+
+**Kilo-Kit** is a comprehensive, modular framework for building and managing AI agent systems at scale (kilo-code = thousands of lines, hundreds of files). It introduces a revolutionary **Cognitive Flow Architecture (CFA)** that treats AI interactions as continuous flows rather than discrete events.
+
+### Core Philosophy
+
+```
+🧠 "Anticipate needs before they arise"
+🔄 "Learn from every interaction"
+📐 "Modularity enables scalability"
+🎯 "Quality over quantity in every token"
+💰 "Cost-aware intelligence"
+```
+
+## ✨ Key Innovations
+
+| Innovation | Description |
+|------------|-------------|
+| **Predictive Context Engine (PCE)** | Pre-loads context before you need it |
+| **Composable Behavior Units (CBU)** | Build workflows from micro-behaviors |
+| **Token Economy Manager (TEM)** | Smart budgeting for cost/quality balance |
+| **Decision Audit Trail (DAT)** | Full explainability for all decisions |
+| **Skill Effectiveness Tracker (SET)** | Self-improving skill system |
+| **Adaptive Routing** | Learns optimal skill selection over time |
+
+## ✨ Key Features
+
+| Feature | Description |
+|---------|-------------|
+| **Skill System** | Modular, loadable skills for specialized tasks |
+| **Adaptive Dispatch** | Intelligent skill routing that learns from usage |
+| **Progressive Disclosure** | Three-level context loading for efficiency |
+| **Context Engineering** | Token optimization and attention management |
+| **Quality Gates** | Mandatory checkpoints: typecheck → lint → test → build |
+| **TDD Workflow** | Test-first development with RED → GREEN → REFACTOR |
+| **Security First** | Input validation, parameterized queries, no hardcoded secrets |
+| **Multi-Stack Support** | TypeScript, Python, .NET, Go ready |
+
+## 💡 Skill Library
+
+`skills/` is the canonical workflow surface for Kilo-Kit. It supports the same **Progressive Disclosure** model as the core framework: scan the index first, load one skill body when routed, then open references/scripts only when needed.
+
+| Layer | Purpose |
+|-------|---------|
+| `skills/kilo-kit/` | Core Kilo-Kit framework skills and Hard-Gate workflows |
+| `skills/<category>/<skill>/` | Expanded skill library organized by execution domain |
+| `skills/README.md` | Human-facing catalog with category summaries and install commands |
+| `skills/SKILLS_INDEX.md` | Lightweight agent index for Predictive Context Engine prefetching |
+
+### Install the Full Skill Library
+
+This installs every valid `SKILL.md` under `skills/`, including Kilo-Kit core skills and the expanded category library.
+
+```bash
+npx skills@latest add VoDaiLocz/KILO-KIT
+```
+
+Use this when you want the entire Kilo-Kit workflow surface available in your agents.
+
+### Install a Category
+
+Use a category path when you only want one execution domain:
+
+```bash
+npx skills@latest add VoDaiLocz/KILO-KIT/skills/engineering
+```
+
+### Install a Single Skill
+
+```bash
+npx skills@latest add VoDaiLocz/KILO-KIT/skills/engineering/tdd
+```
+
+## 📁 Project Structure
+
+```
+kilo-kit/
+├── README.md                    # This file
+├── QUICKSTART.md               # 15-minute getting started guide
+├── CONTRIBUTING.md             # Contribution guidelines
+├── CHANGELOG.md                # Version history
+│
+├── .claude-plugin/             # Claude Code entry point
+│   └── instructions.md
+├── .cursor-plugin/             # Cursor IDE entry point
+│   └── instructions.md
+├── .codex/                     # OpenAI Codex entry point
+│   └── instructions.md
+├── .opencode/                  # OpenCode entry point
+│   └── instructions.md
+│
+├── skills/                     # Installable skill packs
+│   ├── README.md               # Human-facing skill catalog
+│   ├── SKILLS_INDEX.md         # Lightweight agent skill index
+│   ├── kilo-kit/               # Core Kilo-Kit skills
+│   │   ├── _template/          # Skill template
+│   │   ├── debugging/          # Debugging skills
+│   │   ├── development/        # Development skills
+│   │   └── quality/            # Quality assurance skills
+│   ├── engineering/            # Engineering and framework skills
+│   ├── productivity/           # Agent workflow skills
+│   ├── problem-solving/        # Debugging/reasoning skills
+│   ├── design/                 # UI/design skills
+│   └── ...                     # Games, ops, docs, AI media, security
+│
+├── commands/                   # Workflow commands
+│   ├── quality-gate.md         # Quality gate workflow
+│   ├── init-skill.md           # Skill initialization
+│   └── validate-skill.md       # Skill validation
+│
+├── src/                        # Core system source
+│   ├── core/                   # Core system components
+│   │   ├── KILO_MASTER.md     # Master skill file (entry point)
+│   │   ├── predictive-engine/  # Predictive Context Engine
+│   │   ├── routing-engine/     # Adaptive Routing Engine
+│   │   ├── execution-engine/   # Execution & Quality Gates
+│   │   └── knowledge-layer/    # Persistent Knowledge
+│   │
+│   ├── behaviors/              # Composable Behavior Units
+│   │   ├── atomic/             # Smallest behavior units
+│   │   ├── compound/           # Combined behaviors
+│   │   └── meta/               # Meta-behaviors
+│   │
+│   └── tools/                  # CLI and utility tools
+│       ├── init-skill.py       # Skill initializer
+│       ├── validate-skill.py   # Skill validator (Python)
+│       └── validate-skill.js   # Skill validator (Node.js)
+│
+├── docs/                       # Documentation
+│   ├── architecture/           # Architecture decisions
+│   ├── COMPLETION_ASSESSMENT.md
+│   ├── DEEP_ANALYSIS.md
+│   └── PROJECT_STRUCTURE.md
+│
+└── examples/                   # Real-world examples
+    ├── basic/                  # Basic usage patterns
+    ├── intermediate/           # Intermediate patterns
+    └── advanced/               # Advanced patterns
+```
+
+## 🚀 Quick Start
+
+### 1. Install
+
+```bash
+# Clone the repository
+git clone https://github.com/VoDaiLocz/KILO-KIT.git
+cd kilo-kit
+
+# No dependencies required - works out of the box!
+```
+
+### 2. Configure Your Agent
+
+Copy the master skill file to your agent's configuration:
+
+```bash
+# For most AI agents
+cp src/core/KILO_MASTER.md ~/.your-agent/KILO_MASTER.md
+
+# Update your agent's system prompt to reference it
+```
+
+### 3. Use Skills
+
+Skills are automatically loaded when your task matches their keywords. See the [Skill Dispatch Table](#-skill-dispatch-table) below.
+
+## 🔌 MCP Integration
+
+Kilo-Kit v1.1.0 includes a read-only MCP server that exposes the skill library as an adaptive routing service for MCP-capable agents.
+
+| MCP Surface | Purpose |
+|-------------|---------|
+| `kilo_route_intent` | Route the current chat request to the best Kilo-Kit skills |
+| `kilo_search_skills` | Search the skill catalog by task or keyword |
+| `kilo_get_skill` | Load one exact `SKILL.md` with context-safe truncation |
+| `kilo_validate_skills` | Run the skill validation quality gate |
+| `kilo://skills/index` | Resource view of the lightweight skill index |
+| `kilo://skills/{category}/{skill}` | Resource view for one skill |
+
+Install from npm in any MCP-capable client:
+
+```json
+{
+  "mcpServers": {
+    "kilo-kit": {
+      "command": "npx",
+      "args": ["-y", "@vodailoc/kilo-kit-mcp"]
+    }
+  }
+}
+```
+
+For local development, build and verify:
+
+```bash
+cd mcp
+npm install
+npm run build
+npm test
+npm run smoke
+```
+
+Local client config template:
+
+```json
+{
+  "mcpServers": {
+    "kilo-kit": {
+      "command": "node",
+      "args": ["<absolute-path-to-KILO-KIT>/mcp/dist/server.js"],
+      "env": {
+        "KILO_KIT_REPO_ROOT": "<absolute-path-to-KILO-KIT>"
+      }
+    }
+  }
+}
+```
+
+See [mcp/README.md](./mcp/README.md) and [.mcp/kilo-kit.example.json](./.mcp/kilo-kit.example.json).
+
+## 📋 Skill Dispatch Table
+
+| Task Keywords | Skill to Load |
+|---------------|---------------|
+| `bug, error, fix, debug` | `skills/kilo-kit/debugging/systematic/` |
+| `validate, validation` | `skills/kilo-kit/debugging/systematic/` |
+| `root cause, why` | `skills/kilo-kit/debugging/root-cause/` |
+| `verify, confirm` | `skills/kilo-kit/debugging/verification/` |
+| `review, PR, code review` | `skills/kilo-kit/quality/code-review/` |
+| `test, TDD, testing` | `skills/kilo-kit/quality/testing/` |
+| `security, auth, OWASP` | `skills/kilo-kit/development/security/` |
+| `API, backend, server` | `skills/kilo-kit/development/backend/` |
+
+## 🎓 Core Principles
+
+### 1. Cognitive Flow Architecture
+
+```
+Traditional:  Task → Process → Response (done)
+
+Kilo-Kit:     ┌─────────────────────────────┐
+              │      COGNITIVE FLOW         │
+              │                             │
+    Input ───►│  Predict → Execute → Learn  │───► Output
+              │      ↑              │       │
+    Next  ───►│      └──────────────┘       │───► Better
+              │                             │
+              └─────────────────────────────┘
+```
+
+### 2. Quality Gates (NEVER SKIP)
+
+```bash
+# Before EVERY commit
+typecheck → lint → test → build
+
+# All must pass. No exceptions.
+```
+
+### 3. The Three Pillars
+
+```
+ANTICIPATE → EXECUTE → LEARN → OPTIMIZE
+     ↑                            │
+     └────────────────────────────┘
+```
+
+### 4. Progressive Disclosure
+
+```
+Level 1: Metadata (always loaded, ~100 tokens)
+Level 2: SKILL.md body (when triggered, <5k tokens)  
+Level 3: References/Scripts (on-demand, unlimited)
+```
+
+## 🔧 Creating Custom Skills
+
+Use the skill template:
+
+```bash
+python src/tools/init-skill.py my-skill --path ./skills/kilo-kit/
+```
+
+This creates:
+
+```
+my-skill/
+├── SKILL.md           # Main instructions (required)
+├── references/        # Documentation to load as needed
+├── scripts/           # Executable utilities
+└── assets/            # Templates, images, etc.
+```
+
+### SKILL.md Format
+
+```yaml
+---
+name: my-skill
+description: >-
+  Clear description of what this skill does and when to use it.
+  Include keywords that should trigger this skill.
+version: 1.0.0
+behaviors: [behavior1, behavior2]
+token_estimate:
+  min: 500
+  typical: 1500
+  max: 5000
+---
+
+# My Skill
+
+## When to Use
+- Situation 1
+- Situation 2
+
+## Process
+1. Step 1
+2. Step 2
+
+## Guidelines
+- Guideline 1
+- Guideline 2
+
+## References
+- `references/detailed-guide.md` - For detailed instructions
+- `scripts/helper.py` - For automated tasks
+```
+
+## 📚 Documentation
+
+- **[QUICKSTART.md](./QUICKSTART.md)** - Get started in 15 minutes
+- **[docs/architecture/](./docs/architecture/)** - Architecture design documents
+- **[docs/PROJECT_STRUCTURE.md](./docs/PROJECT_STRUCTURE.md)** - Project structure guide
+- **[examples/](./examples/)** - Real-world usage examples
+
+## 🤝 Contributing
+
+We welcome contributions! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for:
+
+- Code of conduct
+- Development setup
+- Pull request process
+- Coding standards
+
+## 📊 Stack Preferences
+
+### TypeScript/JavaScript (2024-2025)
+| Category | Preferred | Avoid |
+|----------|-----------|-------|
+| Runtime | Bun, Node 20+ | Node <18 |
+| Backend | Hono, Elysia | Express |
+| ORM | Drizzle, Prisma 5+ | Sequelize |
+| Testing | Vitest, Playwright | Jest |
+| Package | pnpm, Bun | npm |
+
+### Python
+| Category | Preferred | Avoid |
+|----------|-----------|-------|
+| Runtime | Python 3.11+ | <3.9 |
+| Backend | FastAPI, Litestar | Flask |
+| ORM | SQLAlchemy 2.0 | <2.0 |
+| Validation | Pydantic v2 | v1 |
+| Linting | Ruff, mypy | flake8 |
+
+### .NET
+| Category | Preferred |
+|----------|-----------|
+| Framework | .NET 8+ |
+| Web | ASP.NET Core |
+| ORM | EF Core |
+| Testing | xUnit, NUnit |
+
+## 🏗️ Roadmap
+
+- [x] v1.0.0 - Core Cognitive Flow Architecture
+- [x] v1.1.0 - MCP Integration
+- [ ] v1.2.0 - Multi-Agent Orchestration
+- [ ] v2.0.0 - Visual Workflow Builder
+
+## 📄 License
+
+Apache 2.0 - See [LICENSE](./LICENSE) for details.
+
+---
+
+**Made with ❤️ for developers who value quality, efficiency, and scalability.**
+
+*Kilo-Kit — Where AI meets excellence.*

package/mcp/README.md

@@ -0,0 +1,132 @@
+# 🔌 Kilo-Kit MCP Server
+
+> **Version:** 1.1.0
+> **Mode:** Read-only Skill Registry + Validator
+> **Transport:** stdio
+
+The Kilo-Kit MCP server exposes the `skills/` workflow surface to MCP-capable agents. It lets agents route the current chat request to the right skill, load exactly one `SKILL.md`, and run the skill validation quality gate without granting write access.
+
+---
+
+## 🎯 Capabilities
+
+| Capability | MCP Tool | Purpose |
+|------------|----------|---------|
+| Skill discovery | `kilo_search_skills` | Search the skill library by task/query |
+| Intent routing | `kilo_route_intent` | Recommend skills for the current chat context |
+| Skill loading | `kilo_get_skill` | Load one exact `SKILL.md` with output limits |
+| Quality gate | `kilo_validate_skills` | Run the Kilo-Kit skill validator summary |
+
+Resources:
+
+| Resource | Purpose |
+|----------|---------|
+| `kilo://skills/index` | Lightweight skill index |
+| `kilo://core/master` | Kilo-Kit master skill |
+| `kilo://skills/{category}/{skill}` | Dynamic skill resource |
+
+Prompts:
+
+| Prompt | Purpose |
+|--------|---------|
+| `kilo-select-skill` | Route a request before implementation |
+| `kilo-validate-library` | Run the validation quality gate |
+
+---
+
+## 🚀 Build and Verify
+
+```bash
+cd mcp
+npm install
+npm run build
+npm test
+npm run smoke
+```
+
+Expected verification:
+
+```text
+Test Files  4 passed
+Tests       8 passed
+MCP smoke check passed.
+```
+
+---
+
+## ⚙️ Client Configuration
+
+Use the published npm package in any MCP-capable client:
+
+```json
+{
+  "mcpServers": {
+    "kilo-kit": {
+      "command": "npx",
+      "args": ["-y", "@vodailoc/kilo-kit-mcp"]
+    }
+  }
+}
+```
+
+The npm package includes the Kilo-Kit skill library, core master file, validator, and built MCP server.
+
+Maintainers publish the npm package from the repository root:
+
+```bash
+npm login
+npm publish --access public
+```
+
+The root `prepublishOnly` gate runs build, typecheck, tests, smoke, and skill validation before npm accepts the publish.
+
+### Local Development
+
+Build first:
+
+```bash
+cd mcp
+npm install
+npm run build
+```
+
+Then configure your MCP-capable client with stdio:
+
+```json
+{
+  "mcpServers": {
+    "kilo-kit": {
+      "command": "node",
+      "args": ["D:/skill/mcp/dist/server.js"],
+      "env": {
+        "KILO_KIT_REPO_ROOT": "D:/skill"
+      }
+    }
+  }
+}
+```
+
+Use `.mcp/kilo-kit.example.json` as the portable template.
+
+---
+
+## 🛡️ Security Posture
+
+- Read-only tools only.
+- No arbitrary filesystem reads.
+- Category and skill names must be single kebab-case path segments.
+- Repository paths are resolved through an allowlist boundary.
+- Tool output is capped to protect context budget.
+- Validation runs the existing Kilo-Kit validator and returns a concise summary.
+
+---
+
+## 🧠 Recommended Agent Flow
+
+```text
+User request
+→ kilo_route_intent(message, context)
+→ kilo_get_skill(category, skill)
+→ follow selected SKILL.md
+→ kilo_validate_skills before claiming the skill library is healthy
+```

package/mcp/dist/formatters.js

@@ -0,0 +1,77 @@
+export function textResponse(text) {
+    return { content: [{ type: "text", text }] };
+}
+export function formatSkills(skills, input, format) {
+    if (format === "json") {
+        return JSON.stringify({ query: input.query, skills }, null, 2);
+    }
+    if (skills.length === 0) {
+        return `No skills matched '${input.query}'. Try a broader query or inspect kilo://skills/index.`;
+    }
+    return [
+        `# Skill Search Results`,
+        ``,
+        `Query: \`${input.query}\``,
+        ``,
+        ...skills.map((skill, index) => `${index + 1}. **${skill.id}**\n   ${skill.description}\n   Path: \`${skill.skillPath}\``),
+    ].join("\n");
+}
+export function formatLoadedSkill(loaded, format) {
+    if (format === "json") {
+        return JSON.stringify(loaded, null, 2);
+    }
+    const references = loaded.skill.references.length > 0
+        ? loaded.skill.references.map((reference) => `- \`${reference}\``).join("\n")
+        : "- No bundled references/scripts/assets found.";
+    const truncation = loaded.truncated
+        ? `\n\n> Output truncated at ${loaded.maxChars} characters. Increase maxChars if you need more.`
+        : "";
+    return [
+        `# ${loaded.skill.id}`,
+        ``,
+        loaded.skill.description,
+        ``,
+        `Path: \`${loaded.skill.skillPath}\``,
+        ``,
+        `## References`,
+        references,
+        ``,
+        `## SKILL.md`,
+        ``,
+        "```md",
+        loaded.content,
+        "```",
+        truncation,
+    ].join("\n");
+}
+export function formatRoute(result, format) {
+    if (format === "json") {
+        return JSON.stringify(result, null, 2);
+    }
+    if (result.recommended.length === 0) {
+        return result.nextAction;
+    }
+    return [
+        "# Kilo-Kit Skill Route",
+        "",
+        ...result.recommended.map((item, index) => `${index + 1}. **${item.skill.id}** (${Math.round(item.confidence * 100)}%)\n   ${item.reason}\n   Path: \`${item.skill.skillPath}\``),
+        "",
+        `Next action: ${result.nextAction}`,
+    ].join("\n");
+}
+export function formatValidation(summary, format) {
+    if (format === "json") {
+        return JSON.stringify(summary, null, 2);
+    }
+    return [
+        "# Kilo-Kit Skill Validation",
+        "",
+        `Command: \`${summary.command}\``,
+        `Valid: **${summary.valid}/${summary.total}**`,
+        `Invalid: **${summary.invalid}**`,
+        "",
+        "```text",
+        summary.output,
+        "```",
+    ].join("\n");
+}

package/mcp/dist/frontmatter.js

@@ -0,0 +1,54 @@
+export function parseSkillFrontmatter(content) {
+    const match = content.match(/^---\s*\r?\n([\s\S]*?)\r?\n---/);
+    if (!match?.[1]) {
+        return {};
+    }
+    const yaml = match[1];
+    const frontmatter = {};
+    const name = parseScalar(yaml, "name");
+    const description = parseDescription(yaml);
+    if (name) {
+        frontmatter.name = name;
+    }
+    if (description) {
+        frontmatter.description = description;
+    }
+    return frontmatter;
+}
+function parseScalar(yaml, key) {
+    const match = yaml.match(new RegExp(`^${key}:\\s*(.+?)\\s*$`, "m"));
+    if (!match?.[1]) {
+        return undefined;
+    }
+    const raw = match[1].trim();
+    if (["|-", "|", ">-", ">"].includes(raw)) {
+        return undefined;
+    }
+    return cleanYamlScalar(raw);
+}
+function parseDescription(yaml) {
+    const block = yaml.match(/^description:\s*[>|]-?\s*\r?\n((?:[ \t]+.*\r?\n?)+)/m);
+    if (block?.[1]) {
+        return block[1]
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .join(" ")
+            .replace(/\s+version:\s+\S+.*$/, "")
+            .trim();
+    }
+    return parseScalar(yaml, "description");
+}
+function cleanYamlScalar(value) {
+    const trimmed = value.trim();
+    const quote = trimmed[0];
+    const unquoted = (quote === `"` || quote === `'`) && trimmed.endsWith(quote)
+        ? trimmed.slice(1, -1)
+        : trimmed;
+    return unquoted
+        .replaceAll("\\u2019", "’")
+        .replaceAll("\\u201c", "“")
+        .replaceAll("\\u201d", "”")
+        .replace(/\s+/g, " ")
+        .trim();
+}

package/mcp/dist/paths.js

@@ -0,0 +1,22 @@
+import path from "node:path";
+const SEGMENT_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+export function normalizeRepoRoot(repoRoot) {
+    return path.resolve(repoRoot);
+}
+export function assertSafeSegment(value, label) {
+    if (!SEGMENT_PATTERN.test(value)) {
+        throw new Error(`Invalid ${label} '${value}'. Use a single kebab-case path segment such as 'engineering' or 'tdd'.`);
+    }
+}
+export function toPosixPath(repoRoot, absolutePath) {
+    const relative = path.relative(repoRoot, absolutePath);
+    return relative.split(path.sep).join("/");
+}
+export function resolveInsideRepo(repoRoot, relativePath) {
+    const resolved = path.resolve(repoRoot, relativePath);
+    const relative = path.relative(repoRoot, resolved);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new Error(`Refusing to access path outside repository: ${relativePath}`);
+    }
+    return resolved;
+}