| name | archflow |
| description | Analyzes a codebase and generates animated HTML architecture reports —
beautiful, bespoke visualizations with interactive animated diagrams
showing how the system works. Three output modes: full report (default),
diagram-only (zero external deps), or scroll-snap slide deck.
Use when the user says: "visualize the codebase", "explain the
architecture", "generate a diagram", "show how the code flows",
"create an architecture diagram", "animate the data flow", "explain
this repo visually", "show me how this works", or "generate an
architecture report".
Do NOT use for: editing source code, generating documentation prose
(use a regular doc), or producing static dependency graphs (this skill
shows one typical request flow end-to-end, not the full graph).
|
| license | MIT |
| allowed-tools | ["shell"] |
Codebase Visualizer
Analyzes a codebase and produces beautiful, self-contained HTML
architecture outputs with animated flow diagrams.
===================================================================
OUTPUT MODES
Full report (default) → ./architecture-report.html
Diagram-only → ./architecture-diagram.html
Slide deck → ./architecture-slides.html
The user picks the mode via natural language:
"generate an architecture report" / "full report" → REPORT MODE
"just the diagram" / "animated diagram only" → DIAGRAM MODE
"slide deck" / "presentation" / "slides" → SLIDE MODE
If unclear, default to REPORT MODE.
NOTE — sibling shim skills can force the mode. If this SKILL.md was
loaded from one of these sibling skills, treat the mode as fixed and
skip natural-language detection:
archflow-diagram → MODE is fixed to DIAGRAM
archflow-slides → MODE is fixed to SLIDES
Direct invocation of archflow keeps the natural-language dispatch
above (defaulting to REPORT).
===================================================================
WORKFLOW — 7-STAGE PIPELINE (all modes)
Every output mode follows the same pipeline. Mode-specific behavior
is noted inline. After each stage completes, print a one-line status.
STAGE 1: ANALYZE
Read references/analysis.md → scan the codebase.
Read references/layouts.md → decide the diagram layout pattern.
Extract: components, groups, flows, external services.
After completion, print:
ANALYZE ✓ {N} files scanned, {M} components, {K} external services
STAGE 2: PLAN
Read references/design-system.md → CSS patterns library
Read references/libraries.md → fonts, Mermaid, CDN imports
Read references/design-qa.md → quality gates
Read references/animation.md → phase engine for the diagram
Read references/navigation.md → TOC sidebar (if needed)
Produce a visible, structured architecture map BEFORE any HTML.
Decide:
→ Font pairing that matches the project character
→ Color palette aesthetic (Blueprint, Terminal Mono, etc.)
→ Background atmosphere (radial glow, dot grid, mesh)
→ Layout pattern (pipeline, hub, medallion)
Do NOT default to the same choices every time.
Plan the content:
REPORT MODE — plan report sections. Include at minimum:
→ Header (project name, description, date)
→ Executive summary
→ KPI metrics
→ Animated architecture diagram (MANDATORY — the hero section)
→ Component directory or data table
→ Supporting content as the project demands
→ Code references
Compose FREELY. Add sections the project needs. Skip ones it doesn't.
DIAGRAM-ONLY MODE — plan diagram layout and phases only.
SLIDE MODE — plan content → slide type mapping and chunk boundaries
(5-7 slides per chunk for chunked generation in BUILD).
Output the architecture map to the user:
PLAN
Architecture: {N} components in {M} groups
Layout: {horizontal-pipeline | multi-agent-hub | medallion-pipeline}
Spine: {entry} → {group1} → {group2} → ... → {exit} ({P} phases)
Design: {font pairing} · {palette} · {atmosphere}
Sections: {N} sections planned
─────────────────────────────────
Groups:
HERO {group name} — {description}
ELEVATED {group name} — {description}
DEFAULT {group name} — {description}
...
This is the CONTRACT. The BUILD stage implements this map — it does
not re-decide architecture.
After completion, print:
PLAN ✓ {M} groups, {P} phases, {layout} layout
STAGE 3: BUILD
Read remaining reference docs as needed (svg-exemplar.md, etc.).
Write HTML/CSS/SVG implementing the architecture map from PLAN.
Use the design-system.md patterns as BUILDING BLOCKS, not templates.
Compose unique CSS per project. Design each component fresh.
REPORT MODE:
→ Write CUSTOM CSS for this specific report
→ Dark/light theme toggle with localStorage persistence
→ Responsive layout, prefers-reduced-motion support
→ The animated diagram is the hero section — maximum visual weight
DIAGRAM-ONLY MODE:
→ Fully self-contained — zero external dependencies
→ Self-contained fonts: 'JetBrains Mono', 'Fira Code', monospace
→ Reference examples (for layout patterns, not rigid templates):
assets/templates/horizontal-pipeline.html
assets/templates/multi-agent-hub.html
assets/templates/medallion-pipeline.html
SLIDE MODE (chunked generation with per-chunk review):
1. PLAN stage defined chunk boundaries (5-7 slides per chunk)
2. For each chunk:
a. BUILD chunk:
- Chunk 1: , CSS, opening
, slides 1-N
- Middle chunks: elements only
- Last chunk: remaining slides, closing
, SlideEngine JS
b. REVIEW chunk: spawn reviewer agent (see references/reviewer-agent.md)
on the chunk HTML (subset checks relevant to slides)
c. FIX chunk if CRITICAL or ERROR found (max 2 fix cycles per chunk)
d. Print per-chunk progress:
Chunk {i}/{M} (slides {start}-{end}): BUILD ✓ REVIEW ✓ (0C 0E 1W)
3. Assemble all validated chunks into single file
4. FINAL REVIEW on the assembled deck for cross-chunk issues:
- Duplicate CSS definitions or mismatched variables
- Slide count matching navigation dots
- Consistent styling across all sections
After completion, print:
BUILD ✓ {output-mode} generated ({lines} lines, {M} chunks)
STAGE 4: DELIVER
Write the output file:
REPORT MODE: ./architecture-report.html
DIAGRAM MODE: ./architecture-diagram.html
SLIDE MODE: ./architecture-slides.html
Single self-contained HTML file. Tell the user the path so they can
open it in a browser.
After completion, print:
DELIVER ✓ {output-path}
STAGE 5: REVIEW (independent agent)
Spawn a separate reviewer agent to validate the output. Use the
task tool with agent_type general-purpose (or code-review if
available). See references/reviewer-agent.md for the full prompt
specification.
The reviewer reads the HTML cold — it did not build the output and
has no memory of what was intended. It only sees what was produced.
This objectivity catches issues that self-review misses.
The reviewer reads the generated HTML file and validates against
the STRUCTURED REVIEW PROTOCOL in design-qa.md.
It runs ALL check categories and produces a severity-scored report:
REVIEW
HTML validity ✓ All tags closed, no broken nesting
Typography ✓ 2 font families (Instrument Serif + DM Sans + Fira Code)
Palette ✓ 2 accents (cyan, orange) + neutrals
Depth tiers ✓ 3 tiers used (hero, elevated, recessed)
Color variety ✓ No monochrome grids
Layout rhythm ✓ 5 distinct section layouts
Backgrounds ✓ Each section has unique treatment
SVG structure ✓ No orphan groups, all arrows connect
SVG text fit ⚠ WARNING: "VectorStoreIndex" may overflow rect at x=290 (est 148px, rect 150px)
SVG labels ✓ All flow labels inside gaps, no border overlap
Animation ✓ 6 phases, all groups highlighted
Theme toggle ✓ CSS variables used throughout
Accessibility ✓ prefers-reduced-motion supported
─────────────────────────────────
VERDICT: PASS (0 CRITICAL, 0 ERROR, 1 WARNING)
Severity levels:
CRITICAL Broken output (missing phase engine, no SVG, HTML syntax error)
ERROR Quality gate failure (single font, flat backgrounds, orphan SVG groups, text overflow)
WARNING Minor issue (tight text fit, same card shape 3x adjacent, could improve variety)
INFO Suggestion (could add a quote slide for breathing room)
After completion, print:
REVIEW ✓ {VERDICT} ({C}C {E}E {W}W)
STAGE 6: FIX (conditional)
Skip this stage if REVIEW verdict is PASS or CONDITIONAL PASS
with only WARNINGs.
If REVIEW has CRITICAL or ERROR findings:
→ Fix CRITICAL findings first — they break the output entirely.
→ Apply targeted fixes. One edit per finding.
→ Do NOT redesign — surgical corrections only.
→ After EACH edit, verify the fix took effect by re-reading the
modified lines. A fix that doesn't change the output is not a fix.
→ After all fixes applied, re-run the full REVIEW (Stage 5).
The re-review must confirm every previously-CRITICAL and
previously-ERROR finding is now resolved. If any CRITICAL
or ERROR persists, that is a failed fix cycle — loop again.
→ Keep looping (fix → review) until the verdict is PASS or
CONDITIONAL PASS. Do not stop while CRITICAL or ERROR remain.
→ Hard ceiling: 5 cycles. If still failing after 5 cycles,
something is fundamentally broken — present the full review
report to the user and ask for guidance. Do not continue.
After completion, print:
FIX ✓ {N} cycle(s) ({M} finding(s) resolved)
STAGE 7: PRESENT
Print final summary with the accumulated progress report.
REPORT / DIAGRAM MODE:
ARCHFLOW: {project-name}
━━━━━━━━━━━━━━━━━━━━━━━━
ANALYZE ✓ {N} files scanned, {M} components found
PLAN ✓ {M} groups, {P} phases, {layout} layout
BUILD ✓ {output-mode} generated ({lines} lines)
DELIVER ✓ {output-path}
REVIEW ✓ PASS (0C 0E 1W)
{FIX ✓ 1 cycle (1 warning resolved)}
━━━━━━━━━━━━━━━━━━━━━━━━
OUTPUT: {path}
QUALITY: {percentage}% ({warnings}W)
SLIDE MODE (includes per-chunk detail):
ARCHFLOW: {project-name}
━━━━━━━━━━━━━━━━━━━━━━━━
ANALYZE ✓ {N} files scanned, {M} components found
PLAN ✓ {M} groups, {P} phases, {N} slides in {M} chunks
BUILD + REVIEW
Chunk 1/{M} (slides 1-{n}): BUILD ✓ REVIEW ✓ (0C 0E 1W)
Chunk 2/{M} (slides {n+1}-{m}): BUILD ✓ REVIEW ✗ → FIX ✓ (0C 0E 0W)
...
ASSEMBLE ✓ {M} chunks → {N} slides
DELIVER ✓ {output-path}
FINAL REVIEW ✓ PASS (0C 0E 1W)
{FIX ✓ 1 cycle (1 warning resolved)}
━━━━━━━━━━━━━━━━━━━━━━━━
OUTPUT: {path}
QUALITY: {percentage}% ({warnings}W)
FIX CYCLES: {count} (chunks {list})
===================================================================
DESIGN PRINCIPLES
Think MAGAZINE, not JIRA. Think PRODUCT PAGE, not ADMIN PANEL.
→ Each report should feel INTENTIONALLY DESIGNED for this specific
project. If you swapped the CSS between two reports and nobody
would notice, you haven't designed anything.
→ TYPOGRAPHY IS THE DESIGN. Use at least 2 distinct font families.
Mix serif display (Instrument Serif, Playfair Display) with
sans-serif body. Add a third voice for quotes/callouts.
Never use one font family for everything.
→ The design-system.md provides BUILDING BLOCKS, not templates.
Compose unique CSS per project. Don't copy class definitions —
design each component fresh, guided by the principles.
→ BACKGROUNDS CREATE ATMOSPHERE. Each section is a different room.
Every section MUST have its own unique background treatment
(radial gradient, linear sweep, texture). No uniform flat
backgrounds across all sections.
→ Keep the palette TIGHT — 2 accent colors + neutrals. Don't use 6+.
→ Use GENEROUS whitespace — 40-80px section padding. Let it breathe.
→ Every section has a UNIQUE layout AND component shape. Don't repeat
card grids. Mix: full-bleed, split panels, stat bars, entity lists,
editorial quotes, terminal mockups, SVG charts.
→ The ANIMATED DIAGRAM is the hero section — maximum visual weight.
→ SINGLE-PAGE DIAGRAMS: prefer compact layouts where the full
architecture is visible in 1-2 viewport scrolls. Use horizontal
flow-rows for linear 4-7 layer systems; vertical stacks only
when layers have nested sub-components.
→ ALL diagrams on the page highlight in SYNC during phase animation.
→ Apply the SQUINT TEST: sections must be distinct when blurred.
→ Apply the SWAP TEST: hierarchy must work without color alone.
→ If it looks like a Bootstrap dashboard, redesign it.
===================================================================
OUTPUT RULES
ALL MODES:
→ Single self-contained HTML file
→ Use real class/function/module names — never generic placeholders
→ Use real external service names (Azure Cosmos DB, not "Database")
→ Phase count: 4-8 phases (sweet spot for animation readability)
→ Max 8 components per row before layout gets crowded
→ After writing, surface the output path so the user can open it
REPORT MODE:
→ File: ./architecture-report.html
→ External deps: Google Fonts CDN + optional Mermaid CDN
→ Dark/light theme toggle with localStorage persistence
→ Responsive layout (works on mobile)
→ prefers-reduced-motion support
DIAGRAM-ONLY MODE:
→ File: ./architecture-diagram.html
→ Fully self-contained — zero external dependencies
SLIDE MODE:
→ File: ./architecture-slides.html
→ External deps: Google Fonts CDN
===================================================================
ANALYSIS DEPTH
For diagram-only: components, data flows (4-8 phases), external
services, 3-4 insights.
For report/slides: ALSO extract component counts, file paths,
layer classifications, detailed data flow descriptions, 4-6
insights, and list of key files analyzed. Create bespoke
visualizations when the data supports it (benchmarks, metrics,
comparison panels, distribution charts).
