claude-mpm 5.4.85__py3-none-any.whl → 5.6.1__py3-none-any.whl

claude_mpm/skills/bundled/pm/mpm-init/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: mpm-init
+description: Initialize or update project for Claude Code and MPM
+user-invocable: true
+version: "1.0.0"
+category: mpm-command
+tags: [mpm-command, system, pm-required, setup]
+---
+
+# /mpm-init
+
+Initialize or intelligently update project for Claude Code and Claude MPM.
+
+## Usage
+
+```
+/mpm-init [update|context|resume|catchup] [options]
+```
+
+## Core Modes
+
+### Project Setup
+
+```
+/mpm-init                      # Auto-detect: offer update or create
+/mpm-init update               # Quick update (30-day git activity)
+/mpm-init --update             # Full documentation refresh
+/mpm-init --force              # Force recreate from scratch
+```
+
+**Delegates to Agentic Coder Optimizer agent** for:
+- CLAUDE.md creation/update (with priority rankings 🔴🟡🟢⚪)
+- AST analysis and code structure docs
+- Single-path workflows (ONE way to do ANYTHING)
+- Tool configuration, memory system, gitignore management
+
+**Smart Update Mode:** Auto-detects existing CLAUDE.md and offers update vs recreate.
+
+### Context Analysis
+
+```
+/mpm-init context [--days N]   # Intelligent git history analysis (default: 7 days)
+/mpm-init catchup              # Quick commit history (last 25 commits, no analysis)
+```
+
+**context:** Delegates to Research agent for deep analysis of:
+- Active work streams (from commit patterns)
+- Intent and motivation (from messages)
+- Risks and blockers
+- Recommended next actions
+
+**catchup:** Direct CLI execution, instant output.
+
+### Resume from Logs
+
+```
+/mpm-init resume [--list] [--session-id ID]
+```
+
+Reads stop event logs from `.claude-mpm/resume-logs/` and `.claude-mpm/responses/` showing:
+- What was being worked on
+- Tasks completed, files modified
+- Next steps, stop reason, token usage
+- Git context (branch, status)
+
+## Key Options
+
+**Configuration:**
+- `--project-type TYPE`: web, api, cli, library
+- `--framework NAME`: react, django, fastapi, etc.
+- `--ast-analysis` / `--no-ast-analysis`: Enable/disable code analysis
+- `--comprehensive` / `--minimal`: Full setup vs CLAUDE.md only
+
+**Organization:**
+- `--organize`: Organize misplaced files
+- `--preserve-custom`: Keep custom sections (default)
+- `--review`: Review without changes
+
+## What Gets Created
+
+**New Projects:**
+- ✅ CLAUDE.md (priority-ranked instructions)
+- ✅ Single-path workflows (make build/test/deploy)
+- ✅ Tool configs (linting, formatting, testing)
+- ✅ Memory system (.claude-mpm/memories/)
+- ✅ DEVELOPER.md, CODE_STRUCTURE.md (with AST)
+- ✅ .gitignore updates (auto-adds .claude-mpm/)
+
+**Updates:**
+- ✅ Smart merging (preserves custom sections)
+- ✅ Automatic archival (docs/_archive/)
+- ✅ Change tracking
+
+## Examples
+
+```bash
+# Quick start
+/mpm-init                      # Auto-detect mode
+
+# Quick update (lightweight)
+/mpm-init update               # 30-day activity report
+
+# Resume work
+/mpm-init context --days 14    # Analyze last 2 weeks
+/mpm-init resume               # Show latest session from logs
+/mpm-init catchup              # Quick commit history
+
+# Full configuration
+/mpm-init --project-type web --framework react --comprehensive
+```
+
+## Implementation Notes
+
+**Delegation patterns:**
+- **Project init/update:** → Agentic Coder Optimizer agent
+- **context:** → PM → Research agent (structured analysis)
+- **catchup:** → Direct CLI (git log wrapper)
+- **resume:** → PM (reads logs, no delegation)
+
+**Token budgets:**
+- context analysis: 10-30s processing time
+- resume display: ~10-20k tokens
+- catchup: instant, minimal tokens
+
+See docs/commands/init.md for comprehensive documentation.

