claude-mpm 5.4.3__py3-none-any.whl → 5.4.21__py3-none-any.whl

claude_mpm/commands/mpm-organize.md

@@ -4,11 +4,11 @@ command: organize
 aliases: [mpm-organize]
 migration_target: /mpm/system:organize
 category: system
-description: Organize project files into proper directories with intelligent pattern detection
+description: Organize all project files including documentation, source code, tests, scripts, and configuration with intelligent consolidation and pruning
 ---
 # /mpm-organize
 
-Organize your project files into proper directories using intelligent pattern detection and framework-aware structure management.
+Organize ALL project files into a clean, structured format with intelligent detection of existing patterns. Includes special handling for documentation consolidation, pruning, and triage into research/user/developer categories.
 
 ## Usage
 
@@ -17,25 +17,35 @@ Organize your project files into proper directories using intelligent pattern de
 /mpm-organize --dry-run             # Preview changes without applying
 /mpm-organize --force               # Proceed even with uncommitted changes
 /mpm-organize --no-backup           # Skip backup creation (not recommended)
+/mpm-organize --docs-only           # Only organize documentation files
 ```
 
 ## Description
 
-This slash command delegates to the **Project Organizer agent** to perform thorough project housekeeping. The agent analyzes your project structure, detects existing patterns and framework conventions, then organizes files into proper directories following best practices.
+This slash command delegates to the **Project Organizer agent** to perform intelligent project organization across ALL file types. The agent analyzes your project structure, detects existing patterns, consolidates duplicates, removes stale content, and organizes everything into a clean, logical structure.
 
-**Smart Organization**: The agent follows the official [Project Organization Standard](../../../docs/reference/PROJECT_ORGANIZATION.md), which defines comprehensive organization rules for Claude MPM projects. It also checks CLAUDE.md for project-specific guidelines and respects framework-specific conventions.
+**Comprehensive Scope**: This command organizes ALL project files including:
+- **Documentation** (.md, .rst, .txt) - consolidate, prune, triage into research/user/developer
+- **Source code** - proper module structure and organization
+- **Tests** - organized test suites
+- **Scripts** - automation tools and utilities
+- **Configuration** - project config files
 
-**Standard Documentation**: After organizing, this command ensures the organization standard is documented and accessible at `docs/reference/PROJECT_ORGANIZATION.md` with proper linking from CLAUDE.md.
+**Smart Detection**: The agent first looks for existing organization patterns in your project (e.g., PROJECT_ORGANIZATION.md, CONTRIBUTING.md). If found, it respects and extends those patterns. If not found, it applies framework-appropriate defaults.
 
 ## Features
 
-- **📁 Intelligent Pattern Detection**: Analyzes existing directory structure and naming conventions
-- **🎯 Framework-Aware**: Respects Next.js, React, Django, Rails, and other framework patterns
-- **🔍 CLAUDE.md Integration**: Follows project-specific guidelines when available
+- **📁 Pattern Detection**: Analyzes existing project structure and detects organization conventions
+- **🔄 Consolidation**: Merges duplicate or related files (especially documentation)
+- **✂️ Pruning**: Identifies and removes outdated, stale, or redundant content
+- **📋 Triage**: Categorizes documentation into research/user/developer directories
+- **🏗️ Code Organization**: Ensures proper module structure and file placement
+- **🧪 Test Organization**: Organizes test suites into proper directories
+- **📜 Script Organization**: Moves scripts to dedicated scripts/ directory
 - **✅ Safe Operations**: Uses `git mv` for tracked files to preserve history
 - **💾 Automatic Backups**: Creates backups before major reorganizations
-- **🔄 Import Path Updates**: Updates import statements after file moves
 - **📊 Organization Report**: Detailed summary of changes and recommendations
+- **🎯 Smart Scope**: Full project or documentation-only mode (--docs-only)
 
 ## Options
 
@@ -44,11 +54,17 @@ This slash command delegates to the **Project Organizer agent** to perform thoro
 - `--no-backup`: Skip backup creation before reorganization (not recommended)
 - `--force`: Proceed even with uncommitted changes (use with caution)
 
-### Organization Options
-- `--docs-only`: Only organize documentation files
+### Scope Options
+- `--docs-only`: Only organize documentation files (legacy behavior)
+- `--code-only`: Only organize source code files
 - `--tests-only`: Only organize test files
 - `--scripts-only`: Only organize script files
-- `--skip-imports`: Don't update import paths after moves
+
+### Organization Options
+- `--consolidate-only`: Only consolidate duplicate files, skip reorganization
+- `--prune-only`: Only identify and remove stale files
+- `--triage-only`: Only categorize files without moving them
+- `--no-prune`: Skip pruning phase (keep all existing files)
 
 ### Output Options
 - `--verbose`: Show detailed analysis and reasoning
@@ -57,178 +73,312 @@ This slash command delegates to the **Project Organizer agent** to perform thoro
 
 ## What This Command Does
 
-### 1. Organization Standard Verification
-- Ensures `docs/reference/PROJECT_ORGANIZATION.md` exists and is current
-- Creates or updates the standard if needed
-- Links the standard from CLAUDE.md for easy reference
+### 1. Pattern Detection
+- Scans existing project structure across all file types
+- Identifies organization conventions (PROJECT_ORGANIZATION.md, CONTRIBUTING.md)
+- Detects framework-specific patterns (Next.js, Django, Flask, etc.)
+- Detects existing documentation organization
+- Falls back to framework-appropriate defaults if no pattern found
 
-### 2. CLAUDE.md Analysis
-- Checks for existing organization guidelines
-- Extracts project-specific rules and conventions
-- Identifies priority areas for organization
+### 2. Standard Project Structure
 
-### 3. Project Structure Detection
-- Scans directory hierarchy and patterns
-- Identifies naming conventions (camelCase, kebab-case, snake_case)
-- Maps current file type locations
-- Detects framework-specific conventions (Next.js, Django, Rails, etc.)
-- Determines organization type (feature/type/domain-based)
-
-### 4. File Organization Strategy
-
-The agent organizes files into standard directories per [PROJECT_ORGANIZATION.md](../../../docs/reference/PROJECT_ORGANIZATION.md):
+If no existing pattern is detected, organizes according to project type:
 
+**Documentation** (all project types):
 ```
