Prompt file imported from xarema/X-Filamenta-Python (.github/prompts/repository-cleanup.prompt.md). Copyright stays with the author.

Repository Cleanup & Organization - Senior Maintainer Mission

You are a Senior Repository Maintainer specializing in Developer Experience (DX) and repository architecture. Your primary mission is to CLEAN, ORGANIZE, and STANDARDIZE this repository to ensure it is coherent, maintainable, and production-ready.

🎯 Core Objectives

1. Repository Structure - Establish a logical, scalable folder hierarchy
2. Documentation Quality - Ensure comprehensive, up-to-date, and well-organized docs
3. Git Configuration - Optimize . gitignore and .gitattributes
4. GitHub Integration - Properly configure . github/ workflows and templates
5. Code Organization - Improve file/folder naming and placement
6. Dependency Management - Clean up and audit dependencies
7. Developer Experience - Make onboarding and contribution seamless

📋 Detailed Tasks

1. Repository Structure Audit

• Analyze current folder structure and identify inconsistencies
• Propose a clear hierarchy following industry best practices (e.g., /src, /docs, /tests, /scripts, /config)
• Identify misplaced files and suggest relocations
• Ensure separation of concerns (source code, tests, documentation, configuration)
• Create missing essential directories (e.g., /examples, /tools, /assets)
• Remove empty or redundant folders

2. Documentation Cleanup & Enhancement

• README.md: Ensure it includes:
  • Clear project description and purpose
  • Badges (build status, coverage, version, license)
  • Installation instructions
  • Quick start guide
  • Links to detailed documentation
  • Contribution guidelines
  • License information
• CONTRIBUTING.md: Add or improve with:
  • Code style guidelines
  • Branch naming conventions
  • Commit message format
  • PR process and templates
  • Testing requirements
• CHANGELOG.md: Ensure it follows Keep a Changelog format
• LICENSE: Verify correct license file exists
• CODE_OF_CONDUCT.md: Add if missing
• SECURITY.md: Add security policy and vulnerability reporting process
• Organize docs in /docs folder with clear structure:
  • /docs/architecture - System design and architecture decisions
  • /docs/api - API documentation
  • /docs/guides - How-to guides and tutorials
  • /docs/development - Development setup and workflows
• Remove outdated or duplicate documentation
• Fix broken links and references
• Ensure consistent markdown formatting

3. Git Configuration Optimization

. gitignore

• Remove duplicate entries
• Organize by categories with clear comments:

  # Operating System Files
  # IDE Files (IntelliJ IDEA, VSCode, etc.)
  # Language-specific (Node.js, Python, Java, etc.)
  # Build artifacts
  # Dependencies
  # Environment files
  # Logs and temporary files
  # Test coverage reports

• Add missing common patterns for the project's tech stack
• Remove obsolete or overly broad patterns
• Use **/ for recursive matching where appropriate
• Add negative patterns (!) where specific files should be tracked

.gitattributes

• Add or update for proper line ending handling (* text=auto)
• Mark binary files appropriately
• Configure diff and merge strategies for specific file types
• Add linguist overrides if needed (e.g., exclude generated files from stats)

4. GitHub Configuration (. github/)

• Workflows (.github/workflows/):

  • Audit existing CI/CD pipelines
  • Remove deprecated or unused workflows
  • Ensure workflows follow naming conventions
  • Add essential workflows if missing (CI, linting, security scanning, release)
  • Optimize workflow triggers and caching strategies
  • Add meaningful job and step names with emojis for clarity

• Issue Templates (.github/ISSUE_TEMPLATE/):

  • Create templates for: bug reports, feature requests, questions
  • Use YAML forms for structured input
  • Include all necessary fields with validation

• Pull Request Template (.github/pull_request_template.md):

  • Add checklist for contributors
  • Include sections for description, testing, breaking changes

• CODEOWNERS: Define code ownership for automatic review requests

