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

claude_mpm/skills/bundled/pm/pm-bug-reporting/pm-bug-reporting.md

@@ -0,0 +1,248 @@
+---
+name: pm-bug-reporting
+version: "1.0.0"
+description: Bug reporting protocol for PM and agents to file GitHub issues
+when_to_use: Framework bugs, agent errors, skill content errors detected
+category: pm-workflow
+tags: [bug-reporting, github, issues, pm-required]
+---
+
+# PM Bug Reporting Protocol
+
+## When to Report Bugs
+
+Report bugs when you encounter:
+- **PM instruction errors** or missing guidance
+- **Agent malfunction** or incorrect behavior
+- **Skill content errors** or outdated information
+- **Framework crashes** or unexpected behavior
+- **Missing or incorrect documentation**
+- **Configuration errors** or invalid defaults
+
+## GitHub Repositories
+
+Route bugs to the correct repository:
+
+| Bug Type | Repository | Owner/Repo |
+|----------|------------|------------|
+| Core MPM (CLI, startup, config, orchestration) | claude-mpm | bobmatnyc/claude-mpm |
+| Agent bugs (wrong behavior, errors, missing capabilities) | claude-mpm-agents | bobmatnyc/claude-mpm-agents |
+| Skill bugs (wrong info, outdated, missing content) | claude-mpm-skills | bobmatnyc/claude-mpm-skills |
+
+## Bug Report Template
+
+When creating an issue, include:
+
+### Title
+Brief, descriptive title (50 chars max)
+- ✅ "PM delegates to non-existent agent"
+- ✅ "Research skill missing web search examples"
+- ❌ "Bug in system"
+- ❌ "Fix this"
+
+### Labels
+Always include:
+- `bug` (required)
+- `agent-reported` (required)
+- Additional context labels:
+  - `high-priority` - Critical functionality broken
+  - `documentation` - Documentation error
+  - `agent-error` - Agent-specific issue
+  - `skill-error` - Skill content issue
+
+### Body Structure
+```markdown
+## What Happened
+[Clear description of the bug]
+
+## Expected Behavior
+[What should have happened]
+
+## Steps to Reproduce
+1. [First step]
+2. [Second step]
+3. [Third step]
+
+## Context
+- Agent: [agent name if applicable]
+- Skill: [skill name if applicable]
+- Error Message: [full error if available]
+- Version: [MPM version if known]
+
+## Impact
+[How this affects users/workflow]
+```
+
+## Using gh CLI
+
+### Prerequisites Check
+```bash
+gh auth status
+```
+
+If not authenticated:
+```bash
+gh auth login
+```
+
+### Creating Issues
+
+**Delegate to ticketing agent** with:
+```
+Task:
+  agent: ticketing
+  task: Create GitHub issue for [bug type]
+  context: |
+    Repository: bobmatnyc/claude-mpm[-agents|-skills]
+    Title: [brief title]
+    Labels: bug, agent-reported
+    Body: |
+      ## What Happened
+      [description]
+
+      ## Expected Behavior
+      [expected]
+
+      ## Steps to Reproduce
+      1. [step 1]
+      2. [step 2]
+
+      ## Context
+      - Agent: [agent name]
+      - Error: [error message]
+
+      ## Impact
+      [impact description]
+```
+
+## Examples
+
+### Core MPM Bug
+```
+Task:
+  agent: ticketing
+  task: Create GitHub issue for core MPM bug
+  context: |
+    Repository: bobmatnyc/claude-mpm
+    Title: PM fails to load configuration on startup
+    Labels: bug, agent-reported, high-priority
+    Body: |
+      ## What Happened
+      PM fails to initialize when configuration.yaml contains invalid syntax.
+      No clear error message shown to user.
+
+      ## Expected Behavior
+      PM should display clear YAML syntax error with line number and fix suggestion.
+
+      ## Steps to Reproduce
+      1. Add invalid YAML to .claude-mpm/configuration.yaml
+      2. Run `mpm`
+      3. Observe generic error without details
+
+      ## Context
+      - Component: Configuration loader
+      - Error: "Failed to load configuration"
+      - Version: 5.4.x
+
+      ## Impact
+      Users cannot diagnose configuration errors, requiring manual YAML validation.
+```
+
+### Agent Bug
+```
+Task:
+  agent: ticketing
+  task: Create GitHub issue for agent bug
+  context: |
+    Repository: bobmatnyc/claude-mpm-agents
+    Title: Research agent fails to search with special characters
+    Labels: bug, agent-reported, agent-error
+    Body: |
+      ## What Happened
+      Research agent throws error when search query contains quotes or special chars.
+
+      ## Expected Behavior
+      Search queries should be properly escaped and executed.
+
+      ## Steps to Reproduce
+      1. Delegate to research: "Search for 'React hooks'"
+      2. Research agent attempts search
+      3. Error: "Invalid search query"
+
+      ## Context
+      - Agent: research
+      - Error: grep command fails with unescaped quotes
+
+      ## Impact
+      Cannot search for quoted phrases or technical terms with special characters.
+```
+
+### Skill Bug
+```
+Task:
+  agent: ticketing
+  task: Create GitHub issue for skill content error
+  context: |
+    Repository: bobmatnyc/claude-mpm-skills
+    Title: Git workflow skill contains outdated branch strategy
+    Labels: bug, agent-reported, documentation, skill-error
+    Body: |
+      ## What Happened
+      Skill recommends `git flow` branching model, which project no longer uses.
+      Current standard is trunk-based development.
+
+      ## Expected Behavior
+      Skill should document current trunk-based workflow.
+
+      ## Context
+      - Skill: git-workflow.md
+      - Section: "Branching Strategy"
+      - Line: 45-60
+
+      ## Impact
+      Agents follow outdated branching model, creating workflow friction.
+```
+
+## Escalation Path
+
+When ticketing agent is unavailable or gh CLI fails:
+
+1. **Log locally** for manual reporting:
+   ```
+   echo "[BUG] $(date): [description]" >> .claude-mpm/logs/bugs.log
+   ```
+
+2. **Report to PM** for alternative action:
+   ```
+   PM should create ticket in primary ticketing system (Linear/JIRA)
+   with note to create GitHub issue once available
+   ```
+
+3. **User notification**:
+   ```
+   "Bug detected: [description]. Logged for manual GitHub issue creation."
+   ```
+
+## Success Criteria
+
+Bug reporting successful when:
+- ✅ Issue created in correct repository
+- ✅ All required labels applied (`bug`, `agent-reported`)
+- ✅ Body follows template structure
+- ✅ Title is clear and concise
+- ✅ Context includes agent/skill name if applicable
+- ✅ Issue URL returned for tracking
+
+## PM Enforcement
+
+PM MUST:
+- Detect bugs during agent interactions
+- Delegate bug reporting to ticketing agent
+- NOT attempt to create GitHub issues directly
+- Follow escalation path if ticketing unavailable
+- Log all bug reports for audit trail
+
+## Related Skills
+- [pm-ticketing-integration.md](pm-ticketing-integration.md) - Ticket delegation patterns
+- [pm-delegation-patterns.md](pm-delegation-patterns.md) - General delegation guidance
+- [ticketing-examples.md](ticketing-examples.md) - Ticketing delegation examples

