tidy-project-structure

When to Use

Use this skill when project organization has drifted from conventions:

• Files scattered across directories without clear organization
• READMEs are outdated or contain broken examples
• Configuration files have multiplied (dev, staging, prod drift)
• Deprecated files remain in project root
• Naming conventions inconsistent across directories

Do NOT use for code refactoring or dependency restructuring. This skill focuses on file organization and documentation hygiene.

Inputs

Parameter	Type	Required	Description
project_path	string	Yes	Absolute path to project root
conventions	string	No	Path to style guide (e.g., docs/conventions.md)
archive_mode	enum	No	move (default) or delete for deprecated files
readme_update	boolean	No	Update stale READMEs (default: true)

Procedure

Step 1: Audit Directory Layout

Compare current structure against project conventions or language best practices.

Common conventions by language:

JavaScript/TypeScript:

src/          # Source code
tests/        # Test files
dist/         # Build output (gitignored)
docs/         # Documentation
.github/      # CI/CD workflows

Python:

package_name/      # Package code
tests/             # Test suite
docs/              # Sphinx docs
scripts/           # Utility scripts

R:

R/                 # R source
tests/testthat/    # Test suite
man/               # Documentation (generated)
vignettes/         # Long-form guides
inst/              # Installed files
data/              # Package data

Rust:

src/          # Source code
tests/        # Integration tests
benches/      # Benchmarks
examples/     # Usage examples

Got: List of files/directories violating conventions saved to structure_audit.txt

If fail: If no conventions documented, use language-standard defaults

Step 2: Move Misplaced Files

Relocate files to their conventional directories.

Common moves:

1. Test files outside tests/ → move to tests/
2. Documentation outside docs/ → move to docs/
3. Build artifacts in src/ → delete (should be gitignored)
4. Config files in root → move to config/ or .config/

For each move:

# Check if file is referenced anywhere
grep -r "filename" .

# If no references or only relative path references:
mkdir -p target_directory/
git mv source/file target_directory/file

# Update any imports/requires
# (language-specific — see repair-broken-references skill)

Got: All files in conventional locations; git history preserved via git mv

If fail: If moving breaks imports, update import paths or escalate

Step 3: Check README Freshness

Identify stale information in all README files.

Staleness indicators:

1. Last modified >6 months ago
2. References to old version numbers
3. Broken links or code examples
4. Missing sections (Installation, Usage, Contributing)
5. No license badge or broken badge links

# Find all READMEs
find . -name "README.md" -o -name "readme.md"

# For each README:
# - Check last modified date
git log -1 --format="%ci" README.md

# - Check for broken links
markdown-link-check README.md

# - Verify example code still runs (sample first example)

Got: List of stale READMEs in readme_freshness.txt with specific issues

If fail: If markdown-link-check unavailable, manually review external links

Step 4: Update Stale READMEs

Fix broken links, update examples, add missing sections.

Standard fixes:

1. Replace broken badge URLs
2. Update version numbers in installation instructions
3. Fix broken example code (run to verify)
4. Add missing sections (use template from project conventions)
5. Update copyright year

README template structure:

# Project Name

Brief description (1-2 sentences).

## Installation

```bash
# Language-specific install command

Usage

# Basic example

Documentation

Link to full docs.

Contributing

Link to CONTRIBUTING.md or inline guidelines.

License

LICENSE badge and link.

**Got:** All READMEs updated; examples verified to run

**If fail:** If example code cannot be verified, mark with warning comment

### Step 5: Review Config Files

Identify configuration drift and consolidate duplicate settings.

**Common config issues**:
1. Multiple `.env` files (`.env`, `.env.local`, `.env.dev`, `.env.prod`)
2. Duplicate settings across config files
3. Hardcoded secrets (should use environment variables)
4. Outdated API endpoints or feature flags

```bash
# Find all config files
find . -name "*.config.*" -o -name ".env*" -o -name "*.yml" -o -name "*.yaml"

