diff --git a/MODERNIZATION_PLAN.md b/MODERNIZATION_PLAN.md
new file mode 100644
index 0000000..1b129fc
--- /dev/null
+++ b/MODERNIZATION_PLAN.md
@@ -0,0 +1,750 @@
+# check-engine Modernization Plan
+
+**Document Version:** 2.0  
+**Date:** 2025-11-08  
+**Status:** Planning Phase - Revised Phasing
+
+## Executive Summary
+
+The `check-engine` project is a valuable Node.js utility that developers run manually or include in scripts/workflows to validate their development environment. This plan focuses on modernizing the tool itself to align with current best practices while expanding its ability to validate modern development tools and environments.
+
+**Key Principle:** Build a solid foundation first, then add features. All modernization, testing improvements, tooling upgrades, TypeScript conversion, and API improvements happen BEFORE adding new validators and feature enhancements. This ensures a stable, well-tested base for future development.
+
+## What check-engine Is
+
+check-engine is a **command-line utility** and **programmatic library** that:
+- Validates that required tools are installed (node, npm, git, etc.)
+- Checks tool versions against requirements in package.json
+- Runs locally on developer machines or in CI/CD pipelines
+- Helps teams maintain consistent development environments
+
+## What check-engine Is NOT
+
+- ❌ Not a cloud service or deployed application
+- ❌ Not a containerized service
+- ❌ Not a Kubernetes workload
+- ❌ Not a SaaS offering
+
+## Current State Assessment
+
+### Strengths
+- ✅ Working core functionality
+- ✅ Good test coverage (91 tests passing)
+- ✅ Active GitHub Actions CI/CD
+- ✅ Dependabot configured for dependency updates
+- ✅ Clean, readable codebase
+- ✅ Semantic versioning support
+- ✅ MIT License (permissive)
+
+### Areas for Improvement
+- ⚠️ Node.js requirement outdated (>=10, should be >=18 or >=20)
+- ⚠️ Security vulnerabilities in dependencies (2 identified)
+- ⚠️ Legacy testing framework (tape)
+- ⚠️ No TypeScript support
+- ⚠️ Missing documentation (CONTRIBUTING, CHANGELOG)
+- ⚠️ Limited modern tool support (docker, kubectl, terraform, etc.)
+- ⚠️ Limited modern package manager support (no bun, no volta)
+- ⚠️ No pre-commit hooks
+- ⚠️ Basic linting configuration
+
+---
+
+## Phasing Strategy
+
+The modernization is structured in 6 phases, with a clear principle: **foundation before features**.
+
+**Phases 1-4** focus entirely on modernizing the existing codebase:
+1. **Foundation** - Security, dependencies, documentation
+2. **Testing** - Modern test framework and comprehensive coverage
+3. **Tooling** - Code quality tools, CI/CD, TypeScript
+4. **API** - Modernize code patterns (async/await, ESM, better APIs)
+
+**Phases 5-6** add new capabilities only after the foundation is solid:
+5. **Features** - New validators and enhancements
+6. **Extensibility** - Plugin system for community
+
+This approach ensures that:
+- ✅ The codebase is stable and well-tested before changes
+- ✅ Refactoring is easier with TypeScript and good tests
+- ✅ New features are built on modern, maintainable code
+- ✅ Risk is minimized by validating the foundation first
+
+---
+
+## Modernization Recommendations
+
+### Phase 1: Foundation (Weeks 1-2) - HIGH Priority
+
+**Focus:** Establish solid foundation with security, dependencies, and documentation
+
+#### 1.1 Update Runtime & Dependencies
+
+**Priority:** HIGH | **Effort:** 2-3 days
+
+**Tasks:**
+- Update minimum Node.js version to `>=18` (LTS) or `>=20` (current LTS)
+- Fix security vulnerabilities via `npm audit fix`
+- Update all dependencies to latest stable versions
+- Update ESLint to latest version (v9.x with flat config)
+
+**Benefits:**
+- Improved performance and security
+- Access to modern JavaScript features
+- Reduced technical debt
+
+---
+
+#### 1.2 Security Enhancements
+
+**Priority:** HIGH | **Effort:** 1 day
+
+**Tasks:**
+- Fix current vulnerabilities (brace-expansion, cross-spawn)
+- Add npm audit check to CI/CD
+- Add CodeQL workflow for static analysis
+- Create SECURITY.md with vulnerability reporting process
+- Configure Dependabot security alerts
+
+**Benefits:**
+- Zero known vulnerabilities
+- Proactive security monitoring
+- Clear security policy
+
+---
+
+#### 1.3 Documentation Improvements
+
+**Priority:** HIGH | **Effort:** 2-3 days
+
+**Tasks:**
+- Create CONTRIBUTING.md with development guidelines
+- Create CHANGELOG.md following Keep a Changelog format
+- Add CODE_OF_CONDUCT.md
+- Enhance README.md with:
+  - Better examples
+  - Troubleshooting section
+  - FAQ section
+  - Badges (build status, version, downloads)
+- Add docs/ folder with:
+  - Architecture overview
+  - Adding new validators guide
+  - Integration examples for CI/CD
+
+**Benefits:**
+- Better onboarding for contributors
+- Clearer communication
+- Professional appearance
+- Easier to maintain and extend
+
+---
+
+### Phase 2: Testing Modernization (Weeks 3-4) - HIGH Priority
+
+**Focus:** Establish robust testing infrastructure before making changes
+
+#### 2.1 Migrate Testing Framework
+
+**Priority:** HIGH | **Effort:** 2-4 days
+
+**Tasks:**
+- Migrate from tape to Vitest or Jest
+- Maintain or improve existing test coverage (91 tests)
+- Add test coverage reporting (>80% threshold)
+- Add integration tests for CLI
+- Set up coverage tracking (Codecov/Coveralls)
+- Add test coverage badges to README
+
+**Framework Recommendation:** Vitest (faster, modern) or Jest (industry standard)
+
+**Benefits:**
+- Better testing experience
+- Visual coverage reports
+- More comprehensive test coverage
+- Easier to write and maintain tests
+- Confidence for future refactoring
+
+---
+
+### Phase 3: Code Quality & Tooling (Weeks 5-6) - HIGH Priority
+
+**Focus:** Developer productivity improvements and modern tooling
+
+#### 3.1 Code Quality Tooling
+
+**Priority:** HIGH | **Effort:** 1-2 days
+
+**Tasks:**
+- Update ESLint to v9 with flat config
+- Add Prettier for consistent formatting
+- Add husky for git hooks
+- Add lint-staged for pre-commit linting
+- Add commitlint for conventional commits
+- Configure EditorConfig
+
+**Benefits:**
+- Consistent code style
+- Prevent bad commits
+- Better commit history
+- Automated code quality checks
+
+---
+
+#### 3.2 CI/CD Pipeline Enhancements
+
+**Priority:** HIGH | **Effort:** 2 days
+
+**Tasks:**
+- Test on multiple Node.js versions (18, 20, 22)
+- Test on multiple OS (Ubuntu, macOS, Windows)
+- Add CodeQL security scanning
+- Add automated release process (release-please)
+- Add performance benchmarking
+
+**Benefits:**
+- Multi-platform support verified
+- Automated release process
+- Better security posture
+- Performance tracking
+
+---
+
+#### 3.3 TypeScript Migration
+
+**Priority:** MEDIUM | **Effort:** 3-5 days
+
+**Tasks:**
+- Add TypeScript configuration (tsconfig.json)
+- Convert to TypeScript or add JSDoc type annotations
+- Provide type definitions for programmatic API
+- Maintain backward compatibility with JavaScript consumers
+
+**Benefits:**
+- Better IDE support and autocomplete
+- Catch errors at compile time
+- Improved documentation through types
+- Easier refactoring
+
+---
+
+### Phase 4: API Modernization (Weeks 7-8) - MEDIUM Priority
+
+**Focus:** Modernize the codebase and API without adding new features
+
+#### 4.1 Async/Await Migration
+
+**Priority:** MEDIUM | **Effort:** 2-3 days
+
+**Tasks:**
+- Convert to native async/await (remove Bluebird)
+- Update promise handling throughout codebase
+- Improve error handling with custom error classes
+- Add proper error propagation
+
+**Benefits:**
+- Modern JavaScript patterns
+- Better error handling
+- Easier to understand and maintain
+- No external promise library dependency
+
+---
+
+#### 4.2 Module System Modernization
+
+**Priority:** MEDIUM | **Effort:** 1-2 days
+
+**Tasks:**
+- Add ESM module support
+- Maintain CJS compatibility for backward compatibility
+- Update exports and imports
+- Test both module formats
+
+**Benefits:**
+- Modern module system support
+- Future-proof codebase
+- Better tree-shaking potential
+
+---
+
+#### 4.3 API Configuration Options
+
+**Priority:** MEDIUM | **Effort:** 1-2 days
+
+**Tasks:**
+- Add configuration options:
+  - Timeout settings
+  - Parallel execution
+  - Custom validators
+  - Output formatting
+- Add event emitters for progress tracking
+- Improve programmatic API
+
+**Benefits:**
+- More flexible API
+- Better performance options
+- Easier integration
+
+---
+
+#### 4.4 Output & Reporting Enhancements
+
+**Priority:** MEDIUM | **Effort:** 1-2 days
+
+**Tasks:**
+- Add multiple output formats:
+  - JSON (machine-readable)
+  - YAML
+  - JUnit XML (for CI/CD)
+  - Markdown
+- Improve colored terminal output
+- Add summary statistics
+- Add quiet mode and verbose/debug mode
+- Better exit codes for different scenarios
+
+**Benefits:**
+- Better CI/CD integration
+- More flexible reporting
+- Easier debugging
+- Better user experience
+
+---
+
+### Phase 5: New Validators & Features (Weeks 9-10) - MEDIUM Priority
+
+**Focus:** Add new validators now that foundation is solid
+
+#### 5.1 Add Modern Tool Validators
+
+**Priority:** MEDIUM | **Effort:** 3-5 days
+
+**Focus:** Add validators for tools developers use to build/deploy containerized and cloud applications
+
+**New Validators to Add:**
+- **Container Tools:**
+  - `docker` - Docker CLI for building containers
+  - `docker-compose` - Docker Compose for local development
+  - `podman` - Alternative container runtime
+  
+- **Kubernetes Tools:**
+  - `kubectl` - Kubernetes CLI
+  - `helm` - Kubernetes package manager
+  - `minikube` - Local Kubernetes for development
+  - `kind` - Kubernetes in Docker
+  
+- **Cloud Platform CLIs:**
+  - `aws` - AWS CLI
+  - `gcloud` - Google Cloud CLI
+  - `az` - Azure CLI
+  
+- **Infrastructure as Code:**
+  - `terraform` - Infrastructure provisioning
+  - `pulumi` - Modern IaC tool
+  
+- **Modern Package Managers:**
+  - `bun` - Fast all-in-one JavaScript runtime
+  - `volta` - JavaScript tool version manager
+  - `fnm` - Fast Node Manager
+  
+- **Build Tools:**
+  - `make` - GNU Make
+  - `cmake` - Cross-platform build system
+  - `gradle` - Java/Android build tool
+
+**Benefits:**
+- Support for modern development workflows
+- Validate environments for container/cloud development
+- Help teams ensure correct tool installation
+- More comprehensive environment validation
+
+---
+
+#### 5.2 Developer Experience Improvements
+
+**Priority:** MEDIUM | **Effort:** 1-2 days
+
+**Tasks:**
+- Add VS Code configuration:
+  - Recommended extensions
+  - Debug configurations
+  - Tasks for common operations
+- Improve CLI UX:
+  - Progress indicators
+  - Better error messages
+  - Helpful hints
+- Add development scripts in package.json
+- Add GitHub Codespaces configuration
+
+**Benefits:**
+- Faster onboarding
+- Better debugging
+- More productive development
+
+---
+
+### Phase 6: Extensibility (Ongoing) - LOW Priority
+
+**Focus:** Enable community contributions and custom validators
+
+#### 6.1 Plugin System
+
+**Priority:** LOW | **Effort:** 2-3 days
+
+**Tasks:**
+- Allow custom validators via configuration
+- Plugin system for external validators
+- Document validator API
+- Create examples for custom validators
+
+**Benefits:**
+- Community can add validators
+- Extensible architecture
+- Support for niche tools
+
+---
+
+#### 6.2 Validator Marketplace (Future)
+
+**Priority:** LOW | **Effort:** TBD
+
+**Tasks:**
+- Design validator registry
+- Create validator publishing guidelines
+- Build discovery mechanism
+
+**Benefits:**
+- Easy discovery of community validators
+- Ecosystem growth
+
+---
+
+## Implementation Timeline
+
+### Phase 1: Foundation (Weeks 1-2)
+**Focus:** Security, dependencies, documentation
+
+**Deliverables:**
+- ✅ Node.js 18+ support
+- ✅ Zero security vulnerabilities
+- ✅ Complete documentation (CONTRIBUTING, CHANGELOG, SECURITY, CODE_OF_CONDUCT)
+- ✅ Enhanced README
+
+**Estimated Effort:** 5-7 days
+
+---
+
+### Phase 2: Testing Modernization (Weeks 3-4)
+**Focus:** Establish robust testing before making changes
+
+**Deliverables:**
+- ✅ Modern testing framework (Vitest/Jest)
+- ✅ >80% test coverage maintained
+- ✅ Integration tests for CLI
+- ✅ Coverage tracking and badges
+
+**Estimated Effort:** 2-4 days
+
+---
+
+### Phase 3: Code Quality & Tooling (Weeks 5-6)
+**Focus:** Developer productivity and modern tooling
+
+**Deliverables:**
+- ✅ ESLint 9 + Prettier + pre-commit hooks
+- ✅ Enhanced CI/CD (multi-platform, automated releases)
+- ✅ TypeScript support
+- ✅ Consistent code quality
+
+**Estimated Effort:** 6-9 days
+
+---
+
+### Phase 4: API Modernization (Weeks 7-8)
+**Focus:** Modernize codebase without adding features
+
+**Deliverables:**
+- ✅ Native async/await (remove Bluebird)
+- ✅ ESM module support
+- ✅ Better configuration options
+- ✅ Multiple output formats
+
+**Estimated Effort:** 5-7 days
+
+---
+
+### Phase 5: New Validators & Features (Weeks 9-10)
+**Focus:** Add new validators with solid foundation in place
+
+**Deliverables:**
+- ✅ Modern tool validators (docker, kubectl, cloud CLIs, etc.)
+- ✅ Improved CLI UX
+- ✅ VS Code configuration
+
+**Estimated Effort:** 4-7 days
+
+---
+
+### Phase 6: Extensibility (Ongoing)
+**Focus:** Plugin system and community contributions
+
+**Deliverables:**
+- ✅ Plugin system for custom validators
+- ✅ Validator API documentation
+- ✅ Community ecosystem
+
+**Estimated Effort:** Variable (2-3 days initial, ongoing)
+
+---
+
+## Technology Stack Recommendations
+
+### Current Stack
+```json
+{
+  "runtime": "Node.js >=10",
+  "testing": "tape + tap-min",
+  "linting": "ESLint 8",
+  "mocking": "proxyquire",
+  "promises": "Bluebird",
+  "cli": "yargs",
+  "colors": "colors"
+}
+```
+
+### Proposed Stack
+```json
+{
+  "runtime": "Node.js >=18",
+  "testing": "Vitest (or Jest)",
+  "linting": "ESLint 9 + Prettier",
+  "typescript": "Optional but recommended",
+  "git-hooks": "Husky + lint-staged",
+  "commits": "commitlint",
+  "promises": "Native async/await",
+  "cli": "yargs (keep)",
+  "colors": "chalk",
+  "ci": "GitHub Actions (enhanced)"
+}
+```
+
+---
+
+## Success Metrics
+
+### After Phase 1: Foundation
+- ✅ 0 security vulnerabilities
+- ✅ Node.js 18+ supported
+- ✅ Complete documentation set
+- ✅ All existing tests passing
+
+### After Phase 2: Testing
+- ✅ >80% test coverage maintained
+- ✅ Modern testing framework (Vitest/Jest)
+- ✅ Integration tests in place
+- ✅ Coverage tracking active
+
+### After Phase 3: Code Quality
+- ✅ Pre-commit hooks working
+- ✅ Automated releases configured
+- ✅ TypeScript support added
+- ✅ Multi-platform CI/CD
+
+### After Phase 4: API Modernization
+- ✅ Native async/await throughout
+- ✅ ESM module support
+- ✅ Multiple output formats
+- ✅ Better configuration options
+
+### After Phase 5: New Features
+- ✅ 10+ new modern tool validators
+- ✅ Improved CLI UX
+- ✅ Better developer experience
+
+### After Phase 6: Extensibility
+- ✅ Plugin system available
+- ✅ Community can add validators
+- ✅ Documented validator API
+
+---
+
+## Backward Compatibility
+
+### Must Maintain
+- ✅ CLI interface and arguments
+- ✅ Programmatic API (check function)
+- ✅ Return value structure
+- ✅ package.json engines format
+- ✅ Exit codes
+
+### Can Change (with deprecation)
+- ⚠️ Internal implementation
+- ⚠️ Output formatting (with --legacy flag)
+
+### Breaking Changes (v2.0.0)
+- 🔴 Minimum Node.js version (10 → 18)
+- 🔴 Testing framework migration (internal)
+
+**Recommendation:** Release as v2.0.0 after Phase 1-2 completion
+
+---
+
+## Risk Assessment
+
+### Low Risk
+- Updating dependencies
+- Adding documentation
+- Adding new validators
+- CI/CD enhancements
+
+### Medium Risk
+- Testing framework migration
+- ESLint configuration changes
+- TypeScript migration
+- API modernization
+
+### High Risk
+- Breaking changes to public API
+- Minimum Node.js version bump
+
+**Mitigation:**
+- Comprehensive testing
+- Beta releases for major changes
+- Clear migration guides
+- Semantic versioning
+
+---
+
+## Use Cases to Support
+
+### 1. Manual Developer Usage
+```bash
+# Developer runs locally
+check-engine
+```
+
+### 2. npm Scripts
+```json
+{
+  "scripts": {
+    "preinstall": "check-engine"
+  }
+}
+```
+
+### 3. CI/CD Pipelines
+```yaml
+# GitHub Actions
+- name: Validate environment
+  run: npx check-engine
+```
+
+### 4. Pre-commit Hooks
+```bash
+# husky pre-commit
+#!/bin/sh
+check-engine || exit 1
+```
+
+### 5. Docker Development Setup Validation
+```bash
+# Validate machine has Docker installed
+check-engine # with docker in engines
+```
+
+### 6. Cloud Development Setup Validation
+```bash
+# Validate machine has kubectl, aws CLI, etc.
+check-engine # with kubectl, aws in engines
+```
+
+---
+
+## Examples of New Validators in Use
+
+### Example 1: Full-Stack JavaScript Developer
+```json
+{
+  "engines": {
+    "node": ">=18",
+    "npm": ">=9",
+    "git": ">=2.30",
+    "docker": ">=20",
+    "docker-compose": ">=2.0"
+  }
+}
+```
+
+### Example 2: Kubernetes Developer
+```json
+{
+  "engines": {
+    "node": ">=18",
+    "kubectl": ">=1.25",
+    "helm": ">=3.10",
+    "docker": ">=20",
+    "minikube": ">=1.30"
+  }
+}
+```
+
+### Example 3: Cloud Developer (AWS)
+```json
+{
+  "engines": {
+    "node": ">=20",
+    "aws": ">=2.13",
+    "terraform": ">=1.5",
+    "docker": ">=24"
+  }
+}
+```
+
+### Example 4: Modern JavaScript Developer
+```json
+{
+  "engines": {
+    "node": ">=20",
+    "bun": ">=1.0",
+    "volta": ">=1.1"
+  }
+}
+```
+
+---
+
+## Next Steps
+
+1. ✅ Review this modernization plan
+2. ⬜ Approve approach and priorities
+3. ⬜ Create GitHub project board for tracking
+4. ⬜ Begin Phase 1 implementation
+5. ⬜ Regular progress reviews
+
+---
+
+## Conclusion
+
+This modernization plan focuses on what check-engine is: a developer utility for validating local development environments. The plan follows a disciplined phased approach:
+
+**Phases 1-4: Foundation First (Weeks 1-8)**
+1. **Foundation** - Security, dependencies, documentation
+2. **Testing** - Modern test framework with strong coverage
+3. **Tooling** - Code quality, CI/CD, TypeScript
+4. **API** - Modernize code patterns (async/await, ESM)
+
+**Phases 5-6: Features Second (Weeks 9+)**
+5. **Features** - New validators for modern tools (docker, kubectl, cloud CLIs)
+6. **Extensibility** - Plugin system for community validators
+
+By modernizing the foundation first, we ensure that:
+- New features are built on stable, well-tested code
+- Refactoring is easier with TypeScript and comprehensive tests
+- The codebase is maintainable for the long term
+- Risk is minimized by proving the foundation works before adding features
+
+The goal is to make check-engine the best tool for ensuring developers have the right tools installed for modern development workflows, including container and cloud development, without turning check-engine itself into a cloud service.
+
+---
+
+**Status:** Planning Complete - Revised Phasing  
+**Total Estimated Time:** 22-34 days (4-7 weeks) for Phases 1-5  
+**Key Change:** All modernization before new features  
+**Next Phase:** Implementation (awaiting approval)