​
Contributing to Task Master

Thank you for your interest in contributing to Task Master! We’re excited to work with you and appreciate your help in making this project better. 🚀

​
🤝 Our Collaborative Approach

We’re a PR-friendly team that values collaboration:

  • ✅ We review PRs quickly - Usually within hours, not days
  • ✅ We’re super reactive - Expect fast feedback and engagement
  • ✅ We sometimes take over PRs - If your contribution is valuable but needs cleanup, we might jump in to help finish it
  • ✅ We’re open to all contributions - From bug fixes to major features

We don’t mind AI-generated code, but we do expect you to:

  • ✅ Review and understand what the AI generated
  • ✅ Test the code thoroughly before submitting
  • ✅ Ensure it’s well-written and follows our patterns
  • ❌ Don’t submit “AI slop” - untested, unreviewed AI output

Why this matters: We spend significant time reviewing PRs. Help us help you by submitting quality contributions that save everyone time!

​
🚀 Quick Start for Contributors

​
1. Fork and Clone

git clone https://github.com/YOUR_USERNAME/claude-task-master.git
cd claude-task-master
npm install

​
2. Create a Feature Branch

Important: Always target the next branch, not main:

git checkout next
git pull origin next
git checkout -b feature/your-feature-name

​
3. Make Your Changes

Follow our development guidelines below.

​
4. Test Everything Yourself

Before submitting your PR, ensure:

# Run all tests
npm test

# Check formatting
npm run format-check

# Fix formatting if needed
npm run format

​
5. Create a Changeset

Required for most changes:

npm run changeset

See the Changeset Guidelines below for details.

​
6. Submit Your PR

  • Target the next branch
  • Write a clear description
  • Reference any related issues

​
📋 Development Guidelines

​
Branch Strategy

  • main: Production-ready code
  • next: Development branch - target this for PRs
  • Feature branches: feature/description or fix/description

​
Code Quality Standards

  1. Write tests for new functionality
  2. Follow existing patterns in the codebase
  3. Add JSDoc comments for functions
  4. Keep functions focused and single-purpose

​
Testing Requirements

Your PR must pass all CI checks:

  • ✅ Unit tests: npm test
  • ✅ Format check: npm run format-check

Test your changes locally first - this saves review time and shows you care about quality.

​
📦 Changeset Guidelines

We use Changesets to manage versioning and generate changelogs.

​
When to Create a Changeset

Always create a changeset for:

  • ✅ New features
  • ✅ Bug fixes
  • ✅ Breaking changes
  • ✅ Performance improvements
  • ✅ User-facing documentation updates
  • ✅ Dependency updates that affect functionality

Skip changesets for:

  • ❌ Internal documentation only
  • ❌ Test-only changes
  • ❌ Code formatting/linting
  • ❌ Development tooling that doesn’t affect users

​
How to Create a Changeset

  1. After making your changes:

    npm run changeset

  2. Choose the bump type:

    • Major: Breaking changes
    • Minor: New features
    • Patch: Bug fixes, docs, performance improvements

  3. Write a clear summary:

    Add support for custom AI models in MCP configuration

  4. Commit the changeset file with your changes:

    git add .changeset/*.md
git commit -m "feat: add custom AI model support"

​
Changeset vs Git Commit Messages

  • Changeset summary: User-facing, goes in CHANGELOG.md
  • Git commit: Developer-facing, explains the technical change

Example:

# Changeset summary (user-facing)
"Add support for custom Ollama models"

# Git commit message (developer-facing)
"feat(models): implement custom Ollama model validation

- Add model validation for custom Ollama endpoints
- Update configuration schema to support custom models
- Add tests for new validation logic"

​
🔧 Development Setup

​
Prerequisites

  • Node.js 18+
  • npm or yarn

​
Environment Setup

  1. Copy environment template:

    cp .env.example .env

  2. Add your API keys (for testing AI features):

    ANTHROPIC_API_KEY=your_key_here
OPENAI_API_KEY=your_key_here
# Add others as needed

​
Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run with coverage
npm run test:coverage

# Run E2E tests
npm run test:e2e

​
Code Formatting

We use Prettier for consistent formatting:

# Check formatting
npm run format-check

# Fix formatting
npm run format

​
📝 PR Guidelines

​
Before Submitting

  • Target the next branch
  • Test everything locally
  • Run the full test suite
  • Check code formatting
  • Create a changeset (if needed)
  • Re-read your changes - ensure they’re clean and well-thought-out

​
PR Description Template

## Description

Brief description of what this PR does.

## Type of Change

- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing

- [ ] I have tested this locally
- [ ] All existing tests pass
- [ ] I have added tests for new functionality

## Changeset

- [ ] I have created a changeset (or this change doesn't need one)

## Additional Notes

Any additional context or notes for reviewers.

​
What We Look For

✅ Good PRs:

  • Clear, focused changes
  • Comprehensive testing
  • Good commit messages
  • Proper changeset (when needed)
  • Self-reviewed code

❌ Avoid:

  • Massive PRs that change everything
  • Untested code
  • Formatting issues
  • Missing changesets for user-facing changes
  • AI-generated code that wasn’t reviewed

​
🏗️ Project Structure

claude-task-master/
├── bin/                    # CLI executables
├── mcp-server/            # MCP server implementation
├── scripts/               # Core task management logic
├── src/                   # Shared utilities and providers and well refactored code (we are slowly moving everything here)
├── tests/                 # Test files
├── docs/                  # Documentation
└── .cursor/               # Cursor IDE rules and configuration
└── assets/							   # Assets like rules and configuration for all IDEs

​
Key Areas for Contribution

  • CLI Commands: scripts/modules/commands.js
  • MCP Tools: mcp-server/src/tools/
  • Core Logic: scripts/modules/task-manager/
  • AI Providers: src/ai-providers/
  • Tests: tests/

​
🐛 Reporting Issues

​
Bug Reports

Include:

  • Task Master version
  • Node.js version
  • Operating system
  • Steps to reproduce
  • Expected vs actual behavior
  • Error messages/logs

​
Feature Requests

Include:

  • Clear description of the feature
  • Use case/motivation
  • Proposed implementation (if you have ideas)
  • Willingness to contribute

​
💬 Getting Help

​
📄 License

By contributing, you agree that your contributions will be licensed under the same license as the project (MIT with Commons Clause).

Thank you for contributing to Task Master! 🎉

Your contributions help make AI-driven development more accessible and efficient for everyone.