@plumpslabs/kuma 2.3.10 → 2.3.13

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.
Files changed (6) hide show
  1. package/dist/{agentDetector-3OTNKKBS.js → agentDetector-YOWQVJFR.js} +4 -4
  2. package/dist/{chunk-J2CBDLXB.js → chunk-ITTJ4SGO.js} +227 -79
  3. package/dist/index.js +9 -9
  4. package/dist/{init-LLP6JDFR.js → init-AI6FVWZI.js} +1 -1
  5. package/dist/{skillGenerator-ILZFWO5O.js → skillGenerator-3PNJV5YU.js} +55 -39
  6. package/package.json +1 -1
package/dist/{agentDetector-3OTNKKBS.js → agentDetector-YOWQVJFR.js} RENAMED
@@ -43,10 +43,10 @@ var AGENT_DETECTORS = [
43
43
  },
44
44
  {
45
45
  type: "opencode",
46
- checkFiles: ["opencode.json"],
47
- checkDirs: [],
46
+ checkFiles: [".agents/skills/kuma/SKILL.md"],
47
+ checkDirs: [".agents"],
48
48
  priority: 65,
49
- label: "OpenCode (opencode.json)"
49
+ label: "OpenCode (.agents/skills/kuma/SKILL.md)"
50
50
  },
