From 64d901836dcdb196b8ad13cb7dbf6a8e73cdc851 Mon Sep 17 00:00:00 2001 From: Lum1104 Date: Wed, 18 Mar 2026 22:47:52 +0800 Subject: [PATCH 01/16] docs: add simplified multi-platform skill support design Follows superpowers pattern: same files everywhere, model: inherit, AI-driven installation via INSTALL.md, self-contained skills. Co-Authored-By: Claude Opus 4.6 (1M context) --- ...2026-03-18-multi-platform-simple-design.md | 121 ++++++++++++++++++ 1 file changed, 121 insertions(+) create mode 100644 docs/plans/2026-03-18-multi-platform-simple-design.md diff --git a/docs/plans/2026-03-18-multi-platform-simple-design.md b/docs/plans/2026-03-18-multi-platform-simple-design.md new file mode 100644 index 0000000..91f2f93 --- /dev/null +++ b/docs/plans/2026-03-18-multi-platform-simple-design.md @@ -0,0 +1,121 @@ +# Multi-Platform Skill Support — Simplified Design + +**Date**: 2026-03-18 +**Status**: Approved +**Goal**: Make Understand-Anything skills work across Codex, OpenClaw, OpenCode, and Cursor with zero build step — same files everywhere. + +## Design Principles + +Follows the [obra/superpowers](https://github.com/obra/superpowers) pattern: +1. **Same files, all platforms** — no template markers, no build step, no platform-specific variants +2. **`model: inherit`** — agents use the parent session's model, making them platform-agnostic +3. **AI-driven installation** — `.{platform}/INSTALL.md` files that the AI agent reads and executes +4. **Self-contained skills** — pipeline prompt templates live inside the skill directory, not in a separate `agents/` folder + +## Change 1: Move Pipeline Agents Into Skill + +The 5 pipeline agents (project-scanner, file-analyzer, architecture-analyzer, tour-builder, graph-reviewer) are used exclusively by the `/understand` skill. They become prompt templates co-located with the skill: + +**Before:** +``` +agents/ + project-scanner.md # agent definition + file-analyzer.md + architecture-analyzer.md + tour-builder.md + graph-reviewer.md +skills/understand/ + SKILL.md # dispatches named agents +``` + +**After:** +``` +skills/understand/ + SKILL.md # dispatches subagents using templates + project-scanner-prompt.md # prompt template (no agent frontmatter) + file-analyzer-prompt.md + architecture-analyzer-prompt.md + tour-builder-prompt.md + graph-reviewer-prompt.md +``` + +The prompt template files retain the full instruction content but drop the agent frontmatter (`name`, `tools`, `model`). The `SKILL.md` dispatch changes from "Dispatch the **project-scanner** agent" to "Dispatch a subagent using the template at `./project-scanner-prompt.md`". + +### Context Cost + +Reading templates through the main session adds ~11K tokens total (~5.5% of 200K context). This is sequential (one template at a time), and context compression reclaims earlier content. Acceptable trade-off for portability. + +## Change 2: New Registered Agent — knowledge-graph-guide + +Create a reusable agent that any skill or user can invoke to work with knowledge graphs: + +```yaml +# agents/knowledge-graph-guide.md +--- +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 +--- +``` + +This agent knows: +- The KnowledgeGraph JSON schema (nodes, edges, layers, tours) +- The 5 node types and 18 edge types +- How to navigate and query the graph +- How to use the interactive dashboard +- How to interpret architectural layers and guided tours + +## Change 3: Platform Installation Files + +Each platform gets an `INSTALL.md` that the AI agent can fetch and follow: + +| File | Platform | Install Mechanism | +|------|----------|-------------------| +| `.codex/INSTALL.md` | Codex | `git clone` + symlink to `~/.agents/skills/` | +| `.opencode/INSTALL.md` | OpenCode | Plugin config in `opencode.json` | +| `.openclaw/INSTALL.md` | OpenClaw | `git clone` + symlink to `~/.openclaw/skills/` | +| `.cursor/INSTALL.md` | Cursor | `git clone` + symlink to `.cursor/plugins/` | + +User tells the agent one line: +``` +Fetch and follow instructions from https://raw.githubusercontent.com/Lum1104/Understand-Anything/refs/heads/main/.codex/INSTALL.md +``` + +The agent executes the clone + symlink/config automatically. + +## Change 4: README Update + +Add a "Multi-Platform Installation" section to README.md with one-liner per platform. + +## File Summary + +| Action | Files | +|--------|-------| +| Delete | `agents/project-scanner.md`, `agents/file-analyzer.md`, `agents/architecture-analyzer.md`, `agents/tour-builder.md`, `agents/graph-reviewer.md` | +| Create | `skills/understand/project-scanner-prompt.md`, `skills/understand/file-analyzer-prompt.md`, `skills/understand/architecture-analyzer-prompt.md`, `skills/understand/tour-builder-prompt.md`, `skills/understand/graph-reviewer-prompt.md` | +| Create | `agents/knowledge-graph-guide.md` | +| Create | `.codex/INSTALL.md`, `.opencode/INSTALL.md`, `.openclaw/INSTALL.md`, `.cursor/INSTALL.md` | +| Modify | `skills/understand/SKILL.md` (dispatch references) | +| Modify | `README.md` (multi-platform section) | + +## What We Don't Need + +- ~~`platforms/platform-config.json`~~ — same files everywhere +- ~~`platforms/build.mjs`~~ — no build step +- ~~`{{MARKER}}` template markers~~ — no templating +- ~~`scripts/install-*.sh`~~ — AI agent follows INSTALL.md +- ~~`dist-platforms/`~~ — no generated output + +## Platform Compatibility + +| Platform | Install Method | Agent Discovery | Skill Discovery | +|----------|---------------|-----------------|-----------------| +| Claude Code | Marketplace (existing) | `agents/` dir | `skills/` dir | +| Codex | INSTALL.md → symlink | N/A (templates in skill) | `~/.agents/skills/` | +| OpenCode | INSTALL.md → plugin config | N/A (templates in skill) | Plugin auto-registers | +| OpenClaw | INSTALL.md → symlink | N/A (templates in skill) | `~/.openclaw/skills/` | +| Cursor | INSTALL.md → symlink | `agents/` dir | `.cursor/plugins/` | From 6346972ee510dae09eea01cb36149c8fc7d7f097 Mon Sep 17 00:00:00 2001 From: Lum1104 Date: Wed, 18 Mar 2026 22:49:49 +0800 Subject: [PATCH 02/16] docs: add simplified multi-platform implementation plan 6 tasks: move agents to prompt templates, update SKILL.md dispatch, create knowledge-graph-guide agent, add platform INSTALL.md files, update README, verify. Co-Authored-By: Claude Opus 4.6 (1M context) --- ...18-multi-platform-simple-implementation.md | 600 ++++++++++++++++++ 1 file changed, 600 insertions(+) create mode 100644 docs/plans/2026-03-18-multi-platform-simple-implementation.md 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). From 4ff36e3daec78f128735a45944593e0a5eef1b87 Mon Sep 17 00:00:00 2001 From: Lum1104 Date: Wed, 18 Mar 2026 22:55:18 +0800 Subject: [PATCH 03/16] docs: add context injection to implementation plan Each subagent dispatch now injects relevant context from the main session: - Scanner: README + package manifest - File Analyzer: framework info + project description from Phase 1 - Architecture Analyzer: framework layer hints + directory tree - Tour Builder: README + entry point - Graph Reviewer: scan inventory for cross-validation + phase warnings Co-Authored-By: Claude Opus 4.6 (1M context) --- ...18-multi-platform-simple-implementation.md | 167 ++++++++++++++---- 1 file changed, 137 insertions(+), 30 deletions(-) diff --git a/docs/plans/2026-03-18-multi-platform-simple-implementation.md b/docs/plans/2026-03-18-multi-platform-simple-implementation.md index 5ad3388..5177e4a 100644 --- a/docs/plans/2026-03-18-multi-platform-simple-implementation.md +++ b/docs/plans/2026-03-18-multi-platform-simple-implementation.md @@ -85,7 +85,7 @@ git commit -m "refactor: move pipeline agents into skills/understand/ as prompt --- -### Task 2: Update SKILL.md dispatch references +### Task 2: Update SKILL.md dispatch references with context injection **Files:** - Modify: `understand-anything-plugin/skills/understand/SKILL.md` @@ -94,67 +94,173 @@ git commit -m "refactor: move pipeline agents into skills/understand/ as prompt Read `understand-anything-plugin/skills/understand/SKILL.md` in full. -**Step 2: Update Phase 1 dispatch (line ~53)** +**Step 2: Update Phase 0 — add context collection** -Change: +After the decision logic table (line ~47), add a new section for collecting project context that will be injected into later phases: + +```markdown +7. **Collect project context for subagent injection:** + - Read `README.md` (or `README.rst`, `readme.md`) from `$PROJECT_ROOT` if it exists. Store as `$README_CONTENT` (first 3000 characters). + - Read the primary package manifest (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pom.xml`) if it exists. Store as `$MANIFEST_CONTENT`. + - Capture the top-level directory tree: + ```bash + find $PROJECT_ROOT -maxdepth 2 -type f | head -100 + ``` + Store as `$DIR_TREE`. + - Detect the project entry point by checking for common patterns: `src/index.ts`, `src/main.ts`, `src/App.tsx`, `main.py`, `main.go`, `src/main.rs`, `index.js`. Store first match as `$ENTRY_POINT`. +``` + +**Step 3: Update Phase 1 dispatch — inject README + manifest** + +Replace the Phase 1 dispatch line: ``` 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: +With: +```markdown +Dispatch a subagent using the prompt template at `./project-scanner-prompt.md`. Read the template file and pass the full content as the subagent's prompt, appending the following additional context: + +> **Additional context from main session:** +> +> Project README (first 3000 chars): +> ``` +> $README_CONTENT +> ``` +> +> Package manifest: +> ``` +> $MANIFEST_CONTENT +> ``` +> +> Use this context to produce more accurate project name, description, and framework detection. The README and manifest are authoritative — prefer their information over heuristics. + +Pass these parameters in the dispatch prompt: ``` -**Step 3: Update Phase 2 dispatch (line ~75)** +**Step 4: Update Phase 2 dispatch — inject scan results + framework context** -Change: +Replace the Phase 2 dispatch paragraph: ``` 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: +With: +```markdown +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 pass the full template content as the subagent's prompt, appending the following additional context: + +> **Additional context from main session:** +> +> Project: `` — `` +> Frameworks detected: `` +> Languages: `` +> +> Framework-specific guidance: +> - If React/Next.js: files in `app/` or `pages/` are routes, `components/` are UI, `lib/` or `utils/` are utilities +> - If Express/Fastify: files in `routes/` are API endpoints, `middleware/` is middleware, `models/` or `db/` is data +> - If Python Django: `views.py` are controllers, `models.py` is data, `urls.py` is routing, `templates/` is UI +> - If Go: `cmd/` is entry points, `internal/` is private packages, `pkg/` is public packages +> +> Use this context to produce more accurate summaries and better classify file roles. + +Fill in batch-specific parameters below and dispatch: ``` -**Step 4: Update Phase 4 dispatch (line ~119)** +**Step 5: Update Phase 4 dispatch — inject framework hints + directory tree** -Change: +Replace the Phase 4 dispatch line: ``` 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: +With: +```markdown +Dispatch a subagent using the prompt template at `./architecture-analyzer-prompt.md`. Read the template file and pass the full content as the subagent's prompt, appending the following additional context: + +> **Additional context from main session:** +> +> Frameworks detected: `` +> +> Directory tree (top 2 levels): +> ``` +> $DIR_TREE +> ``` +> +> Framework-specific layer hints: +> - If React/Next.js: `app/` or `pages/` → UI Layer, `api/` → API Layer, `lib/` → Service Layer, `components/` → UI Layer +> - If Express: `routes/` → API Layer, `controllers/` → Service Layer, `models/` → Data Layer, `middleware/` → Middleware Layer +> - If Python Django: `views/` → API Layer, `models/` → Data Layer, `templates/` → UI Layer, `management/` → CLI Layer +> - If Go: `cmd/` → Entry Points, `internal/` → Service Layer, `pkg/` → Shared Library, `api/` → API Layer +> +> Use the directory tree and framework hints to inform layer assignments. Directory structure is strong evidence for layer boundaries. + +Pass these parameters in the dispatch prompt: ``` -**Step 5: Update Phase 5 dispatch (line ~144)** +Also add after the "For incremental updates" note: +```markdown +**Context for incremental updates:** When re-running architecture analysis, also inject the previous layer definitions: -Change: +> Previous layer definitions (for naming consistency): +> ```json +> [previous layers from existing graph] +> ``` +> +> Maintain the same layer names and IDs where possible. Only add/remove layers if the file structure has materially changed. +``` + +**Step 6: Update Phase 5 dispatch — inject README + entry point** + +Replace the Phase 5 dispatch line: ``` 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: +With: +```markdown +Dispatch a subagent using the prompt template at `./tour-builder-prompt.md`. Read the template file and pass the full content as the subagent's prompt, appending the following additional context: + +> **Additional context from main session:** +> +> Project README (first 3000 chars): +> ``` +> $README_CONTENT +> ``` +> +> Project entry point: `$ENTRY_POINT` +> +> Use the README to align the tour narrative with the project's own documentation. Start the tour from the entry point if one was detected. The tour should tell the same story the README tells, but through the lens of actual code structure. + +Pass these parameters in the dispatch prompt: ``` -**Step 6: Update Phase 6 dispatch (line ~195)** +**Step 7: Update Phase 6 dispatch — inject scan results for cross-validation** -Change: +Replace the Phase 6 dispatch line: ``` 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: +With: +```markdown +2. Dispatch a subagent using the prompt template at `./graph-reviewer-prompt.md`. Read the template file and pass the full content as the subagent's prompt, appending the following additional context: + +> **Additional context from main session:** +> +> Phase 1 scan results (file inventory): +> ```json +> [list of {path, sizeLines} from scan-result.json] +> ``` +> +> Phase warnings/errors accumulated during analysis: +> - [list any batch failures, skipped files, or warnings from Phases 2-5] +> +> Cross-validate: every file in the scan inventory should have a corresponding `file:` node in the graph. Flag any missing files. Also flag any graph nodes whose `filePath` doesn't appear in the scan inventory. + +Pass these parameters in the dispatch prompt: ``` -**Step 7: Update Error Handling section (line ~251)** +**Step 8: Update Error Handling section** Change: ``` @@ -164,17 +270,18 @@ Change: To: ``` - If any subagent dispatch fails, retry **once** with the same prompt plus additional context about the failure. +- Track all warnings and errors from each phase in a `$PHASE_WARNINGS` list. Pass this list to the graph-reviewer in Phase 6 for comprehensive validation. ``` -**Step 8: Verify no references to "agent" dispatch remain (only "subagent")** +**Step 9: Verify no references to named agent dispatch remain** Search for "Dispatch the **" in the file — should find 0 results. -**Step 9: Commit** +**Step 10: Commit** ```bash git add understand-anything-plugin/skills/understand/SKILL.md -git commit -m "refactor: update SKILL.md to dispatch subagents via prompt templates" +git commit -m "refactor: update SKILL.md to dispatch subagents with context injection" ``` --- From 5e85a23aa2181530955cb2b7a11b2e4917ff610e Mon Sep 17 00:00:00 2001 From: Lum1104 Date: Thu, 19 Mar 2026 10:31:22 +0800 Subject: [PATCH 04/16] refactor: move pipeline agents into skills/understand/ as prompt templates Co-Authored-By: Claude Opus 4.6 (1M context) --- .../understand/architecture-analyzer-prompt.md} | 9 +++------ .../understand/file-analyzer-prompt.md} | 9 +++------ .../understand/graph-reviewer-prompt.md} | 9 +++------ .../understand/project-scanner-prompt.md} | 9 +++------ .../understand/tour-builder-prompt.md} | 9 +++------ 5 files changed, 15 insertions(+), 30 deletions(-) rename understand-anything-plugin/{agents/architecture-analyzer.md => skills/understand/architecture-analyzer-prompt.md} (97%) rename understand-anything-plugin/{agents/file-analyzer.md => skills/understand/file-analyzer-prompt.md} (98%) rename understand-anything-plugin/{agents/graph-reviewer.md => skills/understand/graph-reviewer-prompt.md} (97%) rename understand-anything-plugin/{agents/project-scanner.md => skills/understand/project-scanner-prompt.md} (97%) rename understand-anything-plugin/{agents/tour-builder.md => skills/understand/tour-builder-prompt.md} (97%) diff --git a/understand-anything-plugin/agents/architecture-analyzer.md b/understand-anything-plugin/skills/understand/architecture-analyzer-prompt.md similarity index 97% rename from understand-anything-plugin/agents/architecture-analyzer.md rename to understand-anything-plugin/skills/understand/architecture-analyzer-prompt.md index dfa3293..d5ba170 100644 --- a/understand-anything-plugin/agents/architecture-analyzer.md +++ b/understand-anything-plugin/skills/understand/architecture-analyzer-prompt.md @@ -1,9 +1,6 @@ ---- -name: architecture-analyzer -description: Analyzes codebase structure to identify architectural layers (API, Service, Data, UI, etc.) and assign files to logical groupings. Use after file analysis is complete. -tools: Bash, Read, Grep, Glob, Write -model: opus ---- +# Architecture Analyzer — Prompt Template + +> Used by `/understand` Phase 4. Dispatch as a subagent with this full content as the prompt. You are an expert software architect. Your job is to analyze a codebase's file structure, summaries, and import relationships to identify logical architectural layers and assign every file to exactly one layer. Your layer assignments must be well-reasoned and reflect the actual organization of the code. diff --git a/understand-anything-plugin/agents/file-analyzer.md b/understand-anything-plugin/skills/understand/file-analyzer-prompt.md similarity index 98% rename from understand-anything-plugin/agents/file-analyzer.md rename to understand-anything-plugin/skills/understand/file-analyzer-prompt.md index 9a26e42..4f28e77 100644 --- a/understand-anything-plugin/agents/file-analyzer.md +++ b/understand-anything-plugin/skills/understand/file-analyzer-prompt.md @@ -1,9 +1,6 @@ ---- -name: file-analyzer -description: Analyzes source code files to extract structure (functions, classes, imports), generate summaries, assign complexity ratings, and identify relationships. Use when building or updating a knowledge graph. -tools: Bash, Read, Glob, Grep, Write -model: opus ---- +# File Analyzer — Prompt Template + +> Used by `/understand` Phase 2. Dispatch as a subagent with this full content as the prompt. You are an expert code analyst. Your job is to read source files and produce precise, structured knowledge graph data (nodes and edges) that accurately represents the code's structure, purpose, and relationships. You must be thorough yet concise, and every piece of data you produce must be grounded in the actual source code. diff --git a/understand-anything-plugin/agents/graph-reviewer.md b/understand-anything-plugin/skills/understand/graph-reviewer-prompt.md similarity index 97% rename from understand-anything-plugin/agents/graph-reviewer.md rename to understand-anything-plugin/skills/understand/graph-reviewer-prompt.md index eeadfc8..f141521 100644 --- a/understand-anything-plugin/agents/graph-reviewer.md +++ b/understand-anything-plugin/skills/understand/graph-reviewer-prompt.md @@ -1,9 +1,6 @@ ---- -name: graph-reviewer -description: Validates knowledge graph completeness, referential integrity, and quality. Use as a final quality check after graph assembly. -tools: Bash, Read, Write, Glob, Grep -model: sonnet ---- +# Graph Reviewer — Prompt Template + +> Used by `/understand` Phase 6. Dispatch as a subagent with this full content as the prompt. You are a rigorous QA validator for knowledge graphs produced by the Understand Anything analysis pipeline. Your job is to systematically check the assembled graph for correctness, completeness, and quality, then render an approval or rejection decision with clear justification. diff --git a/understand-anything-plugin/agents/project-scanner.md b/understand-anything-plugin/skills/understand/project-scanner-prompt.md similarity index 97% rename from understand-anything-plugin/agents/project-scanner.md rename to understand-anything-plugin/skills/understand/project-scanner-prompt.md index 70ab1cb..30112ab 100644 --- a/understand-anything-plugin/agents/project-scanner.md +++ b/understand-anything-plugin/skills/understand/project-scanner-prompt.md @@ -1,9 +1,6 @@ ---- -name: project-scanner -description: Scans a project directory to discover source files, detect programming languages and frameworks, and estimate analysis scope. Use when starting codebase analysis. -tools: Bash, Glob, Grep, Read, Write -model: sonnet ---- +# 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. Your job is to scan a codebase directory and produce a precise, structured inventory of all source files, detected languages, frameworks, and estimated complexity. Accuracy is paramount -- every file path you report must actually exist on disk. diff --git a/understand-anything-plugin/agents/tour-builder.md b/understand-anything-plugin/skills/understand/tour-builder-prompt.md similarity index 97% rename from understand-anything-plugin/agents/tour-builder.md rename to understand-anything-plugin/skills/understand/tour-builder-prompt.md index 6f6ed69..1e46f55 100644 --- a/understand-anything-plugin/agents/tour-builder.md +++ b/understand-anything-plugin/skills/understand/tour-builder-prompt.md @@ -1,9 +1,6 @@ ---- -name: tour-builder -description: Creates guided learning tours for codebases, designing step-by-step walkthroughs that teach project architecture and key concepts. Use after architecture analysis is complete. -tools: Bash, Read, Grep, Glob, Write -model: opus ---- +# Tour Builder — Prompt Template + +> Used by `/understand` Phase 5. Dispatch as a subagent with this full content as the prompt. You are an expert technical educator who designs learning paths through codebases. Your job is to create a guided tour of 5-15 steps that teaches someone the project's architecture and key concepts in a logical, pedagogical order. Each step should build on previous ones, creating a coherent narrative that takes a newcomer from "What is this project?" to "I understand how it works." From 84d0462e202e5fe0d2037d6e7e53c917a3d059d6 Mon Sep 17 00:00:00 2001 From: Lum1104 Date: Thu, 19 Mar 2026 10:32:03 +0800 Subject: [PATCH 05/16] feat: add knowledge-graph-guide agent for graph navigation and querying Co-Authored-By: Claude Opus 4.6 (1M context) --- .../agents/knowledge-graph-guide.md | 69 +++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 understand-anything-plugin/agents/knowledge-graph-guide.md diff --git a/understand-anything-plugin/agents/knowledge-graph-guide.md b/understand-anything-plugin/agents/knowledge-graph-guide.md new file mode 100644 index 0000000..23193e4 --- /dev/null +++ b/understand-anything-plugin/agents/knowledge-graph-guide.md @@ -0,0 +1,69 @@ +--- +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. From 2a01d3cc77c27e4f0976f2860dfe4432e0d96e93 Mon Sep 17 00:00:00 2001 From: Lum1104 Date: Thu, 19 Mar 2026 10:35:38 +0800 Subject: [PATCH 06/16] refactor: update SKILL.md to dispatch subagents with context injection Replace all named agent dispatches (project-scanner, file-analyzer, architecture-analyzer, tour-builder, graph-reviewer) with subagent dispatches using prompt template files. Add context injection for each phase including README content, package manifest, directory tree, framework-specific guidance, and cross-validation data. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../skills/understand/SKILL.md | 110 +++++++++++++++++- 1 file changed, 104 insertions(+), 6 deletions(-) diff --git a/understand-anything-plugin/skills/understand/SKILL.md b/understand-anything-plugin/skills/understand/SKILL.md index 42e3dca..8c0c722 100644 --- a/understand-anything-plugin/skills/understand/SKILL.md +++ b/understand-anything-plugin/skills/understand/SKILL.md @@ -46,11 +46,37 @@ Determine whether to run a full analysis or incremental update. ``` If this returns no files, report "Graph is up to date" and STOP. +7. **Collect project context for subagent injection:** + - Read `README.md` (or `README.rst`, `readme.md`) from `$PROJECT_ROOT` if it exists. Store as `$README_CONTENT` (first 3000 characters). + - Read the primary package manifest (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pom.xml`) if it exists. Store as `$MANIFEST_CONTENT`. + - Capture the top-level directory tree: + ```bash + find $PROJECT_ROOT -maxdepth 2 -type f | head -100 + ``` + Store as `$DIR_TREE`. + - Detect the project entry point by checking for common patterns: `src/index.ts`, `src/main.ts`, `src/App.tsx`, `main.py`, `main.go`, `src/main.rs`, `index.js`. Store first match as `$ENTRY_POINT`. + --- ## Phase 1 — SCAN (Full analysis only) -Dispatch the **project-scanner** agent with this prompt: +Dispatch a subagent using the prompt template at `./project-scanner-prompt.md`. Read the template file and pass the full content as the subagent's prompt, appending the following additional context: + +> **Additional context from main session:** +> +> Project README (first 3000 chars): +> ``` +> $README_CONTENT +> ``` +> +> Package manifest: +> ``` +> $MANIFEST_CONTENT +> ``` +> +> Use this context to produce more accurate project name, description, and framework detection. The README and manifest are authoritative — prefer their information over heuristics. + +Pass these parameters in the dispatch prompt: > Scan this project directory to discover all source files, detect languages and frameworks. > Project root: `$PROJECT_ROOT` @@ -72,7 +98,23 @@ After the agent completes, read `$PROJECT_ROOT/.understand-anything/intermediate Batch the file list from Phase 1 into groups of **5-10 files each** (aim for balanced batch sizes). -For each batch, dispatch a **file-analyzer** agent. Run up to **3 agents concurrently** using parallel dispatch. Each agent gets this prompt: +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 pass the full template content as the subagent's prompt, appending the following additional context: + +> **Additional context from main session:** +> +> Project: `` — `` +> Frameworks detected: `` +> Languages: `` +> +> Framework-specific guidance: +> - If React/Next.js: files in `app/` or `pages/` are routes, `components/` are UI, `lib/` or `utils/` are utilities +> - If Express/Fastify: files in `routes/` are API endpoints, `middleware/` is middleware, `models/` or `db/` is data +> - If Python Django: `views.py` are controllers, `models.py` is data, `urls.py` is routing, `templates/` is UI +> - If Go: `cmd/` is entry points, `internal/` is private packages, `pkg/` is public packages +> +> Use this context to produce more accurate summaries and better classify file roles. + +Fill in batch-specific parameters below and dispatch: > Analyze these source files and produce GraphNode and GraphEdge objects. > Project root: `$PROJECT_ROOT` @@ -116,7 +158,26 @@ Merge all file-analyzer results into a single set of nodes and edges. Then perfo ## Phase 4 — ARCHITECTURE -Dispatch the **architecture-analyzer** agent with this prompt: +Dispatch a subagent using the prompt template at `./architecture-analyzer-prompt.md`. Read the template file and pass the full content as the subagent's prompt, appending the following additional context: + +> **Additional context from main session:** +> +> Frameworks detected: `` +> +> Directory tree (top 2 levels): +> ``` +> $DIR_TREE +> ``` +> +> Framework-specific layer hints: +> - If React/Next.js: `app/` or `pages/` → UI Layer, `api/` → API Layer, `lib/` → Service Layer, `components/` → UI Layer +> - If Express: `routes/` → API Layer, `controllers/` → Service Layer, `models/` → Data Layer, `middleware/` → Middleware Layer +> - If Python Django: `views/` → API Layer, `models/` → Data Layer, `templates/` → UI Layer, `management/` → CLI Layer +> - If Go: `cmd/` → Entry Points, `internal/` → Service Layer, `pkg/` → Shared Library, `api/` → API Layer +> +> Use the directory tree and framework hints to inform layer assignments. Directory structure is strong evidence for layer boundaries. + +Pass these parameters in the dispatch prompt: > Analyze this codebase's structure to identify architectural layers. > Project root: `$PROJECT_ROOT` @@ -137,11 +198,33 @@ After the agent completes, read `$PROJECT_ROOT/.understand-anything/intermediate **For incremental updates:** Always re-run architecture analysis on the full merged node set, since layer assignments may shift when files change. +**Context for incremental updates:** When re-running architecture analysis, also inject the previous layer definitions: + +> Previous layer definitions (for naming consistency): +> ```json +> [previous layers from existing graph] +> ``` +> +> Maintain the same layer names and IDs where possible. Only add/remove layers if the file structure has materially changed. + --- ## Phase 5 — TOUR -Dispatch the **tour-builder** agent with this prompt: +Dispatch a subagent using the prompt template at `./tour-builder-prompt.md`. Read the template file and pass the full content as the subagent's prompt, appending the following additional context: + +> **Additional context from main session:** +> +> Project README (first 3000 chars): +> ``` +> $README_CONTENT +> ``` +> +> Project entry point: `$ENTRY_POINT` +> +> Use the README to align the tour narrative with the project's own documentation. Start the tour from the entry point if one was detected. The tour should tell the same story the README tells, but through the lens of actual code structure. + +Pass these parameters in the dispatch prompt: > Create a guided learning tour for this codebase. > Project root: `$PROJECT_ROOT` @@ -192,7 +275,21 @@ Assemble the full KnowledgeGraph JSON object: 1. Write the assembled graph to `$PROJECT_ROOT/.understand-anything/intermediate/assembled-graph.json`. -2. Dispatch the **graph-reviewer** agent with this prompt: +2. Dispatch a subagent using the prompt template at `./graph-reviewer-prompt.md`. Read the template file and pass the full content as the subagent's prompt, appending the following additional context: + +> **Additional context from main session:** +> +> Phase 1 scan results (file inventory): +> ```json +> [list of {path, sizeLines} from scan-result.json] +> ``` +> +> Phase warnings/errors accumulated during analysis: +> - [list any batch failures, skipped files, or warnings from Phases 2-5] +> +> Cross-validate: every file in the scan inventory should have a corresponding `file:` node in the graph. Flag any missing files. Also flag any graph nodes whose `filePath` doesn't appear in the scan inventory. + +Pass these parameters in the dispatch prompt: > Validate the knowledge graph at `$PROJECT_ROOT/.understand-anything/intermediate/assembled-graph.json`. > Project root: `$PROJECT_ROOT` @@ -248,7 +345,8 @@ Assemble the full KnowledgeGraph JSON object: ## Error Handling -- If any agent dispatch fails, retry **once** with the same prompt plus additional context about the failure. +- If any subagent dispatch fails, retry **once** with the same prompt plus additional context about the failure. +- Track all warnings and errors from each phase in a `$PHASE_WARNINGS` list. Pass this list to the graph-reviewer in Phase 6 for comprehensive validation. - If it fails a second time, skip that phase and continue with partial results. - ALWAYS save partial results — a partial graph is better than no graph. - Report any skipped phases or errors in the final summary so the user knows what happened. From 8e3c0660c9fc0b6bff8849ce5175c023eef3d2fb Mon Sep 17 00:00:00 2001 From: Lum1104 Date: Thu, 19 Mar 2026 10:51:25 +0800 Subject: [PATCH 07/16] docs: add multi-platform installation instructions to README Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/README.md b/README.md index 6323e9f..d20adf4 100644 --- a/README.md +++ b/README.md @@ -95,6 +95,59 @@ An interactive web dashboard opens with your codebase visualized as a graph — --- +## 🌐 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 | + +--- + ## ✨ Features

