version: 2.2.0
python_min_version: '3.10'
dependencies: []
compatibility:
  tested_python:
  - '3.10'
  - '3.11'
  - '3.12'
  - '3.13'
  os:
  - Windows
  - Linux
  - macOS

When to Use

Repository has accumulated build artifacts and temp files
Multiple agent/coordination directories scattered in root
Log files and coverage reports cluttering the workspace
Need to consolidate prototype code and test outputs
Preparing for a clean commit or release
After major refactoring work

Cleanup Categories

1. Build Artifacts

Files generated during build/install processes that should not be tracked.

Pattern	Description	Location
`*.egg-info/`	Python package metadata	`src/*/`
`__pycache__/`	Python bytecode cache	Throughout
`.pytest_cache/`	Pytest cache	Root and test dirs
`build/`	Build output directory	Root
`dist/`	Distribution packages	Root
`*.pyc`	Compiled Python files	Throughout
`*.pyo`	Optimized Python files	Throughout

Cleanup commands:

# Find all build artifacts
find . -type d -name "__pycache__" -o -name "*.egg-info" -o -name ".pytest_cache"

# Remove Python cache (safe - regenerated automatically)
find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null
find . -type d -name "*.egg-info" -exec rm -rf {} + 2>/dev/null
find . -type d -name ".pytest_cache" -exec rm -rf {} + 2>/dev/null

2. Log Files

Generated log files that accumulate during development and testing.

Pattern	Description
`*.log`	General log files
`*LogFile.txt`	OrcaFlex log files
`.log.`	Rotated log files
`debug.log`	Debug output

Cleanup commands:

# Find log files
find . -name "*.log" -o -name "*LogFile.txt"

# Remove log files (verify first)
find . -name "*.log" -type f -delete
find . -name "*LogFile.txt" -type f -delete

3. Temp Files

Temporary files created during processing or editing.

Pattern	Description
`*.tmp`	Temporary files
`.temp/`	Temp directories
`cache/`	Cache directories
`*.bak`	Backup files
`*.swp`	Vim swap files
`*~`	Editor backup files

Cleanup commands:

# Find temp files
find . -name "*.tmp" -o -name "*.bak" -o -name "*.swp" -o -name "*~"

# Remove temp files
find . \( -name "*.tmp" -o -name "*.bak" -o -name "*.swp" -o -name "*~" \) -type f -delete

4. Coverage Reports

Test coverage artifacts that can be regenerated.

Pattern	Description
`htmlcov/`	HTML coverage reports
`.coverage`	Coverage data file
`.coverage.*`	Parallel coverage data
`coverage.xml`	XML coverage report

Cleanup commands:

# Remove coverage artifacts
rm -rf htmlcov/
rm -f .coverage .coverage.* coverage.xml

5. IDE Artifacts

Editor and IDE generated files.

Pattern	Description
`.idea/`	PyCharm/IntelliJ
`.vscode/`	VS Code (keep settings.json)
`*.code-workspace`	VS Code workspaces
`.spyproject/`	Spyder IDE

Note: Some IDE settings may be intentionally tracked. Check .gitignore first.

6. Benchmark Artifacts

Benchmark directories often contain mixed content that needs separation.

Pattern	Description	Action
`benchmarks/reports/`	Timestamped HTML reports	Add to .gitignore
`benchmarks/results/`	Timestamped CSV/JSON	Add to .gitignore
`benchmarks/legacy_projects/`	Reference test data	Move to tests/fixtures/
`benchmarks/*.py`	Benchmark scripts	Keep tracked

Cleanup commands:

