zhongwei/gh-cskiro-claudex
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:16:40 +08:00
commit f125e90b9f
370 changed files with 67769 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

82
skills/planning/ascii-diagram-creator/CHANGELOG.md Normal file
View File

@@ -0,0 +1,82 @@
# Changelog
All notable changes to the ASCII Diagram Creator skill will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [0.3.1] - 2025-11-23
### Added
- **Mandatory Completion Checklist**: Template that must be output before skill is complete
- **CRITICAL markers**: Phase 4 marked as MANDATORY in workflow table
- **Explicit Phase 4 enforcement**: Execution pattern now lists all required Phase 4 steps
### Changed
- Execution pattern step 6 now explicitly lists all Phase 4 integration options
- Workflow table highlights Phase 4 as mandatory with warning callout
- Added "skill is NOT complete until" enforcement language
### Fixed
- Prevents LLM from skipping Phase 4 (Output & Integration) steps
- Ensures CLAUDE.md directive setup is always offered
## [0.3.0] - 2025-11-23
### Added
- **Mermaid Export**: Convert ASCII diagrams to Mermaid syntax for graphical rendering in GitHub, GitLab, Notion
- **Git-Aware Staleness Detection**: Automatically detect outdated diagrams based on git history and source file changes
- **PR Template Integration**: Auto-suggest diagram inclusion in PR descriptions and update PR templates
- **CLAUDE.md Directive Setup**: Interactive step to configure proactive diagram suggestions in user's CLAUDE.md
- **Phase 4 (Output & Integration)**: New workflow phase covering all output formats and integration options
- **Mermaid Export Reference Guide**: Comprehensive guide for ASCII-to-Mermaid conversion rules and examples
### Changed
- Workflow now includes 5 phases (added Output & Integration)
- Key capabilities expanded from 8 to 12 features
- Removed "Future Enhancements" section (all features now implemented)
### Documentation
- Added Version History section to README
- Updated all feature descriptions with version tags (v0.3.0)
- Added conversion examples and platform support matrix for Mermaid export
## [0.2.0] - 2025-11-23
### Added
- **Codebase Auto-Discovery Mode**: Automatically scan project structure, detect architecture patterns, and populate diagrams (reduces 50% manual exploration)
- **Project-Type Templates**: Pre-built templates for Bulletproof React, Next.js App Router, Express API, and Monorepo architectures
- **Diagram Versioning Metadata**: Track diagram freshness with `created`, `last-verified`, `source-patterns`, and `stale-after` fields
- **Workflow Automation Examples**: Hook-based auto-triggers, CLAUDE.md directives, and sub-agent integration patterns
- **Fifth Diagram Type**: Relationship/Synergy diagrams for showing how elements interact or complement each other
- **Project-Type Templates Reference**: New reference file with complete templates for each architecture type
### Changed
- Enhanced Phase 0 (Context Analysis) with auto-discovery commands
- Updated Quick Reference to include all five diagram types
- Improved key capabilities list in SKILL.md overview
### Documentation
- Added Workflow Automation section to README with three integration options
- Expanded feature documentation with version tags (v0.2.0)
## [0.1.0] - 2025-01-23
### Added
- Initial skill release
- Four diagram types: Architecture, Before/After, Phased Migration, Data Flow
- Visual elements: box-drawing characters, arrows, status indicators
- Phase-based workflow (context analysis, selection, generation, refinement)
- Reference materials for visual elements, best practices, and templates
- Example diagrams for each diagram type
- 80-character max width formatting for terminal compatibility

232
skills/planning/ascii-diagram-creator/README.md Normal file
View File

@@ -0,0 +1,232 @@
# ASCII Diagram Creator
Generate clear, terminal-compatible ASCII diagrams for system architecture, migrations, and data flows.
## Quick Start
Simply describe what you want to visualize:
```
"Create a diagram showing how our authentication module connects to the database"
"Show before and after for our directory restructuring"
"Diagram the three phases of our migration plan"
"Illustrate how data flows from the API to the frontend"
```
## Features
### Five Diagram Types
1. **Architecture** - System components and their relationships
2. **Before/After** - Compare current vs proposed state
3. **Phased Migration** - Step-by-step progression with status
4. **Data Flow** - How data moves through the system
5. **Relationship/Synergy** - How elements interact or complement each other
### Auto-Discovery Mode (v0.2.0)
Automatically scans your codebase to populate diagrams:
- Detects project type (Bulletproof React, Next.js, Express, Monorepo)
- Discovers feature boundaries, routes, and API layers
- Reduces 50% of manual codebase exploration
### Project-Type Templates (v0.2.0)
Pre-built templates for common architectures:
- **Bulletproof React** - Feature-based architecture with import rules
- **Next.js App Router** - Route groups and server components
- **Express API** - Layered architecture (routes → controllers → services)
- **Monorepo** - Apps and packages dependency flow
### Diagram Versioning (v0.2.0)
Track diagram freshness with metadata:
```markdown
<!-- diagram-meta
created: 2025-01-23
last-verified: 2025-01-23
source-patterns: [src/features/*, src/app/routes/*]
stale-after: 30d
-->
```
### Mermaid Export (v0.3.0)
Convert ASCII diagrams to Mermaid syntax for graphical rendering:
- Works in GitHub, GitLab, Notion, and other platforms
- Preserves structure, arrows, and groupings
- Includes status styling with CSS classes
```mermaid
graph LR
A[app/routes] --> B[features/domains]
B --> C[shared/common]
```
### Git-Aware Staleness Detection (v0.3.0)
Automatically detect outdated diagrams based on git history:
- Checks if source files have changed since last verification
- Generates staleness report with recommended actions
- Flags diagrams as STALE, CURRENT, or OUTDATED
### PR Template Integration (v0.3.0)
Seamlessly integrate diagrams into your PR workflow:
- Auto-suggest inclusion in PR descriptions
- Option to update PR templates with diagram section
- Include architecture impact documentation
### CLAUDE.md Directive Setup (v0.3.0)
Configure proactive diagram suggestions:
- Add semantic triggers to your CLAUDE.md
- Auto-suggest diagrams for feature branches
- Customize trigger phrases for your workflow
### Professional Visual Elements
- Box-drawing characters for clean boundaries
- Directional arrows for relationships
- Status indicators for progress tracking
- 80-character max width for terminal compatibility
## Example Output
```
┌─────────────────────────────────────────────────────────┐
│ SYSTEM CONSOLIDATION PLAN │
└─────────────────────────────────────────────────────────┘
PHASE 1: Analysis
┌──────────────────┐
│ Current State │──► Identify duplicates
│ 11 directories │──► Find dependencies
│ 3 systems │──► Check references
└──────────────────┘
│
▼
PHASE 2: Migration
┌──────────────────┐
│ Moving Data │
│ ✓ Memory files │
│ ✓ Pattern files │
│ ⏳ Script updates │
└──────────────────┘
│
▼
PHASE 3: Validation
┌──────────────────┐
│ Final State │
│ 2 directories │──► All tests passing
│ 1 unified system │──► No duplicates
└──────────────────┘
```
## Use Cases
- **PR Descriptions**: Include before/after diagrams to clarify changes
- **Architecture Documentation**: Visualize system structure
- **Migration Planning**: Track progress through phases
- **Team Communication**: Share clear visual representations
## Tips
- **Be specific**: "Show the auth flow from login to token storage"
- **Mention status**: "Include progress indicators for each phase"
- **Request refinements**: "Make the boxes wider" or "Add a legend"
## Limitations
- Not for graphical/image output (use Mermaid for that)
- Max 80 characters wide for terminal compatibility
- Text-based only - no colors or special fonts
## Workflow Automation
Make diagram creation automatic by integrating with your development workflow.
### Option A: Hook-Based Auto-Trigger (Recommended)
Create a git hook that suggests diagrams when creating feature branches:
```bash
# .git/hooks/post-checkout
#!/bin/bash
# Trigger when creating feature branches
BRANCH_NAME=$(git rev-parse --abbrev-ref HEAD)
if [[ "$BRANCH_NAME" =~ ^feature/ ]]; then
echo ""
echo "📊 Architecture Diagrams Recommended"
echo "Consider creating diagrams for this feature:"
echo " • Run: /ascii-diagram or invoke the skill"
echo " • Ask: 'create architecture diagram for this feature'"
echo ""
fi
```
### Option B: CLAUDE.md Directive
Add to your project's CLAUDE.md to enable proactive suggestions:
```markdown
## Architecture Documentation Standards
### When Starting New Features
Before implementation, create or update ASCII diagrams in `docs/architecture/`:
- Use `ascii-diagram-creator` skill for feature boundaries
- Update architecture diagrams if adding new routes or features
- Include diagram in PR description for reviewer context
### Auto-Trigger Phrases
When user mentions: "new feature", "planning", "architecture", "how should I structure"
→ Proactively offer to create architecture diagrams
```
### Option C: Sub-Agent Integration
Create a feature-planner sub-agent that chains diagram creation:
```markdown
# .claude/agents/feature-planner.md
---
name: feature-planner
description: Plan new features with architecture visualization
tools: [Read, Write, Glob, Grep]
---
When planning a new feature:
1. Analyze existing architecture using auto-discovery
2. **Invoke ascii-diagram-creator** for visual planning
3. Generate feature scaffold based on diagram
4. Create initial test files
```
### Recommended Workflow
```
┌─────────────────────────────────────────────────────────────────┐
│ AUTOMATIC DIAGRAM GENERATION WORKFLOW │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 1. Developer creates feature branch │
│ └──► Hook detects "feature/" prefix │
│ │
│ 2. Hook injects context into conversation │
│ └──► "Architecture diagrams recommended for this feature" │
│ │
│ 3. Claude proactively offers diagram creation │
│ └──► Based on CLAUDE.md directive │
│ │
│ 4. Diagrams created in docs/architecture/features/{name}.md │
│ └──► Linked in PR template automatically │
│ │
└─────────────────────────────────────────────────────────────────┘
```
## Version History
- **v0.3.0** - Mermaid export, git-aware staleness, PR integration, CLAUDE.md directives
- **v0.2.0** - Auto-discovery, project templates, diagram versioning
- **v0.1.0** - Initial release with 5 diagram types

