Visualize

---
description: Interactive Visual Board — generate a visual diagram of any concept, system, flow, or architecture and open it in the browser
---

# Interactive Visual Board

Generate a professional interactive diagram as a self-contained HTML file and open it in the browser. This skill visualizes anything — system architecture, data flows, auth sequences, pipelines, how a feature works, and more. Claude writes the HTML directly using **CSS flexbox layout** — no SVG pixel coordinates, no coordinate math, no overlaps.

## Phase 0: Load RAG Context (MANDATORY FIRST ACTION)

Call `POST http://127.0.0.1:8612/context` with:
```json
{"agent":"workflow-agent","task_description":"visual diagram: $ARGUMENTS — current project","project_path":"<cwd>"}

If it fails: stop and tell the user "RAG is not connected. Run /rag before using this skill."

0b — Verify project is indexed (required for codebase search to work):

Detect the project path:

1. Read $CLAUDEBOOST_HOME/state/project-workspaces.json — use the entry keyed by the current working directory to get the active workspace ID, then look up project_path in workspaces.json. Fall back to current working directory if the file doesn't exist or has no entry for this directory.

Call GET http://127.0.0.1:8612/status and check indexed_projects for the detected path.

• Indexed: note file/chunk counts and continue.
• Not indexed: run Skill(skill="index-project", args="<project_path>") immediately. Do not continue until indexing completes.
• RAG offline: stop and tell the user to run /rag first.

---

Phase 0c: Determine What to Visualize

Read $ARGUMENTS (the text the user typed after /visualize).

Derive three things you'll use throughout:

• TOPIC — a human-readable title for what's being visualized (e.g. "Auth Flow", "RAG Pipeline", "CI/CD Pipeline", "Architecture")
• SLUG — a lowercase, hyphenated filename stem (e.g. auth-flow, rag-pipeline, ci-cd-pipeline, architecture)
• MODE — one of: concept, self-map, project-map

Rules:

• $ARGUMENTS is empty or --project → project-map mode, TOPIC = "Architecture", SLUG = architecture
• $ARGUMENTS is --self → self-map mode, TOPIC = "How ClaudeBoost Works", SLUG = claudeboost
• $ARGUMENTS describes a concept, flow, or question (e.g. "auth flow", "how the RAG system works", "data pipeline") → concept mode; derive TOPIC and SLUG from the argument text

For concept mode: TOPIC = title-cased version of the argument, SLUG = lowercase hyphenated (strip "how", "the", "a" if they'd make the slug awkward). Example: how the RAG system works → TOPIC RAG System, SLUG rag-system.

Carry TOPIC, SLUG, and MODE forward. Use TOPIC in the HTML title and toolbar. Use SLUG for the output filename.

---

Phase 0d: Audience Calibration (concept mode only)

Only run when MODE = concept.

Before designing layers, decide who this diagram is for. Look at the TOPIC and any phrasing in $ARGUMENTS for signals:

Signal	Audience tier
"how does X work", "explain X", "what is X"	Novice — explain from scratch
"X flow", "X pipeline", "X architecture" (no "how")	Technical — assume familiarity, skip basics
"X deep dive", "X internals", "X implementation"	Expert — full detail, jargon fine

Default for concept mode: Novice-first.

Novice-first rules (apply unless TOPIC signals technical/expert audience):

• Open each layer label and card subtitle with plain language, not jargon. Add the technical term after: "Stores results (vector database)"
• Use one real-world analogy per card detail panel before any technical explanation. Example: "Think of this as a card catalog — it lets the system find relevant documents by meaning, not just keywords."
• Define acronyms on first use in the audio tour: "RAG — short for Retrieval-Augmented Generation — works like..."
• Put dense technical detail (config values, code paths, API contracts) in the collapsible <details> section of each detail panel, not in the main body
• The board should answer "what does this do for me?" before "how does it work?"

---

Step 1: Detect Mode

ls agents/ knowledge/ 2>/dev/null | head -5

• MODE is already set from Phase 0c — skip detection only if the user passed an explicit flag (--self, --project) or a concept argument.
• If no argument was given, use the directory check: both agents/ and knowledge/ exist → set MODE to self-map; otherwise project-map.

User can always override: --self forces self-map, --project forces project-map.

---

Step 2a: Self-Map — Get Data from Extractor

Run the extractor — it reads all agents, knowledge files, hooks, and commands in one shot:

"${CLAUDEBOOST_PYTHON}" "${CLAUDEBOOST_HOME}/scripts/visualize-extract.py" "${CLAUDEBOOST_HOME}" /tmp/cb-graph.json

Then Read /tmp/cb-graph.json with the Read tool. Use the layers, side_rails, and card fields (title, subtitle, detail, responsibilities, icon, accent) as your content. Do not run any other data-gathering commands — everything is already in the JSON.

---

Step 2b: Project-Map — Gather Data

1. Read top-level structure and key config:

   ls -la && cat package.json 2>/dev/null || cat pyproject.toml 2>/dev/null || cat Cargo.toml 2>/dev/null
   

2. If RAG project index exists: POST http://127.0.0.1:8612/search with {"scope":"codebase","mode":"graph","query":"services endpoints data models","project_path":"<cwd>","limit":8}
3. Identify 8–15 key components: entry points, services, data stores, external APIs, middleware. Cap at 15 — more components hurt clarity.

---

Step 2c: Ticket Context Enrichment (runs whenever a workspace ticket is available)

After gathering project/self-map data, check for active ticket context. This step turns a plain architecture map into a why are we here diagram.

Check for workspace files:

From t ```