# Phase 2 Roadmap: Scripts Organization Implementation

**Status**: Ready for Implementation | **Created**: 2025-10-29 | **Duration**: 2-4 weeks

This document outlines Phase 2 work for Epic #360, which focuses on implementing the refactoring and consolidation strategies identified in Phase 1.

---

## 📋 Phase 2 Overview

Phase 1 (Epic #360, Issues #336-340) completed the **ANALYSIS & PLANNING** phase:
- ✅ Audited 45 scripts (10 categories)
- ✅ Documented organization patterns
- ✅ Created refactoring plan (1.95-2.75K token savings)
- ✅ Identified 58+ duplicate utilities
- ✅ Archived 3 obsolete scripts

**Phase 2** will **IMPLEMENT** the identified improvements:

| Epic | Focus | Impact | Timeline |
|------|-------|--------|----------|
| **Epic #366** | Refactor IMPLEMENT commands | 590 token savings (62% reduction) | 1-2 weeks |
| **Epic #367** | Consolidate duplicate utilities | 50% build size reduction (~100 KB) | 1-2 weeks |

---

## 🎯 Epic #366: Phase 2A - Refactor IMPLEMENT Commands

**Goal**: Use 3 extracted orchestrators to refactor 4 IMPLEMENT commands, reducing code duplication and token usage.

**GitHub**: [Epic #366](https://github.com/tailwind-ai/roadcrew-internal/issues/366)

### Child Issues

#### Issue #368: Refactor analyze-epic.md 🟢
- **Priority**: HIGH
- **Effort**: 1-2 hours
- **Classification**: 3 (ai-solo)
- **Token Savings**: 200-300 tokens (67% reduction)
- **Changes**: 450→100-150 lines
- **Approach**: Replace inline epic analysis with `analyzeEpic()` orchestrator call
- **Status**: Ready to start

#### Issue #369: Refactor implement-issue.md 🟢
- **Priority**: MEDIUM
- **Effort**: 1-2 hours
- **Classification**: 3 (ai-solo)
- **Token Savings**: 100-200 tokens (40% reduction)
- **Changes**: 80-100→50-60 lines
- **Approach**: Use `testing-harness` and coordinator utilities
- **Status**: Ready to start
- **Depends on**: Issue #368 (for reference patterns)

#### Issue #370: Refactor implement-epic.md 🟡
- **Priority**: MEDIUM
- **Effort**: 2-3 hours
- **Classification**: 5 (ai-led)
- **Token Savings**: 300-500 tokens (50% reduction)
- **Changes**: 350-400→100-150 lines
- **Approach**: Consolidate orchestration logic with coordinator functions
- **Status**: Ready to start
- **Depends on**: Issue #368 (reference patterns)

#### Issue #371: Refactor autopilot.md 🟠
- **Priority**: HIGH
- **Effort**: 3-4 hours
- **Classification**: 6 (ai-led)
- **Token Savings**: 600-900 tokens (70% reduction)
- **Changes**: 600-700→150-200 lines
- **Approach**: Use all 3 orchestrators (epic, coordinator, testing-harness)
- **Status**: Ready to start
- **Depends on**: Issues #368, #369, #370 (for reference)

#### Issue #372: Integration Testing & Validation 🟡
- **Priority**: HIGH
- **Effort**: 1-2 hours
- **Classification**: 5 (ai-led)
- **Testing**: End-to-end, behavioral parity, performance
- **Status**: Ready after issues #368-371
- **Depends on**: Issues #368, #369, #370, #371 (all refactored commands)

### Token Savings Summary (Epic #366)

| Command | Current | After | Savings | % |
|---------|---------|-------|---------|-----|
| analyze-epic | ~150 | ~50 | 100 | 67% |
| implement-issue | ~100 | ~60 | 40 | 40% |
| implement-epic | ~200 | ~100 | 100 | 50% |
| autopilot | ~500 | ~150 | 350 | 70% |
| **TOTAL** | **~950** | **~360** | **590** | **62%** |

### Implementation Sequence (Epic #366)

```
Week 1:
├─ Day 1: Issue #368 (analyze-epic) - 1-2 hrs ✓ INDEPENDENT
├─ Day 1: Issue #369 (implement-issue) - 1-2 hrs ✓ INDEPENDENT
├─ Day 2: Issue #370 (implement-epic) - 2-3 hrs (references #368)
└─ Day 3: Issue #371 (autopilot) - 3-4 hrs (references #368-370)

Week 2:
└─ Day 1: Issue #372 (Integration testing) - 1-2 hrs (depends on all above)
```

---

## 🎯 Epic #367: Phase 2B - Consolidate Duplicate Utilities

**Goal**: Consolidate 58+ duplicate utility files across scripts/utils/ and scripts/utils/roadcrew/, reducing build size by 50%.

**GitHub**: [Epic #367](https://github.com/tailwind-ai/roadcrew-internal/issues/367)

### Critical Issue: 58+ Duplicate Files

**Problem**: 
- Same files exist in both `scripts/utils/` and `scripts/utils/roadcrew/`
- ~100 KB of duplicate code in build output
- Developers confused about which version to use

**Solution**:
- Keep canonical version in `scripts/utils/roadcrew/`
- Remove all duplicates from `scripts/utils/`
- Update all imports across codebase
- Result: 50% build size reduction (~100 KB)

### Child Issues

#### Issue #373: Create Automated Import Rewriter Script
- **Priority**: HIGH
- **Effort**: 2-3 hours
- **Classification**: 5 (ai-led)
- **Deliverable**: `scripts/consolidate-imports.ts`
- **Features**:
  - Scan all .ts files for imports from scripts/utils/ (non-roadcrew)
  - Generate mapping of old → new paths
  - Rewrite all imports to roadcrew equivalents
  - Handle both 'from' and 'require' styles
  - Dry-run mode for preview
  - Rollback functionality
- **Status**: Ready to start
- **Impact**: 2-3 hours of automation saves 6+ hours of manual work

#### Issue #374: Update All Imports in Codebase (Dev-Wide)
- **Priority**: HIGH
- **Effort**: 1-2 hours
- **Classification**: 4 (ai-led)
- **Process**:
  1. Run consolidate-imports.ts on entire codebase
  2. Verify all imports point to scripts/utils/roadcrew/
  3. Run linter to catch broken imports
  4. TypeScript compilation
  5. Manual verification of 10+ files
- **Status**: Ready after Issue #373
- **Depends on**: Issue #373 (rewriter script)
- **Risk**: MEDIUM (large scope, many files affected)
- **Mitigation**: Automated verification + comprehensive testing

#### Issue #375: Remove Duplicate Files from scripts/utils/
- **Priority**: HIGH
- **Effort**: 1-2 hours
- **Classification**: 4 (ai-led)
- **Process**:
  1. Identify all 58+ duplicate groups
  2. Verify all imports updated (no broken imports)
  3. Delete duplicates from scripts/utils/ (keep roadcrew/)
  4. Verify build succeeds
  5. Confirm no duplicates in dist/
- **Status**: Ready after Issue #374
- **Depends on**: Issue #374 (all imports updated)
- **Risk**: LOW (no logic changes, only file removal)
- **Impact**: Final consolidation step

#### Issue #376: Verify Build Integrity & Measure Size Reduction
- **Priority**: HIGH
- **Effort**: 1 hour
- **Classification**: 3 (ai-solo)
- **Measurements**:
  - Build size before: ~200 KB
  - Build size after: ~100 KB (target)
  - Actual reduction: ___% (to be measured)
  - Build time: unchanged
  - Performance: no degradation
- **Deliverable**: Size reduction report
- **Status**: Ready after Issue #375
- **Depends on**: Issue #375 (files removed)

#### Issue #377: Integration Testing & Validation
- **Priority**: HIGH
- **Effort**: 1-2 hours
- **Classification**: 5 (ai-led)
- **Testing Scope**:
  - Full test suite run (target: 90%+ coverage)
  - No functional regressions
  - All 4 IMPLEMENT commands working
  - Orchestrators work with consolidated utilities
  - Performance: no degradation
  - Build: clean, no warnings
- **Status**: Ready after Issue #376
- **Depends on**: All previous issues (#373-376)

### Build Size Impact (Epic #367)

```
BEFORE CONSOLIDATION:
├── dist/scripts/utils/
│   ├── ai-command-wrapper.js          ← DUPLICATE
│   ├── ai-context-parser.js           ← DUPLICATE
│   ├── ... (50+ more duplicates)
├── dist/scripts/utils/roadcrew/
│   ├── ai-command-wrapper.js          ← DUPLICATE
│   ├── ai-context-parser.js           ← DUPLICATE
│   ├── ... (50+ more duplicates)

Size: ~200 KB

AFTER CONSOLIDATION:
├── dist/scripts/utils/roadcrew/
│   ├── ai-command-wrapper.js          ✓ SINGLE
│   ├── ai-context-parser.js           ✓ SINGLE
│   ├── ... (50+ utilities, clean)

Size: ~100 KB (50% reduction)
```

### Implementation Sequence (Epic #367)

```
Week 1-2 (can run parallel to Epic #366):
├─ Day 1: Issue #373 (Import rewriter) - 2-3 hrs ✓ INDEPENDENT
├─ Day 2: Issue #374 (Update imports) - 1-2 hrs (depends on #373)
├─ Day 2: Issue #375 (Remove duplicates) - 1-2 hrs (depends on #374)
└─ Day 3: Issue #376 (Verify build) - 1 hr (depends on #375)

Week 2:
└─ Day 1: Issue #377 (Integration testing) - 1-2 hrs (depends on all above)
```

---

## 📊 Phase 2 Timeline & Execution

### Parallel Execution (Recommended)

Both epics can run **in parallel** (no dependencies between them):

```
WEEK 1:
├─ Epic #366: Start issues #368, #369 (parallel)
├─ Epic #367: Start issue #373
├─ Epic #366: Continue #370, #371 (sequential after initial)
└─ Epic #367: Continue #374, #375, #376

WEEK 2:
├─ Epic #366: Issue #372 (integration testing)
└─ Epic #367: Issue #377 (integration testing)

COMPLETION: End of Week 2
```

### Resource Requirements

- **Developer**: 1 full-time equivalent
- **QA/Testing**: 4-6 hours for integration testing
- **Review**: 4-6 hours for code review
- **Total**: ~40-48 hours (1-2 weeks)

### Milestones

| Milestone | Target | Issues | Epic |
|-----------|--------|--------|------|
| **M1** | End of Day 1 | #368, #369, #373 | Both |
| **M2** | End of Day 2 | #370, #374, #375 | Both |
| **M3** | End of Day 3 | #371, #376 | Both |
| **M4** | End of Day 4 | #372, #377 | Both |

---

## 🔗 Dependency Graph

```
Epic #366 (Refactor IMPLEMENT Commands):
├─ #368 (analyze-epic) ──────────────┐
├─ #369 (implement-issue) ──────────┤
├─ #370 (implement-epic) ← depends  ├─→ #372 (Integration test)
└─ #371 (autopilot) ────────────────┘

Epic #367 (Consolidate Duplicates):
├─ #373 (Create rewriter) ────────────┐
├─ #374 (Update imports) ← depends ───┤
├─ #375 (Remove files) ← depends ─────┤
├─ #376 (Verify build) ← depends ─────┤
└─ #377 (Integration test) ← depends ─┘

No cross-epic dependencies (can run parallel)
```

---

## 🎯 Success Criteria

### Epic #366 Success
- ✅ All 4 commands refactored
- ✅ 590+ lines removed
- ✅ 1.95-2.75K tokens saved
- ✅ Test coverage: 80%+
- ✅ Zero functional regressions
- ✅ All tests pass

### Epic #367 Success
- ✅ 58+ duplicate files consolidated
- ✅ Build size reduced 50% (~100 KB)
- ✅ All imports updated
- ✅ Build succeeds, no duplicates in dist/
- ✅ Test coverage: 90%+
- ✅ Zero functional regressions

### Phase 2 Overall Success
- ✅ 590 tokens saved (Epic #366)
- ✅ 50% build reduction (Epic #367)
- ✅ 9 child issues completed
- ✅ 100% test coverage
- ✅ Zero regressions
- ✅ All PRs reviewed & merged

---

## 📈 Metrics & Tracking

### Metrics to Measure

| Metric | Before | Target After | Epic |
|--------|--------|--------------|------|
| IMPLEMENT token count | ~950 | ~360 | #366 |
| Build size | ~200 KB | ~100 KB | #367 |
| Code duplication | 58 groups | 0 groups | #367 |
| Test coverage | 80%+ | 90%+ | Both |
| Build time | Baseline | Same/better | #367 |

### CI/CD Integration

- All tests run automatically on each PR
- Build size tracked in CI output
- Token measurements logged
- Performance benchmarks compared

---

## 📋 Execution Checklist

### Pre-Start (Week 0)
- [ ] Approve Phase 2 roadmap
- [ ] Assign developer(s)
- [ ] Review all 10 child issues
- [ ] Set up tracking/monitoring
- [ ] Create tracking branch: `phase-2` from `dev`

### Epic #366 Execution (Week 1-2)
- [ ] Start: Issue #368 (analyze-epic)
- [ ] Start: Issue #369 (implement-issue)
- [ ] Continue: Issue #370 (implement-epic)
- [ ] Continue: Issue #371 (autopilot)
- [ ] Finalize: Issue #372 (Integration testing)
- [ ] Create PR: feature branch → dev
- [ ] Code review & approval
- [ ] Merge to dev

### Epic #367 Execution (Week 1-2, Parallel)
- [ ] Start: Issue #373 (Create rewriter)
- [ ] Continue: Issue #374 (Update imports)
- [ ] Continue: Issue #375 (Remove duplicates)
- [ ] Continue: Issue #376 (Verify build)
- [ ] Finalize: Issue #377 (Integration testing)
- [ ] Create PR: feature branch → dev
- [ ] Code review & approval
- [ ] Merge to dev

### Post-Completion (Week 2 End)
- [ ] Create release PR: dev → main
- [ ] Final review
- [ ] Merge to main
- [ ] Create GitHub releases
- [ ] Document Phase 2 completion
- [ ] Measure final metrics

---

## 🚀 Getting Started

### Phase 2 Start Checklist

1. ✅ Review this roadmap document
2. ✅ Review Epic #366 and all child issues
3. ✅ Review Epic #367 and all child issues
4. ✅ Understand dependencies and timeline
5. Create feature branch: `git checkout -b phase-2-implementation`
6. Ready to start: `/autopilot 366` or `/autopilot 367`

### Recommended Order

**Start with Epic #366** (less risky, simpler):
```bash
/autopilot 366
```

**Then Epic #367** (can run parallel):
```bash
/autopilot 367
```

---

## 📞 Support & Questions

- **Phase 1 Analysis**: See context/tests/epic-360-issue-338-refactoring.md
- **Phase 1 Analysis**: See context/tests/epic-360-issue-339-consolidation.md
- **Questions?**: Check Epic #360 for analysis context

---

**Status**: Phase 2 Roadmap Ready for Implementation  
**Created**: 2025-10-29  
**Duration**: 2-4 weeks (1-2 weeks parallel execution)  
**Impact**: 590 tokens + 50% build reduction  
**Next**: Assign developer and start Epic #366 or #367