bobmatnyc/claude-mpm/mpm-teaching-mode

# 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

🎓 **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**:

 
**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

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 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

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

🎓 **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**:

 
**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

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.

🎓 **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

🎓 **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

🎓 **Watch Me Work: Git Operations**
 
**Step 1: Check Status**

Output: 3 modified, 1 new
 
**Step 2: Review Changes**

**Why**: Catch debug code, secrets, mistakes BEFORE committing
 
**Step 3: Stage Selectively**

**Why**: One logical change per commit (not "fix everything")
 
**Step 4: Write Descriptive Commit**

 
**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: 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: 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: 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.

🎓 **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.