@plumpslabs/kuma 2.4.3 → 2.4.5

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,32 +31,44 @@ 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 exposes **3 coarse-grained tools** with **13 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 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` | Read a recorded architecture flow | 🔴 High |
 
@@ -64,7 +76,7 @@ Kuma exposes **3 coarse-grained tools** with **13 core actions** — the full ag
 
 | 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 |
@@ -87,7 +99,7 @@ Kuma exposes exactly **3 coarse-grained tools** — the agent picks an *action*,
 
 | Tool | Core Actions | Purpose |
 |------|--------------|---------|
-| `kuma_context` | `init`, `research`, `history`, `flow` | Load project context, understand unfamiliar code |
+| `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 |
 
@@ -106,15 +118,15 @@ Everything else is an internal action — not exposed to the agent. The agent us
 
 ## 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
 

package/agents/kuma-guardian.md

@@ -0,0 +1,37 @@
+---
+name: kuma-guardian
+description: Runtime safety guardian. Pre-flight check, architecture boundary audit, circular dependency detection, and anti-pattern prevention. Read-only.
+mode: subagent
+mainAgent: false
+subagent: true
+permission:
+  read: allow
+  grep: allow
+  glob: allow
+  list: allow
+  bash: deny
+  webfetch: deny
+  websearch: deny
+  task: deny
+  edit:
+    "*": deny
+disallowedTools: Write, Edit, Task
+---
+
+<agent_persona>
+You are the Kuma Safety Guardian. Your directive is pre-modification safety enforcement and architectural protection.
+You analyze proposed changes, detect anti-patterns, circular dependencies, and verify that the agent does not edit code blindly.
+</agent_persona>
+
+<strict_boundaries>
+- READ-ONLY: Never modify any source code files.
+- Inspect codebase via kuma_context, kuma_safety, grep, glob, and read tools.
+- If high risk or circular dependency is detected, raise explicit safety blocking recommendation.
+</strict_boundaries>
+
+<workflow>
+1. Run `kuma_safety({ action: "guard" })` to check session state and edit loops.
+2. Check file boundaries and package dependencies using `kuma_context({ action: "map" })`.
+3. If circular imports or boundary violations are found, report exact import chains.
+4. Render verdict: PASS or BLOCK.
+</workflow>

package/agents/kuma-researcher.md

@@ -0,0 +1,36 @@
+---
+name: kuma-researcher
+description: Codebase intelligence & blast radius researcher. Maps monorepo packages, traces dependency trees, inspects past decisions, and gathers gotchas before changes. Read-only.
+mode: subagent
+mainAgent: false
+subagent: true
+permission:
+  read: allow
+  grep: allow
+  glob: allow
+  list: allow
+  bash: deny
+  webfetch: deny
+  websearch: deny
+  task: deny
+  edit:
+    "*": deny
+disallowedTools: Write, Edit, Task
+---
+
+<agent_persona>
+You are the Kuma Codebase Researcher. You explore unfamiliar code, compute blast radius, discover domain flows, and extract historical gotchas so the main agent has 100% clarity before modifying code.
+</agent_persona>
+
+<strict_boundaries>
+- READ-ONLY: Never modify any source code files.
+- Focus strictly on research, dependency traversal, and impact scoring.
+</strict_boundaries>
+
+<workflow>
+1. Initialize context via `kuma_context({ action: "init" })`.
+2. Inspect area via `kuma_context({ action: "research", scope: "<target>" })`.
+3. Calculate blast radius via `kuma_context({ action: "impact", target: "<target>" })`.
+4. Check cross-session history via `kuma_context({ action: "history", target: "<file>" })`.
+5. Return structured report with affected files, consumers, and known gotchas.
+</workflow>

package/commands/kuma:checkpoint.md

@@ -0,0 +1,12 @@
+---
+description: "📸 Kuma Checkpoint — Create an atomic named snapshot before risky work"
+---
+# /kuma:checkpoint
+
+Take an atomic rollback snapshot of current files and knowledge graph.
+
+```javascript
+kuma_safety({ action: "checkpoint", label: "[pre-refactor-feature-x]" })
+```
+
+Creates `<label>/` snapshot with `kuma.db` + modified files.

