Kilo-Kit: MCP Workflow Gates for Coding Agents

Version: 1.3.1 Author: Kilo-Kit Team License: Apache 2.0

Kilo-Kit is a local-first MCP server and skill library for making coding agents follow safer, repeatable workflows before they touch code.

Use it when your agent skips planning, ignores project workflow rules, forgets useful context, or claims work is done before verification.

It packages a curated skills/ library, an MCP server, and a C4 workflow gate that turns a user request into an auditable loop:

request -> route -> planning gate -> memory check -> workflow release -> verification gate

The published package is @vodailoc/kilo-kit-mcp.

Why Use It

What It Provides

Install In Two Steps

Step 1: install the MCP server in your client.

Use the published package in any MCP-capable host:

{
  "mcpServers": {
    "kilo-kit": {
      "command": "npx",
      "args": ["-y", "@vodailoc/kilo-kit-mcp"]
    }
  }
}

Step 2: bootstrap the host-agent rule in your project.

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

Or initialize all supported host files:

npx -y --package=@vodailoc/kilo-kit-mcp kilo-kit-init init --client all

This writes an idempotent Kilo-Kit C4 block to:

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.

For Codex CLI on Windows, use an npm prefix outside the source checkout so npm does not resolve a local checkout:

[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

Why Bootstrap Is Needed

MCP exposes tools, prompts, resources, and server instructions. It does not force every host agent to call those tools automatically.

Kilo-Kit ships the C4 rule in four places:

• MCP server instructions.
• MCP resource kilo://rules/c4.
• MCP prompt kilo-c4-workflow.
• Host bootstrap files created by kilo-kit-init.

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.

C4 Workflow

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:

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.

Read-only requests such as status, show, read, or explain can skip the brainstorming gate.

C4 States

Returned Workflow

When C4 is ready, it returns:

• 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.

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.

MCP Tools

MCP Resources

Persistence

Route telemetry is in memory by default. Enable JSONL decision persistence with:

KILO_KIT_WRITE_DECISIONS=true
KILO_KIT_DECISION_TRAIL_PATH=/absolute/path/decision-trail.jsonl

If KILO_KIT_DECISION_TRAIL_PATH is not set, route decisions are written to .kilo/decision-trail.jsonl under KILO_KIT_REPO_ROOT.

C4 memory uses node:sqlite when available and defaults to:

~/.kilo-kit/orchestrator.sqlite

Override C4 paths with:

KILO_KIT_MEMORY_PATH=/absolute/path/orchestrator.sqlite
KILO_KIT_ORCHESTRATION_AUDIT_PATH=/absolute/path/orchestration-audit.jsonl

C4 memory stores structured facts, decisions, orchestration sessions, and workflow outcomes. The audit file stores append-only state transition events.

Skill Library

skills/ is the workflow surface shipped with the package.

Install the full skill library:

npx skills@latest add VoDaiLocz/KILO-KIT

Install one category:

npx skills@latest add VoDaiLocz/KILO-KIT/skills/engineering

Install one skill:

npx skills@latest add VoDaiLocz/KILO-KIT/skills/engineering/tdd

Repository Layout

.
|-- .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

Local Development

Install, build, test, and smoke-check the MCP server:

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

Use a local MCP server during development:

{
  "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"
      }
    }
  }
}

Release

The root package publishes through npm Trusted Publishing from GitHub Actions.

Configure npm once:

Then run the Publish npm package workflow or push a version tag:

git tag v1.3.1
git push origin v1.3.1

The release workflow runs build, typecheck, tests, smoke, skill validation, package dry-run, and npm publish --access public --ignore-scripts.

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.

License

Apache 2.0. See LICENSE.