|
| 1 | +# kimi-openspec |
| 2 | + |
| 3 | +Official OpenSpec plugin for Kimi Code — enables spec-driven development (SDD) workflows. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +This plugin integrates [OpenSpec](https://github.com/Fission-AI/OpenSpec) into Kimi Code, allowing AI assistants to manage structured change proposals, specifications, and tasks before writing code. |
| 8 | + |
| 9 | +## What is OpenSpec? |
| 10 | + |
| 11 | +OpenSpec is a lightweight, open-source spec-driven development framework that helps AI coding assistants follow instructions more effectively. It works with 30+ tools including Kimi Code, Claude Code, Cursor, GitHub Copilot, and more. |
| 12 | + |
| 13 | +### Core Workflow |
| 14 | + |
| 15 | +``` |
| 16 | +/opsx:new → /opsx:continue → /opsx:apply → /opsx:verify → /opsx:archive |
| 17 | +``` |
| 18 | + |
| 19 | +### Key Concepts |
| 20 | + |
| 21 | +- **Proposals** — Structured change requests with technical designs |
| 22 | +- **Specifications** — Living documentation that captures functional requirements |
| 23 | +- **Task Checklists** — Implementation tasks with AI guidance |
| 24 | +- **Archives** — Completed changes preserved for reference |
| 25 | + |
| 26 | +## Installation |
| 27 | + |
| 28 | +This plugin is bundled with Kimi Code as an official plugin. To enable it: |
| 29 | + |
| 30 | +```bash |
| 31 | +kimi plugin install kimi-openspec |
| 32 | +``` |
| 33 | + |
| 34 | +Or add it to your Kimi Code configuration. |
| 35 | + |
| 36 | +## Prerequisites |
| 37 | + |
| 38 | +- Node.js 18+ (for running `npx`) |
| 39 | +- The plugin automatically installs `@fission-ai/openspec` via `npx --yes` |
| 40 | + |
| 41 | +## Tools |
| 42 | + |
| 43 | +### `openspec_init` |
| 44 | + |
| 45 | +Initialize OpenSpec in your project. |
| 46 | + |
| 47 | +**Parameters:** |
| 48 | +- `tools` (string, optional): AI tools to configure. Default: `"claude"`. Options: `"all"`, `"none"`, or comma-separated list (e.g. `"claude,cursor,codex"`). |
| 49 | +- `force` (boolean, optional): Auto-cleanup legacy files without prompting. |
| 50 | + |
| 51 | +### `openspec_new_change` |
| 52 | + |
| 53 | +Create a new change directory with proposal, design, tasks, and spec scaffolding. |
| 54 | + |
| 55 | +**Parameters:** |
| 56 | +- `name` (string, required): Name of the change (kebab-case recommended). |
| 57 | +- `description` (string, optional): Description to add to README.md. |
| 58 | + |
| 59 | +### `openspec_list` |
| 60 | + |
| 61 | +List all OpenSpec changes or specs. |
| 62 | + |
| 63 | +**Parameters:** |
| 64 | +- `specs` (boolean, optional): List specs instead of changes. |
| 65 | + |
| 66 | +### `openspec_show` |
| 67 | + |
| 68 | +Show details of a specific change or spec. |
| 69 | + |
| 70 | +**Parameters:** |
| 71 | +- `itemName` (string, required): Name of the item to show. |
| 72 | +- `type` (string, optional): Item type — `"change"` or `"spec"`. |
| 73 | + |
| 74 | +### `openspec_status` |
| 75 | + |
| 76 | +Display artifact completion status for a change. |
| 77 | + |
| 78 | +**Parameters:** |
| 79 | +- `changeName` (string, required): Change name to show status for. |
| 80 | + |
| 81 | +### `openspec_validate` |
| 82 | + |
| 83 | +Validate a change proposal or spec. |
| 84 | + |
| 85 | +**Parameters:** |
| 86 | +- `itemName` (string, optional): Name of the change to validate. |
| 87 | +- `all` (boolean, optional): Validate all changes and specs. |
| 88 | +- `strict` (boolean, optional): Enable strict validation mode. |
| 89 | + |
| 90 | +### `openspec_archive` |
| 91 | + |
| 92 | +Archive a completed change and merge its spec updates back into the main specs directory. |
| 93 | + |
| 94 | +**Parameters:** |
| 95 | +- `changeName` (string, required): Name of the change to archive. |
| 96 | +- `skipSpecs` (boolean, optional): Skip spec updates during archive. |
| 97 | + |
| 98 | +### `openspec_update` |
| 99 | + |
| 100 | +Update OpenSpec instruction files to the latest version. |
| 101 | + |
| 102 | +### `openspec_instructions` |
| 103 | + |
| 104 | +Output enriched instructions for an artifact or apply phase. |
| 105 | + |
| 106 | +**Parameters:** |
| 107 | +- `artifact` (string, required): Artifact name (e.g. `"design.md"`, `"tasks.md"`) or `"apply"`. |
| 108 | +- `changeName` (string, optional): Change name. |
| 109 | + |
| 110 | +### `openspec_read_file` |
| 111 | + |
| 112 | +Read any OpenSpec artifact directly by file type. Much faster than `show` — use this when you need file contents. |
| 113 | + |
| 114 | +**Parameters:** |
| 115 | +- `name` (string, required): Change or spec name. |
| 116 | +- `fileType` (string, required): File to read. Options: `proposal.md`, `design.md`, `tasks.md`, `spec.md`, `review.md`, `plan.md`, `.openspec.yaml`. |
| 117 | +- `type` (string, optional): Item type — `"change"` or `"spec"`. If omitted, prefers changes. |
| 118 | + |
| 119 | +### `openspec_refresh_cache` |
| 120 | + |
| 121 | +Force refresh the cached directory listing. Use if changes were made outside OpenSpec tools. |
| 122 | + |
| 123 | +## Prompts |
| 124 | + |
| 125 | +### `openspec_kickoff` |
| 126 | + |
| 127 | +A pre-built prompt that steers the AI into a strict spec-driven workflow from the first turn. Automatically injected when supported by the AI assistant. |
| 128 | + |
| 129 | +## Usage Example |
| 130 | + |
| 131 | +``` |
| 132 | +User: I want to add a dark mode feature to this application. |
| 133 | +AI: I'll help you add a dark mode feature using OpenSpec for structured planning. |
| 134 | +
|
| 135 | +[AI uses openspec_init if not already initialized] |
| 136 | +[AI uses openspec_new_change to create "add-dark-mode" change] |
| 137 | +[AI uses openspec_read_file to review proposal.md and tasks.md] |
| 138 | +[AI implements tasks sequentially] |
| 139 | +[AI uses openspec_validate to verify] |
| 140 | +[AI uses openspec_archive when complete] |
| 141 | +``` |
| 142 | + |
| 143 | +## Architecture |
| 144 | + |
| 145 | +This plugin is an MCP (Model Context Protocol) server that: |
| 146 | + |
| 147 | +1. Wraps the `@fission-ai/openspec` CLI commands |
| 148 | +2. Maintains an in-memory cache of `openspec/changes/` and `openspec/specs/` directories for fast listing |
| 149 | +3. Provides direct file reading via `openspec_read_file` to bypass CLI subprocess overhead |
| 150 | +4. Exposes a built-in `openspec_kickoff` prompt for spec-driven workflow initialization |
| 151 | + |
| 152 | +## Cache |
| 153 | + |
| 154 | +The plugin maintains an in-memory cache of the OpenSpec directory structure: |
| 155 | +- Cache is built on server startup |
| 156 | +- Cache is refreshed after any mutating operation (`init`, `new_change`, `archive`, `update`) |
| 157 | +- Manual refresh available via `openspec_refresh_cache` |
| 158 | + |
| 159 | +## Error Handling |
| 160 | + |
| 161 | +- If OpenSpec CLI is not installed, the plugin will attempt to install it automatically via `npx --yes` |
| 162 | +- If the project is not initialized, list operations will suggest running `openspec_init` |
| 163 | +- File read operations return clear error messages with available files list |
| 164 | + |
| 165 | +## License |
| 166 | + |
| 167 | +MIT — see LICENSE file. |
0 commit comments