claude_mpm/skills/bundled/pm/mpm-monitor/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: mpm-monitor
+description: Control monitoring server and dashboard
+user-invocable: true
+version: "1.0.0"
+category: mpm-command
+tags: [mpm-command, system, pm-optional]
+---
+
+# /mpm-monitor
+
+Manage Socket.IO monitoring server for real-time dashboard.
+
+## Usage
+```
+/mpm-monitor [start|stop|restart|status|port] [options]
+```
+
+**Subcommands:**
+- `start`: Start server (auto-selects port 8765-8785)
+- `stop`: Stop running server
+- `status`: Show server status
+- `port <PORT>`: Start on specific port
+
+**Key Options:**
+- `--port PORT`: Specific port
+- `--force`: Force kill to reclaim port
+- `--foreground`: Run in foreground (default: background)
+
+Dashboard: http://localhost:8766
+
+See docs/commands/monitor.md for details.

claude_mpm/skills/bundled/pm/mpm-organize/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: mpm-organize
+description: Organize project files with intelligent consolidation
+user-invocable: true
+version: "1.0.0"
+category: mpm-command
+tags: [mpm-command, system, pm-optional]
+---
+
+# /mpm-organize
+
+Organize ALL project files with intelligent detection, consolidation, and pruning.
+
+## Usage
+```
+/mpm-organize [--dry-run] [--force] [options]
+```
+
+**Delegates to Project Organizer agent** for comprehensive file organization.
+
+## Scope
+
+**Default:** Organizes ALL project files
+- Documentation (.md, .rst, .txt)
+- Source code (proper module structure)
+- Tests (organized test suites)
+- Scripts (scripts/ directory)
+- Configuration (appropriate locations)
+
+**Protected files (never moved):** README.md, package.json, pyproject.toml, Makefile, .gitignore, etc.
+
+## Key Options
+
+**Safety:**
+- `--dry-run`: Preview without changes (recommended first run)
+- `--force`: Proceed with uncommitted changes
+- `--no-backup`: Skip backup (not recommended)
+
+**Scope:**
+- `--docs-only`: Only documentation (legacy behavior)
+- `--code-only` / `--tests-only` / `--scripts-only`: Specific file types
+
+**Operations:**
+- `--consolidate-only`: Merge duplicates only
+- `--prune-only`: Remove stale files only
+- `--no-prune`: Keep all files (no deletions)
+
+## What It Does
+
+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
+
+## Standard Structure
+
+```
+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)
+```
+
+## Examples
+
+```bash
+# Preview changes (recommended first)
+/mpm-organize --dry-run
+
+# Organize everything with backup
+/mpm-organize
+
+# Documentation only
+/mpm-organize --docs-only --dry-run
+
+# Consolidate without pruning
+/mpm-organize --consolidate-only --no-prune
+
+# Save report
+/mpm-organize --report /tmp/organize-report.md
+```
+
+## Expected Output
+
+```
+🔍 Analyzing project structure...
+✓ Detected PROJECT_ORGANIZATION.md - using project standards
+✓ Found 23 documentation files, 15 test files, 8 scripts
+
+📁 Proposed Changes:
+
+  Consolidate:
+    → Merge README_OLD.md + README_BACKUP.md → docs/user/README.md
+
+  Organize:
+    docs/research/ ← spike-oauth.md (from root)
+    tests/unit/ ← test_auth.py (from root)
+    scripts/ ← deploy.sh (from root)
+
+  Prune:
+    ✂ Remove TODO_2023.md (stale 18 months)
+
+📊 Summary: 8 to move, 2 to merge, 3 to prune
+```
+
+## Safety Features
+
+- 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)
+
+See docs/commands/organize.md for full documentation.

