diff --git a/CLAUDE.md b/CLAUDE.md
index a240cb109f..1364c6b23f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -146,3 +146,13 @@ bash-it search docker
   - Examples: `${BASH_VERSION-}`, `${HOME-}`, `${PATH-}`
   - Critical for variables checked in conditionals: `if [ -n "${BASH_VERSION-}" ]`
   - This defensive practice ensures scripts work regardless of user's shell options
+
+## Project Planning & Roadmaps
+
+Strategic planning documents are maintained in `docs/plans/`:
+
+- **[Quick Reference](docs/plans/bash-it-quick-reference.md)** - TL;DR summary of current issues and action items
+- **[Comprehensive Issue Analysis](docs/plans/bash-it-issues-comprehensive-analysis.md)** - Detailed breakdown of all open issues with categorization and recommendations
+- **[2025 Roadmap](docs/plans/bash-it-roadmap-2025.md)** - 6-month technical debt reduction plan with phases and success metrics
+
+These documents guide ongoing maintenance, issue triage, and code quality improvements.
diff --git a/docs/plans/bash-it-issues-comprehensive-analysis.md b/docs/plans/bash-it-issues-comprehensive-analysis.md
new file mode 100644
index 0000000000..299bcf6ab1
--- /dev/null
+++ b/docs/plans/bash-it-issues-comprehensive-analysis.md
@@ -0,0 +1,395 @@
+# Bash-it Open Issues - Comprehensive Analysis & Action Plan
+**Analysis Date**: 2025-10-05
+**Total Open Issues**: 32
+**Analyzed By**: Claude Code
+
+---
+
+## Executive Summary
+
+Out of 32 open issues:
+- **5 Quick Wins** - Can be fixed immediately with simple PRs
+- **6 Require Your Decision** - Need maintainer input on direction
+- **18 Stale/Redundant** - Old issues (>2 years) that need closure decisions
+- **3 Long-term Roadmap** - Strategic features for future planning
+
+**Critical Finding**: 78% of issues are stale (>2 years old). Recommend aggressive issue gardening to improve project health.
+
+---
+
+## 1. QUICK WINS - Can Do Without Your Help (5 issues)
+
+### ✅ Issue #2317: Auto-infer remote name
+**Status**: ✨ **ALREADY FIXED** - PR #2345 created today
+- Simple helper function to detect git remote name
+- No more hardcoded "origin" assumption
+- **Action**: None needed
+
+### ⚡ Issue #2314: Interactive install fails for todo aliases
+**Effort**: 5 minutes
+**Fix**: Rename `todo.txt-cli.aliases.bash` → `todo.aliases.bash`
+- Clear bug, clear solution already identified in issue
+- Just a file rename to match naming convention
+- **Action**: I can fix this immediately
+
+### ⚡ Issue #2296: down4me function broken
+**Effort**: 10 minutes
+**Fix**: Update URL in `lib/base.bash` - downforeveryoneorjustme.com API changed
+- The external service changed their API
+- Need to find new service or update implementation
+- **Action**: I can research and fix this immediately
+
+### ⚡ Issue #2260: SSH completion removes @ symbol
+**Effort**: 30 minutes
+**Fix**: Fix completion logic in `completion/available/ssh.completion.bash`
+- Completion parser issue with user@host format
+- **Action**: I can investigate and fix this
+
+### ⚡ Issue #2238: Uninstall script deletes bashrc incorrectly
+**Effort**: 1 hour
+**Fix**: Improve `uninstall.sh` to be smarter about backups
+- Should prompt user before reverting to old backup
+- Should merge changes rather than wholesale replacement
+- **Action**: I can fix this with proper testing
+
+---
+
+## 2. DECISION REQUIRED - Need Your Input (6 issues)
+
+### 🤔 Issue #2248: Add Laravel Artisan completion
+**Decision Needed**: Accept feature or close?
+- Someone willing to contribute Artisan (Laravel) completions
+- **Question**: Do you want to expand framework-specific completions?
+- **Recommendation**: Accept if contributor provides PR matching quality standards
+- **Your Call**: Yes/No on framework completions?
+
+### 🤔 Issue #2245: Add tmux -c completion
+**Decision Needed**: Accept feature or close?
+- Small enhancement to tmux completion
+- **Question**: Accept incremental tmux improvements?
+- **Recommendation**: Accept if clean PR submitted
+- **Your Call**: Yes/No?
+
+### 🤔 Issue #2216: Show node version only in package.json directories
+**Decision Needed**: Performance vs. features
+- User wants nvm plugin to be "smarter" - only show version in Node projects
+- **Philosophical question**: Should plugins auto-optimize or let users configure?
+- **Trade-off**: Adds complexity vs. improves UX
+- **Your Call**: Add smart detection or close as "won't fix"?
+
+### 🤔 Issue #2214: Do you need maintainers?
+**Decision Needed**: Project governance
+- Open question about adding maintainers
+- **Action**: You need to respond about maintainer status/needs
+- **Your Call**: Are you looking for co-maintainers?
+
+### 🤔 Issue #1819: Package bash-it with package manager
+**Decision Needed**: Distribution strategy
+- Request to get bash-it into Homebrew, apt, etc.
+- **Major effort** but would improve adoption
+- **Question**: Is packaging worth the maintenance burden?
+- **Your Call**: Worth pursuing or close?
+
+### 🤔 Issue #825: Aliases shadowing program names
+**Decision Needed**: Philosophy on aliases
+- Some aliases override common commands (e.g., `ll`)
+- **Question**: Should bash-it be more conservative with alias names?
+- **Recommendation**: Document clearly, let users choose
+- **Your Call**: Change default alias behavior or close?
+
+---
+
+## 3. STALE/REDUNDANT - Need Closure Decisions (18 issues)
+
+These are all >2 years old with minimal activity. **Recommend closing most** with option to reopen if someone volunteers.
+
+### 🗑️ Ancient Issues (>4 years old) - Recommend CLOSE
+
+#### Issue #517 (2015): Plugin load times
+- Created 9 years ago
+- Generic performance concern, no specific action items
+- **Recommendation**: Close - performance is acceptable now
+
+#### Issue #825 (2016): Aliases shadowing programs
+- Already listed above in "Decision Required"
+
+#### Issue #922 (2017): Support for enhancd
+- 7 years old, labeled "seems abandoned"
+- External tool integration request
+- **Recommendation**: Close - no activity, unclear if still needed
+
+#### Issue #1053 (2017): Evaluate kcov code coverage
+- 7 years old, technical improvement
+- **Recommendation**: Close - we use BATS now, coverage not critical
+
+#### Issue #1207 (2018): Prompt wrap-around glitches
+- 6 years old, prompt theme visual bugs
+- **Recommendation**: Close - likely fixed in modern terminals, needs repro
+
+### 🗑️ Old Issues (2-4 years) - Recommend CLOSE unless someone volunteers
+
+#### Issue #1640 (2020): Cleanup "base" and "general"
+- Vague organizational request
+- **Recommendation**: Close - or convert to specific actionable issue
+
+#### Issue #1680 (2020): Add documentation for all commands
+- Massive undertaking, no volunteers
+- **Recommendation**: Close - accept incremental doc improvements instead
+
+#### Issue #1693 (2020): todo plugin doesn't use $TODO variable
+- Related to #2314 (todo aliases)
+- **Recommendation**: Close as duplicate or fix alongside #2314
+
+#### Issue #1696 (2020): Help us clean up Bash-it!
+- Meta tracking issue for cleanup
+- **Recommendation**: KEEP OPEN - useful for coordinating cleanup efforts
+- **Action**: Update with current status (pre-commit hooks working!)
+
+#### Issue #1818 (2021): Moving external libraries to vendor/
+- Technical debt cleanup
+- **Recommendation**: Close - already done, verify and close
+
+#### Issue #1943 (2021): Performance of bash-preexec DEBUG trap
+- Performance concern about DEBUG trap
+- **Recommendation**: Close - needs reproduction, likely non-issue
+
+#### Issue #2080 (2022): Structure all aliases
+- Organizational improvement
+- **Recommendation**: Close - too vague, accept specific alias improvements
+
+#### Issue #2084 (2022): Platform dependent config file selection
+- Question about macOS vs Linux config differences
+- **Recommendation**: Close - working as designed, or needs specific fix proposal
+
+#### Issue #2149 (2022): pyenv plugin breaks over SSH
+- SSH + pyenv interaction issue
+- **Recommendation**: Close - needs reproduction, likely user config issue
+
+#### Issue #2150 (2022): Help information for preview command
+- Documentation request
+- **Recommendation**: Close - command is self-explanatory, or add quick docs
+
+#### Issue #2174 (2022): System alias breaks completion
+- Completion conflict with user's system alias
+- **Recommendation**: Investigate - might be legit bug or user config issue
+
+#### Issue #2184 (2022): Show plugin source URI
+- Feature request for plugin metadata
+- **Recommendation**: Close - not worth complexity, plugins are in repo
+
+#### Issue #2197 (2023): bash-it preview not working
+- Preview command bug
+- **Recommendation**: Close - needs reproduction on current version
+
+#### Issue #2202 (2023): Why does install add shebang to bash_profile?
+- Question about install behavior
+- **Recommendation**: Answer and close - likely incorrect assumption
+
+### 🕐 Recent but inactive (1-2 years) - Investigate before closing
+
+#### Issue #2254 (2024): Syntax error in alias_completion
+- Bash syntax error in generated completion file
+- **Recommendation**: Try to reproduce, fix or close
+
+#### Issue #2264 (2024): Alias completion doesn't complete
+- Already listed in Quick Wins above
+
+#### Issue #2297 (2025): Powerline multiline SSH padlock miscalculation
+- Recent bug (Mar 2025), active (Sept update)
+- **Recommendation**: KEEP OPEN - legitimate bug, needs fix
+
+---
+
+## 4. LONG-TERM ROADMAP (3 issues)
+
+### 📋 Issue #1696: Help us clean up Bash-it!
+**Status**: Active coordination issue
+- Good place to track pre-commit cleanup progress
+- **Action**: Keep open, update regularly with progress
+- **Next Steps**:
+  - List remaining files not in `clean_files.txt`
+  - Create "good first issue" labels for individual files
+
+### 📋 Issue #1819: Package Bash-it with package managers
+**Status**: Requires decision (see Decision Required section)
+- Would significantly improve installation experience
+- **Effort**: Epic (months)
+- **Benefit**: High - easier adoption
+- **Dependencies**: Need CI/CD, release process, semantic versioning
+
+### 📋 Issue #1053: Code coverage with kcov
+**Status**: Low priority technical improvement
+- Would be nice to have coverage metrics
+- **Effort**: Medium (weeks)
+- **Benefit**: Low - we have tests, coverage is nice-to-have
+
+---
+
+## 5. WORK PLAN TO REDUCE TECH DEBT
+
+### Phase 1: Immediate Wins (This Week)
+**I can do these without your input:**
+
+1. ✅ Fix #2317 - Auto-detect git remote (DONE - PR #2345)
+2. ⚡ Fix #2314 - Rename todo alias file (5 min)
+3. ⚡ Fix #2296 - Research and fix down4me function (30 min)
+4. ⚡ Fix #2260 - SSH completion @ symbol (1 hour)
+5. ⚡ Fix #2238 - Improve uninstall script (2 hours)
+
+**Total Time**: ~4 hours, 5 PRs, 5 issues closed
+
+### Phase 2: Issue Gardening (Next Week)
+**Need your approval, then I execute:**
+
+1. Close stale issues (18 issues) with polite message:
+   - "Closing due to age/inactivity. Please reopen with reproduction on latest version if still relevant."
+2. Update #1696 (cleanup tracking) with current status
+3. Label issues needing decisions with "needs-decision"
+4. Label quick wins with "good-first-issue"
+
+**Total Time**: 2 hours, 18 issues closed, improved issue hygiene
+
+### Phase 3: Strategic Decisions (This Month)
+**You decide, I can implement:**
+
+1. **Decision**: Accept framework-specific completions? (#2248 Laravel)
+2. **Decision**: Smart plugin behavior? (#2216 nvm auto-detect)
+3. **Decision**: Need co-maintainers? (#2214)
+4. **Decision**: Pursue packaging? (#1819)
+5. **Decision**: Conservative aliases? (#825)
+
+**Outcome**: Clear project direction, updated CLAUDE.md with decisions
+
+### Phase 4: Continued Cleanup (Ongoing)
+**Sustaining momentum:**
+
+1. Continue `clean_files.txt` expansion
+   - Current: ~50 files clean
+   - Goal: All files pass pre-commit hooks
+2. Add tests for bugs as they're fixed
+3. Improve documentation incrementally
+4. Monthly issue triage (close stale, label new)
+
+---
+
+## 6. RECOMMENDATIONS
+
+### Critical Actions
+1. ✅ **Fix Quick Wins** - 5 issues, 4 hours work, big impact
+2. 🧹 **Close Stale Issues** - Improve project health, reduce noise
+3. 🎯 **Make Strategic Decisions** - Give project clear direction
+
+### Nice to Have
+4. 📦 **Consider Packaging** - Would improve adoption significantly
+5. 📚 **Incremental Docs** - Fix docs as you touch code
+6. 🧪 **Coverage Tracking** - Low priority, would be nice
+
+### Don't Do
+- ❌ Don't try to fix all old issues - most are stale
+- ❌ Don't accept vague feature requests - require specific proposals
+- ❌ Don't feel bad closing old issues - it's healthy
+
+---
+
+## 7. WHAT I CAN DO WITHOUT YOUR HELP
+
+### Immediately (Today)
+- [x] Fix #2317 - git remote auto-detect (DONE)
+- [ ] Fix #2314 - todo alias rename
+- [ ] Fix #2296 - down4me function
+- [ ] Fix #2260 - SSH completion
+
+### This Week
+- [ ] Fix #2238 - uninstall script
+- [ ] Draft issue closure messages for stale issues
+- [ ] Update #1696 with cleanup progress
+- [ ] Identify next 10 files for `clean_files.txt`
+
+### Ongoing
+- [ ] Continue pre-commit cleanup (add files to clean_files.txt)
+- [ ] Write tests for bugs I fix
+- [ ] Improve docs as I work
+
+---
+
+## 8. WHAT I NEED FROM YOU
+
+### Decisions Needed
+1. **Close stale issues?** - Should I close the 18 stale issues (>2 years old)?
+2. **Framework completions?** (#2248) - Accept Laravel/Artisan completion?
+3. **Smart plugins?** (#2216) - Should nvm only show in Node projects?
+4. **Maintainer status?** (#2214) - Are you seeking co-maintainers?
+5. **Packaging?** (#1819) - Worth pursuing package manager distribution?
+6. **Alias philosophy?** (#825) - Stay aggressive or be more conservative?
+
+### Approval Needed
+- Approve me to start making PRs for Quick Wins
+- Approve mass closure of stale issues (with template message)
+
+---
+
+## 9. PROPOSED ISSUE CLOSURE TEMPLATE
+
+For stale issues, I recommend this message:
+
+```markdown
+Closing this issue due to inactivity (2+ years old).
+
+If this is still relevant, please:
+1. Test with latest bash-it version
+2. Provide reproduction steps
+3. Reopen or create new issue with updated details
+
+Thanks for your contribution to bash-it! 🎉
+```
+
+---
+
+## 10. SUCCESS METRICS
+
+### Short Term (1 month)
+- [ ] 5+ Quick Win PRs merged
+- [ ] 18 stale issues closed
+- [ ] Open issue count < 15
+- [ ] All open issues labeled and categorized
+
+### Medium Term (3 months)
+- [ ] 100+ files in `clean_files.txt` (currently ~50)
+- [ ] All quick wins fixed
+- [ ] Strategic decisions made and documented
+- [ ] Issue response time < 1 week
+
+### Long Term (6 months)
+- [ ] All files pass pre-commit hooks
+- [ ] < 10 open issues at any time
+- [ ] Clear contribution guidelines
+- [ ] Possibly: Package manager distribution
+
+---
+
+## APPENDIX: Issue Reference
+
+### Quick Wins (5)
+- #2317 ✅ Auto-detect git remote (DONE)
+- #2314 Todo alias install failure
+- #2296 down4me broken
+- #2260 SSH completion @ issue
+- #2238 Uninstall script issue
+
+### Decision Required (6)
+- #2248 Laravel completion
+- #2245 tmux completion
+- #2216 Smart nvm plugin
+- #2214 Need maintainers?
+- #1819 Package managers
+- #825 Alias philosophy
+
+### Stale/Close (18)
+- #517, #825, #922, #1053, #1207 (Ancient >4yr)
+- #1640, #1680, #1693, #1818, #1943, #2080, #2084, #2149, #2150, #2174, #2184, #2197, #2202 (Old 2-4yr)
+- #2254 (Recent but needs repro)
+
+### Keep Open (3)
+- #1696 Cleanup tracking issue
+- #2297 Powerline bug (recent, active)
+- Any issues with recent activity or clear action items
diff --git a/docs/plans/bash-it-quick-reference.md b/docs/plans/bash-it-quick-reference.md
new file mode 100644
index 0000000000..0a4dcd448d
--- /dev/null
+++ b/docs/plans/bash-it-quick-reference.md
@@ -0,0 +1,122 @@
+# Bash-it Issue Analysis - Quick Reference
+**Date**: 2025-10-05
+
+## TL;DR
+
+📊 **32 open issues** → Can reduce to **~10** with focused effort
+
+### What I Can Do Right Now (No Approval Needed)
+1. ✅ Fix #2317 - git remote detection (DONE - PR #2345)
+2. Fix #2314 - todo alias rename (5 min)
+3. Fix #2296 - down4me function (30 min)  
+4. Fix #2260 - SSH completion (1 hour)
+5. Fix #2238 - uninstall script (2 hours)
+
+**Total**: ~4 hours work, 5 bugs fixed
+
+### What I Need From You
+
+#### Decision 1: Close Stale Issues?
+Close 18 issues that are 2+ years old with no activity?
+- ✅ **Recommend YES** - Improves project health
+- Template message: "Closing due to inactivity. Reopen if still relevant."
+
+#### Decision 2: Framework Completions?
+Accept Laravel/Artisan completions (#2248)?
+- ⚖️ **Your call** - Accept if quality is good?
+
+#### Decision 3: Smart Plugins?
+Should nvm plugin auto-detect Node projects (#2216)?
+- ⚖️ **Your call** - More features vs. more complexity?
+
+#### Decision 4: Need Co-Maintainers?
+Response to #2214 about project governance?
+- ⚖️ **Your call** - Want help maintaining?
+
+#### Decision 5: Package Managers?
+Worth effort to get into Homebrew (#1819)?
+- ⚖️ **Recommend YES** - Big UX improvement, modest effort
+
+#### Decision 6: Alias Philosophy?
+Be more conservative with aliases like `ll`? (#825)
+- ⚖️ **Recommend NO** - Keep current, improve docs
+
+---
+
+## Issue Breakdown
+
+### ✅ Can Fix Without Your Help (5)
+- #2317: git remote (DONE)
+- #2314: todo alias
+- #2296: down4me
+- #2260: SSH completion
+- #2238: uninstall script
+
+### 🤔 Need Your Decision (6)
+- #2248: Laravel completion
+- #2245: tmux completion
+- #2216: Smart nvm
+- #2214: Maintainers
+- #1819: Packaging
+- #825: Alias philosophy
+
+### 🗑️ Recommend Closing (18)
+All are 2+ years old with no activity:
+- #517, #922, #1053, #1207 (Ancient >4yr)
+- #1640, #1680, #1693, #1818, #1943, #2080, #2084, #2149, #2150, #2174, #2184, #2197, #2202 (Old 2-4yr)
+- #2254 (Needs repro)
+
+### 📌 Keep Open (3)
+- #1696: Cleanup tracking issue (still active)
+- #2297: Powerline bug (recent, active)
+- Any new issues with activity
+
+---
+
+## Recommended Action Plan
+
+### This Week
+1. I fix 5 quick win bugs
+2. You review and approve stale issue closure
+3. You make strategic decisions
+
+### Next Week  
+1. Close stale issues
+2. Start pre-commit cleanup
+3. Label remaining issues
+
+### This Month
+1. Continue code cleanup
+2. Improve documentation
+3. Monthly issue triage
+
+---
+
+## Files Created
+
+1. `/tmp/bash-it-issues-comprehensive-analysis.md` - Full detailed analysis
+2. `/tmp/bash-it-roadmap-2025.md` - 6-month technical debt reduction plan
+3. `/tmp/bash-it-quick-reference.md` - This file (TL;DR version)
+4. `/tmp/bash-it-open-issues.json` - Raw issue data
+
+---
+
+## Key Metrics
+
+| Metric | Now | After Phase 1 | After Phase 2 | Target |
+|--------|-----|---------------|---------------|--------|
+| Open Issues | 32 | 27 | 9 | <10 |
+| Stale Issues | 25 | 25 | 0 | 0 |
+| Quick Wins Done | 1 | 5 | 5 | 5 |
+| Clean Files | ~50 | ~60 | ~100 | 400+ |
+
+---
+
+## Next Action
+
+**Your Move**: Review and decide:
+1. Approve Quick Win fixes?
+2. Approve stale issue closure?
+3. Make strategic decisions (#2248, #2216, #2214, #1819, #825)?
+
+**My Move**: Once approved, execute immediately
diff --git a/docs/plans/bash-it-roadmap-2025.md b/docs/plans/bash-it-roadmap-2025.md
new file mode 100644
index 0000000000..27d574a8e3
--- /dev/null
+++ b/docs/plans/bash-it-roadmap-2025.md
@@ -0,0 +1,412 @@
+# Bash-it Technical Debt Reduction Roadmap 2025
+**Created**: 2025-10-05
+**Owner**: Maintainers
+**Goal**: Reduce open issues from 32 to <10, improve code quality to 100% pre-commit clean
+
+---
+
+## Current State Assessment
+
+### Health Metrics (2025-10-05)
+- 📊 **Open Issues**: 32
+- 🧹 **Clean Files**: ~50 files in `clean_files.txt`
+- ✅ **Pre-commit Coverage**: ~15% of codebase
+- ⏰ **Stale Issues**: 78% (>2 years old)
+- 🐛 **Active Bugs**: 5 fixable quickly
+- 🎯 **Issue Response Time**: Variable (some years old)
+
+### Technical Debt Categories
+1. **Code Quality**: Many files don't pass shellcheck/shfmt
+2. **Issue Backlog**: 25 stale issues creating noise
+3. **Documentation**: Inconsistent, incomplete
+4. **Testing**: Good BATS coverage, but could expand
+5. **Distribution**: Manual install only, no package managers
+
+---
+
+## Phase 1: Quick Wins Sprint (Week 1-2)
+**Goal**: Fix 5 bugs, close 5 issues, build momentum
+**Effort**: ~8 hours total
+
+### Tasks
+- [x] #2317: Auto-detect git remote (DONE - PR #2345)
+- [ ] #2314: Rename todo alias file (5 min)
+- [ ] #2296: Fix down4me function (30 min)
+- [ ] #2260: Fix SSH completion @ removal (1 hour)
+- [ ] #2238: Improve uninstall script (2 hours)
+
+### Success Criteria
+- ✅ 5 PRs merged
+- ✅ 5 issues closed
+- ✅ All fixes have tests
+- ✅ Clean git history
+
+### Deliverables
+- Working fixes for real user problems
+- Test coverage for fixed bugs
+- Updated documentation where needed
+- Template for future quick-win sprints
+
+---
+
+## Phase 2: Issue Garden Cleanup (Week 3-4)
+**Goal**: Reduce noise, improve project health
+**Effort**: ~4 hours
+
+### Strategy: Aggressive Stale Issue Closure
+Close issues that are:
+- >2 years old with no recent activity
+- Vague feature requests with no volunteers
+- Questions that were never answered
+- Fixed but not closed
+- No longer relevant
+
+### Execution Plan
+1. **Week 3**: Draft closure messages for each issue
+2. **Get maintainer approval** on closure list
+3. **Week 4**: Close issues with polite template message
+4. **Add labels**: "stale-closed", "reopen-if-relevant"
+
+### Issues to Close (18 total)
+**Ancient** (>4 years, likely irrelevant):
+- #517: Plugin load times (2015)
+- #922: Support for enhancd (2017)
+- #1053: Evaluate kcov coverage (2017)
+- #1207: Prompt wrap-around (2018)
+
+**Old** (2-4 years, no activity):
+- #1640: Cleanup base/general
+- #1680: Document all commands
+- #1693: todo plugin $TODO variable
+- #1818: Move libs to vendor
+- #1943: preexec performance
+- #2080: Structure aliases
+- #2084: Platform config question
+- #2149: pyenv over SSH
+- #2150: Preview help
+- #2174: System alias breaks completion
+- #2184: Show plugin source URI
+- #2197: Preview not working
+- #2202: Install shebang question
+
+**Recent but stale** (needs repro):
+- #2254: Syntax error in completion
+
+### Success Criteria
+- ✅ Open issues reduced from 32 to <15
+- ✅ All remaining issues labeled appropriately
+- ✅ Clear "why closed" rationale for each
+- ✅ Template for future issue gardening
+
+---
+
+## Phase 3: Strategic Decisions (Month 2)
+**Goal**: Establish clear project direction
+**Effort**: Discussion + documentation
+
+### Decisions Required
+
+#### 1. Framework-Specific Completions (#2248, #2245)
+**Question**: Accept framework-specific completions (Laravel, etc.)?
+**Options**:
+- A) Accept all quality completions (grow features)
+- B) Only popular/maintained frameworks (selective)
+- C) Reject (keep bash-it focused)
+
+**Recommendation**: Option B - Selective acceptance
+- Require: Good tests, maintained upstream, popular (>10k stars)
+- Reject: Niche frameworks, unmaintained, poor code quality
+
+#### 2. Smart Plugin Behavior (#2216)
+**Question**: Should plugins auto-detect context (e.g., nvm only in Node projects)?
+**Options**:
+- A) Add smart detection (better UX, more complexity)
+- B) Keep simple (user configures, less magic)
+
+**Recommendation**: Option B - Keep simple
+- Document how users can add conditional logic themselves
+- Avoid complexity in core plugins
+
+#### 3. Maintainer/Governance (#2214)
+**Question**: Need co-maintainers? How to govern?
+**Options**:
+- A) Seek co-maintainers (share workload)
+- B) Stay solo (full control)
+- C) Create contributor tiers (core + trusted)
+
+**Recommendation**: Option C - Tiered contributors
+- Core maintainer(s): Can merge to master
+- Trusted contributors: Can label, triage issues
+- Contributors: Submit PRs
+
+#### 4. Package Manager Distribution (#1819)
+**Question**: Worth effort to get into Homebrew, apt, etc.?
+**Options**:
+- A) Full packaging effort (Homebrew, apt, yum)
+- B) Homebrew only (most requested)
+- C) Git install only (current)
+
+**Recommendation**: Option B - Homebrew first
+- Create Homebrew formula (2-4 hours work)
+- Improves adoption significantly
+- Low maintenance once set up
+- Defer other package managers until demand proven
+
+#### 5. Alias Philosophy (#825)
+**Question**: How aggressive with default aliases?
+**Options**:
+- A) Very conservative (no common command shadowing)
+- B) Current approach (some shadowing, documented)
+- C) More aggressive (convenience > safety)
+
+**Recommendation**: Option B - Current + better docs
+- Keep current aliases (many users depend on them)
+- Add BIG WARNING in docs about ll, la, etc.
+- Add `bash-it doctor --check-conflicts` command
+- Let users decide (enable/disable)
+
+### Outcome
+- All decisions documented in CLAUDE.md
+- Issues closed or converted to tracked work
+- Clear contributor guidelines
+
+---
+
+## Phase 4: Pre-commit Expansion (Month 2-3)
+**Goal**: Get 80%+ of files passing pre-commit hooks
+**Effort**: ~20 hours spread over 6 weeks
+
+### Current State
+- `clean_files.txt` has ~50 entries
+- Remaining: ~450 bash files need cleanup
+- Pre-commit hooks: shellcheck, shfmt, trailing whitespace, etc.
+
+### Strategy: Chip Away Weekly
+- **Weekly goal**: Add 10 files to `clean_files.txt`
+- **Prioritize**: Most-used files first (lib/, install.sh, bash_it.sh)
+- **Batch fixes**: Group similar files (all themes, all plugins of type X)
+
+### Target Files (Priority Order)
+1. **Core** (Week 1-2):
+   - bash_it.sh
+   - scripts/reloader.bash
+   - All files in lib/
+   
+2. **Install/Uninstall** (Week 3):
+   - install.sh (partially done)
+   - uninstall.sh
+
+3. **Popular Plugins** (Week 4-5):
+   - plugins/available/base.plugin.bash
+   - plugins/available/git.plugin.bash
+   - plugins/available/docker.plugin.bash
+   - plugins/available/nvm.plugin.bash
+
+4. **Themes** (Week 6-7):
+   - Focus on most popular themes first
+   - bobby, powerline, atomic, etc.
+
+5. **Completions** (Week 8-9):
+   - System completions
+   - Popular tool completions
+
+6. **Aliases** (Week 10+):
+   - Lower priority (users can disable)
+   - Fix as time permits
+
+### Success Criteria
+- ✅ 80% of files in `clean_files.txt`
+- ✅ All core files (lib/, scripts/) clean
+- ✅ Install scripts clean
+- ✅ Top 10 plugins/themes clean
+
+---
+
+## Phase 5: Documentation Refresh (Month 3-4)
+**Goal**: Improve docs incrementally as we work
+**Effort**: ~10 hours
+
+### Key Documentation Needs
+1. **README.md**: Update with current state
+2. **CONTRIBUTING.md**: Clear guidelines for PRs
+3. **CLAUDE.md**: Document decisions, patterns
+4. **Wiki**: Troubleshooting common issues
+
+### Approach: Doc-as-you-go
+- Fix bug → Update relevant docs
+- Add feature → Update examples
+- Close stale issue → Document decision
+
+### Priority Docs
+1. Pre-commit hook usage (for contributors)
+2. Plugin development guide
+3. Theme development guide
+4. Troubleshooting guide
+5. Performance optimization guide
+
+---
+
+## Phase 6: Testing Expansion (Month 4-5)
+**Goal**: Increase test coverage for critical paths
+**Effort**: ~15 hours
+
+### Current Testing
+- BATS framework in place
+- Good coverage of core functionality
+- Some plugins/completions lack tests
+
+### Testing Priorities
+1. **Core Functions**: lib/helpers.bash functions
+2. **Bug Fixes**: Every bug fix gets a test
+3. **Plugins**: At least smoke tests for all
+4. **Completions**: Test completion generation
+
+### Success Criteria
+- ✅ All functions in lib/ have tests
+- ✅ All fixed bugs have regression tests
+- ✅ CI runs tests on every PR
+- ✅ Test coverage >70%
+
+---
+
+## Phase 7: Packaging & Distribution (Month 5-6)
+**Goal**: Get bash-it into Homebrew (if decision approved)
+**Effort**: ~8 hours initial + ongoing maintenance
+
+### Homebrew Formula Steps
+1. Create formula in homebrew-core
+2. Define installation steps
+3. Add update mechanism
+4. Add uninstall support
+5. Submit PR to Homebrew
+
+### Requirements
+- Semantic versioning (start tagging releases)
+- Stable release process
+- Update mechanism (bash-it update needs to work)
+- CI to test formula
+
+### Success Criteria
+- ✅ Homebrew formula accepted
+- ✅ Users can `brew install bash-it`
+- ✅ Formula auto-updates with releases
+- ✅ Documented in README
+
+---
+
+## Success Metrics & KPIs
+
+### Issue Health
+| Metric | Current | 1 Month | 3 Months | 6 Months |
+|--------|---------|---------|----------|----------|
+| Open Issues | 32 | <15 | <10 | <10 |
+| Stale Issues | 25 | 0 | 0 | 0 |
+| Response Time | Variable | <1 week | <3 days | <3 days |
+| Issues with Labels | 50% | 100% | 100% | 100% |
+
+### Code Quality
+| Metric | Current | 1 Month | 3 Months | 6 Months |
+|--------|---------|---------|----------|----------|
+| Clean Files | 50 | 100 | 250 | 400+ |
+| Pre-commit Coverage | 15% | 30% | 60% | 80%+ |
+| Shellcheck Pass | ~15% | ~30% | ~60% | 80%+ |
+| Test Coverage | Good | Good | Better | 70%+ |
+
+### Project Health
+| Metric | Current | 1 Month | 3 Months | 6 Months |
+|--------|---------|---------|----------|----------|
+| Documentation | Fair | Good | Good | Excellent |
+| Contributor Guidelines | Basic | Clear | Clear | Comprehensive |
+| Distribution | Git only | Git only | Git only | + Homebrew |
+| Active Contributors | Few | Growing | Growing | Community |
+
+---
+
+## Risk Management
+
+### Risks & Mitigations
+
+#### Risk: Closing issues angers contributors
+**Mitigation**: 
+- Polite closure messages
+- Clear "reopen if relevant" policy
+- Respond promptly to reopens
+
+#### Risk: Pre-commit slows down contributors
+**Mitigation**:
+- Clear docs on running pre-commit
+- Auto-fix where possible (shfmt -w)
+- Allow incremental improvement
+
+#### Risk: Feature decisions split community
+**Mitigation**:
+- Be transparent about reasoning
+- Accept feedback, be willing to reverse
+- Plugins are optional - defaults matter less
+
+#### Risk: Packaging creates maintenance burden
+**Mitigation**:
+- Start with Homebrew only
+- Automate release process
+- Only pursue if demand is real
+
+---
+
+## Timeline Summary
+
+```
+Month 1: Quick Wins + Issue Cleanup
+  Week 1-2: Fix 5 bugs
+  Week 3-4: Close 18 stale issues
+
+Month 2: Decisions + Pre-commit Start
+  Week 5-6: Make strategic decisions
+  Week 7-8: Clean core files
+
+Month 3: Pre-commit Expansion
+  Week 9-12: Add 40+ files to clean_files.txt
+
+Month 4: Documentation + Testing
+  Week 13-16: Improve docs, add tests
+
+Month 5-6: Polish + Optional Packaging
+  Week 17-20: Continue cleanup
+  Week 21-24: Homebrew formula (if approved)
+```
+
+---
+
+## Resource Requirements
+
+### Time Investment
+- **Maintainer**: 2-4 hours/week decision-making, review
+- **Contributor(s)**: 4-8 hours/week implementation
+- **Total**: ~6-12 hours/week for 6 months
+
+### Skills Needed
+- Bash scripting (existing)
+- Testing with BATS (existing)
+- Git workflow (existing)
+- GitHub Actions (light, for packaging)
+- Homebrew packaging (learn, ~4 hours)
+
+---
+
+## Next Steps
+
+1. **Review this roadmap** with maintainer(s)
+2. **Approve Phase 1** Quick Wins sprint
+3. **Decide on stale issue closure** approach
+4. **Make strategic decisions** (Phase 3)
+5. **Start executing** week by week
+
+---
+
+## Questions for Maintainer
+
+1. Approve Quick Wins sprint? (5 bug fixes)
+2. Approve stale issue closure? (18 issues)
+3. Which strategic decisions need discussion?
+4. What's the priority: features vs. cleanup?
+5. Interest in co-maintainers/trusted contributors?
+6. Should I start Phase 1 immediately?