@vodailoc/kilo-kit-mcp 1.3.0 → 1.3.1

package/README.md

@@ -1,450 +1,289 @@
-<p align="center">
-  <img src="assets/social-preview.png" alt="Kilo-Kit social preview" width="100%">
-</p>
+# Kilo-Kit
 
-<p align="center">
-  <a href="https://github.com/VoDaiLocz/KILO-KIT/stargazers"><img src="https://img.shields.io/github/stars/VoDaiLocz/KILO-KIT?style=for-the-badge&logo=github&label=Stars&color=18181b&labelColor=0f172a" alt="GitHub stars"></a>
-  <a href="https://github.com/VoDaiLocz/KILO-KIT/commits/main"><img src="https://img.shields.io/github/last-commit/VoDaiLocz/KILO-KIT?style=for-the-badge&logo=git&label=Last%20commit&color=22c55e&labelColor=0f172a" alt="Last commit"></a>
-  <a href="https://github.com/VoDaiLocz/KILO-KIT/graphs/contributors"><img src="https://img.shields.io/github/contributors/VoDaiLocz/KILO-KIT?style=for-the-badge&logo=github&label=Contributors&color=f97316&labelColor=0f172a" alt="Contributors"></a>
-  <a href="https://github.com/VoDaiLocz/KILO-KIT/actions/workflows/publish.yml"><img src="https://img.shields.io/github/actions/workflow/status/VoDaiLocz/KILO-KIT/publish.yml?style=for-the-badge&logo=githubactions&label=Publish&color=22c55e&labelColor=0f172a" alt="Publish workflow"></a>
-  <a href="https://www.npmjs.com/package/@vodailoc/kilo-kit-mcp"><img src="https://img.shields.io/npm/v/@vodailoc/kilo-kit-mcp?style=for-the-badge&logo=npm&label=npm&color=ef4444&labelColor=0f172a" alt="npm version"></a>
-  <a href="https://www.npmjs.com/package/@vodailoc/kilo-kit-mcp"><img src="https://img.shields.io/npm/dm/@vodailoc/kilo-kit-mcp?style=for-the-badge&logo=npm&label=downloads&color=0284c7&labelColor=0f172a" alt="npm downloads"></a>
-  <a href="LICENSE"><img src="https://img.shields.io/github/license/VoDaiLocz/KILO-KIT?style=for-the-badge&label=License&color=64748b&labelColor=0f172a" alt="License"></a>
-</p>
+Kilo-Kit is a local-first skill and orchestration framework for MCP-capable coding agents.
 
-<p align="center">
-  <img src="https://img.shields.io/badge/skills-134-06b6d4?style=for-the-badge&labelColor=0f172a" alt="134 skills">
-  <img src="https://img.shields.io/badge/MCP-ready-14b8a6?style=for-the-badge&logo=modelcontextprotocol&labelColor=0f172a" alt="MCP ready">
-  <img src="https://img.shields.io/badge/Codex-ready-111827?style=for-the-badge&logo=openai&labelColor=0f172a" alt="Codex ready">
-  <img src="https://img.shields.io/badge/Trusted%20Publishing-OIDC-8b5cf6?style=for-the-badge&logo=githubactions&labelColor=0f172a" alt="Trusted publishing">
-  <img src="https://img.shields.io/badge/Node-%3E%3D20-339933?style=for-the-badge&logo=nodedotjs&labelColor=0f172a" alt="Node >=20">
-  <img src="https://img.shields.io/badge/TypeScript-5.9-3178c6?style=for-the-badge&logo=typescript&labelColor=0f172a" alt="TypeScript 5.9">
-</p>
+It packages a curated `skills/` library, an MCP server, and a C4 orchestration gate that turns a user request into an auditable workflow:
 
-# 🚀 Kilo-Kit: Professional AI Agent Development Framework
-
-> **Version:** 1.3.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"
+```text
+request -> route -> brainstorming gate -> memory confirmation -> workflow release -> verification gate
 ```
 
-## ✨ 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 |
+The published package is `@vodailoc/kilo-kit-mcp`.
 
-## ✨ Key Features
+## What It Provides
 
-| 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 |
+| Area | Purpose |
+| --- | --- |
+| Skill library | Installable `SKILL.md` workflows grouped by engineering, productivity, debugging, design, operations, docs, and more. |
+| MCP server | stdio server exposing routing, skill loading, validation, C4 orchestration, memory, and route reports. |
+| C4 gate | A closed-loop workflow gate that blocks substantive work until the real brainstorming skill has been followed and approved. |
+| Memory | Optional SQLite-backed facts, decisions, sessions, and workflow outcomes. |
+| Audit | Optional JSONL trail for C4 state transitions and route decisions. |
+| Verification | A returned verification gate that agents must satisfy before claiming completion. |
 
-## 💡 Skill Library
+## Install In Two Steps
 
