@maestria/kimi-code 0.5.2 → 0.6.0

package/INSTALL.md

@@ -2,7 +2,7 @@
 
 ## Prerequisites
 
-- **Kimi Code v0.12.0+** - required for first-class `AgentSwarm` support. On older versions, fallback to single `Agent` calls.
+- **Kimi Code v0.38.0+** - required for the native plugin `systemPromptPath` contract used by this package. Older versions may still load the skills-only subset, but are outside the verified support boundary.
 
 ## Via maestria CLI (recommended)
 
@@ -11,15 +11,13 @@ pnpx maestria@latest install kimi-code
 pnpx maestria@latest status
 ```
 
-The CLI pulls `@maestria/kimi-code` from npm (`npm pack @maestria/kimi-code@latest`) and extracts it into:
+The CLI pulls `@maestria/kimi-code` from npm (`npm pack @maestria/kimi-code@latest`), extracts it into Kimi Code's managed plugin directory, and registers it in Kimi's native `plugins/installed.json` registry:
 
 ```text
-~/.kimi-code/plugins/managed/maestria
+${KIMI_CODE_HOME:-~/.kimi-code}/plugins/managed/maestria
 ```
 
-It also copies the global rules to `~/.kimi-code/AGENTS.md`.
-
-After install, add the recommended `[[hooks]]` and `[[permission.rules]]` blocks to `~/.kimi-code/config.toml` (see the [full installation guide](https://maestria.dev/kimi-code/getting-started/installation/)).
+The installer preserves existing plugin records and does not overwrite global instructions. After install, start a new session so the plugin's `sessionStart.skill` loads the orchestrator and Kimi contributes `SYSTEM.md` through its native `systemPromptPath`. Add any desired `[[hooks]]` and `[[permission.rules]]` blocks to the Kimi config separately (see the [full installation guide](https://maestria.dev/kimi-code/getting-started/installation/)).
 
 ### Updating
 
@@ -31,7 +29,7 @@ pnpx maestria@latest status
 To pin to a specific version:
 
 ```bash
-pnpx maestria@latest update kimi-code --version 0.4.6
+pnpx maestria@latest update kimi-code --version 0.5.2
 ```
 
 ## Verify
@@ -39,14 +37,13 @@ pnpx maestria@latest update kimi-code --version 0.4.6
 1. Start a new Kimi Code session (`/new`)
 2. Ask: "List your available specialists"
 3. The orchestrator should respond listing builder, adventurer, architect, planner, reviewer, writer, and diagnose.
-4. Confirm `ls ~/.kimi-code/AGENTS.md` exists.
+4. Confirm the plugin is enabled in `/plugins` and that Maestria's system-prompt rules appear in the active context.
+5. Optional workflow commands are namespaced as `/maestria:fein`, `/maestria:sonar`, and `/maestria:blitz`.
 
 ## Uninstall
 
 ```bash
 pnpx maestria@latest uninstall kimi-code
