Hidden Folder Audit

Hidden Folder Audit Skill

Systematic audit and consolidation of hidden (dot) folders in a repository. Identifies duplicate configurations, dead symlinks, orphaned directories, and consolidation opportunities to establish a clean, maintainable folder structure.

Version Metadata

version: 1.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 multiple hidden folders over time
• Multiple AI/agent configuration directories exist (.agent-os/, .ai/, .claude/)
• Symlinks point to non-existent targets
• Unclear which configuration is authoritative
• Preparing for repository restructure or cleanup
• After inheriting or forking a repository
• Before establishing new folder standards

Audit Process

Step 1: Inventory All Hidden Folders

List all hidden directories at the repository root.

# List all hidden directories (excluding .git)
find . -maxdepth 1 -type d -name ".*" ! -name ".git" | sort

# With sizes
du -sh .*/ 2>/dev/null | grep -v "^0" | sort -hr

# Include symlinks
find . -maxdepth 1 \( -type d -o -type l \) -name ".*" ! -name ".git" | sort

Step 2: Check Git Tracking Status

Determine which hidden folders are tracked, ignored, or untracked.

# Check if folder is tracked
git ls-files --error-unmatch .folder/ 2>/dev/null && echo "TRACKED" || echo "NOT TRACKED"

# Check if folder is ignored
git check-ignore -v .folder/ 2>/dev/null && echo "IGNORED" || echo "NOT IGNORED"

# List all tracked hidden files
git ls-files | grep "^\." | cut -d'/' -f1 | sort -u

# List all gitignored hidden folders
git status --porcelain --ignored | grep "^!!" | grep "^\./\." | cut -d'/' -f2 | sort -u

Step 3: Analyze Content Overlap

Check for duplicate or overlapping content between hidden folders.

# Compare agent configurations
diff -rq .agent-os/agents/ .claude/agents/ 2>/dev/null

# Find duplicate files by name
find .agent-os .ai .claude -name "*.md" -type f 2>/dev/null | xargs -I {} basename {} | sort | uniq -d

# Find duplicate files by content (MD5)
find .agent-os .ai .claude -type f 2>/dev/null | xargs md5sum 2>/dev/null | sort | uniq -w32 -d

# Compare directory structures
diff <(find .agent-os -type f | sed 's|.agent-os/||' | sort) \
     <(find .claude -type f | sed 's|.claude/||' | sort) 2>/dev/null

Step 4: Identify Authoritative Source

Determine which folder should be the single source of truth.

Criteria for Authoritative Source:

1. Git tracking - Tracked folders are more likely authoritative
2. Recency - Check last modification dates
3. Completeness - More complete configuration wins
4. Active use - Referenced in CI/CD, scripts, documentation
5. Tool requirements - Some tools require specific folder names

# Check modification times
stat -c '%Y %n' .*/ 2>/dev/null | sort -rn | head -10

# Check for references in scripts and CI
grep -r "\.agent-os" --include="*.sh" --include="*.yml" --include="*.yaml" .
grep -r "\.claude" --include="*.sh" --include="*.yml" --include="*.yaml" .

# Check symlink targets
find . -maxdepth 2 -type l -exec ls -la {} \;

Step 5: Plan Consolidation

Create a migration plan based on analysis.

Migration Checklist:

• Identify target folder structure
• List files to migrate
• Identify files to delete
• Update references in code/scripts
• Update .gitignore
• Test after migration

Common Hidden Folders Reference

Based on actual cleanup sessions, this table provides verified recommendations.

Related Directory Patterns

Some non-hidden directories follow similar cleanup/consolidation patterns.

specs/archive/

Standard location for completed specification plans.

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

benchmarks/

Benchmark directories typically contain mixed content requiring separation.

