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

claude_mpm/skills/bundled/collaboration/writing-plans/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: Writing Plans
+description: Create detailed implementation plans with bite-sized tasks for engineers with zero codebase context
+when_to_use: when design is complete and you need detailed implementation tasks for engineers with zero codebase context
+version: 2.2.0
+progressive_disclosure:
+  level: 1
+  references:
+    - path: references/plan-structure-templates.md
+      title: Plan Structure & Templates
+      description: Standard headers, task templates, and structure examples
+    - path: references/best-practices.md
+      title: Best Practices & Guidelines
+      description: Writing for zero-context engineers, code completeness, test design patterns
+---
+
+# Writing Plans
+
+## Overview
+
+Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
+
+Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.
+
+**Announce at start:** "I'm using the Writing Plans skill to create the implementation plan."
+
+**Context:** This should be run in a dedicated worktree (created by brainstorming skill).
+
+**Save plans to:** `docs/plans/YYYY-MM-DD-<feature-name>.md`
+
+## Quick Reference
+
+**Plan header template:** See [Plan Structure & Templates](references/plan-structure-templates.md#standard-plan-document-header)
+
+**Task template:** See [Plan Structure & Templates](references/plan-structure-templates.md#task-template-structure)
+
+**Granularity guide:** Each step = 2-5 minutes. See [Best Practices](references/best-practices.md#bite-sized-task-granularity)
+
+## Core Principles
+
+- **Exact file paths always** - Not "in the user module" but "`src/models/user.py`"
+- **Complete code in plan** - Not "add validation" but show the validation code
+- **Exact commands with expected output** - "`pytest tests/file.py -v`" with what you'll see
+- **Reference relevant skills** - Use @ syntax: `@skills/category/skill-name`
+- **DRY, YAGNI, TDD, frequent commits** - Every task follows this pattern
+
+For detailed guidance: [Best Practices & Guidelines](references/best-practices.md)
+
+## Execution Handoff
+
+After saving the plan, offer execution choice:
+
+**"Plan complete and saved to `docs/plans/<filename>.md`. Two execution options:**
+
+**1. Subagent-Driven (this session)** - I dispatch fresh subagent per task, review between tasks, fast iteration
+
+**2. Parallel Session (separate)** - Open new session with executing-plans, batch execution with checkpoints
+
+**Which approach?"**
+
+**If Subagent-Driven chosen:**
+- Use @skills/collaboration/subagent-driven-development
+- Stay in this session
+- Fresh subagent per task + code review
+
+**If Parallel Session chosen:**
+- Guide them to open new session in worktree
+- New session uses @skills/collaboration/executing-plans
+
+## Remember
+
+- Write for zero-context engineers (specify everything)
+- Complete code blocks, not instructions
+- Exact commands with expected output
+- Test first, then implement, then commit
+- Reference existing patterns in codebase
+- Keep tasks bite-sized (2-5 minutes each)
+
+**Need examples?** See [Plan Structure & Templates](references/plan-structure-templates.md) for complete task examples.
+
+**Need patterns?** See [Best Practices](references/best-practices.md) for error handling, logging, test design, and more.

claude_mpm/skills/bundled/collaboration/writing-plans/references/best-practices.md

@@ -0,0 +1,362 @@
+# Plan Writing Best Practices
+
+## Core Principles
+
+### DRY (Don't Repeat Yourself)
+- Extract common patterns into utilities
+- Reuse existing functions and classes
+- Create shared helpers for repeated logic
+- Never copy-paste code in the plan
+
+### YAGNI (You Aren't Gonna Need It)
+- Build only what's required by the design
+- No speculative features
+- No "future-proofing" unless explicitly required
+- Start simple, extend when needed
+
+### TDD (Test-Driven Development)
+- Write test first, always
+- Watch it fail before implementing
+- Implement minimal code to pass
+- Refactor after green
+
+### Frequent Commits
+- Commit after each passing test
+- One feature per commit
+- Clear, descriptive commit messages
+- Never commit broken code
+
+## Writing for Zero-Context Engineers
+
+### Assume They Know
+- Core programming concepts
+- The programming language syntax
+- Basic development tools (git, pytest, npm)
+- General software patterns
+
+### Assume They DON'T Know
+- Your specific codebase structure
+- Domain-specific terminology
+- Project conventions and patterns
+- Where files should go
+- Which existing utilities to use
+- Your testing strategy
+
+### Therefore, Always Specify
+- **Exact file paths** - not "in the user module" but "`src/models/user.py`"
+- **Complete code** - not "add validation" but show the validation code
+- **Exact commands** - not "run tests" but "`pytest tests/models/test_user.py -v`"
+- **Expected output** - what should happen when they run the command
+- **Line numbers** for modifications - "`src/config.py:45-52`"
+
+## Complete Code, Not Instructions
+
+❌ **Bad (vague instructions):**
+```markdown
+**Step 3: Add validation**
+
+Add email validation to the User model.
+Make sure to check for valid format.
+```
+
+✅ **Good (complete code):**
+```markdown
+**Step 3: Add validation to User model**
+
+In `src/models/user.py`, add this method after line 12:
+```python
+def __post_init__(self):
+    if not validate_email(self.email):
+        raise ValueError(f"Invalid email: {self.email}")
+    if self.created_at is None:
+        self.created_at = datetime.utcnow()
+```
+```
+
+## Exact Commands with Expected Output
+
+❌ **Bad (vague):**
+```markdown
+**Step 2: Run the test**
+
+Run the test and make sure it fails.
+```
+
+✅ **Good (specific):**
+```markdown
+**Step 2: Run test to verify it fails**
+
+Run: `pytest tests/models/test_user.py::test_user_creation -v`
+Expected output:
+```
+FAILED tests/models/test_user.py::test_user_creation - ModuleNotFoundError: No module named 'models.user'
+```
+
+This is expected! We haven't created the module yet.
+```
+
+## File Path Precision
+
+### For New Files
+```markdown
+**Files:**
+- Create: `src/api/handlers/users.py`
+- Create: `tests/api/test_users.py`
+```
+
+### For Modifications
+```markdown
+**Files:**
+- Modify: `src/api/routes.py:15` (add import)
+- Modify: `src/api/routes.py:45` (add route registration)
+- Modify: `src/config.py:12-18` (update database config)
+```
+
+### For Referenced Files
+```markdown
+**Documentation to check:**
+- See: `docs/api-design.md` (endpoint specification)
+- Reference: `src/api/handlers/auth.py:25-40` (similar pattern)
+```
+
+## Test Design for Zero-Context Engineers
+
+Many engineers struggle with test design. Help them by:
+
+### Show What to Test
+```markdown
+**Test coverage needed:**
+1. Happy path (valid input → expected output)
+2. Invalid input (error handling)
+3. Edge cases (empty, null, boundary values)
+4. Integration (does it work with real dependencies?)
+```
+
+### Provide Complete Test Examples
+```python
+# Happy path
+def test_create_user_success():
+    user = create_user("alice", "alice@example.com")
+    assert user.username == "alice"
+    assert user.email == "alice@example.com"
+
+# Invalid input
+def test_create_user_invalid_email():
+    with pytest.raises(ValueError, match="Invalid email"):
+        create_user("alice", "not-an-email")
+
+# Edge case
+def test_create_user_empty_username():
+    with pytest.raises(ValueError, match="Username cannot be empty"):
+        create_user("", "alice@example.com")
+```
+
+### Explain Test Strategy
+```markdown
+**Why these tests:**
+- `test_create_user_success`: Verifies basic functionality works
+- `test_create_user_invalid_email`: Ensures we reject bad data
+- `test_create_user_empty_username`: Prevents edge case bugs
+```
+
+## Referencing Existing Code
+
+### Use @ Syntax for Skills
+```markdown
+For authentication patterns, see @skills/security/implementing-auth
+For API design, reference @skills/api/rest-endpoints
+```
+
+### Reference Codebase Files
+```markdown
+**Similar implementations:**
+- `src/api/handlers/auth.py:25-40` - shows JWT validation pattern
+- `src/utils/validators.py:10-15` - email validation we can reuse
+```
+
+### Point to Documentation
+```markdown
+**Required reading:**
+- `docs/architecture/database-schema.md` - understand our user model
+- `docs/api/authentication.md` - see auth requirements
+```
+
+## Handling Dependencies and Setup
+
+### External Dependencies
+```markdown
+**Dependencies needed:**
+
+Add to `requirements.txt`:
+```
+bcrypt==4.0.1
+PyJWT==2.8.0
+```
+
+Install:
+```bash
+pip install -r requirements.txt
+```
+```
+
+### Configuration Changes
+```markdown
+**Configuration update:**
+
+In `src/config.py`, add:
+```python
+JWT_SECRET = os.environ.get("JWT_SECRET", "dev-secret-key")
+JWT_EXPIRATION_HOURS = 24
+```
+
+In `.env.example`:
+```
+JWT_SECRET=your-secret-key-here
+```
+```
+
+## Common Patterns to Include
+
+### Error Handling Pattern
+```python
+try:
+    result = risky_operation()
+    return result
+except SpecificError as e:
+    logger.error(f"Operation failed: {e}")
+    raise ValueError(f"Cannot complete operation: {e}")
+except Exception as e:
+    logger.exception("Unexpected error")
+    raise
+```
+
+### Resource Cleanup Pattern
+```python
+def process_file(filepath):
+    file_handle = None
+    try:
+        file_handle = open(filepath, 'r')
+        data = file_handle.read()
+        return process_data(data)
+    finally:
+        if file_handle:
+            file_handle.close()
+```
+
+### Logging Pattern
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+
+def important_operation():
+    logger.info("Starting operation")
+    try:
+        result = do_work()
+        logger.info(f"Operation completed: {result}")
+        return result
+    except Exception as e:
+        logger.error(f"Operation failed: {e}", exc_info=True)
+        raise
+```
+
+## Documentation in Plans
+
+### When to Include Inline Docs
+```markdown
+**Step 3: Implement user creation with docstring**
+
+```python
+def create_user(username: str, email: str) -> User:
+    """
+    Create a new user with validation.
+
+    Args:
+        username: User's chosen username (must be unique)
+        email: User's email address (must be valid format)
+
+    Returns:
+        User: The created user object
+
+    Raises:
+        ValueError: If username/email invalid or user exists
+    """
+    if not username:
+        raise ValueError("Username cannot be empty")
+    if not validate_email(email):
+        raise ValueError(f"Invalid email: {email}")
+
+    return User(username=username, email=email)
+```
+```
+
+### When to Update Separate Docs
+```markdown
+**Step 10: Update API documentation**
+
+In `docs/api/endpoints.md`, add:
+```markdown
+### POST /users
+
+Create a new user account.
+
+**Request:**
+```json
+{
+  "username": "alice",
+  "email": "alice@example.com"
+}
+```
+
+**Response:** 201 Created
+```json
+{
+  "id": 1,
+  "username": "alice",
+  "email": "alice@example.com",
+  "created_at": "2025-01-15T10:30:00Z"
+}
+```
+```
+```
+
+## Commit Message Guidelines
+
+### Format
+```
+type: brief description
+
+- Detail 1
+- Detail 2
+```
+
+### Types
+- `feat:` - New feature
+- `fix:` - Bug fix
+- `test:` - Add/update tests
+- `refactor:` - Code restructuring
+- `docs:` - Documentation only
+- `chore:` - Tooling, dependencies
+
+### Examples
+```bash
+git commit -m "feat: add user email validation"
+git commit -m "test: add edge cases for user creation"
+git commit -m "fix: handle empty username in user model"
+git commit -m "refactor: extract validation to utils module"
+```
+
+## Quality Checklist for Plans
+
+Before saving the plan, verify:
+
+- [ ] All file paths are exact and absolute
+- [ ] All code blocks are complete (not pseudocode)
+- [ ] All commands include expected output
+- [ ] Tests are written before implementation
+- [ ] Each step is 2-5 minutes of work
+- [ ] Dependencies and setup are documented
+- [ ] Error handling is included
+- [ ] Commit messages are descriptive
+- [ ] Referenced skills use @ syntax
+- [ ] Header follows standard template