Project Management Tools

How pair integrates with project management tools to manage stories, tasks, and initiatives automatically.

pair manages work items for you. When you run process skills like /pair-process-implement or /pair-process-plan-stories, pair reads your way-of-working.md adoption file to determine which PM tool to use, then creates and updates issues, stories, and tasks automatically.

Two fields, one rule

A backlog and a repository are not always the same product. way-of-working.md names the PM tool that holds your cards and, optionally, a code-host that holds the branches, pull requests and reviews. Leave code-host out and the PM tool is the code host too, the zero-configuration case for GitHub; declare it and pair routes card and state work to one tool and branch, PR and review work to the other, linked by plain text. The rule itself, and why it exists, is one page: Code host and PM tool. It is also why the table below has a "Hosts your code?" column.

How It Works

You choose a PM tool during project bootstrap (or change it later in way-of-working.md)
pair reads the config every time a process skill runs
pair creates and updates work items: initiatives, epics, stories, tasks: in the configured tool
Status flows automatically: completing a task updates the story, completing all stories updates the epic, and so on

You focus on the work. pair keeps the board in sync.

Supported Options

Tool	Best For	External Service	Hosts your code?
Filesystem	Solo devs, offline work, simple projects	No (PM tool)	No, declare a `code-host`
GitHub Projects	Teams already on GitHub, open source projects	Yes (free)	Yes
Linear	Teams wanting a polished PM experience	Yes (paid)	No, declare a `code-host`
Azure DevOps	Teams in the Microsoft ecosystem, enterprise requirements	Yes (free tier)	Yes (Azure Repos)

Two tools, or one? GitHub Projects and Azure DevOps host repositories, branches and pull requests themselves, so the PM tool is the code host and there is nothing extra to configure. Filesystem and Linear host no code, so those projects are split by construction: add one line (code-host: github) to way-of-working.md → ## Git Workflow, and pair routes item/state work to the PM tool and branch/PR/review work to the code host, cross-linking the two with a Refs: <issue-id> line in the PR body. See Code host.

Choosing a Tool

Starting solo or want no PM tool account? Use Filesystem, everything lives in your repo as Markdown files (plus a code-host for the PRs).
Team on GitHub? Use GitHub Projects, issues, labels, and project boards you already know, and one tool for everything.
Want a dedicated PM tool? Use Linear, clean UI, fast workflows, great API (plus a code-host for the PRs).
Microsoft shop or enterprise? Use Azure DevOps: Boards work items, branch policies, and pipelines in one place.

You can switch between tools at any time by updating way-of-working.md. Your adoption files and Knowledge Base stay the same.

The Mapping Model

pair uses a consistent hierarchy regardless of tool:

Initiative (strategic goal)
└── Epic (feature set)
    └── User Story (deliverable increment)
        └── Task (implementation step)

Each PM tool maps this hierarchy to its own concepts:

pair Concept	Filesystem	GitHub Projects	Linear	Azure DevOps
Initiative	Markdown file	Issue + label	Project	Epic
Epic	Markdown file	Issue + label	Issue (parent)	Feature
User Story	Markdown file	Issue + label	Issue (sub-issue)	Product Backlog Item
Task	Checklist in story	Checklist in issue body	Checklist in issue	Task (child work item)

Configuration

All PM tool configuration lives in one place: .pair/adoption/tech/way-of-working.md. Each tool guide shows the exact configuration lines to add.

AI Coding Tools: set up your AI assistant
Process Lifecycle: the full development lifecycle
Adoption Files concept: how adoption files work

Tool not listed? See Add a custom PM tool.