# Move test fixtures to proper location
mkdir -p tests/fixtures/orcaflex
git mv benchmarks/legacy_projects/* tests/fixtures/orcaflex/

# Untrack generated outputs
git rm -r --cached benchmarks/reports benchmarks/results

# Add to .gitignore
echo "benchmarks/reports/" >> .gitignore
echo "benchmarks/results/" >> .gitignore

Consolidation Patterns

Agent Directories

Multiple agent-related directories should consolidate to .claude/agents/.

Before:

root/
├── agents/
├── .agents/
├── agent_configs/
└── .agent-os/

After:

.claude/
└── agents/
    ├── core/
    ├── devops/
    └── specialized/

Commands:

# Find scattered agent directories
find . -maxdepth 2 -type d -name "*agent*"

# Move to consolidated location
git mv agents/* .claude/agents/ 2>/dev/null
git mv .agents/* .claude/agents/ 2>/dev/null
rm -rf agents .agents agent_configs

Runtime/Coordination Data

Session state files
Coordination lock files
Runtime cache
Worker state

Commands:

# Create runtime directory

# Move runtime files (don't use git mv - these are untracked)

Prototype Code

Prototype and experimental code should go to examples/prototypes/.

Commands:

mkdir -p examples/prototypes
git mv prototype_*.py examples/prototypes/
git mv experimental/ examples/prototypes/

Test Outputs

Test output files should go to tests/outputs/ (gitignored).

Commands:

mkdir -p tests/outputs
mv tests/*.html tests/outputs/
mv tests/*.json tests/outputs/
mv tests/test_results/ tests/outputs/

Plan Files

Completed specification plans should be archived.

Pattern:

Active plans: specs/modules/<plan>.md
Completed plans: specs/archive/<plan>.md

Commands:

# Archive completed plan (check status: completed in YAML frontmatter)
mkdir -p specs/archive
git mv specs/modules/<completed-plan>.md specs/archive/

Hidden Folder Cleanup

Legacy AI and agent hidden folders often accumulate during development. These need review and consolidation.

Common Hidden Folders

Folder	Description	Action
`.agent-os/`	Legacy agent OS framework	Consolidate to `.claude/`
`.ai/`	Legacy AI configuration	Consolidate to `.claude/`
`.agent-runtime/`	Runtime symlinks (often dead)	Delete if dead links
`.common/`	Orphaned utility scripts	Delete or relocate to `scripts/`
`.specify/`	Stale specification templates	Delete if unused
`.drcode/`	External tool config (Dr. Code)	Keep if actively used
`.slash-commands/`	Command registry	Keep

Discovery Commands

# List all hidden directories with sizes
du -sh .*/ 2>/dev/null | grep -v "^\./\.git"

# Find dead symlinks in hidden folders
find .agent-runtime -type l ! -exec test -e {} \; -print 2>/dev/null

# Count files in each hidden directory
for dir in .claude .agent-os .ai .common .specify; do
  if [ -d "$dir" ]; then
    count=$(find "$dir" -type f | wc -l)
    echo "$dir: $count files"
  fi
done

Cleanup Commands

# Remove dead symlink directories
rm -rf .agent-runtime/

# Remove stale template directories
rm -rf .specify/

# Remove orphaned utilities (after relocating useful scripts)
rm -rf .common/

# Consolidate .agent-os to .claude
git mv .agent-os/agents/* .claude/agents/ 2>/dev/null
git mv .agent-os/skills/* .claude/skills/ 2>/dev/null
git mv .agent-os/docs/* .claude/docs/ 2>/dev/null
rm -rf .agent-os/

# Consolidate .ai to .claude
git mv .ai/config/* .claude/config/ 2>/dev/null
git mv .ai/prompts/* .claude/prompts/ 2>/dev/null
rm -rf .ai/

Consolidation Merge Strategies

When merging folders, file conflicts are common. Use these strategies to preserve important content while eliminating duplicates.

Conflict Resolution Patterns

Conflict Type	Strategy	Example
Same filename	Rename with suffix	`README.md` -> `README-legacy.md`
Similar content	Use subdirectory	`commands/` -> `commands/legacy-scripts/`
Unique content	Preserve in dedicated folder	Keep `implementation-history/`
Clear duplicates	Delete after verification	Remove exact copies

Merge Commands

# Rename conflicting files before merge
mv .agent-os/README.md .agent-os/README-legacy.md

# Create legacy subdirectory for scripts
mkdir -p .claude/commands/legacy-scripts
git mv .agent-os/commands/* .claude/commands/legacy-scripts/

# Preserve unique historical content
git mv .agent-os/implementation-history/ .claude/docs/implementation-history/

# Find and remove exact duplicates (verify first)
md5sum .claude/agents/*.md .agent-os/agents/*.md | sort | uniq -w32 -d

Pre-Merge Checklist

Compare file lists between source and target
Identify naming conflicts
Decide rename vs. subdirectory strategy
Document unique content to preserve
Verify duplicates before deletion

File Count Verification

Track consolidation progress with file counts to ensure nothing is lost.

Progress Tracking Commands

# Count tracked files in each hidden folder
for dir in .claude .agent-os .ai; do
  count=$(git ls-files "$dir" 2>/dev/null | wc -l)
  echo "$dir: $count files"
done

# Count all files (tracked + untracked)
for dir in .claude .agent-os .ai .common .specify; do
  if [ -d "$dir" ]; then
    tracked=$(git ls-files "$dir" 2>/dev/null | wc -l)
    total=$(find "$dir" -type f | wc -l)
    echo "$dir: $tracked tracked, $total total"
  fi
done

# Before/after comparison
echo "=== Before Consolidation ===" > consolidation-log.txt
for dir in .claude .agent-os .ai; do
  count=$(git ls-files "$dir" 2>/dev/null | wc -l)
  echo "$dir: $count files" >> consolidation-log.txt
done

Verification After Merge

# Verify no files were lost
expected_count=150  # Set to sum of source folders
actual_count=$(git ls-files .claude | wc -l)
echo "Expected: $expected_count, Actual: $actual_count"

# List any untracked files that might have been missed
git status --porcelain | grep "^??" | grep -E "^\?\? \.(claude|agent-os|ai)/"

Discovery Commands

List Untracked Files

# All untracked files
git status --porcelain | grep "^??"

# Untracked files with size
git status --porcelain | grep "^??" | cut -c4- | xargs -I {} sh -c 'du -h "{}" 2>/dev/null'

Find Large Files

# Files larger than 1MB
find . -type f -size +1M -exec ls -lh {} \;

# Files larger than 10MB
find . -type f -size +10M -exec ls -lh {} \;

# Largest files in repo
find . -type f -exec du -h {} + 2>/dev/null | sort -rh | head -20

Find Duplicates

# Find duplicate markdown files in agent directories
find . -name "*.md" -path "*/agents/*" -type f

# Find files with same name
find . -type f -name "*.py" | xargs -I {} basename {} | sort | uniq -d

# Find duplicate by content (requires md5sum)
find . -type f -exec md5sum {} + | sort | uniq -w32 -d

Find Hidden Directories

# List all hidden directories
find . -maxdepth 1 -type d -name ".*" | grep -v "^\./\.git$"

# Hidden directories with sizes
du -sh .*/