-`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.
+Step 1: install the MCP server in your client.
 
-| 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 |
+Use the published package in any MCP-capable host:
 
-### Install the Full Skill Library
+```json
+{
+  "mcpServers": {
+    "kilo-kit": {
+      "command": "npx",
+      "args": ["-y", "@vodailoc/kilo-kit-mcp"]
+    }
+  }
+}
+```
 
-This installs every valid `SKILL.md` under `skills/`, including Kilo-Kit core skills and the expanded category library.
+Step 2: bootstrap the host-agent rule in your project.
 
 ```bash
-npx skills@latest add VoDaiLocz/KILO-KIT
+npx -y --package=@vodailoc/kilo-kit-mcp kilo-kit-init init --client gemini
+npx -y --package=@vodailoc/kilo-kit-mcp kilo-kit-init init --client codex
+npx -y --package=@vodailoc/kilo-kit-mcp kilo-kit-init init --client claude
 ```
 
-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:
+Or initialize all supported host files:
 
 ```bash
-npx skills@latest add VoDaiLocz/KILO-KIT/skills/engineering
+npx -y --package=@vodailoc/kilo-kit-mcp kilo-kit-init init --client all
 ```
 
-### Install a Single Skill
+This writes an idempotent Kilo-Kit C4 block to:
 
-```bash
-npx skills@latest add VoDaiLocz/KILO-KIT/skills/engineering/tdd
-```
+| Client | File |
+| --- | --- |
+| Gemini CLI | `GEMINI.md` |
+| OpenAI Codex | `AGENTS.md` |
+| Claude Code | `CLAUDE.md` |
 
-## 📁 Project Structure
+The block is wrapped in `KILO-KIT:C4` markers, so running the command again updates the Kilo-Kit section without deleting your existing project rules.
 
-```
-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
+For Codex CLI on Windows, use an npm prefix outside the source checkout so npm does not resolve a local checkout:
+
+```toml
+[mcp_servers.kilo-kit]
+command = "npm"
+args = ["exec", "--prefix", "C:\\Users\\Admin", "--yes", "--package=@vodailoc/kilo-kit-mcp", "--", "kilo-kit-mcp"]
+startup_timeout_sec = 60
+enabled = true
 ```
 
-## 🚀 Quick Start
+## Why Bootstrap Is Needed
 
-### 1. Install
+MCP exposes tools, prompts, resources, and server instructions. It does not force every host agent to call those tools automatically.
 
-```bash
-# Clone the repository
-git clone https://github.com/VoDaiLocz/KILO-KIT.git
-cd kilo-kit
+Kilo-Kit ships the C4 rule in four places:
 
-# No dependencies required - works out of the box!
-```
+- MCP server instructions.
+- MCP resource `kilo://rules/c4`.
+- MCP prompt `kilo-c4-workflow`.
+- Host bootstrap files created by `kilo-kit-init`.
 
-### 2. Configure Your Agent
+The bootstrap file is the reliable part. It tells the host agent to call C4 before implementation instead of waiting for the user to manually request MCP usage.
 
-Copy the master skill file to your agent's configuration:
+## C4 Workflow
 
-```bash
-# For most AI agents
-cp src/core/KILO_MASTER.md ~/.your-agent/KILO_MASTER.md
+`kilo_orchestrate_task` is the main C4 entry point. It does not execute code. It routes the request, records state, and releases the next workflow only when the gate conditions are satisfied.
+
+The intended flow is:
 
-# Update your agent's system prompt to reference it
+```text
+1. User sends a substantive task.
+2. Agent calls kilo_orchestrate_task(message, context).
+3. C4 routes the task and injects productivity/brainstorming first.
+4. State becomes brainstorming_required.
+5. Agent loads productivity/brainstorming with kilo_get_skill.
+6. Agent follows that skill and gets user approval.
+7. Agent calls kilo_orchestrate_task again with the same sessionId and brainstormingApproved=true.
+8. C4 checks memory suggestions.
+9. If suggestions exist, state becomes awaiting_memory_confirmation.
+10. Agent accepts or rejects suggestions with memoryConfirmations.
+11. State becomes ready.
+12. C4 returns finalWorkflow without productivity/brainstorming.
+13. Agent loads the first workflow skill with kilo_get_skill.
+14. Agent also checks its internal skill list for other relevant skills before coding.
+15. Agent executes the workflow and satisfies the returned verificationGate before completion.
 ```
 
-### 3. Use Skills
+Read-only requests such as status, show, read, or explain can skip the brainstorming gate.
 
-Skills are automatically loaded when your task matches their keywords. See the [Skill Dispatch Table](#-skill-dispatch-table) below.
+### C4 States
 
-## 🔌 MCP Integration
+| State | Meaning |
+| --- | --- |
+| `brainstorming_required` | Substantive work is blocked until `productivity/brainstorming` is loaded, followed, and approved by the user. |
+| `awaiting_memory_confirmation` | C4 found remembered operating preferences. The agent must accept or reject them before execution. |
+| `ready` | C4 has released the post-brainstorming workflow and verification gate. |
 
-Kilo-Kit v1.3.0 includes a read-only MCP server that exposes the skill library as an adaptive routing service for MCP-capable agents.
+### Returned Workflow
 
-| MCP Surface | Purpose |
-|-------------|---------|
-| `kilo_orchestrate_task` | C4 central gate: require the real `/brainstorming` skill first, then log/route the approved task and release the post-brainstorming workflow |
-| `kilo_route_intent` | Route the current chat request to skills, workflow order, rule hierarchy, and decision trail |
-| `kilo_search_skills` | Search the skill catalog by task or keyword |
-| `kilo_get_skill` | Load one exact `SKILL.md` with context-safe truncation |
-| `kilo_route_report` | Summarize route telemetry, top skills, workflows, and conflict penalties |
-| `kilo_memory_report` | Inspect C4 global memory facts, decisions, and suggestions |
-| `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 |
+When C4 is ready, it returns:
 