51
51
  {
52
52
  type: "kiro",
@@ -152,7 +152,7 @@ function getSkillPath(type) {
152
152
  return ".agents/skills/kuma/SKILL.md";
153
153
  // Same path as Antigravity
154
154
  case "opencode":
155
- return "opencode.json";
155
+ return ".agents/skills/kuma/SKILL.md";
156
156
  case "aider":
157
157
  return "CONVENTIONS.md";
158
158
  case "windsurf":
package/dist/{chunk-J2CBDLXB.js → chunk-ITTJ4SGO.js} RENAMED
@@ -28,7 +28,7 @@ var CONFIG_LABELS = {
28
28
  cline: "Cline (.clinerules/*.md)",
29
29
  aider: "Aider (CONVENTIONS.md via .aider.conf.yml)",
30
30
  antigravity: "Antigravity CLI (.agents/skills/)",
31
- opencode: "OpenCode (opencode.json + skills)",
31
+ opencode: "OpenCode (AGENTS.md + skills)",
32
32
  codex: "Codex CLI (AGENTS.md + .codex/config.toml)",
33
33
  qwen: "Qwen Code (AGENTS.md + settings.json)",
34
34
  kiro: "Kiro (.kiro/steering/*.md)",
@@ -52,7 +52,7 @@ function configFilePath(type) {
52
52
  case "antigravity":
53
53
  return ".agents/skills/kuma/SKILL.md";
54
54
  case "opencode":
55
- return "opencode.json";
55
+ return "AGENTS.md";
56
56
  case "codex":
57
57
  return "AGENTS.md";
58
58
  case "qwen":
@@ -66,9 +66,23 @@ function configFilePath(type) {
66
66
  }
67
67
  }
68
68
  var BOOTSTRAP_LINES = [
69
- "Kuma MCP tools are installed. All behavioral rules are in `.kuma/init.md`.",
70
- "**Before coding, call `kuma_init()`** to load project context and session memory.",
71
- "Project knowledge persists in `.kuma/memories/*.md` across sessions."
69
+ "Kuma MCP tools are installed (kuma_context, kuma_memory, kuma_safety).",
70
+ '**Before coding, call `kuma_context({ action: "init" })`** to load project context and session memory.',
71
+ "Project knowledge persists in `.kuma/memories/*.md` across sessions.",
72
+ "",
73
+ "\u26A0\uFE0F **MANDATORY WORKFLOW** \u2014 Follow in order every session:",
74
+ "",
75
+ ' 1. `kuma_context({ action: "init" })` \u2014 Load context (START HERE)',
76
+ ' 2. `kuma_safety({ action: "guard" })` \u2014 Safety check before work',
77
+ ' 3. `kuma_context({ action: "research", scope: "<area>" })` \u2014 Research before editing',
78
+ " 4. *(edit using native tools)*",
79
+ ' 5. `kuma_memory({ action: "research_save", scope: "<area>" })` \u2014 Save findings',
80
+ ' 6. `kuma_safety({ action: "verify", scope: "<area>" })` \u2014 Verify changes',
81
+ ' 7. `kuma_context({ action: "changes" })` \u2014 Review changes',
82
+ "",
83
+ "\u26D4 Skipping workflow = stale context, missed decisions, unverified code.",
84
+ "\u{1F4D6} Full rules: `.kuma/init.md`",
85
+ "\u{1F9E0} Tools: `kuma_context` | `kuma_memory` | `kuma_safety`"
72
86
  ].join("\n");
73
87
  var KUMA_CORE_INSTRUCTIONS = BOOTSTRAP_LINES;
74
88
  function claudeTemplate() {
@@ -132,19 +146,15 @@ function aiderTemplate() {
132
146
  KUMA_CORE_INSTRUCTIONS
133
147
  ].join("\n");
134
148
  }
135
- function opencodeTemplate() {
136
- const config = {
137
- $schema: "https://opencode-ai.github.io/schema.json",
138
- mcp: {
139
- kuma: {
140
- type: "local",
141
- command: ["npx", "-y", "@plumpslabs/kuma"],
142
- enabled: true
143
- }
144
- },
145
- instructions: [".kuma/init.md"]
146
- };
147
- return JSON.stringify(config, null, 2) + "\n";
149
+ function opencodeAgentsMdTemplate() {
150
+ return [
151
+ "## Kuma MCP \u2014 OpenCode",
152
+ "",
153
+ KUMA_CORE_INSTRUCTIONS,
154
+ "",
155
+ "\u{1F4D6} Rules: `.kuma/init.md`",
156
+ "\u{1F9E0} Skill: `.agents/skills/kuma/SKILL.md`"
157
+ ].join("\n");
148
158
  }
149
159
  function codexTemplate() {
150
160
  return [
@@ -253,74 +263,201 @@ function antigravityMcpConfigTemplate() {
253
263
  }
254
264
  function generateInitMdContent() {
255
265
  return [
256
- "# Kuma Init \u2014 Behavioral Rules",
266
+ "# Kuma Init \u2014 Mandatory Workflow",
257
267
  "",
258
268
  "_(Auto-generated by `kuma init` \u2014 edit this file directly to customize rules)_",
259
269
  "",
260
- "## Kuma V3 \u2014 3 Coarse-Grained Tools",
261
- "",
262
- "Kuma provides 3 pipeline-driven tools. Each action triggers a multi-step deterministic workflow internally.",
263
- "",
264
- "### \u{1F9E0} kuma_context \u2014 Context & Research (call FIRST every session)",
265
- "",
266
- '- `kuma_context({ action: "init" })` \u2014 Load project brief, detect stack, show structure',
267
- '- **`kuma_context({ action: "research", scope: "..." })` \u2014 WAJIB before editing unfamiliar code**',
268
- " - 5-step pipeline: load cache \u2192 check staleness \u2192 query graph \u2192 impact analysis \u2192 decision lookup",
269
- '- `kuma_context({ action: "impact", target: "symbol" })` \u2014 Analyze change effects',
270
- '- `kuma_context({ action: "navigate", target: "flow" })` \u2014 Trace code flow',
271
- '- `kuma_context({ action: "changes" })` \u2014 View session change log',
272
- '- `kuma_context({ action: "health" })` \u2014 Project health score 0-100',
273
- "",
274
- "### \u{1F4DD} kuma_memory \u2014 Decision & Knowledge",
270
+ "---",
275
271
  "",
276
- '- `kuma_memory({ action: "research_save", scope: "...", ... })` \u2014 Save research results',
277
- '- `kuma_memory({ action: "decision", decisionAction: "record", ... })` \u2014 ADR-style decision',
278
- '- **`kuma_memory({ action: "mine", scope: "..." })` \u2014 Mine historical decisions from git log & comments**',
279
- '- `kuma_memory({ action: "session" })` \u2014 Session summary',
280
- '- `kuma_memory({ action: "heal" })` \u2014 Self-heal knowledge graph',
281
- '- `kuma_memory({ action: "search", query: "..." })` \u2014 Search memories + graph',
282
- '- `kuma_memory({ action: "changes" })` \u2014 View change log',
272
+ "## \u26A0\uFE0F SESSION WORKFLOW \u2014 Follow Steps in Order",
273
+ "",
274
+ "### STEP 1: Init Session (ALWAYS \u2014 Start of Session)",
275
+ "```",
276
+ 'kuma_context({ action: "init" })',
277
+ "```",
278
+ "**When:** Every session start or project switch",
279
+ "**Why:** Load project brief, restore session memory, populate knowledge graph",
280
+ "",
281
+ "### STEP 2: Safety Guard (ALWAYS \u2014 Before Work)",
282
+ "```",
283
+ 'kuma_safety({ action: "guard", guardGoal: "describe your intent" })',
284
+ "```",
285
+ "**When:** After STEP 1, before research or editing",
286
+ "**Why:** Detect anti-patterns, code drift, runaway loops upfront",
287
+ "",
288
+ "### STEP 3: Research (MANDATORY \u2014 Before Editing Unfamiliar Code)",
289
+ "```",
290
+ 'kuma_context({ action: "research", scope: "<target area>" })',
291
+ "```",
292
+ "**When:** Every time you plan to edit code in an unfamiliar area",
293
+ "**Why:** 5-step pipeline: cache load \u2192 staleness check \u2192 graph query \u2192 impact analysis \u2192 decision lookup",
294
+ "",
295
+ "> \u26D4 DO NOT EDIT FILES BEFORE STEP 3 \u2014 Unless trivial/minor change",
296
+ "",
297
+ "### STEP 4: EDIT \u2014 Implement (Use Agent Native Tools)",
298
+ "```",
299
+ "# Use agent BUILT-IN tools to read, grep, edit, create files",
300
+ "# Kuma does NOT manage files \u2014 that's your agent's job",
301
+ "```",
302
+ "",
303
+ "**AUTO-RECORDED nodes/edges** (Kuma scanner detects these automatically):",
304
+ "- Files, Functions, Classes \u2192 created as graph nodes",
305
+ "- Imports, Calls, Extends \u2192 created as graph edges",
306
+ "- Variables, Components, Routes \u2192 created when detected",
307
+ "",
308
+ "**MANUAL \u2014 When to call these yourself:**",
309
+ '- `kuma_memory({ action: "research_save" })` \u2014 after exploring/learning something new',
310
+ '- `kuma_memory({ action: "decision" })` \u2014 after making an architecture/design choice',
311
+ '- `kuma_memory({ action: "context" })` \u2014 inject arbitrary context notes',
312
+ '- `kuma_memory({ action: "domain_rules" })` \u2014 record business rules',
313
+ '- `kuma_memory({ action: "arch_flow" })` \u2014 document architecture flow',
314
+ '- `kuma_memory({ action: "gotcha" })` \u2014 log known quirks/workarounds',
315
+ '- `kuma_memory({ action: "todo" })` \u2014 create persistent task',
316
+ '- `kuma_memory({ action: "mine" })` \u2014 extract historical decisions from git',
317
+ "",
318
+ "### STEP 5: Save Research (AFTER Editing)",
319
+ "```",
320
+ 'kuma_memory({ action: "research_save", scope: "<area>", confidence: 0.8 })',
321
+ "```",
322
+ "**When:** After exploring a new area or finishing edits",
323
+ "**Why:** Persist findings into knowledge graph + research cache",
324
+ "",
325
+ "### STEP 6: Record Decision (AFTER Significant Changes)",
326
+ "```",
327
+ 'kuma_memory({ action: "decision", decisionAction: "record", title: "...", outcome: "..." })',
328
+ "```",
329
+ "**When:** After making architecture/design decisions",
330
+ "**Why:** Saves ADR (Architecture Decision Record) to the decision log",
331
+ "",
332
+ "### STEP 7: Verify (AFTER Editing)",
333
+ "```",
334
+ 'kuma_safety({ action: "verify", scope: "<area or file>" })',
335
+ "```",
336
+ "**When:** After edits are done, before switching tasks",
337
+ "**Why:** Auto-run scoped tests + AST code validation",
338
+ "",
339
+ "### STEP 8: Check Changes (BEFORE Commit / End of Session)",
340
+ "```",
341
+ 'kuma_context({ action: "changes" })',
342
+ "```",
343
+ "**When:** End of session or before git commit",
344
+ "**Why:** Review all modifications made in this session",
283
345
  "",
284
- "### \u{1F6E1}\uFE0F kuma_safety \u2014 Safety & Policy",
346
+ "---",
285
347
  "",
286
- '- `kuma_safety({ action: "guard", guardGoal: "..." })` \u2014 Anti-pattern, drift, loop detection',
287
- '- **`kuma_safety({ action: "verify", scope: "..." })` \u2014 Auto-run scoped tests & verify correctness**',
288
- '- `kuma_safety({ action: "check", ... })` \u2014 Pre-execution safety check',
289
- '- `kuma_safety({ action: "audit" })` \u2014 Query safety audit trail',
290
- '- `kuma_safety({ action: "lock", lockAction: "acquire", ... })` \u2014 Multi-agent file lock',
291
- '- `kuma_safety({ action: "health" })` \u2014 Safety score 0-100',
292
- '- `kuma_safety({ action: "override", ... })` \u2014 Logged safety bypass',
348
+ "## \u{1F4CB} Tool Reference",
293
349
  "",
294
- "## Mandatory Research Pipeline",
350
+ "### \u{1F9E0} kuma_context \u2014 Context & Research",
295
351
  "",
296
- "**Before editing any unfamiliar code, you MUST call:**",
352
+ "| Action | Description | When to Call |",
353
+ "|--------|-------------|--------------|",
354
+ "| `init` | Load project brief, restore session | STEP 1 \u2014 Every session |",
355
+ "| `research` | 5-step research pipeline | STEP 3 \u2014 Before edits |",
356
+ "| `impact` | Analyze change effects on symbol | After research, before design |",
357
+ "| `navigate` | Trace code flow | When need to understand call flow |",
358
+ "| `changes` | View session change log | STEP 8 \u2014 End of session |",
359
+ "| `health` | Project health score 0-100 | Periodic check |",
360
+ "| `digest` | Ultra-compact project briefing | Session start (alt to init) |",
361
+ "| `drift` | Detect memory staleness | When suspecting stale context |",
297
362
  "",
298
- ' kuma_context({ action: "research", scope: "<area>" })',
363
+ "### \u{1F4DD} kuma_memory \u2014 Decision & Knowledge",
299
364
  "",
300
- "This runs: cache load \u2192 staleness check \u2192 graph query \u2192 impact analysis \u2192 decision lookup.",
301
- "Only after reviewing the structured result should you make changes.",
365
+ "| Action | Description | When to Call |",
366
+ "|--------|-------------|--------------|",
367
+ "| `research_save` | Save research results | STEP 5 \u2014 After exploring/editing |",
368
+ "| `decision` | ADR-style decision record | STEP 6 \u2014 After major decisions |",
369
+ "| `mine` | Mine decisions from git log | When need historical context |",
370
+ "| `session` | Session summary | End of session |",
371
+ "| `heal` | Self-heal knowledge graph | When graph has errors |",
372
+ "| `search` | Search memories + graph | Find stored information |",
373
+ "| `todo` | Persistent todo CRUD | When managing tasks |",
374
+ "| `context` | Inject context notes | Manual \u2014 additional notes |",
375
+ "| `domain_rules` | Layer 1: business rules | Manual \u2014 record business rules |",
376
+ "| `arch_flow` | Layer 2: architecture flow | Manual \u2014 document architecture |",
377
+ "| `gotcha` | Layer 3: known gotchas | Manual \u2014 log quirks/legacy |",
378
+ "| `layers` | Show all 3 layers summary | Overview memory layers |",
302
379
  "",
303
- "After editing, save what you learned:",
380
+ "### \u{1F6E1}\uFE0F kuma_safety \u2014 Safety & Policy",
304
381
  "",
305
- ' kuma_memory({ action: "research_save", scope: "<area>", confidence: 0-1 })',
382
+ "| Action | Description | When to Call |",
383
+ "|--------|-------------|--------------|",
384
+ "| `guard` | Anti-pattern, drift, loop | STEP 2 \u2014 Before work |",
385
+ "| `verify` | Auto-run scoped tests | STEP 7 \u2014 After edits |",
386
+ "| `check` | Pre-execution safety check | Before risky operations |",
387
+ "| `audit` | Query safety audit trail | Security investigation |",
388
+ "| `lock` | Multi-agent file lock | Multi-agent collaboration |",
389
+ "| `health` | Safety score 0-100 | Periodic check |",
390
+ "| `policy` | Policy-as-Code engine | Evaluate command/file paths |",
391
+ "| `ast` | AST-based code validation | Code correctness checks |",
392
+ "| `checkpoint` | Create atomic snapshot | Before major refactors |",
393
+ "| `contract` | Pre/post-condition check | Contract verification |",
306
394
  "",
307
- "## General Rules",
395
+ "---",
308
396
  "",
309
- '- **Call `kuma_context({ action: "init" })` at session start** \u2014 always',
310
- '- **Research before edit** \u2014 always call `kuma_context({ action: "research" })` first',
311
- '- **Save after research** \u2014 use `kuma_memory({ action: "research_save" })` to persist',
312
- '- **Record decisions** \u2014 use `kuma_memory({ action: "decision" })` for significant changes',
313
- '- **Verify with guard** \u2014 use `kuma_safety({ action: "guard" })` after editing',
314
- '- **Check changes** \u2014 use `kuma_context({ action: "changes" })` to track what you modified',
397
+ "## \u{1F4CA} Knowledge Graph \u2014 Node Types & Shapes",
398
+ "",
399
+ "Kuma's knowledge graph visualizes your project structure. Each node type has a unique shape:",
400
+ "",
401
+ "| Shape | Node Type | Description | Auto/Manual |",
402
+ "|-------|-----------|-------------|-------------|",
403
+ "| \u25A2 `box` | function | Functions (named/arrow) | AUTO by scanner |",
404
+ "| \u2B21 `hexagon` | class | Classes (TS/JS) | AUTO by scanner |",
405
+ "| \u25CB `ellipse` | module | Directory modules | AUTO by scanner |",
406
+ "| \u25C7 `diamond` | component | React/Vue components | AUTO by scanner |",
407
+ "| \u25A3 `square` | file | Source files | AUTO by scanner |",
408
+ "| \u25B2 `triangle` | route | API routes | AUTO by scanner |",
409
+ "| \u2B52 `star` | test | Test files/describes | AUTO by scanner |",
410
+ "| \u{1F4C4} `note` | context | Manual context notes | MANUAL \u2014 kuma_memory context |",
411
+ "| \u{1F3F7}\uFE0F `tag` | domain_rule | Business rules (Layer 1) | MANUAL \u2014 kuma_memory domain_rules |",
412
+ "| \u{1F500} `flow` | arch_flow | Architecture flows (Layer 2) | MANUAL \u2014 kuma_memory arch_flow |",
413
+ "| \u26A0\uFE0F `warning` | gotcha | Known gotchas (Layer 3) | MANUAL \u2014 kuma_memory gotcha |",
414
+ "| \u{1F4CC} `milestone` | decision | Architecture decisions | MANUAL \u2014 kuma_memory decision |",
415
+ "| \u2705 `checklist` | todo | Persistent todos | MANUAL \u2014 kuma_memory todo |",
416
+ "",
417
+ "**Edges (connections between nodes):**",
418
+ "- `imports` \u2014 file imports another (AUTO)",
419
+ "- `calls` \u2014 function calls another (AUTO)",
420
+ "- `defines` \u2014 file defines function/class (AUTO)",
421
+ "- `depends_on` \u2014 logical dependency (AUTO + MANUAL)",
422
+ "- `extends` \u2014 class extends class (AUTO)",
423
+ "- `contains` \u2014 file contains function (AUTO)",
424
+ "- `composes` \u2014 component contains sub-component (AUTO)",
425
+ "- `references` \u2014 node references context note (MANUAL)",
315
426
  "",
316
- "## What Kuma Does NOT Do (Use Agent Native Tools)",
427
+ "---",
317
428
  "",
318
- "- Editing files \u2014 use your AI agent's native edit tools",
319
- "- Searching code \u2014 use your agent's native grep/search",
320
- "- Running commands \u2014 use your agent's native terminal",
321
- "- Creating files \u2014 use your agent's native file creation",
322
- "- Git operations \u2014 use your agent's native git tools",
323
- "- Linting/testing \u2014 use your agent's native run commands",
429
+ "## \u{1F4CC} Workflow Summary",
430
+ "",
431
+ "```",
432
+ "EVERY SESSION (Mandatory):",
433
+ " 1. kuma_context \u2192 init \u2014 Load project context",
434
+ " 2. kuma_safety \u2192 guard \u2014 Safety check",
435
+ " 3. kuma_context \u2192 research \u2014 Research target area",
436
+ " --- EDIT (use native tools) ---",
437
+ " 5. kuma_memory \u2192 research_save \u2014 Save findings",
438
+ " 6. kuma_memory \u2192 decision \u2014 Record decisions",
439
+ " 7. kuma_safety \u2192 verify \u2014 Verify correctness",
440
+ " 8. kuma_context \u2192 changes \u2014 Review changes",
441
+ "",
442
+ "MANUAL (When needed):",
443
+ " kuma_memory \u2192 domain_rules \u2014 Business rules (Layer 1)",
444
+ " kuma_memory \u2192 arch_flow \u2014 Architecture flow (Layer 2)",
445
+ " kuma_memory \u2192 gotcha \u2014 Known quirks (Layer 3)",
446
+ " kuma_memory \u2192 context \u2014 Additional notes",
447
+ " kuma_memory \u2192 todo \u2014 Task management",
448
+ " kuma_memory \u2192 mine \u2014 Historical context",
449
+ "```",
450
+ "",
451
+ "## \u{1F6AB} What Kuma Does NOT Do (Use Agent Native Tools)",
452
+ "",
453
+ "| Function | Correct Tool |",
454
+ "|----------|-------------|",
455
+ "| Edit files | Agent native edit tools |",
456
+ "| Search code | Agent native grep/search |",
457
+ "| Run commands | Agent native terminal |",
458
+ "| Create files | Agent native file creation |",
459
+ "| Git operations | Agent native git tools |",
460
+ "| Lint/test | Agent native run commands |",
324
461
  "",
325
462
  "---",
326
463
  "_Generated by Kuma MCP - https://github.com/plumpslabs/kuma_"
@@ -334,7 +471,7 @@ var TEMPLATES = {
334
471
  cline: clineRulesTemplate,
335
472
  aider: aiderTemplate,
336
473
  antigravity: antigravitySkillTemplate,
337
- opencode: opencodeTemplate,
474
+ opencode: opencodeAgentsMdTemplate,
338
475
  codex: codexTemplate,
339
476
  qwen: qwenTemplate,
340
477
  kiro: kiroRulesTemplate,
@@ -353,11 +490,21 @@ function handleOpencodeSecondary(root, results) {
353
490
  "description: Kuma MCP \u2014 safety toolkit for AI coding agents. Research, memory, and safety guard.",
354
491
  "---",
355
492
  "",
356
- "Kuma MCP tools are installed. All behavioral rules are in `.kuma/init.md`.",
357
- "**Before coding, call `kuma_init()` to load project context and session memory.**",
493
+ "Kuma MCP tools are installed (kuma_context, kuma_memory, kuma_safety).",
494
+ '**Before coding, call `kuma_context({ action: "init" })`** to load project context and session memory.',
358
495
  "Project knowledge persists in `.kuma/memories/*.md` across sessions.",
359
496
  "",
360
- "MCP server configured in `opencode.json`."
497
+ "\u26A0\uFE0F **MANDATORY WORKFLOW** \u2014 Follow in order every session:",
498
+ "",
499
+ ' 1. `kuma_context({ action: "init" })` \u2014 Load context (START HERE)',
500
+ ' 2. `kuma_safety({ action: "guard" })` \u2014 Safety check before work',
501
+ ' 3. `kuma_context({ action: "research", scope: "<area>" })` \u2014 Research before editing',
502
+ " 4. *(edit using native tools)*",
503
+ ' 5. `kuma_memory({ action: "research_save", scope: "<area>" })` \u2014 Save findings',
504
+ ' 6. `kuma_safety({ action: "verify", scope: "<area>" })` \u2014 Verify changes',
505
+ ' 7. `kuma_context({ action: "changes" })` \u2014 Review changes',
506
+ "",
507
+ "\u{1F4D6} Full rules: `.kuma/init.md`"
361
508
  ].join("\n");
362
509
  if (fs.existsSync(skillPath)) {
363
510
  const existing = fs.readFileSync(skillPath, "utf-8");
@@ -365,7 +512,9 @@ function handleOpencodeSecondary(root, results) {
365
512
  results.push({ type: "opencode", filePath: ".agents/skills/kuma/SKILL.md", action: "skipped" });
366
513
  return;
367
514
  }
368
- results.push({ type: "opencode", filePath: ".agents/skills/kuma/SKILL.md", action: "skipped" });
515
+ const newContent = existing.trimEnd() + "\n\n---\n\n" + content;
516
+ fs.writeFileSync(skillPath, newContent, "utf-8");
517
+ results.push({ type: "opencode", filePath: ".agents/skills/kuma/SKILL.md", action: "appended" });
369
518
  } else {
370
519
  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
371
520
  fs.writeFileSync(skillPath, content, "utf-8");
@@ -453,7 +602,7 @@ function handleQwenSecondary(root, results) {
453
602
  });
454
603
  }
455
604
  }
456
- var AGENTS_MD_TYPES = ["codex", "qwen", "copilot"];
605
+ var AGENTS_MD_TYPES = ["opencode", "codex", "qwen", "copilot"];
457
606
  function getAgentsMdHeader() {
458
607
  return [
459
608
  "# Kuma MCP - Combined Agent Instructions",
@@ -468,7 +617,7 @@ function getAgentsMdHeader() {
468
617
  }
469
618
  function getCombinedAgentsMd(selectedTypes) {
470
619
  const sections = [getAgentsMdHeader()];
471
- const agentOrder = ["codex", "qwen", "copilot"];
620
+ const agentOrder = ["opencode", "codex", "qwen", "copilot"];
472
621
  for (const t of agentOrder) {
473
622
  if (selectedTypes.has(t)) {
474
623
  sections.push(TEMPLATES[t]());
@@ -707,6 +856,7 @@ function runInit(options) {
707
856
  fs.writeFileSync(fullPath, combinedContent, "utf-8");
708
857
  results.push({ type, filePath: relativePath, action: "created" });
709
858
  }
859
+ if (selectedSet.has("opencode")) handleOpencodeSecondary(root, results);
710
860
  if (selectedSet.has("codex")) handleCodexSecondary(root, results);
711
861
  if (selectedSet.has("qwen")) handleQwenSecondary(root, results);
712
862
  if (selectedSet.has("copilot")) handleCopilotSecondary(root, results);
@@ -751,8 +901,6 @@ function runInit(options) {
751
901
  handleCodewhaleSecondary(root, results);
752
902
  } else if (type === "aider") {
753
903
  handleAiderSecondary(root, results);
754
- } else if (type === "opencode") {
755
- handleOpencodeSecondary(root, results);
756
904
  }
757
905
  }
758
906
  } catch (err) {
package/dist/index.js CHANGED
@@ -8,7 +8,7 @@ import {
8
8
  ALL_CONFIG_TYPES,
9
9
  formatInitResults,
10
10
  runInit
11
- } from "./chunk-J2CBDLXB.js";
11
+ } from "./chunk-ITTJ4SGO.js";
12
12
  import {
13
13
  formatDecisionTemplate,
14
14
  getProactiveMemories,
@@ -2161,7 +2161,7 @@ async function handleVerify(params) {
2161
2161
  function registerAllTools(server) {
2162
2162
  server.tool(
2163
2163
  "kuma_context",
2164
- "**Call FIRST every session.** Understand your project before making changes. Actions: init (load project brief), research (5-step pipeline: cache\u2192staleness\u2192graph\u2192impact\u2192decision), impact (analyze change effects), navigate (trace code flow), changes (view change log), health (project health score 0-100). RESEARCH IS REQUIRED before editing unfamiliar code.",
2164
+ "**Call FIRST every session.** Understand your project before making changes.\n\nWORKFLOW:\n\u2022 STEP 1 (ALWAYS): `init` \u2014 load project brief, restore session\n\u2022 STEP 3 (BEFORE edits): `research` \u2014 5-step pipeline (cache\u2192staleness\u2192graph\u2192impact\u2192decision)\n\u2022 STEP 8 (END of session): `changes` \u2014 review what you modified\n\nOther actions: impact (analyze changes), navigate (trace flow), health (score 0-100), digest (compact briefing), drift (detect staleness).",
2165
2165
  {
2166
2166
  action: z.enum(["init", "research", "impact", "navigate", "changes", "health", "rollback", "researches", "sync", "visualize", "digest", "drift", "progressive"]).describe("Action: init=project brief, research=5-step research pipeline (REQUIRED before edits), impact=analyze change effects, navigate=trace code flow, changes=view change log, rollback=undo a change by ID, researches=list all cached research, sync=unified batch state, visualize=Mermaid knowledge graph diagram, digest=ultra-compact <500 token project briefing (Issue #18), drift=detect memory staleness & code drift (Issue #20), progressive=progressive context loading (Issue #25), health=project health score"),
2167
2167
  scope: z.string().optional().describe("Research scope for research/progressive action"),
@@ -2190,7 +2190,7 @@ function registerAllTools(server) {
2190
2190
  );
2191
2191
  server.tool(
2192
2192
  "kuma_memory",
2193
- "Record and retrieve project knowledge. Actions: decision (ADR-style record/template/suggest), mine (mine historical decisions from git log & code comments), research_save (save research), session (session summary), heal (graph repair), search (search all), changes (change log), todo (persistent todo CRUD), context (inject context notes), benchmark (capture/diff metrics), decision_log (living document with status tracking).",
2193
+ "**Call AFTER editing** to persist what you learned.\n\nAFTER EDITING (call these yourself):\n\u2022 STEP 5: `research_save` \u2014 save findings into knowledge graph\n\u2022 STEP 6: `decision` \u2014 record architecture decisions (ADR)\n\nMANUAL (call when you discover something):\n\u2022 `gotcha` \u2014 found a quirk/workaround/legacy issue? Log it!\n\u2022 `domain_rules` \u2014 uncovered business rules? Save them!\n\u2022 `arch_flow` \u2014 mapped out architecture flow? Document it!\n\u2022 `context` \u2014 need to inject extra notes? Use this!\n\u2022 `todo` \u2014 create persistent task items\n\u2022 `mine` \u2014 extract historical context from git log\n\nOther actions: session, heal, search, changes, benchmark, layers.",
2194
2194
  {
2195
2195
  action: z.enum(["decision", "mine", "research_save", "session", "heal", "search", "changes", "todo", "context", "benchmark", "decision_log", "domain_rules", "arch_flow", "gotcha", "layers", "federated", "gen_test", "trajectory", "skills"]).describe("Memory action: decision=ADR, mine=mine git log & comments, research_save=save, session=summary, heal=repair, search=search, changes=log, todo=manage todos, context=inject notes, benchmark=capture/diff, decision_log=manage decisions, domain_rules=Layer 1 business rules (Issue #17), arch_flow=Layer 2 architecture flow (Issue #17), gotcha=Layer 3 known gotchas (Issue #17/#21), layers=all 3 layers summary, federated=resolve federated kuma:// URI (Issue #27), gen_test=generate test from trajectory (Issue #28), trajectory=list trajectories, skills=list distilled skills"),
2196
2196
  scope: z.string().optional().describe("Scope for research_save/search/todo/context/mine/federated"),
@@ -2257,7 +2257,7 @@ function registerAllTools(server) {
2257
2257
  );
2258
2258
  server.tool(
2259
2259
  "kuma_safety",
2260
- "Safety checks, policy enforcement, security scanning, integrated auto-verification, and project hygiene. Actions: guard (anti-pattern detection), verify (auto-run scoped tests), check (pre-exec safety), audit (query trail), lock (multi-agent), health (score), security (scan for leaks), gc (garbage collection), doctor (health check), portability (path check), gitignore (auto-config), override (bypass).",
2260
+ "Safety checks, policy enforcement, and auto-verification.\n\nWORKFLOW:\n\u2022 STEP 2 (BEFORE work): `guard` \u2014 detect anti-patterns, drift, runaway loops\n\u2022 STEP 7 (AFTER edits): `verify` \u2014 auto-run scoped tests + AST validation\n\nOther actions: check (pre-exec safety), audit (query trail), lock (multi-agent), health (score 0-100), policy (evaluate commands), ast (code validation), checkpoint (snapshot before refactors), contract (pre/post-condition check).",
2261
2261
  {
2262
2262
  action: z.enum(["guard", "verify", "check", "audit", "lock", "health", "override", "security", "gc", "doctor", "portability", "gitignore", "clean", "policy", "ast", "validate", "checkpoint", "rollback_label", "checkpoint_list", "contract"]).describe("Safety action: guard=anti-patterns, verify=auto-run scoped tests, check=pre-exec safety, audit=query trail, lock=multi-agent, health=score, security=scan leaks, gc=garbage collect, doctor=health check, portability=paths, gitignore=config, clean=purge scratch dir & drift, policy=Policy-as-Code engine (Issue #24), ast/validate=AST-based code validation (Issue #22), checkpoint=create atomic snapshot (Issue #29), rollback_label=restore from checkpoint (Issue #29), checkpoint_list=list checkpoints, contract=run contract checks (Issue #26), override=bypass"),
2263
2263
  // Verify params
@@ -2345,7 +2345,7 @@ Available config files:
2345
2345
  --cline .clinerules/kuma.md (Cline)
2346
2346
  --aider CONVENTIONS.md + .aider.conf.yml (Aider)
2347
2347
  --antigravity .agents/skills/kuma/SKILL.md (Antigravity CLI)
2348
- --opencode opencode.json (OpenCode)
2348
+ --opencode AGENTS.md + .agents/skills/ (OpenCode)
2349
2349
  --codex AGENTS.md + .codex/ (Codex CLI - OpenAI)
2350
2350
  --qwen AGENTS.md + settings.json (Qwen Code)
2351
2351
  --kiro .kiro/steering/kuma.md (Kiro)
@@ -2571,7 +2571,7 @@ async function main() {
2571
2571
  });
2572
2572
  (async () => {
2573
2573
  try {
2574
- const { generateInitMdContent } = await import("./init-LLP6JDFR.js");
2574
+ const { generateInitMdContent } = await import("./init-AI6FVWZI.js");
2575
2575
  const fs7 = await import("fs");
2576
2576
  const path7 = await import("path");
2577
2577
  const initMdPath = path7.resolve(process.cwd(), ".kuma/init.md");
@@ -2587,8 +2587,8 @@ async function main() {
2587
2587
  })();
2588
2588
  (async () => {
2589
2589
  try {
2590
- const { detectAgent, getSkillPath, getAgentLabel } = await import("./agentDetector-3OTNKKBS.js");
2591
- const { generateSkill, getSecondaryFiles } = await import("./skillGenerator-ILZFWO5O.js");
2590
+ const { detectAgent, getSkillPath, getAgentLabel } = await import("./agentDetector-YOWQVJFR.js");
2591
+ const { generateSkill, getSecondaryFiles } = await import("./skillGenerator-3PNJV5YU.js");
2592
2592
  const fs7 = await import("fs");
2593
2593
  const path7 = await import("path");
2594
2594
  const detection = detectAgent();
@@ -2759,7 +2759,7 @@ function interactiveSelect() {
2759
2759
  type: "antigravity",
2760
2760
  label: "7) Antigravity CLI (.agents/skills/)"
2761
2761
  },
2762
- { type: "opencode", label: "8) OpenCode (opencode.json)" },
2762
+ { type: "opencode", label: "8) OpenCode (AGENTS.md + skills)" },
2763
2763
  {
2764
2764
  type: "codex",
2765
2765
  label: "9) Codex CLI - OpenAI (AGENTS.md + .codex/config.toml)"
package/dist/{init-LLP6JDFR.js → init-AI6FVWZI.js} RENAMED
@@ -4,7 +4,7 @@ import {
4
4
  formatInitResults,
5
5
  generateInitMdContent,
6
6
  runInit
7
- } from "./chunk-J2CBDLXB.js";
7
+ } from "./chunk-ITTJ4SGO.js";
8
8
  import "./chunk-E2KFPEBT.js";
9
9
  export {
10
10
  ALL_CONFIG_TYPES,
package/dist/{skillGenerator-ILZFWO5O.js → skillGenerator-3PNJV5YU.js} RENAMED
@@ -1,8 +1,22 @@
1
1
  // src/utils/skillGenerator.ts
2
2
  var BOOTSTRAP = [
3
- "Kuma MCP tools are available. All behavioral rules are in `.kuma/init.md`.",
4
- "**Before coding, call `kuma_init()`** to load project context and session memory.",
5
- "Project knowledge persists in `.kuma/memories/*.md` across sessions."
3
+ "Kuma MCP tools are available (kuma_context, kuma_memory, kuma_safety).",
4
+ '**Before coding, call `kuma_context({ action: "init" })`** to load project context and session memory.',
5
+ "Project knowledge persists in `.kuma/memories/*.md` across sessions.",
6
+ "",
7
+ "\u26A0\uFE0F **MANDATORY WORKFLOW** \u2014 Follow in order every session:",
8
+ "",
9
+ ' 1. `kuma_context({ action: "init" })` \u2014 Load context (START HERE)',
10
+ ' 2. `kuma_safety({ action: "guard" })` \u2014 Safety check before work',
11
+ ' 3. `kuma_context({ action: "research", scope: "<area>" })` \u2014 Research before editing',
12
+ " 4. *(edit using native tools)*",
13
+ ' 5. `kuma_memory({ action: "research_save", scope: "<area>" })` \u2014 Save findings',
14
+ ' 6. `kuma_safety({ action: "verify", scope: "<area>" })` \u2014 Verify changes',
15
+ ' 7. `kuma_context({ action: "changes" })` \u2014 Review changes',
16
+ "",
17
+ "\u26D4 Skipping workflow = stale context, missed decisions, unverified code.",
18
+ "\u{1F4D6} Full rules: `.kuma/init.md`",
19
+ "\u{1F9E0} Tools: `kuma_context` | `kuma_memory` | `kuma_safety`"
6
20
  ].join("\n");
7
21
  function generateSkill(type) {
8
22
  switch (type) {
@@ -60,8 +74,9 @@ function generateClaudeSkill() {
60
74
  BOOTSTRAP,
61
75
  "",
62
76
  "\u{1F4D6} **Usage:**",
63
- " \u2022 `kuma_init()` \u2014 load project context (call first)",
64
- ' \u2022 `kuma_guard({check: "all"})` \u2014 safety check before risky ops',
77
+ ' \u2022 `kuma_context({ action: "init" })` \u2014 load project context (call first)',
78
+ ' \u2022 `kuma_safety({ action: "guard" })` \u2014 safety check before risky ops',
79
+ ' \u2022 `kuma_safety({ action: "verify", scope: "<area>" })` \u2014 verify after edits',
65
80
  " \u2022 `.kuma/init.md` \u2014 full behavioral rules",
66
81
  " \u2022 `.kuma/memories/` \u2014 persistent project knowledge"
67
82
  ].join("\n");
@@ -76,9 +91,9 @@ function generateCursorSkill() {
76
91
  BOOTSTRAP,
77
92
  "",
78
93
  "\u{1F4D6} **Usage:**",
79
- " \u2022 `kuma_init()` \u2014 load project context (call first)",
80
- ' \u2022 `kuma_guard({check: "all"})` \u2014 safety check before risky ops',
81
- ' \u2022 `kuma_verify({action: "test"})` \u2014 verify after edits',
94
+ ' \u2022 `kuma_context({ action: "init" })` \u2014 load project context (call first)',
95
+ ' \u2022 `kuma_safety({ action: "guard" })` \u2014 safety check before risky ops',
96
+ ' \u2022 `kuma_safety({ action: "verify", scope: "<area>" })` \u2014 verify after edits',
82
97
  " \u2022 `.kuma/init.md` \u2014 full behavioral rules",
83
98
  " \u2022 `.kuma/memories/` \u2014 persistent project knowledge"
84
99
  ].join("\n");
@@ -94,8 +109,9 @@ function generateClineSkill() {
94
109
  BOOTSTRAP,
95
110
  "",
96
111
  "\u{1F4D6} **Usage:**",
97
- " \u2022 `kuma_init()` \u2014 load project context (call first)",
98
- ' \u2022 `kuma_guard({check: "all"})` \u2014 safety check before risky ops',
112
+ ' \u2022 `kuma_context({ action: "init" })` \u2014 load project context (call first)',
113
+ ' \u2022 `kuma_safety({ action: "guard" })` \u2014 safety check before risky ops',
114
+ ' \u2022 `kuma_safety({ action: "verify", scope: "<area>" })` \u2014 verify after edits',
99
115
  " \u2022 `.kuma/init.md` \u2014 full behavioral rules"
100
116
  ].join("\n");
101
117
  }
@@ -109,9 +125,9 @@ function generateAntigravitySkill() {
109
125
  BOOTSTRAP,
110
126
  "",
111
127
  "\u{1F4D6} **Usage:**",
112
- " \u2022 `kuma_init()` \u2014 load project context (call first)",
113
- ' \u2022 `kuma_guard({check: "all"})` \u2014 safety check',
114
- ' \u2022 `kuma_verify({action: "test"})` \u2014 verify after edits',
128
+ ' \u2022 `kuma_context({ action: "init" })` \u2014 load project context (call first)',
129
+ ' \u2022 `kuma_safety({ action: "guard" })` \u2014 safety check',
130
+ ' \u2022 `kuma_safety({ action: "verify", scope: "<area>" })` \u2014 verify after edits',
115
131
  " \u2022 `.kuma/init.md` \u2014 full behavioral rules"
116
132
  ].join("\n");
117
133
  }
@@ -141,17 +157,16 @@ function generateCodexConfigToml() {
141
157
  ].join("\n");
142
158
  }
143
159
  function generateOpencodeSkill() {
144
- return JSON.stringify({
145
- $schema: "https://opencode-ai.github.io/schema.json",
146
- mcp: {
147
- kuma: {
148
- type: "local",
149
- command: ["npx", "-y", "@plumpslabs/kuma"],
150
- enabled: true
151
- }
152
- },
153
- instructions: [".kuma/init.md"]
154
- }, null, 2) + "\n";
160
+ return [
161
+ "---",
162
+ "name: kuma-mcp",
163
+ "description: Kuma MCP \u2014 safety toolkit for AI coding agents. Research, memory, and safety guard.",
164
+ "---",
165
+ "",
166
+ BOOTSTRAP,
167
+ "",
168
+ "\u{1F4D6} Read `.kuma/init.md` for detailed rules."
169
+ ].join("\n");
155
170
  }
156
171
  function generateAiderSkill() {
157
172
  return [
@@ -160,8 +175,9 @@ function generateAiderSkill() {
160
175
  BOOTSTRAP,
161
176
  "",
162
177
  "\u{1F4D6} **Usage:**",
163
- " \u2022 `kuma_init()` \u2014 load project context (call first)",
164
- ' \u2022 `kuma_guard({check: "all"})` \u2014 safety check',
178
+ ' \u2022 `kuma_context({ action: "init" })` \u2014 load project context (call first)',
179
+ ' \u2022 `kuma_safety({ action: "guard" })` \u2014 safety check',
180
+ ' \u2022 `kuma_safety({ action: "verify", scope: "<area>" })` \u2014 verify after edits',
165
181
  " \u2022 `.kuma/init.md` \u2014 full behavioral rules"
166
182
  ].join("\n");
167
183
  }
@@ -178,10 +194,7 @@ function generateWindsurfSkill() {
178
194
  return [
179
195
  "# Kuma MCP \u2014 Windsurf",
180
196
  "",
181
- "Windsurf Cascade agent: Kuma MCP tools are available.",
182
- "All behavioral rules are in `.kuma/init.md`.",
183
- "**Before coding, call `kuma_init()` to load project context.**",
184
- "Project knowledge persists in `.kuma/memories/*.md` across sessions.",
197
+ BOOTSTRAP,
185
198
  "",
186
199
  "Also auto-detected via `.windsurf/skills/` and `.agents/skills/`."
187
200
  ].join("\n");
@@ -196,8 +209,9 @@ function generateCopilotSkill() {
196
209
  BOOTSTRAP,
197
210
  "",
198
211
  "\u{1F4D6} **Usage:**",
199
- " \u2022 `kuma_init()` \u2014 load project context (call first)",
200
- ' \u2022 `kuma_guard({check: "all"})` \u2014 safety check',
212
+ ' \u2022 `kuma_context({ action: "init" })` \u2014 load project context (call first)',
213
+ ' \u2022 `kuma_safety({ action: "guard" })` \u2014 safety check',
214
+ ' \u2022 `kuma_safety({ action: "verify", scope: "<area>" })` \u2014 verify after edits',
201
215
  " \u2022 `.kuma/init.md` \u2014 full behavioral rules"
202
216
  ].join("\n");
203
217
  }
@@ -208,8 +222,9 @@ function generateQwenSkill() {
208
222
  BOOTSTRAP,
209
223
  "",
210
224
  "\u{1F4D6} **Usage:**",
211
- " \u2022 `kuma_init()` \u2014 load project context (call first)",
212
- ' \u2022 `kuma_guard({check: "all"})` \u2014 safety check',
225
+ ' \u2022 `kuma_context({ action: "init" })` \u2014 load project context (call first)',
226
+ ' \u2022 `kuma_safety({ action: "guard" })` \u2014 safety check',
227
+ ' \u2022 `kuma_safety({ action: "verify", scope: "<area>" })` \u2014 verify after edits',
213
228
  " \u2022 `.kuma/init.md` \u2014 full behavioral rules"
214
229
  ].join("\n");
215
230
  }
@@ -235,9 +250,9 @@ function generateKiroSkill() {
235
250
  BOOTSTRAP,
236
251
  "",
237
252
  "\u{1F4D6} **Usage:**",
238
- " \u2022 `kuma_init()` \u2014 load project context (call first)",
239
- ' \u2022 `kuma_guard({check: "all"})` \u2014 safety check',
240
- ' \u2022 `kuma_verify({action: "test"})` \u2014 verify after edits',
253
+ ' \u2022 `kuma_context({ action: "init" })` \u2014 load project context (call first)',
254
+ ' \u2022 `kuma_safety({ action: "guard" })` \u2014 safety check',
255
+ ' \u2022 `kuma_safety({ action: "verify", scope: "<area>" })` \u2014 verify after edits',
241
256
  " \u2022 `.kuma/init.md` \u2014 full behavioral rules"
242
257
  ].join("\n");
243
258
  }
@@ -251,8 +266,9 @@ function generateOpenclawSkill() {
251
266
  BOOTSTRAP,
252
267
  "",
253
268
  "\u{1F4D6} **Usage:**",
254
- " \u2022 `kuma_init()` \u2014 load project context (call first)",
255
- ' \u2022 `kuma_guard({check: "all"})` \u2014 safety check',
269
+ ' \u2022 `kuma_context({ action: "init" })` \u2014 load project context (call first)',
270
+ ' \u2022 `kuma_safety({ action: "guard" })` \u2014 safety check',
271
+ ' \u2022 `kuma_safety({ action: "verify", scope: "<area>" })` \u2014 verify after edits',
256
272
  " \u2022 `.kuma/init.md` \u2014 full behavioral rules"
257
273
  ].join("\n");
258
274
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@plumpslabs/kuma",
3
- "version": "2.3.10",
3
+ "version": "2.3.13",
4
4
  "description": "Safety-first context & orchestration engine for AI coding agents. MCP server with mandatory research pipeline, knowledge graph, impact analysis, decision memory, and safety guard — works with any MCP client.",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",