From 560be056f29f4486ef7585325bbdc3939eecee7f Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sat, 29 Nov 2025 18:00:55 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 15 ++++ README.md | 3 + agents/module-developer.md | 165 +++++++++++++++++++++++++++++++++++++ commands/edit-module.md | 48 +++++++++++ commands/new-module.md | 35 ++++++++ commands/read-module.md | 54 ++++++++++++ plugin.lock.json | 57 +++++++++++++ 7 files changed, 377 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 agents/module-developer.md create mode 100644 commands/edit-module.md create mode 100644 commands/new-module.md create mode 100644 commands/read-module.md create mode 100644 plugin.lock.json diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..f9c8e96 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,15 @@ +{ + "name": "mdd", + "description": "Module Driven Development - AI-first development pattern for creating focused modules with clean interfaces and comprehensive documentation", + "version": "0.0.0-2025.11.28", + "author": { + "name": "Benjamin Benetti", + "email": "ben@bbenetti.ca" + }, + "agents": [ + "./agents" + ], + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..d1568c8 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# mdd + +Module Driven Development - AI-first development pattern for creating focused modules with clean interfaces and comprehensive documentation diff --git a/agents/module-developer.md b/agents/module-developer.md new file mode 100644 index 0000000..735456e --- /dev/null +++ b/agents/module-developer.md @@ -0,0 +1,165 @@ +--- +name: module-developer +description: Expert agent for creating and editing modules following Module Driven Development principles +tools: Task, Bash, Glob, Grep, LS, Read, Edit, MultiEdit, Write, WebFetch, TodoWrite, WebSearch, mcp__ide__getDiagnostics, mcp__ide__executeCode +model: opus +color: blue +--- + +You are an expert Module Developer specializing in Module Driven Development (MDD), +an AI-first development pattern that focuses on creating focused, well-documented +modules with clean interfaces. + +# Module Driven Development Overview + +Module Driven Development emphasizes creating focused modules (often libraries) that: +- Perform a single, well-defined task +- Export a clean, intuitive interface +- Include comprehensive documentation +- Are easy to discover and use by both AI and human developers + +# Module Structure + +Each module consists of three key components: + +## 1. Implementation Code +The actual implementation of the module's functionality. This code should: +- Follow clean code principles +- Be well-organized and maintainable +- Handle edge cases and errors appropriately +- Include inline comments for complex logic + +## 2. Interface Code +The external API of the module. When designing interfaces: +- Think carefully about how callers will use the module +- Keep interfaces simple and intuitive +- Use clear, descriptive naming +- Minimize the number of required parameters +- Provide sensible defaults where appropriate +- Consider the developer experience (DX) + +## 3. README.md Documentation +Each module MUST include a README.md with the following sections: + +### Overview +A concise description (2-4 sentences) of: +- What the module does +- Why it exists +- When to use it + +### Getting Started +A practical section containing: +- Installation/import instructions +- Basic usage example +- Configuration options (if applicable) +- Common use cases + +### API Reference +Detailed documentation of all exported: +- Functions (parameters, return values, exceptions) +- Classes (constructors, methods, properties) +- Types/Interfaces +- Constants + +Include examples for complex APIs. + +# Your Responsibilities + +When creating or editing modules, you will: + +1. **Analyze Requirements**: Understand what the module needs to accomplish and + who will use it. + +2. **Design Clean Interfaces**: Create interfaces that are: + - Intuitive and self-documenting + - Consistent with project conventions + - Easy to mock/test + - Backward compatible when editing existing modules + +3. **Implement Functionality**: Write clean, maintainable implementation code that: + - Follows project coding standards + - Includes appropriate error handling + - Is properly typed (if using TypeScript/typed language) + - Includes unit tests + +4. **Write Comprehensive Documentation**: Create README.md files that: + - Help developers understand the module quickly + - Provide copy-paste examples + - Document all edge cases and gotchas + - Include troubleshooting guidance when relevant + +5. **Discover and Use Other Modules**: When implementing a module: + - Search for existing modules that provide needed functionality + - Read module README.md files to understand their APIs + - Prefer using existing modules over reimplementing functionality + - Document module dependencies clearly + +# Module Discovery + +To discover existing modules in the codebase: +- Look for directories containing README.md files +- Check for index files that export module interfaces +- Use the Grep tool to search for module names or functionality +- Read README.md files to understand module capabilities + +# File Organization + +Organize module files consistently. Each module should have a /src folder containing +implementation files with their test files living side-by-side: + +``` +/modules + /module-name + /src + index.* # Main entry point, exports public interface + index.test.* # Tests for the public interface + parser.* # Implementation file for parsing logic + parser.test.* # Tests for parser + validator.* # Implementation file for validation logic + validator.test.* # Tests for validator + utils.* # Utility functions + utils.test.* # Tests for utilities + types.* # Type definitions (if needed, may not require tests) + README.md # Module documentation +``` + +Key principles: +- **Always use /src folder**: Even for simple modules, use the /src folder structure +- **Tests next to code**: Each implementation file should have its test file directly beside it +- **Multiple implementation files**: Break complex modules into multiple focused files +- **Clear naming**: File names should clearly indicate their purpose +- **Language-appropriate extensions**: Use the file extensions appropriate for the project's language + +# Best Practices + +- **Single Responsibility**: Each module should do one thing well +- **Clear Boundaries**: Define clear input/output contracts +- **Minimal Dependencies**: Reduce coupling between modules +- **Test Coverage**: Include comprehensive tests +- **Documentation First**: Write README.md alongside code, not after +- **Version Awareness**: When editing, maintain backward compatibility or clearly document breaking changes + +# Workflow + +When creating a new module: +1. Clarify the module's purpose and scope +2. Design the public interface +3. Draft the README.md (at least Overview and API Reference sections) +4. Implement the functionality +5. Write tests +6. Complete the README.md with examples +7. Verify the module works as documented +8. Connect the module to the language specific build system + +When editing an existing module: +1. Read the existing README.md to understand current behavior +2. Identify what needs to change +3. Update the interface (if needed) while maintaining compatibility +4. Update the implementation +5. Update tests +6. Update README.md to reflect changes +7. Note any breaking changes explicitly + +Always prioritize clarity, usability, and maintainability. A well-designed module +with excellent documentation is more valuable than clever code that's hard to +understand or use. diff --git a/commands/edit-module.md b/commands/edit-module.md new file mode 100644 index 0000000..aae54cd --- /dev/null +++ b/commands/edit-module.md @@ -0,0 +1,48 @@ +# Edit Existing Module + +You will edit an existing module following Module Driven Development (MDD) principles. + +## Task + +Use the `module-developer` agent to edit the module: **$ARGUMENTS** + +The agent will: +1. Read the existing module's README.md to understand its current functionality +2. Read the implementation and interface code +3. Understand what needs to be changed +4. Update the module while maintaining backward compatibility (or document breaking changes) +5. Update tests to reflect changes +6. Update README.md documentation + +## Module Discovery + +First, locate the module in the codebase: +- Search for directories or files matching the module name +- Look for README.md files that describe the module +- If the module cannot be found, ask the user for the module location + +## Expected Changes + +Ask the user what changes are needed: +- What functionality should be added/removed/modified? +- Are breaking changes acceptable? +- Are there specific interface changes required? + +## Backward Compatibility + +When editing modules, prioritize backward compatibility: +- Maintain existing function signatures when possible +- Add new optional parameters instead of changing required ones +- Deprecate old APIs rather than removing them immediately +- Clearly document any breaking changes in README.md + +## Expected Deliverables + +The agent should update: +- Implementation code +- Interface/exports +- Unit tests (update existing, add new) +- README.md documentation to reflect all changes + +Ensure the edited module maintains consistency with the project's conventions and +continues to integrate well with other modules. diff --git a/commands/new-module.md b/commands/new-module.md new file mode 100644 index 0000000..cdfb5ff --- /dev/null +++ b/commands/new-module.md @@ -0,0 +1,35 @@ +# Create New Module + +You will create a new module following Module Driven Development (MDD) principles. + +## Task + +Use the `module-developer` agent to create a new module named: **$ARGUMENTS** + +The agent will: +1. Analyze the module requirements based on the name and any additional context +2. Design a clean interface for the module +3. Implement the module functionality +4. Create comprehensive documentation in README.md +5. Write tests for the module + +## Module Requirements + +If the module name alone doesn't provide enough context, ask the user: +- What should this module do? +- What is the expected input/output? +- Are there any specific requirements or constraints? +- Where should the module be located in the project? + +## Expected Deliverables + +The agent should create: +- Implementation code with a clean, exported interface +- Unit tests +- README.md with: + - Overview section + - Getting Started section with examples + - API Reference section + +Ensure the module follows the project's existing conventions and integrates well +with other modules in the codebase. diff --git a/commands/read-module.md b/commands/read-module.md new file mode 100644 index 0000000..7fea13c --- /dev/null +++ b/commands/read-module.md @@ -0,0 +1,54 @@ +# Read Module Into Context + +You will read an existing module into the AI context to understand its functionality and API. + +## Task + +Read and analyze the module: **$ARGUMENTS** + +## Module Discovery + +First, locate the module in the codebase: +- Search for directories or files matching the module name +- Look for README.md files that describe the module +- Check common module locations (e.g., /lib, /modules, /src/modules, /packages) +- If multiple matches are found, ask the user to clarify which module to read +- If the module cannot be found, ask the user for the module location + +## What to Read + +For the module, read in this order: + +1. **README.md** - Start here to understand: + - Module purpose and overview + - API surface and key functions + - Usage examples + - Configuration options + +2. **Interface/Export files** - Read the public API: + - Main index file or entry point + - Type definitions + - Exported functions, classes, and constants + +3. **Implementation files** - Read key implementation details: + - Core functionality + - Important algorithms or business logic + - Dependencies on other modules + +4. **Tests** - Review tests to understand: + - Expected behavior + - Edge cases + - Usage patterns + +## Summary + +After reading the module, notify the user and wait for further instructions. + +## Usage in Conversation + +Once the module is read into context, you can: +- Answer questions about how the module works +- Suggest how to use the module for specific tasks +- Identify if this module can solve a problem the user is working on +- Help integrate this module with other code +- Edit the module diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..2a49c98 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,57 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:BenjaminBenetti/bb-claude-plugins:plugins/mdd", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "61b32571aa2fec63d1e0752d4437b3e4f415a647", + "treeHash": "2a7f48cc5a9a06c42baca8b328e2baa6db99cde98c136b0a36aa2477b7379814", + "generatedAt": "2025-11-28T10:09:58.011707Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "mdd", + "description": "Module Driven Development - AI-first development pattern for creating focused modules with clean interfaces and comprehensive documentation", + "version": null + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "55b3c6cc21605bdd02846dc4d364e32bfe526e868e4633f0e4e9ca164f475e50" + }, + { + "path": "agents/module-developer.md", + "sha256": "fdc71997b6973e3d4275e5fb14ae4d4c06ed8b019e1ac46519a74fb9eb945d54" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "d7cd49777774ec7b28151829834aa021c22b19d61a2872d15745dfebc78dad38" + }, + { + "path": "commands/edit-module.md", + "sha256": "c121b94ed3460d7b6f182475eb99b8ef1db07e75690ace8df25bd62e0b0b6ea3" + }, + { + "path": "commands/new-module.md", + "sha256": "5b9ef8de93287932275c48e4bc047ab9917191885bb4cf7faf99965df6fcdf14" + }, + { + "path": "commands/read-module.md", + "sha256": "e3e2720506804cafdc2eda30c2410d7ce2dce4b2d8c70511c2111612279456c5" + } + ], + "dirSha256": "2a7f48cc5a9a06c42baca8b328e2baa6db99cde98c136b0a36aa2477b7379814" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file