# Separate fixtures from generated outputs
mkdir -p tests/fixtures/orcaflex
git mv benchmarks/legacy_projects/* tests/fixtures/orcaflex/
git rm -r --cached benchmarks/reports benchmarks/results
echo "benchmarks/reports/" >> .gitignore
echo "benchmarks/results/" >> .gitignore

Consolidation Commands

Migrate .agent-os to .claude

# Backup first
cp -r .agent-os .agent-os.backup

# Migrate agents
mkdir -p .claude/agents
cp -r .agent-os/agents/* .claude/agents/ 2>/dev/null

# Migrate standards (if applicable)
mkdir -p .claude/standards
cp -r .agent-os/standards/* .claude/standards/ 2>/dev/null

# Update git tracking
git rm -r --cached .agent-os/ 2>/dev/null
git add .claude/

# Remove old folder after verification
rm -rf .agent-os
rm -rf .agent-os.backup  # After confirming migration

Migrate .ai to .claude

# Backup first
cp -r .ai .ai.backup

# Migrate prompts to skills
mkdir -p .claude/skills/prompts
cp -r .ai/prompts/* .claude/skills/prompts/ 2>/dev/null

# Migrate config
cp .ai/config.* .claude/ 2>/dev/null

# Cleanup
git rm -r --cached .ai/ 2>/dev/null
rm -rf .ai

Clean Dead Symlinks

# Find broken symlinks
find . -maxdepth 2 -type l ! -exec test -e {} \; -print

# Remove broken symlinks
find . -maxdepth 2 -type l ! -exec test -e {} \; -delete

# Remove specific dead symlink folder
rm -rf .agent-runtime

Consolidate Runtime Directories

# Create standard runtime directory
mkdir -p .claude-flow/state
mkdir -p .claude-flow/cache
mkdir -p .claude-flow/logs

# Migrate coordination data
mv .coordination/* .claude-flow/state/ 2>/dev/null
mv .session/* .claude-flow/state/ 2>/dev/null

# Remove old directories
rm -rf .coordination .session

Update .gitignore

Add these patterns after consolidation:

# Runtime and state (not tracked)
.claude-flow/
.coordination/
.session/

# Legacy folders (prevent re-creation)
.agent-os/
.ai/
.agent-runtime/

# Cache directories
.pytest_cache/
.ruff_cache/
.mypy_cache/
__pycache__/

Audit Checklist

Pre-Audit

• Working directory is clean (git status)
• Create backup branch: git checkout -b backup/pre-hidden-audit
• Document current state: ls -la .*/ > hidden-folders-before.txt

Discovery Phase

• List all hidden folders at root level
• Record size of each hidden folder
• Identify symlinks and their targets
• Check git tracking status for each

Analysis Phase

• Identify duplicate configurations
• Find broken symlinks
• Determine authoritative source for each config type
• Check for active usage in scripts/CI

Planning Phase

• Create target folder structure diagram
• List files to migrate with source/destination
• List files/folders to delete
• Identify scripts/references to update

Execution Phase

• Backup folders before migration
• Migrate content to authoritative locations
• Update git tracking (git rm --cached, git add)
• Remove legacy folders
• Update .gitignore

Verification Phase

• Run tests to ensure nothing broke
• Verify symlinks work (if any remain)
• Confirm scripts still function
• Check CI/CD pipelines
• Commit with descriptive message

Documentation Phase

• Update README if folder structure changed
• Document new standard in CLAUDE.md or equivalent
• Remove references to legacy folders in docs

Verification Commands

Use these commands to verify the final state after audit and cleanup.

Verify Hidden Folder State

# List remaining hidden folders (should be minimal)
echo "=== Remaining Hidden Folders ==="
find . -maxdepth 1 -type d -name ".*" ! -name ".git" | sort

# Expected remaining folders:
# .claude/       - AI configuration (authoritative)
# .claude-flow/  - Runtime data (gitignored)
# .github/       - GitHub workflows
# .githooks/     - Git hooks
# .vscode/       - VS Code settings (if tracked)

# Verify no legacy folders remain
echo "=== Checking for Legacy Folders ==="
for dir in .agent-os .ai .drcode .slash-commands .git-commands .benchmarks .agent-runtime .common .specify; do
  if [ -d "$dir" ]; then
    echo "WARNING: $dir still exists!"
  fi
done
echo "Check complete."

Verify Consolidation Targets

# Verify .claude/ structure
echo "=== .claude/ Structure ==="
ls -la .claude/

# Verify scripts/git/ exists if .git-commands was consolidated
echo "=== scripts/git/ ==="
ls -la scripts/git/ 2>/dev/null || echo "scripts/git/ does not exist"

# Verify .claude/docs/commands/ if .slash-commands was consolidated
echo "=== .claude/docs/commands/ ==="
ls -la .claude/docs/commands/ 2>/dev/null || echo ".claude/docs/commands/ does not exist"

