Skip to main content

CODITECT Reorganization Plan Standard

Purpose​

This standard defines the structure and process for creating folder and file reorganization plans within CODITECT projects, ensuring safe, reversible, and well-documented restructuring.

Scope​

Applies to:

  • Project-wide reorganizations
  • Directory-specific restructuring
  • File migrations between locations
  • Customer projects using CODITECT framework

1. Core Principles​

1.1 Safety First​

PrincipleImplementation
ReversibleAlways use git mv, never delete without backup
DocumentedEvery move tracked in plan
ValidatedTest after each phase
ApprovedUser approval before execution

1.2 Planning Hierarchy​

docs/reorganization-plans/
├── MASTER-REORGANIZATION-PLAN.md    # Overview and priorities
├── COMPLETION-CHECKLIST.md          # Final validation
├── root/
│   ├── PLAN.md                      # Root directory plan
│   └── TASKLIST.md                  # Root tasks
├── docs/
│   ├── PLAN.md                      # docs/ directory plan
│   └── TASKLIST.md                  # docs/ tasks
└── [directory-name]/
    ├── PLAN.md                      # Directory-specific plan
    └── TASKLIST.md                  # Directory-specific tasks

2. Master Plan Structure​

2.1 Required Sections​

# Master Reorganization Plan

## Executive Summary
- Current state score
- Target state score
- Total files to move
- Estimated time

## Scope
- Directories included
- Directories excluded
- Out of scope items

## Priorities
| Priority | Directory | Complexity | Time |
|----------|-----------|------------|------|
| P0 | root/ | Low | 30m |
| P0 | docs/ | High | 90m |
| P1 | scripts/ | Medium | 45m |

## Cross-Cutting Standards
- Naming conventions to apply
- README requirements
- Frontmatter requirements

## Execution Order
1. Backup current state
2. Create feature branch
3. Execute P0 directories
4. Validate P0
5. Execute P1 directories
6. Validate P1
7. Final validation
8. Merge and cleanup

## Rollback Plan
How to revert if issues occur.

## Success Criteria
- [ ] All files moved per plans
- [ ] All READMEs present
- [ ] No broken links
- [ ] Tests pass
- [ ] User approval

3. Directory Plan Structure​

3.1 Required Sections​

# [Directory Name] Reorganization Plan

## Overview
Brief description of this directory's purpose.

## Current State

### Directory Structure

current/ ├── file1.md ├── misplaced-file.py └── subdirectory/


### Issues Identified
| Issue | Severity | Description |
|-------|----------|-------------|
| Stray file | Medium | `misplaced-file.py` doesn't belong |
| Missing README | Low | No README.md present |

### Current Metrics
- Files: 15
- Subdirectories: 3
- README coverage: 33%

## Target State

### Target Structure

target/ ├── README.md ├── file1.md └── subdirectory/ └── README.md


### Target Metrics
- Files: 14 (1 moved out)
- Subdirectories: 3
- README coverage: 100%

## Actions

### Files to Move
| From | To | Reason |
|------|----|--------|
| `./misplaced-file.py` | `../scripts/` | Script belongs in scripts/ |

### Files to Create
| File | Purpose |
|------|---------|
| `README.md` | Directory documentation |
| `subdirectory/README.md` | Subdirectory documentation |

### Files to Rename
| From | To | Reason |
|------|----|--------|
| `oldname.md` | `new-name.md` | Naming convention |

### Files to Delete
| File | Reason | Backup Location |
|------|--------|-----------------|
| (None) | - | - |

## Execution Steps

### Phase 1: Preparation
1. [ ] Verify current state matches documented
2. [ ] Create backup branch

### Phase 2: Moves
1. [ ] `git mv misplaced-file.py ../scripts/`
2. [ ] Verify file in new location

### Phase 3: Creates
1. [ ] Create README.md from template
2. [ ] Create subdirectory/README.md

### Phase 4: Validation
1. [ ] All files in correct locations
2. [ ] All READMEs present
3. [ ] No broken links
4. [ ] Git status clean

## Rollback
```bash
git checkout backup-branch -- .

Dependencies​

  • Depends on: None
  • Blocks: None

---

## 4. Task List Structure

### 4.1 Checkbox Format

```markdown
# [Directory Name] Reorganization Tasklist

## Status
- Total Tasks: 15
- Completed: 0
- In Progress: 0
- Blocked: 0

