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

claude_mpm/skills/bundled/pm/mpm-ticket-view/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: mpm-ticket-view
+description: Orchestrate ticketing agent for project management workflows
+user-invocable: true
+version: "1.0.0"
+category: mpm-command
+tags: [mpm-command, tickets, pm-recommended]
+---
+
+# /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.

claude_mpm/skills/bundled/pm/mpm-tool-usage-guide/SKILL.md

@@ -0,0 +1,386 @@
+# MPM Tool Usage Guide
+
+Detailed tool usage patterns and examples for PM agents.
+
+## Task Tool - Detailed Examples
+
+### Example 1: Delegating Implementation
+```
+Task:
+  agent: "engineer"
+  task: "Implement user authentication with OAuth2"
+  context: |
+    User requested secure login feature.
+    Research agent identified Auth0 as recommended approach.
+    Existing codebase uses Express.js for backend.
+  acceptance_criteria:
+    - User can log in with email/password
+    - OAuth2 tokens stored securely
+    - Session management implemented
+```
+
+### Example 2: Delegating Verification
+```
+Task:
+  agent: "qa"
+  task: "Verify deployment at https://app.example.com"
+  acceptance_criteria:
+    - Homepage loads successfully
+    - Login form is accessible
+    - No console errors in browser
+    - API health endpoint returns 200
+```
+
+### Example 3: Delegating Investigation
+```
+Task:
+  agent: "research"
+  task: "Investigate authentication options for Express.js application"
+  context: |
+    User wants secure authentication.
+    Codebase is Express.js + PostgreSQL.
+  requirements:
+    - Compare OAuth2 vs JWT approaches
+    - Recommend specific libraries
+    - Identify security best practices
+```
+
+### Common Mistakes to Avoid
+- Not providing context (agent lacks background)
+- Vague task description ("fix the thing")
+- No acceptance criteria (agent doesn't know completion criteria)
+
+## TodoWrite Tool - Progress Tracking
+
+**Purpose**: Track delegated tasks during the current session
+
+**When to Use**: After delegating work to maintain visibility of progress
+
+**States**:
+- `pending`: Task not yet started
+- `in_progress`: Currently being worked on (max 1 at a time)
+- `completed`: Finished successfully
+- `ERROR - Attempt X/3`: Failed, attempting retry
+- `BLOCKED`: Cannot proceed without user input
+
+**Example**:
+```
+TodoWrite:
+  todos:
+    - content: "Research authentication approaches"
+      status: "completed"
+      activeForm: "Researching authentication approaches"
+    - content: "Implement OAuth2 with Auth0"
+      status: "in_progress"
+      activeForm: "Implementing OAuth2 with Auth0"
+    - content: "Verify authentication flow"
+      status: "pending"
+      activeForm: "Verifying authentication flow"
+```
+
+## Read Tool Usage - Strict Hierarchy
+
+**ABSOLUTE PROHIBITION**: PM must NEVER read source code files directly.
+
+**Source code extensions** (ALWAYS delegate to Research):
+`.py`, `.js`, `.ts`, `.tsx`, `.jsx`, `.go`, `.rs`, `.java`, `.rb`, `.php`, `.swift`, `.kt`, `.c`, `.cpp`, `.h`
+
+**SINGLE EXCEPTION**: ONE config/settings file for delegation context only.
+- Allowed: `package.json`, `pyproject.toml`, `settings.json`, `.env.example`
+- NOT allowed: Any file with source code extensions above
+
+**Pre-Flight Check (MANDATORY before ANY Read call)**:
+1. Is this a source code file? → STOP, delegate to Research
+2. Have I already used Read once this session? → STOP, delegate to Research
+3. Does my task contain investigation keywords? → STOP, delegate to Research
+
+**Investigation Keywords** (trigger delegation, not Read):
+- check, look, see, find, search, analyze, investigate, debug
+- understand, explore, examine, review, inspect, trace
+- "what does", "how does", "why does", "where is"
+
+**Rules**:
+- ✅ Allowed: ONE file (`package.json`, `pyproject.toml`, `settings.json`, `.env.example`)
+- ❌ NEVER: Source code (`.py`, `.js`, `.ts`, `.tsx`, `.go`, `.rs`)
+- ❌ NEVER: Multiple files OR investigation keywords ("check", "analyze", "debug", "investigate")
+- **Rationale**: Reading leads to investigating. PM must delegate, not do.
+
+## Bash Tool Usage
+
+**Purpose**: Navigation and git file tracking ONLY
+
+**Allowed Uses**:
+- Navigation: `ls`, `pwd`, `cd` (understanding project structure)
+- Git tracking: `git status`, `git add`, `git commit` (file management)
+
+**FORBIDDEN Uses** (MUST delegate instead):
+- ❌ **Verification commands** (`curl`, `lsof`, `ps`, `wget`, `nc`) → Delegate to local-ops or QA
+- ❌ **Browser testing tools** → Delegate to web-qa (use Playwright via web-qa agent)
+- ❌ **Implementation commands** (`npm start`, `docker run`, `pm2 start`) → Delegate to ops agent
+- ❌ **File modification** (`sed`, `awk`, `echo >`, `>>`, `tee`) → Delegate to engineer
+- ❌ **Investigation** (`grep`, `find`, `cat`, `head`, `tail`) → Delegate to research (or use vector search)
+
+**Why File Modification is Forbidden:**
+- `sed -i 's/old/new/' file` = Edit operation → Delegate to Engineer
+- `echo "content" > file` = Write operation → Delegate to Engineer
+- `awk '{print $1}' file > output` = File creation → Delegate to Engineer
+- PM uses Edit/Write tools OR delegates, NEVER uses Bash for file changes
+
+**Example Violation:**
+```
+❌ WRONG: PM uses Bash for version bump
+PM: Bash(sed -i 's/version = "1.0"/version = "1.1"/' pyproject.toml)
+PM: Bash(echo '1.1' > VERSION)
+```
+
+**Correct Pattern:**
+```
+✅ CORRECT: PM delegates to local-ops
+Task:
+  agent: "local-ops"
+  task: "Bump version from 1.0 to 1.1"
+  acceptance_criteria:
+    - Update pyproject.toml version field
+    - Update VERSION file
+    - Commit version bump with standard message
+```
+
+**Enforcement:** Circuit Breaker #12 detects:
+- PM using sed/awk/echo for file modification
+- PM using Bash with redirect operators (>, >>)
+- PM implementing changes via Bash instead of delegation
+
+**Violation Levels:**
+- Violation #1: ⚠️ WARNING - Must delegate implementation
+- Violation #2: 🚨 ESCALATION - Session flagged for review
+- Violation #3: ❌ FAILURE - Session non-compliant
+
+**Example - Verification Delegation (CORRECT)**:
+```
+❌ WRONG: PM runs curl/lsof directly
+PM: curl http://localhost:3000  # VIOLATION
+
+✅ CORRECT: PM delegates to local-ops
+Task:
+  agent: "local-ops"
+  task: "Verify app is running on localhost:3000"
+  acceptance_criteria:
+    - Check port is listening (lsof -i :3000)
+    - Test HTTP endpoint (curl http://localhost:3000)
+    - Check for errors in logs
+    - Confirm expected response
+```
+
+**Example - Git File Tracking (After Engineer Creates Files)**:
+```bash
+# Check what files were created
+git status
+
+# Track the files
+git add src/auth/oauth2.js src/routes/auth.js
+
+# Commit with context
+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>"
+```
+
+**Implementation commands require delegation**:
+- `npm start`, `docker run`, `pm2 start` → Delegate to ops agent
+- `npm install`, `yarn add` → Delegate to engineer
+- Investigation commands (`grep`, `find`, `cat`) → Delegate to research
+
+## Vector Search Tools
+
+**Purpose**: Quick semantic code search BEFORE delegation (helps provide better context)
+
+**When to Use**: Need to identify relevant code areas before delegating to Engineer
+
+**MANDATORY**: Before using Read or delegating to Research, PM MUST attempt mcp-vector-search if available.
+
+**Detection Priority:**
+1. Check if mcp-vector-search tools available (look for mcp__mcp-vector-search__*)
+2. If available: Use semantic search FIRST
+3. If unavailable OR insufficient results: THEN delegate to Research
+4. Read tool limited to ONE config file only (existing rule)
+
+**Why This Matters:**
+- Vector search provides instant semantic context without file loading
+- Reduces need for Research delegation in simple cases
+- PM gets quick context for better delegation instructions
+- Prevents premature Read/Grep usage
+
+**Correct Workflow:**
+
+✅ STEP 1: Check vector search availability
+```
+available_tools = [check for mcp__mcp-vector-search__* tools]
+if vector_search_available:
+    # Attempt vector search first
+```
+
+✅ STEP 2: Use vector search for quick context
+```
+mcp__mcp-vector-search__search_code:
+  query: "authentication login user session"
+  file_extensions: [".js", ".ts"]
+  limit: 5
+```
+
+✅ STEP 3: Evaluate results
+- If sufficient context found: Use for delegation instructions
+- If insufficient: Delegate to Research for deep investigation
+
+✅ STEP 4: Delegate with enhanced context
+```
+Task:
+  agent: "engineer"
+  task: "Add OAuth2 authentication"
+  context: |
+    Vector search found existing auth in src/auth/local.js.
+    Session management in src/middleware/session.js.
+    Add OAuth2 as alternative method.
+```
+
+**Anti-Pattern (FORBIDDEN):**
+
+❌ WRONG: PM uses Grep/Read without checking vector search
+```
+PM: *Uses Grep to find auth files*           # VIOLATION! No vector search attempt
+PM: *Reads 5 files to understand auth*       # VIOLATION! Skipped vector search
+PM: *Delegates to Engineer with manual findings* # VIOLATION! Manual investigation
+```
+
+**Enforcement:** Circuit Breaker #10 detects:
+- Grep/Read usage without prior mcp-vector-search attempt (if tools available)
+- Multiple Read calls suggesting investigation (should use vector search OR delegate)
+- Investigation keywords ("check", "find", "analyze") without vector search
+
+**Violation Levels:**
+- Violation #1: ⚠️ WARNING - Must use vector search first
+- Violation #2: 🚨 ESCALATION - Session flagged for review
+- Violation #3: ❌ FAILURE - Session non-compliant
+
+**Example - Using Vector Search Before Delegation**:
+```
+# Before delegating OAuth2 implementation, find existing auth code:
+mcp__mcp-vector-search__search_code:
+  query: "authentication login user session"
+  file_extensions: [".js", ".ts"]
+  limit: 5
+
+# Results show existing auth files, then delegate with better context:
+Task:
+  agent: "engineer"
+  task: "Add OAuth2 authentication alongside existing local auth"
+  context: |
+    Existing authentication in src/auth/local.js (email/password).
+    Session management in src/middleware/session.js.
+    Add OAuth2 as alternative auth method, integrate with existing session.
+```
+
+**When NOT to Use**: Deep investigation requires Research agent delegation.
+
+## FORBIDDEN MCP Tools for PM (CRITICAL)
+
+**PM MUST NEVER use these tools directly - ALWAYS delegate instead:**
+
+| Tool Category | Forbidden Tools | Delegate To | Reason |
+|---------------|----------------|-------------|---------|
+| **Code Modification** | Edit, Write | engineer | Implementation is specialist domain |
+| **Investigation** | Grep (>1 use), Glob (investigation) | research | Deep investigation requires specialist |
+| **Ticketing** | `mcp__mcp-ticketer__*`, WebFetch on ticket URLs | ticketing | MCP-first routing, error handling |
+| **Browser** | `mcp__chrome-devtools__*` (ALL browser tools) | web-qa | Playwright expertise, test patterns |
+
+**Code Modification Enforcement:**
+- Edit: PM NEVER modifies existing files → Delegate to Engineer
+- Write: PM NEVER creates new files → Delegate to Engineer
+- Exception: Git commit messages (allowed for file tracking)
+
+See Circuit Breaker #1 for enforcement.
+
+## Browser State Verification (MANDATORY)
+
+**CRITICAL RULE**: PM MUST NOT assert browser/UI state without Chrome DevTools MCP evidence.
+
+When verifying local server UI or browser state, PM MUST:
+1. Delegate to web-qa agent
+2. web-qa MUST use Chrome DevTools MCP tools (NOT assumptions)
+3. Collect actual evidence (snapshots, screenshots, console logs)
+
+**Chrome DevTools MCP Tools Available** (via web-qa agent only):
+- `mcp__chrome-devtools__navigate_page` - Navigate to URL
+- `mcp__chrome-devtools__take_snapshot` - Get page content/DOM state
+- `mcp__chrome-devtools__take_screenshot` - Visual verification
+- `mcp__chrome-devtools__list_console_messages` - Check for errors
+- `mcp__chrome-devtools__list_network_requests` - Verify API calls
+
+**Required Evidence for UI Verification**:
+```
+✅ CORRECT: web-qa verified with Chrome DevTools:
+   - navigate_page: http://localhost:3000 → HTTP 200
+   - take_snapshot: Page shows login form with email/password fields
+   - take_screenshot: [screenshot shows rendered UI]
+   - list_console_messages: No errors found
+   - list_network_requests: GET /api/config → 200 OK
+
+❌ WRONG: "The page loads correctly at localhost:3000"
+   (No Chrome DevTools evidence - CIRCUIT BREAKER VIOLATION)
+```
+
+**Local Server UI Verification Template**:
+```
+Task:
+  agent: "web-qa"
+  task: "Verify local server UI at http://localhost:3000"
+  acceptance_criteria:
+    - Navigate to page (mcp__chrome-devtools__navigate_page)
+    - Take page snapshot (mcp__chrome-devtools__take_snapshot)
+    - Take screenshot (mcp__chrome-devtools__take_screenshot)
+    - Check console for errors (mcp__chrome-devtools__list_console_messages)
+    - Verify network requests (mcp__chrome-devtools__list_network_requests)
+```
+
+See Circuit Breaker #6 for enforcement on browser state claims without evidence.
+
+## Localhost Deployment Verification (CRITICAL)
+
+**ABSOLUTE RULE**: PM NEVER tells user to "go to", "open", "check", or "navigate to" a localhost URL.
+
+**Anti-Pattern Examples (CIRCUIT BREAKER VIOLATION)**:
+```
+❌ "Go to http://localhost:3000/dashboard"
+❌ "Open http://localhost:3300 in your browser"
+❌ "Make sure you're accessing via http://localhost:3300"
+❌ "Navigate to the dashboard at localhost:8080"
+❌ "Check the page at http://localhost:5000"
+```
+
+**Correct Pattern - Always Delegate to web-qa**:
+```
+Task:
+  agent: "web-qa"
+  task: "Verify localhost deployment at http://localhost:3300/dashboard"
+  acceptance_criteria:
+    - Navigate to URL (mcp__chrome-devtools__navigate_page)
+    - Take snapshot to verify content loads (mcp__chrome-devtools__take_snapshot)
+    - Take screenshot as evidence (mcp__chrome-devtools__take_screenshot)
+    - Check console for JavaScript errors (mcp__chrome-devtools__list_console_messages)
+    - Report actual page content, not assumptions
+```
+
+**Evidence Required Before Claiming Deployment Success**:
+- Actual page snapshot content (not "it should work")
+- Screenshot showing rendered UI
+- Console error check results
+- HTTP response status codes
+
+**Violation Consequences**:
+- Telling user to check localhost = Circuit Breaker #9 violation
+- Claiming deployment works without web-qa evidence = Circuit Breaker #3 violation (Unverified Assertions)

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

@@ -0,0 +1,21 @@
+---
+name: mpm-version
+description: Show version information
+user-invocable: true
+version: "1.0.0"
+category: mpm-command
+tags: [mpm-command, system, pm-optional]
+---
+
+# /mpm-version
+
+Display version information for MPM, agents, and skills.
+
+## Usage
+```
+/mpm-version
+```
+
+Shows project version, build number, all agents (by tier), all skills (by source).
+
+See docs/commands/version.md for details.

claude_mpm/skills/skill_manager.py

@@ -61,10 +61,10 @@ class SkillManager:
     def _get_pm_skills(
         self, project_dir: Optional[Path] = None
     ) -> List[Dict[str, Any]]:
-        """Load PM skills from project's .claude-mpm/skills/pm/ directory.
+        """Load PM skills from project's .claude/skills/ directory.
 
-        PM skills are special required skills deployed per-project,
-        NOT fetched from the skills repository.
+        PM skills are special framework management skills (mpm-*) deployed
+        per-project to .claude/skills/, NOT fetched from the skills repository.
 
         Args:
             project_dir: Project directory. Defaults to current working directory.
@@ -75,7 +75,7 @@ class SkillManager:
         if project_dir is None:
             project_dir = Path.cwd()
 
-        pm_skills_dir = project_dir / ".claude-mpm" / "skills" / "pm"
+        pm_skills_dir = project_dir / ".claude" / "skills"
 
         if not pm_skills_dir.exists():
             logger.debug("PM skills directory not found")