# Verify specs/archive exists for completed plans
echo "=== specs/archive/ ==="
ls -la specs/archive/ 2>/dev/null || echo "specs/archive/ does not exist"

# Verify benchmark structure
echo "=== benchmarks/ Structure ==="
ls -la benchmarks/ 2>/dev/null || echo "benchmarks/ does not exist"

# Check for legacy_projects in benchmarks (should be moved)
if [ -d "benchmarks/legacy_projects" ]; then
  echo "[WARN] benchmarks/legacy_projects/ should be moved to tests/fixtures/"
fi

Verify Git Status

# Check for untracked hidden folders
echo "=== Untracked Hidden Folders ==="
git status --porcelain | grep "^??" | grep "^\./\." || echo "None found"

# Verify .gitignore includes runtime folders
echo "=== .gitignore Hidden Folder Entries ==="
grep -E "^\.(claude-flow|coordination|session)" .gitignore || echo "No runtime folders in .gitignore"

# Count tracked files in .claude/
echo "=== .claude/ Tracked Files ==="
git ls-files .claude/ | wc -l

Final State Checklist

# Run all verification checks
echo "=== Final State Verification ==="

# 1. Only expected hidden folders exist
hidden_count=$(find . -maxdepth 1 -type d -name ".*" ! -name ".git" ! -name ".claude" ! -name ".claude-flow" ! -name ".github" ! -name ".githooks" ! -name ".vscode" | wc -l)
if [ "$hidden_count" -eq 0 ]; then
  echo "[OK] No unexpected hidden folders"
else
  echo "[WARN] $hidden_count unexpected hidden folders found"
fi

# 2. Legacy folders are gone
legacy_count=0
for dir in .agent-os .ai .drcode .slash-commands .git-commands .benchmarks; do
  [ -d "$dir" ] && legacy_count=$((legacy_count + 1))
done
if [ "$legacy_count" -eq 0 ]; then
  echo "[OK] All legacy folders removed"
else
  echo "[WARN] $legacy_count legacy folders remain"
fi

# 3. .claude/ has expected subdirectories
for subdir in agents docs skills; do
  if [ -d ".claude/$subdir" ]; then
    echo "[OK] .claude/$subdir exists"
  else
    echo "[WARN] .claude/$subdir missing"
  fi
done

# 4. Git working directory is clean
if git diff --quiet 2>/dev/null; then
  echo "[OK] Git working directory is clean"
else
  echo "[INFO] Git has uncommitted changes"
fi

Best Practices

1. Always backup before deleting - Create a backup branch or copy
2. Use git rm for tracked folders - Preserves history
3. Check symlink targets before deleting - May need to update references
4. Update .gitignore first - Prevents accidental re-tracking
5. Test after consolidation - Ensure nothing broke
6. Commit in logical chunks - Separate migration from cleanup
7. Document the changes - Future maintainers will thank you

Related Skills

• repo-cleanup - General repository cleanup
• module-based-refactor - For source code restructuring
• session-start-routine - Session initialization

References

• Git ls-files documentation: https://git-scm.com/docs/git-ls-files
• Git check-ignore documentation: https://git-scm.com/docs/git-check-ignore
• Symbolic links in Git: https://git-scm.com/book/en/v2/Git-Internals-Git-References

Version History

• 1.2.0 (2026-01-20): Added Related Directory Patterns section
  • Added benchmarks/ entry to reference table (SPLIT action)
  • Added Related Directory Patterns section for non-hidden directories
  • Added specs/archive/ as standard location for completed plans
  • Added benchmarks/ separation pattern (fixtures vs generated outputs)
  • Updated verification commands for new patterns
• 1.1.0 (2026-01-20): Updated reference table and added verification commands
  • Updated Common Hidden Folders Reference table with verified recommendations
  • Added .drcode/ as DELETE (confirmed legacy AI config)
  • Added .slash-commands/ as CONSOLIDATE to .claude/docs/commands/
  • Added .git-commands/ as CONSOLIDATE to scripts/git/
  • Added .benchmarks/ as DELETE (usually empty)
  • Added .githooks/ as KEEP (standard location)
  • Added Verification Commands section with:
    • Verify Hidden Folder State commands
    • Verify Consolidation Targets commands
    • Verify Git Status commands
    • Final State Checklist script
  • Added Notes column to reference table for additional context
• 1.0.0 (2025-01-20): Initial release based on digitalmodel repository hidden folder audit session