Quickstart

Get up and running with pair on macOS or Linux. By the end of this guide, your project will have a Knowledge Base that gives your AI assistant full context about your development standards.

Prerequisites

• Node.js 18 or higher
• pnpm (or npm) package manager
• Terminal access

Install pair-cli

Option 1: Package Manager (Recommended)

Install pair-cli globally:

npm install -g @pair/pair-cli

Or with pnpm:

pnpm add -g @pair/pair-cli

Option 2: Manual Install (Offline)

For air-gapped environments:

1. Download the latest release from GitHub Releases
2. Extract the pair-cli-manual-vX.Y.Z.zip file
3. Run directly from the extracted folder

Verify Installation

pair-cli --version

Expected output:

pair-cli vX.Y.Z

Install the Knowledge Base

Navigate to your project root and run:

pair-cli install

This creates the .pair/ folder with documentation, guidelines, how-to guides, and adoption templates. It also sets up .github/ workflows and the agent bridge pattern (AGENTS.md).

Your project now has:

.pair/
  knowledge/          # Reference material: process guides, standards
    how-to/           # 11 step-by-step guides (PRD → code review)
    guidelines/       # Technical standards (architecture, testing, code design)
    assets/           # Templates (PRD, checklist, commit, PR)
  adoption/           # Your decisions (filled in as you make them)
    product/          # PRD, subdomain definitions
    tech/             # Architecture, tech stack, infrastructure

See what pair can install in your project:

pair-cli install --list-targets

Start Using pair

Your AI assistant (Claude, Copilot, Cursor) now reads the .pair/ folder automatically. The next step is creating your adoption files — the project-specific decisions that keep every AI session aligned.

You don't write these files manually. The AI generates them interactively, asking the right questions along the way.

New Project

Run /pair-next in your AI assistant. It detects empty adoption files and walks you through:

1. PRD creation — the AI asks about your product vision, users, pain points, and features, then generates .pair/adoption/product/adopted/PRD.md
2. Bootstrap — the AI guides you through architecture, tech stack, infrastructure, and way-of-working decisions, generating adoption files in .pair/adoption/tech/adopted/
3. What comes next — /pair-next continues to suggest the right next step as your project evolves

Existing Project

For projects with an existing codebase, the AI reverse-engineers your project context — reading dependencies, config files, Git history, and code structure — then proposes adoption files for you to review and refine.

The quick version: run pair-cli install, then paste a reverse-engineering prompt into your AI assistant. It analyzes the codebase, presents findings, and asks you to confirm before generating any files.

For the full guided walkthrough with the complete prompt and step-by-step refinement process, see the Existing Project tutorial (~30 min).

Keep Your KB Up to Date

When pair publishes new guidelines, templates, or how-to improvements:

pair-cli update

This refreshes the Knowledge Base content (guidelines, how-tos, templates) while preserving your adoption files — your decisions are never overwritten.

The Development Process

pair defines a 9-step development lifecycle organized in four levels:

Each step has a how-to guide in .pair/knowledge/how-to/ that the AI follows, and a matching skill (e.g., /pair-process-implement) that automates it. Run /pair-next at any point to find out which step comes next.

Learn more about the Process Lifecycle

Choose Your Setup

The steps above work for everyone. For environment-specific configuration:

• Solo Setup — Working alone? Minimal setup, no team coordination needed.
• Team Setup — Shared standards, adoption files, and the agent bridge pattern for multi-developer teams.
• Organization Rollout — Custom KB packaging, distribution, and governance across multiple teams.

Want a guided, end-to-end walkthrough? Pick a tutorial that matches your context — solo developer (~30 min), team lead (~45 min), or enterprise architect (~60 min).

Feeling lost? Check the FAQ — it covers the most common questions about process, languages, tools, and customization.