@plumpslabs/kuma 2.4.2 → 2.4.4

package/.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "plumpslabs-kuma",
+  "description": "Safety-first context & orchestration engine for AI coding agents.",
+  "owner": {
+    "name": "plumpslabs",
+    "url": "https://github.com/plumpslabs"
+  },
+  "plugins": [
+    {
+      "name": "kuma",
+      "description": "Safety-first context & orchestration engine for AI coding agents. Shadow memory, gotcha lifecycle, blast radius impact analysis, and test verification.",
+      "source": "./",
+      "category": "safety"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "kuma",
+  "version": "2.4.4",
+  "description": "Safety-first context & orchestration engine for AI coding agents. Shadow memory, gotcha lifecycle, blast radius impact analysis, and test verification.",
+  "author": {
+    "name": "plumpslabs",
+    "url": "https://github.com/plumpslabs"
+  },
+  "license": "MIT"
+}

package/INSTALL.md

@@ -0,0 +1,265 @@
+# 🐻 Kuma — Complete Installation & Provider Setup Guide
+
+> Universal guide to installing and configuring **Kuma MCP** for every major AI coding agent and IDE.
+
+---
+
+## ⚡ Quick Start (Universal)
+
+The fastest way to install Kuma in any repository:
+
+```bash
+# 1-Liner auto-detect installer (auto-configures rules, hooks, and MCP)
+curl -fsSL https://raw.githubusercontent.com/plumpslabs/kuma/main/install.sh | bash
+```
+
+Or via `npx` with zero installation:
+
+```bash
+# Auto-detects your IDE/agent and creates tailored rules & hooks
+npx @plumpslabs/kuma init
+
+# Or initialize for ALL supported providers at once
+npx @plumpslabs/kuma init --all
+```
+
+---
+
+## 🔌 Provider Setup Matrix
+
+| Provider / IDE | Install Method | Config Files Generated | MCP Integration |
+|---|---|---|---|
+| **Claude Code** | Marketplace / `kuma init` | `CLAUDE.md`, `.claude/settings.json` (hooks) | `.mcp.json` / `~/.claude.json` |
+| **Google Antigravity** | Plugin / `kuma init` | `.agents/rules/kuma.md`, `.agents/skills/`, `GEMINI.md` | `.agents/mcp_config.json` |
+| **Cursor** | `kuma init --cursor` | `.cursor/rules/kuma.mdc`, `.cursorrules` | `.cursor/mcp.json` |
+| **Windsurf** | `kuma init --windsurf` | `.windsurfrules`, `.windsurf/rules/kuma.md` | `~/.codeium/windsurf/mcp_config.json` |
+| **OpenCode** | `kuma init --opencode` | `AGENTS.md`, `.opencode/plugins/kuma.js` | `opencode.json` (array command) |
+| **GitHub Copilot** | `kuma init --copilot` | `.github/copilot-instructions.md`, `.github/skills/` | Extension settings |
+| **Zed** | `kuma init` | `AGENTS.md` | `settings.json` (`context_servers`) |
+| **Cline / Roo / Trae** | `kuma init --cline` | `.clinerules/kuma.md`, `.roo/rules/`, `.trae/rules/` | Cline MCP UI |
+| **Codex (OpenAI)** | `kuma init --codex` | `AGENTS.md`, `.codex/config.toml` | Codex MCP config |
+| **Aider** | `kuma init --aider` | `CONVENTIONS.md`, `.aider.conf.yml` | Native config |
+| **Qwen / Kiro** | `kuma init --qwen --kiro` | `AGENTS.md`, `.kiro/steering/kuma.md` | Local config |
+
+---
+
+## 🟠 1. Claude Code
+
+### Method A: Claude Code Marketplace (Recommended)
+Add the Kuma marketplace and install the plugin directly:
+
+```bash
+/plugin marketplace add plumpslabs/kuma
+/plugin install kuma@plumpslabs-kuma
+```
+
+### Method B: Via `kuma init`
+Run inside your project directory:
+```bash
+npx @plumpslabs/kuma init --claude
+```
+
+This creates:
+- `CLAUDE.md` — Project context and safety obedience guidelines.
+- `.claude/settings.json` — PreToolUse hooks (`kuma hook pre-edit` and `kuma hook pre-bash`) that auto-inject known gotchas before file modifications.
+
+### MCP Configuration
+Add to `.mcp.json` in your project root or `~/.claude.json` globally:
+
+```json
+{
+  "mcpServers": {
+    "kuma": {
+      "command": "npx",
+      "args": ["-y", "@plumpslabs/kuma"]
+    }
+  }
+}
+```
+
+---
+
+## 🟣 2. Google Antigravity (AGY) / Gemini CLI
+
+### Method A: Plugin Installation (System-Wide)
+Install Kuma directly into your Antigravity plugins directory:
+
+```bash
+# Clone to Antigravity global plugins
+git clone https://github.com/plumpslabs/kuma.git ~/.gemini/config/plugins/kuma
+```
+Or via AGY plugin command:
+```bash
+agy plugin add https://github.com/plumpslabs/kuma
+```
+
+Antigravity will automatically read `plugin.json`, mount the `kuma-mcp` skill, and launch Kuma via `mcp_config.json`.
+
+### Method B: Per-Project via `kuma init`
+```bash
+npx @plumpslabs/kuma init --antigravity
+```
+
+This creates:
+- `.agents/skills/kuma/SKILL.md` — Core workflow skill.
+- `.agents/rules/kuma.md` — Antigravity behavioral safety rules.
+- `GEMINI.md` — Root workspace instructions.
+- `.agents/mcp_config.json` — Preconfigured MCP server configuration.
+
+---
+
+## ⚡ 3. Cursor
+
+Run inside your project:
+```bash
+npx @plumpslabs/kuma init --cursor
+```
+
+### Files Created:
+- `.cursor/rules/kuma.mdc` — Modern Cursor rule with XML delimiters and gotcha query triggers.
+- `.cursorrules` — Fallback universal rule for all Cursor versions.
+
+### MCP Configuration:
+Create or edit `.cursor/mcp.json` in your workspace or global settings:
+```json
+{
+  "mcpServers": {
+    "kuma": {
+      "command": "npx",
+      "args": ["-y", "@plumpslabs/kuma"]
+    }
+  }
+}
+```
+
+---
+
+## 🌊 4. Windsurf
+
+Run:
+```bash
+npx @plumpslabs/kuma init --windsurf
+```
+
+### Files Created:
+- `.windsurfrules` — Cascade behavioral guidelines.
+- `.windsurf/rules/kuma.md` — Detailed safety and gotcha workflow instructions.
+
+### MCP Configuration:
+Add to `~/.codeium/windsurf/mcp_config.json`:
+```json
+{
+  "mcpServers": {
+    "kuma": {
+      "command": "npx",
+      "args": ["-y", "@plumpslabs/kuma"]
+    }
+  }
+}
+```
+
+---
+
+## 🔵 5. OpenCode
+
+Run:
+```bash
+npx @plumpslabs/kuma init --opencode
+```
+
+### Files Created:
+- `AGENTS.md` — Shared agent instructions.
+- `.opencode/plugins/kuma.js` — Native OpenCode plugin for pre-edit gotcha interception.
+- `.opencode/skills/kuma/SKILL.md` — OpenCode skill with `kuma_kuma_*` prefixed actions.
+
+### MCP Configuration:
+Add to `opencode.json` in your project root:
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "kuma": {
+      "type": "local",
+      "command": ["npx", "-y", "@plumpslabs/kuma"],
+      "enabled": true
+    }
+  }
+}
+```
+*(Note: OpenCode requires `command` to be an array containing the binary and its arguments together).*
+
+---
+
+## 🐙 6. GitHub Copilot Editor
+
+Run:
+```bash
+npx @plumpslabs/kuma init --copilot
+```
+
+### Files Created:
+- `.github/copilot-instructions.md` — Workspace instructions for Copilot Chat.
+- `.github/skills/kuma/SKILL.md` — Copilot skills definition.
+
+---
+
+## ⚡ 7. Zed
+
+Add to your Zed `settings.json`:
+```json
+{
+  "context_servers": {
+    "kuma": {
+      "command": "npx",
+      "args": ["-y", "@plumpslabs/kuma"]
+    }
+  }
+}
+```
+
+---
+
+## 🛡️ 8. Cline / Roo-Code / Trae
+
+Run:
+```bash
+npx @plumpslabs/kuma init --cline
+```
+
+### Files Created:
+- `.clinerules/kuma.md`
+- `.roo/rules/kuma.md`
+- `.trae/rules/kuma.md`
+
+Configure the MCP server via Cline's MCP Settings UI:
+- **Server Name:** `kuma`
+- **Command:** `npx`
+- **Args:** `["-y", "@plumpslabs/kuma"]`
+
+---
+
+## 🍵 Companion Mode: Kuma + Matcha
+
+Kuma works standalone, but if you use [Matcha](https://github.com/plumpslabs/matcha):
+- **Matcha** handles the cognitive planning gate, stack audits, and code review.
+- **Kuma** handles runtime safety, blast radius impact analysis, gotchas memory, and post-edit verification.
+
+Install both in 1 line:
+```bash
+curl -fsSL https://raw.githubusercontent.com/plumpslabs/matcha/main/install.sh | bash
+curl -fsSL https://raw.githubusercontent.com/plumpslabs/kuma/main/install.sh | bash
+```
+
+---
+
+## 📊 Kuma Studio Dashboard
+
+To launch the web dashboard:
+```bash
+npx @plumpslabs/kuma studio
+```
+Access at `http://localhost:3322` to view:
+- **Gotcha Shield** (filters, 1-click workaround copy)
+- **Domain Sequence Flows**
+- **Workspace & Blast Radius Simulator**
+- **Health & Efficiency Metrics**

