Skip to main content
Testing & QAagentic-dev3o

explaining-architecture

Analyzes project architecture and generates ASCII state machine and sequence diagrams. Use for explaining a project, analyzing architecture, tracing an entrypoint, showing a state machine, or generating a sequence diagram.

Stars
10
Source
agentic-dev3o/devx-plugins
Updated
2026-05-22
Slug
agentic-dev3o--devx-plugins--explaining-architecture
View on GitHubRaw SKILL.md

// install — copy + paste into any project

mkdir -p .claude/skills && curl -fsSL https://raw.githubusercontent.com/agentic-dev3o/devx-plugins/HEAD/plugins/qa/skills/explaining-architecture/SKILL.md -o .claude/skills/explaining-architecture.md

Drops the SKILL.md into .claude/skills/explaining-architecture.md. Works with Claude Code, Cursor, and any agent that loads SKILL.md files from .claude/skills/.

Project Explain

Analyze project architecture and produce ASCII state machine and sequence diagrams for a given codebase or feature.

Target: $ARGUMENTS

Workflow

Copy this checklist and track progress:

Architecture Analysis:
- [ ] Step 1: Analyze project composition
- [ ] Step 2: Find entrypoint
- [ ] Step 3: Build state machine graph
- [ ] Step 4: Generate sequence diagram
- [ ] Step 5: Output synthesis

Step 1: Analyze Project Composition

Run language statistics: tokei || echo 'not installed'

If tokei is unavailable, use Glob to count files by extension and estimate composition.

Detect and read the first package manifest found (package.json, Cargo.toml, go.mod, pyproject.toml, requirements.txt, pom.xml, build.gradle). Identify framework from config files and directory structure.

Step 2: Find Entrypoint

If $ARGUMENTS is specified, locate that feature or module first.

Otherwise search for the main entrypoint: main field in manifest, common files (main.*, index.*, app.*, cmd/main.go), or framework-specific entries (pages/_app.tsx, src/main.rs, manage.py).

From the entrypoint, trace initialization, configuration loading, service bootstrapping, and main event loop or request handler.

Step 3: Build State Machine Graph

Analyze the target for state variables, transition triggers, guards, side effects, and terminal states. Generate an ASCII acyclic graph using box-drawing characters (─ │ ┌ ┐ └ ┘ ├ ┤ ┬ ┴ ┼ ► ◄ ▲ ▼). Max 80 chars wide.

Step 4: Generate Sequence Diagram

Identify actors (client, controllers, services, data layer, external APIs). Generate an ASCII sequence diagram showing control flow between them. Max 80 chars wide.

Step 5: Output Synthesis

Present findings using this template:

╔════════════════════════════════════════╗
║ PROJECT: <name>                        ║
╠════════════════════════════════════════╣
║ Language: <primary>                    ║
║ Framework: <detected>                  ║
║ Type: <CLI/API/Web/Library>            ║
╚════════════════════════════════════════╝

Then include in order:

  1. Stack Summary — language, framework, major libraries, build tools, test framework
  2. State Machine Diagram — acyclic graph from Step 3
  3. Sequence Diagram — control flow from Step 4
  4. Key Files — entrypoint, config, controller, service paths

Constraints

  • ASCII diagrams only (no mermaid), max 80 chars wide
  • Focus on specified feature path for large projects