# Documentation Reorganization Summary
**Date**: 2025-10-11
**Purpose**: Reorganize mcp-split-plan documentation to support phase-based /specify workflow execution
**Status**: Complete
---
## Objective
Transform the mixed documentation structure (workflow-mcp + codebase-mcp + shared) into a focused, phase-based structure optimized for executing the codebase-mcp refactoring using the /specify workflow.
---
## What Changed
### Before: Mixed Structure
```
docs/mcp-split-plan/
├── 00-architecture/ # Shared architecture (both MCPs)
├── 01-codebase-mcp/ # codebase-mcp planning
├── 02-workflow-mcp/ # workflow-mcp planning (different repo!)
├── 03-orchestration/ # General orchestration patterns
├── PHASE-0-*.md # Phase 0 documents (mixed scope)
├── HANDOFF-*.md # Execution prompts
├── IMPLEMENTATION-ROADMAP.md # Overall roadmap
├── INIT-WORKFLOW-MCP.md # workflow-mcp initialization
├── CONSTITUTION-INIT-PROMPT.md
├── README.md # Executive summary
└── START-HERE.md # Quick start guide
```
**Problems**:
- Mixed codebase-mcp and workflow-mcp documentation
- No clear execution path for /specify workflow
- Difficult to find materials for specific implementation phases
- workflow-mcp docs confusing for codebase-mcp work
### After: Phase-Based Structure
```
docs/mcp-split-plan/
├── README.md # NEW: Phase-based execution guide
├── START-HERE.md # KEPT: Original quick start (reference)
│
├── phases/ # NEW: Phase-based execution folders
│ ├── phase-00-preparation/
│ │ ├── README.md # Phase overview, objectives, deliverables
│ │ ├── HANDOFF-PHASE-0B-CODEBASE-MCP.md
│ │ ├── PHASE-0-*.md # All Phase 0 planning documents
│ │ └── planning-docs/ # Copy of 01-codebase-mcp for reference
│ │
│ ├── phase-01-database-refactor/
│ │ └── README.md # Database schema refactoring guide
│ │
│ ├── phase-02-remove-tools/
│ │ └── README.md # Tool removal guide
│ │
│ ├── phase-03-multi-project/
│ │ └── README.md # Multi-project support guide
│ │
│ ├── phase-04-connection-mgmt/
│ │ └── README.md # Connection pooling guide
│ │
│ ├── phase-05-docs-migration/
│ │ └── README.md # Documentation update guide
│ │
│ ├── phase-06-performance/
│ │ └── README.md # Performance testing guide
│ │
│ └── phase-07-final-validation/
│ └── README.md # Final validation guide
│
└── _archive/ # Historical/reference materials
├── workflow-mcp/ # workflow-mcp docs (separate repo)
│ ├── 02-workflow-mcp/
│ ├── HANDOFF-PHASE-0A-WORKFLOW-MCP.md
│ ├── INIT-WORKFLOW-MCP.md
│ └── CONSTITUTION-INIT-PROMPT.md
│
├── shared-architecture/ # Shared architecture docs
│ ├── 00-architecture/
│ └── 03-orchestration/
│
├── 01-codebase-mcp/ # Original planning docs
│ ├── FINAL-IMPLEMENTATION-PLAN.md
│ ├── constitution.md
│ ├── ARCHITECTURAL-REVIEW.md
│ └── ... (all original files)
│
└── IMPLEMENTATION-ROADMAP.md
```
**Benefits**:
- Clear separation: codebase-mcp vs workflow-mcp
- Phase-based execution path for /specify workflow
- Self-contained phase folders with all needed materials
- Easy to find documentation for current phase
- Archived reference materials remain accessible
---
## File Movements
### Moved to Archive
**workflow-mcp specific (separate repo)**:
- `02-workflow-mcp/` → `_archive/workflow-mcp/02-workflow-mcp/`
- `HANDOFF-PHASE-0A-WORKFLOW-MCP.md` → `_archive/workflow-mcp/`
- `INIT-WORKFLOW-MCP.md` → `_archive/workflow-mcp/`
- `CONSTITUTION-INIT-PROMPT.md` → `_archive/workflow-mcp/`
**Shared architecture (reference)**:
- `00-architecture/` → `_archive/shared-architecture/00-architecture/`
- `03-orchestration/` → `_archive/shared-architecture/03-orchestration/`
**Original planning docs (reference)**:
- `01-codebase-mcp/` → `_archive/01-codebase-mcp/`
- `IMPLEMENTATION-ROADMAP.md` → `_archive/IMPLEMENTATION-ROADMAP.md`
### Moved to Phase Folders
**Phase 00 (Preparation)**:
- `HANDOFF-PHASE-0B-CODEBASE-MCP.md` → `phases/phase-00-preparation/`
- `PHASE-0-ARCHITECTURAL-REVIEW.md` → `phases/phase-00-preparation/`
- `PHASE-0-FINAL-PLAN.md` → `phases/phase-00-preparation/`
- `PHASE-0-FOUNDATION.md` → `phases/phase-00-preparation/`
- `PHASE-0-REVIEW.md` → `phases/phase-00-preparation/`
- Copy of `01-codebase-mcp/` → `phases/phase-00-preparation/planning-docs/`
### Created New Files
**Root README**:
- `README.md` - Complete rewrite with phase-based execution guide
**Phase READMEs (8 new files)**:
- `phases/phase-00-preparation/README.md`
- `phases/phase-01-database-refactor/README.md`
- `phases/phase-02-remove-tools/README.md`
- `phases/phase-03-multi-project/README.md`
- `phases/phase-04-connection-mgmt/README.md`
- `phases/phase-05-docs-migration/README.md`
- `phases/phase-06-performance/README.md`
- `phases/phase-07-final-validation/README.md`
**This document**:
- `REORGANIZATION-SUMMARY.md` - You're reading it!
---
## Phase Mapping
The 8 phases map to the original 12 phases from FINAL-IMPLEMENTATION-PLAN.md:
| New Phase | Original Phases | Scope |
|-----------|----------------|-------|
| **Phase 00: Preparation** | Phase 0-1 | Prerequisites, baseline, branch setup |
| **Phase 01: Database Refactor** | Phase 2 | Schema changes (9 tables dropped) |
| **Phase 02: Remove Tools** | Phases 3-6 | Remove 14 non-search tools |
| **Phase 03: Multi-Project** | Phase 7 | Add project_id parameter |
| **Phase 04: Connection Mgmt** | Phase 8 | Connection pooling with LRU |
| **Phase 05: Docs/Migration** | Phases 9-10 | Documentation updates |
| **Phase 06: Performance** | Phase 11 | Performance testing |
| **Phase 07: Final Validation** | Phase 12 | MCP compliance, security, release |
---
## Phase README Contents
Each phase README includes:
### Standard Sections
1. **Metadata**: Phase number, duration, dependencies, status
2. **Objective**: Clear statement of what this phase achieves
3. **Scope**: What's included and NOT included (boundaries)
4. **Prerequisites**: What must be complete before starting
5. **Key Deliverables**: Specific artifacts produced
6. **Acceptance Criteria**: Checklist for completion
7. **Rollback Procedure**: How to undo if needed
8. **Execution Notes**: Technical details and gotchas
9. **Next Phase**: What comes after completion
10. **Related Documentation**: Links to planning docs
### Phase-Specific Content
Each README is tailored to its phase:
- **Phase 00**: Prerequisites validation, baseline collection
- **Phase 01**: Migration scripts, schema validation
- **Phase 02**: Tool removal strategy, code cleanup
- **Phase 03**: project_id validation, workflow-mcp integration
- **Phase 04**: Connection pool design, LRU eviction
- **Phase 05**: Documentation structure, migration guide
- **Phase 06**: Performance benchmarks, stress tests
- **Phase 07**: MCP inspector, security audit, release checklist
---
## How to Use New Structure
### For /specify Workflow Execution
1. **Start with Phase 00**:
```bash
cd /Users/cliffclarke/Claude_Code/codebase-mcp/docs/mcp-split-plan/phases/phase-00-preparation
cat README.md
```
2. **Run /specify**:
- Use phase README content as spec input
- Reference planning-docs/FINAL-IMPLEMENTATION-PLAN.md for technical details
- Run `/specify`, `/plan`, `/tasks`, `/implement`
3. **Complete Phase 00**:
- Verify all acceptance criteria met
- Commit changes
- Push branch and tags
4. **Move to Phase 01**:
```bash
cd ../phase-01-database-refactor
cat README.md
```
5. **Repeat** for each phase until Phase 07 complete
### For Direct Execution (Without /specify)
1. **Use HANDOFF prompt**:
```bash
cd phases/phase-00-preparation
cat HANDOFF-PHASE-0B-CODEBASE-MCP.md
# Copy-paste into new Claude Code chat
```
2. **Claude executes directly** following the detailed plan
### For Reference/Planning
1. **Review archived planning docs**:
```bash
cd _archive/01-codebase-mcp
cat FINAL-IMPLEMENTATION-PLAN.md
```
2. **Review architecture**:
```bash
cd _archive/shared-architecture/00-architecture
cat overview.md
```
---
## Key Improvements
### 1. Clear Focus on codebase-mcp
**Before**: Mixed workflow-mcp and codebase-mcp documentation
**After**: codebase-mcp focused, workflow-mcp clearly archived
### 2. Phase-Based Execution
**Before**: Flat structure with no execution path
**After**: 8 sequential phases with clear dependencies
### 3. Self-Contained Phases
**Before**: Need to search multiple directories for context
**After**: Each phase folder has everything needed
### 4. /specify Workflow Compatible
**Before**: Not designed for /specify workflow
**After**: Each phase README optimized for /specify input
### 5. Preserved History
**Before**: N/A (first organization)
**After**: All original docs archived and accessible
---
## Timeline Estimate
Based on phase READMEs:
| Phase | Duration | Cumulative |
|-------|----------|------------|
| Phase 00: Preparation | 2-3 hours | 3h |
| Phase 01: Database | 4-6 hours | 9h |
| Phase 02: Remove Tools | 8-12 hours | 21h |
| Phase 03: Multi-Project | 6-8 hours | 29h |
| Phase 04: Connection Mgmt | 4-6 hours | 35h |
| Phase 05: Docs/Migration | 3-4 hours | 39h |
| Phase 06: Performance | 4-6 hours | 45h |
| Phase 07: Final Validation | 2-3 hours | 48h |
| **TOTAL** | **37-48 hours** | **~1 week** |
---
## Success Criteria (Overall Refactoring)
After completing all 7 phases:
### Functional Requirements
- [ ] Only 2 MCP tools: `index_repository`, `search_code`
- [ ] Multi-project support with database-per-project
- [ ] project_id validation (`^[a-z0-9-]{1,50}$`)
- [ ] Optional workflow-mcp integration
- [ ] Connection pooling with LRU eviction
### Performance Requirements
- [ ] Indexing: <60s for 10k files (p95)
- [ ] Search: <500ms latency (p95)
- [ ] No regression from baseline (within 10%)
### Quality Requirements
- [ ] Type-safe: mypy --strict passes
- [ ] Test coverage: >80%
- [ ] MCP protocol compliant (mcp-inspector)
- [ ] Security: 0 critical vulnerabilities
### Documentation Requirements
- [ ] README.md updated
- [ ] Migration guide (v1.x → v2.0)
- [ ] Configuration guide
- [ ] Architecture documentation
### Release Requirements
- [ ] Version: 2.0.0
- [ ] CHANGELOG.md updated
- [ ] Git tag: v2.0.0
- [ ] Release notes drafted
---
## Files Summary
### Created (10 files)
- `README.md` (root - completely rewritten)
- `phases/phase-00-preparation/README.md`
- `phases/phase-01-database-refactor/README.md`
- `phases/phase-02-remove-tools/README.md`
- `phases/phase-03-multi-project/README.md`
- `phases/phase-04-connection-mgmt/README.md`
- `phases/phase-05-docs-migration/README.md`
- `phases/phase-06-performance/README.md`
- `phases/phase-07-final-validation/README.md`
- `REORGANIZATION-SUMMARY.md` (this file)
### Moved (41+ files)
- 10+ files to `_archive/workflow-mcp/`
- 10+ files to `_archive/shared-architecture/`
- 11+ files to `_archive/01-codebase-mcp/`
- 5 files to `phases/phase-00-preparation/`
- 11+ files copied to `phases/phase-00-preparation/planning-docs/`
- 1 file to `_archive/IMPLEMENTATION-ROADMAP.md`
### Kept in Place (1 file)
- `START-HERE.md` (original quick start guide, still useful as reference)
---
## Verification
To verify the reorganization is complete:
```bash
cd /Users/cliffclarke/Claude_Code/codebase-mcp/docs/mcp-split-plan
# Check structure
tree -L 2
# Expected output:
# .
# ├── README.md
# ├── REORGANIZATION-SUMMARY.md
# ├── START-HERE.md
# ├── _archive
# │ ├── 01-codebase-mcp
# │ ├── IMPLEMENTATION-ROADMAP.md
# │ ├── shared-architecture
# │ └── workflow-mcp
# └── phases
# ├── phase-00-preparation
# ├── phase-01-database-refactor
# ├── phase-02-remove-tools
# ├── phase-03-multi-project
# ├── phase-04-connection-mgmt
# ├── phase-05-docs-migration
# ├── phase-06-performance
# └── phase-07-final-validation
# Count phase READMEs
find phases/ -name "README.md" | wc -l
# Expected: 8
# Count archived docs
find _archive/ -type f | wc -l
# Expected: 40+
```
---
## Next Steps
1. **Verify structure**: Check tree output matches expected
2. **Review README files**: Ensure accuracy and completeness
3. **Start Phase 00**: Navigate to `phases/phase-00-preparation/`
4. **Execute /specify workflow**: Follow phase-based approach
5. **Complete refactoring**: Work through all 7 phases
---
## Questions or Issues
- **Can't find a document?** Check `_archive/` directories
- **Phase scope unclear?** Read the phase README and planning-docs
- **Need overall context?** Read root README.md and START-HERE.md
- **Want original roadmap?** See `_archive/IMPLEMENTATION-ROADMAP.md`
---
## Conclusion
The documentation has been successfully reorganized to support phase-based /specify workflow execution. The new structure:
1. **Focuses on codebase-mcp** (this repo)
2. **Archives workflow-mcp docs** (separate repo)
3. **Provides 8 clear phases** with dependencies and deliverables
4. **Enables /specify workflow** with self-contained phase folders
5. **Preserves all history** in accessible archive
**Status**: Reorganization Complete ✅
**Ready for**: Phase 00 Execution
**Last Updated**: 2025-10-11
---
**Ready to begin? Start with `phases/phase-00-preparation/README.md`!**