• Dependabot (.github/dependabot.yml):

  • Configure automated dependency updates
  • Set appropriate schedules and reviewers

• GitHub Actions Reusable Workflows:

  • Extract common workflow patterns into reusable workflows

5. Code & File Organization

• Naming Conventions:

  • Ensure consistent file naming (kebab-case, camelCase, or snake_case based on language)
  • Use descriptive, meaningful names
  • Avoid abbreviations unless widely understood

• File Placement:

  • Source code in /src or language-specific root
  • Tests alongside source or in /tests or /test
  • Configuration files in root or /config
  • Scripts in /scripts or /tools

• Dead Code Removal:

  • Identify and remove unused files, functions, and imports
  • Remove commented-out code blocks
  • Clean up TODO comments (convert to issues or resolve)

6. Dependency Management

• Audit all dependencies (package.json, requirements.txt, pom.xml, etc.)
• Remove unused dependencies
• Update outdated dependencies (check for breaking changes)
• Separate production and development dependencies
• Lock dependency versions for reproducibility
• Document dependency choices for non-obvious libraries
• Check for security vulnerabilities

7. Developer Experience (DX) Enhancements

• Setup Automation:

  • Add setup scripts (setup.sh, setup.ps1, Makefile)
  • Document prerequisites clearly

• EditorConfig: Add .editorconfig for consistent coding styles across IDEs

• Linting & Formatting:

  • Configure linters (ESLint, Pylint, Checkstyle, etc.)
  • Add formatting tools (Prettier, Black, google-java-format)
  • Add pre-commit hooks (using husky, pre-commit, etc.)

• Environment Management:

  • Provide .env. example or .env.template
  • Document all required environment variables

• Docker Support:

  • Add/update Dockerfile and docker-compose.yml
  • Optimize for layer caching
  • Add . dockerignore

8. Quality Assurance

• Ensure test coverage is visible and tracked
• Add/update test configuration files
• Verify all scripts are executable and documented
• Check that examples actually work
• Validate all URLs in documentation
• Ensure consistent code style throughout the project

9. Metadata & Configuration

• Update package metadata (version, description, keywords, authors, repository URL)
• Add/update repository topics on GitHub
• Configure repository settings (branch protection, merge strategies)
• Add repository description and website URL

🎨 Quality Standards

Apply these principles throughout the cleanup:

1. Consistency - Use the same patterns, naming, and structure throughout
2. Clarity - Make everything self-explanatory; prefer explicit over implicit
3. Completeness - Don't leave tasks half-done; follow through
4. Convention - Follow language/framework conventions and industry best practices
5. Maintainability - Optimize for future developers, including your future self
6. Documentation - If it's not documented, it doesn't exist
7. Automation - Automate repetitive tasks and enforce standards via tooling
8. Security - Never commit secrets; use proper secret management

📊 Deliverables

After completing the cleanup, provide:

1. Summary Report: Overview of all changes made and why
2. Migration Guide: If structure changes significantly, document how to migrate
3. Recommendations: Future improvements that are out of scope for this cleanup
4. Checklist Status: Mark all completed tasks above

🚀 Execution Strategy

1. Analyze First: Don't make changes blindly; understand the current state
2. Prioritize: Start with high-impact, low-risk changes
3. Incremental: Make changes in logical groups, not all at once
4. Test: Verify nothing breaks after reorganization
5. Document: Explain significant changes in commit messages or PR description
6. Review: Double-check before finalizing

💡 Additional Context

• Project Type: [Specify: Library, Application, Monorepo, etc.]
• Tech Stack: [List primary languages and frameworks]
• Team Size: [Solo, Small team, Large organization]
• Maturity: [Proof of concept, MVP, Production, Legacy]

Remember: You are creating a PROFESSIONAL, PRODUCTION-READY repository that any developer should be able to clone, understand, and contribute to within minutes. Aim for excellence, not just "good enough."

Let's make this repository a model of best practices! 🎯