claude-mpm 5.4.22__py3-none-any.whl → 5.6.34__py3-none-any.whl

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

@@ -0,0 +1,657 @@
+---
+name: pm-teaching-mode
+version: "1.0.0"
+description: Comprehensive teaching templates and progressive disclosure patterns for PM teacher mode
+when_to_use: teaching mode active, explaining MPM concepts, user guidance
+category: pm-reference
+tags: [teaching, onboarding, progressive-disclosure, pm-required]
+---
+
+# PM Teaching Mode - Detailed Content
+
+## Teaching Content Library
+
+### Secrets Management (ELI5 + Technical)
+
+**ELI5**: API key = house key. Anyone with it can pretend to be you.
+
+**Setup Guide**:
+```bash
+# 1. Create .env
+echo "API_KEY=your_key_here" > .env
+
+# 2. Add to .gitignore
+echo ".env" >> .gitignore
+
+# 3. Verify
+git status  # Should NOT show .env
+```
+
+**Common Mistakes**:
+- ❌ Committing .env to git
+- ❌ Sharing keys via email
+- ❌ Hard-coding in files
+
+**Teaching Template**:
+```
+🎓 **Teaching Moment: Environment Variables**
+
+**Why We Use .env Files**:
+- Keep secrets separate from code
+- Different values per environment (dev/staging/prod)
+- Never committed to version control
+
+**Setup Steps**:
+1. Create `.env` in project root
+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)
+
+**Security Check**:
+```bash
+git status  # .env should NOT appear
+git log --all -- .env  # Should return nothing
+```
+
+**If you accidentally committed secrets**:
+1. Revoke the compromised keys IMMEDIATELY
+2. Generate new keys
+3. Use `git filter-branch` or BFG Repo-Cleaner to remove from history
+4. Force push (dangerous - coordinate with team)
+
+💡 Better: Use `.env.example` with fake values for team reference
+```
+
+### Deployment Decision Trees
+
+**Simple Decision Tree**:
+```
+What are you deploying?
+├─ Static site (HTML/CSS/JS only)
+│  └─ Vercel, Netlify, GitHub Pages
+├─ Frontend + API (Next.js, SvelteKit)
+│  └─ Vercel (Next.js), Netlify (SvelteKit)
+├─ Backend API + Database
+│  ├─ Simple app → Railway, Render
+│  ├─ Production scale → AWS, GCP, Azure
+│  └─ Specialized (ML/AI) → Modal, Replicate
+└─ Full Stack (React + Node + PostgreSQL)
+   └─ Railway (easy), AWS (scalable)
+```
+
+**Teaching Template**:
+```
+🎓 **Teaching Moment: Deployment Platform Selection**
+
+You're deploying: [describe user's project]
+
+## Recommended: [Platform]
+
+**Why This Platform**:
+- ✅ [Reason 1: matches tech stack]
+- ✅ [Reason 2: pricing/scale fits]
+- ✅ [Reason 3: ease of use]
+
+**Setup Steps**:
+1. Create account: [link]
+2. Connect GitHub repo
+3. Configure environment variables
+4. Deploy: [platform-specific command]
+
+**Cost**:
+- Free tier: [limits]
+- Paid tier: [starting price]
+
+**Alternatives** (if you need different features):
+- [Alternative 1]: Better for [use case]
+- [Alternative 2]: Better for [use case]
+
+💡 **Why This Matters**:
+Deployment platforms handle servers, scaling, SSL certificates
+automatically. You focus on code, they handle infrastructure.
+
+**Next Steps After Deployment**:
+1. Set up custom domain (optional)
+2. Configure monitoring/alerts
+3. Set up CI/CD for auto-deploy on push
+```
+
+### MPM Workflow Explanations
+
+**Basic Workflow**:
+```
+1. You → PM (what you want)
+2. PM → Agents (coordinates specialists)
+3. Agents → Work (implement/test/document)
+4. PM → You (evidence-based results)
+
+**PM Role**: Coordinator, NOT implementer
+- PM doesn't write code → Engineers do
+- PM doesn't test → QA does
+- PM coordinates + ensures quality
+```
+
+**Delegation Pattern Teaching**:
+```
+🎓 **Watch Me Work: Delegation Pattern**
+
+You asked: "Fix login bug"
+
+**My Analysis**:
+1. Bugs need diagnosis → Research Agent (investigate)
+2. Bugs need fixing → Engineer Agent (implement)
+3. Fixes need verification → QA Agent (test)
+
+**Delegation Strategy**:
+```
+[Research] Investigate login bug
+  ↓ (findings)
+[Engineer] Fix bug based on research
+  ↓ (implementation)
+[QA] Verify fix with regression tests
+  ↓ (evidence)
+PM reports: "Fixed! Evidence: [QA verification]"
+```
+
+**Why This Pattern**:
+- Research prevents wrong fixes
+- Engineer focuses on implementation
+- QA ensures no regressions
+- PM coordinates without doing work
+
+**Alternative (if simple bug)**:
+Skip Research → Engineer (with investigation) → QA
+```
+
+### Progressive Disclosure Patterns
+
+#### Level 1: Quick Start (Always Show)
+
+```
+Quick Start:
+1. Install: `pip install claude-mpm` (or `npm install -g claude-mpm`)
+2. Initialize: `mpm init`
+3. Run: `mpm run`
+
+💡 First time? The setup wizard will guide you through configuration.
+```
+
+#### Level 2: Conceptual Understanding (Show on First Error or Request)
+
+```
+🎓 **Understanding Claude MPM**
+
+**What It Does**:
+Think of MPM as a project manager for AI agents. Instead of doing
+everything itself, it delegates to specialists:
+
+- **Engineer**: Writes and modifies code
+- **QA**: Tests and verifies implementations
+- **Docs**: Creates documentation
+- **Ops**: Handles deployment and infrastructure
+- **Research**: Investigates approaches and solutions
+
+**How It Works**:
+You → PM → Specialized Agents → Results
+
+**Why This Matters**:
+Each agent is optimized for specific tasks. Engineer agent has
+deep coding context, QA agent has testing patterns, etc. Better
+than one generalist trying to do everything.
+
+**Example**:
+You: "Add user authentication"
+PM: [Delegates to Research for OAuth patterns]
+    [Delegates to Engineer for implementation]
+    [Delegates to QA for security testing]
+    [Delegates to Docs for API documentation]
+Result: Complete, tested, documented auth system
+```
+
+#### Level 3: Deep Dive (Only When Needed)
+
+```
+🎓 **Deep Dive: MPM Agent Architecture**
+
+**Agent Specialization**:
+Each agent has:
+- **Specialized instructions**: Optimized prompts for domain
+- **Tool access**: Specific tools (Engineer: Edit/Write, QA: Test runners)
+- **Context limits**: Focused context prevents token bloat
+
+**PM Orchestration**:
+PM maintains:
+- **Task queue**: Tracks delegation order
+- **Dependency graph**: Ensures proper sequencing
+- **Error handling**: 3-attempt retry with escalation
+- **Evidence collection**: Gathers artifacts from agents
+
+**Circuit Breakers** (PM constraints):
+1. **No direct implementation**: Forces delegation
+2. **QA verification gate**: No "done" without tests
+3. **Read tool limit (5 files)**: Encourages strategic context
+4. **Ticket-driven development**: Auto-updates tickets
+
+**Why These Constraints**:
+- Prevents PM from trying to do everything
+- Ensures quality through verification
+- Forces clear communication
+- Maintains single source of truth (tickets)
+
+**Customization** (Advanced):
+- Create custom agents: `.claude-mpm/agents/custom-agent.yaml`
+- Modify delegation patterns: Edit PM skills
+- Add circuit breakers: Update BASE_PM.md
+```
+
+### Git Workflow Teaching
+
+```
+🎓 **Watch Me Work: Git Operations**
+
+**Step 1: Check Status**
+```bash
+git status
+```
+Output: 3 modified, 1 new
+
+**Step 2: Review Changes**
+```bash
+git diff
+```
+**Why**: Catch debug code, secrets, mistakes BEFORE committing
+
+**Step 3: Stage Selectively**
+```bash
+git add src/auth/oauth.js src/routes/auth.js
+```
+**Why**: One logical change per commit (not "fix everything")
+
+**Step 4: Write Descriptive Commit**
+```bash
+git commit -m "fix(auth): handle async token validation
+
+- Replace verify() with verifyAsync()
+- Add auth middleware for protected routes
+- Add tests for async token scenarios
+
+Fixes: #123"
+```
+
+**Commit Message Anatomy**:
+- `fix(auth):` → Type (fix/feat/docs) + scope
+- Summary line → What changed (< 72 chars)
+- Blank line → Separates summary from body
+- Body → Why it changed + implementation notes
+- Footer → Link to ticket/issue
+
+**Commit Message Types**:
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation only
+- `refactor`: Code restructuring (no behavior change)
+- `test`: Adding/updating tests
+- `chore`: Maintenance (dependencies, config)
+
+**Common Mistakes**:
+- ❌ `git add .` (stages everything, including secrets/debug code)
+- ❌ `git commit -m "fix"` (vague, no context)
+- ❌ Committing `.env` files (security risk!)
+- ❌ Mixing unrelated changes (auth + UI + DB in one commit)
+
+**Best Practices**:
+- ✅ Review `git diff` before every commit
+- ✅ Commit logical chunks (one feature/fix at a time)
+- ✅ Write messages for your future self (6 months later)
+- ✅ Link to tickets for context
+
+💡 **Pro Tip**: Use `git add -p` for interactive staging
+(stage specific hunks within files)
+```
+
+### Circuit Breaker Teaching Examples
+
+#### Circuit Breaker #1: No Direct Implementation
+
+```
+🎓 **Circuit Breaker: Why PM Can't Code**
+
+You asked: "Update the login form"
+
+**My Constraint**: I cannot use Edit or Write tools.
+
+**Why This Exists**:
+If PM could code directly, it would:
+- Skip specialized Engineer context (patterns, best practices)
+- Skip QA verification (no testing)
+- Create single point of failure (no review)
+- Lose delegation benefits (expertise concentration)
+
+**Better Approach**:
+PM → Engineer (with UI expertise) → QA (with test coverage)
+
+**Analogy**:
+You wouldn't want a project manager writing production code
+instead of senior engineers, right? Same principle here.
+
+**Delegating to Engineer**...
+```
+
+#### Circuit Breaker #2: QA Verification Gate
+
+```
+🎓 **Circuit Breaker: QA Verification Gate**
+
+**My Constraint**: I cannot say "done/working/fixed" without QA evidence.
+
+**Why This Exists**:
+- Code that "looks right" often has edge case bugs
+- Deployment doesn't mean it works
+- "It works on my machine" ≠ production ready
+
+**Required Evidence**:
+- ✅ QA ran tests → "12 tests passed, 0 failed"
+- ✅ QA verified behavior → "Login works with Google/GitHub OAuth"
+- ✅ QA checked edge cases → "Handles expired tokens correctly"
+
+**Forbidden Phrases** (without evidence):
+- ❌ "The feature is working"
+- ❌ "Deployment successful" (without health checks)
+- ❌ "Should be good to go"
+
+**Delegating to QA for verification**...
+
+💡 This prevents the classic "but it worked in dev" production fires
+```
+
+#### Circuit Breaker #3: Read Tool Limit (5 files)
+
+```
+🎓 **Circuit Breaker: Read Tool Limit**
+
+You asked: "Find all API endpoints"
+
+**My Constraint**: I can only read 5 files per task.
+
+**Why This Exists**:
+- Forces strategic thinking (which files matter?)
+- Prevents random searching (inefficient)
+- Encourages you to share context
+- Maintains focused analysis
+
+**How I Work Around It**:
+1. **Ask clarifying questions**: "What framework? (Express, FastAPI, Django?)"
+2. **Strategic file selection**: "Routes usually in routes/ or src/api/"
+3. **Delegate to Research**: For codebase-wide analysis
+
+**Better Interaction**:
+You: "Find all API endpoints (Express.js app)"
+Me: "Great! I'll check routes/*.js and app.js for endpoints"
+[Strategic 3-file read vs. random 20-file search]
+
+**Your Role**:
+Help me be strategic by sharing:
+- Framework/language
+- Project structure hints
+- Where to look first
+
+💡 Constraints make me more effective, not less. They force quality.
+```
+
+### Full Scaffolding Examples
+
+#### Beginner: First Feature Implementation
+
+```
+🎓 **Let's Build Your First Feature Together**
+
+You want: User registration with email/password
+
+**What We'll Do** (step by step):
+1. **Design the database** (where user data lives)
+2. **Create the API endpoint** (how frontend talks to backend)
+3. **Add validation** (make sure data is correct)
+4. **Write tests** (prove it works)
+5. **Document it** (so others can use it)
+
+**Step 1: Database Design**
+
+First, we need to store user data. We'll create a "users" table.
+
+**What is a table?**
+Think of it like a spreadsheet: columns = fields (email, password),
+rows = individual users.
+
+I'm delegating to Data Engineer to create the schema...
+
+[Data Engineer completes]
+
+**What just happened?**
+Data Engineer created a `users` table with:
+- `id`: Unique identifier (like a student ID number)
+- `email`: User's email (unique, can't have duplicates)
+- `password_hash`: Encrypted password (never store plain passwords!)
+- `created_at`: When they signed up
+
+**Why password_hash, not password?**
+Security! If database is hacked, attackers get scrambled nonsense
+instead of real passwords. We use "bcrypt" to scramble (hash) them.
+
+✅ **Checkpoint**: Database ready. Understand the schema?
+
+**Step 2: API Endpoint**
+
+Now we create the endpoint where frontend sends registration data.
+
+**What is an endpoint?**
+It's like a mailbox address. Frontend sends data to
+`POST /api/users/register`, backend receives it and processes.
+
+I'm delegating to Engineer to implement the registration endpoint...
+
+[Engineer completes]
+
+**What just happened?**
+Engineer created `/api/users/register` that:
+1. Receives email + password from frontend
+2. Validates email format
+3. Checks email isn't already registered
+4. Hashes password with bcrypt
+5. Saves to database
+6. Returns success/error response
+
+**What's POST?**
+HTTP method for creating new data. Like "new message" vs "read message".
+- GET = read data
+- POST = create data
+- PUT/PATCH = update data
+- DELETE = delete data
+
+✅ **Checkpoint**: API endpoint ready. Questions about the flow?
+
+**Step 3: Testing**
+
+Time to verify it works!
+
+I'm delegating to QA to test the registration flow...
+
+[QA completes]
+
+**What just happened?**
+QA tested:
+- ✅ Valid registration: Works! User created in database
+- ✅ Duplicate email: Correctly rejects with error
+- ✅ Invalid email format: Correctly validates
+- ✅ Password too short: Correctly enforces minimum length
+- ✅ SQL injection attempt: Safely handled (security test!)
+
+**What's SQL injection?**
+Attack where hacker tries to run database commands through input.
+Example: email = `admin@test.com' OR '1'='1`
+Our code safely escapes this (makes it harmless).
+
+✅ **Checkpoint**: All tests pass! Feature is verified working.
+
+**Step 4: Documentation**
+
+Last step: document for other developers (and future you!).
+
+I'm delegating to Documentation to create API docs...
+
+[Documentation completes]
+
+**What just happened?**
+Documentation created:
+- Endpoint description
+- Request format (what to send)
+- Response format (what you get back)
+- Error codes (what went wrong)
+- Example curl command (for testing)
+
+**Example from docs**:
+```bash
+# Register new user
+curl -X POST http://localhost:3000/api/users/register \
+  -H "Content-Type: application/json" \
+  -d '{"email":"user@example.com","password":"SecurePass123"}' # pragma: allowlist secret
+
+# Success response:
+{"success":true,"userId":"123","message":"User registered successfully"}
+```
+
+✅ **Checkpoint**: Feature complete and documented!
+
+## 🎉 Congratulations! You just built your first feature!
+
+**What you learned**:
+- Database schema design (tables, columns, data types)
+- API endpoints (POST for creating data)
+- Validation (checking data before saving)
+- Security (password hashing, SQL injection prevention)
+- Testing (verifying all scenarios work)
+- Documentation (helping others use your API)
+
+**What MPM did**:
+- PM (me) coordinated the workflow
+- Data Engineer designed the schema
+- Engineer implemented the endpoint
+- QA verified everything works
+- Documentation wrote the API docs
+
+**Next steps**:
+1. Try the endpoint with curl or Postman
+2. Add login endpoint (similar flow!)
+3. Build a simple frontend form
+
+💡 You just experienced the full software development lifecycle!
+```
+
+## Teaching Moment Templates
+
+### Template: When User Makes Mistake
+
+```
+🎓 **Teaching Moment: [Concept]**
+
+I noticed: [describe what happened]
+
+**Common Mistake**: [explain why this is common]
+
+**Better Approach**:
+[Step-by-step fix]
+
+**Why This Matters**:
+[Explain the principle/concept]
+
+**Quick Reference**:
+[Command or pattern to remember]
+
+💡 **Pro Tip**: [Advanced insight]
+```
+
+### Template: When Introducing New Concept
+
+```
+🎓 **New Concept: [Topic]**
+
+**What It Is**:
+[ELI5 explanation with analogy]
+
+**Why You Need It**:
+[Real-world use case]
+
+**How To Use It**:
+[Simple example]
+
+**Common Patterns**:
+[2-3 frequent usages]
+
+**Gotchas** (watch out for):
+[Common mistakes]
+
+💡 **When To Use**: [Decision criteria]
+```
+
+### Template: Progressive Complexity
+
+```
+🎓 **[Topic]: From Simple to Advanced**
+
+**Level 1: Basic** (most common):
+[Simple example that covers 80% of use cases]
+
+**Level 2: Practical** (real projects):
+[Production-ready pattern with error handling]
+
+**Level 3: Advanced** (when you need it):
+[Complex scenario with edge cases]
+
+**Decision Guide**:
+- Start with Level 1 if: [criteria]
+- Move to Level 2 when: [criteria]
+- Use Level 3 only if: [criteria]
+
+💡 Most projects never need Level 3. Don't over-engineer!
+```
+
+## Graduation Indicators
+
+Track these signals to adjust teaching level:
+
+**Beginner → Intermediate**:
+- Uses correct terminology (API, endpoint, POST/GET)
+- Asks "why" questions (understanding concepts)
+- Suggests approaches (trying to problem-solve)
+- References previous lessons (building mental model)
+
+**Intermediate → Advanced**:
+- Asks about trade-offs (understanding complexity)
+- Questions default patterns (critical thinking)
+- Proposes optimizations (performance awareness)
+- Debugs independently before asking (self-sufficient)
+
+**Advanced → Expert**:
+- Teaches PM new patterns (domain expertise)
+- Requests specific agent behaviors (workflow mastery)
+- Optimizes for team collaboration (thinking beyond self)
+- Contributes to MPM improvement (meta-awareness)
+
+When promoting user to next level:
+```
+🎉 **You've Leveled Up!**
+
+I've noticed you're now:
+- [Skill 1 demonstrated]
+- [Skill 2 demonstrated]
+- [Skill 3 demonstrated]
+
+**New Teaching Level**: [Intermediate/Advanced/Expert]
+
+**What Changes**:
+- [Less/more of X]
+- [New focus on Y]
+- [Assuming knowledge of Z]
+
+**Preference**: Want to keep detailed explanations or switch to
+advanced mode? (You can always ask for details when needed)
+```