-# or
-rm -rf ~/.kimi-code/plugins/managed/maestria ~/.kimi-code/AGENTS.md
 ```
 
 Optionally remove the `[[hooks]]` and `[[permission.rules]]` blocks from `~/.kimi-code/config.toml`.

package/README.md

@@ -1,6 +1,6 @@
 # @maestria/kimi-code
 
-A Kimi Code plugin that ships 8 specialized skills (orchestrator + 7 specialists) for engineering workflows with swarm-aware orchestration.
+A Kimi Code plugin that ships a native system-prompt contract, an orchestrator, and 7 specialist skills for engineering workflows with swarm-aware orchestration.
 
 > This package is part of the Maestria project. See [VISION.md](https://github.com/agustinusnathaniel/maestria/blob/main/VISION.md) for the project vision, motivation, and scope.
 
@@ -19,13 +19,14 @@ See [INSTALL.md](https://github.com/agustinusnathaniel/maestria/blob/main/packag
 
 ## What It Provides
 
-- **8 skills** - `orchestrator` (auto-loaded at session start) plus builder, adventurer, architect, planner, reviewer, writer, and diagnose personas, loaded on demand via the `Skill` tool.
-- **Swarm-aware orchestration** - routes ≥3 uniform items through Kimi Code's `AgentSwarm` for parallel fan-out.
-- **Global rules** - `rules/AGENTS.md` auto-loaded by Kimi Code at session start.
+- **8 core skills** - `orchestrator` (auto-loaded at session start) plus builder, adventurer, architect, planner, reviewer, writer, and diagnose personas, loaded on demand via the `Skill` tool.
+- **Native workflow commands** - `/maestria:fein`, `/maestria:sonar`, and `/maestria:blitz` are registered through Kimi's plugin `commands` field.
+- **Swarm-aware orchestration** - routes 2 or more uniform items through Kimi Code's `AgentSwarm` for parallel fan-out.
+- **System-prompt rules** - `SYSTEM.md` is contributed through Kimi's native `systemPromptPath`; no global `AGENTS.md` file is written.
 
 ## Support / Platform Notes
 
-- Kimi Code hardcodes its `coder`/`explore`/`plan` subagents; the 7 specialist identities are persona content in prompt templates, not custom subagent definitions.
+- Kimi Code 0.38.0+ supports plugin system-prompt contributions and custom agents; this package uses the native system-prompt path and keeps specialist identities in skills and prompt templates for compatibility.
 - Persona text is advisory; tool-layer enforcement comes from the user-applied `[[hooks]]`/`[[permission.rules]]` blocks documented in `INSTALL.md`.
 
 ## Documentation and Changelog

package/{rules/AGENTS.md → SYSTEM.md}

@@ -1,6 +1,5 @@
 <!-- Auto-generated from @maestria/core. See the canonical file at packages/core/agent-directives/rules.md. -->
 
-
 <!-- Auto-generated from @maestria/core. Do not edit directly.
      Edit the canonical file at packages/core/agent-directives/ instead. -->
 

package/{skills/commands/blitz/SKILL.md → commands/blitz.md}

@@ -1,15 +1,12 @@
 ---
 name: blitz
-description: "Fast implementation mode: skip optional recon/design unless unknown; required review remains"
-type: prompt
-whenToUse: When the user types /blitz or includes "blitz" in their message for fast implementation.
-arguments: []
+description: 'Fast implementation mode: skip optional recon/design unless unknown; required review remains'
 ---
 
 <!-- Auto-generated from @maestria/core. Do not edit directly.
      Edit the canonical file at packages/core/agent-directives/ instead. -->
 
-**Skill profile:** `plan` - workflow mode command. You have Read, Glob, Grep, Bash, FetchURL, and WebSearch.
+**Workflow command:** use the fastest safe route allowed by the active Kimi profile, while retaining required review.
 
 [MODE: blitz]
 

package/{skills/commands/fein/SKILL.md → commands/fein.md}

@@ -1,15 +1,12 @@
 ---
 name: fein
-description: "Full pipeline mode: recon, design, implement, review"
-type: prompt
-whenToUse: When the user types /fein or includes "fein" in their message to run the complete maestria pipeline.
-arguments: []
+description: 'Full pipeline mode: recon, design, implement, review'
 ---
 
 <!-- Auto-generated from @maestria/core. Do not edit directly.
      Edit the canonical file at packages/core/agent-directives/ instead. -->
 
-**Skill profile:** `plan` - workflow mode command. You have Read, Glob, Grep, Bash, FetchURL, and WebSearch.
+**Workflow command:** use the Kimi Agent and its native Agent/AgentSwarm tools as permitted by the active profile.
 
 [MODE: fein]
 

package/{skills/commands/sonar/SKILL.md → commands/sonar.md}

@@ -1,15 +1,12 @@
 ---
 name: sonar
-description: "Research-only mode: recon and design, no implementation"
-type: prompt
-whenToUse: When the user types /sonar or includes "sonar" in their message for research-only work.
-arguments: []
+description: 'Research-only mode: recon and design, no implementation'
 ---
 
 <!-- Auto-generated from @maestria/core. Do not edit directly.
      Edit the canonical file at packages/core/agent-directives/ instead. -->
 
-**Skill profile:** `plan` - workflow mode command. You have Read, Glob, Grep, Bash, FetchURL, and WebSearch.
+**Workflow command:** keep this route read-only and stop before implementation.
 
 [MODE: sonar]
 

package/kimi.plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "maestria",
-  "version": "0.4.6",
-  "description": "Maestria agent pack for Kimi Code - 8 specialized skills with swarm-aware orchestration",
+  "version": "0.6.0",
+  "description": "Maestria agent pack for Kimi Code - specialist skills with swarm-aware orchestration",
   "keywords": [
     "maestria",
     "kimi-code",
@@ -17,14 +17,16 @@
   "homepage": "https://github.com/agustinusnathaniel/maestria",
   "license": "MIT",
   "skills": "./skills/",
+  "commands": "./commands/",
+  "systemPromptPath": "./SYSTEM.md",
   "sessionStart": {
     "skill": "orchestrator"
   },
-  "skillInstructions": "Maestria dispatch rules for Kimi Code:\n- 7 specialist personas: builder, adventurer, architect, planner, reviewer, writer, diagnose\n- Use Skill(skill=\"<persona>\") to load a persona, then inline its methodology into Agent()/AgentSwarm() prompts\n- builder/adventurer/planner/reviewer/writer/diagnose → subagent_type \"coder\" (except adventurer → \"explore\", planner → \"plan\")\n- Routing table in the orchestrator skill shows the full specialist→subagent mapping\n- The orchestrator auto-loads at session start and provides full delegation methodology",
+  "skillInstructions": "Maestria dispatch rules for Kimi Code:\n- 7 specialist personas: builder, adventurer, architect, planner, reviewer, writer, diagnose\n- Use Skill(skill=\"<persona>\") to load a persona, then inline its methodology into Agent()/AgentSwarm() prompts\n- builder/diagnose/writer → subagent_type \"coder\"; adventurer → \"explore\"; architect/planner/reviewer → \"plan\"\n- Routing table in the orchestrator skill shows the full specialist→subagent mapping\n- The orchestrator auto-loads at session start and provides full delegation methodology",
   "interface": {
     "displayName": "Maestria Agent Pack",
-    "shortDescription": "8 specialized engineering workflow skills for Kimi Code",
-    "longDescription": "Maestria packages 7 specialist personas (builder, adventurer, planner, reviewer, architect, writer, diagnose) plus an orchestrator skill that auto-loads at session start. The orchestrator composes personas into prompt templates for Kimi Code's 3 built-in subagents (coder, explore, plan) and uses AgentSwarm for parallel fan-out. Built on the Harness Engineering principle: precise rules, explicit boundaries, and clear delegation chains over raw capability.",
+    "shortDescription": "Specialized engineering workflow skills for Kimi Code",
+    "longDescription": "Maestria packages universal rules, 7 specialist personas (builder, adventurer, planner, reviewer, architect, writer, diagnose), and an orchestrator skill that auto-loads at session start. The orchestrator composes personas into prompt templates for Kimi Code's 3 built-in subagents (coder, explore, plan) and uses AgentSwarm for parallel fan-out. Built on the Harness Engineering principle: precise rules, explicit boundaries, and clear delegation chains over raw capability.",
     "developerName": "Agustinus Nathaniel",
     "websiteURL": "https://github.com/agustinusnathaniel/maestria"
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maestria/kimi-code",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "private": false,
   "description": "Maestria agent pack for Kimi Code - 8 specialized skills with swarm-aware orchestration",
   "keywords": [
@@ -23,8 +23,9 @@
   },
   "files": [
     "kimi.plugin.json",
+    "SYSTEM.md",
     "skills",
-    "rules",
+    "commands",
     "INSTALL.md",
     "README.md"
   ],

package/skills/architect/SKILL.md

@@ -15,7 +15,7 @@ arguments: []
 <!-- Auto-generated from @maestria/core. Do not edit directly.
      Edit the canonical file at packages/core/agent-directives/ instead. -->
 
-**Subagent profile:** `plan` - you have Read, Glob, Grep, Bash, WebSearch, and FetchURL. You do **not** have Write or Edit.
+**Subagent profile:** `plan` - you have Read, Glob, Grep, WebSearch, and FetchURL. You do **not** have Bash, Write, or Edit.
 
 You make architecture decisions systematically.
 

package/skills/orchestrator/SKILL.md

@@ -12,7 +12,7 @@ arguments: []
 <!-- Auto-generated from @maestria/core. Do not edit directly.
      Edit the canonical file at packages/core/agent-directives/ instead. -->
 
-**Subagent profile:** `plan` - you have Read, Glob, Grep, Bash, FetchURL, and WebSearch. You do **not** have Write or Edit.
+**Subagent profile:** `plan` - you have Read, Glob, Grep, FetchURL, and WebSearch. You do **not** have Bash, Write, or Edit.
 
 You are the orchestrator: you select the smallest safe route for each turn, delegate specialist work with concise briefs, integrate results, and drive implementation outcomes through delivery.
 
@@ -103,7 +103,7 @@ Report briefly at milestones - route chosen, delegations integrated, verificatio
 
 ## Swarm Usage (AgentSwarm)
 
-When 3+ items are uniform (same persona, same goal, independent units), use `AgentSwarm` instead of `Agent`. The swarm dispatches N parallel agents, collects results, and returns them as a structured array.
+When 2+ items are uniform (same persona, same goal, independent units), use `AgentSwarm` instead of `Agent`. The swarm dispatches N parallel agents, collects results, and returns an XML result envelope.
 
 ### When to use AgentSwarm
 
@@ -115,8 +115,12 @@ When 3+ items are uniform (same persona, same goal, independent units), use `Age
 ### How AgentSwarm works
 
 ```
-AgentSwarm(persona: "builder", data: [...], prompt: "...")
-  → [{status, files, summary}, ...]
+AgentSwarm(
+  description: "Review independent files",
+  subagent_type: "coder",
+  prompt_template: "Review {{item}} for correctness and test gaps.",
+  items: ["src/a.ts", "src/b.ts"]
+)
 ```
 
 Array elements run in parallel. Each gets its own context snapshot. Results are gathered after all complete.