Safe Deletion Commands

For Tracked Files (Use git rm)

# Remove tracked file
git rm path/to/file

# Remove tracked directory
git rm -r path/to/directory

# Remove from git but keep local copy
git rm --cached path/to/file

For Untracked Files (Use rm)

# Remove untracked file
rm path/to/file

# Remove untracked directory
rm -rf path/to/directory

# Interactive removal (safer)
rm -i path/to/file

Dry Run First

# Preview what would be deleted
git clean -n -d

# Preview including ignored files
git clean -n -d -x

Gitignore Updates

Add these entries to .gitignore after cleanup:

# Build artifacts
__pycache__/
*.py[cod]
*$py.class
*.egg-info/
*.egg
build/
dist/
.eggs/

# Test artifacts
.pytest_cache/
.coverage
.coverage.*
htmlcov/
coverage.xml
*.cover

# IDE
.idea/
.vscode/
*.code-workspace
.spyproject/

# Logs
*.log
*LogFile.txt

# Temp files
*.tmp
*.bak
*.swp
*~
.temp/
cache/

.coordination/
.session/

# Benchmark generated outputs
benchmarks/reports/
benchmarks/results/

# Test outputs
tests/outputs/
tests/*.html
tests/*.json

# Large binary files
*.sim
*.dat
*.bin

Cleanup Checklist

Pre-Cleanup

Git working directory status documented
Important untracked files identified
Backup created if needed

Build Artifacts

__pycache__/ directories removed
*.egg-info/ directories removed
.pytest_cache/ removed
build/ and dist/ removed if present

Log Files

*.log files removed or archived
*LogFile.txt files removed
Rotated logs cleaned

Temp Files

*.tmp files removed
Editor backup files removed
Cache directories cleaned

Coverage Reports

htmlcov/ removed
.coverage files removed

Consolidation

Agent directories consolidated to .claude/agents/
Prototypes moved to examples/prototypes/
Test outputs moved to tests/outputs/
Benchmark test fixtures moved to tests/fixtures/
Benchmark generated outputs untracked and gitignored
Completed plan files archived to specs/archive/

Hidden Folder Review

.agent-os/ reviewed and consolidated
.ai/ reviewed and consolidated
.agent-runtime/ deleted if dead symlinks
.common/ relocated or deleted
.specify/ deleted if stale

Post-Cleanup

.gitignore updated with new patterns
git status shows clean or expected state
Tests still pass after cleanup

Final Cleanup Checklist

Based on actual cleanup sessions, these folders have been verified for removal or consolidation.

Folders to DELETE (Confirmed Safe)

Folder	Reason	Verification
`.drcode/`	Legacy AI config (Dr. Code)	Not referenced in any scripts or CI
`.benchmarks/`	Empty benchmark folder	`ls .benchmarks/` returns empty or missing
`.agent-runtime/`	Dead symlinks only	`find .agent-runtime -type l ! -exec test -e {} \;`
`.common/`	Orphaned utilities	No imports reference this folder
`.specify/`	Stale specification templates	Specs moved to `specs/templates/`

Folders to CONSOLIDATE

Source	Destination	Command
`.slash-commands/`	`.claude/docs/commands/`	`git mv .slash-commands/* .claude/docs/commands/`
`.git-commands/`	`scripts/git/`	`git mv .git-commands/* scripts/git/`
`.agent-os/`	`.claude/`	See module-based-refactor skill
`.ai/`	`.claude/`	See module-based-refactor skill

Folders to KEEP

Folder	Reason
`.githooks/`	Standard location for git hooks
`.github/`	GitHub workflows and templates
`.claude/`	Authoritative AI configuration
`.vscode/`	Team VS Code settings (if tracked)

Cleanup Commands

# Delete legacy config folders
rm -rf .drcode/
rm -rf .benchmarks/

# Consolidate slash-commands to docs
mkdir -p .claude/docs/commands
git mv .slash-commands/* .claude/docs/commands/ 2>/dev/null
rm -rf .slash-commands/

# Consolidate git-commands to scripts
mkdir -p scripts/git
git mv .git-commands/* scripts/git/ 2>/dev/null
rm -rf .git-commands/

# Verify cleanup
ls -la .* 2>/dev/null | grep "^d"

README Update Checklist

After cleanup, update the README to reflect the new structure.

Structure Section Updates

Update directory tree to show new structure
Remove references to deleted folders
Add .claude/ folder description
Document scripts/git/ consolidation
Note module-based architecture in src/

Example README Structure Section

## Repository Structure

project/
├── .claude/              # AI configuration and documentation
│   ├── agents/           # Agent definitions
│   ├── docs/             # Reference documentation
│   ├── skills/           # Skill definitions
│   └── settings.json     # Claude Code settings
├── .githooks/            # Git hooks
├── scripts/              # Utility scripts
│   └── git/              # Git-related scripts
├── src/<pkg>/modules/    # Source modules (5-layer architecture)
├── tests/modules/        # Test modules
├── specs/modules/        # Specification modules
├── docs/modules/         # Documentation modules
└── examples/modules/     # Example modules

References to Remove

.agent-os/ - consolidated to .claude/
.ai/ - consolidated to .claude/
.drcode/ - deleted (legacy)
.slash-commands/ - consolidated to .claude/docs/commands/
.git-commands/ - consolidated to scripts/git/

Best Practices

Always verify before deleting - Use find and ls before rm
Use git rm for tracked files - Preserves history and staging
Update .gitignore first - Prevents re-adding cleaned files
Commit cleanup separately - Keep cleanup commits distinct from feature work
Document what was removed - Use clear commit messages
Check file sizes - Large files may need special handling (Git LFS)

Related Skills

module-based-refactor - For restructuring after cleanup
session-start-routine - Session initialization

References

Git clean documentation: https://git-scm.com/docs/git-clean
Git rm documentation: https://git-scm.com/docs/git-rm
Gitignore patterns: https://git-scm.com/docs/gitignore

Version History

2.2.0 (2026-01-20): Added Benchmark Cleanup and Plan File Archival patterns
- Added Benchmark Artifacts section for handling benchmark directories
- Added Plan Files section for archiving completed specifications
- Added benchmark patterns to .gitignore recommendations
- Updated checklist with benchmark and plan archival items
2.1.0 (2026-01-20): Added Final Cleanup Checklist and README Update Checklist
- Added Final Cleanup Checklist with verified DELETE/CONSOLIDATE/KEEP tables
- Confirmed .drcode/ as safe to delete (legacy AI config)
- Added .slash-commands/ consolidation to .claude/docs/commands/
- Added .git-commands/ consolidation to scripts/git/
- Added .benchmarks/ as safe to delete if empty
- Added README Update Checklist for structure documentation
- Added example README structure section template
- Added references to remove checklist
2.0.0 (2026-01-20): Major update with hidden folder cleanup learnings
- Added Hidden Folder Cleanup section with legacy AI folder patterns
- Added Consolidation Merge Strategies for conflict resolution
- Added File Count Verification for tracking consolidation progress
- Updated Cleanup Checklist with hidden folder review items
- Documented patterns for .agent-os, .ai, .agent-runtime, .common, .specify, .drcode, .slash-commands
1.0.0 (2025-01-20): Initial release based on digitalmodel repository cleanup session

repo-cleanup

Repository Cleanup Skill

Version Metadata