-Install from npm in any MCP-capable client:
+- `finalWorkflow`: ordered Kilo-Kit skill steps for the task mode.
+- `firstSkillToLoad`: first skill the agent should load with `kilo_get_skill`.
+- `verificationGate`: commands and rationale that must pass before completion.
+- `nextAction`: the immediate instruction for the agent.
+- `auditRef`: present when orchestration audit JSONL is enabled.
 
-```json
-{
-  "mcpServers": {
-    "kilo-kit": {
-      "command": "npx",
-      "args": ["-y", "@vodailoc/kilo-kit-mcp"]
-    }
-  }
-}
-```
+The returned workflow is a primary route, not the only context source. Agents must also inspect their own available skill list and load any other relevant skills before implementation.
 
-Recommended Codex CLI config on Windows:
+## MCP Tools
 
-```toml
-[mcp_servers.kilo-kit]
-command = "npm"
-args = ["exec", "--prefix", "C:\\Users\\Admin", "--yes", "--package=@vodailoc/kilo-kit-mcp", "--", "kilo-kit-mcp"]
-startup_timeout_sec = 60
-enabled = true
-```
+| Tool | Purpose |
+| --- | --- |
+| `kilo_orchestrate_task` | C4 gate for substantive work. Routes internally, enforces brainstorming first, checks memory, and releases the final workflow. |
+| `kilo_route_intent` | Routes a request to recommended skills, task mode, workflow order, rule hierarchy, and decision trail. |
+| `kilo_search_skills` | Searches the skill catalog by natural-language query. |
+| `kilo_get_skill` | Loads one exact `SKILL.md` with context-safe truncation. |
+| `kilo_route_report` | Reports route telemetry, top skills, workflows, score averages, and conflict penalties. |
+| `kilo_memory_report` | Reports C4 memory facts, decisions, suggestions, sessions, and workflow outcomes. |
+| `kilo_validate_skills` | Runs the skill validation gate. |
 
-The `--prefix` keeps npm from resolving the local source checkout when Codex is opened inside the Kilo-Kit repository.
+## MCP Resources
 
-Route telemetry is kept in memory by default. Set `KILO_KIT_WRITE_DECISIONS=true` to persist JSONL route decisions under `.kilo/decision-trail.jsonl`, or set `KILO_KIT_DECISION_TRAIL_PATH` to choose a different file.
+| Resource | Purpose |
+| --- | --- |
+| `kilo://skills/index` | Lightweight skill index for discovery. |
+| `kilo://core/master` | Core Kilo-Kit master instructions. |
+| `kilo://rules/c4` | Minimal host-agent operating rules for the C4 workflow. |
+| `kilo://skills/{category}/{skill}` | Dynamic skill resource for one skill. |
 
-C4 orchestration memory is global by default at `~/.kilo-kit/orchestrator.sqlite` when Node's SQLite runtime is available. Set `KILO_KIT_MEMORY_PATH` to use a different SQLite file, and set `KILO_KIT_ORCHESTRATION_AUDIT_PATH` to write an append-only JSONL audit trail for C4 state transitions.
+## Persistence
 
-For local development, build and verify:
+Route telemetry is in memory by default. Enable JSONL decision persistence with:
 
 ```bash
-cd mcp
-npm install
-npm run build
-npm test
-npm run smoke
+KILO_KIT_WRITE_DECISIONS=true
+KILO_KIT_DECISION_TRAIL_PATH=/absolute/path/decision-trail.jsonl
 ```
 
-Local client config template:
+If `KILO_KIT_DECISION_TRAIL_PATH` is not set, route decisions are written to `.kilo/decision-trail.jsonl` under `KILO_KIT_REPO_ROOT`.
 
-```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>"
-      }
-    }
-  }
-}
-```
+C4 memory uses `node:sqlite` when available and defaults to:
 
-See [mcp/README.md](./mcp/README.md) and [.mcp/kilo-kit.example.json](./.mcp/kilo-kit.example.json).
-
-### Maintainer Release Flow
+```text
+~/.kilo-kit/orchestrator.sqlite
+```
 
-Kilo-Kit publishes `@vodailoc/kilo-kit-mcp` through npm Trusted Publishing. Configure npm once with:
+Override C4 paths with:
 
