Project Organization Skill

Overview

Comprehensive skill for organizing CODITECT projects to production standards. Combines structure analysis, safe file reorganization, documentation generation, and validation into a cohesive workflow.

When to Use

Use this skill when:

• Starting a new project that needs organization
• Preparing a project for production deployment
• Cleaning up accumulated organizational debt
• Onboarding an existing project to CODITECT standards
• Conducting periodic organizational maintenance

Capabilities

Level 1: Quick Organization

• Identify obvious organizational issues
• Generate basic reorganization suggestions
• Create missing root-level README

Level 2: Standard Organization

• Complete structure analysis
• Generate reorganization plan
• Move files to correct locations
• Generate all missing READMEs
• Fix naming convention violations

Level 3: Production Readiness

• Full production readiness audit
• Multi-phase reorganization execution
• Cross-reference validation
• CI/CD configuration review
• Comprehensive documentation

Workflow

1. Analysis
   └── Run project-structure-analyzer
   └── Generate analysis report
   └── Calculate current score

2. Planning
   └── Create reorganization plans
   └── Prioritize by severity
   └── Estimate effort

3. Execution
   └── Create backup
   └── Execute file moves
   └── Generate documentation
   └── Fix naming issues

4. Validation
   └── Verify structure
   └── Check references
   └── Run production audit
   └── Calculate new score

Usage

Quick Start

# Analyze current state
/organize --analyze

# Generate and execute plan
/organize --execute

# Validate results
/organize --validate

Detailed Usage

# Full organization workflow
/agent project-structure-analyzer "Analyze project"
# Review analysis, then:
/agent file-reorganization-orchestrator "Execute reorganization"
# Generate docs:
/agent readme-generator "Create missing READMEs"
# Final check:
/agent production-readiness-auditor "Validate production readiness"

Standards Applied

This skill enforces:

• DIRECTORY-STRUCTURE-STANDARD.md
• FILE-NAMING-CONVENTIONS.md
• README-STANDARD.md
• PRODUCTION-READINESS-CHECKLIST.md

Related Agents

Agent	Role in Skill
project-structure-analyzer	Analysis phase
file-reorganization-orchestrator	Execution phase
readme-generator	Documentation phase
naming-convention-enforcer	Naming fixes
production-readiness-auditor	Validation phase

Output Artifacts

• docs/reorganization-plans/ - All reorganization plans
• Analysis reports
• README.md files in all directories
• Production readiness audit report

Success Criteria

Level	Criteria
Level 1	Score improves by ≥10 points
Level 2	Score ≥80/100, 95% README coverage
Level 3	Score ≥95/100, Grade A, Production Ready

Example

User: I need to organize this project for production

Skill Application:

1. Analysis Phase
   /agent project-structure-analyzer "Full analysis"
   Result: Score 65/100 (Grade D)

2. Planning Phase
   Created: docs/reorganization-plans/
   - MASTER-REORGANIZATION-PLAN.md
   - root/PLAN.md
   - docs/PLAN.md

3. Execution Phase
   /agent file-reorganization-orchestrator "Execute plans"
   Moved: 15 files
   Renamed: 8 files

4. Documentation Phase
   /agent readme-generator "Generate all"
   Created: 12 README files

5. Validation Phase
   /agent production-readiness-auditor "Final audit"
   Result: Score 94/100 (Grade A-)

Improvement: +29 points, Production Ready ✓

Success Output

When successful, this skill MUST output:

✅ SKILL COMPLETE: project-organization

Completed:
- [x] Project structure analyzed (score: X → Y)
- [x] Reorganization plans generated in docs/reorganization-plans/
- [x] File moves executed (N files relocated)
- [x] README files generated (M directories documented)
- [x] Naming violations fixed (K files renamed)
- [x] Production readiness validated (Grade: X)

Outputs:
- docs/reorganization-plans/MASTER-REORGANIZATION-PLAN.md
- docs/reorganization-plans/{directory}/PLAN.md (per directory)
- README.md files in all key directories
- Production readiness audit report
- Before/after structure comparison

Final Score: Y/100 (Grade X) | Improvement: +Z points

Completion Checklist

Before marking this skill as complete, verify:

• Structure analysis completed with score calculated
• All reorganization plans reviewed and approved
• File moves executed without breaking references
• All directories have appropriate README files
• Naming convention violations resolved
• Production readiness audit shows Grade B or higher
• No broken imports or paths after reorganization
• Git history preserved for moved files (git mv used)
• Documentation updated to reflect new structure
• Final score ≥80/100 (Grade B minimum)

Failure Indicators

This skill has FAILED if:

• ❌ Analysis incomplete or missing key directories
• ❌ File moves broke application functionality
• ❌ Imports/references not updated after moves
• ❌ README files missing critical information
• ❌ Naming violations persist after fixes
• ❌ Final score <80/100 (below Grade B)
• ❌ Production audit shows blocking issues
• ❌ Git history lost for moved files
• ❌ Cross-references broken between documents

When NOT to Use

Do NOT use this skill when:

• New greenfield projects - Use project-structure-patterns instead for initial setup
• Minor file additions - Single file additions don't need full reorganization
• During active development - Wait for stable point to avoid merge conflicts
• Legacy codebases with hard-coded paths - Reorganization will break everything
• Production systems without backup - Too risky without rollback capability
• Time-sensitive releases - Reorganization adds risk near deadlines
• External dependencies on paths - Breaking public APIs or documented paths

Alternative approaches:

• Use file-reorganization-orchestrator alone for targeted moves
• Use readme-generator alone for documentation gaps
• Use naming-convention-enforcer alone for naming fixes

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Moving without planning	Breaks references, creates chaos	Always generate and review plans first
Ignoring git history	Lost file history in git log	Use git mv, not delete+create
No README updates	Users can't find relocated files	Update all affected documentation
Breaking public APIs	External dependencies break	Keep public paths stable, reorganize internals
Renaming inconsistently	Some files fixed, others missed	Apply naming standards across all files
Skipping validation	Don't know if reorganization succeeded	Always run production audit after
Large atomic changes	High risk, hard to review	Break into phased reorganization
No backup/rollback	Can't undo if breaks production	Tag or branch before major changes
Mixing concerns	Reorganization + feature work = conflicts	Do reorganization in dedicated session
Ignoring dependencies	Move file but not its dependencies	Analyze and move related files together

Principles

This skill embodies these CODITECT principles:

• #1 Recycle → Extend → Re-Use → Create - Reuses existing files in better structure
• #3 Keep It Simple - Simplifies navigation through logical organization
• #4 Separation of Concerns - Groups related files, separates unrelated
• #5 Eliminate Ambiguity - Clear directory purpose eliminates "where does this go?"
• #6 Clear, Understandable, Explainable - README files explain every directory
• #8 No Assumptions - Analyzes actual structure before making changes
• #13 Automate Repetitive Tasks - Automates analysis, planning, and execution
• #15 Standards Compliance - Enforces CODITECT directory and naming standards

Full Principles: CODITECT-STANDARD-AUTOMATION.md

---

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