-docs/           # All documentation files (*.md, guides, architecture)
-tests/          # All test files and test utilities
-tmp/            # Temporary and ephemeral files
-scripts/        # Ad-hoc scripts and utilities
-src/            # Source code following framework conventions
-.claude/        # Claude MPM configuration and agents
+docs/
+├── research/     # Research findings, analysis, investigations
+│   ├── spikes/   # Technical spikes and experiments
+│   └── notes/    # Development notes and brainstorming
+├── user/         # User-facing documentation
+│   ├── guides/   # How-to guides and tutorials
+│   ├── faq/      # Frequently asked questions
+│   └── examples/ # Usage examples
+└── developer/    # Developer documentation
+    ├── api/      # API documentation
+    ├── architecture/ # Architecture decisions and diagrams
+    └── contributing/ # Contribution guidelines
 ```
 
-### 5. Framework-Specific Handling
+**Source Code** (framework-specific):
+- Python: `src/package_name/` structure
+- JavaScript/TypeScript: Framework conventions (Next.js, React, etc.)
+- Other: Language-appropriate module structure
+
+**Tests**: `tests/` with mirrored source structure
+
+**Scripts**: `scripts/` for automation tools
+
+**Configuration**: Root or `config/` depending on project size
+
+### 3. File Consolidation
+
+Identifies and merges duplicate/similar files:
+
+**Documentation**:
+- Duplicate README files
+- Similar guide documents
+- Redundant architecture notes
+- Multiple versions of same doc
+- Scattered meeting notes
 
-**Next.js Projects**:
-- Respects `pages/`, `app/`, `public/`, API routes
-- Organizes components by feature or domain
-- Maintains Next.js conventions
+**Code**:
+- Duplicate utility functions
+- Similar helper modules
+- Redundant configuration files
 
-**Django Projects**:
-- Maintains app structure
-- Organizes migrations, templates, static files
-- Preserves Django conventions
+### 4. Content Pruning
 
-**React Projects**:
-- Organizes components, hooks, utils
-- Maintains component hierarchy
-- Groups related files
+Removes or archives stale/obsolete content:
 
-**Other Frameworks**:
-- Detects and respects framework conventions
-- Applies appropriate organizational patterns
+**Documentation**:
+- Outdated documentation (last modified >6 months)
+- Stale TODO lists and notes
+- Obsolete architecture documents
+- Deprecated API documentation
+- Empty or placeholder files
+
+**Code**:
+- Commented-out code blocks
+- Unused imports and dependencies
+- Dead code (unreferenced functions/classes)
+
+### 5. File Categorization & Triage
+
+Categorizes and organizes files by purpose:
+
+**Documentation**:
+- **Research**: Analysis, spikes, investigations, experiments
+- **User**: Guides, tutorials, FAQs, how-tos
+- **Developer**: API docs, architecture, contributing guides
+
+**Code**:
+- Source code to proper module structure
+- Tests to organized test suites
+- Scripts to scripts/ directory
+- Configuration to appropriate locations
 
 ### 6. Safe File Movement
 
-For each file to be moved:
-1. Analyzes file purpose and dependencies
-2. Determines optimal location based on patterns
+For each file being organized:
+1. Analyzes file type, content, and purpose
+2. Determines optimal location based on detected patterns
 3. Uses `git mv` for version-controlled files
-4. Updates import paths in affected files
-5. Validates build still works
+4. Preserves git history
+5. Creates backup before major changes
+6. Validates move doesn't break imports or references
 
 ### 7. Backup Creation
 
-Before major reorganization:
+Before reorganization:
 ```bash
