mirror of
https://github.com/Egonex-AI/Understand-Anything.git
synced 2026-06-22 10:58:03 +08:00
Merge pull request #6 from Lum1104/feature/multi-platform-simple
feat: add multi-platform support for Understand-Anything
This commit is contained in:
Yuxiang Lin
@@ -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"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,18 @@
|
||||
{
|
||||
"name": "understand-anything",
|
||||
"description": "AI-powered codebase understanding — analyze, visualize, and explain any project",
|
||||
"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"
|
||||
]
|
||||
}
|
||||
@@ -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
|
||||
```
|
||||
@@ -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/"
|
||||
}
|
||||
@@ -0,0 +1,45 @@
|
||||
# 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
|
||||
```
|
||||
|
||||
**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
|
||||
|
||||
- `@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
|
||||
```
|
||||
@@ -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.
|
||||
@@ -95,6 +95,56 @@ 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/.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/.openclaw/INSTALL.md
|
||||
```
|
||||
|
||||
### 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.
|
||||
|
||||
### 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 | Auto-discovery |
|
||||
|
||||
---
|
||||
|
||||
## ✨ Features
|
||||
|
||||
<p align="center">
|
||||
@@ -210,6 +260,16 @@ Please open an issue first for major changes so we can discuss the approach.
|
||||
<strong>Stop reading code blind. Start understanding everything.</strong>
|
||||
</p>
|
||||
|
||||
## Star History
|
||||
|
||||
<a href="https://www.star-history.com/?repos=Lum1104%2FUnderstand-Anything&type=date&legend=top-left">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=Lum1104/Understand-Anything&type=date&theme=dark&legend=top-left" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/image?repos=Lum1104/Understand-Anything&type=date&legend=top-left" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/image?repos=Lum1104/Understand-Anything&type=date&legend=top-left" />
|
||||
</picture>
|
||||
</a>
|
||||
|
||||
<p align="center">
|
||||
MIT License © <a href="https://github.com/Lum1104">Lum1104</a>
|
||||
</p>
|
||||
|
||||
@@ -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/understand-anything-plugin/.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/` |
|
||||
@@ -0,0 +1,560 @@
|
||||
# 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. 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, JSON (plugin descriptors), 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 with context injection
|
||||
|
||||
**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 0 — add context collection**
|
||||
|
||||
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:
|
||||
```
|
||||
|
||||
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 4: Update Phase 2 dispatch — inject scan results + framework context**
|
||||
|
||||
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:
|
||||
```
|
||||
|
||||
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: `<projectName>` — `<projectDescription>`
|
||||
> Frameworks detected: `<frameworks from Phase 1>`
|
||||
> Languages: `<languages from Phase 1>`
|
||||
>
|
||||
> 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 5: Update Phase 4 dispatch — inject framework hints + directory tree**
|
||||
|
||||
Replace the Phase 4 dispatch line:
|
||||
```
|
||||
Dispatch the **architecture-analyzer** agent with this 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: `<frameworks from Phase 1>`
|
||||
>
|
||||
> 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:
|
||||
```
|
||||
|
||||
Also add after the "For incremental updates" note:
|
||||
```markdown
|
||||
**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.
|
||||
```
|
||||
|
||||
**Step 6: Update Phase 5 dispatch — inject README + entry point**
|
||||
|
||||
Replace the Phase 5 dispatch line:
|
||||
```
|
||||
Dispatch the **tour-builder** agent with this 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 7: Update Phase 6 dispatch — inject scan results for cross-validation**
|
||||
|
||||
Replace the Phase 6 dispatch line:
|
||||
```
|
||||
2. Dispatch the **graph-reviewer** agent with this 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 8: Update Error Handling section**
|
||||
|
||||
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.
|
||||
- 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 9: Verify no references to named agent dispatch remain**
|
||||
|
||||
Search for "Dispatch the **" in the file — should find 0 results.
|
||||
|
||||
**Step 10: Commit**
|
||||
|
||||
```bash
|
||||
git add understand-anything-plugin/skills/understand/SKILL.md
|
||||
git commit -m "refactor: update SKILL.md to dispatch subagents with context injection"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 3: Create knowledge-graph-guide agent
|
||||
|
||||
**Files:**
|
||||
- Create: `understand-anything-plugin/agents/knowledge-graph-guide.md`
|
||||
|
||||
**Step 1: Write the agent definition**
|
||||
|
||||
Create `understand-anything-plugin/agents/knowledge-graph-guide.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: knowledge-graph-guide
|
||||
description: |
|
||||
Use this agent when users need help understanding, querying, or working
|
||||
with an Understand-Anything knowledge graph. Guides users through graph
|
||||
structure, node/edge relationships, layer architecture, tours, and
|
||||
dashboard usage.
|
||||
model: inherit
|
||||
---
|
||||
|
||||
You are an expert on Understand-Anything knowledge graphs. You help users navigate, query, and understand the `knowledge-graph.json` files produced by the `/understand` skill.
|
||||
|
||||
## What You Know
|
||||
|
||||
### Graph Location
|
||||
|
||||
The knowledge graph lives at `<project-root>/.understand-anything/knowledge-graph.json`. Metadata is at `<project-root>/.understand-anything/meta.json`.
|
||||
|
||||
### Graph Structure
|
||||
|
||||
The JSON has this top-level shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0.0",
|
||||
"project": { "name", "languages", "frameworks", "description", "analyzedAt", "gitCommitHash" },
|
||||
"nodes": [...],
|
||||
"edges": [...],
|
||||
"layers": [...],
|
||||
"tour": [...]
|
||||
}
|
||||
```
|
||||
|
||||
### Node Types (5)
|
||||
|
||||
| Type | ID Convention | Description |
|
||||
|---|---|---|
|
||||
| `file` | `file:<relative-path>` | Source file |
|
||||
| `function` | `func:<relative-path>:<name>` | Function or method |
|
||||
| `class` | `class:<relative-path>:<name>` | Class, interface, or type |
|
||||
| `module` | `module:<name>` | Logical module or package |
|
||||
| `concept` | `concept:<name>` | Abstract concept or pattern |
|
||||
|
||||
### Edge Types (18)
|
||||
|
||||
| Category | Types |
|
||||
|---|---|
|
||||
| Structural | `imports`, `exports`, `contains`, `inherits`, `implements` |
|
||||
| Behavioral | `calls`, `subscribes`, `publishes`, `middleware` |
|
||||
| Data flow | `reads_from`, `writes_to`, `transforms`, `validates` |
|
||||
| Dependencies | `depends_on`, `tested_by`, `configures` |
|
||||
| Semantic | `related`, `similar_to` |
|
||||
|
||||
### Layers
|
||||
|
||||
Layers represent architectural groupings (e.g., API, Service, Data, UI). Each layer has an `id`, `name`, `description`, and `nodeIds` array.
|
||||
|
||||
### Tours
|
||||
|
||||
Tours are guided walkthroughs with sequential steps. Each step has a `title`, `description`, `nodeId` (focus node), and optional `highlightEdges`.
|
||||
|
||||
## How to Help Users
|
||||
|
||||
1. **Finding things**: Help users locate nodes by file path, function name, or concept. Use `jq` or grep on the JSON.
|
||||
2. **Understanding relationships**: Trace edges between nodes to explain dependencies, call chains, and data flow.
|
||||
3. **Architecture overview**: Summarize layers and their contents.
|
||||
4. **Onboarding**: Walk through the tour steps to explain the codebase.
|
||||
5. **Dashboard**: Guide users to run `/understand-dashboard` to visualize the graph interactively.
|
||||
6. **Querying**: Help users write `jq` commands to extract specific information from the graph JSON.
|
||||
```
|
||||
|
||||
**Step 2: Commit**
|
||||
|
||||
```bash
|
||||
git add understand-anything-plugin/agents/knowledge-graph-guide.md
|
||||
git commit -m "feat: add knowledge-graph-guide agent for graph navigation and querying"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 4: Move platform INSTALL.md files to repo root
|
||||
|
||||
**Files:**
|
||||
- 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: Move the three platform directories to root**
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
**Step 2: Delete .cursor/ (replaced by .cursor-plugin/ in Task 5)**
|
||||
|
||||
```bash
|
||||
git rm -r understand-anything-plugin/.cursor/
|
||||
```
|
||||
|
||||
**Step 3: Verify symlink paths are correct**
|
||||
|
||||
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
|
||||
git add -A
|
||||
git commit -m "refactor: move platform config directories to repo root for discovery"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 5: Add plugin descriptors
|
||||
|
||||
**Files:**
|
||||
- Create: `.cursor-plugin/plugin.json`
|
||||
- Create: `.claude-plugin/plugin.json`
|
||||
|
||||
**Step 1: Create `.cursor-plugin/plugin.json`**
|
||||
|
||||
```json
|
||||
{
|
||||
"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/"
|
||||
}
|
||||
```
|
||||
|
||||
Note: paths point into `understand-anything-plugin/` since the source stays nested.
|
||||
|
||||
**Step 2: Create `.claude-plugin/plugin.json`**
|
||||
|
||||
```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 .cursor-plugin/ .claude-plugin/plugin.json
|
||||
git commit -m "feat: add Cursor and Claude plugin descriptors for auto-discovery"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 6: Update README with corrected multi-platform URLs
|
||||
|
||||
**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/packages/
|
||||
```
|
||||
|
||||
Skills, agents, and packages should all still exist inside the wrapper.
|
||||
|
||||
**Step 3: Verify no platform configs remain inside the wrapper**
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
**Step 4: Run tests**
|
||||
|
||||
```bash
|
||||
pnpm --filter @understand-anything/core build && pnpm --filter @understand-anything/core test
|
||||
```
|
||||
|
||||
All tests should pass — only config files moved, not source code.
|
||||
|
||||
**Step 5: Verify marketplace.json is unchanged**
|
||||
|
||||
```bash
|
||||
cat .claude-plugin/marketplace.json | grep source
|
||||
```
|
||||
|
||||
Expected: `"source": "./understand-anything-plugin"` — unchanged, still correct.
|
||||
|
||||
**Step 6: Verify no stale raw GitHub URLs**
|
||||
|
||||
```bash
|
||||
grep -r "understand-anything-plugin/\." README.md
|
||||
```
|
||||
|
||||
Expected: 0 results (no URLs pointing to old nested platform config locations).
|
||||
@@ -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 `<project-root>/.understand-anything/knowledge-graph.json`. Metadata is at `<project-root>/.understand-anything/meta.json`.
|
||||
|
||||
### Graph Structure
|
||||
|
||||
The JSON has this top-level shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0.0",
|
||||
"project": { "name", "languages", "frameworks", "description", "analyzedAt", "gitCommitHash" },
|
||||
"nodes": [...],
|
||||
"edges": [...],
|
||||
"layers": [...],
|
||||
"tour": [...]
|
||||
}
|
||||
```
|
||||
|
||||
### Node Types (5)
|
||||
|
||||
| Type | ID Convention | Description |
|
||||
|---|---|---|
|
||||
| `file` | `file:<relative-path>` | Source file |
|
||||
| `function` | `func:<relative-path>:<name>` | Function or method |
|
||||
| `class` | `class:<relative-path>:<name>` | Class, interface, or type |
|
||||
| `module` | `module:<name>` | Logical module or package |
|
||||
| `concept` | `concept:<name>` | Abstract concept or pattern |
|
||||
|
||||
### Edge Types (18)
|
||||
|
||||
| Category | Types |
|
||||
|---|---|
|
||||
| Structural | `imports`, `exports`, `contains`, `inherits`, `implements` |
|
||||
| Behavioral | `calls`, `subscribes`, `publishes`, `middleware` |
|
||||
| Data flow | `reads_from`, `writes_to`, `transforms`, `validates` |
|
||||
| Dependencies | `depends_on`, `tested_by`, `configures` |
|
||||
| Semantic | `related`, `similar_to` |
|
||||
|
||||
### Layers
|
||||
|
||||
Layers represent architectural groupings (e.g., API, Service, Data, UI). Each layer has an `id`, `name`, `description`, and `nodeIds` array.
|
||||
|
||||
### Tours
|
||||
|
||||
Tours are guided walkthroughs with sequential steps. Each step has a `title`, `description`, `nodeId` (focus node), and optional `highlightEdges`.
|
||||
|
||||
## How to Help Users
|
||||
|
||||
1. **Finding things**: Help users locate nodes by file path, function name, or concept. Use `jq` or grep on the JSON.
|
||||
2. **Understanding relationships**: Trace edges between nodes to explain dependencies, call chains, and data flow.
|
||||
3. **Architecture overview**: Summarize layers and their contents.
|
||||
4. **Onboarding**: Walk through the tour steps to explain the codebase.
|
||||
5. **Dashboard**: Guide users to run `/understand-dashboard` to visualize the graph interactively.
|
||||
6. **Querying**: Help users write `jq` commands to extract specific information from the graph JSON.
|
||||
@@ -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"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -46,17 +46,43 @@ 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 -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`.
|
||||
|
||||
---
|
||||
|
||||
## 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`
|
||||
> 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
|
||||
@@ -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: `<projectName>` — `<projectDescription>`
|
||||
> Frameworks detected: `<frameworks from Phase 1>`
|
||||
> Languages: `<languages from Phase 1>`
|
||||
>
|
||||
> 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`
|
||||
@@ -95,7 +137,7 @@ After ALL batches complete, read each `batch-<N>.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
|
||||
@@ -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: `<frameworks from Phase 1>`
|
||||
>
|
||||
> 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`
|
||||
@@ -133,15 +194,62 @@ Dispatch the **architecture-analyzer** agent with this 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.
|
||||
|
||||
`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:<kebab-case-name>",
|
||||
"name": "<layer name>",
|
||||
"description": "<what belongs in this layer>",
|
||||
"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:
|
||||
|
||||
> 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`
|
||||
@@ -164,7 +272,50 @@ Dispatch the **tour-builder** agent with this 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.
|
||||
|
||||
`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:<relative-path>` convention
|
||||
- Synthesize missing layer IDs as `layer:<kebab-case-name>`
|
||||
- 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`
|
||||
|
||||
---
|
||||
|
||||
@@ -190,26 +341,50 @@ 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 the **graph-reviewer** agent with this prompt:
|
||||
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:**
|
||||
>
|
||||
> 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`
|
||||
> 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`.
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
@@ -242,13 +417,15 @@ Assemble the full KnowledgeGraph JSON object:
|
||||
- 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.
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
+25
-30
@@ -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.
|
||||
|
||||
@@ -212,31 +209,29 @@ Use `layer:<kebab-case>` 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:**
|
||||
@@ -259,7 +254,7 @@ Produce a single, valid JSON block. Every field shown is **required**.
|
||||
|
||||
After producing the JSON:
|
||||
|
||||
1. Write the JSON to: `<project-root>/.understand-anything/intermediate/layers.json`
|
||||
1. Write the JSON array to: `<project-root>/.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.
|
||||
|
||||
+3
-6
@@ -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.
|
||||
|
||||
+3
-6
@@ -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.
|
||||
|
||||
+3
-6
@@ -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.
|
||||
|
||||
+20
-25
@@ -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."
|
||||
|
||||
@@ -210,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:**
|
||||
@@ -256,7 +251,7 @@ Produce a single, valid JSON block.
|
||||
|
||||
After producing the JSON:
|
||||
|
||||
1. Write the JSON to: `<project-root>/.understand-anything/intermediate/tour.json`
|
||||
1. Write the JSON array to: `<project-root>/.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.
|
||||
|
||||
Reference in New Issue
Block a user