## Phase 1: Preparation
- [ ] Document current state
- [ ] Create backup branch
- [ ] Verify prerequisites

## Phase 2: File Operations
- [ ] Move `file1.md` to `destination/`
- [ ] Move `file2.md` to `destination/`
- [ ] Rename `oldname.md` to `new-name.md`

## Phase 3: Creation
- [ ] Create `README.md`
- [ ] Add frontmatter to existing files

## Phase 4: Validation
- [ ] Verify all moves completed
- [ ] Check for broken links
- [ ] Run automated validation
- [ ] Get user approval

## Phase 5: Cleanup
- [ ] Update cross-references
- [ ] Commit changes
- [ ] Delete backup branch (after merge)

5. Scoring System​

5.1 Production Readiness Score​

ComponentMax PointsCriteria
Structure25Follows directory standard
Naming20Follows naming conventions
README coverage20README in every directory
No stray files15Files in correct locations
Frontmatter10Proper metadata
Documentation10Up-to-date docs

5.2 Score Interpretation​

ScoreGradeStatus
90-100AProduction-ready
80-89BMinor improvements needed
70-79CModerate reorganization needed
60-69DSignificant work required
<60FMajor restructuring required

6. Templates​

6.1 Master Plan Template​

See templates/REORGANIZATION-PLAN-TEMPLATE.md

6.2 Directory Plan Template​

---
type: plan
title: [Directory] Reorganization Plan
status: draft
priority: P0
estimated_time: 30m
---

# [Directory] Reorganization Plan

## Overview

[Brief description]

## Current State

### Structure

[current tree]


### Issues
| Issue | Severity | Description |
|-------|----------|-------------|

## Target State

### Structure

[target tree]


## Actions

### Files to Move
| From | To | Reason |
|------|----|--------|

### Files to Create
| File | Purpose |
|------|---------|

## Execution

- [ ] Step 1
- [ ] Step 2
- [ ] Step 3

## Validation

- [ ] All files moved
- [ ] READMEs present
- [ ] No broken links

7. Execution Workflow​

7.1 Pre-Execution​

# 1. Create backup
git checkout -b backup/reorganization-$(date +%Y%m%d)
git push origin backup/reorganization-$(date +%Y%m%d)

# 2. Create working branch
git checkout main
git checkout -b reorganization/$(date +%Y%m%d)

# 3. Verify current state
/organize --analyze

7.2 During Execution​

# Always use git mv
git mv old-location/file.md new-location/file.md

# Commit frequently
git add -A
git commit -m "reorg: Move [file] to [location]"

# Validate after each phase
/structure --validate

7.3 Post-Execution​

# Final validation
/organize --validate

# Update documentation
/readme-gen --missing

# Commit and push
git add -A
git commit -m "reorg: Complete [directory] reorganization"
git push origin reorganization/$(date +%Y%m%d)

# Create PR
gh pr create --title "Reorganization: [Directory]" --body "..."

8. Validation Checklist​

8.1 Per-Directory Validation​

  • All planned moves completed
  • All planned creates completed
  • No unplanned changes
  • README.md present
  • Structure matches target
  • No broken internal links
  • Frontmatter valid (where required)

8.2 Master Validation​

  • All directory plans completed
  • Cross-directory references updated
  • CI/CD passes
  • No regressions introduced
  • Documentation updated
  • User approval obtained

9. Automation​

9.1 Available Commands​

# Analyze current state
/organize --analyze

# Generate reorganization plan
/organize --plan

# Validate structure
/structure --validate

# Generate missing READMEs
/readme-gen --missing

# Check naming conventions
/naming-check

# Run production readiness audit
/production-audit

9.2 Scripts​

# Analyze project structure
python scripts/analyze-project-structure.py

# Validate reorganization
python scripts/validate-reorganization.py

# Generate reorganization report
python scripts/reorganization-report.py

10. Best Practices​

10.1 Do's​

  • Document before changing
  • Use git mv for all moves
  • Commit frequently
  • Validate after each phase
  • Keep backup branch until merge
  • Get user approval for deletions

10.2 Don'ts​

  • Never delete without backup
  • Don't batch too many changes
  • Don't skip validation
  • Don't modify production without PR
  • Don't assume - verify

References​

Version: 1.0.0 Status: Active Owner: CODITECT Core Team Last Updated: 2026-01-02