MCP/mcp-shrimp-task-manager
1
0
Fork 0
mirror of https://github.com/cjo4m06/mcp-shrimp-task-manager.git synced 2025-07-25 07:22:26 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat: Add CONTRIBUTING.md and update PR template

Browse Source
This commit is contained in:
Sergio Gonzalez 2025-06-08 19:51:39 +02:00
parent 1aab4e44b3
commit 5a39f9a9a9
3 changed files with 390 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
.github/PULL_REQUEST_TEMPLATE.md vendored Normal file
View File

@ -0,0 +1,44 @@
### Description
<!--
Please include a summary of the change and which issue is fixed if applicable.
Please also include relevant motivation and context.
List any dependencies that are required for this change.
-->
### Type of change
<!-- Please delete options that are not relevant. -->
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] This change requires a documentation update
### How Has This Been Tested?
<!--
Please describe the tests that you ran to verify your changes.
Provide instructions so we can reproduce.
Please also list any relevant details for your test configuration.
-->
- [ ] `npm run test` (following the project's testing guidelines)
- [ ] Manual testing with the following configuration:
**Test Configuration**:
* **Client**: (e.g., Cursor, Claude Code)
* **OS**: (e.g., macOS, Windows, Linux)
* **Node.js version**:
### Checklist:
- [ ] I have performed a self-review of my own code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation (`README.md`, `CHANGELOG.md`)
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] I have checked to ensure my PR is focused on a single feature/fix
- [ ] I have updated the version number in `package.json`

95
CONTRIBUTING.md Normal file
View File

