docs: add comprehensive gameplan for Issue #147 explode-implode enhancement

Created detailed implementation strategy addressing:
- Directory organization preservation through multiple variants
- Manifest system for complete reversibility
- File extension conventions (.md, .mdd, .mdz, .mdt)
- Auto-detection algorithm for seamless operations
- Phased implementation approach with clear success criteria

Associated Issues Created:
- #148: Phase 1 - Core Infrastructure
- #149: Phase 2 - Variant Implementations
- #150: Phase 3 - Advanced Packaging Features
- #151: Phase 4 - Integration and Documentation
- #152: Manifest System Design
- #153: Auto-Detection Algorithm

Timeline: 8-12 weeks total implementation
Benefits: Preserves information, multiple organization patterns,
backward compatibility, extensible design

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

ISSUE_147_EXPLODE_IMPLODE_ENHANCEMENT_GAMEPLAN.md

@@ -0,0 +1,182 @@
+# Issue #147: Explode-Implode Enhancement Gameplan
+
+## Executive Summary
+
+This document outlines the comprehensive gameplan to enhance the explode-implode cycle in MarkiTect, addressing the need to preserve directory organization and provide multiple explosion variants while maintaining complete reversibility.
+
+## Problem Statement
+
+Current limitations of the explode-implode system:
+1. **Ordering Loss**: Chapter sequence not preserved during explode → implode cycle
+2. **No Directory Organization Options**: Only one explosion pattern supported
+3. **No Metadata Preservation**: Original structure context lost
+4. **Missing File Type Conventions**: No standardized extensions (.mdd, .mdz, .mdt)
+5. **No Auto-Detection**: Can't automatically determine explosion variant during implode
+
+## Solution Architecture
+
+### 1. Directory Organization Variants
+
+**Variant A: Current Flat Structure**
+```
+book.mdd/
+├── manifest.md          # NEW: Order preservation
+├── book_title/
+│   ├── index.md         # Main content
+│   ├── chapter_1.md
+│   └── chapter_2.md
+└── conclusion.md
+```
+
+**Variant B: Hierarchical Structure**
+```
+book.mdd/
+├── manifest.md
+├── 01_book_title/
+│   ├── index.md
+│   ├── 01_chapter_1/
+│   │   ├── index.md
+│   │   └── 01_section_1.md
+│   └── 02_chapter_2/
+└── 99_conclusion.md
+```
+
+**Variant C: Semantic Structure**
+```
+book.mdd/
+├── manifest.md
+├── parts/
+│   ├── 01_fundamentals/
+│   └── 02_advanced/
+├── chapters/
+│   ├── 01_basics/
+│   └── 02_intermediate/
+└── appendices/
+```
+
+### 2. Manifest System for Reversibility
+
+**manifest.md Structure:**
+```yaml
+---
+explosion_type: hierarchical_v1
+original_file: book.md
+created: 2025-10-12T19:30:00Z
+markitect_version: 0.1.0
+preservation:
+  front_matter: true
+  section_order: true
+  heading_levels: true
+structure:
+  - type: h1
+    title: "Book Title"
+    path: "01_book_title/index.md"
+    order: 1
+  - type: h2
+    title: "Chapter 1: Basics"
+    path: "01_book_title/01_chapter_1/index.md"
+    parent: "Book Title"
+    order: 2
+---
+
+# Explosion Manifest
+
+This directory was created by exploding `book.md` using the hierarchical structure variant.
+```
+
+### 3. File Extension Conventions
+
+- **.md** - Standard markdown file
+- **.mdd** - Markdown Directory (exploded markdown structure)
+- **.mdz** - Markdown Zip (compressed .mdd with manifest)
+- **.mdt** - Markdown Transcluded (zip with all referenced resources)
+
+### 4. Enhanced Command Interface
+
+```bash
+# Explode with variants
+markitect md-explode book.md --variant=flat          # Current behavior
+markitect md-explode book.md --variant=hierarchical  # Numbered structure
+markitect md-explode book.md --variant=semantic      # Semantic grouping
+
+# Auto-detect and implode
+markitect md-implode book.mdd/                       # Auto-detects variant
+markitect md-implode book.mdd/ --force-variant=flat  # Override detection
+
+# Package operations
+markitect md-package book.mdd/ book.mdz              # Create zip
+markitect md-package book.mdd/ book.mdt --transclude # Include resources
+```
+
+### 5. Auto-Detection Algorithm
+
+1. **Check for manifest.md** - Primary detection method
+2. **Directory naming patterns** - Numbered prefixes → hierarchical
+3. **Semantic directory names** - parts/, chapters/ → semantic
+4. **Fallback to current** - No pattern → flat structure
+
+## Implementation Strategy
+
+### Phase 1: Core Infrastructure
+1. Create `ExplodeVariant` enum and base classes
+2. Implement `ManifestManager` for manifest creation/parsing
+3. Add variant detection logic
+4. Update command interface with `--variant` parameter
+
+### Phase 2: Variant Implementations
+1. Refactor current logic into `FlatVariant` class
+2. Implement `HierarchicalVariant` with numbered structure
+3. Implement `SemanticVariant` with content-based grouping
+4. Add comprehensive tests for each variant
+
+### Phase 3: Advanced Features
+1. Implement `.mdz` and `.mdt` packaging
+2. Add transclusion support for external resources
+3. Enhance auto-detection with machine learning patterns
+4. Add migration tools for existing exploded structures
+
+### Phase 4: Integration & Polish
+1. Update documentation and examples
+2. Add performance benchmarks
+3. Create migration guide for existing users
+4. Integration with asset management system
+
+## Benefits
+
+✅ **Preserves All Information** - Manifest ensures reversibility
+✅ **Multiple Organization Patterns** - Suits different use cases
+✅ **Backward Compatibility** - Current behavior preserved as default
+✅ **Auto-Detection** - Seamless implode operations
+✅ **Extensible** - Easy to add new variants
+✅ **Standardized** - Clear file extension conventions
+
+## Success Criteria
+
+1. **100% Reversibility** - Any exploded structure can be perfectly imploded
+2. **Variant Auto-Detection** - Implode automatically detects explosion variant
+3. **Backward Compatibility** - Existing workflows continue to work
+4. **Performance** - New features don't significantly impact performance
+5. **Documentation** - Complete user and developer documentation
+6. **Test Coverage** - Comprehensive test suite for all variants and edge cases
+
+## Timeline Estimate
+
+- **Phase 1**: 2-3 weeks (Core Infrastructure)
+- **Phase 2**: 3-4 weeks (Variant Implementations)
+- **Phase 3**: 2-3 weeks (Advanced Features)
+- **Phase 4**: 1-2 weeks (Integration & Polish)
+
+**Total Estimated Duration**: 8-12 weeks
+
+## Risk Assessment
+
+**Medium Risk**: Backward compatibility with existing exploded structures
+**Low Risk**: Performance impact of manifest system
+**Low Risk**: Complexity of auto-detection algorithm
+
+## Next Steps
+
+1. Create detailed implementation issues for each phase
+2. Set up feature branch for development
+3. Begin Phase 1 implementation
+4. Coordinate with asset management system integration