claude_mpm/skills/bundled/pm/pm-delegation-patterns/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: pm-delegation-patterns
+version: "1.0.0"
+description: Common delegation patterns for PM agent
+when_to_use: delegation questions, agent selection, workflow patterns
+category: pm-reference
+tags: [delegation, agents, patterns, pm-required]
+---
+
+# Common Delegation Patterns
+
+## Full Stack Feature
+
+**Workflow**: Research → Analyzer → react-engineer + Engineer → Ops (deploy) → Ops (VERIFY) → api-qa + web-qa → Docs
+
+**When**: Complete feature requiring frontend, backend, and deployment
+
+**Example**:
+```
+User: "Add user dashboard with analytics"
+PM delegates:
+  1. Research: Investigate dashboard frameworks and analytics libraries
+  2. Code Analyzer: Review solution approach
+  3. react-engineer: Build dashboard UI components
+  4. Engineer: Implement analytics API endpoints
+  5. Ops: Deploy to staging
+  6. Ops: Verify deployment (health checks, logs)
+  7. api-qa: Test API endpoints
+  8. web-qa: Test dashboard UI
+  9. Documentation: Update API docs and user guide
+```
+
+## API Development
+
+**Workflow**: Research → Analyzer → Engineer → Deploy (if needed) → Ops (VERIFY) → web-qa (fetch tests) → Docs
+
+**When**: Backend API implementation without frontend
+
+**Example**:
+```
+User: "Create REST API for user management"
+PM delegates:
+  1. Research: API design patterns, authentication
+  2. Code Analyzer: Review API design
+  3. Engineer: Implement API endpoints
+  4. Ops: Deploy API to staging (if needed)
+  5. Ops: Verify deployment
+  6. web-qa: Run fetch tests on endpoints
+  7. Documentation: Generate API documentation
+```
+
+## Web UI
+
+**Workflow**: Research → Analyzer → web-ui/react-engineer → Ops (deploy) → Ops (VERIFY with Playwright) → web-qa → Docs
+
+**When**: Frontend-only changes
+
+**Example**:
+```
+User: "Redesign landing page"
+PM delegates:
+  1. Research: UI/UX best practices, component libraries
+  2. Code Analyzer: Review design approach
+  3. react-engineer: Implement new landing page
+  4. Ops: Deploy to staging
+  5. Ops: Verify deployment with Playwright
+  6. web-qa: Visual regression testing
+  7. Documentation: Update component documentation
+```
+
+## Local Development
+
+**Workflow**: Research → Analyzer → Engineer → **local-ops** (PM2/Docker) → **local-ops** (VERIFY logs+fetch) → QA → Docs
+
+**When**: Working with localhost, PM2, Docker, or local processes
+
+**Example**:
+```
+User: "Set up local development server"
+PM delegates:
+  1. Research: Local development setup best practices
+  2. Code Analyzer: Review setup approach
+  3. Engineer: Configure development environment
+  4. local-ops: Start server with PM2/Docker
+  5. local-ops: Verify server running (lsof, curl, logs)
+  6. QA: Test local endpoints
+  7. Documentation: Update setup guide
+```
+
+## Bug Fix
+
+**Workflow**: Research → Analyzer → Engineer → Deploy → Ops (VERIFY) → web-qa (regression) → version-control
+
+**When**: Fixing reported bugs
+
+**Example**:
+```
+User: "Fix login error on Safari"
+PM delegates:
+  1. Research: Investigate Safari-specific issues
+  2. Code Analyzer: Review fix approach
+  3. Engineer: Implement fix
+  4. Ops: Deploy fix to staging
+  5. Ops: Verify deployment
+  6. web-qa: Run regression tests, verify Safari fix
+  7. version-control: Create PR with fix
+```
+
+## Vercel Site
+
+**Workflow**: Research → Analyzer → Engineer → vercel-ops (deploy) → vercel-ops (VERIFY) → web-qa → Docs
+
+**When**: Vercel-hosted applications
+
+**Example**:
+```
+User: "Deploy blog to Vercel"
+PM delegates:
+  1. Research: Vercel deployment best practices
+  2. Code Analyzer: Review deployment config
+  3. Engineer: Configure Vercel settings
+  4. vercel-ops: Deploy to Vercel
+  5. vercel-ops: Verify deployment (health check)
+  6. web-qa: Test deployed site
+  7. Documentation: Update deployment guide
+```
+
+## Railway App
+
+**Workflow**: Research → Analyzer → Engineer → railway-ops (deploy) → railway-ops (VERIFY) → api-qa → Docs
+
+**When**: Railway-hosted applications
+
+**Example**:
+```
+User: "Deploy API to Railway"
+PM delegates:
+  1. Research: Railway deployment patterns
+  2. Code Analyzer: Review Railway config
+  3. Engineer: Configure Railway settings
+  4. railway-ops: Deploy to Railway
+  5. railway-ops: Verify deployment
+  6. api-qa: Test API endpoints
+  7. Documentation: Update deployment docs
+```
+
+## Agent Selection by Trigger Keywords
+
+| Keywords | Agent | Use Case |
+|----------|-------|----------|
+| localhost, PM2, docker-compose, port, process | **local-ops** | Local development |
+| vercel, edge function, serverless | **vercel-ops** | Vercel platform |
+| railway, nixpacks | **railway-ops** | Railway platform |
+| gcp, google cloud, IAM, OAuth consent | **gcp-ops** | Google Cloud |
+| clerk, auth middleware, OAuth provider | **clerk-ops** | Clerk authentication |
+| browser, screenshot, click, navigate, DOM | **web-qa** | Browser testing |
+| ticket, issue, PROJ-123, #123 | **ticketing** | Ticket operations |
+| skill, stack, framework | **mpm-skills-manager** | Skill management |
+
+## Delegation Best Practices
+
+1. **Provide Context**: Include relevant background for agent
+2. **Clear Acceptance Criteria**: Define completion criteria
+3. **Wait for Completion**: Don't interrupt agent work
+4. **Collect Evidence**: Get specific artifacts from agents
+5. **Immediate File Tracking**: Track files right after agent creates them
+6. **Chain Verification**: QA verification after implementation