package/commands/kuma:guard.md

@@ -0,0 +1,16 @@
+---
+description: "🛡️ Kuma Guard — Pre-flight safety check against anti-patterns, drift, and circular deps"
+---
+# /kuma:guard
+
+Verify safety boundaries before applying complex refactors or multi-file edits.
+
+```javascript
+kuma_safety({ action: "guard", guardGoal: "[what you are doing]" })
+```
+
+**What it checks:**
+- Missing pre-modification research
+- Architecture boundary violations & circular imports
+- Scope drift (editing files outside declared goal)
+- Runaway execution loops

package/commands/kuma:impact.md

@@ -0,0 +1,16 @@
+---
+description: "💥 Kuma Impact — Calculate blast radius, affected consumers, and safety risk score"
+---
+# /kuma:impact
+
+Evaluate blast radius before modifying high-leverage files or shared packages.
+
+```javascript
+kuma_context({ action: "impact", target: "[file or package path]" })
+```
+
+**What it returns:**
+- Direct and transitive consumers
+- Downstream affected packages in monorepos
+- Mapped test suites to run
+- Safety risk level (`low`, `medium`, `high`, `critical`)

package/commands/kuma:init.md

@@ -0,0 +1,16 @@
+---
+description: "🐻 Kuma Init — Initialize session context, lean brief (<500 tokens), and branch tracking"
+---
+# /kuma:init
+
+Initialize Kuma session context before writing any code.
+
+```javascript
+kuma_context({ action: "init", goal: "[current task goal]" })
+```
+
+**What it does:**
+- Restores cross-session shadow memory
+- Loads fresh gotchas for the active branch
+- Evaluates repository rules and path constraints
+- Informs about branch switches

package/commands/kuma:research.md

@@ -0,0 +1,17 @@
+---
+description: "🔬 Kuma Research — 5-step pre-edit research pipeline before editing unfamiliar code"
+---
+# /kuma:research
+
+Run research pipeline before editing code you haven't touched before.
+
+```javascript
+kuma_context({ action: "research", scope: "[module or feature area]" })
+```
+
+**Pipeline Stages:**
+1. Check research cache in `.kuma/kuma.db`
+2. Query knowledge graph for related nodes and edges
+3. Scan references and entry points
+4. Compute blast radius and test coverage
+5. Retrieve historical ADR decisions and gotchas

package/commands/kuma:rollback.md

@@ -0,0 +1,12 @@
+---
+description: "⏪ Kuma Rollback — Restore codebase from a labeled checkpoint snapshot"
+---
+# /kuma:rollback
+
+Restore codebase to the exact state captured in a previous checkpoint.
+
+```javascript
+kuma_safety({ action: "rollback_label", label: "[label-name]" })
+```
+
+If the label is not found, Kuma lists all available snapshots.

package/commands/kuma:studio.md

@@ -0,0 +1,17 @@
+---
+description: "📊 Kuma Studio — Web dashboard for gotchas, flows, workspace matrix, and metrics"
+---
+# /kuma:studio
+
+Launch or view Kuma Studio web dashboard.
+
+```bash
+npx @plumpslabs/kuma studio
+```
+
+Opens `http://localhost:3322` featuring:
+- **Gotcha Shield** (status filters & 1-click workaround copy)
+- **Domain Sequence Flows**
+- **Workspace & Blast Radius Simulator**
+- **Health & Efficiency Metrics**
+- **Calm Knowledge Graph** (physics toggle)

package/commands/kuma:verify.md

@@ -0,0 +1,15 @@
+---
+description: "🧪 Kuma Verify — Post-edit scoped test verification and validation"
+---
+# /kuma:verify
+
+Run scoped tests and verify that changes did not introduce regressions.
+
+```javascript
+kuma_safety({ action: "verify", scope: "[modified scope or file]" })
+```
+
+**What it does:**
+- Automatically identifies appropriate test runner (Jest, Vitest, Pytest, Go test, Cargo)
+- Executes tests restricted to the modified blast radius
+- Records pass/fail metrics in session memory