arcade-analyze-skill

A Claude Code skill that recovers and visualizes the architecture of a software codebase using arcade-agent — the Python successor to USC's ARCADE workbench (Architecture Recovery, Change, And Decay Evaluator).

Point it at a Java / Kotlin / Python / C / C++ / TypeScript / JavaScript / Go project (local path or git URL) and it runs the full pipeline — ingest → parse → recover → detect smells → compute metrics → visualize — then opens an interactive HTML report with the component diagram, dependency graph, architectural smells, and quality metrics.

Demo

Two real runs, both with the default pkg algorithm, generated by examples/run_demo.sh. They show the skill across languages — and the contrast between a clean codebase and a tangled one.

Target	Language	Entities	Edges	Components	Smells	RCI	BasicMQ	Report
arcade-agent (self)	Python	200	115	5	3	0.85	0.79	HTML · live
arcade_core	Java	1078	3520	13	6	0.40	0.26	HTML · live

_{Figures are from the original June 2026 demo run against arcade-agent 0.1.0; re-run examples/run_demo.sh to refresh them. The last column was labelled TurboMQ before arcade-agent #26 — at the time the two metrics returned an identical number, and the normalized one is BasicMQ.}

Read the numbers: arcade-agent (Python) scores high on RCI/BasicMQ — cohesive, well-separated modules. arcade_core (Java) scores much lower and surfaces a 9-component dependency cycle plus a hub (Clustering) that 58% of components depend on — the classic signature of a large research codebase that grew organically.

Architecture diagram (arcade-agent, Python)

Recovered components and their dependencies. Note the cycle Default → Algorithms → Tools → Default that the skill flags as a smell:

graph TD
    Default["Default<br/>(21 entities)"]
    Algorithms["Algorithms<br/>(65 entities)"]
    Exporters["Exporters<br/>(15 entities)"]
    Parsers["Parsers<br/>(58 entities)"]
    Tools["Tools<br/>(41 entities)"]
    Algorithms --> Tools
    Default --> Algorithms
    Default --> Parsers
    Exporters --> Tools
    Tools --> Default
    Tools --> Parsers

Loading

The interactive HTML report renders this diagram, the full component/entity breakdown, every smell with its explanation, and all six metrics. View it live: https://lemduc.github.io/arcade-analyze-skill/

App-style visualizer demo

Try it live: https://lemduc.github.io/arcade-analyze-skill/arcade-visualizer-demo.html (no install needed — it's the committed examples/arcade-visualizer-demo.html, which you can also download and open locally without arcade-agent). It is a single-page workbench with sidebar views: pan/zoom architecture diagram with click-to-drill details, weighted dependencies + DSM, failure-point cards, a ranked Architect Recommendations roadmap (quick wins / planned / big bets), an animated hop-by-hop flow simulation with custom trace recording, a Knowledge view with balanced scores, principle signals, strengths/risks and per-component quality, and a feedback bar — plus a dark/light mode toggle (☀️/🌙 in the top bar; the choice persists across reloads). Regenerate it with:

python3 scripts/visualizer.py --from-model examples/visualizer-demo-model.json \
  -o examples/arcade-visualizer-demo.html --no-open

Reproduce it

ARCADE_AGENT_HOME=/path/to/arcade-agent \
ARCADE_CORE_HOME=/path/to/arcade_core \
  ./examples/run_demo.sh

(ARCADE_CORE_HOME is optional — clone arcade_core to include the Java run.)

What it does

• Recovers a component-level architecture via clustering (PKG, WCA, ACDC, ARC, LIMBO).
• Detects architectural smells: dependency cycles, concern overload, scattered functionality, link overload.
• Computes quality metrics: RCI and BasicMQ (both normalized to [0, 1]), TurboMQ (the unbounded Bunch-style sum of cluster factors), intra/inter-connectivity.
• Visualizes everything in a self-contained interactive HTML report (auto-opened), with optional Mermaid component diagrams.

Install

This skill is a thin wrapper over arcade-agent, so you need that installed first — the easy way is from PyPI (Python ≥ 3.12), and no environment variable is needed:

pip install arcade-agent

Alternatively, for development against a checkout: create its virtualenv (pip install -e ".[dev]") and tell the skill where it lives — the scripts check --arcade-home, then $ARCADE_AGENT_HOME, and a configured checkout wins over a pip install:

export ARCADE_AGENT_HOME=/path/to/arcade-agent

Then install the skill itself, either way:

A. As a Claude Code plugin (recommended). This repo is a plugin marketplace — inside Claude Code run:

/plugin marketplace add lemduc/arcade-analyze-skill
/plugin install arcade-analyze@arcade-tools

Updates ship with the repo: /plugin marketplace update arcade-tools pulls the latest version.

B. Manually, as a bare skill. Symlink the repo into your skills directory (the symlink name becomes the skill name arcade-analyze):

git clone https://github.com/lemduc/arcade-analyze-skill.git
ln -sfn "$(pwd)/arcade-analyze-skill" ~/.claude/skills/arcade-analyze

Use -sfn, not plain -s. If a link is already there, ln -s creates a nested link inside the old target rather than repointing it — so a stale link survives silently and Claude Code never loads the skill. Re-run the -sfn form whenever you move the checkout, and verify with:

ls ~/.claude/skills/arcade-analyze/SKILL.md

If that errors, the link is dangling and the skill will not appear.

Usage

In Claude Code, just ask in natural language — the skill triggers on requests like "analyze the architecture of /path/to/repo", "compare PKG vs WCA on this project", "what changed architecturally since v1.0?", or "explain the Clustering component". The skill picks the right workflow below.

Each workflow is a script; run it with any interpreter where arcade-agent is pip-installed (plain python3 after pip install arcade-agent), or with the checkout's venv interpreter as shown below. <source> is a local directory or a git URL (cloned for you).

1. Analyze — one codebase → static HTML report (the default)

"$ARCADE_AGENT_HOME/.venv/bin/python" scripts/analyze.py <source> \
  --language java --algorithm pkg

This is the default report: a self-contained static HTML page (component diagram, smells, metrics). For an explorable version of the same analysis — click a component to drill in — use the optional interactive report (#11); it's an alternative, not a replacement.

Options: --language/-l, --algorithm/-a (pkg default, wca/acdc/arc/limbo), --num-clusters/-n, --source-root (e.g. src/main/java), --use-llm, --also-mermaid, --output/-o, --no-open, --arcade-home.

2. Compare algorithms — side-by-side recovery report

"$ARCADE_AGENT_HOME/.venv/bin/python" scripts/compare_algorithms.py <source> \
  --algorithms pkg,wca,acdc -n 13

Pass -n (target cluster count) when including wca — it over-fragments without one. arc/limbo require --use-llm.

3. Diff versions — architectural drift between two git refs

"$ARCADE_AGENT_HOME/.venv/bin/python" scripts/diff_versions.py <local-git-repo> \
  --from v1.0.0 --to v1.2.0 --language java

Clones to a temp dir (your working tree is untouched). Prints a markdown drift report — A2A similarity, metric deltas, added/removed components, entity movements, new vs. resolved smells. --to defaults to HEAD; -o saves the markdown.

4. Query — answer questions about the architecture

"$ARCADE_AGENT_HOME/.venv/bin/python" scripts/query.py summarize <source>
"$ARCADE_AGENT_HOME/.venv/bin/python" scripts/query.py explain <source> Clustering
"$ARCADE_AGENT_HOME/.venv/bin/python" scripts/query.py find <source> "authentication"
"$ARCADE_AGENT_HOME/.venv/bin/python" scripts/query.py ask <source> most_coupled

5–10. Architect deliverables

# Executive summary: health score + findings + recommended actions
"$ARCADE_AGENT_HOME/.venv/bin/python" scripts/summary_report.py <source> -l java -o summary.md

# Design Structure Matrix (scales past Mermaid; cycles in red)
"$ARCADE_AGENT_HOME/.venv/bin/python" scripts/dsm.py <source> -l java

# C4-PlantUML + Structurizr DSL export
"$ARCADE_AGENT_HOME/.venv/bin/python" scripts/export_c4.py <source> -l java -o out/

# Ranked refactoring roadmap (quick wins vs big bets)
"$ARCADE_AGENT_HOME/.venv/bin/python" scripts/refactor_plan.py <source> -l java -o plan.md

# Rule + layered-architecture validation (exits 1 on violation → CI gate)
"$ARCADE_AGENT_HOME/.venv/bin/python" scripts/validate.py <source> -l java --rules .arcade-rules.json

# Multi-module / microservices system view
"$ARCADE_AGENT_HOME/.venv/bin/python" scripts/analyze_system.py <modA> <modB> <modC> -l java

# Interactive, explorable report — click a component to drill in
"$ARCADE_AGENT_HOME/.venv/bin/python" scripts/interactive_report.py <source> -l java

# App-style visualizer — diagram + DSM + failure points + animated flow simulation
"$ARCADE_AGENT_HOME/.venv/bin/python" scripts/visualizer.py <source> -l java

The interactive report (interactive_report.py) is an optional explorable alternative to the default static report from analyze.py — the static report stays the default; reach for this one when you want to explore rather than read. Click a component in the diagram (or its chip) and a side panel drills into that component — its entities, what it depends on / what depends on it, cohesion, API surface, and the smells that touch it. Dependency chips are themselves clickable, so you walk the graph instead of scrolling a page. Everything is embedded in one self-contained HTML file (only Mermaid loads from a CDN).

The visualizer (visualizer.py) goes one step further: an app-style single-page workbench (fully offline — no CDN; dark by default, with a persistent dark/light mode toggle in the top bar) with sidebar views:

• Architecture — pan/zoom node-card diagram with a Components (L1) / Detailed (L2) toggle and a click-to-drill side panel;
• Dependencies — weighted dependency list + Design Structure Matrix, cyclic pairs in red;
• Failure Points — smells presented as failure cards: severity, concrete impact, suggested mitigation, estimated effort;
• Recommendations — a ranked, senior-architect-style improvement plan (quick wins / planned work / big bets) derived from the failure points and the weakest principle signals, each with the concrete components to touch, the metrics it improves, and the estimated effort;
• Simulate — animate a dependency flow hop-by-hop through the graph with a per-hop coupling waterfall; traces are auto-derived (entry flow, hub fan-out, cycle walk) and you can record custom ones by clicking components;
• Knowledge — the full arcade-agent metric set with plain-English interpretation: core metrics with their evidence (intra/inter edge counts, bidirectional pairs…), the derived balanced scores and principle signals (acyclic deps, layering health, hub balance…), strengths vs risks, and a per-component quality table (cluster factor, intra-connectivity);
• Comments — a feedback bar whose notes can be copied out as a ready-to-paste prompt for Claude.

Live mode (--serve) turns the visualizer into a two-way loop with an agent: visualizer.py --from-model model.json --serve serves the app on localhost, writes every feedback-bar note to <model>-feedback.json on disk (where Claude can read it), and auto-reloads the page within ~2 seconds whenever the model JSON changes — so Claude reads your feedback, edits the model, and your browser view refreshes itself.

A committed demo (no arcade-agent needed) lives at examples/arcade-visualizer-demo.html, rendered from examples/visualizer-demo-model.json via visualizer.py --from-model.

Enforcing architecture in CI: define rules in .arcade-rules.json (see assets/arcade-rules.sample.json) and copy assets/arch-gate.yml into your repo's .github/workflows/. The gate fails the PR on cycles, forbidden dependencies, metric floors, oversized components, or bottlenecks.

Architecture guardrail (arcade-guard)

Keep an AI agent (or a human) aligned to an intended architecture while building, not just analyzing after the fact. You define the intended architecture once in architecture.spec.json (components by path glob, layers, allowed/forbidden dependencies, decay budgets); the guardrail enforces it deterministically. See GUARDRAIL_PLAN.md for the full design and status.

# Scaffold a contract (templates: hexagonal | layered | clean | mvc)
"$ARCADE_AGENT_HOME/.venv/bin/python" scripts/guard.py init --template hexagonal

# PROACTIVE: where should a new thing live, and what may it depend on?
"$ARCADE_AGENT_HOME/.venv/bin/python" scripts/guard.py propose . --intent "add a Redis cache client"

# Before adding a cross-component dependency
"$ARCADE_AGENT_HOME/.venv/bin/python" scripts/guard.py preview . --from api --to store

# After a change — verdict + fixes; exits 1 on FAIL (pre-commit / CI gate)
"$ARCADE_AGENT_HOME/.venv/bin/python" scripts/guard.py check . --fail-on error

Or run it as an MCP server so any agent can call it as tools (check_architecture, propose_placement, preview_impact, explain_violation, remediate):

ARCADE_AGENT_HOME=/path/to/arcade-agent \
  /path/to/arcade-agent/.venv/bin/python scripts/guard_mcp.py

Tiered enforcement: advisory in the agent's loop (MCP tools + assets/guard-claude-hook.md) and blocking at the boundary (assets/guard-pre-commit.sh, assets/guard-ci.yml). Sample contract: assets/architecture.spec.sample.json.

See references/algorithms.md for algorithm, smell, and metric details, and ROADMAP.md for what's planned next.

Layout

arcade-analyze-skill/
├── SKILL.md                      # skill definition + how to drive each workflow
├── scripts/
│   ├── _common.py                # shared: home resolution, ingest+parse+recover, summary
│   ├── analyze.py                # 1. single-run pipeline → HTML report
│   ├── compare_algorithms.py     # 2. side-by-side algorithm comparison
│   ├── diff_versions.py          # 3. architectural drift across git refs (+ CI gate)
│   ├── query.py                  # 4. Q&A: summarize / explain / find / ask
│   ├── summary_report.py         # 5. executive summary: health score + findings
│   ├── dsm.py                    # 6. Design Structure Matrix view
│   ├── export_c4.py              # 7. C4-PlantUML + Structurizr DSL export
│   ├── refactor_plan.py          # 8. ranked refactoring roadmap
│   ├── validate.py               # 9. rule + layered-architecture validation
│   ├── analyze_system.py         # 10. multi-module / microservices view
│   ├── interactive_report.py     # 11. explorable HTML report (click to drill in)
│   ├── visualizer.py             # 12. app-style visualizer (diagram/DSM/failures/simulate)
│   ├── _spec.py                  # arcade-guard: architecture-contract engine
│   ├── guard.py                  # arcade-guard CLI (init/check/propose/preview/...)
│   └── guard_mcp.py              # arcade-guard MCP server (agent-callable tools)
├── assets/                       # rules + CI gates + guard spec/hooks/templates
├── examples/                     # committed demo reports + run_demo.sh
├── references/algorithms.md      # algorithm / smell / metric reference
├── GUARDRAIL_PLAN.md             # arcade-guard design + implementation status
└── ROADMAP.md                    # roadmap toward a full architect tool

License

MIT