Graphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.
TypeScript antigravity-skillsbusiness-knowledgeclaude-codeclaude-skillscodebase-analysiscodexcodex-skillsdeveloper-tools-ai-agentgemini-cli-skillskarpathy-llm-wikiknowledge-baseknowledge-graphmemoryopencode-skillspi-agentunderstandcodevibe-coding
docs: add simplified multi-platform implementation plan
Lum11046346972ee510
diff --git a/docs/plans/2026-03-18-multi-platform-simple-implementation.md b/docs/plans/2026-03-18-multi-platform-simple-implementation.mdnew file mode 100644index 00000000..5ad3388b--- /dev/null+++ b/docs/plans/2026-03-18-multi-platform-simple-implementation.md@@ -0,0 +1,600 @@+# Multi-Platform Simple Implementation Plan++> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.++**Goal:** Make Understand-Anything skills work across Codex, OpenClaw, OpenCode, and Cursor — same files everywhere, no build step.++**Architecture:** Move 5 pipeline agents into `skills/understand/` as prompt templates. Create a reusable `knowledge-graph-guide` agent. Add per-platform INSTALL.md files for AI-driven installation.++**Tech Stack:** Markdown (SKILL.md, INSTALL.md), YAML frontmatter, Bash (symlink/clone commands in install docs).++**Design Doc:** `docs/plans/2026-03-18-multi-platform-simple-design.md`++---++### Task 1: Move pipeline agents into skills/understand/ as prompt templates++**Files:**+- Move: `understand-anything-plugin/agents/project-scanner.md` → `understand-anything-plugin/skills/understand/project-scanner-prompt.md`+- Move: `understand-anything-plugin/agents/file-analyzer.md` → `understand-anything-plugin/skills/understand/file-analyzer-prompt.md`+- Move: `understand-anything-plugin/agents/architecture-analyzer.md` → `understand-anything-plugin/skills/understand/architecture-analyzer-prompt.md`+- Move: `understand-anything-plugin/agents/tour-builder.md` → `understand-anything-plugin/skills/understand/tour-builder-prompt.md`+- Move: `understand-anything-plugin/agents/graph-reviewer.md` → `understand-anything-plugin/skills/understand/graph-reviewer-prompt.md`++**Step 1: Copy each agent file to the new location**++For each of the 5 files, copy from `agents/` to `skills/understand/` with the new name.++**Step 2: Strip agent frontmatter from the prompt templates**++Each prompt template file should remove the agent-specific YAML frontmatter (`name`, `description`, `tools`, `model`). Replace it with a simple Markdown header describing the template's purpose.++For example, `project-scanner-prompt.md` changes from:++```markdown+---+name: project-scanner+description: Scans a project directory...+tools: Bash, Glob, Grep, Read, Write+model: sonnet+---++You are a meticulous project inventory specialist...+```++To:++```markdown+# Project Scanner — Prompt Template++> Used by `/understand` Phase 1. Dispatch as a subagent with this full content as the prompt.++You are a meticulous project inventory specialist...+```++Apply this pattern to all 5 files:+- `project-scanner-prompt.md` — "Used by `/understand` Phase 1"+- `file-analyzer-prompt.md` — "Used by `/understand` Phase 2"+- `architecture-analyzer-prompt.md` — "Used by `/understand` Phase 4"+- `tour-builder-prompt.md` — "Used by `/understand` Phase 5"+- `graph-reviewer-prompt.md` — "Used by `/understand` Phase 6"++Keep the rest of the file content (the body instructions) exactly as-is.++**Step 3: Delete the original agent files**++```bash+cd understand-anything-plugin+rm agents/project-scanner.md agents/file-analyzer.md agents/architecture-analyzer.md agents/tour-builder.md agents/graph-reviewer.md+```++**Step 4: Verify the files exist in the new location**++```bash+ls understand-anything-plugin/skills/understand/+```++Expected: `SKILL.md`, plus the 5 `*-prompt.md` files.++**Step 5: Commit**++```bash+git add -A understand-anything-plugin/agents/ understand-anything-plugin/skills/understand/+git commit -m "refactor: move pipeline agents into skills/understand/ as prompt templates"+```++---++### Task 2: Update SKILL.md dispatch references++**Files:**+- Modify: `understand-anything-plugin/skills/understand/SKILL.md`++**Step 1: Read the current SKILL.md**++Read `understand-anything-plugin/skills/understand/SKILL.md` in full.++**Step 2: Update Phase 1 dispatch (line ~53)**++Change:+```+Dispatch the **project-scanner** agent with this prompt:+```++To:+```+Dispatch a subagent using the prompt template at `./project-scanner-prompt.md`. Read the template file, fill in the parameters below, and pass the full content as the subagent's prompt:+```++**Step 3: Update Phase 2 dispatch (line ~75)**++Change:+```+For each batch, dispatch a **file-analyzer** agent. Run up to **3 agents concurrently** using parallel dispatch. Each agent gets this prompt:+```++To:+```+For each batch, dispatch a subagent using the prompt template at `./file-analyzer-prompt.md`. Run up to **3 subagents concurrently** using parallel dispatch. Read the template once, then for each batch fill in the parameters below and pass the full content as the subagent's prompt:+```++**Step 4: Update Phase 4 dispatch (line ~119)**++Change:+```+Dispatch the **architecture-analyzer** agent with this prompt:+```++To:+```+Dispatch a subagent using the prompt template at `./architecture-analyzer-prompt.md`. Read the template file, fill in the parameters below, and pass the full content as the subagent's prompt:+```++**Step 5: Update Phase 5 dispatch (line ~144)**++Change:+```+Dispatch the **tour-builder** agent with this prompt:+```++To:+```+Dispatch a subagent using the prompt template at `./tour-builder-prompt.md`. Read the template file, fill in the parameters below, and pass the full content as the subagent's prompt:+```++**Step 6: Update Phase 6 dispatch (line ~195)**++Change:+```+2. Dispatch the **graph-reviewer** agent with this prompt:+```++To:+```+2. Dispatch a subagent using the prompt template at `./graph-reviewer-prompt.md`. Read the template file, fill in the parameters below, and pass the full content as the subagent's prompt:+```++**Step 7: Update Error Handling section (line ~251)**++Change:+```+- If any agent dispatch fails, retry **once** with the same prompt plus additional context about the failure.+```++To:+```+- If any subagent dispatch fails, retry **once** with the same prompt plus additional context about the failure.+```++**Step 8: Verify no references to "agent" dispatch remain (only "subagent")**++Search for "Dispatch the **" in the file — should find 0 results.++**Step 9: Commit**++```bash+git add understand-anything-plugin/skills/understand/SKILL.md+git commit -m "refactor: update SKILL.md to dispatch subagents via prompt templates"+```++---++### Task 3: Create knowledge-graph-guide agent++**Files:**+- Create: `understand-anything-plugin/agents/knowledge-graph-guide.md`++**Step 1: Write the agent definition**++Create `understand-anything-plugin/agents/knowledge-graph-guide.md`:++```markdown+---+name: knowledge-graph-guide+description: |+ Use this agent when users need help understanding, querying, or working+ with an Understand-Anything knowledge graph. Guides users through graph+ structure, node/edge relationships, layer architecture, tours, and+ dashboard usage.+model: inherit+---++You are an expert on Understand-Anything knowledge graphs. You help users navigate, query, and understand the `knowledge-graph.json` files produced by the `/understand` skill.++## What You Know++### Graph Location++The knowledge graph lives at `<project-root>/.understand-anything/knowledge-graph.json`. Metadata is at `<project-root>/.understand-anything/meta.json`.++### Graph Structure++The JSON has this top-level shape:++```json+{+ "version": "1.0.0",+ "project": { "name", "languages", "frameworks", "description", "analyzedAt", "gitCommitHash" },+ "nodes": [...],+ "edges": [...],+ "layers": [...],+ "tour": [...]+}+```++### Node Types (5)++| Type | ID Convention | Description |+|---|---|---|+| `file` | `file:<relative-path>` | Source file |+| `function` | `func:<relative-path>:<name>` | Function or method |+| `class` | `class:<relative-path>:<name>` | Class, interface, or type |+| `module` | `module:<name>` | Logical module or package |+| `concept` | `concept:<name>` | Abstract concept or pattern |++### Edge Types (18)++| Category | Types |+|---|---|+| Structural | `imports`, `exports`, `contains`, `inherits`, `implements` |+| Behavioral | `calls`, `subscribes`, `publishes`, `middleware` |+| Data flow | `reads_from`, `writes_to`, `transforms`, `validates` |+| Dependencies | `depends_on`, `tested_by`, `configures` |+| Semantic | `related`, `similar_to` |++### Layers++Layers represent architectural groupings (e.g., API, Service, Data, UI). Each layer has an `id`, `name`, `description`, and `nodeIds` array.++### Tours++Tours are guided walkthroughs with sequential steps. Each step has a `title`, `description`, `nodeId` (focus node), and optional `highlightEdges`.++## How to Help Users++1. **Finding things**: Help users locate nodes by file path, function name, or concept. Use `jq` or grep on the JSON.+2. **Understanding relationships**: Trace edges between nodes to explain dependencies, call chains, and data flow.+3. **Architecture overview**: Summarize layers and their contents.+4. **Onboarding**: Walk through the tour steps to explain the codebase.+5. **Dashboard**: Guide users to run `/understand-dashboard` to visualize the graph interactively.+6. **Querying**: Help users write `jq` commands to extract specific information from the graph JSON.+```++**Step 2: Commit**++```bash+git add understand-anything-plugin/agents/knowledge-graph-guide.md+git commit -m "feat: add knowledge-graph-guide agent for graph navigation and querying"+```++---++### Task 4: Create platform INSTALL.md files++**Files:**+- Create: `understand-anything-plugin/.codex/INSTALL.md`+- Create: `understand-anything-plugin/.opencode/INSTALL.md`+- Create: `understand-anything-plugin/.openclaw/INSTALL.md`+- Create: `understand-anything-plugin/.cursor/INSTALL.md`++**Step 1: Create .codex/INSTALL.md**++```markdown+# Installing Understand-Anything for Codex++## Prerequisites++- Git++## Installation++1. **Clone the repository:**+ ```bash+ git clone https://github.com/Lum1104/Understand-Anything.git ~/.codex/understand-anything+ ```++2. **Create the skills symlink:**+ ```bash+ mkdir -p ~/.agents/skills+ ln -s ~/.codex/understand-anything/understand-anything-plugin/skills ~/.agents/skills/understand-anything+ ```++ **Windows (PowerShell):**+ ```powershell+ New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"+ cmd /c mklink /J "$env:USERPROFILE\.agents\skills\understand-anything" "$env:USERPROFILE\.codex\understand-anything\understand-anything-plugin\skills"+ ```++3. **Restart Codex** to discover the skills.++## Verify++```bash+ls -la ~/.agents/skills/understand-anything+```++You should see a symlink pointing to the skills directory.++## Usage++Skills activate automatically when relevant. You can also invoke directly:+- "Analyze this codebase and build a knowledge graph"+- "Help me understand this project's architecture"++## Updating++```bash+cd ~/.codex/understand-anything && git pull+```++Skills update instantly through the symlink.++## Uninstalling++```bash+rm ~/.agents/skills/understand-anything+rm -rf ~/.codex/understand-anything+```+```++**Step 2: Create .opencode/INSTALL.md**++```markdown+# Installing Understand-Anything for OpenCode++## Prerequisites++- [OpenCode.ai](https://opencode.ai) installed++## Installation++Add understand-anything to the `plugin` array in your `opencode.json` (global or project-level):++```json+{+ "plugin": ["understand-anything@git+https://github.com/Lum1104/Understand-Anything.git"]+}+```++Restart OpenCode. The plugin auto-installs and registers all skills.++## Verify++Ask: "List available skills" — you should see understand, understand-chat, understand-dashboard, etc.++## Usage++```+use skill tool to load understand-anything/understand+```++Or just ask: "Analyze this codebase and build a knowledge graph"++## Updating++Restart OpenCode — the plugin re-installs from git automatically.++## Uninstalling++Remove the plugin line from `opencode.json` and restart.+```++**Step 3: Create .openclaw/INSTALL.md**++```markdown+# Installing Understand-Anything for OpenClaw++## Prerequisites++- Git++## Installation++1. **Clone the repository:**+ ```bash+ git clone https://github.com/Lum1104/Understand-Anything.git ~/.openclaw/understand-anything+ ```++2. **Create the skills symlink:**+ ```bash+ mkdir -p ~/.openclaw/skills+ ln -s ~/.openclaw/understand-anything/understand-anything-plugin/skills ~/.openclaw/skills/understand-anything+ ```++3. **Restart OpenClaw** to discover the skills.++## Usage++- `@understand` — Analyze the current codebase+- `@understand-chat` — Ask questions about the knowledge graph+- `@understand-dashboard` — Launch the interactive dashboard++## Updating++```bash+cd ~/.openclaw/understand-anything && git pull+```++## Uninstalling++```bash+rm ~/.openclaw/skills/understand-anything+rm -rf ~/.openclaw/understand-anything+```+```++**Step 4: Create .cursor/INSTALL.md**++```markdown+# Installing Understand-Anything for Cursor++## Prerequisites++- Git++## Installation++1. **Clone the repository:**+ ```bash+ git clone https://github.com/Lum1104/Understand-Anything.git ~/.cursor/understand-anything+ ```++2. **Create the plugin symlink:**+ ```bash+ mkdir -p ~/.cursor/plugins+ ln -s ~/.cursor/understand-anything/understand-anything-plugin ~/.cursor/plugins/understand-anything+ ```++3. **Restart Cursor** to discover the plugin.++## Usage++Skills activate automatically when relevant. Use `/understand` to analyze a codebase.++## Updating++```bash+cd ~/.cursor/understand-anything && git pull+```++## Uninstalling++```bash+rm ~/.cursor/plugins/understand-anything+rm -rf ~/.cursor/understand-anything+```+```++**Step 5: Commit**++```bash+git add understand-anything-plugin/.codex/ understand-anything-plugin/.opencode/ understand-anything-plugin/.openclaw/ understand-anything-plugin/.cursor/+git commit -m "feat: add per-platform INSTALL.md for AI-driven installation"+```++---++### Task 5: Update README with multi-platform section++**Files:**+- Modify: `README.md`++**Step 1: Read the current README**++Read `README.md` in full to find where the installation section is.++**Step 2: Add multi-platform section after the existing Quick Start**++Add a new section titled "Multi-Platform Installation" with this content:++```markdown+## 🌐 Multi-Platform Installation++Understand-Anything works across multiple AI coding platforms.++### Claude Code (Native)++```bash+/plugin marketplace add Lum1104/Understand-Anything+/plugin install understand-anything+```++### Codex++Tell Codex:+```+Fetch and follow instructions from https://raw.githubusercontent.com/Lum1104/Understand-Anything/refs/heads/main/understand-anything-plugin/.codex/INSTALL.md+```++### OpenCode++Add to your `opencode.json`:+```json+{+ "plugin": ["understand-anything@git+https://github.com/Lum1104/Understand-Anything.git"]+}+```++### OpenClaw++Tell OpenClaw:+```+Fetch and follow instructions from https://raw.githubusercontent.com/Lum1104/Understand-Anything/refs/heads/main/understand-anything-plugin/.openclaw/INSTALL.md+```++### Cursor++Tell Cursor:+```+Fetch and follow instructions from https://raw.githubusercontent.com/Lum1104/Understand-Anything/refs/heads/main/understand-anything-plugin/.cursor/INSTALL.md+```++### Platform Compatibility++| Platform | Status | Install Method |+|----------|--------|----------------|+| Claude Code | ✅ Native | Plugin marketplace |+| Codex | ✅ Supported | AI-driven install |+| OpenCode | ✅ Supported | Plugin config |+| OpenClaw | ✅ Supported | AI-driven install |+| Cursor | ✅ Supported | AI-driven install |+```++**Step 3: Commit**++```bash+git add README.md+git commit -m "docs: add multi-platform installation instructions to README"+```++---++### Task 6: Verify everything works++**Step 1: Check file structure**++```bash+ls understand-anything-plugin/skills/understand/+ls understand-anything-plugin/agents/+ls understand-anything-plugin/.codex/+ls understand-anything-plugin/.opencode/+ls understand-anything-plugin/.openclaw/+ls understand-anything-plugin/.cursor/+```++Expected:+- `skills/understand/`: SKILL.md + 5 *-prompt.md files+- `agents/`: only `knowledge-graph-guide.md`+- Each `.{platform}/`: INSTALL.md++**Step 2: Verify no old agent references remain in SKILL.md**++```bash+grep -n "Dispatch the \*\*" understand-anything-plugin/skills/understand/SKILL.md+```++Expected: 0 results.++**Step 3: Verify prompt templates don't have agent frontmatter**++```bash+head -3 understand-anything-plugin/skills/understand/project-scanner-prompt.md+```++Expected: Markdown header, NOT `---` YAML frontmatter.++**Step 4: Verify knowledge-graph-guide has model: inherit**++```bash+grep "model:" understand-anything-plugin/agents/knowledge-graph-guide.md+```++Expected: `model: inherit`++**Step 5: Run existing tests to check nothing broke**++```bash+cd understand-anything-plugin && pnpm test+```++Expected: All tests pass (tests don't reference agent files directly).