193
skills/planning/ascii-diagram-creator/SKILL.md Normal file
View File

@@ -0,0 +1,193 @@
---
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](workflow/phase-0-context-analysis.md) |
| 1 | Diagram Type Selection | → [workflow/phase-1-diagram-selection.md](workflow/phase-1-diagram-selection.md) |
| 2 | Diagram Generation | → [workflow/phase-2-generation.md](workflow/phase-2-generation.md) |
| 3 | Iterative Refinement | → [workflow/phase-3-refinement.md](workflow/phase-3-refinement.md) |
| **4** | **Output & Integration (MANDATORY)** | → [workflow/phase-4-output-integration.md](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:
```markdown
<!-- 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](reference/visual-elements.md)
- [Best Practices](reference/best-practices.md)
- [Diagram Type Templates](reference/diagram-types.md)
- [Project-Type Templates](reference/project-templates.md)
- [Mermaid Export Guide](reference/mermaid-export.md)
## 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.
```markdown
## 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:**
```markdown
## 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

64
skills/planning/ascii-diagram-creator/examples/architecture-diagram.md Normal file
View File

@@ -0,0 +1,64 @@
# Example: Architecture Diagram
## Scenario
A user asks: "Show me how our e-commerce platform components are connected."
## Generated Diagram
```
┌─────────────────────────────────────────────────────────────────────────┐
│ E-COMMERCE PLATFORM ARCHITECTURE │
└─────────────────────────────────────────────────────────────────────────┘
┌───────────────────┐ ┌───────────────────┐
│ Web Frontend │ │ Mobile Frontend │
├───────────────────┤ ├───────────────────┤
│ • React SPA │ │ • React Native │
│ • Redux state │ │ • Offline sync │
│ • Tailwind CSS │ │ • Push notifs │
└───────────────────┘ └───────────────────┘
│ │
└───────────────────┬───────────────────────────┘
│
▼
┌───────────────────┐
│ API Gateway │
├───────────────────┤
│ • Rate limiting │
│ • Auth validation │
│ • Request routing │
└───────────────────┘
│
┌───────────────────┼───────────────────┐
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Auth Service │ │ Product Service │ │ Order Service │
├─────────────────┤ ├─────────────────┤ ├─────────────────┤
│ • JWT tokens │ │ • Catalog CRUD │ │ • Cart mgmt │
│ • OAuth 2.0 │ │ • Search/filter │ │ • Checkout flow │
│ • Session mgmt │ │ • Inventory │ │ • Payment proc │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Users DB │ │ Products DB │ │ Orders DB │
│ (PostgreSQL) │ │ (PostgreSQL) │ │ (PostgreSQL) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
```
## Explanation
This architecture diagram shows the three-tier structure of the e-commerce platform:
1. **Presentation Layer**: Web and mobile frontends
2. **API Layer**: Gateway with routing to microservices
3. **Data Layer**: Dedicated databases per service
The vertical flow clearly shows how requests travel from clients through the gateway to specific services and their databases.
## Usage Suggestions
- Include in architecture documentation
- Add to README for new developer onboarding
- Reference in technical design documents

66
skills/planning/ascii-diagram-creator/examples/before-after-diagram.md Normal file
View File

@@ -0,0 +1,66 @@
# Example: Before/After Diagram
## Scenario
A user asks: "Show the directory structure before and after our TypeScript migration."
## Generated Diagram
```
┌─────────────────────────────────────────────────────────────────────────┐
│ JAVASCRIPT TO TYPESCRIPT MIGRATION │
└─────────────────────────────────────────────────────────────────────────┘
BEFORE (JavaScript): AFTER (TypeScript):
src/ src/
├── components/ ├── components/
│ ├── Button.js ──► │ ├── Button.tsx ✓
│ ├── Button.css ──► │ │ (CSS modules imported)
│ ├── Form.js ──► │ ├── Form.tsx ✓
│ ├── Form.css ──► │ │ (CSS modules imported)
│ └── Modal.js ──► │ └── Modal.tsx ✓
├── utils/ ├── utils/
│ ├── helpers.js ──► │ ├── helpers.ts ✓
│ ├── constants.js ──► │ ├── constants.ts ✓
│ └── api.js ──► │ └── api.ts ✓
├── hooks/ ├── hooks/
│ ├── useAuth.js ──► │ ├── useAuth.ts ✓
│ └── useForm.js ──► │ └── useForm.ts ✓
├── types/ NEW ├── types/
│ │ ├── index.ts ✓
│ │ ├── api.d.ts ✓
│ │ └── components.d.ts ✓
├── App.js ──► ├── App.tsx ✓
├── index.js ──► ├── index.tsx ✓
└── .eslintrc.js ──► ├── .eslintrc.js (updated)
└── tsconfig.json NEW
Configuration Files:
├── package.json ──► ├── package.json (updated deps)
├── jest.config.js ──► ├── jest.config.js (ts-jest)
└── .babelrc ✗ └── (removed - using tsc)
Legend:
✓ = Conversion complete
──► = Transformed/updated
✗ = Removed
NEW = New file/directory
```
## Explanation
This before/after diagram shows the complete scope of a TypeScript migration:
- **File transformations**: .js → .tsx/.ts conversions
- **New additions**: types/ directory with type definitions
- **Removed files**: Babel config (replaced by TypeScript compiler)
- **Updated configs**: ESLint and Jest configurations
The parallel columns make it easy to trace each file's transformation.
## Usage Suggestions
- Include in migration PR description
- Add to project README as migration record
- Reference in team communication about changes

119
skills/planning/ascii-diagram-creator/examples/data-flow-diagram.md Normal file
View File

@@ -0,0 +1,119 @@
# Example: Data Flow Diagram
## Scenario
A user asks: "Illustrate how user authentication data flows through our system."
## Generated Diagram
```
┌─────────────────────────────────────────────────────────────────────────┐
│ USER AUTHENTICATION FLOW │
└─────────────────────────────────────────────────────────────────────────┘
┌──────────────┐
│ Browser │
│ Login Form │
└──────────────┘
│
│ 1. POST /auth/login
│ { email, password }
▼
┌──────────────┐
│ API Gateway │
│ (Express) │
└──────────────┘
│
│ 2. Route to auth service
▼
┌──────────────────────────────────────────────────────────────┐
│ AUTH SERVICE │
├──────────────────────────────────────────────────────────────┤
│ │
│ 3. Validate credentials │
│ ┌─────────────┐ │
│ │ Hash pwd │──► Compare with stored hash │
│ └─────────────┘ │
│ │ │
│ ▼ │
│ 4. Query user database │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ Users DB │────►│ User record │ │
│ │ (Postgres) │ │ + roles │ │
│ └─────────────┘ └─────────────┘ │
│ │ │
│ ▼ │
│ 5. Generate tokens │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ JWT Access │ │ Refresh │ │
│ │ (15 min) │ │ (7 days) │ │
│ └─────────────┘ └─────────────┘ │
│ │ │ │
│ │ ▼ │
│ │ 6. Store refresh token │
│ │ ┌─────────────┐ │
│ │ │ Redis │ │
│ │ │ Sessions │ │
│ │ └─────────────┘ │
│ │ │
└────────────┼──────────────────────────────────────────────────┘
│
│ 7. Return tokens
▼
┌──────────────┐
│ API Gateway │
└──────────────┘
│
│ 8. Set cookies & respond
│ { accessToken, user }
▼
┌──────────────┐
│ Browser │
│ Store JWT │
└──────────────┘
│
│ 9. Subsequent requests
│ Authorization: Bearer <token>
▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ API Gateway │────►│ Middleware │────►│ Protected │
│ │ │ Verify JWT │ │ Resources │
└──────────────┘ └──────────────┘ └──────────────┘
TOKEN REFRESH FLOW:
Access Token Expired
│
▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Browser │────►│ POST /auth/ │────►│ Redis │
│ Refresh Req │ │ refresh │ │ Validate │
└──────────────┘ └──────────────┘ └──────────────┘
│ │
│◄───────────────────┘
│ Valid? Issue new tokens
▼
┌──────────────┐
│ New Access │
│ Token │
└──────────────┘
```
## Explanation
This data flow diagram shows the complete authentication lifecycle:
1. **Initial login flow**: Steps 1-8 show credential validation and token generation
2. **Token storage**: Redis for refresh tokens, browser for access tokens
3. **Protected resource access**: JWT verification middleware
4. **Token refresh**: Separate flow for getting new access tokens
The nested structure within the Auth Service box shows internal processing details while maintaining flow clarity.
## Usage Suggestions
- Include in security documentation
- Add to API documentation for developers
- Reference during security audits
- Share with new team members during onboarding

93
skills/planning/ascii-diagram-creator/examples/phased-migration-diagram.md Normal file
View File

@@ -0,0 +1,93 @@
# Example: Phased Migration Diagram
## Scenario
A user asks: "Create a diagram showing our database migration phases with current progress."
## Generated Diagram
```
┌─────────────────────────────────────────────────────────────────────────┐
│ DATABASE MIGRATION: MONGODB TO POSTGRESQL │
│ Target: Q4 2025 Completion │
└─────────────────────────────────────────────────────────────────────────┘
PHASE 1: Schema Design & Setup ✓
┌─────────────────────────────────────────────────────────────────────────┐
│ Status: COMPLETE Duration: 2w │
├─────────────────────────────────────────────────────────────────────────┤
│ ✓ Analyze MongoDB collections and relationships │
│ ✓ Design PostgreSQL schema with proper normalization │
│ ✓ Create migration scripts and rollback procedures │
│ ✓ Set up staging environment with both databases │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
PHASE 2: Dual-Write Implementation ✓
┌─────────────────────────────────────────────────────────────────────────┐
│ Status: COMPLETE Duration: 3w │
├─────────────────────────────────────────────────────────────────────────┤
│ ✓ Implement write-through to both MongoDB and PostgreSQL │
│ ✓ Add feature flags for gradual rollout │
│ ✓ Deploy to staging and validate data consistency │
│ ✓ Monitor for performance impact (< 50ms added latency) │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
PHASE 3: Historical Data Migration ⏳
┌─────────────────────────────────────────────────────────────────────────┐
│ Status: IN PROGRESS (60%) Duration: 4w │
├─────────────────────────────────────────────────────────────────────────┤
│ ✓ Migrate users collection (2.3M records) │
│ ✓ Migrate products collection (150K records) │
│ ⏳ Migrate orders collection (5.2M records) - 60% complete │
│ Migrate reviews collection (890K records) │
│ Validate data integrity across all tables │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
PHASE 4: Read Path Migration
┌─────────────────────────────────────────────────────────────────────────┐
│ Status: PENDING Duration: 2w │
├─────────────────────────────────────────────────────────────────────────┤
│ Switch read operations to PostgreSQL (feature flag) │
│ Run parallel queries and compare results │
│ Gradually increase PostgreSQL read traffic (10% → 100%) │
│ Monitor query performance and optimize indexes │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
PHASE 5: Cutover & Cleanup
┌─────────────────────────────────────────────────────────────────────────┐
│ Status: PENDING Duration: 1w │
├─────────────────────────────────────────────────────────────────────────┤
│ Disable MongoDB writes │
│ Update all application configuration │
│ Archive MongoDB data │
│ Remove dual-write code and feature flags │
│ Document lessons learned │
└─────────────────────────────────────────────────────────────────────────┘
Summary: Phase 3 of 5 │ Overall Progress: ~55% │ On Track for Q4
Legend:
✓ = Complete ⏳ = In Progress (blank) = Pending
```
## Explanation
This phased migration diagram provides:
- **Clear progress visibility**: Status and completion percentage per phase
- **Detailed tasks**: Specific actions within each phase
- **Time estimates**: Duration for planning purposes
- **Overall summary**: Quick status check at the bottom
The vertical flow shows dependencies between phases while the detailed boxes provide actionable information.
## Usage Suggestions
- Include in weekly status updates
- Add to project management tools
- Share with stakeholders for progress visibility
- Update after each milestone completion

189
skills/planning/ascii-diagram-creator/reference/best-practices.md Normal file
View File

@@ -0,0 +1,189 @@
# Best Practices
Guidelines for creating clear, effective ASCII diagrams.
## Formatting Rules
### Width Constraints
**Maximum line width: 80 characters**
This ensures compatibility with:
- Terminal windows
- Code review tools
- Markdown rendering
- Email clients
```
# Good - fits in 80 chars
┌──────────────────────────────────────────────────────────────────────────┐
# Bad - exceeds 80 chars, will wrap
┌────────────────────────────────────────────────────────────────────────────────────┐
```
### Alignment
**Vertical alignment** creates visual hierarchy:
```
# Good - aligned centers
┌─────────┐
│ Step 1 │
└─────────┘
│
▼
┌─────────┐
│ Step 2 │
└─────────┘
# Bad - misaligned
┌─────────┐
│ Step 1 │
└─────────┘
│
▼
┌─────────┐
│ Step 2 │
└─────────┘
```
**Horizontal alignment** for side-by-side comparisons:
```
# Good - columns aligned
BEFORE: AFTER:
├── file1.js ──► ├── file1.ts
└── file2.js ──► └── file2.ts
# Bad - uneven columns
BEFORE: AFTER:
├── file1.js ──► ├── file1.ts
└── file2.js ──► └── file2.ts
```
### Spacing
Use blank lines to separate logical sections:
```
┌─────────────────────────────────────────────┐
│ MIGRATION PLAN │
└─────────────────────────────────────────────┘
PHASE 1: Analysis
┌──────────────────┐
│ Analyze current │
└──────────────────┘
PHASE 2: Migration
┌──────────────────┐
│ Execute changes │
└──────────────────┘
```
## Clarity Guidelines
### Use Consistent Box Sizes
Keep related boxes the same width:
```
# Good - consistent widths
┌──────────────────┐ ┌──────────────────┐
│ Component A │ │ Component B │
└──────────────────┘ └──────────────────┘
# Bad - inconsistent
┌────────┐ ┌────────────────────────┐
│ Comp A │ │ Component B │
└────────┘ └────────────────────────┘
```
### Include Legends
When using symbols, explain them:
```
┌──────────────────┐
│ ✓ Database │
│ ⏳ API │
│ ✗ Legacy │
└──────────────────┘
Legend:
✓ = Complete
⏳ = In Progress
✗ = Removed
```
### Group Related Items
Use visual proximity to show relationships:
```
┌─────────────────────────────────────────┐
│ FRONTEND LAYER │
├─────────────────────────────────────────┤
│ • React Components │
│ • State Management │
│ • Routing │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ BACKEND LAYER │
├─────────────────────────────────────────┤
│ • API Endpoints │
│ • Business Logic │
│ • Database Access │
└─────────────────────────────────────────┘
```
## Information Density
### Include Status Indicators
Show progress at a glance:
```
│ ✓ Step 1: Setup │
│ ✓ Step 2: Configuration │
│ ⏳ Step 3: Migration │
│ Step 4: Validation │
```
### Show Counts When Relevant
Provide context with numbers:
```
┌──────────────────┐
│ Current State │
│ 11 directories │
│ 47 files │
│ 3 duplicates │
└──────────────────┘
```
### Add Brief Descriptions
Clarify purpose without cluttering:
```
┌──────────────────┐
│ Auth Service │──► Handles JWT tokens
│ 3 endpoints │──► Login, logout, refresh
└──────────────────┘
```
## Common Mistakes to Avoid
| Mistake | Problem | Solution |
|---------|---------|----------|
| Exceeding 80 chars | Wrapping breaks diagram | Split or abbreviate |
| No legend | Symbols are confusing | Always include legend |
| Inconsistent boxes | Looks unprofessional | Standardize widths |
| Too much detail | Overwhelming | Simplify or split |
| No spacing | Hard to read | Add blank lines |
| Misaligned arrows | Confusing flow | Check alignment |

237
skills/planning/ascii-diagram-creator/reference/diagram-types.md Normal file
View File

@@ -0,0 +1,237 @@
# Diagram Type Templates
Ready-to-use templates for each diagram type.
## 1. Architecture Diagram
**Purpose**: Show system components and their relationships.
### Basic Template
```
┌─────────────────────────────────┐
│ COMPONENT NAME │
├─────────────────────────────────┤
│ • Feature 1 │
│ • Feature 2 │
│ • Feature 3 │
└─────────────────────────────────┘
│
▼
┌─────────────────────────────────┐
│ CONNECTED COMPONENT │
└─────────────────────────────────┘
```
### Multi-Component Template
```
┌───────────────┐ ┌───────────────┐
│ Frontend │ │ Backend │
├───────────────┤ ├───────────────┤
│ • React │────►│ • Node.js │
│ • Redux │ │ • Express │
└───────────────┘ └───────────────┘
│
▼
┌───────────────┐
│ Database │
├───────────────┤
│ • PostgreSQL │
└───────────────┘
```
### When to Use
- Documenting service architecture
- Explaining module relationships
- Showing system overview
- Onboarding new team members
---
## 2. Before/After Diagram
**Purpose**: Compare current vs proposed state.
### Basic Template
```
BEFORE: AFTER:
old/structure/ ──► new/structure/
├── file1 KEPT ├── file1
├── file2 MOVED ├── relocated/
│ │ └── file2
└── file3 DELETED
```
### With Status Indicators
```
CURRENT STATE: TARGET STATE:
src/ src/
├── components/ ✓ ├── components/
│ ├── old.js ──► │ └── new.tsx
│ └── legacy.js ✗ ├── features/
├── utils/ 🔄 │ └── auth/
│ └── helpers.js ──► └── shared/
└── tests/ ✓ └── utils/
```
### File Transformation
```
BEFORE: AFTER:
src/ src/
├── Button.js ──► ├── Button.tsx ✓
├── Button.css ──► │ (styles included)
├── Form.js ──► ├── Form.tsx ✓
├── Form.css ──► │ (styles included)
└── utils.js ──► └── utils.ts ✓
Legend: ✓ = TypeScript conversion complete
```
### When to Use
- Planning directory restructuring
- Showing migration scope
- Documenting refactoring changes
- Creating PR descriptions
---
## 3. Phased Migration Diagram
**Purpose**: Show step-by-step progression with status.
### Basic Template
```
┌────────────────────────────────┐
│ PHASE 1: Description │
│ Status: COMPLETE ✓ │
│ Action: Specific task │
└────────────────────────────────┘
│
▼
┌────────────────────────────────┐
│ PHASE 2: Description │
│ Status: IN PROGRESS ⏳ │
│ Action: Specific task │
└────────────────────────────────┘
│
▼
┌────────────────────────────────┐
│ PHASE 3: Description │
│ Status: PENDING │
│ Action: Specific task │
└────────────────────────────────┘
```
### Detailed Migration Plan
```
┌─────────────────────────────────────────────────────────┐
│ SYSTEM CONSOLIDATION PLAN │
└─────────────────────────────────────────────────────────┘
PHASE 1: Analysis ✓
┌──────────────────┐
│ Current State │──► Identify duplicates
│ 11 directories │──► Find dependencies
│ 3 systems │──► Check references
└──────────────────┘
│
▼
PHASE 2: Migration ⏳
┌──────────────────┐
│ Moving Data │
│ ✓ Memory files │
│ ✓ Pattern files │
│ ⏳ Script updates │
└──────────────────┘
│
▼
PHASE 3: Validation
┌──────────────────┐
│ Final State │
│ 2 directories │──► All tests passing
│ 1 unified system │──► No duplicates
└──────────────────┘
```
### When to Use
- Tracking multi-phase projects
- Showing progress through stages
- Planning sequential changes
- Sprint/milestone planning
---
## 4. Data Flow Diagram
**Purpose**: Illustrate how data moves through the system.
### Basic Template
```
Input ──► Process ──► Output
▲ │ │
│ ▼ ▼
Feedback Storage Display
```
### API Request Flow
```
┌────────┐ ┌────────────┐ ┌──────────┐
│ Client │────►│ API Gateway│────►│ Service │
└────────┘ └────────────┘ └──────────┘
▲ │
│ ▼
│ ┌──────────┐
└────────────────────────────│ Database │
Response with data └──────────┘
```
### Authentication Flow
```
User Input
│
▼
┌──────────────┐
│ Login Form │
└──────────────┘
│
▼
┌──────────────┐ ┌──────────────┐
│ Auth Service │────►│ Token Store │
└──────────────┘ └──────────────┘
│ │
▼ │
┌──────────────┐ │
│ JWT Token │◄───────────┘
└──────────────┘
│
▼
Protected Resources
```
### Data Pipeline
```
Raw Data ──► Validate ──► Transform ──► Store ──► Display
│ │ │
▼ ▼ ▼
Errors Logs Analytics
```
### When to Use
- Explaining API request/response flow
- Documenting data pipelines
- Showing processing steps
- Illustrating system integrations

233
skills/planning/ascii-diagram-creator/reference/mermaid-export.md Normal file
View File

@@ -0,0 +1,233 @@
# Mermaid Export Guide
Convert ASCII diagrams to Mermaid syntax for graphical rendering in GitHub, GitLab, Notion, and other platforms that support Mermaid.
## When to Use Mermaid Export
- Documentation that will be viewed in GitHub/GitLab (renders automatically)
- Presentations where graphical output is preferred
- Teams that prefer visual diagrams over text-based
- When you need to iterate on diagrams in a visual editor
## Conversion Rules
### Basic Elements
| ASCII Element | Mermaid Syntax | Example |
|---------------|----------------|---------|
| `┌─────┐` Box | `[Label]` | `A[Component]` |
| `(( ))` Circle | `((Label))` | `A((Start))` |
| `{ }` Diamond | `{Label}` | `A{Decision}` |
| `──►` Arrow | `-->` | `A --> B` |
| `◄──` Reverse | `<--` | `A <-- B` |
| `◄─►` Bidirectional | `<-->` | `A <--> B` |
| `──✗` Blocked | `-.-x` | `A -.-x B` |
| Text on arrow | `-- text -->` | `A -- calls --> B` |
### Container Elements
| ASCII Pattern | Mermaid Equivalent |
|--------------|-------------------|
| Nested boxes | `subgraph` |
| Grouped components | `subgraph "Name"` |
| Layers | Multiple subgraphs |
### Status Indicators
Use Mermaid classes for status styling:
```mermaid
graph TD
A[Complete]:::done
B[In Progress]:::pending
C[Blocked]:::blocked
classDef done fill:#90EE90
classDef pending fill:#FFE4B5
classDef blocked fill:#FFB6C1
```
---
## Conversion Examples
### Architecture Diagram
**ASCII Input**:
```
┌─────────────────────────────────────────────────────────────┐
│ APPLICATION ARCHITECTURE │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ app/ │ │ features/ │ │ shared/ │ │
│ │ (routes) │────►│ (domains) │────►│ (common) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
**Mermaid Output**:
```mermaid
graph LR
subgraph "Application Architecture"
A[app/<br/>routes] --> B[features/<br/>domains]
B --> C[shared/<br/>common]
end
```
### Before/After Diagram
**ASCII Input**:
```
BEFORE AFTER
┌──────────────┐ ┌──────────────┐
│ Monolith │ │ Service A │
│ All-in-one │ ──► ├──────────────┤
│ │ │ Service B │
└──────────────┘ └──────────────┘
```
**Mermaid Output**:
```mermaid
graph LR
subgraph Before
A[Monolith<br/>All-in-one]
end
subgraph After
B[Service A]
C[Service B]
end
A -.-> B
A -.-> C
```
### Phased Migration Diagram
**ASCII Input**:
```
PHASE 1: Analysis PHASE 2: Migration PHASE 3: Validation
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ ✓ Complete │───────►│ ⏳ In Progress│────────►│ ○ Pending │
└──────────────┘ └──────────────┘ └──────────────┘
```
**Mermaid Output**:
```mermaid
graph LR
A[Phase 1<br/>Analysis]:::done --> B[Phase 2<br/>Migration]:::pending
B --> C[Phase 3<br/>Validation]:::future
classDef done fill:#90EE90,stroke:#228B22
classDef pending fill:#FFE4B5,stroke:#FF8C00
classDef future fill:#E0E0E0,stroke:#808080
```
### Data Flow Diagram
**ASCII Input**:
```
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ User │────►│ API │────►│ Service │────►│ DB │
└─────────┘ └─────────┘ └─────────┘ └─────────┘
▲ │
└──────────────────────────────────────────────┘
```
**Mermaid Output**:
```mermaid
graph LR
A[User] --> B[API]
B --> C[Service]
C --> D[DB]
D --> A
```
---
## Direction Options
Choose the flow direction based on diagram type:
| Direction | Syntax | Best For |
|-----------|--------|----------|
| Left to Right | `graph LR` | Data flows, pipelines |
| Top to Bottom | `graph TD` | Hierarchies, architecture |
| Bottom to Top | `graph BT` | Bottom-up structures |
| Right to Left | `graph RL` | Reverse flows |
---
## Advanced Features
### Subgraph Nesting
```mermaid
graph TD
subgraph "Frontend"
subgraph "Components"
A[Button]
B[Form]
end
subgraph "Pages"
C[Home]
D[Dashboard]
end
end
C --> A
D --> B
```
### Click Events (for interactive diagrams)
```mermaid
graph TD
A[Component]
click A "https://github.com/repo/component" "View source"
```
### Notes and Comments
```mermaid
graph TD
A[Start] --> B[Process]
B --> C[End]
%% This is a comment
%% Comments don't render
```
---
## Platform Support
| Platform | Support | Notes |
|----------|---------|-------|
| GitHub | ✓ Native | Renders in markdown files and issues |
| GitLab | ✓ Native | Renders in markdown |
| Notion | ✓ Native | Use `/mermaid` block |
| VS Code | ✓ Extension | Mermaid Preview extension |
| Obsidian | ✓ Native | Built-in support |
| Confluence | ⚠️ Plugin | Requires Mermaid plugin |
---
## Conversion Tips
1. **Keep it simple**: ASCII diagrams with many nested elements may not convert cleanly
2. **Use subgraphs sparingly**: More than 2-3 levels of nesting gets hard to read
3. **Add line breaks**: Use `<br/>` in node labels for multi-line text
4. **Test rendering**: Preview in GitHub/GitLab before committing
5. **Preserve ASCII version**: Keep both formats for different use cases
---
## Quick Conversion Checklist
- [ ] Identify all boxes → Convert to nodes `[Label]`
- [ ] Identify all arrows → Convert to connections `-->`
- [ ] Identify groupings → Convert to `subgraph`
- [ ] Identify status indicators → Add `classDef` styles
- [ ] Choose direction (`LR` vs `TD`)
- [ ] Test rendering in target platform

237
skills/planning/ascii-diagram-creator/reference/project-templates.md Normal file
View File

@@ -0,0 +1,237 @@
# Project-Type Templates
Pre-built architecture diagram templates for common project types. Use these as starting points after auto-discovery detects the project type.
## Template Selection
| Project Type | Detection Signals | Template |
|--------------|-------------------|----------|
| Bulletproof React | `src/features/*`, eslint-plugin-import | [bulletproof-react](#bulletproof-react) |
| Next.js App Router | `src/app/**/page.tsx`, next.config.* | [next-app-router](#nextjs-app-router) |
| Express API | express in deps, `routes/*` or `controllers/*` | [express-api](#express-api) |
| Monorepo (Nx/Turborepo) | `packages/*` or `apps/*`, workspace config | [monorepo](#monorepo) |
| Generic Full-Stack | Mixed patterns | [generic-fullstack](#generic-full-stack) |
---
## Bulletproof React
**Detection**: `src/features/*/index.{ts,tsx}` + eslint-plugin-import
```
┌─────────────────────────────────────────────────────────────────┐
│ APPLICATION ARCHITECTURE │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ app/ │ │ features/ │ │ shared/ │ │
│ │ (routes) │────►│ (domains) │────►│ (common) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ routes/ │ │ components/ │ │ lib/ │ │
│ │ layouts/ │ │ hooks/ │ │ types/ │ │
│ │ │ │ api/ │ │ utils/ │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
├─────────────────────────────────────────────────────────────────┤
│ Import Rules: app → features → shared (unidirectional) │
└─────────────────────────────────────────────────────────────────┘
```
**Populate with**:
- Features from `glob: src/features/*/index.ts`
- Routes from `glob: src/app/**`
- Cross-feature deps from `grep: import.*from '@/features`
---
## Next.js App Router
**Detection**: `app/**/page.tsx` + `next.config.*`
```
┌─────────────────────────────────────────────────────────────────┐
│ NEXT.JS APP STRUCTURE │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ app/ │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ layout │ │ page │ │ loading │ │ error │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │
│ │ │ │ │ │
│ │ ▼ ▼ │ │
│ │ ┌─────────────────────────────────────────────┐ │ │
│ │ │ Route Groups │ │ │
│ │ │ (auth)/ (dashboard)/ (public)/ │ │ │
│ │ └─────────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ components/ │ │ lib/ │ │ types/ │ │
│ │ (UI) │ │ (server) │ │ (shared) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
```
**Populate with**:
- Route groups from `glob: src/app/(*)/`
- Dynamic routes from `glob: src/app/**/[*]`
- Server actions from `grep: "use server"`
---
## Express API
**Detection**: `express` in dependencies + `routes/*` or `controllers/*`
```
┌─────────────────────────────────────────────────────────────────┐
│ EXPRESS API LAYERS │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Request ──► ┌──────────────────────────────────┐ │
│ │ Middleware Layer │ │
│ │ auth │ validation │ rate-limit │ │
│ └──────────────┬───────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────┐ │
│ │ Routes Layer │ │
│ │ /api/users │ /api/products │ │
│ └──────────────┬───────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────┐ │
│ │ Controllers Layer │ │
│ │ userController │ productCtrl │ │
│ └──────────────┬───────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────┐ │
│ │ Services Layer │ │
│ │ userService │ productService │ │
│ └──────────────┬───────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────┐ │
│ │ Data Layer │ │
│ │ models │ repositories │ db │ │
│ └──────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
```
**Populate with**:
- Routes from `glob: routes/*.js` or `grep: router\.(get|post|put|delete)`
- Controllers from `glob: controllers/*.js`
- Models from `glob: models/*.js`
---
## Monorepo
**Detection**: `packages/*` or `apps/*` + workspace config (nx.json, turbo.json, pnpm-workspace.yaml)
```
┌─────────────────────────────────────────────────────────────────┐
│ MONOREPO STRUCTURE │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ apps/ │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ web │ │ admin │ │ api │ │ │
│ │ └────┬────┘ └────┬────┘ └────┬────┘ │ │
│ └────────┼─────────────┼────────────┼──────────────────┘ │
│ │ │ │ │
│ └─────────────┼────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ packages/ │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ ui │ │ utils │ │ types │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ config │ │ api │ │ eslint │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
├─────────────────────────────────────────────────────────────────┤
│ Dependency Flow: apps → packages (unidirectional) │
└─────────────────────────────────────────────────────────────────┘
```
**Populate with**:
- Apps from `glob: apps/*/package.json`
- Packages from `glob: packages/*/package.json`
- Internal deps from each package.json dependencies
---
## Generic Full-Stack
**Detection**: Mixed patterns or undetected project type
```
┌─────────────────────────────────────────────────────────────────┐
│ FULL-STACK APPLICATION │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ Frontend │ │ Backend │ │
│ │ ┌───────────┐ │ │ ┌───────────┐ │ │
│ │ │ UI │ │ │ │ API │ │ │
│ │ │Components │ │ ──► │ │ Routes │ │ │
│ │ └───────────┘ │ │ └───────────┘ │ │
│ │ ┌───────────┐ │ │ ┌───────────┐ │ │
│ │ │ State │ │ │ │ Services │ │ │
│ │ │Management │ │ │ │ Business │ │ │
│ │ └───────────┘ │ │ └───────────┘ │ │
│ │ ┌───────────┐ │ │ ┌───────────┐ │ │
│ │ │ API │ │ │ │ Data │ │ │
│ │ │ Client │ │ │ │ Layer │ │ │
│ │ └───────────┘ │ │ └───────────┘ │ │
│ └─────────────────────┘ └─────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────┐ │
│ │ Database │ │
│ └─────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
```
**Populate with**:
- Manual discovery based on directory structure
- `ls src/` or `tree -L 2` for structure overview
---
## Usage Instructions
1. **Auto-detect project type** using Phase 0 discovery commands
2. **Select matching template** from this reference
3. **Run populate commands** to fill in actual component names
4. **Customize** by adding/removing boxes based on actual architecture
5. **Add diagram metadata** for versioning (see below)
### Adding Diagram Metadata
Include this comment block at the top of generated diagrams:
```markdown
<!-- diagram-meta
type: [template-name]
created: YYYY-MM-DD
last-verified: YYYY-MM-DD
source-patterns: [glob patterns used]
stale-after: 30d
-->
```
This enables automated staleness detection when the codebase structure changes.

162
skills/planning/ascii-diagram-creator/reference/visual-elements.md Normal file
View File

@@ -0,0 +1,162 @@
# Visual Elements Reference
Complete reference for all ASCII diagram visual elements.
## Box Drawing Characters
### Basic Box
```
┌─────────────────┐
│ Content │
└─────────────────┘
```
### Box with Header
```
┌─────────────────┐
│ HEADER │
├─────────────────┤
│ Content │
└─────────────────┘
```
### Box with Multiple Sections
```
┌─────────────────┐
│ Section 1 │
├─────────────────┤
│ Section 2 │
├─────────────────┤
│ Section 3 │
└─────────────────┘
```
### Character Reference
| Character | Name | Usage |
|-----------|------|-------|
| `┌` | Top-left corner | Start of box |
| `┐` | Top-right corner | End of top border |
| `└` | Bottom-left corner | Start of bottom border |
| `┘` | Bottom-right corner | End of box |
| `─` | Horizontal line | Top/bottom borders |
| `│` | Vertical line | Side borders |
| `├` | Left T-junction | Left side divider |
| `┤` | Right T-junction | Right side divider |
| `┬` | Top T-junction | Top divider |
| `┴` | Bottom T-junction | Bottom divider |
| `┼` | Cross junction | Grid intersection |
## Arrows
### Directional Arrows
| Arrow | Name | Meaning |
|-------|------|---------|
| `──►` | Right arrow | Forward flow, transformation |
| `◄──` | Left arrow | Reverse flow, feedback |
| `◄─►` | Bidirectional | Two-way communication |
| `│` + `▼` | Down arrow | Vertical flow downward |
| `│` + `▲` | Up arrow | Vertical flow upward |
### Status Arrows
| Arrow | Meaning | Example Use |
|-------|---------|-------------|
| `──✓` | Approved/kept | Retained items in migration |
| `──✗` | Blocked/removed | Deleted items |
### Creating Vertical Flow
```
┌─────────┐
│ Step 1 │
└─────────┘
│
▼
┌─────────┐
│ Step 2 │
└─────────┘
```
## Status Indicators
### Progress Symbols
| Symbol | Meaning | When to Use |
|--------|---------|-------------|
| `✓` | Complete/done | Finished tasks, kept items |
| `✗` | Removed/failed | Deleted items, blocked tasks |
| `⏳` | In progress | Currently active work |
| `🔄` | Migrated/moved | Relocated items |
### Alert Symbols
| Symbol | Meaning | When to Use |
|--------|---------|-------------|
| `⚠️` | Warning | Needs attention |
| `🔴` | Critical | Urgent issue |
### Using Status in Diagrams
```
┌──────────────────┐
│ Migration Status │
├──────────────────┤
│ ✓ Database │
│ ✓ API endpoints │
│ ⏳ Frontend │
│ ✗ Legacy cleanup │
└──────────────────┘
```
## Tree Structures
### Directory Tree
```
project/
├── src/
│ ├── components/
│ │ ├── Button.tsx
│ │ └── Form.tsx
│ └── utils/
│ └── helpers.ts
└── tests/
└── unit/
```
### Tree Characters
| Character | Usage |
|-----------|-------|
| `├──` | Branch with more siblings below |
| `└──` | Last branch (no more siblings) |
| `│` | Vertical continuation |
## Combining Elements
### Architecture with Status
```
┌─────────────────────┐
│ API Gateway ✓ │
└─────────────────────┘
│
▼
┌─────────────────────┐
│ Auth Service ⏳ │
└─────────────────────┘
```
### Before/After with Arrows
```
BEFORE: AFTER:
├── old.js ──► ├── new.ts ✓
├── temp.js ──✗ └── utils.ts ✓
└── legacy.js ──✗
```

102
skills/planning/ascii-diagram-creator/workflow/phase-0-context-analysis.md Normal file
View File

@@ -0,0 +1,102 @@
# Phase 0: Context Analysis
**Purpose**: Understand what the user wants to visualize and gather necessary information to create an effective diagram.
**Execute immediately when skill activates.**
## 1. Auto-Discovery Mode (NEW)
**Run these discovery steps automatically** to reduce manual exploration:
### Project Type Detection
Execute in parallel to detect project architecture:
```bash
# React/Frontend detection
glob: "src/features/**" OR "src/app/**" OR "pages/**"
# Package detection
read: package.json → extract dependencies, scripts
# Config file detection
glob: "{next,vite,webpack}.config.*" OR "tsconfig.json"
```
### Architecture Scanning
```bash
# Feature boundaries (Bulletproof React)
glob: "src/features/*/index.{ts,tsx}"
# Route structure
glob: "src/app/**/page.{ts,tsx}" OR "pages/**/*.{ts,tsx}"
# API layer
grep: "export.*function.*fetch|api|query" --type ts
# Cross-feature dependencies
grep: "import.*from '@/features" OR "from '../features"
```
### Output Summary
After auto-discovery, report:
```
Project Type: [bulletproof-react | next-app-router | express-api | monorepo | generic]
Features Found: [list of feature directories]
Routes Found: [list of route patterns]
Key Dependencies: [from package.json]
Architecture Pattern: [detected pattern]
```
This auto-discovery reduces 50% of manual codebase exploration.
---
## 2. Identify Visualization Target
Determine what needs to be diagrammed:
- **System architecture**: Components, modules, services
- **File/directory structure**: Current or proposed organization
- **Process flow**: Steps, phases, stages
- **Data movement**: Input, processing, output
## 3. Extract Key Information
From the user's request or **auto-discovery results**:
- Component names and relationships
- Current vs desired state (for migrations)
- Number of phases/steps (for phased diagrams)
- Data sources and destinations (for flow diagrams)
## 4. Assess Complexity
Evaluate scope to determine diagram approach:
| Complexity | Characteristics | Approach |
|------------|-----------------|----------|
| Simple | 2-4 components, linear flow | Single compact diagram |
| Medium | 5-10 components, some branches | Standard diagram with sections |
| Complex | 10+ components, multiple flows | Multiple diagrams or layered view |
## Output
Context summary ready for diagram type selection:
- **What**: Clear description of visualization target
- **Scope**: Number of components/phases
- **Purpose**: How the diagram will be used (PR, docs, presentation)
- **Constraints**: Any specific requirements (width, detail level)
## Common Issues
**Vague requests**: Ask for clarification
- "What specifically would you like to see in the diagram?"
- "Should this show the current state, proposed state, or both?"
**Missing information**: Gather from codebase if possible
- Run `ls` or `tree` for directory structures
- Check existing docs for architecture info

71
skills/planning/ascii-diagram-creator/workflow/phase-1-diagram-selection.md Normal file
View File

@@ -0,0 +1,71 @@
# Phase 1: Diagram Type Selection
**Purpose**: Choose the most appropriate diagram type based on context analysis.
## Decision Matrix
| User Wants To... | Diagram Type | Key Indicator |
|------------------|--------------|---------------|
| Show how things connect | Architecture | "components", "modules", "relationships" |
| Compare states | Before/After | "current vs", "migration", "restructuring" |
| Show progression | Phased Migration | "phases", "steps", "stages", "timeline" |
| Explain movement | Data Flow | "flow", "pipeline", "process", "how data" |
## 1. Architecture Diagram
**Best for**: System components and their relationships
**Use when**:
- Explaining how modules connect
- Documenting service architecture
- Showing dependencies between components
**Example context**: "Show how our auth module connects to the database"
## 2. Before/After Diagram
**Best for**: Comparing current vs proposed state
**Use when**:
- Planning directory restructuring
- Showing migration changes
- Documenting refactoring scope
**Example context**: "Show the file structure before and after cleanup"
## 3. Phased Migration Diagram
**Best for**: Step-by-step progression with status
**Use when**:
- Tracking multi-phase projects
- Showing progress through stages
- Planning sequential changes
**Example context**: "Diagram our three-phase migration plan"
## 4. Data Flow Diagram
**Best for**: How data moves through the system
**Use when**:
- Explaining API request/response flow
- Documenting data pipelines
- Showing processing steps
**Example context**: "Illustrate how user data flows from signup to storage"
## Output
Selected diagram type with rationale:
- **Type**: Which of the four diagram types
- **Rationale**: Why this type fits best
- **Key elements**: Main components to include
- **Optional elements**: Status indicators, legends, etc.
## Hybrid Approaches
Sometimes multiple types work. Consider:
- **Architecture + Status**: Show components with progress indicators
- **Before/After + Phases**: Show transformation in stages
- **Data Flow + Architecture**: Show data movement between components

106
skills/planning/ascii-diagram-creator/workflow/phase-2-generation.md Normal file
View File

@@ -0,0 +1,106 @@
# Phase 2: Diagram Generation
**Purpose**: Create the ASCII diagram using proper visual elements and formatting.
## 1. Apply Formatting Rules
Before generating, ensure compliance:
- **Maximum width**: 80 characters
- **Box alignment**: Vertical centers aligned
- **Spacing**: Clear separation between sections
- **Legends**: Include when using status indicators
## 2. Select Visual Elements
### Box Drawing Characters
```
┌─────────────────┐ Top border
│ Content │ Side borders with padding
├─────────────────┤ Section divider
│ More content │
└─────────────────┘ Bottom border
```
### Arrow Types
| Arrow | Meaning | Usage |
|-------|---------|-------|
| `──►` | Transformation/flow | Data movement, process flow |
| `◄──` | Reverse flow | Feedback loops |
| `◄─►` | Bidirectional | Two-way communication |
| `──✓` | Approved/kept | Retained items |
| `──✗` | Removed/blocked | Deleted items |
### Status Indicators
| Symbol | Meaning |
|--------|---------|
| `✓` | Complete/kept |
| `✗` | Removed/deleted |
| `⏳` | In progress |
| `🔄` | Migrated/moved |
| `⚠️` | Warning |
| `🔴` | Critical |
## 3. Generate Diagram
Follow the template for the selected type:
### Architecture Template
```
┌─────────────────────────────────┐
│ COMPONENT NAME │
├─────────────────────────────────┤
│ • Feature 1 │
│ • Feature 2 │
└─────────────────────────────────┘
│
▼
[Connected Component]
```
### Before/After Template
```
BEFORE: AFTER:
old/structure/ ──► new/structure/
├── file1 KEPT ├── file1
├── file2 MOVED └── newfile
└── file3 DELETED
```
### Phased Migration Template
```
┌────────────────────────────────┐
│ PHASE 1: Description │
│ Status: IN PROGRESS │
│ Action: Specific task │
└────────────────────────────────┘
│
▼
[Next Phase]
```
### Data Flow Template
```
Input ──► Process ──► Output
▲ │ │
│ ▼ ▼
Feedback Storage Display
```
## 4. Add Context
Include with the diagram:
- Brief explanation of what it shows
- Legend for any symbols used
- Suggested usage (PR, docs, README)
## Output
Complete ASCII diagram with:
- Proper formatting (80-char max)
- Appropriate visual elements
- Clear labels and structure
- Explanatory context

73
skills/planning/ascii-diagram-creator/workflow/phase-3-refinement.md Normal file
View File

@@ -0,0 +1,73 @@
# Phase 3: Iterative Refinement
**Purpose**: Adjust the diagram based on user feedback to achieve optimal clarity and usefulness.
## Common Refinement Requests
### Layout Adjustments
| Request | Action |
|---------|--------|
| "Make it wider" | Expand boxes to max 80 chars |
| "More compact" | Reduce padding, combine elements |
| "Add spacing" | Insert blank lines between sections |
| "Align boxes" | Ensure vertical/horizontal alignment |
### Content Changes
| Request | Action |
|---------|--------|
| "Add status indicators" | Include ✓, ✗, ⏳ symbols |
| "Show more detail" | Expand component descriptions |
| "Simplify" | Remove non-essential elements |
| "Add legend" | Include symbol definitions |
### Structural Changes
| Request | Action |
|---------|--------|
| "Split into phases" | Convert to phased migration type |
| "Show both states" | Switch to before/after format |
| "Focus on data flow" | Emphasize arrows and movement |
| "Add dependencies" | Include connecting arrows |
## Refinement Process
1. **Acknowledge request**: Confirm understanding of the change
2. **Make targeted edit**: Only modify what was requested
3. **Preserve context**: Keep existing good elements
4. **Present updated diagram**: Show the refined version
5. **Offer further refinement**: "Would you like any other adjustments?"
## Quality Checklist
Before finalizing, verify:
- [ ] **Width**: No line exceeds 80 characters
- [ ] **Alignment**: Boxes and arrows properly aligned
- [ ] **Clarity**: Labels are clear and descriptive
- [ ] **Completeness**: All requested elements included
- [ ] **Legend**: Symbols explained if used
- [ ] **Purpose**: Diagram serves stated goal
## Final Delivery
Provide the diagram with:
- **Usage suggestion**: Where to include (PR, docs, wiki)
- **Format note**: Copy-paste ready for markdown/terminal
- **Update reminder**: When to refresh the diagram
## Example Refinement Dialog
**User**: "Can you make the boxes wider and add status indicators?"
**Response**: Updated diagram with:
- Boxes expanded to full 80-character width
- Status indicators (✓, ⏳, ✗) added to each phase
- Legend included at bottom
```
[Updated diagram here]
```
Would you like any other adjustments?

237
skills/planning/ascii-diagram-creator/workflow/phase-4-output-integration.md Normal file
View File

@@ -0,0 +1,237 @@
# Phase 4: Output & Integration
**Purpose**: Provide multiple output formats and integrate diagrams into the user's workflow for maximum value.
**Execute after diagram refinement is complete.**
## 1. Output Format Options
After generating the ASCII diagram, offer these output options:
### ASCII (Default)
The standard terminal-compatible format already generated.
### Mermaid Export
Convert the ASCII diagram to Mermaid syntax for graphical rendering:
```javascript
// Example conversion for Architecture diagram
graph TD
subgraph "Application Layer"
A[app/routes] --> B[features/domains]
B --> C[shared/common]
end
subgraph "Feature Layer"
B --> D[components]
B --> E[hooks]
B --> F[api]
end
```
**Conversion rules**:
| ASCII Element | Mermaid Equivalent |
|---------------|-------------------|
| `┌─────┐` Box | `[Label]` node |
| `──►` Arrow | `-->` connection |
| `◄─►` Bidirectional | `<-->` connection |
| Nested boxes | `subgraph` |
| `✓` Status | `:::done` class |
| `⏳` Pending | `:::pending` class |
**Ask user**: "Would you like me to also generate a Mermaid version for graphical rendering?"
---
## 2. Git-Aware Staleness Detection
Check if existing diagrams in the project are stale based on git history:
### Detection Logic
```bash
# Find diagram files with metadata
grep -r "diagram-meta" docs/architecture/ --include="*.md" -l
# For each diagram, extract source-patterns and check git log
git log --since="30 days ago" --name-only -- "src/features/*"
```
### Staleness Report
```markdown
## Diagram Staleness Report
| Diagram | Last Verified | Source Changes | Status |
|---------|---------------|----------------|--------|
| `docs/architecture/auth-flow.md` | 2025-10-15 | 12 files changed | ⚠️ STALE |
| `docs/architecture/api-layer.md` | 2025-11-20 | 0 files changed | ✓ Current |
| `docs/architecture/features.md` | 2025-09-01 | 45 files changed | 🔴 OUTDATED |
### Recommended Actions
1. Re-verify `auth-flow.md` - auth module had significant changes
2. Update `features.md` - multiple new features added since last update
```
**Proactive check**: Run this detection when user asks about architecture or before major changes.
---
## 3. PR Template Integration
Automatically suggest or insert diagrams into PR descriptions:
### Detection
Check for existing PR templates:
```bash
# Common PR template locations
ls -la .github/PULL_REQUEST_TEMPLATE.md
ls -la .github/pull_request_template.md
ls -la docs/PULL_REQUEST_TEMPLATE.md
```
### Integration Options
**Option A: Suggest inclusion in PR body**
```markdown
## Architecture Impact
<!-- Generated by ascii-diagram-creator -->
```
[Insert generated diagram here]
```
This change affects the following components:
- Feature: auth
- Routes: /login, /logout, /refresh
```
**Option B: Auto-append to PR template**
If user agrees, add a section to their PR template:
```markdown
## Architecture Diagram (if applicable)
<!--
If this PR changes architecture, include a diagram:
- Use ascii-diagram-creator skill
- Show before/after for refactoring
- Show data flow for new features
-->
```
**Ask user**: "Would you like me to add this diagram to your PR description or update your PR template?"
---
## 4. CLAUDE.md Directive Setup
**IMPORTANT**: After completing the diagram, ask the user if they want to set up proactive diagram suggestions.
### Offer Prompt
> "Would you like me to add a directive to your CLAUDE.md so I proactively offer architecture diagrams when you're planning features, migrations, or refactoring?"
### If User Accepts
Add this directive to their project or global CLAUDE.md:
```markdown
## Proactive Skill Directives
### ASCII Diagram Creator
**Proactively offer architecture diagrams** when the user:
- Creates a feature branch (`feature/*`)
- Asks "how should I structure...", "what's the architecture for...", or "show me how X connects"
- Plans a migration, refactoring, or major restructuring
- Needs to communicate system changes in a PR description
- Mentions "visualize", "diagram", "show the flow", or "illustrate"
**Auto-trigger phrases**:
- "new feature", "planning", "architecture", "how should I structure"
- "before and after", "migration plan", "refactoring"
- "PR description", "explain to the team"
**Response pattern**:
1. Use auto-discovery to scan codebase (features, routes, dependencies)
2. Select appropriate template (Bulletproof React, Next.js, Express, Monorepo)
3. Generate diagram with versioning metadata
4. Offer Mermaid export and PR integration
5. Suggest placement: `docs/architecture/` or PR description
**Example proactive offer**:
> "I notice you're planning a new feature. Would you like me to create an architecture diagram showing the current system structure and where this feature will integrate? This can help with planning and serve as documentation in your PR."
```
### Placement Options
Ask user where to add the directive:
1. **Project CLAUDE.md** (`./CLAUDE.md`) - For project-specific behavior
2. **Global CLAUDE.md** (`~/.claude/CLAUDE.md`) - For all projects
**Implementation**:
```bash
# Check if directive already exists
grep -q "ASCII Diagram Creator" ~/.claude/CLAUDE.md && echo "Already configured"
# If not, append to file
cat >> ~/.claude/CLAUDE.md << 'EOF'
[directive content]
EOF
```
---
## 5. Output Summary
After completing all options, provide a summary:
```markdown
## Diagram Generation Complete
**Outputs Created**:
- ✓ ASCII diagram (80-char width, terminal-compatible)
- ✓ Mermaid export (for graphical rendering)
- ✓ Diagram metadata (staleness tracking enabled)
**Integration**:
- ✓ Added to PR description
- ✓ CLAUDE.md directive configured (global)
**Staleness Tracking**:
- Source patterns: `src/features/auth/*`, `src/app/routes/auth/*`
- Stale after: 30 days
- Next verification: 2025-12-23
**Recommended Location**:
Save to: `docs/architecture/auth-flow.md`
```
---
## Quick Reference
### User Prompts for This Phase
| User Says | Action |
|-----------|--------|
| "export to mermaid" | Generate Mermaid syntax |
| "check for stale diagrams" | Run staleness detection |
| "add to PR" | Insert in PR description |
| "set up auto-suggestions" | Configure CLAUDE.md directive |
| "save this diagram" | Write to docs/architecture/ |
### Output Format Decision Tree
```
Is user creating PR?
├─ Yes → Offer PR integration
└─ No → Is user planning feature?
├─ Yes → Offer CLAUDE.md directive
└─ No → Offer Mermaid export for docs
```