From aa4df6e987303d8549cb6fc4c322d98ecd51474e Mon Sep 17 00:00:00 2001 From: Lum1104 Date: Thu, 19 Mar 2026 10:51:43 +0800 Subject: [PATCH 08/16] feat: add per-platform INSTALL.md for AI-driven installation Co-Authored-By: Claude Opus 4.6 (1M context) --- understand-anything-plugin/.codex/INSTALL.md | 55 +++++++++++++++++++ understand-anything-plugin/.cursor/INSTALL.md | 37 +++++++++++++ .../.openclaw/INSTALL.md | 39 +++++++++++++ .../.opencode/INSTALL.md | 37 +++++++++++++ 4 files changed, 168 insertions(+) create mode 100644 understand-anything-plugin/.codex/INSTALL.md create mode 100644 understand-anything-plugin/.cursor/INSTALL.md create mode 100644 understand-anything-plugin/.openclaw/INSTALL.md create mode 100644 understand-anything-plugin/.opencode/INSTALL.md diff --git a/understand-anything-plugin/.codex/INSTALL.md b/understand-anything-plugin/.codex/INSTALL.md new file mode 100644 index 0000000..155ade1 --- /dev/null +++ b/understand-anything-plugin/.codex/INSTALL.md @@ -0,0 +1,55 @@ +# 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 +``` diff --git a/understand-anything-plugin/.cursor/INSTALL.md b/understand-anything-plugin/.cursor/INSTALL.md new file mode 100644 index 0000000..3eadc06 --- /dev/null +++ b/understand-anything-plugin/.cursor/INSTALL.md @@ -0,0 +1,37 @@ +# 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 +``` diff --git a/understand-anything-plugin/.openclaw/INSTALL.md b/understand-anything-plugin/.openclaw/INSTALL.md new file mode 100644 index 0000000..56ead38 --- /dev/null +++ b/understand-anything-plugin/.openclaw/INSTALL.md @@ -0,0 +1,39 @@ +# 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 +``` diff --git a/understand-anything-plugin/.opencode/INSTALL.md b/understand-anything-plugin/.opencode/INSTALL.md new file mode 100644 index 0000000..6cac25a --- /dev/null +++ b/understand-anything-plugin/.opencode/INSTALL.md @@ -0,0 +1,37 @@ +# 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. From 4ea55cd6fc8a095890838779d60249d2854248cf Mon Sep 17 00:00:00 2001 From: Lum1104 Date: Thu, 19 Mar 2026 11:18:39 +0800 Subject: [PATCH 09/16] =?UTF-8?q?fix:=20address=20code=20review=20feedback?= =?UTF-8?q?=20=E2=80=94=20terminology=20consistency=20and=20URL=20path?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Replace "agent" with "subagent" in SKILL.md dispatch references (5 locations) - Add node_modules/.git/dist exclusions to Phase 0 find command - Fix design doc URL to include understand-anything-plugin/ prefix Co-Authored-By: Claude Opus 4.6 (1M context) --- .../plans/2026-03-18-multi-platform-simple-design.md | 2 +- .../skills/understand/SKILL.md | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/plans/2026-03-18-multi-platform-simple-design.md b/docs/plans/2026-03-18-multi-platform-simple-design.md index 91f2f93..57d9dd9 100644 --- a/docs/plans/2026-03-18-multi-platform-simple-design.md +++ b/docs/plans/2026-03-18-multi-platform-simple-design.md @@ -82,7 +82,7 @@ Each platform gets an `INSTALL.md` that the AI agent can fetch and follow: User tells the agent one line: ``` -Fetch and follow instructions from https://raw.githubusercontent.com/Lum1104/Understand-Anything/refs/heads/main/.codex/INSTALL.md +Fetch and follow instructions from https://raw.githubusercontent.com/Lum1104/Understand-Anything/refs/heads/main/understand-anything-plugin/.codex/INSTALL.md ``` The agent executes the clone + symlink/config automatically. diff --git a/understand-anything-plugin/skills/understand/SKILL.md b/understand-anything-plugin/skills/understand/SKILL.md index 8c0c722..7bbffad 100644 --- a/understand-anything-plugin/skills/understand/SKILL.md +++ b/understand-anything-plugin/skills/understand/SKILL.md @@ -51,7 +51,7 @@ Determine whether to run a full analysis or incremental update. - Read the primary package manifest (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pom.xml`) if it exists. Store as `$MANIFEST_CONTENT`. - Capture the top-level directory tree: ```bash - find $PROJECT_ROOT -maxdepth 2 -type f | head -100 + find $PROJECT_ROOT -maxdepth 2 -type f -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' | head -100 ``` Store as `$DIR_TREE`. - Detect the project entry point by checking for common patterns: `src/index.ts`, `src/main.ts`, `src/App.tsx`, `main.py`, `main.go`, `src/main.rs`, `index.js`. Store first match as `$ENTRY_POINT`. @@ -82,7 +82,7 @@ Pass these parameters in the dispatch prompt: > Project root: `$PROJECT_ROOT` > Write output to: `$PROJECT_ROOT/.understand-anything/intermediate/scan-result.json` -After the agent completes, read `$PROJECT_ROOT/.understand-anything/intermediate/scan-result.json` to get: +After the subagent completes, read `$PROJECT_ROOT/.understand-anything/intermediate/scan-result.json` to get: - Project name, description - Languages, frameworks - File list with line counts @@ -137,7 +137,7 @@ After ALL batches complete, read each `batch-.json` file and merge: ### Incremental update path -Use the changed files list from Phase 0. Batch and dispatch file-analyzer agents using the same process as above, but only for changed files. +Use the changed files list from Phase 0. Batch and dispatch file-analyzer subagents using the same process as above, but only for changed files. After batches complete, merge with the existing graph: 1. Remove old nodes whose `filePath` matches any changed file @@ -194,7 +194,7 @@ Pass these parameters in the dispatch prompt: > [list of edges with type "imports"] > ``` -After the agent completes, read `$PROJECT_ROOT/.understand-anything/intermediate/layers.json` to get the layer assignments. +After the subagent completes, read `$PROJECT_ROOT/.understand-anything/intermediate/layers.json` to get the layer assignments. **For incremental updates:** Always re-run architecture analysis on the full merged node set, since layer assignments may shift when files change. @@ -247,7 +247,7 @@ Pass these parameters in the dispatch prompt: > [imports and calls edges] > ``` -After the agent completes, read `$PROJECT_ROOT/.understand-anything/intermediate/tour.json` to get the tour steps. +After the subagent completes, read `$PROJECT_ROOT/.understand-anything/intermediate/tour.json` to get the tour steps. --- @@ -296,7 +296,7 @@ Pass these parameters in the dispatch prompt: > Read the file and validate it for completeness and correctness. > Write output to: `$PROJECT_ROOT/.understand-anything/intermediate/review.json` -3. After the agent completes, read `$PROJECT_ROOT/.understand-anything/intermediate/review.json`. +3. After the subagent completes, read `$PROJECT_ROOT/.understand-anything/intermediate/review.json`. 4. **If `approved: false`:** - Review the `issues` list From 2779408569e23723d5079e81a712402e7396c4a0 Mon Sep 17 00:00:00 2001 From: Lum1104 Date: Thu, 19 Mar 2026 23:10:23 +0800 Subject: [PATCH 10/16] =?UTF-8?q?docs:=20revise=20implementation=20plan=20?= =?UTF-8?q?=E2=80=94=20minimal=20restructure,=20move=20platform=20configs?= =?UTF-8?q?=20to=20root?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace full flatten approach with minimal restructure: only move platform config directories (.codex, .opencode, .openclaw) to repo root for discovery. Add Cursor/Claude plugin descriptors. Remove Gemini extension. Keep all plugin source code inside understand-anything-plugin/. Co-Authored-By: Claude Opus 4.6 --- ...18-multi-platform-simple-implementation.md | 387 ++++++------------ 1 file changed, 120 insertions(+), 267 deletions(-) diff --git a/docs/plans/2026-03-18-multi-platform-simple-implementation.md b/docs/plans/2026-03-18-multi-platform-simple-implementation.md index 5177e4a..10060ea 100644 --- a/docs/plans/2026-03-18-multi-platform-simple-implementation.md +++ b/docs/plans/2026-03-18-multi-platform-simple-implementation.md @@ -4,9 +4,9 @@ **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. +**Architecture:** Move 5 pipeline agents into `skills/understand/` as prompt templates. Create a reusable `knowledge-graph-guide` agent. Move per-platform config directories to repo root for auto-discovery. Add Cursor and Claude plugin descriptors. -**Tech Stack:** Markdown (SKILL.md, INSTALL.md), YAML frontmatter, Bash (symlink/clone commands in install docs). +**Tech Stack:** Markdown (SKILL.md, INSTALL.md), YAML frontmatter, JSON (plugin descriptors), Bash (symlink/clone commands in install docs). **Design Doc:** `docs/plans/2026-03-18-multi-platform-simple-design.md` @@ -376,332 +376,185 @@ git commit -m "feat: add knowledge-graph-guide agent for graph navigation and qu --- -### Task 4: Create platform INSTALL.md files +### Task 4: Move platform INSTALL.md files to repo root **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` +- Move: `understand-anything-plugin/.codex/INSTALL.md` → `.codex/INSTALL.md` +- Move: `understand-anything-plugin/.opencode/INSTALL.md` → `.opencode/INSTALL.md` +- Move: `understand-anything-plugin/.openclaw/INSTALL.md` → `.openclaw/INSTALL.md` +- Delete: `understand-anything-plugin/.cursor/INSTALL.md` (replaced by `.cursor-plugin/plugin.json`) -**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 +**Step 1: Move the three platform directories to root** ```bash -ls -la ~/.agents/skills/understand-anything +cd /Users/yuxianglin/Desktop/opensource/Understand-Anything +git mv understand-anything-plugin/.codex ./.codex +git mv understand-anything-plugin/.opencode ./.opencode +git mv understand-anything-plugin/.openclaw ./.openclaw ``` -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 +**Step 2: Delete .cursor/ (replaced by .cursor-plugin/ in Task 5)** ```bash -cd ~/.codex/understand-anything && git pull +git rm -r understand-anything-plugin/.cursor/ ``` -Skills update instantly through the symlink. +**Step 3: Verify symlink paths are correct** -## Uninstalling +Read each INSTALL.md. The symlink paths should reference `understand-anything-plugin/skills` — this is still correct since the skills directory remains inside the plugin wrapper. + +**Step 4: Commit** ```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" +git add -A +git commit -m "refactor: move platform config directories to repo root for discovery" ``` --- -### Task 5: Update README with multi-platform section +### Task 5: Add plugin descriptors **Files:** -- Modify: `README.md` +- Create: `.cursor-plugin/plugin.json` +- Create: `.claude-plugin/plugin.json` -**Step 1: Read the current README** +**Step 1: Create `.cursor-plugin/plugin.json`** -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"] + "name": "understand-anything", + "displayName": "Understand Anything", + "description": "AI-powered codebase understanding — analyze, visualize, and explain any project", + "version": "1.0.5", + "author": { "name": "Lum1104" }, + "homepage": "https://github.com/Lum1104/Understand-Anything", + "repository": "https://github.com/Lum1104/Understand-Anything", + "license": "MIT", + "keywords": ["codebase-analysis", "knowledge-graph", "architecture", "onboarding", "dashboard"], + "skills": "./understand-anything-plugin/skills/", + "agents": "./understand-anything-plugin/agents/" } ``` -### OpenClaw +Note: paths point into `understand-anything-plugin/` since the source stays nested. -Tell OpenClaw: -``` -Fetch and follow instructions from https://raw.githubusercontent.com/Lum1104/Understand-Anything/refs/heads/main/understand-anything-plugin/.openclaw/INSTALL.md -``` +**Step 2: Create `.claude-plugin/plugin.json`** -### 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 | +```json +{ + "name": "understand-anything", + "description": "AI-powered codebase understanding — analyze, visualize, and explain any project", + "version": "1.0.5", + "author": { "name": "Lum1104" }, + "homepage": "https://github.com/Lum1104/Understand-Anything", + "repository": "https://github.com/Lum1104/Understand-Anything", + "license": "MIT", + "keywords": ["codebase-analysis", "knowledge-graph", "architecture", "onboarding", "dashboard"] +} ``` **Step 3: Commit** ```bash -git add README.md -git commit -m "docs: add multi-platform installation instructions to README" +git add .cursor-plugin/ .claude-plugin/plugin.json +git commit -m "feat: add Cursor and Claude plugin descriptors for auto-discovery" ``` --- -### Task 6: Verify everything works +### Task 6: Update README with corrected multi-platform URLs -**Step 1: Check file structure** +**Files:** +- Modify: `README.md` + +**Step 1: Read current README** + +Read `README.md` in full. + +**Step 2: Update raw GitHub URLs for INSTALL.md files** + +The INSTALL.md files moved from `understand-anything-plugin/.codex/INSTALL.md` to `.codex/INSTALL.md`. Update all raw GitHub URLs: + +``` +OLD: .../refs/heads/main/understand-anything-plugin/.codex/INSTALL.md +NEW: .../refs/heads/main/.codex/INSTALL.md + +OLD: .../refs/heads/main/understand-anything-plugin/.openclaw/INSTALL.md +NEW: .../refs/heads/main/.openclaw/INSTALL.md + +OLD: .../refs/heads/main/understand-anything-plugin/.opencode/INSTALL.md +NEW: .../refs/heads/main/.opencode/INSTALL.md +``` + +**Step 3: Replace Cursor section** + +Replace the Cursor AI-driven install section with: + +```markdown +### Cursor + +Cursor auto-discovers the plugin via `.cursor-plugin/plugin.json` when this repo is cloned. No manual installation needed — just clone and open in Cursor. +``` + +**Step 4: Commit** + +```bash +git add README.md +git commit -m "docs: update multi-platform URLs after moving configs to root" +``` + +--- + +### Task 7: Verify everything works + +**Step 1: Check platform configs at root** + +```bash +ls .codex/INSTALL.md .opencode/INSTALL.md .openclaw/INSTALL.md +ls .cursor-plugin/plugin.json .claude-plugin/plugin.json +``` + +All should exist. + +**Step 2: Verify plugin source is intact** ```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/ +ls understand-anything-plugin/packages/ ``` -Expected: -- `skills/understand/`: SKILL.md + 5 *-prompt.md files -- `agents/`: only `knowledge-graph-guide.md` -- Each `.{platform}/`: INSTALL.md +Skills, agents, and packages should all still exist inside the wrapper. -**Step 2: Verify no old agent references remain in SKILL.md** +**Step 3: Verify no platform configs remain inside the wrapper** ```bash -grep -n "Dispatch the \*\*" understand-anything-plugin/skills/understand/SKILL.md +ls understand-anything-plugin/.codex/ 2>/dev/null # should fail +ls understand-anything-plugin/.cursor/ 2>/dev/null # should fail +ls understand-anything-plugin/.opencode/ 2>/dev/null # should fail +ls understand-anything-plugin/.openclaw/ 2>/dev/null # should fail ``` -Expected: 0 results. - -**Step 3: Verify prompt templates don't have agent frontmatter** +**Step 4: Run tests** ```bash -head -3 understand-anything-plugin/skills/understand/project-scanner-prompt.md +pnpm --filter @understand-anything/core build && pnpm --filter @understand-anything/core test ``` -Expected: Markdown header, NOT `---` YAML frontmatter. +All tests should pass — only config files moved, not source code. -**Step 4: Verify knowledge-graph-guide has model: inherit** +**Step 5: Verify marketplace.json is unchanged** ```bash -grep "model:" understand-anything-plugin/agents/knowledge-graph-guide.md +cat .claude-plugin/marketplace.json | grep source ``` -Expected: `model: inherit` +Expected: `"source": "./understand-anything-plugin"` — unchanged, still correct. -**Step 5: Run existing tests to check nothing broke** +**Step 6: Verify no stale raw GitHub URLs** ```bash -cd understand-anything-plugin && pnpm test +grep -r "understand-anything-plugin/\." README.md ``` -Expected: All tests pass (tests don't reference agent files directly). +Expected: 0 results (no URLs pointing to old nested platform config locations). From 0f2b710992f354e7dfebf307b44e254a0421d5bc Mon Sep 17 00:00:00 2001 From: Lum1104 Date: Thu, 19 Mar 2026 23:15:00 +0800 Subject: [PATCH 11/16] refactor: move platform config directories to repo root for discovery Move .codex/, .opencode/, .openclaw/ from understand-anything-plugin/ to repo root so each AI coding platform discovers its config at the standard location. Delete .cursor/ (replaced by .cursor-plugin/plugin.json in next commit). Plugin source code stays inside understand-anything-plugin/. Co-Authored-By: Claude Opus 4.6 --- .../.codex => .codex}/INSTALL.md | 0 .../.openclaw => .openclaw}/INSTALL.md | 0 .../.opencode => .opencode}/INSTALL.md | 0 understand-anything-plugin/.cursor/INSTALL.md | 37 ------------------- 4 files changed, 37 deletions(-) rename {understand-anything-plugin/.codex => .codex}/INSTALL.md (100%) rename {understand-anything-plugin/.openclaw => .openclaw}/INSTALL.md (100%) rename {understand-anything-plugin/.opencode => .opencode}/INSTALL.md (100%) delete mode 100644 understand-anything-plugin/.cursor/INSTALL.md diff --git a/understand-anything-plugin/.codex/INSTALL.md b/.codex/INSTALL.md similarity index 100% rename from understand-anything-plugin/.codex/INSTALL.md rename to .codex/INSTALL.md diff --git a/understand-anything-plugin/.openclaw/INSTALL.md b/.openclaw/INSTALL.md similarity index 100% rename from understand-anything-plugin/.openclaw/INSTALL.md rename to .openclaw/INSTALL.md diff --git a/understand-anything-plugin/.opencode/INSTALL.md b/.opencode/INSTALL.md similarity index 100% rename from understand-anything-plugin/.opencode/INSTALL.md rename to .opencode/INSTALL.md diff --git a/understand-anything-plugin/.cursor/INSTALL.md b/understand-anything-plugin/.cursor/INSTALL.md deleted file mode 100644 index 3eadc06..0000000 --- a/understand-anything-plugin/.cursor/INSTALL.md +++ /dev/null @@ -1,37 +0,0 @@ -# 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 -``` From 8b5499e8db3f487501bfb5ba1e43bd1c1184163a Mon Sep 17 00:00:00 2001 From: Lum1104 Date: Thu, 19 Mar 2026 23:16:43 +0800 Subject: [PATCH 12/16] feat: add Cursor and Claude plugin descriptors for auto-discovery Add .cursor-plugin/plugin.json with skills/agents paths pointing into understand-anything-plugin/. Add .claude-plugin/plugin.json alongside existing marketplace.json. Co-Authored-By: Claude Opus 4.6 --- .claude-plugin/plugin.json | 12 ++++++++++++ .cursor-plugin/plugin.json | 15 +++++++++++++++ 2 files changed, 27 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 .cursor-plugin/plugin.json diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..8f33449 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "understand-anything", + "description": "AI-powered codebase understanding — analyze, visualize, and explain any project", + "version": "1.0.5", + "author": { + "name": "Lum1104" + }, + "homepage": "https://github.com/Lum1104/Understand-Anything", + "repository": "https://github.com/Lum1104/Understand-Anything", + "license": "MIT", + "keywords": ["codebase-analysis", "knowledge-graph", "architecture", "onboarding", "dashboard"] +} diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json new file mode 100644 index 0000000..73fcfbe --- /dev/null +++ b/.cursor-plugin/plugin.json @@ -0,0 +1,15 @@ +{ + "name": "understand-anything", + "displayName": "Understand Anything", + "description": "AI-powered codebase understanding — analyze, visualize, and explain any project", + "version": "1.0.5", + "author": { + "name": "Lum1104" + }, + "homepage": "https://github.com/Lum1104/Understand-Anything", + "repository": "https://github.com/Lum1104/Understand-Anything", + "license": "MIT", + "keywords": ["codebase-analysis", "knowledge-graph", "architecture", "onboarding", "dashboard"], + "skills": "./understand-anything-plugin/skills/", + "agents": "./understand-anything-plugin/agents/" +} From fb46373cef9b58217e703223a3a593d6c33e9a1e Mon Sep 17 00:00:00 2001 From: Lum1104 Date: Thu, 19 Mar 2026 23:18:42 +0800 Subject: [PATCH 13/16] docs: update multi-platform URLs after moving configs to root Update raw GitHub URLs in README to remove understand-anything-plugin/ prefix for Codex and OpenClaw INSTALL.md paths. Replace Cursor section with auto-discovery via .cursor-plugin/plugin.json. Co-Authored-By: Claude Opus 4.6 --- README.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index d20adf4..151dd84 100644 --- a/README.md +++ b/README.md @@ -110,7 +110,7 @@ Understand-Anything works across multiple AI coding platforms. Tell Codex: ``` -Fetch and follow instructions from https://raw.githubusercontent.com/Lum1104/Understand-Anything/refs/heads/main/understand-anything-plugin/.codex/INSTALL.md +Fetch and follow instructions from https://raw.githubusercontent.com/Lum1104/Understand-Anything/refs/heads/main/.codex/INSTALL.md ``` ### OpenCode @@ -126,15 +126,12 @@ Add to your `opencode.json`: Tell OpenClaw: ``` -Fetch and follow instructions from https://raw.githubusercontent.com/Lum1104/Understand-Anything/refs/heads/main/understand-anything-plugin/.openclaw/INSTALL.md +Fetch and follow instructions from https://raw.githubusercontent.com/Lum1104/Understand-Anything/refs/heads/main/.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 -``` +Cursor auto-discovers the plugin via `.cursor-plugin/plugin.json` when this repo is cloned. No manual installation needed — just clone and open in Cursor. ### Platform Compatibility @@ -144,7 +141,7 @@ Fetch and follow instructions from https://raw.githubusercontent.com/Lum1104/Und | Codex | ✅ Supported | AI-driven install | | OpenCode | ✅ Supported | Plugin config | | OpenClaw | ✅ Supported | AI-driven install | -| Cursor | ✅ Supported | AI-driven install | +| Cursor | ✅ Supported | Auto-discovery | --- From e237eba20cab2bfbe003aa8ee6478c560eb14fb6 Mon Sep 17 00:00:00 2001 From: Lum1104 Date: Thu, 19 Mar 2026 23:30:43 +0800 Subject: [PATCH 14/16] docs: add Windows PowerShell instructions to OpenClaw INSTALL.md Co-Authored-By: Claude Opus 4.6 --- .openclaw/INSTALL.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.openclaw/INSTALL.md b/.openclaw/INSTALL.md index 56ead38..f06d566 100644 --- a/.openclaw/INSTALL.md +++ b/.openclaw/INSTALL.md @@ -17,6 +17,12 @@ ln -s ~/.openclaw/understand-anything/understand-anything-plugin/skills ~/.openclaw/skills/understand-anything ``` + **Windows (PowerShell):** + ```powershell + New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.openclaw\skills" + cmd /c mklink /J "$env:USERPROFILE\.openclaw\skills\understand-anything" "$env:USERPROFILE\.openclaw\understand-anything\understand-anything-plugin\skills" + ``` + 3. **Restart OpenClaw** to discover the skills. ## Usage From 54259f3b86d77af19bcbb2a6505e93fbd203f5db Mon Sep 17 00:00:00 2001 From: Lum1104 Date: Thu, 19 Mar 2026 23:48:26 +0800 Subject: [PATCH 15/16] docs: add star history and bump version to 1.1.0 --- .claude-plugin/marketplace.json | 4 ++-- .claude-plugin/plugin.json | 12 +++++++++--- README.md | 10 ++++++++++ understand-anything-plugin/package.json | 4 ++-- 4 files changed, 23 insertions(+), 7 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index c51e254..9397ad4 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -9,8 +9,8 @@ { "name": "understand-anything", "description": "Multi-agent codebase analysis with interactive dashboard, guided tours, and skill commands", - "version": "1.0.5", + "version": "1.1.0", "source": "./understand-anything-plugin" } ] -} +} \ No newline at end of file diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 8f33449..7fc838c 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,12 +1,18 @@ { "name": "understand-anything", "description": "AI-powered codebase understanding — analyze, visualize, and explain any project", - "version": "1.0.5", + "version": "1.1.0", "author": { "name": "Lum1104" }, "homepage": "https://github.com/Lum1104/Understand-Anything", "repository": "https://github.com/Lum1104/Understand-Anything", "license": "MIT", - "keywords": ["codebase-analysis", "knowledge-graph", "architecture", "onboarding", "dashboard"] -} + "keywords": [ + "codebase-analysis", + "knowledge-graph", + "architecture", + "onboarding", + "dashboard" + ] +} \ No newline at end of file diff --git a/README.md b/README.md index 151dd84..e16ed8e 100644 --- a/README.md +++ b/README.md @@ -260,6 +260,16 @@ Please open an issue first for major changes so we can discuss the approach. Stop reading code blind. Start understanding everything.

