> ## Documentation Index
> Fetch the complete documentation index at: https://taskgraph-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing to TaskGraph

> How to contribute to TaskGraph: set up the repo, run the tests, and open a pull request with a conventional-commit title.

Thank you for your interest in contributing to TaskGraph! 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

```bash theme={null}
git clone https://github.com/YOUR_USERNAME/taskgraph-ai.git
cd taskgraph-ai
npm install
```

### 2. Create a Feature Branch

Branch from `main`:

```bash theme={null}
git checkout main
git pull origin main
git checkout -b feat/your-feature-name
```

### 3. Make Your Changes

Follow our development guidelines below.

### 4. Test Everything Yourself

**Before submitting your PR**, ensure:

```bash theme={null}
# 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

Your PR **must pass all CI checks**:

* **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)

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

## Versioning

Releases are cut automatically when a PR merges to `main`, from its commit title. Don't add a changeset.

| Title prefix | Release |
| - | - |
| `feat:` | Minor (patch while TaskGraph is below 1.0) |
| `fix:`, `perf:`, `revert:` | Patch |
| `feat!:` or a `BREAKING CHANGE:` footer | Major (minor while below 1.0) |
| `chore:`, `docs:`, `ci:`, `test:` | No release |

The title becomes the release note, so write it for users: say what they get or what's fixed.

```bash theme={null}
# 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)

Merging cuts the tag and the GitHub Release, but it does not publish to npm. The release workflow only **stages** the build, and nothing is installable until a maintainer approves it:

```bash theme={null}
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
```

Approve only the newest staged version. Each one is built from its own tag, so the newest already includes every earlier fix, and approving the older ones just adds clutter. If a published version turns out to be bad, don't unpublish it. Run `npm deprecate "taskgraph-ai@<fixed-version>" "<what breaks>; upgrade to >=<fixed-version>"` to warn everyone on the older versions.

## 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**:

   ```bash theme={null}
   cp .env.example .env
   ```

2. **Sign in to Claude Code** (for testing AI features). No provider API keys are needed:

   ```bash theme={null}
   claude
   ```

### Running Tests

```bash theme={null}
# 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

We use [Biome](https://biomejs.dev) for consistent formatting:

```bash theme={null}
# 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

GitHub fills in the description from `.github/PULL_REQUEST_TEMPLATE.md`. Say what the PR does, link the issue it fixes, and give a few steps to check that it works. Releases come from the PR title (see Versioning), so there is no changeset to add.

### What We Look For

**Good PRs**:

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

**Avoid**:

* Massive PRs that change everything
* Untested code
* Formatting issues
* AI-generated code that wasn't reviewed

## Project Structure

```text theme={null}
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

All business logic belongs in `@tm/core`. `@tm/cli` and `@tm/mcp` are thin layers that call it and format the result, so don't parse, validate or transform data in them. Logic needed by both goes in `@tm/core` once.

* **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

Include:

* TaskGraph 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

* **Issues**: [GitHub Issues](https://github.com/stephennmiller/taskgraph-ai/issues)

## 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 TaskGraph!**

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.