@ -0,0 +1,95 @@
# Contributing to MCP Shrimp Task Manager
First off, thank you for considering contributing to MCP Shrimp Task Manager! It's people like you that make this such a great tool. We welcome any and all contributions.
## Code of Conduct
This project and everyone participating in it is governed by a simple code of conduct: be respectful. We are committed to providing a friendly, safe and welcoming environment for all.
## How Can I Contribute?
There are many ways to contribute, from writing tutorials or blog posts, improving the documentation, submitting bug reports and feature requests or writing code which can be incorporated into the main project.
### Reporting Bugs
If you find a bug, you can either open an issue on our [GitHub repository](https://github.com/cjo4m06/mcp-shrimp-task-manager/issues) or submit a direct pull request with the fix. For more complex bugs that require discussion, opening an issue first is recommended.
Here is a template you can use if you choose to open an issue:
```markdown
**Describe the bug**
A clear and concise description of what the bug is.
**To Reproduce**
Steps to reproduce the behavior:
1. **Configuration**: Detail your `mcp.json` or `.env` configuration.
2. **Tool Call**: The exact tool call you made (e.g., `plan_task ...`).
3. **Context**: Any relevant context, like the state of the `tasks.json` file.
4. **Observed Behavior**: The error or incorrect output.
**Expected behavior**
A clear and concise description of what you expected to happen.
**Environment (please complete the following information):**
- **OS**: [e.g. macOS, Linux, Windows]
- **Client**: [e.g. Cursor, Claude Code, custom script]
- **MCP Shrimp Task Manager Version**: [e.g. 1.0.19]
**Additional context**
Add any other logs or context about the problem here.
```
### Suggesting Enhancements
If you have an idea for a new feature or an enhancement to an existing one, you can either open an issue on our [GitHub repository](https://github.com/cjo4m06/mcp-shrimp-task-manager/issues) to discuss it, or submit a direct pull request for straightforward additions. For significant features that may impact the architecture, it's advisable to open an issue for discussion beforehand.
Here is a template you can use if you choose to open an issue:
```markdown
**Is your feature request related to a problem? Please describe.**
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
**Describe the solution you'd like**
A clear and concise description of what you want to happen. This could include new tools, or changes to existing tool behaviors.
**Describe alternatives you've considered**
A clear and concise description of any alternative solutions or features you've considered.
**Additional context**
Add any other context or mock-ups about the feature request here.
```
### Your First Code Contribution
Unsure where to begin contributing to MCP Shrimp Task Manager? You can start by looking through these `good-first-issue` and `help-wanted` issues:
- [Good first issues](https://github.com/cjo4m06/mcp-shrimp-task-manager/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) - issues which should only require a few lines of code, and a test or two.
- [Help wanted issues](https://github.com/cjo4m06/mcp-shrimp-task-manager/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) - issues which should be a bit more involved than `good-first-issue` issues.
## Contribution Workflow and Pull Requests
Since this project maintains a clean commit history and a focused development pace, we follow a strict contribution workflow. All contributions are made via pull requests from forked repositories.
1. **Fork & Clone**: Fork the repository on GitHub, then clone it to your local machine.
2. **Install Dependencies**: Install the dependencies by running `npm install` in the project's root directory.
3. **Branch**: Create a new branch for your work, following the convention `feat/your-feature-name` for features or `fix/your-bug-fix` for bug fixes. For example: `git checkout -b feat/new-research-tool`.
4. **Make your changes**: Run the build command `npm run build` to make sure everything compiles correctly.
5. **Focus Your Work**: Each pull request should address a single issue or feature. Please do not mix bug fixes and new features in the same PR. This focus helps streamline the review process and makes it easier to track changes.
6. **Commit**: Commit your changes with a descriptive message that follows the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format.
7. **Push**: Push your branch to your forked repository.
8. **Open a Pull Request**:
- Navigate to the [main repository](https://github.com/cjo4m06/mcp-shrimp-task-manager/pulls) and open a new pull request from your forked branch.
- GitHub will automatically populate the PR description with our template. Please fill it out as completely as possible. The more context you provide, the faster your PR can be reviewed.
9. **Code Review**: The repository owner (`@cjo4m06`) will review your pull request. They may ask for changes or clarification.
10. **Merge**: Once the PR is approved, the owner will merge it into the `main` branch. We do not allow contributors to merge their own PRs.
As a part of the review process, please ensure your PR includes:
- Corresponding changes to documentation (`README.md`).
- Updates to the `CHANGELOG.md`.
- An increase in the version number in `package.json` following [SemVer](http://semver.org/).
### Testing
As noted in PR [#35](https://github.com/cjo4m06/mcp-shrimp-task-manager/pull/35), we are in the process of migrating our testing framework to [Vitest](https://vitest.dev/). For any new code contributions, please include tests written with Vitest. This will help us accelerate the transition and ensure the quality of our codebase.
Thank you for your contribution!

251
shrimp-rules.en.md Normal file
View File

@ -0,0 +1,251 @@
# Development Guidelines
This document provides the dedicated specifications for AI Agents performing development tasks in the `mcp-shrimp-task-manager` project.
## 1. Project Overview
- **Project Name**: `mcp-shrimp-task-manager`
- **Purpose**: A task management tool designed for AI Agents, emphasizing chain-of-thought, reflection, and style consistency. It converts natural language into structured development tasks with dependency tracking and iterative refinement capabilities.
- **Technology Stack**:
- **Primary Language**: TypeScript
- **Runtime Environment**: Node.js (ES Module)
- **Main Frameworks/Libraries**: Express.js (for potential API or WebGUI), Zod (for data validation)
- **Package Manager**: npm
- **Core Features**:
- Natural language task parsing
- Structured task generation and management
- Task dependency tracking
- Task execution and verification assistance
- Integration with AI Agent's thought processes
## 2. Project Architecture
- **Main Source Code Directory**: `src/`
- `src/index.ts`: Main application entry point or module export point. **Modifications to this file require careful impact assessment.**
- `src/utils/`: General-purpose utility functions.
- `src/types/`: TypeScript type definitions. **When adding or modifying types, ensure consistency with Zod schemas (if applicable).**
- `src/tools/`: Project-specific tools or modules for integration with external services.
- `src/models/`: Data model definitions (potentially related to Zod schemas).
- `src/prompts/`: Prompt templates related to AI interaction. **Modifying or adding prompts requires consideration of the potential impact on AI Agent behavior.**
- `src/public/`: WebGUI or other static assets.
- `src/tests/`: Unit and integration tests.
- **Compiled Output Directory**: `dist/` (This directory is auto-generated by `tsc`. **Do not manually modify its contents.**).
- **Configuration Files**:
- `package.json`: Project dependencies and scripts. **After adding dependencies, you must run `npm install`.**
- `tsconfig.json`: TypeScript compilation settings. **Do not modify the `"strict": true` setting unless absolutely necessary.**
- `.env.example` & `.env`: Environment variable settings. **Sensitive information must not be committed to version control.**
- **Documentation**:
- `README.md`: Main project documentation.
- `docs/`: May contain more detailed architecture, API documentation, etc.
- `CHANGELOG.md`: Record of version changes. **Must be updated before releasing a new version.**
- `data/WebGUI.md`: Contains the link to the Task Manager UI.
## 3. Code Specifications
### 3.1. Naming Conventions
- **Variables and Functions**: Use camelCase.
- _Do_: `const taskName = "example"; function processTask() {}`
- _Don't_: `const Task_Name = "example"; function Process_Task() {}`
- **Classes and Interfaces**: Use PascalCase.
- _Do_: `class TaskManager {}; interface ITaskOptions {}`
- _Don't_: `class taskManager {}; interface iTaskOptions {}`
- **File Names**: Use camelCase or kebab-case for `.ts` files.
- _Do_: `taskProcessor.ts`, `task-utils.ts`
- _Don't_: `TaskProcessor.ts`, `task_utils.ts`
- **Constants**: Use UPPER_SNAKE_CASE.
- _Do_: `const MAX_RETRIES = 3;`
- _Don't_: `const maxRetries = 3;`
### 3.2. Formatting Requirements
- **Indentation**: Use 2 spaces for indentation. **Do not use Tab characters.**
- **Semicolons**: Statements must end with a semicolon.
- **Quotes**: Prefer single quotes (`'`) for strings, unless the string itself contains single quotes.
- _Do_: `const message = 'Hello World'; const complex = "It\\'s complex";`
- _Don't_: `const message = "Hello World";`
- **Max Line Length**: Recommended not to exceed 120 characters.
- **Comments**:
- Use `//` for single-line comments.
- Use `/* ... */` for multi-line comments.
- Use JSDoc-style comments for public functions, classes, and methods.
- _Do_:
```typescript
/**
* Processes a given task.
* @param taskId The ID of the task to process.
* @returns True if successful, false otherwise.
*/
function processTaskById(taskId: string): boolean {
// implementation
return true;
}
```
### 3.3. TypeScript Specific Guidelines
- **Type Annotations**: All function parameters, return values, and variable declarations should have explicit type annotations. **The use of the `any` type is forbidden, except in very specific and unavoidable circumstances, which require a comment explaining the reason.**
- _Do_: `function greet(name: string): string { return \`Hello, ${name}\`; }`
- _Don't_: `function greet(name): any { return "Hello, " + name; }`
- **Interfaces vs. Type Aliases**: Prefer Interfaces for defining object shapes and Type Aliases for defining union types, tuples, or other complex types.
- **ES Modules**: Use `import` and `export` syntax.
- _Do_: `import { Task } from './models/task'; export class TaskService {}`
- _Don't_: `const Task = require('./models/task'); module.exports = TaskService;`
- **Strict Mode**: The project has `"strict": true` enabled. All TypeScript strict mode errors must be resolved.
## 4. Feature Implementation Guidelines
### 4.1. General Principles
- **Single Responsibility Principle (SRP)**: Each function and class should be responsible for only one piece of functionality.
- **Keep It Simple, Stupid (KISS)**: Avoid overly complex solutions.
- **Don't Repeat Yourself (DRY)**: Extract common logic into reusable functions or classes, stored in `src/utils/` or relevant modules.
- **Error Handling**:
- Use `try...catch` to handle expected errors.
- Provide clear error messages for critical operations.
- Consider using custom error classes to provide richer error information.
- **Logging**:
- Add logging for critical operations, error handling, and important state changes.
- Consider using structured logging.
- **Do not log sensitive information (e.g., passwords, API Keys).**
### 4.2. Zod Usage
- Data structures defined in `src/models/` or `src/types/` should primarily use Zod schemas for definition and validation.
- Zod schemas should be kept in sync with TypeScript types. You can use `z.infer<typeof schema>` to generate types.
- _Do_:
```typescript
import { z } from "zod";
export const TaskSchema = z.object({
id: z.string().uuid(),
name: z.string().min(1),
description: z.string().optional(),
});
export type Task = z.infer<typeof TaskSchema>;
```
### 4.3. Express.js Usage (if API/WebGUI exists)
- Route definitions should be clear and follow RESTful principles (for APIs).
- Middleware should be effectively organized, e.g., error handling middleware, logging middleware.
- All external input (request parameters, body, query) **must** be validated using Zod or a similar mechanism.
## 5. Framework/Plugin/Third-Party Library Usage Guidelines
- **Adding Dependencies**:
- **Must** first evaluate the necessity, maintenance status, and security of the dependency.
- Use `npm install <package-name>` (for runtime dependencies) or `npm install --save-dev <package-name>` (for development dependencies).
- **Must** specify a clear version range in `package.json` (e.g., `^1.2.3` or `~1.2.3`), avoid using `*`.
- **Updating Dependencies**: Regularly check and update dependencies to the latest stable version to get security patches and new features. Assess potential breaking changes before updating.
- **Removing Dependencies**: If a dependency is no longer needed, remove it using `npm uninstall <package-name>` and remove related references from the code.
## 6. Workflow Guidelines
### 6.1. Development Process
1. **Understand the Task**: Carefully read the task description, requirements, and acceptance criteria.
2. **Branch Management**: Create a new feature branch from the latest `main` (or `develop`) branch. Branch names should be concise and clear, e.g., `feature/add-task-editing` or `fix/login-bug`.
3. **Coding and Testing**:
- Code according to these guidelines.
- **Must** write unit tests (stored in `src/tests/`) for new features or bug fixes.
- Run `npm run build` to ensure the code compiles successfully.
- Run `npm run dev` or `npm run start` locally for testing.
4. **Code Committing**:
- Git commit messages should follow the Conventional Commits specification (e.g., `feat: add user authentication`, `fix: resolve issue with task sorting`).
- **Do not commit code with `console.log` or other debugging messages to the main branches.**
5. **Pull Request (PR)**:
- Push the feature branch to the remote repository and create a Pull Request to the `main` (or `develop`) branch.
- The PR description should clearly explain the changes and their purpose.
6. **Code Review**: Wait for other developers or AI Agents to conduct a code review.
7. **Merge and Deploy**: After the code review is passed, merge the PR. The deployment process follows the project setup.
### 6.2. Version Control (Git)
- **Main Branches**:
- `main`: Represents the stable and deployable product version.
- `develop` (if used): Represents the latest in-development version.
- **Commit Frequency**: Small, frequent, and meaningful commits are recommended.
- **Resolving Conflicts**: When merging or rebasing branches, if conflicts occur, they **must** be resolved carefully to ensure the correctness and integrity of the code.
### 6.3. CHANGELOG Updates
- Before releasing a new version, `CHANGELOG.md` **must** be updated.
- The log should include the version number, release date, and a list of new features, bug fixes, and breaking changes.
## 7. Key File Interaction Guidelines
- **Modifying `src/types/` or `src/models/` (especially Zod schemas)**:
- **Must** check and update all files that reference these types or schemas to ensure type consistency.
- **Must** re-run relevant tests.
- **Modifying `src/index.ts`**:
- If the module's exported API is changed, **must** check all dependent projects or files and make necessary adjustments.
- **Modifying `package.json` (especially `dependencies` or `scripts`)**:
- **Must** notify team members or relevant AI Agents to run `npm install`.
- If `scripts` are modified, ensure the CI/CD process (if any) is updated accordingly.
- **Modifying `.env.example`**:
- **Must** synchronously update `.env` files in all development environments and notify team members.
- **Modifying `README.md` or documents in `docs/`**:
- If changes involve core features or usage, **must** ensure the accuracy and timeliness of the documentation.
## 8. AI Decision-Making Guidelines
### 8.1. Handling Vague Requests
- When receiving a vague development instruction (e.g., "optimize the task list display"):
1. **Attempt to Clarify**: If possible, request more specific details or expected outcomes from the user or task initiator.
2. **Analyze Context**: Check related code (`src/`), existing UI (if any), and relevant issues (if any) to infer intent.
3. **Propose Solutions**: Based on the analysis, propose 1-2 concrete implementation plans, explaining their pros, cons, and estimated effort.
4. **Wait for Confirmation**: Do not proceed with large-scale code modifications until clear instructions are received.
### 8.2. Error/Exception Handling Strategy
- **Priorities**:
1. **User Experience**: Avoid program crashes and provide friendly error messages.
2. **Data Integrity**: Ensure errors do not lead to data corruption or inconsistency.
3. **System Stability**: Log detailed error information for troubleshooting.
- **Choices**:
- For predictable errors (e.g., invalid user input), handle them within the operation's context and provide feedback.
- For unexpected system errors, catch, log, and potentially re-throw or trigger a global error handling mechanism.
### 8.3. Dependency Selection
- When needing to introduce a new third-party library:
1. **Check Existing**: Verify if a similar library that meets the requirements already exists in the project.
2. **Evaluate Options**:
- **Activity and Community Support**: Choose well-maintained libraries with active communities.
- **Lightweight**: Avoid introducing libraries that are too large or have redundant features.
- **Security**: Check for known security vulnerabilities.
- **License**: Ensure compatibility with the project's license.
3. **Minimization Principle**: Only introduce libraries that are genuinely needed.
## 9. Prohibitions
- **Do not directly modify any files in the `dist/` directory.** This directory contains compiled output.
- **Do not assume a new dependency is available without running `npm install`.**
- **Do not commit untested or unfinished code directly to the main branches (`main` or `develop`).** Use feature branches.
- **Do not commit code containing API Keys, passwords, or other sensitive information to the version control system.** Use the `.env` file for such information.
- **Do not make major changes to the core architecture or public API without notification and approval.**
- **Do not ignore TypeScript type errors.** All errors reported by `tsc` must be resolved.
- **Do not use the `any` type without a very good reason and a corresponding comment.**
- **Do not leave large amounts of `console.log` or other temporary debugging code in the codebase.**
- **Do not release a new version without updating `CHANGELOG.md`.**
- **Do not introduce third-party libraries incompatible with the project's MIT license.**
## 10. Updating This Guideline Document (`shrimp-rules.md`)
- When the project's tech stack, core architecture, main workflow, or important guidelines change, this document **must** be updated accordingly.
- Update requests should clearly specify the sections and content to be changed.
- If a vague "update rules" instruction is received, the AI Agent **must**:
1. Autonomously analyze the current codebase for changes (e.g., `git diff`, recent commits).
2. Compare the existing `shrimp-rules.md` with the project's current state to find inconsistent or outdated rules.
3. List the inferred update points and their justifications in the `process_thought` stage.
4. Propose specific modifications or directly edit this document.
5. **Strictly prohibited** to seek clarification from the user on a vague request before performing an autonomous analysis.
---
This development guide aims to ensure that AI Agents can participate in the development of the `mcp-shrimp-task-manager` project efficiently, consistently, and securely.