-| Field | Value |
-|-------|-------|
-| Provider | GitHub Actions |
-| Repository | `VoDaiLocz/KILO-KIT` |
-| Workflow filename | `publish.yml` |
+```bash
+KILO_KIT_MEMORY_PATH=/absolute/path/orchestrator.sqlite
+KILO_KIT_ORCHESTRATION_AUDIT_PATH=/absolute/path/orchestration-audit.jsonl
+```
 
-After that, run the GitHub Actions workflow `Publish npm package`, or push a version tag such as `v1.3.0`. The workflow uses OIDC, so it does not need an npm token or interactive OTP.
+C4 memory stores structured facts, decisions, orchestration sessions, and workflow outcomes. The audit file stores append-only state transition events.
 
-## 📋 Skill Dispatch Table
+## Skill Library
 
-| 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/` |
+`skills/` is the workflow surface shipped with the package.
 
-## 🎓 Core Principles
+| Path | Purpose |
+| --- | --- |
+| `skills/SKILLS_INDEX.md` | Lightweight index for routing and discovery. |
+| `skills/kilo-kit/` | Core Kilo-Kit framework skills. |
+| `skills/engineering/` | Engineering and framework workflows. |
+| `skills/productivity/` | Agent workflow and planning skills. |
+| `skills/problem-solving/` | Debugging and reasoning skills. |
+| `skills/design/` | Frontend and product design skills. |
+| `skills/operations/` | DevOps, MCP, shell, browser, and server skills. |
+| `skills/writing-docs/` | Documents, slides, PDFs, spreadsheets, and diagrams. |
 
-### 1. Cognitive Flow Architecture
+Install the full skill library:
 
-```
-Traditional:  Task → Process → Response (done)
-
-Kilo-Kit:     ┌─────────────────────────────┐
-              │      COGNITIVE FLOW         │
-              │                             │
-    Input ───►│  Predict → Execute → Learn  │───► Output
-              │      ↑              │       │
-    Next  ───►│      └──────────────┘       │───► Better
-              │                             │
-              └─────────────────────────────┘
+```bash
+npx skills@latest add VoDaiLocz/KILO-KIT
 ```
 
-### 2. Quality Gates (NEVER SKIP)
+Install one category:
 
 ```bash
-# Before EVERY commit
-typecheck → lint → test → build
-
-# All must pass. No exceptions.
+npx skills@latest add VoDaiLocz/KILO-KIT/skills/engineering
 ```
 
-### 3. The Three Pillars
+Install one skill:
 
-```
-ANTICIPATE → EXECUTE → LEARN → OPTIMIZE
-     ↑                            │
-     └────────────────────────────┘
+```bash
+npx skills@latest add VoDaiLocz/KILO-KIT/skills/engineering/tdd
 ```
 
-### 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)
+## Repository Layout
+
+```text
+.
+|-- .claude-plugin/       Claude Code entry instructions
+|-- .codex/               Codex entry instructions
+|-- .cursor-plugin/       Cursor entry instructions
+|-- .mcp/                 MCP config examples
+|-- .opencode/            OpenCode entry instructions
+|-- commands/             Reusable workflow commands
+|-- docs/                 Architecture and planning documents
+|-- examples/             Example workflows
+|-- mcp/                  TypeScript MCP server
+|-- skills/               Installable skill library
+|-- src/core/             Core framework docs and validator entry files
+`-- src/tools/            Skill initialization and validation tools
 ```
 
-## 🔧 Creating Custom Skills
+## Local Development
 
-Use the skill template:
+Install, build, test, and smoke-check the MCP server:
 
 ```bash
-python src/tools/init-skill.py my-skill --path ./skills/kilo-kit/
+npm --prefix mcp install
+npm --prefix mcp run build
+npm --prefix mcp run typecheck
+npm --prefix mcp test
+npm --prefix mcp run smoke
+node src/tools/validate-skill.js --all skills
 ```
 
-This creates:
+Use a local MCP server during development:
 
+```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"
+      }
+    }
+  }
+}
 ```
-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
+## Release
 
-### 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 |
+The root package publishes through npm Trusted Publishing from GitHub Actions.
 
-### 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 |
+Configure npm once:
 
-### .NET
-| Category | Preferred |
-|----------|-----------|
-| Framework | .NET 8+ |
-| Web | ASP.NET Core |
-| ORM | EF Core |
-| Testing | xUnit, NUnit |
+| Field | Value |
+| --- | --- |
+| Provider | GitHub Actions |
+| Repository | `VoDaiLocz/KILO-KIT` |
+| Workflow filename | `publish.yml` |
 
-## 🏗️ Roadmap
+Then run the `Publish npm package` workflow or push a version tag:
 
-- [x] v1.0.0 - Core Cognitive Flow Architecture
-- [x] v1.1.0 - MCP Integration
-- [x] v1.2.0 - Multi-Agent Orchestration
-- [x] v1.3.0 - Primary Brainstorming Gate for C4
-- [ ] v2.0.0 - Visual Workflow Builder
+```bash
+git tag v1.3.1
+git push origin v1.3.1
+```
 
