Initial commit

skills/planning/ascii-diagram-creator/workflow/phase-0-context-analysis.md

@@ -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

skills/planning/ascii-diagram-creator/workflow/phase-1-diagram-selection.md

@@ -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

skills/planning/ascii-diagram-creator/workflow/phase-2-generation.md

@@ -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

skills/planning/ascii-diagram-creator/workflow/phase-3-refinement.md

@@ -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?

skills/planning/ascii-diagram-creator/workflow/phase-4-output-integration.md

@@ -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
+```