-backup_YYYYMMDD_HHMMSS.tar.gz  # Complete project backup
+backup_project_YYYYMMDD_HHMMSS.tar.gz  # Full project backup (or docs-only)
 ```
 
-### 8. Import Path Updates
+### 8. Protected Files (Never Moved)
+
+These files remain in project root:
+- `README.md`, `CHANGELOG.md`, `LICENSE.md`
+- `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`
+- `CLAUDE.md`, `CODE.md`, `DEVELOPER.md`
+- Package files: `package.json`, `pyproject.toml`, `Cargo.toml`, etc.
+- Build configs: `Makefile`, `Dockerfile`, `docker-compose.yml`
+- Git files: `.gitignore`, `.gitattributes`
+- Environment templates: `.env.example`, `.env.sample`
 
-Automatically updates:
-- Python imports (`from old.path import X` → `from new.path import X`)
-- JavaScript/TypeScript imports (`import X from './old/path'` → `import X from './new/path'`)
-- Relative path references
-- Configuration file paths
+### 9. Files Excluded from Organization
 
-### 9. Organization Report
+Never touched:
+- Build artifacts: `dist/`, `build/`, `node_modules/`, `__pycache__/`
+- Version control: `.git/`, `.svn/`, `.hg/`
+- Virtual environments: `venv/`, `.venv/`, `env/`
+- IDE configs: `.vscode/`, `.idea/` (unless --config-only)
+
+### 10. Organization Report
 
 Generates detailed report including:
-- Files moved and their new locations
+- All files moved with before/after locations
+- Files consolidated (merged) with change summary
+- Files pruned (removed or archived) with reasoning
 - Pattern analysis and detected conventions
-- Import paths updated
+- Import/reference validation results
 - Recommendations for further improvements
-- Violations of best practices (if any)
 
 ## Examples
 
-### Preview Organization (Recommended First Run)
+### Preview Full Project Organization (Recommended First Run)
 ```bash
 /mpm-organize --dry-run
 ```
-Shows what would be changed without making any modifications.
+Shows what changes would be made across ALL project files without applying them.
+
+### Preview Documentation Organization Only
+```bash
+/mpm-organize --docs-only --dry-run
+```
+Shows what documentation changes would be made (legacy behavior).
 
-### Full Organization with Backup
+### Full Project Organization with Backup
 ```bash
 /mpm-organize
 ```
-Interactive mode with automatic backup before changes.
+Interactive mode with automatic backup before organizing all project files.
 
-### Force Organization (With Uncommitted Changes)
+### Organize Tests and Scripts Only
 ```bash
-/mpm-organize --force --verbose
+/mpm-organize --tests-only --scripts-only
 ```
-Organizes project even with uncommitted changes, shows detailed output.
+Focus on organizing test files and scripts, leave everything else untouched.
 
-### Organize Documentation Only
+### Consolidate Duplicate Files Only
 ```bash
-/mpm-organize --docs-only --dry-run
+/mpm-organize --consolidate-only --dry-run
+```
+Preview which duplicate files would be merged across the project.
+
+### Identify Stale Files (All Types)
+```bash
+/mpm-organize --prune-only --dry-run
 ```
-Preview how documentation files would be organized.
+See which outdated files would be removed or archived.
 
-### Quick Organization Without Backup
+### Triage Documentation by Category
 ```bash