package/README.md

@@ -31,55 +31,56 @@ Kuma is an MCP (Model Context Protocol) server that acts as a **pre-modification
 
 ## Quick Start
 
-```bash
-# Run with npx (zero setup)
-npx -y @plumpslabs/kuma
+### ⚡ Universal 1-Liner (Auto-detects your IDE/Agent)
 
-# Or install globally
-npm install -g @plumpslabs/kuma
-kuma
+```bash
+curl -fsSL https://raw.githubusercontent.com/plumpslabs/kuma/main/install.sh | bash
 ```
 
-Kuma auto-generates:
-- `.kuma/init.md` — Project-specific behavioral rules
-- `.kuma/kuma.db` — SQLite knowledge graph (WASM, zero native build)
-- `.skills/` — Skill files for common patterns
+### 🧩 Or Install as a Native Plugin
+
+* **Claude Code Marketplace:**
+  ```bash
+  /plugin marketplace add plumpslabs/kuma
+  /plugin install kuma@plumpslabs-kuma
+  ```
+* **Antigravity CLI (AGY):**
+  ```bash
+  agy plugin add https://github.com/plumpslabs/kuma
+  ```
+* **Via NPX (Zero Install):**
+  ```bash
+  npx @plumpslabs/kuma init --all
+  ```
+
+📖 See [INSTALL.md](INSTALL.md) for the complete provider matrix (Cursor, Windsurf, OpenCode, Copilot, Zed, Cline, Aider, etc.).
 
 ---
 
 ## Core Architecture: 3 Pipeline-Driven Tools
 
-Kuma provides **3 coarse-grained tools** with impactful actions. Removed gimmick actions (add_node, feature, heal, harvest, session_mine, todo, context, benchmark, domain_rules, layers, noise_policy, lock, override, policy, contract, portability, doctor, gitignore, clean, progressive, sync, visualize, researches) are no longer documented.
+Kuma exposes **3 coarse-grained tools** with **15 core actions** — the full agent surface. Anything else (impact, navigate, changes, digest, drift, resume, mine, session, delete_node, clear, goal_progress, check, audit, security, gc, ast, validate, gotcha_staleness) was **removed** — not hidden, gone — so the agent never has to choose from 30+ options and there is no dead surface to maintain.
 
 ### 🧠 `kuma_context` — Context & Research
 
 | Action | Purpose | Impact |
 |--------|---------|--------|
-| `init` | Lean project brief + restore session | 🔴 Required first |
+| `init` | Lean project brief + restore session + branch tracking | 🔴 Required first |
 | `research` | 5-step pipeline: cache → graph → scan → impact → decision | 🔴 Required before edits |
+| `map` | Monorepo package topology & workspace boundary mapping | 🔴 High |
+| `impact` | Blast radius analysis: affected consumers & risk scoring | 🔴 High |
 | `history` | Why is this file written this way (cross-session trace) | 🔴 High |
-| `flow` | Hash-verified derived flow cache (F13) | 🔴 High |
-| `impact` | Analyze change effects on related code | 🟡 Linear |
-| `navigate` | Trace code flow across files | 🟡 Linear |
-| `changes` | View change log for current session | 🟡 Linear |
-| `rollback` | Undo a specific change by ID | 🟡 Linear |
-| `digest` | Ultra-compact <500 token project briefing | 🟡 Linear |
-| `drift` | Detect memory staleness & code drift | 🟡 Linear |
-| `resume` | Load previous session context | 🟡 Linear |
+| `flow` | Read a recorded architecture flow | 🔴 High |
 
 ### 💾 `kuma_memory` — Decision & Knowledge
 
 | Action | Purpose | Impact |
 |--------|---------|--------|
-| `gotcha` | Record bugs/quirks IMMEDIATELY | 🔴 Exponential |
+| `gotcha` | Record bugs/quirks + lifecycle (`active` → `resolved` → `deprecated`) | 🔴 Exponential |
 | `arch_flow` | Record architecture flow (max 5 core files) | 🔴 Exponential |
 | `decision` | Record ADR-style decision with rationale | 🔴 Exponential |
 | `research_save` | Save research findings to cache | 🟡 Linear |
-| `mine` | Mine git history for hidden decisions | 🟡 Linear |
-| `session` | View session summary | 🟢 Skip |
-| `search` | Search knowledge graph | 🟡 Linear |
-| `delete_node` | Remove node/gotcha from graph + table | 🟡 Linear |
-| `goal_progress` | Track goal completion | 🟢 Skip |
+| `search` | Quick lookup of memory + knowledge graph | 🟡 Linear |
 
 ### 🛡️ `kuma_safety` — Safety & Verification
 
@@ -87,13 +88,8 @@ Kuma provides **3 coarse-grained tools** with impactful actions. Removed gimmick
 |--------|---------|--------|
 | `guard` | Detect anti-patterns, drift, runaway loops | 🔴 Required |
 | `verify` | Auto-run scoped tests after edits | 🔴 High |
-| `check` | Pre-execution safety check | 🟡 Linear |
-| `audit` | Query safety audit trail | 🟡 Linear |
-| `security` | Scan for leaked secrets/tokens | 🟡 Linear |
-| `gc` | Garbage collect stale data | 🟢 Skip |
-| `ast` / `validate` | AST-based code validation | 🟡 Linear |
-| `checkpoint` | Atomic snapshot before refactors | 🟡 Linear |
-| `rollback_label` | Restore from checkpoint | 🟡 Linear |
+| `checkpoint` | Labeled snapshot before risky work | 🟡 Linear |
+| `rollback_label` | Restore a labeled snapshot | 🟡 Linear |
 
 ---
 
@@ -103,11 +99,11 @@ Kuma exposes exactly **3 coarse-grained tools** — the agent picks an *action*,
 
 | Tool | Core Actions | Purpose |
 |------|--------------|---------|
-| `kuma_context` | `init`, `research`, `history` | Load project context, understand unfamiliar code |
-| `kuma_memory` | `gotcha`, `decision`, `arch_flow`, `research_save` | Persistent knowledge that saves future sessions |
-| `kuma_safety` | `guard`, `verify` | Pre-risk check, post-edit verification |
+| `kuma_context` | `init`, `research`, `history`, `flow`, `map`, `impact` | Load project context, understand unfamiliar code |
+| `kuma_memory` | `gotcha`, `decision`, `arch_flow`, `research_save`, `search` | Persistent knowledge that saves future sessions |
+| `kuma_safety` | `guard`, `verify`, `checkpoint`, `rollback_label` | Pre-risk check, post-edit verification, snapshot/restore |
 
-Everything else is an internal action for power users. The agent uses its **own native tools** for editing, searching, and execution — Kuma is memory & safety, not a code manager.
+Everything else is an internal action — not exposed to the agent. The agent uses its **own native tools** for editing, searching, and execution — Kuma is memory & safety, not a code manager.
 
 ### What Kuma Provides
 
@@ -122,15 +118,15 @@ Everything else is an internal action for power users. The agent uses its **own
 
 ## Kuma Studio
 
-Kuma Studio is a **web-based dashboard** for visualizing and managing your knowledge graph.
+Kuma Studio is a **streamlined, modular web dashboard** for visualizing your codebase intelligence, gotchas shield, and workspace topology without visual clutter.
 
 ### Features
 
-- **📊 Knowledge Graph** — Interactive node-edge visualization with physics simulation
-- **⚠️ Gotchas** — Known bugs and quirks with severity levels
-- **⚡ Efficiency** — Session metrics, time saved, verification pass rates
-- **🪄 Injections** — Shadow-memory metrics: injection count + time saved (24h)
-- **📈 Staleness** — Detection of stale nodes with missing file references
+- **🛡️ Gotcha Shield** — Filter gotchas by status (`active`, `verified`, `resolved`), severity, and copy workarounds in 1 click
+- **🔀 Domain Sequence Flows** — Linear architecture hops and execution sequences
+- **📦 Workspace & Blast Radius** — Monorepo package dependency matrix and real-time blast radius impact simulator
+- **⚡ Health & Efficiency** — Session metrics, estimated hours saved, verification pass rates, and injection statistics
+- **🕸️ Calm Knowledge Graph** — Clean node-link visualization with optional physics simulation and depth controls
 
 ### Usage
 
@@ -205,10 +201,10 @@ A typical Kuma-powered session follows this flow:
                    Record what was learned for future sessions
 
 6. VERIFY        → kuma_safety({ action: 'verify' })
-                   Auto-run scoped tests + AST validation
+                   Auto-run scoped tests + validation
 
-7. REVIEW        → kuma_context({ action: 'changes' })
-                   Review what was modified this session
+7. CHECKPOINT    → kuma_safety({ action: 'checkpoint', label: 'post-<feature>' })
+                   Snapshot once stable — restore with rollback_label if needed
 ```
 
 ---
