Daily Repository Housekeeping Skill Skill

Daily Repository Housekeeping Skill

Purpose

Automatically maintain repository cleanliness and organization by scanning for misplaced files, organizing loose scripts, cleaning up temporary files, and ensuring professional folder structure throughout the codebase.

Activation

Invoke with: housekeeping (no parameters required)

Example:

"Hey Claude, read the housekeeping guide and analyze our repo for any cleanup needed."

Reference Documentation

This skill implements the workflow defined in: /resources/docs/HOUSEKEEPING.md

Read this file first to understand the comprehensive organization protocol.

Workflow Overview

Phase 1: Repository Scan & Analysis

Analyze the current state of the repository across all critical areas.

1.1 Root Directory Scan

First, load the ALLOWED ROOT FILES WHITELIST (see below)

List all files at repository root (not folders)
Compare against whitelist to categorize:
- KEEP (Whitelisted) - Framework/system required files that MUST stay at root
- ORGANIZE - Loose scripts (.py, .sh, .js, .ts files that don't belong at root)
- ORGANIZE - Documentation files (.md files other than README.md)
- DELETE - Backup files (.bak, .backup, *~, *.tmp)
- DELETE - System files (.DS_Store, Thumbs.db)
- ORGANIZE or DELETE - Other misplaced files (determine based on content)

Key Rule: If a file is NOT on the whitelist, it needs to be organized or deleted.

1.2 Context Folder Analysis

Check context root for files other than README.md
Scan for documentation files that need proper categorization
Identify folders with inconsistent naming conventions
Look for duplicate or outdated files

1.3 Resources Folder Analysis

Scan for new utilities or scripts without proper categorization
Check if Python/Shell scripts are in correct subfolders
Verify documentation is in appropriate thematic folders
Identify loose files that need homes

1.4 Git Diff Analysis (Optional Context)

Check what files were recently added (signals for what might be messy)
Identify new scripts or docs that need organization

Phase 2: Issue Categorization

Categorize all findings into severity levels:

Auto-Fix (No Approval Needed)

Small, obvious fixes that can be done immediately:

Delete system files (.DS_Store, Thumbs.db)
Delete backup files (.bak, .backup, *~)
Delete temporary files (*.tmp, *.log that aren't in logs/)
Move 1-2 clearly misplaced files to obvious locations

Requires Approval

Larger changes that need user confirmation:

Moving multiple files (3+)
Creating new folder structures
Renaming existing folders
Deleting files that might be important (scripts, docs, configs)
Major reorganization

Phase 3: Auto-Fix Execution

For items categorized as "Auto-Fix":

Delete unnecessary files:

# System files
find . -name ".DS_Store" -delete
find . -name "Thumbs.db" -delete

# Backup files
find . -name "*.bak" -delete
find . -name "*.backup" -delete
find . -name "*~" -delete

Move 1-2 clearly misplaced files:
- Single Python script at root → resources/utilities/scripts/python/[category]/
- Single shell script at root → resources/utilities/scripts/shell/[category]/
- Documentation file in context root → appropriate context subfolder
Silent execution - just do it, no need to announce

Phase 4: Plan Presentation (If Needed)

If there are items requiring approval:

Present current state:
- Show ASCII tree of problematic areas
- List all files that need organization
- Categorize by type/purpose
Propose solution:
- Show ASCII tree of proposed structure
- Explain what will be moved where
- Explain what will be deleted
Wait for user approval before proceeding
Use TodoWrite tool to track all planned changes

Phase 5: Implementation (After Approval)

Execute approved changes in this order:

Create new folder structure (if needed)
- Follow naming conventions: lowercase-with-hyphens
- Create deep subfolder hierarchies with clear categorization
Delete approved files (backups, duplicates, temp files)
Move files in logical groups:
- Python scripts → resources/utilities/scripts/python/[category]/
- Shell scripts → resources/utilities/scripts/shell/[category]/
- Documentation → appropriate context or resources subfolder
- Examples → resources/examples/
Rename folders (if needed) following conventions
Verify nothing lost - check that all important files were moved, not deleted

Phase 6: Git Commit

Stage all changes:
```
git add .
```
Review changes:
```
git status
```

Commit with descriptive message:

git commit -m "$(cat <<'EOF'
chore: Daily housekeeping - organize repository structure

• Cleaned up loose files from root directory
• Organized scripts into proper utility folders
• Deleted temporary and backup files
• Maintained professional folder structure

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"

Push to remote (only if user explicitly requests)

Phase 7: Slack Notification

Send brief update to Academy channel:

Get Academy channel ID:

Use mcp__slack__slack_list_channels to find Academy channel

Send notification:

Use mcp__slack__slack_send_message with:
- Channel: Academy channel ID
- Message: "🧹 Daily housekeeping completed for transportation-insight repository! Organized loose files, cleaned up context folder, and maintained proper folder structure for optimal development workflow."

Keep it brief - 2 sentences max, professional tone

Allowed Root Files Whitelist

CRITICAL: Only these files are allowed at the repository root. Everything else must be organized or deleted.

Framework Configuration Files

package.json - NPM package configuration
package-lock.json - NPM lock file
tsconfig.json - TypeScript configuration
tsconfig.tsbuildinfo - TypeScript build cache
next.config.js - Next.js configuration
next.config.mjs - Next.js configuration (ESM)
next-env.d.ts - Next.js type definitions
middleware.ts - Next.js middleware
middleware.js - Next.js middleware (JS)

Amplify Files

amplify.yml - Amplify build configuration
amplify_outputs.json - Amplify runtime configuration

Git & Version Control

.gitignore - Git ignore rules
.gitattributes - Git attributes

Environment & Configuration

.env - Environment variables (if exists)
.env.local - Local environment variables
.env.production - Production environment variables
.env.development - Development environment variables

Documentation

README.md - Main project documentation (ONLY .md file allowed at root)
CLAUDE.md - Symlink to Claude config (if exists)

IDE Configuration

.eslintrc.js - ESLint configuration
.eslintrc.json - ESLint configuration
.prettierrc - Prettier configuration
.prettierignore - Prettier ignore rules
.editorconfig - Editor configuration

Build & CI/CD

Dockerfile - Docker configuration (if exists)
.dockerignore - Docker ignore rules (if exists)

Other Framework Files

postcss.config.js - PostCSS configuration (if exists)
tailwind.config.js - Tailwind configuration (if exists)
jest.config.js - Jest configuration (if exists)
vitest.config.ts - Vitest configuration (if exists)

Everything else = ORGANIZE or DELETE

What Gets Organized (Examples)

sync_databricks.py → resources/utilities/scripts/python/databricks/
setup_auth.sh → resources/utilities/scripts/shell/auth/
TESTING_NOTES.md → context/qa-test-scenarios/
architecture.md → context/technical-docs/
old_config.json → DELETE or move to resources/

What Gets Deleted (Always)

.DS_Store - macOS system files
Thumbs.db - Windows system files
*.bak - Backup files
*.backup - Backup files
*~ - Temp files
*.tmp - Temp files
*.log - Log files (unless in /logs folder)

Folder Structure Standards

Root Directory (Keep Only These)

transportation-insight/
├── .amplify/                  # Amplify framework
├── .claude/                   # Claude Code config
├── .git/                      # Git version control
├── .github/                   # GitHub config
├── .next/                     # Next.js build
├── amplify/                   # Amplify backend
├── context/                   # Project context (user-specified keep)
├── logs/                      # Application logs (user-specified keep)
├── node_modules/              # NPM dependencies
├── public/                    # Next.js public assets
├── resources/                 # All supporting materials
├── src/                       # Application source code
├── .env.local                 # Environment config
├── .gitignore                 # Git ignore rules
├── amplify_outputs.json       # Amplify outputs
├── amplify.yml                # Amplify build config
├── middleware.ts              # Next.js middleware
├── next-env.d.ts              # Next.js types
├── next.config.js             # Next.js config
├── package.json               # NPM package config
├── package-lock.json          # NPM lock file
├── README.md                  # Main documentation
├── tsconfig.json              # TypeScript config
└── tsconfig.tsbuildinfo       # TypeScript build info

Context Folder Structure

context/
├── README.md                          # ONLY file at root level
├── legacy-codebase/                   # Previous platform code
├── qa-test-scenarios/                 # Testing scenarios
├── setup-guides/                      # Auth and setup docs
├── team-communications/               # Slack conversations
├── technical-docs/                    # Architecture docs
└── ui-specifications/                 # Design specs

Resources Utilities Structure

resources/utilities/
├── scripts/
│   ├── python/
│   │   ├── slack/              # Slack integration scripts
│   │   ├── databricks/         # Database scripts
│   │   └── [category]/         # Other categorized scripts
│   └── shell/
│       ├── auth/               # Authentication setup
│       ├── sync/               # Synchronization scripts
│       └── deployment/         # Deployment scripts
└── resources/                  # Text files, links, references

Naming Conventions

Use lowercase with hyphens: team-communications, qa-test-scenarios
Be descriptive: ui-specifications not design
Group by purpose: setup-guides for all auth/config docs
Avoid abbreviations: legacy-codebase not legacy

Critical Rules

Read HOUSEKEEPING.md first - This skill implements that guide
Enforce the whitelist - Only whitelisted files stay at root, everything else gets organized or deleted
Auto-fix small issues - Don't ask for permission on obvious cleanups
Present plan for major changes - Show ASCII trees and get approval
Follow naming conventions - Professional, descriptive folder names
Deep organization - Use subfolder hierarchies, not flat structures
Use TodoWrite for tracking - Plan and track all major changes
Silent on auto-fixes - Just do the work, don't announce trivial cleanups
Always notify Academy - Send Slack update when done
Never move framework files - Keep whitelisted root files in place (see whitelist above)
Respect user-specified folders - context and logs stay at root as folders
When in doubt, ask - If a file's purpose is unclear, ask user before organizing/deleting

Excluded Folders (Don't Organize These)

From tsconfig.json, these folders are excluded and should be ignored:

node_modules - Dependencies, don't touch
src_original - Archived code, leave alone
src/warehouse - Excluded from build, leave alone
OldSource - Legacy code, leave alone
amplify/**/* - Don't reorganize Amplify structure
scripts/**/* - If this exists, leave it alone

Success Criteria

✅ Root directory contains only essential framework files + context + logs + resources ✅ Context folder has only README.md at root, all docs properly categorized ✅ Resources folder has deep organization with clear categorization ✅ No loose files - everything has a logical, discoverable location ✅ Consistent naming throughout (lowercase-with-hyphens) ✅ All changes committed with descriptive message ✅ Academy channel notified of completion ✅ Developer can find any file within 30 seconds

Example Execution

Morning invocation:

User: "Hey Claude, read the housekeeping guide and analyze our repo for any cleanup needed."

Claude's workflow:

Reads /resources/docs/HOUSEKEEPING.md
Loads Allowed Root Files Whitelist from skill
Scans root directory, context folder, resources folder
Compares root files against whitelist:
- Whitelisted (KEEP): package.json, tsconfig.json, README.md, middleware.ts, etc.
- Not whitelisted (ORGANIZE): sync_databricks.py, old_script.sh
- Not whitelisted (ORGANIZE): AUTH_NOTES.md, TESTING.md (docs not on whitelist)
- Always delete: .DS_Store files
Identifies:
- 3 .DS_Store files (auto-delete)
- 1 Python script at root: sync_databricks.py (NOT on whitelist → needs categorization)
- 2 docs in context root: AUTH_NOTES.md, TESTING.md (need proper folders)
Auto-fixes:
- Deletes all .DS_Store files silently

Presents plan:

Found 3 files at root that are NOT on the whitelist:

📂 Root Directory Violations:
❌ sync_databricks.py (Python script - should be in resources/utilities/)
❌ AUTH_NOTES.md (Documentation - should be in context/setup-guides/)
❌ TESTING.md (Documentation - should be in context/qa-test-scenarios/)

Proposed actions:
• Move sync_databricks.py → resources/utilities/scripts/python/databricks/
• Move AUTH_NOTES.md → context/setup-guides/
• Move TESTING.md → context/qa-test-scenarios/

[Shows ASCII tree of proposed changes]

User approves
Executes:
- Moves sync_databricks.py → resources/utilities/scripts/python/databricks/
- Moves AUTH_NOTES.md → context/setup-guides/
- Moves TESTING.md → context/qa-test-scenarios/
Commits changes with descriptive message
Sends Slack notification to Academy channel
Reports: "Housekeeping complete! Repository is clean and organized. All root files now comply with whitelist."

Agent Skills: Daily Repository Housekeeping Skill

Install this agent skill to your local

Skill Files