Contributing Guide

July 17, 2025 · View on GitHub

Thank you for your interest in contributing to the Claude PM Framework! This guide provides everything you need to know about contributing code, documentation, and ideas to the project.

Code of Conduct

By participating in this project, you agree to abide by our Code of Conduct:

Be respectful of differing viewpoints and experiences
Be constructive in your feedback and criticism
Be inclusive and welcoming to all contributors
Be professional in all interactions

Getting Started

1. Fork and Clone

# Fork the repository on GitHub, then:
git clone https://github.com/YOUR_USERNAME/claude-multiagent-pm.git
cd claude-multiagent-pm
git remote add upstream https://github.com/Bobjayafam/claude-multiagent-pm.git

2. Set Up Development Environment

Follow the Development Setup Guide to configure your environment.

3. Create a Branch

# Update main branch
git checkout main
git pull upstream main

# Create feature branch
git checkout -b feature/your-feature-name
# Or for bugs: git checkout -b fix/issue-description

Contribution Types

1. Bug Reports

Before reporting a bug:

Search existing issues to avoid duplicates
Try to reproduce with the latest version
Collect relevant information (logs, environment, steps)

Bug report template:

### Description
Clear description of the bug

### Steps to Reproduce
1. Step one
2. Step two
3. ...

### Expected Behavior
What should happen

### Actual Behavior
What actually happens

### Environment
- OS: [e.g., macOS 13.0]
- Node.js: [e.g., 18.16.0]
- Python: [e.g., 3.10.0]
- Framework Version: [e.g., 0.9.3]

### Additional Context
Any other relevant information, logs, or screenshots

2. Feature Requests

Before requesting a feature:

Check if it's already requested or in development
Consider if it aligns with project goals
Think about implementation complexity

Feature request template:

### Feature Description
Clear description of the proposed feature

### Use Case
Why is this feature needed? What problem does it solve?

### Proposed Implementation
How might this be implemented? (optional)

### Alternatives Considered
What alternatives have you considered?

### Additional Context
Any mockups, examples, or references

3. Code Contributions

Code Style

Python Code Style:

Follow PEP 8
Use type hints where appropriate
Maximum line length: 88 characters (Black default)
Use descriptive variable names

# Good
async def process_agent_task(
    agent_id: str,
    task_data: Dict[str, Any],
    timeout: Optional[int] = None
) -> AgentResult:
    """Process a task using the specified agent.
    
    Args:
        agent_id: Unique identifier for the agent
        task_data: Task parameters and context
        timeout: Optional timeout in seconds
        
    Returns:
        AgentResult containing execution status and output
        
    Raises:
        AgentNotFoundError: If agent_id is invalid
        TaskTimeoutError: If execution exceeds timeout
    """
    # Implementation

JavaScript/TypeScript Code Style:

Use ESLint and Prettier configurations
Prefer async/await over callbacks
Use meaningful function names
Document complex logic

// Good
/**
 * Initialize the framework with given configuration
 * @param {Object} config - Framework configuration
 * @returns {Promise<void>}
 */
async function initializeFramework(config) {
  validateConfig(config);
  await loadAgents();
  await setupServices();
  logger.info('Framework initialized successfully');
}

Commit Messages

Follow the Conventional Commits specification:

<type>(<scope>): <subject>

<body>

<footer>

Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting, etc.)
refactor: Code refactoring
perf: Performance improvements
test: Test additions or fixes
build: Build system changes
ci: CI/CD changes
chore: Other changes

Examples:

# Feature
git commit -m "feat(agents): Add performance monitoring agent"

# Bug fix
git commit -m "fix(cli): Resolve path issues on Windows"

# Documentation
git commit -m "docs(api): Update agent registry documentation"

# With body
git commit -m "feat(cache): Implement shared prompt cache

- Add LRU cache with 99.7% performance improvement
- Implement automatic cache invalidation
- Add cache metrics and monitoring

Closes #123"

Pull Request Process

Before submitting:
- Ensure all tests pass
- Update documentation
- Add tests for new features
- Run linting and formatting
PR title format:
```
<type>(<scope>): <description>
```

PR description template:

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] Tests added/updated
- [ ] Breaking changes documented

## Related Issues
Closes #123
Related to #456

4. Documentation Contributions

Documentation Style

Write in clear, concise English
Use active voice
Include code examples
Keep paragraphs short
Use proper markdown formatting

Documentation Structure

# Page Title

Brief introduction paragraph explaining the topic.

## Main Section

### Subsection

Content with **emphasis** where needed.

```python
# Code example
def example():
    pass