-/mpm-organize --no-backup
+/mpm-organize --docs-only --triage-only --verbose
 ```
-Skip backup creation for small changes (use with caution).
+Categorize documentation into research/user/developer without moving files.
+
+### Full Organization Without Pruning
+```bash
+/mpm-organize --no-prune
+```
+Organize and consolidate all files but keep everything (no deletions).
 
 ### Save Organization Report
 ```bash
-/mpm-organize --report /tmp/organize-report.md
+/mpm-organize --report /tmp/project-organize-report.md
 ```
-Save detailed report to file for review.
+Save detailed organization report to file for review.
 
 ## Implementation
 
-This slash command delegates to the **Project Organizer agent** (`project-organizer`), which performs intelligent file organization based on detected patterns and framework conventions.
+This slash command delegates to the **Project Organizer agent** (`project-organizer`), which performs intelligent project organization based on detected patterns and content analysis across all file types.
 
 The agent receives the command options as context and then:
-1. Analyzes CLAUDE.md for organization guidelines
-2. Detects project framework and patterns
-3. Identifies misplaced files
-4. Creates safe reorganization plan
-5. Executes file moves with git integration
-6. Updates import paths across codebase
-7. Validates build integrity
-8. Generates organization report
+1. **Scans** for all project files (or scope-specific with --docs-only, --tests-only, etc.)
+2. **Detects** existing organization patterns (PROJECT_ORGANIZATION.md, CONTRIBUTING.md, framework conventions)
+3. **Analyzes** file content, purpose, and relationships
+4. **Categorizes** files by type and purpose (documentation by audience, code by module, tests by coverage)
+5. **Identifies** duplicates, stale content, and misplaced files
+6. **Validates** that moves won't break imports or references
+7. **Creates** safe reorganization plan with detailed reasoning
+8. **Executes** file moves with git integration (preserves history)
+9. **Generates** comprehensive organization report
 
 When you invoke `/mpm-organize [options]`, Claude MPM:
 - Passes the options to the Project Organizer agent as task context
-- The agent executes the organization workflow
-- Results are returned to you through the agent's structured output
+- The agent executes the comprehensive organization workflow
+- Results are returned through structured output with detailed change log
+
+**Scope Control**:
+- Default: Organizes ALL project files (comprehensive)
+- `--docs-only`: Only documentation files (legacy behavior)
+- `--code-only`, `--tests-only`, `--scripts-only`: Specific file types
 
 ## Expected Output
 
-### Dry Run Mode
+### Dry Run Mode (Full Project)
 ```
 🔍 Analyzing project structure...
-✓ Detected framework: Next.js
-✓ Organization pattern: Feature-based
-✓ Found CLAUDE.md guidelines
+✓ Detected PROJECT_ORGANIZATION.md - using project standards
+✓ Found Python Flask project with standard structure
+✓ Found 23 documentation files
+✓ Found 15 misplaced test files
+✓ Found 8 scripts in root directory
+✓ Identified 3 duplicate READMEs
+✓ Found 5 stale files
 
 📁 Proposed Changes:
 
-  docs/
-    ← README_OLD.md (from root)
-    ← architecture-notes.txt (from root)
+  Documentation:
+    Consolidate:
+      → Merge README_OLD.md + README_BACKUP.md → docs/user/README.md
+      → Merge architecture-v1.md + architecture-v2.md → docs/developer/architecture/decisions.md
+
+    Organize:
+      docs/research/
+        ← spike-oauth.md (from root)
+        ← performance-analysis.md (from root)
+      docs/user/guides/
+        ← getting-started.md (from root)
+        ← installation.md (from docs/)
+
+    Prune:
+      ✂ Remove TODO_2023.md (last modified 18 months ago)
+      ✂ Archive deprecated-api.md → docs/_archive/
+
+  Tests:
+    tests/unit/
+      ← test_auth.py (from root)
+      ← test_utils.py (from src/)
+    tests/integration/
+      ← test_api_integration.py (from root)
+
+  Scripts:
+    scripts/
+      ← deploy.sh (from root)
+      ← run_tests.py (from root)
+      ← backup_db.sh (from utils/)
+
+  Source Code:
+    src/myapp/utils/
+      → Consolidate helpers.py + utility_functions.py → utils.py
+
+📊 Summary:
+  - 8 documentation files to move
+  - 4 files to consolidate (2 merged)
+  - 5 files to prune (3 removed, 2 archived)
+  - 15 test files to organize
+  - 8 scripts to move
+  - 2 code files to consolidate
+
+Run without --dry-run to apply changes.
+```
 
-  tests/
-    ← test_helper.py (from src/)
-    ← api.test.js (from src/api/)
+### Dry Run Mode (Documentation Only)
+```bash
+/mpm-organize --docs-only --dry-run
+```
+```
+🔍 Analyzing documentation structure...
+✓ Detected existing pattern: docs/guides/ and docs/reference/
+✓ Found 23 documentation files
+✓ Identified 3 duplicate READMEs
+✓ Found 5 stale documentation files
 