# For each config:
# - Check for duplicate keys
# - Grep for hardcoded secrets (API keys, tokens, passwords)
grep -E "(api[_-]?key|token|password|secret)" config_file

# - Compare dev vs prod settings
diff .env.dev .env.prod

Got: Config drift documented in config_review.txt; secrets flagged for escalation

If fail: If diff shows major divergence, escalate to devops-engineer

Step 6: Archive Deprecated Files

Move or delete files no longer needed.

Candidates for archiving:

• Commented-out config files (e.g., nginx.conf.old)
• Legacy scripts not run in >1 year
• Backup files (e.g., file.bak, file~)
• Build artifacts accidentally committed

Archive process:

# Create archive directory (if archive_mode=move)
mkdir -p archive/YYYY-MM-DD/

# For each deprecated file:
# 1. Verify not referenced anywhere
grep -r "filename" .

# 2. Check git history for last modification
git log -1 --format="%ci" filename

# 3. If not modified in >1 year and no references:
if [ "$archive_mode" = "move" ]; then
  git mv filename archive/YYYY-MM-DD/
else
  git rm filename
fi

# 4. Document in ARCHIVE_LOG.md
echo "- filename (reason, last modified: DATE)" >> ARCHIVE_LOG.md

Got: Deprecated files archived; ARCHIVE_LOG.md updated

If fail: If uncertain whether file is deprecated, leave in place and document in report

Step 7: Verify Naming Conventions

Check for inconsistent file naming across project.

Common conventions:

• kebab-case: my-file.js (common in JS/web projects)
• snake_case: my_file.py (Python standard)
• PascalCase: MyComponent.tsx (React components)
• camelCase: myUtility.js (JavaScript functions)

# Find files violating conventions
# Example: Python project expecting snake_case
find . -name "*.py" | grep -v "__pycache__" | grep -E "[A-Z-]"

# For each violation, either:
# 1. Rename to match conventions
# 2. Document exception (e.g., Django settings.py convention)

Got: All files follow naming conventions or exceptions documented

If fail: If renaming breaks imports, update references or escalate

Step 8: Generate Tidying Report

Document all structural changes.

# Project Structure Tidying Report

**Date**: YYYY-MM-DD
**Project**: <project_name>

## Directory Changes

- Moved X files to conventional directories
- Created Y new directories
- Archived Z deprecated files

## README Updates

- Updated W stale READMEs
- Fixed X broken links
- Verified Y code examples

## Config Cleanup

- Consolidated X duplicate settings
- Flagged Y hardcoded secrets for removal
- Documented Z config drift issues

## Files Archived

See ARCHIVE_LOG.md for full list (Z files).

## Naming Convention Fixes

- Renamed X files to match conventions
- Documented Y exceptions

## Escalations

- [Config drift requiring devops review]
- [Hardcoded secrets requiring security audit]

Got: Report saved to TIDYING_REPORT.md

If fail: (N/A — generate report regardless)

Validation Checklist

After tidying:

• All files in conventional directories
• No broken links in any README
• README examples verified to run
• Config files reviewed for secrets
• Deprecated files archived with documentation
• Naming conventions consistent
• Git history preserved (used git mv, not mv)
• Tests still pass after moves

Pitfalls

1. Breaking Relative Imports: Moving files breaks relative import paths. Update all references or use absolute imports.

2. Losing Git History: Using mv instead of git mv loses file history. Always use git commands for moves.

3. Over-Organizing: Creating too many nested directories makes navigation harder. Keep it flat until complexity requires structure.

4. Deleting Instead of Archiving: Direct deletion loses ability to recover. Always archive first unless certain.

5. Ignoring Language Conventions: Imposing personal preferences over language standards. Follow established conventions.

6. Not Updating Documentation: Moving files without updating README paths leaves docs broken.

Related Skills

• clean-codebase — Remove dead code, fix lint warnings
• repair-broken-references — Fix links and imports after moves
• escalate-issues — Route complex config issues to specialists
• devops/config-management — Advanced config consolidation
• compliance/documentation-audit — Comprehensive doc review