@@ -127,25 +131,25 @@ When using AgentSwarm, only the orchestrator may talk to the user. Swarm agents
 
 ### Result envelope
 
-Each swarm agent returns: `{status: "ok"|"error", files: string[], summary: string}`. The orchestrator reads the envelope and decides next steps.
+Each swarm result is returned in Kimi's XML envelope. Read the per-item status and handoff text before deciding whether to continue or repair.
 
 ## Background Sub-Agents
 
-You may launch `Agent(persona: "explore", task: "research this")` as a background investigation while continuing other work. Background agents run concurrently and report back. Signal completion by returning a structured result.
+You may launch `Agent(prompt: "research this", description: "Explore the question", subagent_type: "explore", run_in_background: true)` as a background investigation while continuing other work. Background agents run concurrently and report back.
 
 ## How to Invoke a Specialist Persona
 
 1. `Skill(skill="adventurer")` - Load the specialist persona (defines constraints, rules, and subagent profile for that role)
-2. `Agent(persona: "...", data: {...}, prompt: "...")` - Delegate a unit of work to the persona
-3. `AgentSwarm(persona: "...", data: [...], prompt: "...")` - Delegate N uniform items to parallel persona instances
+2. `Agent(prompt: "...", description: "Short task label", subagent_type: "coder")` - Delegate a unit of work to the mapped built-in profile
+3. `AgentSwarm(description: "...", subagent_type: "coder", prompt_template: "... {{item}} ...", items: [...])` - Delegate uniform items in parallel
 
 ### Why the two-step pattern?
 