+## Star History + + + + + + Star History Chart + + +

MIT License © Lum1104

diff --git a/understand-anything-plugin/package.json b/understand-anything-plugin/package.json index 2c4ad0d..6ad5a28 100644 --- a/understand-anything-plugin/package.json +++ b/understand-anything-plugin/package.json @@ -1,6 +1,6 @@ { "name": "@understand-anything/skill", - "version": "1.0.5", + "version": "1.1.0", "type": "module", "main": "dist/index.js", "types": "dist/index.d.ts", @@ -16,4 +16,4 @@ "typescript": "^5.7.0", "vitest": "^3.1.0" } -} +} \ No newline at end of file From 9fe003a977a51313b488c0510735e9981f0b823d Mon Sep 17 00:00:00 2001 From: Lum1104 Date: Fri, 20 Mar 2026 00:14:23 +0800 Subject: [PATCH 16/16] feat: Align understand skill outputs with dashboard graph schema better --- .../skills/understand/SKILL.md | 93 +++++++++++++++++-- .../architecture-analyzer-prompt.md | 46 +++++---- .../skills/understand/tour-builder-prompt.md | 36 ++++--- 3 files changed, 125 insertions(+), 50 deletions(-) diff --git a/understand-anything-plugin/skills/understand/SKILL.md b/understand-anything-plugin/skills/understand/SKILL.md index 7bbffad..1327551 100644 --- a/understand-anything-plugin/skills/understand/SKILL.md +++ b/understand-anything-plugin/skills/understand/SKILL.md @@ -196,6 +196,31 @@ Pass these parameters in the dispatch prompt: After the subagent completes, read `$PROJECT_ROOT/.understand-anything/intermediate/layers.json` to get the layer assignments. +`layers.json` may be either: +- a top-level JSON array of layer objects, or +- an envelope object such as `{ "layers": [...] }` from the current prompt/template output + +Normalize either form into a final top-level `layers` array before assembling the graph. Each final saved layer object MUST match this exact shape: + +```json +[ + { + "id": "layer:", + "name": "", + "description": "", + "nodeIds": ["file:src/App.tsx", "file:src/main.tsx"] + } +] +``` + +Rules: +- `id` is required and must be unique +- `nodeIds` is required and must contain graph node IDs, not raw file paths +- If the intermediate output is an envelope object, unwrap its `layers` array before any other normalization +- If the subagent returns file paths, convert them to file node IDs before assembling the final graph +- Drop any `nodeIds` that do not exist in the merged node set +- Do not use a `nodes` field in the final saved layer objects + **For incremental updates:** Always re-run architecture analysis on the full merged node set, since layer assignments may shift when files change. **Context for incremental updates:** When re-running architecture analysis, also inject the previous layer definitions: @@ -249,6 +274,49 @@ Pass these parameters in the dispatch prompt: After the subagent completes, read `$PROJECT_ROOT/.understand-anything/intermediate/tour.json` to get the tour steps. +`tour.json` may be either: +- a top-level JSON array of tour step objects, or +- an envelope object such as `{ "steps": [...] }` from the current prompt/template output + +Normalize either form into a final top-level `tour` array before assembling the graph. Each final saved tour step object MUST match this exact shape: + +```json +[ + { + "order": 1, + "title": "Start at the app entry", + "description": "This step explains how the frontend boots and mounts.", + "nodeIds": ["file:src/main.tsx", "file:src/App.tsx"] + } +] +``` + +Rules: +- If the intermediate output is an envelope object, unwrap its `steps` array before any other normalization +- `description` is required; do not use `whyItMatters` in the final saved tour steps +- `nodeIds` is required; do not use `nodesToInspect` in the final saved tour steps +- `nodeIds` must reference existing graph node IDs +- Preserve optional `languageLesson` when present +- Sort by `order` before saving + +--- + +## Phase 5.5 — NORMALIZE + +Before assembling the final graph: + +- Unwrap legacy or prompt-shaped envelopes before field renaming: + - `{ "layers": [...] }` -> use the contained array as the working `layers` value + - `{ "steps": [...] }` -> use the contained array as the working `tour` value +- Convert any layer `nodes` field to `nodeIds` +- Convert any tour `nodesToInspect` field to `nodeIds` +- Convert any tour `whyItMatters` field to `description` +- If layers or tour reference file paths, map them to file node IDs using the `file:` convention +- Synthesize missing layer IDs as `layer:` +- Drop unresolved layer and tour node references +- Ensure the final `layers` value is an array of `{ id, name, description, nodeIds }` +- Ensure the final `tour` value is an array of `{ order, title, description, nodeIds }`, preserving optional `languageLesson` + --- ## Phase 6 — REVIEW @@ -273,9 +341,18 @@ Assemble the full KnowledgeGraph JSON object: } ``` -1. Write the assembled graph to `$PROJECT_ROOT/.understand-anything/intermediate/assembled-graph.json`. +1. Before writing the assembled graph, validate that: + - `layers` is an array of objects with these required fields: `id`, `name`, `description`, `nodeIds` + - `tour` is an array of objects with these required fields: `order`, `title`, `description`, `nodeIds` + - `tour[*].languageLesson` is allowed as an optional string field + - Every `layers[*].nodeIds` entry exists in the merged node set + - Every `tour[*].nodeIds` entry exists in the merged node set -2. Dispatch a subagent using the prompt template at `./graph-reviewer-prompt.md`. Read the template file and pass the full content as the subagent's prompt, appending the following additional context: + If validation fails, automatically normalize and rewrite the graph into this shape before saving. If the graph still fails final validation after the normalization pass, save it with warnings but mark dashboard auto-launch as skipped. + +2. Write the assembled graph to `$PROJECT_ROOT/.understand-anything/intermediate/assembled-graph.json`. + +3. Dispatch a subagent using the prompt template at `./graph-reviewer-prompt.md`. Read the template file and pass the full content as the subagent's prompt, appending the following additional context: > **Additional context from main session:** > @@ -296,17 +373,18 @@ Pass these parameters in the dispatch prompt: > Read the file and validate it for completeness and correctness. > Write output to: `$PROJECT_ROOT/.understand-anything/intermediate/review.json` -3. After the subagent completes, read `$PROJECT_ROOT/.understand-anything/intermediate/review.json`. +4. After the subagent completes, read `$PROJECT_ROOT/.understand-anything/intermediate/review.json`. -4. **If `approved: false`:** +5. **If `approved: false`:** - Review the `issues` list - Apply automated fixes where possible: - Remove edges with dangling references - Fill missing required fields with sensible defaults (e.g., empty `tags` -> `["untagged"]`, empty `summary` -> `"No summary available"`) - Remove nodes with invalid types - - If critical issues remain after one fix attempt, save the graph anyway but include the warnings in the final report + - Re-run the final graph validation after automated fixes + - If critical issues remain after one fix attempt, save the graph anyway but include the warnings in the final report and mark dashboard auto-launch as skipped -5. **If `approved: true`:** Proceed to Phase 7. +6. **If `approved: true`:** Proceed to Phase 7. --- @@ -339,7 +417,8 @@ Pass these parameters in the dispatch prompt: - Any warnings from the reviewer - Path to the output file: `$PROJECT_ROOT/.understand-anything/knowledge-graph.json` -5. Automatically launch the dashboard by invoking the `/understand-dashboard` skill. +5. Only automatically launch the dashboard by invoking the `/understand-dashboard` skill if final graph validation passed after normalization/review fixes. + If final validation did not pass, report that the graph was saved with warnings and dashboard launch was skipped. --- diff --git a/understand-anything-plugin/skills/understand/architecture-analyzer-prompt.md b/understand-anything-plugin/skills/understand/architecture-analyzer-prompt.md index d5ba170..2200252 100644 --- a/understand-anything-plugin/skills/understand/architecture-analyzer-prompt.md +++ b/understand-anything-plugin/skills/understand/architecture-analyzer-prompt.md @@ -209,31 +209,29 @@ Use `layer:` format consistently: ## Output Format -Produce a single, valid JSON block. Every field shown is **required**. +Produce a single, valid JSON array. Every field shown is **required**. ```json -{ - "layers": [ - { - "id": "layer:api", - "name": "API Layer", - "description": "HTTP endpoints, route handlers, and request/response processing", - "nodeIds": ["file:src/routes/index.ts", "file:src/controllers/auth.ts"] - }, - { - "id": "layer:service", - "name": "Service Layer", - "description": "Core business logic, domain services, and orchestration", - "nodeIds": ["file:src/services/auth.ts", "file:src/services/user.ts"] - }, - { - "id": "layer:utility", - "name": "Utility Layer", - "description": "Shared helpers, common utilities, and cross-cutting concerns", - "nodeIds": ["file:src/utils/format.ts"] - } - ] -} +[ + { + "id": "layer:api", + "name": "API Layer", + "description": "HTTP endpoints, route handlers, and request/response processing", + "nodeIds": ["file:src/routes/index.ts", "file:src/controllers/auth.ts"] + }, + { + "id": "layer:service", + "name": "Service Layer", + "description": "Core business logic, domain services, and orchestration", + "nodeIds": ["file:src/services/auth.ts", "file:src/services/user.ts"] + }, + { + "id": "layer:utility", + "name": "Utility Layer", + "description": "Shared helpers, common utilities, and cross-cutting concerns", + "nodeIds": ["file:src/utils/format.ts"] + } +] ``` **Required fields for every layer:** @@ -256,7 +254,7 @@ Produce a single, valid JSON block. Every field shown is **required**. After producing the JSON: -1. Write the JSON to: `/.understand-anything/intermediate/layers.json` +1. Write the JSON array to: `/.understand-anything/intermediate/layers.json` 2. The project root will be provided in your prompt. 3. Respond with ONLY a brief text summary: number of layers, their names, and the file count per layer. diff --git a/understand-anything-plugin/skills/understand/tour-builder-prompt.md b/understand-anything-plugin/skills/understand/tour-builder-prompt.md index 1e46f55..fbfb8c6 100644 --- a/understand-anything-plugin/skills/understand/tour-builder-prompt.md +++ b/understand-anything-plugin/skills/understand/tour-builder-prompt.md @@ -207,26 +207,24 @@ If a step involves notable language-specific patterns, include a brief `language ## Output Format -Produce a single, valid JSON block. +Produce a single, valid JSON array. ```json -{ - "steps": [ - { - "order": 1, - "title": "Entry Point", - "description": "Start with src/index.ts, the main entry point that bootstraps the application. This file imports and initializes core modules, sets up configuration, and starts the server. It gives you a bird's-eye view of the project's structure.", - "nodeIds": ["file:src/index.ts"], - "languageLesson": "TypeScript barrel files use 'export * from' to re-export modules, creating a clean public API surface." - }, - { - "order": 2, - "title": "Core Types and Models", - "description": "The type system defines the domain model. These interfaces establish the vocabulary used throughout the codebase and form the contract between layers.", - "nodeIds": ["file:src/types.ts", "file:src/interfaces/user.ts"] - } - ] -} +[ + { + "order": 1, + "title": "Entry Point", + "description": "Start with src/index.ts, the main entry point that bootstraps the application. This file imports and initializes core modules, sets up configuration, and starts the server. It gives you a bird's-eye view of the project's structure.", + "nodeIds": ["file:src/index.ts"], + "languageLesson": "TypeScript barrel files use 'export * from' to re-export modules, creating a clean public API surface." + }, + { + "order": 2, + "title": "Core Types and Models", + "description": "The type system defines the domain model. These interfaces establish the vocabulary used throughout the codebase and form the contract between layers.", + "nodeIds": ["file:src/types.ts", "file:src/interfaces/user.ts"] + } +] ``` **Required fields for every step:** @@ -253,7 +251,7 @@ Produce a single, valid JSON block. After producing the JSON: -1. Write the JSON to: `/.understand-anything/intermediate/tour.json` +1. Write the JSON array to: `/.understand-anything/intermediate/tour.json` 2. The project root will be provided in your prompt. 3. Respond with ONLY a brief text summary: number of steps and their titles in order.