Contributing to TaskGraph

​

Our Collaborative Approach

• 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

• 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/taskgraph-ai.git
cd taskgraph-ai
npm install

​

2. Create a Feature Branch

git checkout main
git pull origin main
git checkout -b feat/your-feature-name

​

3. Make Your Changes

​

4. Test Everything Yourself

# Run all tests
npm test

# Check formatting
npm run format-check

# Fix formatting if needed
npm run format

​

5. Submit Your PR

• Target main
• Use a conventional-commit title (see Versioning below)
• Write a clear description
• Reference any related issues

​

Development Guidelines

​

Branch Strategy

• main: The only long-lived branch. PRs target it, and releases are cut from it
• Feature branches: feat/description, fix/description, docs/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

• Tests: npm test, plus npm run test -w <package> for each package you touched (@tm/core, @tm/cli, @tm/mcp, @tm/profiles)
• Types: npm run turbo:typecheck
• Legacy JS types: npm run typecheck:root (checks the JSDoc in scripts/ against the TypeScript that calls it)
• Build: npm run build
• Format check: npm run format-check
• Unused code: npm run knip (files, exports and dependencies nothing uses)

​

Versioning

# Good
feat: research prints the answer once, rendered to fit the terminal
fix: models --setup no longer leaves the menu on screen after Ctrl-C

# Not as useful
feat: refactor research.js

​

Publishing to npm (maintainers)

npm stage list taskgraph-ai          # staged versions and their ids
npm stage approve <stage-id>         # publish one (asks for 2FA)
npm view taskgraph-ai dist-tags      # confirm `latest` is the version you expect

​

Development Setup

​

Prerequisites

• Node.js 22.13 or newer (.nvmrc pins 24 for development)
• npm (the repo is an npm workspace; npm install also points git at .githooks/, whose pre-push hook runs the format check)

​

Environment Setup

1. Copy environment template:
   cp .env.example .env
   
2. Sign in to Claude Code (for testing AI features). No provider API keys are needed:
   claude
   

​

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run with coverage
npm run test:coverage

# Run a package's tests (coverage off; npm run test:coverage -w <package>
# turns it on and checks the coverage thresholds)
npm run test -w @tm/core
npm run test -w @tm/cli
npm run test -w @tm/mcp
npm run test -w @tm/profiles

​

Code Formatting

# Check formatting
npm run format-check

# Fix formatting
npm run format

​

PR Guidelines

​

Before Submitting

• Target main with a conventional-commit title
• Test everything locally
• Run the full test suite
• Check code formatting
• Re-read your changes - ensure they’re clean and well-thought-out

​

PR Description

​

What We Look For

• Clear, focused changes
• Comprehensive testing
• Good commit messages
• Self-reviewed code

• Massive PRs that change everything
• Untested code
• Formatting issues
• AI-generated code that wasn’t reviewed

​

Project Structure

taskgraph-ai/
├── apps/
│   ├── cli/                  # @tm/cli: command-line interface
│   ├── mcp/                  # @tm/mcp: MCP server
│   └── docs/                 # Mintlify docs site (this page)
├── packages/
│   ├── tm-core/              # @tm/core: all business logic
│   ├── tm-profiles/          # @tm/profiles: shell utils, cleanup of old slash commands
│   ├── claude-code-plugin/   # Claude Code plugin: slash commands and agents (markdown only)
│   └── build-config/         # Shared build config
├── scripts/, src/, mcp-server/  # Older JavaScript, being moved into @tm/core
├── tests/                    # Older root test suite (new tests go next to the code)
├── docs/                     # Documentation
├── assets/                   # Assets installed into user projects (e.g. AGENTS.md)
└── .claude/                  # Claude Code rules (path-scoped dev conventions)

​

Where Changes Go

• Business logic: packages/tm-core/src/
• CLI commands: apps/cli/src/commands/
• MCP tools: apps/mcp/src/
• Tests: next to the code as <file>.spec.ts; integration tests in the package’s tests/integration/. Write them in TypeScript, not in the older root tests/ suite.

​

Reporting Issues

​

Bug Reports

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

​

Feature Requests

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

​

Getting Help

• Issues: GitHub Issues

​

License