Code Host vs PM Tool

How pair works when your backlog and your code live in different tools, the optional code-host override, the routing rule, and the Linear + GitHub reference case.

pair distinguishes two tools that are usually the same one:

the PM tool: where the backlog lives (initiatives, epics, stories, state)
the code host: where the code lives (repositories, branches, pull requests, reviews)

On GitHub or Azure DevOps these coincide, so you configure nothing. On Linear, Jira or the filesystem tracker they cannot: those tools host no code. That is what the optional code-host field is for.

Zero Configuration by Default

Omit code-host and the code host is your PM tool. Behavior is identical to a single-tool project: there is nothing to migrate and nothing to declare.

Declaring the same tool in both places is treated exactly as omitting it: single-tool, no dual-write.

One exception: a PM tool that hosts no code. linear, jira and filesystem own no repositories, branches or pull requests, so an omitted code-host has nothing to fall back to. On those tools pair asks for code-host at setup, and a PR operation without it HALTs with a setup pointer rather than resolving to a tool that cannot host a PR.

PM tool	Hosts code?	`code-host`
GitHub Projects, Azure DevOps	Yes	Omit it
Linear, Jira, `filesystem`	No	Declare it

Declaring a Split Setup

Add a ## Git Workflow section to .pair/adoption/tech/way-of-working.md:

## Git Workflow
 
- `code-host`: `github` - repository `acme/platform`.
- `base-branch`: `main`.

Field	Default	Meaning
`code-host`	(the PM tool)	The tool hosting repositories, branches and pull requests
`base-branch`	`main`	The branch PRs target and feature branches are cut from

The Routing Rule

Skills never assume the two tools coincide: they route by field. The rule lives in one place (.pair/knowledge/guidelines/technical-standards/ai-development/skill-conventions/way-of-working-pm-resolution.md), so no skill re-derives it:

Operation	Goes to
Create/update an issue, read its hierarchy, labels, state (`/pair-capability-classify` reading a card)	PM tool
State transitions (Ready, In Progress, Review, Done)	PM tool
Close an issue, cascade to its parents	PM tool
Branches, pushes, pull request create/update/read	Code host
PR labels and required checks (the CI gate)	Code host
Code review submission and PR merge	Code host
Open-PR detection (`/pair-next` row 6)	Code host
Classification matrix + chromatic tags	Whichever side the target is, refinement writes the card (PM tool), review writes the PR (code host)

Two invariants follow:

State transitions always happen on the PM tool. PR states (draft/ready/approved/merged) live on the code host and are never mirrored onto the board: no state is duplicated.
The pair review check registers on the code host only, because that is where it gates the merge. The board sees the outcome through the linked PR.

Cross-Linking (No Native Integration Required)

The two tools are linked by text convention in both directions. Native integrations (e.g. Linear's own GitHub app) may be enabled, but no skill depends on one:

PR → issue: the PR body carries Refs: <issue-id> with the PM tool's own identifier, Refs: ENG-412 on Linear, Refs: #412 on GitHub, Refs: PROJ-412 on Jira. /pair-process-review reads this to find the story from a PR.
Issue → PR: /pair-capability-publish-pr posts the PR URL back onto the issue as soon as the PR exists, as a comment (or the tool's link field), never as a body edit, so your story's acceptance criteria and task breakdown are untouched.

If the issue id can't be resolved when writing the back-link, the PR is still created: you get a warning with a manual-link instruction, never a failed publish.

Reference Case: Linear + GitHub

- Linear is adopted for project management.
  Team: `ENG`. Access: Linear MCP Server.
 
## Git Workflow
 
- `code-host`: `github` - repository `acme/platform`.
- `base-branch`: `main`.

The cycle then runs across both tools:

/pair-process-refine-story    → story refined on Linear (ENG-412 → Todo)
/pair-process-implement       → ENG-412 → In Progress on Linear; branch on GitHub
/pair-capability-publish-pr   → PR on GitHub with "Refs: ENG-412";
                                PR URL commented on ENG-412; ENG-412 → In Review
/pair-process-review          → review + merge on GitHub; ENG-412 → Done on Linear

Failure Modes

Situation	Behavior
`code-host` declared but unreachable/unauthenticated	Publish HALTs with a setup pointer. PM-side work already done is not rolled back
`code-host` omitted on a PM tool that hosts no code (Linear, Jira, `filesystem`)	HALT before any PR operation, with a pointer to `## Git Workflow`. Item/state work keeps working
Existing Linear/Jira/`filesystem` project upgrading pair	One-time step: declare `code-host` once (or re-run `/pair-capability-setup-pm`, which backfills it). Until then PR operations HALT as above; repository-hosting trackers are unaffected
Issue id not found when linking back	PR is still created; warning with a manual-link instruction
Back-link re-run (a fix round, or recovery from a HALT)	The existing comment is detected and not re-posted, exactly one `PR: <url>` comment per item
Same tool in both fields	Treated exactly as omitted: no dual-write, no cross-link comment. Sameness is per product: `github` ≡ `github-projects`, `azure-devops` ≡ `azure-repos`

Adoption files: where way-of-working.md lives
Canonical states: the state vocabulary the PM tool side writes
Linear: the split setup end to end
PM Tools overview: choosing a PM tool

Next: Tag-driven quality gates, the tier that scales gates and review.