-The `Skill` call loads persona-specific context (rules, tools, behavioral constraints). The `Agent` call sends the actual task. This separation ensures each persona starts with the right configuration every time.
+The `Skill` call loads persona-specific context (rules, tools, behavioral constraints). The `Agent` call sends the actual task with Kimi's required prompt, description, and subagent type fields. This separation ensures each persona starts with the right configuration every time.
 
 ### Subagent profile vs persona
 
-The `explore` subagent has Read-only tools. The `coder` subagent has full Write/Edit. The `plan` subagent is Read-only with Bash access.
+The `explore` subagent has read-only search tools. The `coder` subagent has full Write/Edit access. The `plan` subagent is read-only and has no shell access.
 
 ### Single-agent pattern
 
@@ -155,23 +159,24 @@ const result = await Skill(skill: "diagnose");
 if (result.status !== "ok") { AskUserQuestion("..."); return; }
 
 // 2. Dispatch the task
-const output = await Agent(persona: "diagnose", data: ctx, prompt: "Find why X fails");
-if (output.status === "ok") { /* use output.files, output.summary */ }
+const output = await Agent(
+  prompt: "Find why X fails",
+  description: "Diagnose failure",
+  subagent_type: "coder"
+);
+if (output.result) { /* use the complete handoff */ }
 ```
 
 ### Swarm pattern
 
 ```
-const items = [
-  { path: "src/a.ts", desc: "..." },
-  { path: "src/b.ts", desc: "..." },
-  { path: "src/c.ts", desc: "..." },
-];
-
-const results = await AgentSwarm(persona: "builder", data: items, prompt: "Update each file");
-for (const r of results) {
-  if (r.status !== "ok") { /* handle */ }
-}
+const results = await AgentSwarm(
+  description: "Update independent files",
+  subagent_type: "coder",
+  prompt_template: "Update {{item}} and run its focused checks.",
+  items: ["src/a.ts", "src/b.ts", "src/c.ts"]
+);
+// Read the XML result envelope and handle failed items explicitly.
 ```
 
 ## Anti-Patterns (additional)

package/skills/planner/SKILL.md

@@ -14,7 +14,7 @@ arguments: []
 <!-- Auto-generated from @maestria/core. Do not edit directly.
      Edit the canonical file at packages/core/agent-directives/ instead. -->
 
-**Subagent profile:** `plan` - you have Read, Glob, Grep, Bash, WebSearch, and FetchURL. You do **not** have Write or Edit.
+**Subagent profile:** `plan` - you have Read, Glob, Grep, WebSearch, and FetchURL. You do **not** have Bash, Write, or Edit.
 
 You create implementation plans.
 

package/skills/reviewer/SKILL.md

@@ -16,7 +16,7 @@ arguments: []
 <!-- Auto-generated from @maestria/core. Do not edit directly.
      Edit the canonical file at packages/core/agent-directives/ instead. -->
 
-**Subagent profile:** `plan` - you have Read, Glob, Grep, Bash, WebSearch, and FetchURL. You do **not** have Write or Edit.
+**Subagent profile:** `plan` - you have Read, Glob, Grep, WebSearch, and FetchURL. You do **not** have Bash, Write, or Edit.
 
 You review code for quality. You do not edit files (read-only checker only).