-## 📄 License
+The release workflow runs build, typecheck, tests, smoke, skill validation, package dry-run, and `npm publish --access public --ignore-scripts`.
 
-Apache 2.0 - See [LICENSE](./LICENSE) for details.
+## Roadmap
 
----
+- v1.3.x: C4 gate hardening, memory/audit clarity, documentation cleanup.
+- v2.0.0: Local Visual Workflow Builder for C4 sessions, memory, and audit review.
 
-**Made with ❤️ for developers who value quality, efficiency, and scalability.**
+## License
 
-*Kilo-Kit — Where AI meets excellence.*
+Apache 2.0. See [LICENSE](./LICENSE).

package/mcp/README.md

@@ -1,6 +1,6 @@
 # 🔌 Kilo-Kit MCP Server
 
-> **Version:** 1.3.0
+> **Version:** 1.3.1
 > **Mode:** Read-only Skill Registry + Validator
 > **Transport:** stdio
 
@@ -26,12 +26,14 @@ Resources:
 |----------|---------|
 | `kilo://skills/index` | Lightweight skill index |
 | `kilo://core/master` | Kilo-Kit master skill |
+| `kilo://rules/c4` | Minimal host-agent operating rules for the C4 workflow |
 | `kilo://skills/{category}/{skill}` | Dynamic skill resource |
 
 Prompts:
 
 | Prompt | Purpose |
 |--------|---------|
+| `kilo-c4-workflow` | Run a request through the C4 gate before substantive implementation |
 | `kilo-select-skill` | Route a request before implementation |
 | `kilo-validate-library` | Run the validation quality gate |
 
@@ -50,8 +52,8 @@ npm run smoke
 Expected verification:
 
 ```text
-Test Files  9 passed
-Tests       22 passed
+Test Files  10 passed
+Tests       28 passed
 MCP smoke check passed.
 ```
 
@@ -74,6 +76,16 @@ Use the published npm package in any MCP-capable client:
 
 The npm package includes the Kilo-Kit skill library, core master file, validator, and built MCP server.
 
+Install the host-agent bootstrap rule in each project where you want C4 to run automatically:
+
+```bash
+npx -y --package=@vodailoc/kilo-kit-mcp kilo-kit-init init --client gemini
+npx -y --package=@vodailoc/kilo-kit-mcp kilo-kit-init init --client codex
+npx -y --package=@vodailoc/kilo-kit-mcp kilo-kit-init init --client claude
+```
+
+Use `--client all` to write `GEMINI.md`, `AGENTS.md`, and `CLAUDE.md` in the target project. Use `--dir <path>` to initialize another project directory.
+
 Route telemetry is in-memory by default. To persist route decisions between server runs, set:
 
 ```bash
@@ -93,6 +105,14 @@ KILO_KIT_ORCHESTRATION_AUDIT_PATH=/absolute/path/orchestration-audit.jsonl
 
 `kilo_orchestrate_task` uses the C4 Brainstorming-First Gate as a skill gate, not a separate C4 questionnaire. Substantive work starts by loading and following `productivity/brainstorming`. After the user approves the brainstorming direction, call `kilo_orchestrate_task` again with `brainstormingApproved=true`; C4 then checks memory suggestions and releases the post-brainstorming workflow.
 
+The released workflow is the primary C4 route, not an exclusive context source. After loading the first C4-selected skill, the agent must still inspect its own available skill list and load any other relevant skills before coding.
+
+Installing the MCP server exposes tools, prompts, resources, and server instructions. It does not force every MCP host to call those tools automatically. If a client does not reliably follow MCP server instructions, use `kilo-kit-init` or add one bootstrap rule to the local agent configuration:
+
+```text
+For substantive project work, call kilo_orchestrate_task before implementation and follow the returned C4 state, workflow, and verificationGate.
+```
+
 ### Codex CLI on Windows
 
 When Codex is opened inside the Kilo-Kit source checkout, `npx -y @vodailoc/kilo-kit-mcp` can resolve the local package instead of the published package. Use an npm prefix outside the repository:
@@ -120,8 +140,8 @@ Configure the npm package once:
 Then publish by running the GitHub Actions workflow `Publish npm package`, or by pushing a version tag:
 
 ```bash
