claude-mpm 4.24.0__py3-none-any.whl → 5.4.41__py3-none-any.whl

claude_mpm/commands/mpm-organize.md

@@ -1,295 +1,120 @@
+---
+namespace: mpm/system
+command: organize
+aliases: [mpm-organize]
+migration_target: /mpm/system:organize
+category: system
+description: Organize project files with intelligent consolidation
+---
 # /mpm-organize
 
-Organize your project files into proper directories using intelligent pattern detection and framework-aware structure management.
+Organize ALL project files with intelligent detection, consolidation, and pruning.
 
 ## Usage
-
 ```
-/mpm-organize                       # Interactive mode with preview
-/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 [--dry-run] [--force] [options]
 ```
 
-## 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.
-
-**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.
-
-**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.
+**Delegates to Project Organizer agent** for comprehensive file organization.
 
-## Features
+## Scope
 
-- **📁 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
-- **✅ 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
+**Default:** Organizes ALL project files
+- Documentation (.md, .rst, .txt)
+- Source code (proper module structure)
+- Tests (organized test suites)
+- Scripts (scripts/ directory)
+- Configuration (appropriate locations)
 
-## Options
+**Protected files (never moved):** README.md, package.json, pyproject.toml, Makefile, .gitignore, etc.
 
-### Safety Options
-- `--dry-run`: Preview all changes without making them (recommended first run)
-- `--no-backup`: Skip backup creation before reorganization (not recommended)
-- `--force`: Proceed even with uncommitted changes (use with caution)
+## Key Options
 
-### Organization Options
-- `--docs-only`: Only organize documentation files
-- `--tests-only`: Only organize test files
-- `--scripts-only`: Only organize script files
-- `--skip-imports`: Don't update import paths after moves
+**Safety:**
+- `--dry-run`: Preview without changes (recommended first run)
+- `--force`: Proceed with uncommitted changes
+- `--no-backup`: Skip backup (not recommended)
 
-### Output Options
-- `--verbose`: Show detailed analysis and reasoning
-- `--quiet`: Minimal output, errors only
-- `--report [path]`: Save organization report to file
+**Scope:**
+- `--docs-only`: Only documentation (legacy behavior)
+- `--code-only` / `--tests-only` / `--scripts-only`: Specific file types
 
-## What This Command Does
+**Operations:**
+- `--consolidate-only`: Merge duplicates only
+- `--prune-only`: Remove stale files only
+- `--no-prune`: Keep all files (no deletions)
 
-### 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
+## What It Does
 
-### 2. CLAUDE.md Analysis
-- Checks for existing organization guidelines
-- Extracts project-specific rules and conventions
-- Identifies priority areas for organization
+1. **Pattern Detection:** Scans for existing organization (PROJECT_ORGANIZATION.md, framework conventions)
+2. **Consolidation:** Merges duplicates (READMEs, guides, utilities)
+3. **Pruning:** Archives/removes stale content (>6 months old, empty files)
+4. **Categorization:** Sorts docs into research/user/developer
+5. **Safe Movement:** Uses `git mv` to preserve history
+6. **Backup:** Creates backup_project_YYYYMMDD_HHMMSS.tar.gz
 
-### 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):
+## Standard Structure
 
 ```
-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/        # Spikes, analysis, notes
+├── user/            # Guides, tutorials, FAQs
+└── developer/       # API docs, architecture, contributing
+
+src/<package>/       # Proper module structure
+tests/               # Mirrored source structure
+scripts/             # Automation tools
+config/              # Configuration (if needed)
 ```
 