claude_mpm/skills/bundled/pm/mpm-postmortem/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: mpm-postmortem
+description: Analyze session errors and suggest improvements
+user-invocable: true
+version: "1.0.0"
+category: mpm-command
+tags: [mpm-command, analysis, pm-recommended]
+---
+
+# /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/skills/bundled/pm/mpm-session-management/SKILL.md

@@ -0,0 +1,312 @@
+# PM Session Management
+
+**Type**: Framework
+**Applies To**: Project Manager Agent
+**Load Priority**: On-demand (context limit or session resume)
+
+## Purpose
+
+This skill provides session pause/resume capabilities for the PM when context limits are approaching or when resuming from a previous session. These protocols are only needed when hitting token limits or starting a session with existing pause state.
+
+## When This Skill Is Loaded
+
+- Context usage reaches 70%+ thresholds
+- Session starts with `.claude-mpm/sessions/ACTIVE-PAUSE.jsonl`
+- Session starts with `.claude-mpm/sessions/LATEST-SESSION.txt`
+- User runs `/mpm-session-resume`
+
+## Auto-Pause System
+
+The MPM framework automatically tracks context usage and pauses sessions when approaching limits:
+
+### Threshold Levels
+
+| Level | Usage | Behavior |
+|-------|-------|----------|
+| Caution | 70% | Warning displayed |
+| Warning | 85% | Stronger warning |
+| **Auto-Pause** | **90%** | **Session pause activated, actions recorded** |
+| Critical | 95% | Session nearly exhausted |
+
+### Auto-Pause Behavior (at 90%)
+
+When context usage reaches 90%:
+
+1. Creates `.claude-mpm/sessions/ACTIVE-PAUSE.jsonl`
+2. Records all subsequent actions (tool calls, responses) incrementally
+3. Displays warning to user about context limits
+4. On session end, finalizes to full session snapshot
+
+The incremental recording ensures all work is captured even if the session hits hard limits.
+
+## Session Resume Protocol
+
+### At Session Start, PM Checks For
+
+**1. Active Incremental Pause**: `.claude-mpm/sessions/ACTIVE-PAUSE.jsonl`
+
+If found:
+- Display warning with action count and context percentage
+- Options:
+  - **Continue**: Resume work from pause state
+  - **Finalize**: Run `/mpm-init pause --finalize` to create snapshot
+  - **Discard**: Start fresh (previous work still in git)
+
+**Example Response**:
+```
+⚠️ Active session pause detected
+
+Actions recorded: 47
+Context usage: ~92%
+
+Options:
+1. Continue working (actions will be recorded)
+2. Finalize pause: /mpm-init pause --finalize
+3. Discard pause: Delete .claude-mpm/sessions/ACTIVE-PAUSE.jsonl
+
+Would you like to continue from the paused session?
+```
+
+**2. Finalized Pause**: `.claude-mpm/sessions/LATEST-SESSION.txt`
+
+If found:
+- Display resume context with accomplishments and next steps
+- Load context from the session snapshot
+- Continue where previous session left off
+
+**Example Response**:
+```
+📋 Resuming from previous session
+
+Last session accomplished:
+- ✅ Implemented OAuth2 authentication (Engineer)
+- ✅ Deployed to staging (Vercel-ops)
+- ⏸️ QA verification in progress
+
+Next steps:
+- Complete QA verification of auth flow
+- Update documentation
+- Deploy to production
+
+Continue with QA verification?
+```
+
+## PM Response to Context Warnings
+
+When PM sees context warnings (70%+), follow this protocol:
+
+### Immediate Actions
+
+1. **Wrap up current work phase**
+   - Complete the current delegation cycle
+   - Don't start new major tasks
+
+2. **Document all in-progress tasks**
+   - Ensure all todos are updated with current status
+   - Mark BLOCKED todos with specific blockers
+   - Add context to in_progress todos
+
+3. **Delegate remaining work with clear handoff**
+   - Provide detailed context to agents
+   - Include acceptance criteria
+   - Reference relevant files and commits
+
+4. **Create summary**
+   - What was completed
+   - What remains to be done
+   - Any blockers or important context
+
+### Example Wrap-Up Sequence
+
+```
+Context at 85% - wrapping up current phase
+
+Completed:
+- ✅ OAuth2 implementation (commit abc123)
+- ✅ Staging deployment verified
+
+In Progress:
+- 🔄 QA verification (api-qa testing login flow)
+
+Remaining:
+- Documentation update (auth flow docs)
+- Production deployment
+
+Creating session snapshot for clean resume...
+```
+
+## Git-Based Session Continuity
+
+Git history provides additional session context that complements session snapshots:
+
+### Useful Git Commands
+
+```bash
+# Recent commits (what was delivered)
+git log --oneline -10
+
+# Uncommitted changes (work in progress)
+git status
+
+# Recent work (last 24 hours)
+git log --since="24 hours ago" --pretty=format:"%h %s"
+
+# Files changed recently
+git log --name-status --since="24 hours ago"
+```
+
+### Integration with Session Resume
+
+When resuming a session, PM should:
+
+1. Load session snapshot (if available)
+2. Check git log for additional context
+3. Verify git status for uncommitted work
+4. Reconcile session state with git state
+
+**Example**:
+```
+Resuming session...
+
+Session snapshot: Work on OAuth2 authentication
+Git log: Last commit "feat: add OAuth2 provider" (2 hours ago)
+Git status: Uncommitted changes in src/auth/middleware.js
+
+Context: Implementation complete, middleware updates in progress
+```
+
+## Session Files Structure
+
+```
+.claude-mpm/sessions/
+├── ACTIVE-PAUSE.jsonl      # Incremental actions during auto-pause
+├── LATEST-SESSION.txt      # Pointer to most recent finalized session
+├── session-*.json          # Machine-readable session snapshots
+├── session-*.yaml          # YAML format
+└── session-*.md            # Human-readable markdown
+```
+
+### File Purposes
+
+- **ACTIVE-PAUSE.jsonl**: Real-time action recording during auto-pause
+- **LATEST-SESSION.txt**: Points to most recent finalized session file
+- **session-*.json**: Complete session state (todos, context, agents used)
+- **session-*.yaml**: Same as JSON but YAML format
+- **session-*.md**: Human-readable summary for quick review
+
+## Best Practices
+
+### When Context Limits Approach
+
+1. **Don't panic**: Auto-pause system will capture your work
+2. **Finish current phase**: Complete the delegation in progress
+3. **Update todos**: Ensure all todos reflect current state
+4. **Create handoff context**: Next PM session needs to understand state
+
+### When Resuming Sessions
+
+1. **Review session snapshot**: Understand what was accomplished
+2. **Check git history**: Verify actual state matches snapshot
+3. **Validate uncommitted work**: Any WIP that wasn't tracked?
+4. **Continue from clear state**: Don't duplicate completed work
+
+### Avoiding Session Bloat
+
+- Keep delegations focused and atomic
+- Don't load unnecessary context (use skills on-demand)
+- Complete and close todos regularly
+- Commit work incrementally (easier to resume)
+
+## Common Scenarios
+
+### Scenario 1: Auto-Pause During Implementation
+
+```
+Context: 90% during Engineer delegation
+
+PM Actions:
+1. Wait for Engineer to complete current file
+2. Track files immediately (git add + commit)
+3. Update todo with completion status
+4. Create summary of implementation state
+5. Session pauses, all recorded in ACTIVE-PAUSE.jsonl
+
+Next Session:
+1. PM detects ACTIVE-PAUSE.jsonl
+2. Continues from implementation state
+3. Proceeds to QA verification phase
+```
+
+### Scenario 2: Resume After Finalized Pause
+
+```
+Context: User returns to continue work
+
+PM Actions:
+1. Detects LATEST-SESSION.txt
+2. Loads session-{timestamp}.md for human summary
+3. Loads session-{timestamp}.json for full state
+4. Checks git log for verification
+5. Presents summary to user
+6. Continues workflow from next phase
+```
+
+### Scenario 3: Context Warning During Research
+
+```
+Context: 75% during Research agent investigation
+
+PM Actions:
+1. Allow Research to complete current investigation
+2. Don't start new research tasks
+3. Collect Research findings
+4. Document findings in session state
+5. Prepare for potential pause at 90%
+
+If 90% reached:
+1. Research findings already documented
+2. Implementation can start in next session
+3. Clear handoff context available
+```
+
+## Integration with PM Workflow
+
+Session management integrates with standard PM workflow:
+
+```
+User Request
+    ↓
+[Check for session resume state]
+    ↓
+Research (if needed)
+    ↓
+[Monitor context usage]
+    ↓
+Implementation
+    ↓
+[Auto-pause if 90% reached]
+    ↓
+Deployment
+    ↓
+QA
+    ↓
+Documentation
+    ↓
+[Final session snapshot if paused]
+    ↓
+Report Results
+```
+
+## Trigger Keywords
+
+- "context", "pause", "resume", "session"
+- "token", "limit", "usage"
+- "continue", "previous session"
+- Auto-loaded at 70%+ context usage
+- Auto-loaded when session files exist
+
+## Related Skills
+
+- `mpm-git-file-tracking` - File tracking during pause/resume
+- `mpm-verification-protocols` - Verification state during pause
+- `mpm-delegation-patterns` - Resuming delegations mid-workflow

