Skip to main content

CODITECT Core Restructuring - Project Plan

Executive Summary​

Strategic Direction: Composition over Monolith Recommendation: STRONG GO (95% confidence) Timeline: 2 weeks (20 hours, single engineer) Risk: LOW (easy rollback at every checkpoint)

The Transformation​

Extract 558.63MB (97.5%) of CODITECT-core into 7 optional submodules, reducing minimal core to 14.37MB essential runtime.

Current State (Monolith)​

  • 573MB forced download
  • 45-second clone on fast network, 5 minutes on slow
  • Mixed concerns (runtime + docs + tools + training)
  • No flexibility in what to install

Target State (Composition)​

  • 14.37MB minimal core (97.5% reduction)
  • 3-second clone on fast network, 15s on slow
  • Users compose only what they need
  • Clear separation of concerns

Key Benefits​

Performance​

  • 93% faster clone times
  • 97% CI/CD bandwidth reduction (50GB/month → 1.5GB/month)
  • 97.5% size reduction for minimal users

User Experience​

  • 5 composition layers (Minimal → User → Documentation → Developer → Docker)
  • Clear upgrade path
  • No forced downloads of unused content

Maintainability​

  • Core changes isolated from docs/tools
  • Clear separation of concerns
  • Independent evolution of submodules

Architecture Overview​

Minimal Core (14.37MB - Runtime Only)​

What Stays​

coditect-core/
├── agents/                    # 1.2MB - 52 AI agent definitions
├── commands/                  # 1.2MB - 81 slash command implementations
├── skills/                    # 3.7MB - all skills with 254+ assets
├── scripts/                   # 2.4MB - 21 automation scripts
├── lib/                       # 1.3MB - Runtime LLM providers
├── MEMORY-CONTEXT/           # 2.8MB - Session persistence
├── config/                   # 812KB - Framework configuration
└── CODITECT-CORE-STANDARDS/  # 816KB - Production standards