-### 5. Framework-Specific Handling
-
-**Next.js Projects**:
-- Respects `pages/`, `app/`, `public/`, API routes
-- Organizes components by feature or domain
-- Maintains Next.js conventions
-
-**Django Projects**:
-- Maintains app structure
-- Organizes migrations, templates, static files
-- Preserves Django conventions
-
-**React Projects**:
-- Organizes components, hooks, utils
-- Maintains component hierarchy
-- Groups related files
-
-**Other Frameworks**:
-- Detects and respects framework conventions
-- Applies appropriate organizational patterns
-
-### 6. Safe File Movement
-
-For each file to be moved:
-1. Analyzes file purpose and dependencies
-2. Determines optimal location based on patterns
-3. Uses `git mv` for version-controlled files
-4. Updates import paths in affected files
-5. Validates build still works
-
-### 7. Backup Creation
-
-Before major reorganization:
-```bash
-backup_YYYYMMDD_HHMMSS.tar.gz  # Complete project backup
-```
-
-### 8. Import Path Updates
-
-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. Organization Report
-
-Generates detailed report including:
-- Files moved and their new locations
-- Pattern analysis and detected conventions
-- Import paths updated
-- Recommendations for further improvements
-- Violations of best practices (if any)
-
 ## Examples
 
-### Preview Organization (Recommended First Run)
 ```bash
+# Preview changes (recommended first)
 /mpm-organize --dry-run
-```
-Shows what would be changed without making any modifications.
 
-### Full Organization with Backup
-```bash
+# Organize everything with backup
 /mpm-organize
-```
-Interactive mode with automatic backup before changes.
-
-### Force Organization (With Uncommitted Changes)
-```bash
-/mpm-organize --force --verbose
-```
-Organizes project even with uncommitted changes, shows detailed output.
 
-### Organize Documentation Only
-```bash
+# Documentation only
 /mpm-organize --docs-only --dry-run
-```
-Preview how documentation files would be organized.
 
-### Quick Organization Without Backup
-```bash
-/mpm-organize --no-backup
-```
-Skip backup creation for small changes (use with caution).
+# Consolidate without pruning
+/mpm-organize --consolidate-only --no-prune
 
-### Save Organization Report
-```bash
+# Save report
 /mpm-organize --report /tmp/organize-report.md
 ```
-Save detailed 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.
-
-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
-
-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
 
 ## Expected Output
 
-### Dry Run Mode
 ```
 🔍 Analyzing project structure...
-✓ Detected framework: Next.js
-✓ Organization pattern: Feature-based
-✓ Found CLAUDE.md guidelines
+✓ Detected PROJECT_ORGANIZATION.md - using project standards
+✓ Found 23 documentation files, 15 test files, 8 scripts
 
 📁 Proposed Changes:
 
-  docs/
-    ← README_OLD.md (from root)
-    ← architecture-notes.txt (from root)
-
-  tests/
-    ← test_helper.py (from src/)
-    ← api.test.js (from src/api/)
-
-  tmp/
-    ← debug_output.log (from root)
-    ← scratch.py (from root)
+  Consolidate:
+    → Merge README_OLD.md + README_BACKUP.md → docs/user/README.md
 
-  scripts/
-    ← migrate.sh (from root)
-    ← deploy_helper.py (from root)
+  Organize:
+    docs/research/ ← spike-oauth.md (from root)
+    tests/unit/ ← test_auth.py (from root)
+    scripts/ ← deploy.sh (from root)
 
-📊 Summary:
-  - 8 files to move
-  - 12 import paths to update
-  - 0 conflicts detected
+  Prune:
+    ✂ Remove TODO_2023.md (stale 18 months)
 
-Run without --dry-run to apply changes.
+📊 Summary: 8 to move, 2 to merge, 3 to prune
 ```
 