claude_mpm/skills/bundled/pm/pm-git-file-tracking/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: pm-git-file-tracking
+version: "1.0.0"
+description: Protocol for tracking files immediately after agent creation
+when_to_use: after agent creates files, before marking todo complete, git operations
+category: pm-workflow
+tags: [git, file-tracking, workflow, pm-required]
+---
+
+# Git File Tracking Protocol
+
+**Critical Principle**: Track files IMMEDIATELY after an agent creates them, not at session end.
+
+## File Tracking Decision Flow
+
+```
+Agent completes work and returns to PM
+    ↓
+Did agent create files? → NO → Mark todo complete, continue
+    ↓ YES
+MANDATORY FILE TRACKING (BLOCKING)
+    ↓
+Step 1: Run `git status` to see new files
+Step 2: Check decision matrix (deliverable vs temp/ignored)
+Step 3: Run `git add <files>` for all deliverables
+Step 4: Run `git commit -m "..."` with proper context
+Step 5: Verify tracking with `git status`
+    ↓
+ONLY NOW: Mark todo as completed
+```
+
+**BLOCKING REQUIREMENT**: PM cannot mark todo complete until files are tracked.
+
+## Decision Matrix: When to Track Files
+
+| File Type | Track? | Reason |
+|-----------|--------|--------|
+| New source files (`.py`, `.js`, etc.) | ✅ YES | Production code must be versioned |
+| New config files (`.json`, `.yaml`, etc.) | ✅ YES | Configuration changes must be tracked |
+| New documentation (`.md` in `/docs/`) | ✅ YES | Documentation is part of deliverables |
+| Documentation in project root (`.md`) | ❌ NO | Only core docs allowed (README, CHANGELOG, CONTRIBUTING) |
+| New test files (`test_*.py`, `*.test.js`) | ✅ YES | Tests are critical artifacts |
+| New scripts (`.sh`, `.py` in `/scripts/`) | ✅ YES | Automation must be versioned |
+| Files in `/tmp/` directory | ❌ NO | Temporary by design (gitignored) |
+| Files in `.gitignore` | ❌ NO | Intentionally excluded |
+| Build artifacts (`dist/`, `build/`) | ❌ NO | Generated, not source |
+| Virtual environments (`venv/`, `node_modules/`) | ❌ NO | Dependencies, not source |
+
+## Commit Message Format
+
+```bash
+git commit -m "feat: add {description}
+
+- Created {file_type} for {purpose}
+- Includes {key_features}
+- Part of {initiative}
+
+🤖 Generated with [Claude MPM](https://github.com/bobmatnyc/claude-mpm)
+
+Co-Authored-By: Claude <noreply@anthropic.com>"
+```
+
+## Before Ending Any Session
+
+**Final verification checklist**:
+
+```bash
+# 1. Check for untracked files
+git status
+
+# 2. If any deliverable files found (should be rare):
+git add <files>
+git commit -m "feat: final session deliverables..."
+
+# 3. Verify tracking complete
+git status  # Should show "nothing to commit, working tree clean"
+```
+
+**Ideal State**: `git status` shows NO untracked deliverable files because PM tracked them immediately after each agent.
+
+## Example Workflow
+
+```bash
+# After Engineer creates new OAuth files
+git status
+# Shows: src/auth/oauth2.js (untracked)
+#        src/routes/auth.js (untracked)
+
+git add src/auth/oauth2.js src/routes/auth.js
+
+git commit -m "feat: add OAuth2 authentication
+
+- Created OAuth2 authentication module
+- Added authentication routes
+- Part of user login feature
+
+🤖 Generated with [Claude MPM](https://github.com/bobmatnyc/claude-mpm)
+
+Co-Authored-By: Claude <noreply@anthropic.com>"
+
+# Verify tracking complete
+git status  # Should show clean working tree
+```
+
+## Integration with Todo Workflow
+
+**BLOCKING SEQUENCE**:
+1. Agent completes task and returns to PM
+2. PM checks if files were created
+3. If YES → Run file tracking protocol (cannot proceed until complete)
+4. Only after tracking verified → Mark todo as completed
+
+This ensures no deliverables are lost between agent completion and session end.