Why These Stay​

  • Required for framework execution (can't run agents without agents/)
  • Runtime state and configuration
  • Production quality enforcement

Extracted Submodules (558.63MB)​

SubmoduleSizePurposeExtract ToPriority
user-training/496KBTraining, certification, templatesCODITECT-trainingP0
Docker/16KBDistribution packaging (Ubuntu + XFCE)CODITECT-Docker-distP0
tools/100MBVite dev server, Playwright testingCODITECT-toolsP0
prompts/180KBResearch prompt templatesCODITECT-promptsP0
archive/600KBDeprecated filesDELETEP0
docs/31MB60+ reference guidesCODITECT-documentationP1
tests/328KBTest suiteCODITECT-testingP1
hooks/220KBGit automationCODITECT-hooksP1

Total Extracted: 558.63MB (97.5% of current repository)

Composition Layers​

Users select the layer matching their needs:

Layer 0: Minimal Core (14.37MB)​

For: Framework operators, API usage, embedded systems

Install​

git clone https://github.com/coditect-ai/coditect-core.git
# Framework ready in 3 seconds

You Get​

  • all agents, all commands, all skills
  • Full orchestration and automation
  • Session persistence

Layer 1: User Edition (14.85MB)​

For: Learners, typical users, certification seekers

Install​

git clone --recurse-submodules https://github.com/coditect-ai/coditect-rollout-master.git
cd submodules/core/coditect-core
git submodule init coditect-training
git submodule update

Additional: Training materials, certification program, sample templates

Layer 2: Documentation Edition (45.85MB)​

For: Power users needing comprehensive reference

Additional: 60+ guides, architecture diagrams, deployment documentation

Layer 3: Developer Edition (246.73MB)​

For: Contributors, component developers, UI work

Additional: Component Viewer (Vite), Playwright testing, git hooks, prompts

Layer 4: Docker Edition (246.75MB)​

For: Docker users needing containerized environment

Additional: Ubuntu 22.04 + XFCE + VNC desktop access

Technical Validation​

Zero Runtime Dependencies (CRITICAL)​

Grep Analysis Results​

grep -r "from tools" --include="*.py" agents/ commands/ scripts/
# Result: NO MATCHES

grep -r "import tools" --include="*.py" agents/ commands/ scripts/
# Result: NO MATCHES

grep -r "docker/" --include="*.py" scripts/
# Result: NO MATCHES

Conclusion: 100% safe to extract all supporting directories

Path References Found (Non-Breaking)​

  • 4 template strings in scripts/ (docs/ paths)
  • 1 template reference in scripts/ (user-training/)
  • All easily fixed with fallback logic

Docker Purpose Clarification​

Docker/ Contents​

  • Dockerfile (6.9KB) - Ubuntu 22.04 + XFCE + VNC + zsh + Claude Code
  • Docker-compose.yml (2.7KB) - Development environment orchestration
  • entrypoint.sh (3.3KB) - Container startup automation

Purpose: Turnkey development environment for CODITECT users (NOT core development)

Conclusion: Extract to CODITECT-Docker-dist (16KB, ZERO risk)

Implementation Roadmap​

Week 1: Low-Risk Batch (P0 - Must Do)​

Timeline: December 6-13, 2025 Effort: 8 hours Engineer: 1 (with git expertise)

Tasks​

Day 1-2: Repository Setup + Low-Risk Extractions (4 hours)​

  1. Create 7 GitHub repositories:

    • CODITECT-training
    • CODITECT-Docker-dist
    • CODITECT-tools
    • CODITECT-prompts
    • CODITECT-documentation
    • CODITECT-testing
    • CODITECT-hooks

  2. Setup git-filter-repo for history preservation

  3. Extract low-risk directories:

    • user-training/ → CODITECT-training (45 min)
    • Docker/ → CODITECT-Docker-dist (45 min)
    • prompts/ → CODITECT-prompts (30 min)
    • archive/ - DELETE (10 min)

Day 3-4: Medium-Risk Extraction (3 hours)​

  1. Extract tools/ → CODITECT-tools (2 hours)
  2. Update references in documentation (1 hour)

Day 5: Validation (1 hour)​

  1. Test all agents/commands/scripts
  2. Verify composition layers work
  3. Document any issues

Checkpoint: 131MB extracted, 442MB core remaining

Week 2: High-Value Extractions (P1 - Should Do)​

Timeline: December 16-20, 2025 Effort: 12 hours Engineer: 1 (with git expertise)

Tasks​

Day 1-2: High-Risk Extraction (6 hours)​

  1. Extract docs/ → CODITECT-documentation (4 hours)
  2. Update path references in scripts/ (1 hour)
  3. Test all documentation links (1 hour)

Day 3: Optional Extractions (4 hours)​

  1. Extract tests/ → CODITECT-testing (2 hours)
  2. Extract hooks/ → CODITECT-hooks (2 hours)

Day 4: Integration Testing (1 hour)​

  1. Test all composition layers
  2. Verify path references work
  3. Final validation

Day 5: Documentation and Deployment (1 hour)​

  1. Create DISTRIBUTION.md (composition guide)
  2. Update all READMEs
  3. Update CI/CD pipelines
  4. Public announcement

Checkpoint: 558.63MB extracted, 14.37MB minimal core achieved

Risk Assessment​

Extraction Risk Matrix​

ExtractionTechnical RiskConfidenceRollback Time
archive/ZERO100%N/A (delete)
user-training/ZERO98%5 min
Docker/ZERO98%5 min
tools/ZERO98%10 min
prompts/LOW95%5 min
tests/LOW92%30 min
hooks/LOW92%30 min
docs/MEDIUM88%1 hour

Overall Confidence: 95% (weighted average)

Risk Mitigation​

Multiple Validation Checkpoints​

  • Week 1 checkpoint after low-risk extractions
  • Week 2 checkpoint after high-value extractions
  • Testing after each extraction

Easy Rollback Procedures​

  • git reflog tracking all changes
  • Each extraction independent (can rollback individually)
  • No destructive operations until validated

Path Reference Safety​

  • Fallback logic for missing paths
  • Comprehensive testing of all references
  • Documentation of all changes

Success Metrics​

Quantitative Targets​

MetricCurrentTargetSuccess Criteria
Repository Size573MB14.37MB✅ <15MB
Clone Time (fast)45s3s✅ <5s
Clone Time (slow)5min15s✅ <20s
CI/CD Checkout573MB14.7MB✅ <20MB
Submodule Count07✅ 7 repos created

Qualitative Targets​

Composition Flexibility​

  • ✅ Users can install minimal core only
  • ✅ Users can compose any layer combination
  • ✅ Clear documentation for each layer

Maintainability​

  • ✅ Core changes isolated from docs/tools
  • ✅ Clear separation of concerns
  • ✅ Independent evolution of submodules

Developer Experience​

  • ✅ Faster git operations
  • ✅ Clearer onboarding
  • ✅ Better CI/CD performance

Business Case​

Investment Required​

Time​

  • Week 1: 8 hours (repository creation, low-risk extractions)
  • Week 2: 12 hours (high-value extractions, documentation)
  • Total: 20 hours (2.5 days)

Resources​

  • 1 engineer with git expertise
  • git-filter-repo tool (open source)
  • GitHub repository creation access

Cost​

  • Engineering time: ~$4,000 (20 hours × $200/hour)
  • Infrastructure: $0 (GitHub free for open source)
  • Tools: $0 (git-filter-repo is free)

Total: $4,000 one-time investment

Expected Benefits (Annual)​

Clone Time Reduction​

  • Current: 45s (fast) / 5min (slow)
  • Target: 3s (fast) / 15s (slow)
  • Improvement: 93% faster

Repository Size Reduction​

  • Current: 573MB forced download
  • Target: 14.37MB minimal (97.5% smaller)
  • User Choice: Compose only what's needed

CI/CD Bandwidth Reduction​

  • Current: 50GB/month (100 runs × 573MB)
  • Target: 1.5GB/month (100 runs × 14.7MB)
  • Savings: 97% (48.5GB/month)

Developer Productivity​

  • Faster git operations (smaller repo)
  • Clearer onboarding (obvious layers)
  • Better caching (smaller checkouts)

Quality Gates​

Checkpoint 1: Week 1 Completion​

Must Pass​

  • ✅ All low-risk extractions complete (user-training/, Docker/, tools/, prompts/, archive/)
  • ✅ 131MB extracted from core
  • ✅ All agents/commands execute without errors
  • ✅ Basic composition test (minimal core + one submodule)

Blockers​

  • Any agent/command failures
  • Path reference errors
  • Git history corruption

Checkpoint 2: Week 2 Completion​

Must Pass​

  • ✅ All high-value extractions complete (docs/, tests/, hooks/)
  • ✅ 558.63MB extracted, 14.37MB core achieved
  • ✅ All 5 composition layers work
  • ✅ CI/CD pipelines updated and tested

Blockers​

  • Documentation link failures
  • Test suite failures
  • Integration issues between layers

Final Validation​

Must Pass​

  • ✅ DISTRIBUTION.md created and reviewed
  • ✅ All 7 submodule READMEs complete
  • ✅ Success metrics achieved (see table above)
  • ✅ Public announcement ready

Component Activation Strategy​

This restructuring does NOT change component activation patterns. Components remain in their original categories:

  • agents/ - Still requires activation per COMPONENT-ACTIVATION-GUIDE.md
  • commands/ - Still requires activation (11 default activated)
  • skills/ - Still requires activation
  • scripts/ - Direct execution (no activation required)

Post-restructuring activation​

# Same workflow as before
python3 scripts/update-component-activation.py activate agent orchestrator \
  --reason "Core restructuring project coordination"

Dependencies​

Analysis Documents​

Primary References​

  1. README-REWRITE-COMPOSITION-ARCHITECTURE.md - Complete composition design (18,000+ words)
  2. README-REWRITE-GAP-ANALYSIS.md - Gap analysis and validation (12,000+ words)
  3. README-REWRITE-SUMMARY.md - Executive summary and business case

Technical Dependencies​

Tools​

  • git-filter-repo (history-preserving extraction)
  • GitHub CLI (repository creation)
  • Python 3.10+ (script updates)

Skills​

  • Git submodule management
  • Repository history preservation
  • GitHub Actions CI/CD updates

Communication Plan​

Week 1 Status Updates​

Frequency: Daily (end of day) Format: Markdown update in TASKLIST-CORE-RESTRUCTURING.md Audience: Project stakeholders

Content​

  • Tasks completed today
  • Checkpoint status
  • Any blockers or issues
  • Next day plan

Week 2 Status Updates​

Frequency: Daily (end of day) Format: Same as Week 1 Additional: Integration test results

Final Announcement​

Timing: After all validations pass

Channels​

  • GitHub Discussions
  • Documentation update
  • Release notes

Content​

  • Composition architecture overview
  • Migration guide for existing users
  • Benefits summary
  • Links to DISTRIBUTION.md

Rollback Procedures​

Individual Extraction Rollback​

If any extraction fails validation​

# 1. Identify failed extraction commit
git log --oneline | head -5

# 2. Revert to before extraction
git revert <commit-hash>

# 3. Verify restoration
git status
python3 scripts/verify-core-integrity.py

# 4. Document issue
# Update TASKLIST-CORE-RESTRUCTURING.md with failure details

Full Project Rollback​

If Week 1 checkpoint fails​

# 1. Reset to pre-restructuring state
git log --grep="Start core restructuring" --oneline
git reset --hard <commit-before-restructuring>

# 2. Verify clean state
git status
git submodule status

# 3. Document learnings
# Create RESTRUCTURING-ROLLBACK-ANALYSIS.md

Post-Completion Tasks​

Documentation Updates​

Required​

  1. Update CODITECT-core/README.md to describe minimal core
  2. Create DISTRIBUTION.md composition guide
  3. Update 7 submodule READMEs
  4. Update master repository documentation

Timeline: 2 hours after final validation

CI/CD Updates​

Required​

  1. Update GitHub Actions workflows to use minimal core
  2. Add submodule checkout steps where needed
  3. Test all pipelines with new structure

Timeline: 3 hours after documentation updates

User Communication​

Required​

  1. Migration guide for existing users
  2. Composition layer selection guide
  3. FAQ document

Timeline: 2 hours after CI/CD updates

Lessons Learned (To Be Updated)​

This section will be populated during and after implementation​

Week 1 Learnings​

  • TBD

Week 2 Learnings​

  • TBD

Overall Retrospective​

  • TBD

References​

Internal Documentation​

External Resources​

Status: Approved - Ready for Implementation Approval Date: December 6, 2025 Approver: Hal Casteel, Founder/CEO/CTO Next Action: Begin Week 1 repository creation and low-risk extractions

Last Updated: December 6, 2025 Version: 0.1.0