-### Actual Organization
-```
-🔍 Analyzing project structure...
-✓ Detected framework: Next.js
-✓ Organization pattern: Feature-based
-✓ Created backup: backup_20250102_143022.tar.gz
-
-📁 Organizing files...
-  ✓ Moved README_OLD.md → docs/
-  ✓ Moved architecture-notes.txt → docs/
-  ✓ Updated 5 import statements
-
-✅ Organization complete!
-
-📊 Report saved to: /tmp/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
-- **Rollback Support**: Backup enables full rollback if needed
-
-## 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
-
-## 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
-
-## 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
-- 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
+## Safety Features
 
-## Related Commands
+- Full project backup before changes
+- Git integration (preserves history)
+- Import validation (ensures moves won't break code)
+- Protected files never touched
+- Conservative pruning (archive when unsure)
 
-- `/mpm-init`: Initialize or update project documentation and structure
-- `/mpm-doctor`: Diagnose project health and issues
-- `/mpm-status`: Check current project state
-- `/mpm-config`: Configure organization rules and preferences
+See docs/commands/organize.md for full documentation.

claude_mpm/commands/mpm-postmortem.md

@@ -0,0 +1,21 @@
+---
+namespace: mpm/analysis
+command: postmortem
+aliases: [mpm-postmortem]
+migration_target: /mpm/analysis:postmortem
+category: analysis
+description: Analyze session errors and suggest improvements
+---
+# /mpm-postmortem
+
+Analyze session errors and generate improvement suggestions.
+
+## Usage
+```
+/mpm-postmortem [--auto-fix] [--create-prs] [--dry-run]
+```
+
+Analyzes errors from: scripts, skills, agents, user code.
+Generates: fixes, updates, PR recommendations, suggestions.
+
+See docs/commands/postmortem.md for details.

claude_mpm/commands/mpm-session-resume.md

@@ -0,0 +1,30 @@
+---
+namespace: mpm/session
+command: resume
+aliases: [mpm-session-resume]
+migration_target: /mpm/session:resume
+category: session
+description: Load context from paused session
+---
+# /mpm-session-resume
+
+Load and display context from most recent paused session.
+
+## Usage
+```
+/mpm-resume
+```
+
+**What it shows:**
+- Session summary and time elapsed
+- Completed work and current tasks
+- Git context and recent commits
+- Next recommended actions
+
+**Session location:** `.claude-mpm/sessions/session-*.json`
+
+**Token usage:** ~20-40k tokens (10-20% of context budget)
+
+**Note:** Reads existing sessions (created automatically at 70% context). Does NOT create new files.
+
+See docs/features/session-auto-resume.md for details.

claude_mpm/commands/mpm-status.md

@@ -1,75 +1,20 @@
-# Show claude-mpm status and environment
-
-Display the current status of Claude MPM including environment information, active services, and system health.
+---
+namespace: mpm/system
+command: status
+aliases: [mpm-status]
+migration_target: /mpm/system:status
+category: system
+description: Display Claude MPM system status
+---
+# /mpm-status
+
+Show MPM system status. Delegates to PM agent.
 
 ## Usage
-
 ```
 /mpm-status
 ```
 
-## Description
-
-This slash command delegates to the **PM agent** to gather and display comprehensive status information about your Claude MPM environment.
-
-## Implementation
-
-This slash command delegates to the **PM agent** to collect status information.
-
-When you run `/mpm-status`, the PM will:
-1. Check Claude MPM version and installation
-2. Verify Python environment and dependencies
-3. Query active services (WebSocket server, Hook Service, Monitor)
-4. Report memory system status
-5. Check agent deployment status
-6. Summarize current configuration
-
-## Information Displayed
-
-The PM agent will gather and present:
-
-- **Claude MPM Version**: Current version and build number
-- **Python Environment**: Python version, virtual environment status
-- **Active Services**:
-  - WebSocket server status and port
-  - Hook service status
-  - Monitor/dashboard status
-- **Memory Usage**: Agent memory files and sizes
-- **Agent Deployment**: Deployed agents and their locations
-- **Configuration**: Key configuration settings
-- **Project Info**: Current project directory and git status
-
-## Expected Output
-
-```
-Claude MPM Status Report
-========================
-
-Version: v4.5.15
-Python: 3.11.13
-Environment: Mamba (claude-mpm)
-
-Services:
-  ✓ WebSocket Server: Running (port 8765)
-  ✓ Hook Service: Active
-  ✓ Monitor: Running (port 3000)
-
-Agents Deployed: 5
-  - PM (Core)
-  - Engineer
-  - Prompt-Engineer
-  - Tester
-  - Project-Organizer
-
-Memory Files: 3 (2.4 MB)
-Configuration: Valid
-
-Project: /Users/masa/Projects/my-project
-Git Status: Clean (main branch)
-```
-
-## Related Commands
+Displays: version, services, agents, memory, configuration, project info.
 
-- `/mpm-doctor`: Diagnose issues and run health checks
-- `/mpm-config`: View or modify configuration
-- `/mpm-agents`: List and manage deployed agents
+See docs/commands/status.md for details.

claude_mpm/commands/mpm-ticket-view.md

@@ -0,0 +1,109 @@
+---
+namespace: mpm/ticket
+command: view
+aliases: [mpm-ticket-view]
+migration_target: /mpm/ticket:view
+category: tickets
+description: Orchestrate ticketing agent for project management workflows
+---
+# /mpm-ticket
+
+High-level ticketing workflows delegating to ticketing agent.
+
+## Usage
+```
+/mpm-ticket <subcommand> [options]
+```
+
+**CRITICAL:** PM delegates ALL ticketing operations to ticketing agent. PM NEVER uses MCP tools directly.
+
+## Subcommands
+
+### /mpm-ticket organize
+Review, transition states, update priorities, identify stale tickets.
+
+**MCP Tools (ticketing agent uses):**
+- ticket_list, ticket_read, ticket_comment
+- ticket_transition, ticket_update
+- ticket_find_stale
+
+**Output:** Tickets transitioned, priorities updated, stale tickets identified, next actions.
+
+### /mpm-ticket proceed
+Analyze project board and recommend next actionable steps.
+
+**MCP Tools (ticketing agent uses):**
+- project_status, ticket_list, ticket_search
+- epic_issues, get_available_transitions
+
+**Output:** Project health, recommended next actions (top 3), blockers requiring attention.
+
+### /mpm-ticket status
+Generate comprehensive status report covering work, tickets, project health.
+
+**MCP Tools (ticketing agent uses):**
+- project_status, ticket_list, ticket_search
+- ticket_find_stale, get_my_tickets
+
+**Output:** Health metrics, ticket counts, high-priority work, blockers, recent activity, risk assessment.
+
+### /mpm-ticket update
+Create project status update (Linear ProjectUpdate).
+
+**MCP Tools (ticketing agent uses):**
+- project_status, project_update_create
+- project_update_list, ticket_list
+
+**Output:** Update ID, health status, accomplishments, metrics, risks, next sprint focus, published link.
+
+### /mpm-ticket project <url>
+Set project URL for context (Linear/GitHub/JIRA).
+
+**MCP Tools (ticketing agent uses):**
+- config_set_default_project, epic_get, config_get
+
+**Output:** Project context configured, platform/ID/name, access verified, summary.
+
+## Delegation Pattern
+
+**WRONG ❌:**
+```
+# PM directly using MCP tools
+result = mcp__mcp-ticketer__ticket_list()
+```
+
+**CORRECT ✅:**
+```
+# PM delegates to ticketing agent
+PM: "I'll have ticketing organize tickets..."
+[PM constructs delegation prompt]
+[Ticketing agent uses MCP tools]
+PM: [Presents results]
+```
+
+## Fallback Strategy
+
+If mcp-ticketer unavailable, ticketing agent falls back to aitrackdown CLI:
+```bash
+aitrackdown status tasks
+aitrackdown show TICKET-123
+aitrackdown transition TICKET-123 done
+```
+
+**PM still delegates** - ticketing agent handles CLI fallback internally.
+
+## Example Workflows
+
+```bash
+# Organize and analyze
+/mpm-ticket organize          # Clean up board
+/mpm-ticket proceed           # Get next steps
+
+# Weekly update
+/mpm-ticket update            # Create status update
+
+# Project setup
+/mpm-ticket project https://linear.app/team/project/abc-123
+```
+
+See docs/commands/ticket.md for comprehensive documentation.