claude_mpm/skills/bundled/pm/pm-pr-workflow/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: pm-pr-workflow
+version: "1.0.0"
+description: Branch protection and PR creation workflow
+when_to_use: PR creation, branch operations, git push to main
+category: pm-workflow
+tags: [git, pr, branch-protection, pm-required]
+---
+
+# PR Workflow and Branch Protection
+
+## Branch Protection Enforcement
+
+**CRITICAL**: PM must enforce branch protection for main branch.
+
+### Detection (run before any main branch operation)
+
+```bash
+git config user.email
+```
+
+### Routing Rules
+
+- User is `bobmatnyc@users.noreply.github.com` → Can push directly to main (if explicitly requested)
+- Any other user → MUST use feature branch + PR workflow
+
+### User Request Translation
+
+When non-privileged users request main branch operations:
+
+| User Request | PM Action |
+|--------------|-----------|
+| "commit to main" | "Creating feature branch workflow instead" |
+| "push to main" | "Branch protection requires PR workflow" |
+| "merge to main" | "Creating PR for review" |
+
+**Error Prevention**: PM proactively guides non-privileged users to correct workflow (don't wait for git errors).
+
+## PR Workflow Delegation
+
+**Default**: Main-based PRs (unless user explicitly requests stacked)
+
+### When User Requests PRs
+
+- Single ticket → One PR (no question needed)
+- Independent features → Main-based (no question needed)
+- User says "stacked" or "dependent" → Stacked PRs (no question needed)
+
+### Recommend Main-Based When
+
+- User doesn't specify preference
+- Independent features or bug fixes
+- Multiple agents working in parallel
+- Simple enhancements
+
+### Recommend Stacked PRs When
+
+- User explicitly requests "stacked" or "dependent" PRs
+- Large feature with clear phase dependencies
+- User is comfortable with rebase workflows
+
+Always delegate to version-control agent with strategy parameters.
+
+## PR Creation Workflow
+
+When creating PRs, delegate to version-control agent with:
+
+```
+Task:
+  agent: "version-control"
+  task: "Create PR for {feature}"
+  context: |
+    Work completed: {summary}
+    Files changed: {file_list}
+    Tests: {test_status}
+    QA verification: {qa_evidence}
+  acceptance_criteria:
+    - Create feature branch from main
+    - Push all commits to feature branch
+    - Create PR with proper description
+    - Link ticket if applicable
+    - Request reviews if needed
+```
+
+## Common Patterns
+
+### Single Feature PR
+```bash
+# Feature branch → PR → Main
+feature/user-auth → PR #123 → main
+```
+
+### Stacked PRs (when requested)
+```bash
+# Stacked feature development
+feature/auth-base → PR #123 → main
+feature/oauth (based on auth-base) → PR #124 → feature/auth-base
+feature/session (based on oauth) → PR #125 → feature/oauth
+```
+
+### Bug Fix PR
+```bash
+# Hotfix branch → PR → Main
+fix/login-error → PR #126 → main
+```
+
+## Branch Protection Checklist
+
+Before any main branch operation:
+- [ ] Check git user email
+- [ ] Verify user has main branch access
+- [ ] If not privileged user, route to feature branch workflow
+- [ ] Create clear user messaging about branch protection
+
+## Integration with Git File Tracking
+
+All file tracking should happen on feature branches before PR creation:
+
+1. Agent creates files
+2. PM tracks files immediately (git add + commit)
+3. PM delegates PR creation to version-control
+4. version-control pushes branch and creates PR
+
+This ensures all work is tracked before entering PR workflow.