diff --git a/docs/plans/2026-03-18-multi-platform-simple-implementation.md b/docs/plans/2026-03-18-multi-platform-simple-implementation.md new file mode 100644 index 0000000..5ad3388 --- /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 `/.understand-anything/knowledge-graph.json`. Metadata is at `/.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:` | Source file | +| `function` | `func::` | Function or method | +| `class` | `class::` | Class, interface, or type | +| `module` | `module:` | Logical module or package | +| `concept` | `concept:` | 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).