Skip to main content

Project Reorganization Workflow

Overview​

Complete workflow for reorganizing a CODITECT project to production standards. Ensures safe, reversible restructuring with full documentation and validation.

Prerequisites​

  • Git repository initialized
  • CODITECT framework available
  • Write access to repository

Workflow Phases​

Phase 1: Analysis (30-60 min)​

Objective: Understand current state and identify issues.

Steps​

  1. Run Structure Analysis

    /agent project-structure-analyzer "Complete analysis of project structure"
    # Or
    python scripts/analyze-project-structure.py --verbose

  2. Review Analysis Report

    • Current score and grade
    • Issues by severity
    • Stray files list
    • Missing READMEs

  3. Check Naming Conventions

    /naming-check
    # Or
    python scripts/enforce-naming-conventions.py

  4. Identify Blocking Issues

    • Critical issues (must fix)
    • High priority items
    • Dependencies between fixes

  5. Document Current State

    • Screenshot/export analysis report
    • Record baseline metrics
    • Note any special considerations

Deliverables​

  • Analysis report generated
  • Current score recorded
  • Issues categorized by priority
  • Baseline metrics documented

Phase 2: Planning (30-45 min)​

Objective: Create comprehensive reorganization plan.

Steps​

  1. Create Plans Directory

    mkdir -p docs/reorganization-plans

  2. Generate Master Plan

    /organize --plan

  3. Create Per-Directory Plans

    • Root directory plan
    • docs/ plan
    • scripts/ plan
    • Other directories as needed

  4. Review and Prioritize

    • Order by dependency
    • Identify quick wins
    • Flag risky operations

Deliverables​

  • MASTER-REORGANIZATION-PLAN.md created
  • Per-directory PLAN.md files created
  • tasklist.md with checkboxes
  • Execution order defined

Phase 3: Execution (2-3 hours)​

Objective: Execute reorganization safely.

Steps​

  1. Create Backup

    git checkout -b backup/pre-reorganization
    git push origin backup/pre-reorganization
    git checkout main
    git checkout -b reorganization/$(date +%Y%m%d)

  2. Execute P0 (Critical) Plans

    /organize --execute
    # Or manually:
    git mv source destination

  3. Validate After Each Phase

    python hooks/post-reorganization-validate.py

  4. Generate Missing READMEs

    /readme-gen --missing --recursive

  5. Fix Naming Violations

    /naming-check --fix

  6. Commit Checkpoints

    git add -A
    git commit -m "reorg: [Phase description]"

Deliverables​

  • Backup branch created
  • All file moves completed
  • READMEs generated
  • Naming fixed
  • Commits created

Phase 4: Validation (30-45 min)​

Objective: Verify reorganization success.

Steps​

  1. Run Production Audit

    /production-audit
    # Or
    python scripts/production-readiness-check.py --report

  2. Verify Score Improvement

    • Compare to baseline
    • Confirm no regressions
    • Document improvements

  3. Check Cross-References

    python hooks/post-reorganization-validate.py --strict

  4. Final Review and Merge

    git add -A
    git commit -m "reorg: Complete project reorganization

    Score: XX → YY
    Grade: X → Y

    - Moved XX files
    - Generated XX READMEs
    - Fixed XX naming violations"

    git checkout main
    git merge reorganization/$(date +%Y%m%d)
    git push

Deliverables​

  • Final audit score ≥80
  • No blocking issues
  • All validations pass
  • Changes merged to main

Rollback Procedure​

If issues occur during reorganization:

Quick Rollback​

git checkout backup/pre-reorganization

Partial Rollback​

git checkout main -- path/to/restore

Full Reset​

git checkout main
git branch -D reorganization/YYYYMMDD
git reset --hard backup/pre-reorganization

Success Criteria​

MetricMinimumTarget
Score80/10095/100
README Coverage80%95%
Naming Compliance95%100%
Blocking Issues00
Stray Files00

Agents Used​

AgentPhasePurpose
project-structure-analyzerAnalysisStructure analysis
file-reorganization-orchestratorExecutionCoordinate moves
readme-generatorExecutionCreate READMEs
naming-convention-enforcerExecutionFix naming
production-readiness-auditorValidationFinal audit

Commands Used​

CommandPhasePurpose
/organizeAllMain organization command
/structureAnalysisView structure
/readme-genExecutionGenerate READMEs
/naming-checkExecutionCheck/fix naming
/production-auditValidationFinal audit

Version: 1.0.0 Created: 2026-01-02 Author: CODITECT Core Team