@maestria/kimi-code 0.4.16 → 0.4.17
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/INSTALL.md +1 -1
- package/README.md +21 -67
- package/package.json +1 -1
- package/rules/AGENTS.md +8 -0
- package/skills/orchestrator/SKILL.md +7 -1
package/INSTALL.md
CHANGED
package/README.md
CHANGED
|
@@ -2,90 +2,44 @@
|
|
|
2
2
|
|
|
3
3
|
A declarative, manifest-based Kimi Code plugin that ships 8 specialized skills (orchestrator + 7 specialists) for engineering workflows with swarm-aware orchestration.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
> This package is part of Maestria. See [VISION.md](https://github.com/agustinusnathaniel/maestria/blob/main/VISION.md) for the project vision, motivation, and scope. The skills and rules are **generated** from the canonical directives in `packages/core/agent-directives/` by the [sync pipeline](https://github.com/agustinusnathaniel/maestria/blob/main/CONTRIBUTING.md#3-the-sync-pipeline-core-concept).
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
## Installation
|
|
8
8
|
|
|
9
9
|
```bash
|
|
10
|
+
# Recommended: via the maestria CLI (pulls the package from npm into ~/.kimi-code/plugins/managed/maestria)
|
|
10
11
|
pnpx maestria@latest install kimi-code
|
|
11
12
|
pnpx maestria@latest status
|
|
12
|
-
```
|
|
13
|
-
|
|
14
|
-
The CLI pulls `@maestria/kimi-code` from npm and extracts it into `~/.kimi-code/plugins/managed/maestria`.
|
|
15
|
-
|
|
16
|
-
## The 8 Skills at a Glance
|
|
17
|
-
|
|
18
|
-
| Skill | Subagent | Purpose |
|
|
19
|
-
| --- | --- | --- |
|
|
20
|
-
| `orchestrator` | main | Auto-loaded at session start. Methodology, delegation, swarm. |
|
|
21
|
-
| `builder` | `coder` | Focused implementation - atomic tasks, write code, run tests. |
|
|
22
|
-
| `adventurer` | `explore` | Codebase reconnaissance - read-only exploration, structured reports. |
|
|
23
|
-
| `architect` | `coder` | Architecture decisions, trade-offs, ADRs. |
|
|
24
|
-
| `planner` | `plan` | Multi-phase implementation plans, success criteria, rollback. |
|
|
25
|
-
| `reviewer` | `coder` | Code review with quality gates - no editing, structured feedback. |
|
|
26
|
-
| `writer` | `coder` | Documentation - READMEs, API docs, changelogs, ADR transcription. |
|
|
27
|
-
| `diagnose` | `coder` | Root cause analysis - 6-step methodology, blast-radius audit. |
|
|
28
|
-
|
|
29
|
-
The orchestrator's `whenToUse` field teaches the model when to dispatch each persona. The 7 specialists are loaded on demand via the `Skill` tool.
|
|
30
|
-
|
|
31
|
-
## Design Philosophy
|
|
32
|
-
|
|
33
|
-
This plugin is built on the **Harness Engineering** principle: `Agent = Model + Harness`. The harness is what turns a raw LLM into a reliable coding agent - the model is just one component.
|
|
34
|
-
|
|
35
|
-
The 6 harness components map directly to plugin features:
|
|
36
|
-
|
|
37
|
-
| Component | Plugin Mapping |
|
|
38
|
-
| ----------------- | ---------------------------------------------------------------------------- |
|
|
39
|
-
| **Instructions** | `rules/AGENTS.md` placed at `~/.kimi-code/AGENTS.md` (auto-loaded) |
|
|
40
|
-
| **Tools** | Skill prescription per specialist; `AgentSwarm` for parallel fan-out |
|
|
41
|
-
| **Sandboxes** | Subagent profile tool lists (`coder`/`explore`/`plan`); `permission.rules` |
|
|
42
|
-
| **Orchestration** | `sessionStart.skill` (orchestrator auto-loads); `Agent` / `AgentSwarm` tools |
|
|
43
|
-
| **Guardrails** | `!!!` rule markers in every SKILL.md; iteration limits; persona constraints |
|
|
44
|
-
| **Observability** | `PreCompact` / `PostCompact` hooks (observation-only); structured handoffs |
|
|
45
|
-
|
|
46
|
-
Most agent failures are configuration failures, not model failures. The plugin's skills are designed with this principle - precise rules, explicit boundaries, and clear delegation chains over raw capability.
|
|
47
|
-
|
|
48
|
-
### How It Works
|
|
49
13
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
4. **Rules loaded** - `~/.kimi-code/AGENTS.md` (which the user copies from `rules/AGENTS.md`) is auto-loaded by Kimi Code's session-start context preparer.
|
|
54
|
-
5. **Specialists dispatched** - the orchestrator loads specialist skills via the `Skill` tool and inlines them into `Agent` / `AgentSwarm` prompts.
|
|
55
|
-
6. **Swarm fan-out** - for ≥3 uniform items, `AgentSwarm` runs the same persona against a list of items, returning a single `<agent_swarm_result>` envelope.
|
|
14
|
+
# Update (latest by default; pin with --version)
|
|
15
|
+
pnpx maestria@latest update kimi-code
|
|
16
|
+
```
|
|
56
17
|
|
|
57
|
-
|
|
18
|
+
See [INSTALL.md](https://github.com/agustinusnathaniel/maestria/blob/main/packages/kimi-code/INSTALL.md) for the full checklist, including the recommended `[[hooks]]` and `[[permission.rules]]` tool-layer safety configuration.
|
|
58
19
|
|
|
59
|
-
|
|
20
|
+
## What It Provides
|
|
60
21
|
|
|
61
|
-
- **
|
|
62
|
-
- **
|
|
63
|
-
- **
|
|
22
|
+
- **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.
|
|
23
|
+
- **Swarm-aware orchestration** - routes ≥3 uniform items through Kimi Code's `AgentSwarm` for parallel fan-out.
|
|
24
|
+
- **Global rules** - `rules/AGENTS.md` auto-loaded by Kimi Code at session start.
|
|
25
|
+
- **Declarative-only** - manifest plus `skills/` and `rules/`; no TypeScript, SDK hooks, or build step.
|
|
64
26
|
|
|
65
|
-
|
|
27
|
+
## Support / Platform Notes
|
|
66
28
|
|
|
67
|
-
|
|
29
|
+
- Kimi Code hardcodes its `coder`/`explore`/`plan` subagents; the 7 specialist identities are persona content in prompt templates, not custom subagent definitions.
|
|
30
|
+
- Persona text is advisory; tool-layer enforcement comes from the user-applied `[[hooks]]`/`[[permission.rules]]` blocks documented in `INSTALL.md`.
|
|
31
|
+
- The generated skills and rules are projections of the canonical core directives. To change behavior, edit `packages/core/agent-directives/` and re-run the sync pipeline - never edit the generated files under `skills/` or `rules/` directly.
|
|
68
32
|
|
|
69
|
-
|
|
70
|
-
pnpx maestria@latest update kimi-code
|
|
71
|
-
```
|
|
33
|
+
## Documentation and Changelog
|
|
72
34
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
pnpx maestria@latest update kimi-code@0.4.6
|
|
77
|
-
```
|
|
78
|
-
|
|
79
|
-
See [INSTALL.md](./INSTALL.md) for details.
|
|
35
|
+
- [User-facing documentation](https://maestria.sznm.dev/kimi-code/) on the docs site
|
|
36
|
+
- [Installation checklist](https://github.com/agustinusnathaniel/maestria/blob/main/packages/kimi-code/INSTALL.md)
|
|
37
|
+
- [Changelog](https://github.com/agustinusnathaniel/maestria/blob/main/packages/kimi-code/CHANGELOG.md)
|
|
80
38
|
|
|
81
39
|
## Contributing
|
|
82
40
|
|
|
83
|
-
See [Contributing](/kimi-code/contributing/) on the docs site.
|
|
41
|
+
See [Contributing](https://maestria.sznm.dev/kimi-code/contributing/) on the docs site.
|
|
84
42
|
|
|
85
43
|
## License
|
|
86
44
|
|
|
87
45
|
MIT
|
|
88
|
-
|
|
89
|
-
## Related
|
|
90
|
-
|
|
91
|
-
- [`@maestria/opencode`](../opencode/README.md) - the OpenCode variant of this plugin (TypeScript SDK, programmatic hooks).
|
package/package.json
CHANGED
package/rules/AGENTS.md
CHANGED
|
@@ -35,6 +35,14 @@ This is the cross-platform behavior contract. It defines outcomes, evidence, saf
|
|
|
35
35
|
- Adjacent findings do not expand the current task automatically. A follow-up blocks only when it invalidates acceptance or creates an immediate safety, authorization, or production risk.
|
|
36
36
|
- Security, authentication, authorization, and permission findings are mandatory stops. Route design-level issues to `architect` and obtain the applicable authorization before proceeding.
|
|
37
37
|
|
|
38
|
+
## Session Continuation and Delivery
|
|
39
|
+
|
|
40
|
+
- **!!! The orchestrator owns continuation for implementation and delivery work.** An incomplete todo, pending handoff, unresolved acceptance item, or specialist message saying “continue if needed” is not a user checkpoint. Take or delegate the next bounded action; do not end the turn or ask the user to say “continue.” Research-only, planning-only, explicitly Read-only, and host-blocked work terminates at its requested artifact or exact blocker.
|
|
41
|
+
- A specialist's Read-only or no-edit result ends that delegation, not the parent work unit. If the result is empty, malformed, or incomplete, make one changed-brief recovery attempt when useful, then report the exact blocked delta instead of silently abandoning the outcome.
|
|
42
|
+
- Freeze the outcome, acceptance criteria, non-goals, and review budget at the start of the work unit. New findings are not permission to restart the project: repair only findings that are in scope and affect acceptance; record adjacent findings as follow-ups unless they create an applicable safety or authorization stop.
|
|
43
|
+
- Do not reset a review or repair budget by splitting the same outcome into more delegations, changing specialist names, or relabelling the finding. A new scope requires a new outcome and acceptance criteria.
|
|
44
|
+
- For implementation work, continue through validation and the project's normal delivery artifact. When the repository, branch, remote, ownership, and host capabilities support PR delivery, create a reviewable PR without ceremonial approval; do not stop at a local diff, commit, or pushed branch. Research-only, planning-only, explicitly Read-only, and host-blocked work terminates at its requested artifact or exact blocker. Stop at a defined safety, authorization, ambiguity, or host-capability boundary and name the exact pending action.
|
|
45
|
+
|
|
38
46
|
## Delegation and Context
|
|
39
47
|
|
|
40
48
|
Supported specialists are `adventurer`, `architect`, `builder`, `diagnose`, `planner`, `reviewer`, and `writer`.
|
|
@@ -103,7 +103,13 @@ Modes are case-insensitive and per-turn unless the platform documents another li
|
|
|
103
103
|
|
|
104
104
|
## Commit and Session Flow
|
|
105
105
|
|
|
106
|
-
For
|
|
106
|
+
For implementation work, own the delivery path: `inspect -> plan -> implement -> validate -> review -> repair -> commit -> push -> PR`.
|
|
107
|
+
|
|
108
|
+
When the repository, branch, remote, ownership, and host capabilities support PR delivery, complete it without ceremonial approval. Do not stop at a local diff, commit, pushed branch, or `PR pending`. Merge, release, and production actions remain separate.
|
|
109
|
+
|
|
110
|
+
The parent session owns continuation until the selected implementation outcome reaches its terminal artifact. Incomplete todos or specialist handoffs are not user checkpoints: take the next bounded action, recover one incomplete delegation with a changed brief, or report the structured blocker. Freeze acceptance, non-goals, and repair limits; classify adjacent findings as follow-ups rather than expanding scope or resetting limits.
|
|
111
|
+
|
|
112
|
+
Research-only, planning-only, explicitly read-only, `sonar`, and host-blocked routes terminate at their requested artifact or exact blocker. Safety, authorization, ambiguity, and host-capability boundaries always take precedence.
|
|
107
113
|
|
|
108
114
|
An explicitly authorized checkpoint may preserve unreviewed work but never authorizes shipping. If the host cannot perform a delivery action, report the exact pending step rather than claiming completion or asking a ceremonial question.
|
|
109
115
|
|