@@ -224,9 +220,8 @@ Kuma stores all context locally in `.kuma/`:
 ├── memory.json      # Session state + metrics (auto)
 ├── auto-gotcha.json # Self-learning loop state (auto)
 ├── policy.yml       # OPTIONAL safety policy — only read if you create it
-├── memories/        # Memory layer markdown (decisions.md, arch_flow.md, ...)
+├── memories/        # Decision log markdown (decisions.md)
 ├── checkpoints/     # Atomic snapshots (label/ with kuma.db + files/)
-└── scratch/         # Temp debug artifacts (auto, ephemeral)
 ```
 
 > Hooks are registered in `.claude/settings.json` (PreToolUse) — not stored under `.kuma/`.
@@ -246,7 +241,7 @@ Kuma stores all context locally in `.kuma/`:
 | **Impact** | Agent doesn't know what's affected | Impact analysis traces dependencies |
 | **Coordination** | Multiple agents conflict | Per-agent session state + audit trail avoid collisions |
 | **Memory** | Agent repeats past mistakes | Decision memory + gotchas prevent loops |
-| **Reversibility** | Hard to undo changes | Checkpoint snapshots + selective undo |
+| **Reversibility** | Hard to undo changes | Checkpoint snapshots + rollback_label |
 | **Staleness** | Knowledge becomes outdated | Drift detection + gotcha staleness checks flag stale data |
 
 ---