-git tag v1.3.0
-git push origin v1.3.0
+git tag v1.3.1
+git push origin v1.3.1
 ```
 
 The workflow runs build, typecheck, tests, smoke, skill validation, package dry-run, and then `npm publish --access public --ignore-scripts` through OIDC.
@@ -178,6 +198,7 @@ User request
 → kilo_orchestrate_task(message, context, brainstormingApproved=true)
 → accept/reject memory suggestions when relevant
 → kilo_get_skill(category, skill) for the first post-brainstorming workflow skill
+→ inspect the agent's internal skill list and load any other relevant skills
 → follow final workflow skills in order
 → kilo_route_report when you need routing analytics
 → kilo_memory_report when you need memory analytics

package/mcp/dist/init.js

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+import { lstatSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const START_MARKER = "<!-- KILO-KIT:C4:START -->";
+const END_MARKER = "<!-- KILO-KIT:C4:END -->";
+const MAX_BOOTSTRAP_FILE_BYTES = 256 * 1024;
+const CLIENT_FILES = {
+    gemini: {
+        fileName: "GEMINI.md",
+        displayName: "Gemini CLI",
+    },
+    codex: {
+        fileName: "AGENTS.md",
+        displayName: "OpenAI Codex",
+    },
+    claude: {
+        fileName: "CLAUDE.md",
+        displayName: "Claude Code",
+    },
+};
+export function bootstrap(options) {
+    validateTargetDirectory(options.cwd);
+    const targets = resolveTargets(options);
+    return targets.map((target) => writeBootstrapBlock(target));
+}
+function resolveTargets(options) {
+    const clients = options.client === "all" ? Object.keys(CLIENT_FILES) : [options.client];
+    return clients.map((client) => {
+        const config = CLIENT_FILES[client];
+        return {
+            client,
+            filePath: path.resolve(options.cwd, config.fileName),
+            displayName: config.displayName,
+        };
+    });
+}
+function writeBootstrapBlock(target) {
+    assertSafeTarget(target.filePath);
+    const block = buildBootstrapBlock(target);
+    let action = "created";
+    let nextContent = block;
+    try {
+        const current = readFileSync(target.filePath, "utf8");
+        action = "updated";
+        nextContent = replaceOrAppendBlock(current, block);
+    }
+    catch (error) {
+        if (!isNotFoundError(error)) {
+            throw error;
+        }
+    }
+    writeFileAtomic(target.filePath, nextContent);
+    return {
+        client: target.client,
+        filePath: target.filePath,
+        action,
+    };
+}
+function replaceOrAppendBlock(current, block) {
+    const start = current.indexOf(START_MARKER);
+    const end = current.indexOf(END_MARKER);
+    const hasStart = start >= 0;
+    const hasEnd = end >= 0;
+    if (hasStart !== hasEnd || (hasStart && end < start)) {
+        throw new Error(`Refusing to update bootstrap file because the Kilo-Kit marker block is malformed. Fix or remove ${START_MARKER} / ${END_MARKER} manually.`);
+    }
+    if (start >= 0 && end > start) {
+        const afterEnd = end + END_MARKER.length;
+        return `${current.slice(0, start)}${block}${current.slice(afterEnd)}`;
+    }
+    const separator = current.endsWith("\n") ? "\n" : "\n\n";
+    return `${current}${separator}${block}`;
+}
+function buildBootstrapBlock(target) {
+    return `${START_MARKER}
+## Kilo-Kit C4 Workflow
+
+Applies to: ${target.displayName}
+
+For substantive coding, debugging, refactoring, review, publishing, or project-work requests:
+
+1. Call \`kilo_orchestrate_task\` before implementation.
+2. If state is \`brainstorming_required\`, load \`productivity/brainstorming\` with \`kilo_get_skill\`, follow it, and get user approval.
+3. Call \`kilo_orchestrate_task\` again with the same \`sessionId\` and \`brainstormingApproved=true\`.
+4. If state is \`awaiting_memory_confirmation\`, accept or reject memory suggestions before execution.
+5. When state is \`ready\`, load \`firstSkillToLoad\` with \`kilo_get_skill\`.
+6. Also inspect the host agent's own available skill list and load any other relevant skills before coding.
+7. Follow \`finalWorkflow\`.
+8. Satisfy \`verificationGate\` before claiming completion.
+
+For read-only requests, \`kilo_route_intent\` is enough.
+${END_MARKER}
+`;
+}
+function isNotFoundError(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+function validateTargetDirectory(cwd) {
+    let stats;
+    try {
+        stats = statSync(cwd);
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            throw new Error(`Target directory does not exist: ${cwd}`);
+        }
+        throw error;
+    }
+    if (!stats.isDirectory()) {
+        throw new Error(`Target path is not a directory: ${cwd}`);
+    }
+    if (lstatSync(cwd).isSymbolicLink()) {
+        throw new Error(`Refusing to write bootstrap files through a symlinked directory: ${cwd}`);
+    }
+}
+function assertSafeTarget(filePath) {
+    try {
+        const stats = lstatSync(filePath);
+        if (stats.isSymbolicLink()) {
+            throw new Error(`Refusing to update symlinked bootstrap file: ${filePath}`);
+        }
+        if (!stats.isFile()) {
+            throw new Error(`Refusing to update non-file bootstrap target: ${filePath}`);
+        }
+        if (stats.size > MAX_BOOTSTRAP_FILE_BYTES) {
+            throw new Error(`Refusing to update bootstrap file larger than ${MAX_BOOTSTRAP_FILE_BYTES} bytes: ${filePath}`);
+        }
+    }
+    catch (error) {
+        if (!isNotFoundError(error)) {
+            throw error;
+        }
+    }
+}
+function writeFileAtomic(filePath, content) {
+    const dir = path.dirname(filePath);
+    const base = path.basename(filePath);
+    const tempPath = path.join(dir, `.${base}.${process.pid}.${Date.now()}.tmp`);
+    try {
+        writeFileSync(tempPath, content, { encoding: "utf8", flag: "wx", mode: 0o644 });
+        renameSync(tempPath, filePath);
+    }
+    catch (error) {
+        try {
+            unlinkSync(tempPath);
+        }
+        catch {
+            // Best-effort cleanup only.
+        }
+        throw error;
+    }
+}
+function parseArgs(argv) {
+    const command = argv[0];
+    if (command !== "init") {
+        throw new Error(usage());
+    }
+    let client;
+    let cwd = process.cwd();
+    for (let index = 1; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--client") {
+            const value = argv[index + 1];
+            if (!value || !isClient(value)) {
+                throw new Error("Expected --client to be one of: gemini, codex, claude, all.");
+            }
+            client = value;
+            index += 1;
+            continue;
+        }
+        if (arg === "--dir") {
+            const value = argv[index + 1];
+            if (!value) {
+                throw new Error("Expected --dir to receive a path.");
+            }
+            cwd = path.resolve(value);
+            index += 1;
+            continue;
+        }
+        if (arg === "--help" || arg === "-h") {
+            throw new Error(usage());
+        }
+        throw new Error(`Unknown argument: ${arg}\n\n${usage()}`);
+    }
+    return {
+        client: client ?? "all",
+        cwd,
+    };
+}
+function isClient(value) {
+    return value === "gemini" || value === "codex" || value === "claude" || value === "all";
+}
+function usage() {
+    return [
+        "Usage:",
+        "  kilo-kit-init init [--client gemini|codex|claude|all] [--dir <path>]",
+        "",
+        "Examples:",
+        "  kilo-kit-init init --client gemini",
+        "  kilo-kit-init init --client codex --dir /path/to/project",
+        "  kilo-kit-init init --client all",
+    ].join("\n");
+}
+async function main() {
+    const options = parseArgs(process.argv.slice(2));
+    const results = bootstrap(options);
+    for (const result of results) {
+        console.log(`${result.action}: ${result.filePath}`);
+    }
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    main().catch((error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    });
+}