-  tmp/
-    ← debug_output.log (from root)
-    ← scratch.py (from root)
+📁 Proposed Changes:
+
+  Consolidate:
+    → Merge README_OLD.md + README_BACKUP.md → docs/user/README.md
+    → Merge architecture-v1.md + architecture-v2.md → docs/developer/architecture/decisions.md
+
+  Prune:
+    ✂ Remove TODO_2023.md (last modified 18 months ago)
+    ✂ Archive deprecated-api.md → docs/_archive/
+    ✂ Remove empty placeholder.md
 
-  scripts/
-    ← migrate.sh (from root)
-    ← deploy_helper.py (from root)
+  Organize:
+    docs/research/
+      ← spike-oauth.md (from root)
+      ← performance-analysis.md (from root)
+    docs/user/guides/
+      ← getting-started.md (from root)
+      ← installation.md (from docs/)
 
 📊 Summary:
-  - 8 files to move
-  - 12 import paths to update
-  - 0 conflicts detected
+  - 8 documentation files to move
+  - 4 files to consolidate (2 merged files)
+  - 5 files to prune (3 removed, 2 archived)
 
 Run without --dry-run to apply changes.
 ```
@@ -236,68 +386,115 @@ Run without --dry-run to apply changes.
 ### Actual Organization
 ```
 🔍 Analyzing project structure...
-✓ Detected framework: Next.js
-✓ Organization pattern: Feature-based
-✓ Created backup: backup_20250102_143022.tar.gz
+✓ Detected PROJECT_ORGANIZATION.md - using project standards
+✓ Created backup: backup_project_20250102_143022.tar.gz
 
-📁 Organizing files...
-  ✓ Moved README_OLD.md → docs/
-  ✓ Moved architecture-notes.txt → docs/
-  ✓ Updated 5 import statements
+📁 Organizing project files...
+  ✓ Consolidated README_OLD.md + README_BACKUP.md → docs/user/README.md
+  ✓ Moved spike-oauth.md → docs/research/
+  ✓ Moved test_auth.py → tests/unit/
+  ✓ Moved deploy.sh → scripts/
+  ✓ Consolidated helpers.py + utility_functions.py → src/myapp/utils/utils.py
+  ✓ Pruned TODO_2023.md (stale)
+  ✓ Archived deprecated-api.md
 
-✅ Organization complete!
+✅ Project organization complete!
 
