@plumpslabs/kuma 2.3.10 → 2.3.12

package/dist/{agentDetector-3OTNKKBS.js → agentDetector-YOWQVJFR.js}

@@ -43,10 +43,10 @@ var AGENT_DETECTORS = [
   },
   {
     type: "opencode",
-    checkFiles: ["opencode.json"],
-    checkDirs: [],
+    checkFiles: [".agents/skills/kuma/SKILL.md"],
+    checkDirs: [".agents"],
     priority: 65,
-    label: "OpenCode (opencode.json)"
+    label: "OpenCode (.agents/skills/kuma/SKILL.md)"
   },
   {
     type: "kiro",
@@ -152,7 +152,7 @@ function getSkillPath(type) {
       return ".agents/skills/kuma/SKILL.md";
     // Same path as Antigravity
     case "opencode":
-      return "opencode.json";
+      return ".agents/skills/kuma/SKILL.md";
     case "aider":
       return "CONVENTIONS.md";
     case "windsurf":

package/dist/{chunk-J2CBDLXB.js → chunk-CRQ7WTPV.js}

@@ -28,7 +28,7 @@ var CONFIG_LABELS = {
   cline: "Cline (.clinerules/*.md)",
   aider: "Aider (CONVENTIONS.md via .aider.conf.yml)",
   antigravity: "Antigravity CLI (.agents/skills/)",
-  opencode: "OpenCode (opencode.json + skills)",
+  opencode: "OpenCode (AGENTS.md + skills)",
   codex: "Codex CLI (AGENTS.md + .codex/config.toml)",
   qwen: "Qwen Code (AGENTS.md + settings.json)",
   kiro: "Kiro (.kiro/steering/*.md)",
@@ -52,7 +52,7 @@ function configFilePath(type) {
     case "antigravity":
       return ".agents/skills/kuma/SKILL.md";
     case "opencode":
-      return "opencode.json";
+      return "AGENTS.md";
     case "codex":
       return "AGENTS.md";
     case "qwen":
@@ -66,8 +66,8 @@ function configFilePath(type) {
   }
 }
 var BOOTSTRAP_LINES = [
-  "Kuma MCP tools are installed. All behavioral rules are in `.kuma/init.md`.",
-  "**Before coding, call `kuma_init()`** to load project context and session memory.",
+  "Kuma MCP tools are installed (kuma_context, kuma_memory, kuma_safety). All behavioral rules are in `.kuma/init.md`.",
+  '**Before coding, call `kuma_context({ action: "init" })`** to load project context and session memory.',
   "Project knowledge persists in `.kuma/memories/*.md` across sessions."
 ].join("\n");
 var KUMA_CORE_INSTRUCTIONS = BOOTSTRAP_LINES;
@@ -132,19 +132,15 @@ function aiderTemplate() {
     KUMA_CORE_INSTRUCTIONS
   ].join("\n");
 }
-function opencodeTemplate() {
-  const config = {
-    $schema: "https://opencode-ai.github.io/schema.json",
-    mcp: {
-      kuma: {
-        type: "local",
-        command: ["npx", "-y", "@plumpslabs/kuma"],
-        enabled: true
-      }
-    },
-    instructions: [".kuma/init.md"]
-  };
-  return JSON.stringify(config, null, 2) + "\n";
+function opencodeAgentsMdTemplate() {
+  return [
+    "## Kuma MCP \u2014 OpenCode",
+    "",
+    KUMA_CORE_INSTRUCTIONS,
+    "",
+    "\u{1F4D6} Rules: `.kuma/init.md`",
+    "\u{1F9E0} Skill: `.agents/skills/kuma/SKILL.md`"
+  ].join("\n");
 }
 function codexTemplate() {
   return [
@@ -253,74 +249,201 @@ function antigravityMcpConfigTemplate() {
 }
 function generateInitMdContent() {
   return [
-    "# Kuma Init \u2014 Behavioral Rules",
+    "# Kuma Init \u2014 Mandatory Workflow",
     "",
     "_(Auto-generated by `kuma init` \u2014 edit this file directly to customize rules)_",
     "",
-    "## Kuma V3 \u2014 3 Coarse-Grained Tools",
-    "",
-    "Kuma provides 3 pipeline-driven tools. Each action triggers a multi-step deterministic workflow internally.",
-    "",
-    "### \u{1F9E0} kuma_context \u2014 Context & Research (call FIRST every session)",
-    "",
-    '- `kuma_context({ action: "init" })` \u2014 Load project brief, detect stack, show structure',
-    '- **`kuma_context({ action: "research", scope: "..." })` \u2014 WAJIB before editing unfamiliar code**',
-    "  - 5-step pipeline: load cache \u2192 check staleness \u2192 query graph \u2192 impact analysis \u2192 decision lookup",
-    '- `kuma_context({ action: "impact", target: "symbol" })` \u2014 Analyze change effects',
-    '- `kuma_context({ action: "navigate", target: "flow" })` \u2014 Trace code flow',
-    '- `kuma_context({ action: "changes" })` \u2014 View session change log',
-    '- `kuma_context({ action: "health" })` \u2014 Project health score 0-100',
-    "",
-    "### \u{1F4DD} kuma_memory \u2014 Decision & Knowledge",
+    "---",
     "",
-    '- `kuma_memory({ action: "research_save", scope: "...", ... })` \u2014 Save research results',
-    '- `kuma_memory({ action: "decision", decisionAction: "record", ... })` \u2014 ADR-style decision',
-    '- **`kuma_memory({ action: "mine", scope: "..." })` \u2014 Mine historical decisions from git log & comments**',
-    '- `kuma_memory({ action: "session" })` \u2014 Session summary',
-    '- `kuma_memory({ action: "heal" })` \u2014 Self-heal knowledge graph',
-    '- `kuma_memory({ action: "search", query: "..." })` \u2014 Search memories + graph',
-    '- `kuma_memory({ action: "changes" })` \u2014 View change log',
+    "## \u26A0\uFE0F SESSION WORKFLOW \u2014 Follow Steps in Order",
+    "",
+    "### STEP 1: Init Session (ALWAYS \u2014 Start of Session)",
+    "```",
+    'kuma_context({ action: "init" })',
+    "```",
+    "**When:** Every session start or project switch",
+    "**Why:** Load project brief, restore session memory, populate knowledge graph",
+    "",
+    "### STEP 2: Safety Guard (ALWAYS \u2014 Before Work)",
+    "```",
+    'kuma_safety({ action: "guard", guardGoal: "describe your intent" })',
+    "```",
+    "**When:** After STEP 1, before research or editing",
+    "**Why:** Detect anti-patterns, code drift, runaway loops upfront",
+    "",
+    "### STEP 3: Research (MANDATORY \u2014 Before Editing Unfamiliar Code)",
+    "```",
+    'kuma_context({ action: "research", scope: "<target area>" })',
+    "```",
+    "**When:** Every time you plan to edit code in an unfamiliar area",
+    "**Why:** 5-step pipeline: cache load \u2192 staleness check \u2192 graph query \u2192 impact analysis \u2192 decision lookup",
+    "",
+    "> \u26D4 DO NOT EDIT FILES BEFORE STEP 3 \u2014 Unless trivial/minor change",
+    "",
+    "### STEP 4: EDIT \u2014 Implement (Use Agent Native Tools)",
+    "```",
+    "# Use agent BUILT-IN tools to read, grep, edit, create files",
+    "# Kuma does NOT manage files \u2014 that's your agent's job",
+    "```",
+    "",
+    "**AUTO-RECORDED nodes/edges** (Kuma scanner detects these automatically):",
+    "- Files, Functions, Classes \u2192 created as graph nodes",
+    "- Imports, Calls, Extends \u2192 created as graph edges",
+    "- Variables, Components, Routes \u2192 created when detected",
+    "",
+    "**MANUAL \u2014 When to call these yourself:**",
+    '- `kuma_memory({ action: "research_save" })` \u2014 after exploring/learning something new',
+    '- `kuma_memory({ action: "decision" })` \u2014 after making an architecture/design choice',
+    '- `kuma_memory({ action: "context" })` \u2014 inject arbitrary context notes',
+    '- `kuma_memory({ action: "domain_rules" })` \u2014 record business rules',
+    '- `kuma_memory({ action: "arch_flow" })` \u2014 document architecture flow',
+    '- `kuma_memory({ action: "gotcha" })` \u2014 log known quirks/workarounds',
+    '- `kuma_memory({ action: "todo" })` \u2014 create persistent task',
+    '- `kuma_memory({ action: "mine" })` \u2014 extract historical decisions from git',
+    "",
+    "### STEP 5: Save Research (AFTER Editing)",
+    "```",
+    'kuma_memory({ action: "research_save", scope: "<area>", confidence: 0.8 })',
+    "```",
+    "**When:** After exploring a new area or finishing edits",
+    "**Why:** Persist findings into knowledge graph + research cache",
+    "",
+    "### STEP 6: Record Decision (AFTER Significant Changes)",
+    "```",
+    'kuma_memory({ action: "decision", decisionAction: "record", title: "...", outcome: "..." })',
+    "```",
+    "**When:** After making architecture/design decisions",
+    "**Why:** Saves ADR (Architecture Decision Record) to the decision log",
+    "",
+    "### STEP 7: Verify (AFTER Editing)",
+    "```",
+    'kuma_safety({ action: "verify", scope: "<area or file>" })',
+    "```",
+    "**When:** After edits are done, before switching tasks",
+    "**Why:** Auto-run scoped tests + AST code validation",
+    "",
+    "### STEP 8: Check Changes (BEFORE Commit / End of Session)",
+    "```",
+    'kuma_context({ action: "changes" })',
+    "```",
+    "**When:** End of session or before git commit",
+    "**Why:** Review all modifications made in this session",
     "",
-    "### \u{1F6E1}\uFE0F kuma_safety \u2014 Safety & Policy",
+    "---",
     "",
-    '- `kuma_safety({ action: "guard", guardGoal: "..." })` \u2014 Anti-pattern, drift, loop detection',
-    '- **`kuma_safety({ action: "verify", scope: "..." })` \u2014 Auto-run scoped tests & verify correctness**',
-    '- `kuma_safety({ action: "check", ... })` \u2014 Pre-execution safety check',
-    '- `kuma_safety({ action: "audit" })` \u2014 Query safety audit trail',
-    '- `kuma_safety({ action: "lock", lockAction: "acquire", ... })` \u2014 Multi-agent file lock',
-    '- `kuma_safety({ action: "health" })` \u2014 Safety score 0-100',
-    '- `kuma_safety({ action: "override", ... })` \u2014 Logged safety bypass',
+    "## \u{1F4CB} Tool Reference",
     "",
-    "## Mandatory Research Pipeline",
+    "### \u{1F9E0} kuma_context \u2014 Context & Research",
     "",
-    "**Before editing any unfamiliar code, you MUST call:**",
+    "| Action | Description | When to Call |",
+    "|--------|-------------|--------------|",
+    "| `init` | Load project brief, restore session | STEP 1 \u2014 Every session |",
+    "| `research` | 5-step research pipeline | STEP 3 \u2014 Before edits |",
+    "| `impact` | Analyze change effects on symbol | After research, before design |",
+    "| `navigate` | Trace code flow | When need to understand call flow |",
+    "| `changes` | View session change log | STEP 8 \u2014 End of session |",
+    "| `health` | Project health score 0-100 | Periodic check |",
+    "| `digest` | Ultra-compact project briefing | Session start (alt to init) |",
+    "| `drift` | Detect memory staleness | When suspecting stale context |",
     "",
-    '    kuma_context({ action: "research", scope: "<area>" })',
+    "### \u{1F4DD} kuma_memory \u2014 Decision & Knowledge",
     "",
-    "This runs: cache load \u2192 staleness check \u2192 graph query \u2192 impact analysis \u2192 decision lookup.",
-    "Only after reviewing the structured result should you make changes.",
+    "| Action | Description | When to Call |",
+    "|--------|-------------|--------------|",
+    "| `research_save` | Save research results | STEP 5 \u2014 After exploring/editing |",
+    "| `decision` | ADR-style decision record | STEP 6 \u2014 After major decisions |",
+    "| `mine` | Mine decisions from git log | When need historical context |",
+    "| `session` | Session summary | End of session |",
+    "| `heal` | Self-heal knowledge graph | When graph has errors |",
+    "| `search` | Search memories + graph | Find stored information |",
+    "| `todo` | Persistent todo CRUD | When managing tasks |",
+    "| `context` | Inject context notes | Manual \u2014 additional notes |",
+    "| `domain_rules` | Layer 1: business rules | Manual \u2014 record business rules |",
+    "| `arch_flow` | Layer 2: architecture flow | Manual \u2014 document architecture |",
+    "| `gotcha` | Layer 3: known gotchas | Manual \u2014 log quirks/legacy |",
+    "| `layers` | Show all 3 layers summary | Overview memory layers |",
     "",
-    "After editing, save what you learned:",
+    "### \u{1F6E1}\uFE0F kuma_safety \u2014 Safety & Policy",
     "",
-    '    kuma_memory({ action: "research_save", scope: "<area>", confidence: 0-1 })',
+    "| Action | Description | When to Call |",
+    "|--------|-------------|--------------|",
+    "| `guard` | Anti-pattern, drift, loop | STEP 2 \u2014 Before work |",
+    "| `verify` | Auto-run scoped tests | STEP 7 \u2014 After edits |",
+    "| `check` | Pre-execution safety check | Before risky operations |",
+    "| `audit` | Query safety audit trail | Security investigation |",
+    "| `lock` | Multi-agent file lock | Multi-agent collaboration |",
+    "| `health` | Safety score 0-100 | Periodic check |",
+    "| `policy` | Policy-as-Code engine | Evaluate command/file paths |",
+    "| `ast` | AST-based code validation | Code correctness checks |",
+    "| `checkpoint` | Create atomic snapshot | Before major refactors |",
+    "| `contract` | Pre/post-condition check | Contract verification |",
     "",
-    "## General Rules",
+    "---",
     "",
-    '- **Call `kuma_context({ action: "init" })` at session start** \u2014 always',
-    '- **Research before edit** \u2014 always call `kuma_context({ action: "research" })` first',
-    '- **Save after research** \u2014 use `kuma_memory({ action: "research_save" })` to persist',
-    '- **Record decisions** \u2014 use `kuma_memory({ action: "decision" })` for significant changes',
-    '- **Verify with guard** \u2014 use `kuma_safety({ action: "guard" })` after editing',
-    '- **Check changes** \u2014 use `kuma_context({ action: "changes" })` to track what you modified',
+    "## \u{1F4CA} Knowledge Graph \u2014 Node Types & Shapes",
+    "",
+    "Kuma's knowledge graph visualizes your project structure. Each node type has a unique shape:",
+    "",
+    "| Shape | Node Type | Description | Auto/Manual |",
+    "|-------|-----------|-------------|-------------|",
+    "| \u25A2 `box` | function | Functions (named/arrow) | AUTO by scanner |",
+    "| \u2B21 `hexagon` | class | Classes (TS/JS) | AUTO by scanner |",
+    "| \u25CB `ellipse` | module | Directory modules | AUTO by scanner |",
+    "| \u25C7 `diamond` | component | React/Vue components | AUTO by scanner |",
+    "| \u25A3 `square` | file | Source files | AUTO by scanner |",
+    "| \u25B2 `triangle` | route | API routes | AUTO by scanner |",
+    "| \u2B52 `star` | test | Test files/describes | AUTO by scanner |",
+    "| \u{1F4C4} `note` | context | Manual context notes | MANUAL \u2014 kuma_memory context |",
+    "| \u{1F3F7}\uFE0F `tag` | domain_rule | Business rules (Layer 1) | MANUAL \u2014 kuma_memory domain_rules |",
+    "| \u{1F500} `flow` | arch_flow | Architecture flows (Layer 2) | MANUAL \u2014 kuma_memory arch_flow |",
+    "| \u26A0\uFE0F `warning` | gotcha | Known gotchas (Layer 3) | MANUAL \u2014 kuma_memory gotcha |",
+    "| \u{1F4CC} `milestone` | decision | Architecture decisions | MANUAL \u2014 kuma_memory decision |",
+    "| \u2705 `checklist` | todo | Persistent todos | MANUAL \u2014 kuma_memory todo |",
+    "",
+    "**Edges (connections between nodes):**",
+    "- `imports` \u2014 file imports another (AUTO)",
+    "- `calls` \u2014 function calls another (AUTO)",
+    "- `defines` \u2014 file defines function/class (AUTO)",
+    "- `depends_on` \u2014 logical dependency (AUTO + MANUAL)",
+    "- `extends` \u2014 class extends class (AUTO)",
+    "- `contains` \u2014 file contains function (AUTO)",
+    "- `composes` \u2014 component contains sub-component (AUTO)",
+    "- `references` \u2014 node references context note (MANUAL)",
     "",
-    "## What Kuma Does NOT Do (Use Agent Native Tools)",
+    "---",
     "",
-    "- Editing files \u2014 use your AI agent's native edit tools",
-    "- Searching code \u2014 use your agent's native grep/search",
-    "- Running commands \u2014 use your agent's native terminal",
-    "- Creating files \u2014 use your agent's native file creation",
-    "- Git operations \u2014 use your agent's native git tools",
-    "- Linting/testing \u2014 use your agent's native run commands",
+    "## \u{1F4CC} Workflow Summary",
+    "",
+    "```",
+    "EVERY SESSION (Mandatory):",
+    "  1. kuma_context   \u2192 init             \u2014 Load project context",
+    "  2. kuma_safety    \u2192 guard            \u2014 Safety check",
+    "  3. kuma_context   \u2192 research         \u2014 Research target area",
+    "  --- EDIT (use native tools) ---",
+    "  5. kuma_memory    \u2192 research_save    \u2014 Save findings",
+    "  6. kuma_memory    \u2192 decision         \u2014 Record decisions",
+    "  7. kuma_safety    \u2192 verify           \u2014 Verify correctness",
+    "  8. kuma_context   \u2192 changes          \u2014 Review changes",
+    "",
+    "MANUAL (When needed):",
+    "  kuma_memory \u2192 domain_rules   \u2014 Business rules (Layer 1)",
+    "  kuma_memory \u2192 arch_flow      \u2014 Architecture flow (Layer 2)",
+    "  kuma_memory \u2192 gotcha         \u2014 Known quirks (Layer 3)",
+    "  kuma_memory \u2192 context        \u2014 Additional notes",
+    "  kuma_memory \u2192 todo           \u2014 Task management",
+    "  kuma_memory \u2192 mine           \u2014 Historical context",
+    "```",
+    "",
+    "## \u{1F6AB} What Kuma Does NOT Do (Use Agent Native Tools)",
+    "",
+    "| Function | Correct Tool |",
+    "|----------|-------------|",
+    "| Edit files | Agent native edit tools |",
+    "| Search code | Agent native grep/search |",
+    "| Run commands | Agent native terminal |",
+    "| Create files | Agent native file creation |",
+    "| Git operations | Agent native git tools |",
+    "| Lint/test | Agent native run commands |",
     "",
     "---",
     "_Generated by Kuma MCP - https://github.com/plumpslabs/kuma_"
@@ -334,7 +457,7 @@ var TEMPLATES = {
   cline: clineRulesTemplate,
   aider: aiderTemplate,
   antigravity: antigravitySkillTemplate,
-  opencode: opencodeTemplate,
+  opencode: opencodeAgentsMdTemplate,
   codex: codexTemplate,
   qwen: qwenTemplate,
   kiro: kiroRulesTemplate,
@@ -357,7 +480,7 @@ function handleOpencodeSecondary(root, results) {
       "**Before coding, call `kuma_init()` to load project context and session memory.**",
       "Project knowledge persists in `.kuma/memories/*.md` across sessions.",
       "",
-      "MCP server configured in `opencode.json`."
+      "\u{1F4D6} Read `.kuma/init.md` for detailed rules."
     ].join("\n");
     if (fs.existsSync(skillPath)) {
       const existing = fs.readFileSync(skillPath, "utf-8");
@@ -365,7 +488,9 @@ function handleOpencodeSecondary(root, results) {
         results.push({ type: "opencode", filePath: ".agents/skills/kuma/SKILL.md", action: "skipped" });
         return;
       }
-      results.push({ type: "opencode", filePath: ".agents/skills/kuma/SKILL.md", action: "skipped" });
+      const newContent = existing.trimEnd() + "\n\n---\n\n" + content;
+      fs.writeFileSync(skillPath, newContent, "utf-8");
+      results.push({ type: "opencode", filePath: ".agents/skills/kuma/SKILL.md", action: "appended" });
     } else {
       if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
       fs.writeFileSync(skillPath, content, "utf-8");
@@ -453,7 +578,7 @@ function handleQwenSecondary(root, results) {
     });
   }
 }
-var AGENTS_MD_TYPES = ["codex", "qwen", "copilot"];
+var AGENTS_MD_TYPES = ["opencode", "codex", "qwen", "copilot"];
 function getAgentsMdHeader() {
   return [
     "# Kuma MCP - Combined Agent Instructions",
@@ -468,7 +593,7 @@ function getAgentsMdHeader() {
 }
 function getCombinedAgentsMd(selectedTypes) {
   const sections = [getAgentsMdHeader()];
-  const agentOrder = ["codex", "qwen", "copilot"];
+  const agentOrder = ["opencode", "codex", "qwen", "copilot"];
   for (const t of agentOrder) {
     if (selectedTypes.has(t)) {
       sections.push(TEMPLATES[t]());
@@ -707,6 +832,7 @@ function runInit(options) {
           fs.writeFileSync(fullPath, combinedContent, "utf-8");
           results.push({ type, filePath: relativePath, action: "created" });
         }
+        if (selectedSet.has("opencode")) handleOpencodeSecondary(root, results);
         if (selectedSet.has("codex")) handleCodexSecondary(root, results);
         if (selectedSet.has("qwen")) handleQwenSecondary(root, results);
         if (selectedSet.has("copilot")) handleCopilotSecondary(root, results);
@@ -751,8 +877,6 @@ function runInit(options) {
           handleCodewhaleSecondary(root, results);
         } else if (type === "aider") {
           handleAiderSecondary(root, results);
-        } else if (type === "opencode") {
-          handleOpencodeSecondary(root, results);
         }
       }
     } catch (err) {

package/dist/index.js

@@ -8,7 +8,7 @@ import {
   ALL_CONFIG_TYPES,
   formatInitResults,
   runInit
-} from "./chunk-J2CBDLXB.js";
+} from "./chunk-CRQ7WTPV.js";
 import {
   formatDecisionTemplate,
   getProactiveMemories,
@@ -2161,7 +2161,7 @@ async function handleVerify(params) {
 function registerAllTools(server) {
   server.tool(
     "kuma_context",
-    "**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.",
+    "**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).",
     {
       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"),
       scope: z.string().optional().describe("Research scope for research/progressive action"),
@@ -2190,7 +2190,7 @@ function registerAllTools(server) {
   );
   server.tool(
     "kuma_memory",
-    "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).",
+    "**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.",
     {
       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"),
       scope: z.string().optional().describe("Scope for research_save/search/todo/context/mine/federated"),
@@ -2257,7 +2257,7 @@ function registerAllTools(server) {
   );
   server.tool(
     "kuma_safety",
-    "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).",
+    "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).",
     {
       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"),
       // Verify params
@@ -2345,7 +2345,7 @@ Available config files:
   --cline      .clinerules/kuma.md          (Cline)
   --aider      CONVENTIONS.md + .aider.conf.yml  (Aider)
   --antigravity .agents/skills/kuma/SKILL.md    (Antigravity CLI)
-  --opencode    opencode.json                (OpenCode)
+  --opencode    AGENTS.md + .agents/skills/      (OpenCode)
   --codex       AGENTS.md + .codex/          (Codex CLI - OpenAI)
   --qwen        AGENTS.md + settings.json    (Qwen Code)
   --kiro        .kiro/steering/kuma.md       (Kiro)
@@ -2571,7 +2571,7 @@ async function main() {
   });
   (async () => {
     try {
-      const { generateInitMdContent } = await import("./init-LLP6JDFR.js");
+      const { generateInitMdContent } = await import("./init-OMETJFLM.js");
       const fs7 = await import("fs");
       const path7 = await import("path");
       const initMdPath = path7.resolve(process.cwd(), ".kuma/init.md");
@@ -2587,8 +2587,8 @@ async function main() {
   })();
   (async () => {
     try {
-      const { detectAgent, getSkillPath, getAgentLabel } = await import("./agentDetector-3OTNKKBS.js");
-      const { generateSkill, getSecondaryFiles } = await import("./skillGenerator-ILZFWO5O.js");
+      const { detectAgent, getSkillPath, getAgentLabel } = await import("./agentDetector-YOWQVJFR.js");
+      const { generateSkill, getSecondaryFiles } = await import("./skillGenerator-RGXRSBX2.js");
       const fs7 = await import("fs");
       const path7 = await import("path");
       const detection = detectAgent();
@@ -2759,7 +2759,7 @@ function interactiveSelect() {
       type: "antigravity",
       label: "7) Antigravity CLI (.agents/skills/)"
     },
-    { type: "opencode", label: "8) OpenCode (opencode.json)" },
+    { type: "opencode", label: "8) OpenCode (AGENTS.md + skills)" },
     {
       type: "codex",
       label: "9) Codex CLI - OpenAI (AGENTS.md + .codex/config.toml)"

package/dist/{init-LLP6JDFR.js → init-OMETJFLM.js}

@@ -4,7 +4,7 @@ import {
   formatInitResults,
   generateInitMdContent,
   runInit
-} from "./chunk-J2CBDLXB.js";
+} from "./chunk-CRQ7WTPV.js";
 import "./chunk-E2KFPEBT.js";
 export {
   ALL_CONFIG_TYPES,

package/dist/{skillGenerator-ILZFWO5O.js → skillGenerator-RGXRSBX2.js}

@@ -1,7 +1,7 @@
 // src/utils/skillGenerator.ts
 var BOOTSTRAP = [
-  "Kuma MCP tools are available. All behavioral rules are in `.kuma/init.md`.",
-  "**Before coding, call `kuma_init()`** to load project context and session memory.",
+  "Kuma MCP tools are available (kuma_context, kuma_memory, kuma_safety). All behavioral rules are in `.kuma/init.md`.",
+  '**Before coding, call `kuma_context({ action: "init" })`** to load project context and session memory.',
   "Project knowledge persists in `.kuma/memories/*.md` across sessions."
 ].join("\n");
 function generateSkill(type) {
@@ -141,17 +141,18 @@ function generateCodexConfigToml() {
   ].join("\n");
 }
 function generateOpencodeSkill() {
-  return JSON.stringify({
-    $schema: "https://opencode-ai.github.io/schema.json",
-    mcp: {
-      kuma: {
-        type: "local",
-        command: ["npx", "-y", "@plumpslabs/kuma"],
-        enabled: true
-      }
-    },
-    instructions: [".kuma/init.md"]
-  }, null, 2) + "\n";
+  return [
+    "---",
+    "name: kuma-mcp",
+    "description: Kuma MCP \u2014 safety toolkit for AI coding agents. Research, memory, and safety guard.",
+    "---",
+    "",
+    "Kuma MCP tools are installed. All behavioral rules are in `.kuma/init.md`.",
+    "**Before coding, call `kuma_init()` to load project context and session memory.**",
+    "Project knowledge persists in `.kuma/memories/*.md` across sessions.",
+    "",
+    "\u{1F4D6} Read `.kuma/init.md` for detailed rules."
+  ].join("\n");
 }
 function generateAiderSkill() {
   return [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plumpslabs/kuma",
-  "version": "2.3.10",
+  "version": "2.3.12",
   "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.",
   "type": "module",
   "main": "dist/index.js",