---

name: ascii-diagram-creator description: Use PROACTIVELY when user asks for ASCII diagrams, text diagrams, or visual representations of systems, workflows, or relationships. Triggers on "ascii diagram", "text diagram", "visualize", "show how X connects/synergizes", "diagram the flow/phases", or "illustrate relationships". Generates terminal-compatible diagrams using box-drawing characters. Supports architecture, before/after, phased migration, data flow, and relationship/synergy diagrams. Not for image generation or graphical output.

ASCII Diagram Creator

Overview

This skill is a visual generator agent that creates clear, terminal-compatible ASCII diagrams to communicate system changes, migrations, and architectural decisions. It analyzes your context, selects the appropriate diagram type, generates the diagram, and refines based on feedback.

Key Capabilities:

• Codebase auto-discovery: Automatically scan project structure, detect architecture patterns, and populate diagrams
• Project-type templates: Pre-built templates for Bulletproof React, Next.js, Express, Monorepos
• Context-aware diagram selection: Automatically choose the best diagram type for your use case
• Professional ASCII formatting: Box-drawing characters, arrows, and status indicators
• Diagram versioning: Metadata tracking for diagram freshness and staleness detection
• Mermaid export: Convert ASCII diagrams to Mermaid syntax for graphical rendering
• Git-aware staleness detection: Automatically flag outdated diagrams based on file changes
• PR template integration: Auto-include relevant diagrams in pull request descriptions
• CLAUDE.md directive setup: Optionally configure proactive diagram suggestions
• Iterative refinement: Adjust width, alignment, and content based on feedback
• Five diagram types: Architecture, Before/After, Phased Migration, Data Flow, Relationship/Synergy
• Terminal-compatible: 80-character max width, works in any terminal/markdown

When to Use This Skill

Trigger Phrases:

• "create an ascii diagram" / "make a text diagram"
• "create a diagram showing..."
• "visualize this architecture"
• "show how X connects/synergizes/relates"
• "diagram the workflow/phases/flow"
• "illustrate the relationships between"
• "show before and after"

Use PROACTIVELY when:

• User is planning a major refactoring or migration
• User is restructuring directories or file organization
• User needs to communicate system changes in a PR description
• User is explaining architecture to team members
• User mentions "show me", "visualize", or "diagram"

Do NOT use when:

• User wants graphical/image output (use Mermaid or external tools)
• User needs flowcharts with complex branching (consider Mermaid)
• User is asking about code, not structure or flow
• Simple lists would suffice instead of visual diagrams

Response Style

Visual Generator Agent: Analyze context to determine what needs visualization, select appropriate diagram type, generate ASCII diagram, and refine through iteration.

Execution Pattern:

1. Analyze context: Understand what the user wants to visualize
2. Select diagram type: Choose Architecture, Before/After, Phased, or Data Flow
3. Generate diagram: Create initial diagram with proper formatting
4. Present with explanation: Show diagram and explain visual elements
5. Refine on request: Adjust based on user feedback ("make it wider", "add status")
6. MANDATORY - Output & Integration: Execute Phase 4 completely:
   • Offer Mermaid export for graphical rendering
   • Run staleness detection if existing diagrams found
   • Offer PR integration if user is working on a PR
   • Ask about CLAUDE.md directive setup
   • Output completion checklist (see below)

CRITICAL: The skill is NOT complete until the Completion Checklist is output.

Workflow

Phase	Description	Details
0	Context Analysis	→ workflow/phase-0-context-analysis.md
1	Diagram Type Selection	→ workflow/phase-1-diagram-selection.md
2	Diagram Generation	→ workflow/phase-2-generation.md
3	Iterative Refinement	→ workflow/phase-3-refinement.md
4	Output & Integration (MANDATORY)	→ workflow/phase-4-output-integration.md

⚠️ IMPORTANT: Phase 4 must ALWAYS be executed. Do not consider the skill complete until you have offered all integration options and output the completion checklist.

Quick Reference

Diagram Types

Type	Purpose	Best For
Architecture	System components and relationships	Showing how modules connect
Before/After	Compare current vs proposed state	Migration plans, refactoring
Phased Migration	Step-by-step progression	Multi-phase projects
Data Flow	How data moves through system	API flows, pipelines
Relationship/Synergy	How elements interact or complement	SDLC phases, skill workflows, team structures

Visual Elements

Category	Elements	Usage
Box Drawing	┌─┬─┐ │ │ │ ├─┼─┤ └─┴─┘	Component boundaries
Arrows	──► ◄── ◄─► ──✗ ──✓	Relationships, flow
Status	✓ ✗ ⏳ 🔄 ⚠️ 🔴	Progress indicators

Formatting Rules

Rule	Value	Reason
Max width	80 characters	Terminal compatibility
Box alignment	Vertical centers	Visual clarity
Spacing	Between sections	Readability
Legends	When using symbols	Self-documenting

Diagram Versioning

Add metadata to track diagram freshness and enable staleness detection:

<!-- diagram-meta
  type: architecture
  created: 2025-01-23
  last-verified: 2025-01-23
  source-patterns: [src/features/*, src/app/routes/*]
  stale-after: 30d
-->

Metadata Fields:

Field	Purpose
type	Diagram type (architecture, data-flow, etc.)
created	Initial creation date
last-verified	Last time diagram was confirmed accurate
source-patterns	Glob patterns of directories diagram represents
stale-after	Days until diagram should be re-verified

Staleness Detection: When files matching source-patterns are modified after stale-after days from last-verified, the diagram should be re-verified.

Reference Materials

• Visual Elements Reference
• Best Practices
• Diagram Type Templates
• Project-Type Templates
• Mermaid Export Guide

Workflow Automation

This skill can be integrated into your workflow automatically. See the README for:

• Hook-based auto-triggers when creating feature branches
• CLAUDE.md directives for proactive diagram suggestions
• Sub-agent integration for feature planning workflows

Mandatory Completion Checklist

You MUST output this checklist before the skill is complete. This ensures all integration options are offered.

## Diagram Generation Complete

### Outputs
- [ ] ASCII diagram generated (80-char width)
- [ ] Diagram metadata added (if saving to file)

### Integration Options Offered (Phase 4)
- [ ] Mermaid export: [offered/accepted/declined/not applicable]
- [ ] PR integration: [offered/accepted/declined/not applicable]
- [ ] CLAUDE.md directive: [offered/accepted/declined/already configured]

### Next Steps
- Recommended save location: [path]
- Staleness tracking: [enabled/disabled]

Example completed checklist:

## Diagram Generation Complete

### Outputs
- [x] ASCII diagram generated (80-char width)
- [x] Diagram metadata added

### Integration Options Offered (Phase 4)
- [x] Mermaid export: offered, user declined
- [x] PR integration: accepted, added to PR description
- [x] CLAUDE.md directive: offered, user accepted (added to ~/.claude/CLAUDE.md)

### Next Steps
- Recommended save location: docs/architecture/auth-flow.md
- Staleness tracking: enabled (30 days)

Metadata

Category: planning Source: Protocol conversion from ~/.claude/protocols/ASCII_DIAGRAM_PROTOCOL.yaml Version: 0.3.1