GitHub Projects

Why this page has no code-host line

GitHub Projects is the tool pair grew up on, and that shows in the configuration below: it declares nothing about where your code lives. The board, the issues, the repository, the branches, the pull requests and the reviews are all the same product, so the two halves of pair's work (moving a story across a board and opening the PR that closes it) land on one tool and one credential.

That coincidence is precisely what hid pair's PM-tool/code-host conflation for a while: on GitHub both jobs have the same answer, so nothing ever contradicted it (the PM tools overview tells that story in full, and ADR-018 is the record). What matters on this page is the default it landed on: code-host is optional, and omitting it means the code host is the PM tool. See Code host vs PM tool for the routing rule.

So the reason you will not find a code-host line in the configuration below is not that it was left out: it is the decision. A GitHub Projects project is the zero-configuration path, and it behaves today exactly as it did before the split existed.

The second thing worth knowing before you configure anything is that an issue and a board item are two different objects on GitHub.

Adding an issue to a project is its own API call, and an issue that is open, assigned and green but never added to the board is invisible in the assignee-filtered view your team actually reads: this happened here, to real issues, and no gate caught it.

GitHub is therefore the one adapter with explicit board membership: pair adds the item to the board, reads back to confirm it landed, and only then writes the status field (per the pm-adapter-visibility-contract decision record, whose contract makes that ordering a requirement for the adapters with explicit board membership (GitHub is the one that needs it) rather than a rule each skill had to remember).

That is why the setup below asks for a project board, not just a repository.

Configuration

Add these lines to .pair/adoption/tech/way-of-working.md:

- GitHub Projects is adopted for project management, using Kanban as the workflow methodology.
  The project is <your-project-name> under the GitHub organization <your-org>.
  See `.pair/knowledge/guidelines/collaboration/project-management-tool/README.md` for usage.
  Use #github MCP to access GitHub Projects, boards, and issues.

Prerequisites

• GitHub account with repository access
• GitHub MCP Server configured for your AI assistant (provides API access to GitHub Projects)
• A GitHub Projects board created for your repository

API Access: MCP + gh CLI Fallback

pair uses the GitHub MCP Server as the primary way to interact with GitHub Projects. MCP provides structured tool calls for:

• Creating and updating issues from process skills
• Managing project board status transitions via GraphQL
• Querying issue state for /pair-next recommendations

When the MCP server is not available (e.g., in CI environments or tools without MCP support), pair falls back to the gh CLI for the same operations. The gh CLI provides equivalent functionality via gh issue, gh api graphql, and gh pr commands.

Primary:   GitHub MCP Server (structured tool calls)
Fallback:  gh CLI (gh issue create, gh api graphql, gh pr create)

Install the GitHub MCP Server following your AI tool's MCP setup guide. If using gh as fallback, ensure it is authenticated (gh auth login).

Mapping Model

pair maps its work hierarchy to GitHub concepts:

pair                    GitHub Projects
────                    ───────────────
Initiative          →   Issue (label: "initiative")
Epic                →   Issue (label: "epic")
User Story          →   Issue (label: "user story")
Task                →   Checklist item in story issue body

How It Works

• Initiatives, epics, and stories are all GitHub Issues, differentiated by labels
• Tasks are checkbox items (- [ ] **T-1**: description) in the story issue body, not separate issues
• Status tracking uses GitHub Projects board columns (Todo, In Progress, Done)
• Hierarchy is maintained through issue references and sub-issue relationships

Status Transitions

Internally, pair skills always think in canonical macrostates (Draft, Ready, In Progress, Review, Done) and resolve them to your actual board columns via the optional State Mapping section in way-of-working.md, omitted by default when your columns already match the canonical names.

pair updates status via GitHub Projects GraphQL API:

Labels

pair uses these labels to identify work item types:

First-Run Example

After configuring way-of-working.md, run a process skill:

/pair-process-plan-stories #42    # break epic #42 into stories

Expected output:

STORIES CREATED:
├── #101: As a user, I want to sign up so that I can access the platform
├── #102: As a user, I want to log in so that I can see my dashboard
├── #103: As a user, I want to reset my password so that I can recover access
└── Epic #42: 3 stories created, all set to "Todo"

pair creates GitHub Issues with the user story label, adds them to your project board in the "Todo" column, and links them to the parent epic.

Verifying the Setup

Check that everything worked:

1. Open your GitHub repository's Projects tab
2. Verify the new issues appear on the board in "Todo"
3. Each issue should have the user story label and reference the epic

Related

• PM Tools overview: choosing the right tool
• Filesystem: zero-PM-dependency alternative (backlog in your repo; still declares a code-host)
• Linear: dedicated PM tool option
• Canonical States & State Mapping: how pair resolves board columns to macrostates