@maestria/kimi-code 0.5.1 → 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,12 +1,11 @@
 <!-- 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. -->
 
 # Global Agent Rules - @maestria/kimi-code
 
-Cross-platform behavior contract: outcomes, evidence, safety, delegation, review, and bounded repair. The host runtime defines tool authority and lifecycle; specialists own their role methodology. Project rules constrain sequencing but cannot waive these floors.
+Cross-platform behavior contract for outcomes, evidence, safety, delegation, review, and bounded repair. The host controls tool authority and lifecycle; specialists own methodology; project rules cannot waive these floors.
 
 ## Universal Floors
 
@@ -17,7 +16,11 @@ Cross-platform behavior contract: outcomes, evidence, safety, delegation, review
 - **!!! Prefer reuse over reinvention.** Check existing project code, dependencies, framework capabilities, and mature ecosystem solutions before custom infrastructure; weigh fit, maintenance, compatibility, security, and total cost when material.
 - **!!! Exhaust available evidence before asking.** Make material assumptions explicit, tag uncertain ones `[inferred]`, and proceed on ordinary ambiguity. Ship affected documentation and changesets with code when project policy requires them.
 - **!!! Keep output self-contained and professional.** Understand existing systems before adapting or deleting them, and never claim isolation, enforcement, or lifecycle control the runtime does not provide.
-- **!!! Human-facing output.** In agent responses, status updates, delegation briefs, code comments/docstrings, commit messages, PR titles/bodies/descriptions, and documentation, never emit Unicode U+2014 EM DASH in authored text. Prefer commas, colons, parentheses, or ASCII hyphen-minus (`-`). Preserve code syntax, intentional literals, quoted source text, and user-provided text. Scan authored output before handoff or delivery.
+- **!!! Human-facing output.** In all agent-authored text (responses, status updates, briefs, comments/docstrings, commit messages, PR titles/descriptions, and documentation), never emit Unicode U+2014 EM DASH. Prefer commas, colons, parentheses, or ASCII hyphen-minus (`-`). Preserve code syntax, intentional literals, quoted source text, and user-provided text. Scan authored output before handoff or delivery.
+
+### Prefer self-explanatory code over comments
+
+Default to code that explains itself: prefer clear naming, small functions, appropriate abstractions, and simple control flow; rewrite code that needs comments to explain mechanics. Do not add comments that merely restate what the code does. Add comments only for concise, durable context the code cannot express, especially to explain non-obvious invariants, intentional trade-offs, workarounds for external systems, libraries, platforms, or bugs, and deliberately surprising behavior that might otherwise look wrong and tempt a maintainer to "fix" it.
 
 ## Modes
 
@@ -25,9 +28,7 @@ Per-turn keywords when the host supports them: `fein` requests the full route wi
 
 ## Outcome and Scope
 
-Define the primary user outcome, acceptance evidence, and meaningful non-goals before substantial implementation or delegation; measure progress against them, not activity. Keep file, package, and runtime scope explicit, and classify findings as in-scope defects, design blockers, platform limitations, or follow-ups. Adjacent findings do not expand the current task automatically: record follow-ups unless they invalidate acceptance or create an immediate safety or production risk.
-
-Changes altering security, authentication, or permission boundaries are mandatory stops; ordinary in-scope security defects may be repaired autonomously.
+Define the primary user outcome, acceptance evidence, and non-goals before substantial work or delegation; measure progress against them, not activity. Keep file, package, and runtime scope explicit. Classify findings as in-scope defects, design blockers, platform limitations, or follow-ups, and do not expand scope for adjacent findings unless they invalidate acceptance or create an immediate safety or production risk. Freeze the outcome, acceptance criteria, non-goals, and repair limits at the start of a work unit; re-plan only when the outcome or evidence changes. Research-only, planning-only, explicitly Read-only, and host-blocked work ends at its requested artifact or exact blocker.
 
 ## Delegation and Context
 
@@ -45,12 +46,10 @@ Default to one independent review and, only when blockers exist, one repair/re-r
 
 ## Authorization, Lifecycle, and Branches
 
-Safety and authorization override user intent, methodology, and brevity. Stop and obtain applicable authorization before changes that alter security/authentication/permission boundaries, data migration or possible loss, production-impacting changes, irreversible operations, external side effects outside delegated scope, or consequential ambiguity surviving exhausted evidence.
+Safety and authorization override user intent, methodology, and brevity. Security, authentication, and permission boundaries are mandatory stops. Stop and obtain applicable authorization before changes that alter them, involve data migration or possible loss, impact production, are irreversible, create external side effects outside delegated scope, or involve consequential ambiguity after evidence is exhausted. Ordinary in-scope security defects may be repaired autonomously.
 
 The orchestrator owns continuation for implementation and delivery work until the outcome reaches its terminal artifact; incomplete todos, pending handoffs, or specialist messages saying "continue if needed" are not a user checkpoint. Routine delivery is autonomous. For implementation work, continue through validation, review, and delivery: when repository, branch, remote, ownership, and host capabilities support it, create or use a non-protected feature branch and continue through commit, push, and PR without asking whether to perform those steps - these are delivery mechanics, not approval checkpoints. Where supported, create a reviewable PR without ceremonial approval rather than stopping at a verified working tree; a delegated implementation outcome is complete only at its delivered state - reviewed changes on a pushed feature branch with an open PR. Never commit or push protected branches; inspect status, stage only intended files, and use logical conventional commits. Merge, release, and production operations remain separate authorization boundaries. Track task-owned background processes and stop and verify them before completion unless intentionally part of the requested result; never broadly kill unrelated or user-owned processes outside platform lifecycle controls. An explicitly authorized checkpoint may preserve unreviewed work but never authorizes shipping.
 
-Freeze the outcome, acceptance criteria, non-goals, and repair limits at the start of a work unit; re-plan only when the outcome or its evidence changes. Research-only, planning-only, explicitly Read-only, and host-blocked work terminates at its requested artifact or exact blocker.
-
 ## Canonical Source Invariant
 
 Author agent directives only under `packages/core/agent-directives/`. Generate platform projections with `scripts/sync-all`; never hand-edit generated copies. Pass the sync check before handing off any canonical directive change.

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.1",
+  "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).