package/mcp/dist/orchestrator.js

@@ -187,9 +187,9 @@ function buildNextAction(state, session, pendingSuggestions, firstSkillToLoad) {
         return `Accept or reject memory suggestions before execution: ${pendingSuggestions.map((item) => item.key).join(", ")}.`;
     }
     if (firstSkillToLoad) {
-        return `Load ${firstSkillToLoad.id} with kilo_get_skill, then follow the final workflow.`;
+        return `Load ${firstSkillToLoad.id} with kilo_get_skill, then follow the final workflow. IMPORTANT: Do NOT rely solely on this workflow. You MUST also scan your full internal skill list (in your system prompt) and use view_file to load any other relevant skills before coding.`;
     }
-    return session.route.nextAction;
+    return session.route.nextAction + " IMPORTANT: You MUST also scan your full internal skill list and load any other relevant skills before coding.";
 }
 function executableWorkflow(session) {
     if (!session.brainstormingApproved) {

package/mcp/dist/server.js

@@ -15,7 +15,7 @@ import { createInMemoryRouteAnalytics, createJsonlRouteAnalytics } from "./route
 import { createSkillRegistry } from "./registry.js";
 import { routeIntent } from "./router.js";
 import { validateSkills } from "./validator.js";
-const SERVER_VERSION = "1.3.0";
+const SERVER_VERSION = "1.3.1";
 const DEFAULT_REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
 const formatSchema = z.enum(["markdown", "json"]).default("markdown");
 export async function createKiloKitServer(options = {}) {
@@ -43,7 +43,7 @@ export async function createKiloKitServer(options = {}) {
         name: "kilo-kit",
         version: SERVER_VERSION,
     }, {
-        instructions: "Use kilo_route_intent before selecting a Kilo-Kit workflow skill. Load one selected skill with kilo_get_skill, then follow its instructions. Route telemetry is in-memory by default and only persists when KILO_KIT_WRITE_DECISIONS=true.",
+        instructions: "For substantive coding, debugging, refactoring, review, publishing, or project-work requests, call kilo_orchestrate_task before implementation. If it returns brainstorming_required, load productivity/brainstorming with kilo_get_skill and get user approval before coding. After approval, call kilo_orchestrate_task again with the same sessionId and brainstormingApproved=true. If it returns awaiting_memory_confirmation, accept or reject memory suggestions before execution. When it returns ready, load firstSkillToLoad with kilo_get_skill, inspect any additional relevant skills available in the host agent, follow the finalWorkflow, and satisfy verificationGate before claiming completion. For read-only requests, kilo_route_intent is acceptable. Route telemetry is in-memory by default and only persists when KILO_KIT_WRITE_DECISIONS=true.",
     });
     server.registerTool("kilo_orchestrate_task", {
         title: "Kilo-Kit C4 Orchestrate Task",
@@ -237,6 +237,18 @@ function registerResources(server, repoRoot, registry) {
             },
         ],
     }));