claude_mpm/skills/bundled/pm/mpm-session-resume/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: mpm-session-resume
+description: Load context from paused session
+user-invocable: true
+version: "1.0.0"
+category: mpm-command
+tags: [mpm-command, session, pm-recommended]
+---
+
+# /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-*.md`
+
+**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/skills/bundled/pm/mpm-status/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: mpm-status
+description: Display Claude MPM system status
+user-invocable: true
+version: "1.0.0"
+category: mpm-command
+tags: [mpm-command, system, pm-required, diagnostics]
+---
+
+# /mpm-status
+
+Show MPM system status. Delegates to PM agent.
+
+## Usage
+
+```
+/mpm-status
+```
+
+## What It Shows
+
+Displays comprehensive system information:
+- **Version**: MPM version and installation details
+- **Services**: WebSocket server status, monitoring dashboard
+- **Agents**: Available agents and their versions
+- **Memory**: Memory system statistics and health
+- **Configuration**: Current MPM configuration settings
+- **Project Info**: Project-specific context and setup
+
+## When to Use
+
+- Check if MPM is properly installed and configured
+- Verify agent availability before delegation
+- Debug system issues or unexpected behavior
+- Get quick overview of system health
+
+See docs/commands/status.md for details.

claude_mpm/skills/bundled/pm/{pm-teaching-mode → mpm-teaching-mode}/SKILL.md

@@ -43,7 +43,7 @@ git status  # Should NOT show .env
 
 **Setup Steps**:
 1. Create `.env` in project root
-2. Add your secrets: `API_KEY=abc123...`
+2. Add your secrets: `API_KEY=abc123...` # pragma: allowlist secret
 3. Add `.env` to `.gitignore`
 4. Load in code: `process.env.API_KEY` (Node) or `os.getenv('API_KEY')` (Python)
 
@@ -513,7 +513,7 @@ Documentation created:
 # Register new user
 curl -X POST http://localhost:3000/api/users/register \
   -H "Content-Type: application/json" \
-  -d '{"email":"user@example.com","password":"SecurePass123"}'
+  -d '{"email":"user@example.com","password":"SecurePass123"}' # pragma: allowlist secret
 
 # Success response:
 {"success":true,"userId":"123","message":"User registered successfully"}