-📊 Report saved to: /tmp/organization-report.md
+📊 Report saved to: /tmp/project-organization-report.md
 ```
 
 ## Safety Guarantees
 
-- **Backup Created**: Full project backup before changes (unless --no-backup)
-- **Git Integration**: Uses `git mv` to preserve file history
-- **Dry Run Available**: Preview all changes before applying
-- **Import Updates**: Automatically fixes broken imports
-- **Build Validation**: Verifies build still works after changes
+- **Full Project Backup**: Backup of all affected files before changes (unless --no-backup)
+- **Git Integration**: Uses `git mv` to preserve file history for tracked files
+- **Dry Run Available**: Preview all changes before applying (--dry-run)
+- **Import Validation**: Validates that code moves won't break imports/references
+- **Protected Files**: Critical root files never moved (README.md, package.json, etc.)
 - **Rollback Support**: Backup enables full rollback if needed
+- **Conservative Pruning**: Stale files are archived rather than deleted when in doubt
+- **Scope Control**: Limit changes to specific file types (--docs-only, --tests-only, etc.)
 
 ## When to Use This Command
 
 Use `/mpm-organize` when:
-- Starting a new project and establishing structure
-- Project has accumulated misplaced files
-- After major feature additions
-- Before major refactoring
-- When onboarding new team members
-- To enforce organization standards
+- **Project has grown organically** and structure has become messy
+- **Test files are scattered** across the codebase
+- **Scripts are in root** instead of scripts/ directory
+- **Documentation is disorganized** with duplicates and stale content
+- **Code has duplicated utilities** that should be consolidated
+- **Starting a new project** and establishing clean structure
+- **Before a major release** (clean up everything)
+- **After a major refactor** (reorganize changed files)
+- **When onboarding new team members** (clear, organized structure)
+- **After accumulating research notes** and experimental code
 
 ## Best Practices
 
-1. **Always Start with Dry Run**: Use `--dry-run` first to preview changes
-2. **Commit First**: Commit your work before organizing (or use --force)
-3. **Review CLAUDE.md**: Ensure guidelines are current before organizing
-4. **Test After**: Run tests after organization to verify nothing broke
-5. **Update Documentation**: Document any new organizational patterns
+1. **Always Start with Dry Run**: Use `--dry-run` first to preview ALL changes
+2. **Commit First**: Commit your work before organizing (or use --force, but not recommended)
+3. **Start Small**: Use `--docs-only` first, then expand to full project organization
+4. **Review Proposed Changes**: Carefully review consolidations and moves
+5. **Verify Pruning Decisions**: Review stale files before removal, some may still be valuable
+6. **Test After Organization**: Run tests after organizing to ensure imports still work
+7. **Update Links**: Check that documentation links and imports still work
+8. **Document Structure**: Update README or PROJECT_ORGANIZATION.md to reflect new structure
+9. **Use Scope Flags**: Limit scope with `--docs-only`, `--tests-only`, etc. for focused changes
+10. **Review Report**: Always check the organization report for detailed change log
 
 ## Notes
 
 - This slash command delegates to the **Project Organizer agent** (`project-organizer`)
-- The agent performs intelligent file placement based on learned patterns
-- Respects framework-specific conventions automatically
+- The agent performs intelligent organization across **all project file types**
+- **Default behavior**: Organizes ALL files (comprehensive project organization)
+- **Legacy behavior**: Use `--docs-only` to only organize documentation (old default)
 - Integrates with git to preserve file history
-- Updates import paths to prevent build breakage
 - Creates comprehensive reports for audit trails
-- Can be run repeatedly safely (idempotent)
-- Follows guidelines in CLAUDE.md when available
-- Falls back to framework conventions and best practices
-
-## Related Documentation
-
-- **[Project Organization Standard](../../../docs/reference/PROJECT_ORGANIZATION.md)**: Comprehensive organization rules and guidelines
-- **[Project Structure](../../../docs/developer/STRUCTURE.md)**: Authoritative file organization reference
-- **[CLAUDE.md](../../../CLAUDE.md)**: Development guidelines with organization quick reference
+- Can be run repeatedly safely (idempotent within scope)
+- Detects existing patterns and respects them (PROJECT_ORGANIZATION.md, CONTRIBUTING.md)
+- Falls back to framework-appropriate defaults if no pattern detected
+
+## What Gets Organized (by Default)
+
+**ALL project files by default**, including:
+
+**Documentation**:
+- Markdown files (*.md)
+- reStructuredText files (*.rst)
+- Text documentation (*.txt in docs/ or with doc-like names)
+- README files in various locations (except root README.md)
+- Guide and tutorial files
+- Architecture and design documents
+
+**Source Code**:
+- Python files (*.py) - organized into proper module structure
+- JavaScript/TypeScript (*.js, *.ts, *.jsx, *.tsx)
+- Other language source files
+- Utilities and helper modules
+
+**Tests**:
+- Unit tests (*_test.*, test_*.*)
+- Integration tests
+- Test fixtures and utilities
+
+**Scripts**:
+- Shell scripts (*.sh, *.bash)
+- Python scripts (identified by patterns)
+- Build and deployment scripts
+
+**Configuration** (with caution):
+- Project-specific configs (not package.json, pyproject.toml, etc.)
+- Environment config templates
+
+**Files NEVER touched (protected)**:
+- Root README.md, CHANGELOG.md, LICENSE.md
+- Package files (package.json, pyproject.toml, Cargo.toml, etc.)
+- Build artifacts (dist/, build/, target/, node_modules/, __pycache__/)
+- Git files (.git/, .gitignore, .gitattributes)
+- CI/CD files (.github/, .gitlab-ci.yml, etc.)
+- Virtual environments (venv/, .venv/, env/)
 
 ## Related Commands
 
 - `/mpm-init`: Initialize or update project documentation and structure
-- `/mpm-doctor`: Diagnose project health and issues
+- `/mpm-doctor`: Diagnose project health and issues (includes documentation checks)
 - `/mpm-status`: Check current project state
-- `/mpm-config`: Configure organization rules and preferences