+    server.registerResource("kilo-c4-operating-rules", "kilo://rules/c4", {
+        title: "Kilo-Kit C4 Operating Rules",
+        description: "Minimal rules a host agent should follow after installing the Kilo-Kit MCP server.",
+        mimeType: "text/markdown",
+    }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                text: C4_OPERATING_RULES,
+            },
+        ],
+    }));
     server.registerResource("kilo-skill", new ResourceTemplate("kilo://skills/{category}/{skill}", {
         list: async () => ({
             resources: registry.listSkills().map((skill) => ({
@@ -265,6 +277,23 @@ function registerResources(server, repoRoot, registry) {
     });
 }
 function registerPrompts(server) {
+    server.registerPrompt("kilo-c4-workflow", {
+        title: "Run Request Through C4",
+        description: "Prompt the agent to use the C4 gate before substantive implementation work.",
+        argsSchema: {
+            request: z.string().min(1).max(4000),
+        },
+    }, ({ request }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Use the Kilo-Kit C4 workflow for this request. Call kilo_orchestrate_task first. If the state is brainstorming_required, load productivity/brainstorming with kilo_get_skill and get approval before coding. If the state is awaiting_memory_confirmation, resolve the suggestions. When the state is ready, load firstSkillToLoad, inspect any other relevant host-agent skills, follow finalWorkflow, and satisfy verificationGate before completion.\n\nRequest:\n${request}`,
+                },
+            },
+        ],
+    }));
     server.registerPrompt("kilo-select-skill", {
         title: "Select Kilo-Kit Skill",
         description: "Prompt the agent to route the current request through Kilo-Kit before implementation.",
@@ -301,6 +330,21 @@ function registerPrompts(server) {
 function normalizeFormat(format) {
     return format ?? "markdown";
 }
+const C4_OPERATING_RULES = `# Kilo-Kit C4 Operating Rules
+
+For substantive coding, debugging, refactoring, review, publishing, or project-work requests:
+
+1. Call \`kilo_orchestrate_task\` before implementation.
+2. If state is \`brainstorming_required\`, load \`productivity/brainstorming\` with \`kilo_get_skill\`, follow it, and get user approval.
+3. Call \`kilo_orchestrate_task\` again with the same \`sessionId\` and \`brainstormingApproved=true\`.
+4. If state is \`awaiting_memory_confirmation\`, accept or reject memory suggestions before execution.
+5. When state is \`ready\`, load \`firstSkillToLoad\` with \`kilo_get_skill\`.
+6. Also inspect the host agent's own available skill list and load any other relevant skills before coding.
+7. Follow \`finalWorkflow\`.
+8. Satisfy \`verificationGate\` before claiming completion.
+
+For read-only requests, \`kilo_route_intent\` is enough.
+`;
 async function main() {
     const server = await createKiloKitServer();
     const transport = new StdioServerTransport();

package/mcp/dist/smoke.js

@@ -23,6 +23,20 @@ try {
             throw new Error(`Missing expected tool: ${required}`);
         }
     }
+    const prompts = await client.listPrompts();
+    const promptNames = prompts.prompts.map((prompt) => prompt.name);
+    for (const required of ["kilo-c4-workflow", "kilo-select-skill", "kilo-validate-library"]) {
+        if (!promptNames.includes(required)) {
+            throw new Error(`Missing expected prompt: ${required}`);
+        }
+    }
+    const resources = await client.listResources();
+    const resourceUris = resources.resources.map((resource) => resource.uri);
+    for (const required of ["kilo://skills/index", "kilo://core/master", "kilo://rules/c4"]) {
+        if (!resourceUris.includes(required)) {
+            throw new Error(`Missing expected resource: ${required}`);
+        }
+    }
     const route = await client.callTool({
         name: "kilo_route_intent",
         arguments: {

package/mcp/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@kilo-kit/mcp",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Kilo-Kit MCP server for skill routing, skill loading, and validation.",
   "type": "module",
   "private": true,
   "bin": {
-    "kilo-kit-mcp": "./dist/server.js"
+    "kilo-kit-mcp": "./dist/server.js",
+    "kilo-kit-init": "./dist/init.js"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -25,5 +26,8 @@
   },
   "engines": {
     "node": ">=20.0.0"
+  },
+  "optionalDependencies": {
+    "@rolldown/binding-linux-x64-gnu": "^1.0.0-rc.17"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vodailoc/kilo-kit-mcp",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Kilo-Kit MCP server for adaptive skill routing, skill loading, and validation.",
   "license": "Apache-2.0",
   "author": "Kilo-Kit Team",
@@ -13,7 +13,8 @@
     "url": "https://github.com/VoDaiLocz/KILO-KIT/issues"
   },
   "bin": {
-    "kilo-kit-mcp": "mcp/dist/server.js"
+    "kilo-kit-mcp": "mcp/dist/server.js",
+    "kilo-kit-init": "mcp/dist/init.js"
   },
   "files": [
     "LICENSE",