Team Setup

A walkthrough for team leads adopting pair across a development team. You'll go from a solo setup to a fully configured team environment in about 45 minutes.

Prerequisites

Before starting, make sure you have:

• Completed the Your First Project tutorial (or equivalent pair experience)
• A project repository with Git initialized and pushed to GitHub
• GitHub access with permission to create Projects, labels, and issues
• A team of 2+ developers (or at least one teammate to onboard at the end)
• pair-cli installed (pair-cli --version should return a version)
• An AI coding assistant that supports Agent Skills

What you'll build

By the end of this tutorial you'll have:

• A shared Knowledge Base installed in your team's repository
• Customized guidelines that match your team's tech stack and conventions
• PM tool integration (GitHub Projects) with boards, labels, and workflows
• A way-of-working adoption file defining your team's methodology
• At least one team member onboarded and working with the same context

Estimated time

~45 minutes.

Step-by-step instructions

1. Install the Knowledge Base

If you haven't already, install pair in your project:

pair-cli install

With pair-cli: pair-cli install. With /pair-assistant (optional, Claude Code): ask for "pair in this project, first time" (how to ask).

This creates the .pair/ directory with the default Knowledge Base, bridge files (AGENTS.md, .claude/, .github/copilot/), and empty adoption templates.

2. Run bootstrap for your team context

Start your AI assistant and run (/pair-next would suggest this on a fresh project):

/pair-process-bootstrap

In your assistant: the command above. With /pair-assistant (optional, Claude Code): ask it to adopt the project; it hands off to /pair-process-bootstrap (how to ask).

During bootstrap, make team-relevant choices:

• Team size: specify your actual team size
• Methodology: choose Scrum, Kanban, or Lean depending on your team's style
• PM tool: select GitHub Projects (the default) or your team's preferred tool
• Quality gates: define what checks run before every commit

Bootstrap records all decisions in .pair/adoption/tech/.

3. Customize the tech stack

Edit .pair/adoption/tech/tech-stack.md to match your team's actual technology choices. For example, if your team uses Jest instead of Vitest:

## Testing
 
- jest is adopted as the testing framework (jest v29.x).
- @testing-library/react is adopted for component testing.

The adoption declaration pattern ([tool] is adopted for [purpose]) tells every AI assistant this is a decision, not a suggestion.

See Customize the Knowledge Base for your team for the full customization guide.

4. Customize code design guidelines

Review .pair/adoption/tech/ and add files for team conventions that differ from the KB defaults:

<!-- .pair/adoption/tech/api-conventions.md -->
 
# API Conventions
 
- All REST endpoints use kebab-case paths.
- Response format follows the JSON:API specification.
- Authentication uses Bearer JWT tokens in the Authorization header.

The AI reads every file in .pair/adoption/, custom files are treated the same as overrides.

5. Configure the PM tool integration

If you chose GitHub Projects during bootstrap, verify the setup (/pair-next may suggest this if PM tool is unconfigured):

/pair-capability-setup-pm

This skill:

1. Creates a GitHub Project board (or connects to an existing one)
2. Configures status fields (Todo → Ready → In Progress → Done)
3. Sets up labels for story types, priorities, and epics
4. Records the PM tool configuration in your way-of-working

6. Set quality gates

Edit .pair/adoption/tech/way-of-working.md to define your team's quality gate:

## Quality Gates
 
- `pnpm quality-gate` is the adopted project-level quality gate command.
- Quality gate includes: type checking, testing, linting, formatting.
 
### Custom Gate Registry
 
| Order | Gate         | Command              | Required |
| ----- | ------------ | -------------------- | -------- |
| 1     | Quality Gate | `pnpm quality-gate`  | Yes      |
| 2     | Security     | `pnpm audit`         | No       |

Every developer and every AI assistant will run these checks before committing.

Prefer automation over hand-editing: /pair-capability-setup-gates provisions shared lint/format config packages (per-type overrides for backend/frontend/shared-lib workspaces) plus pre-commit + pre-push hooks, defaulting to husky. See the shared config packages guideline for the pattern, pair's own tools/* is the reference implementation. Override the hook manager by recording your choice in way-of-working.md before running the skill.

The same skill also provisions a deterministic secret-scanning CI job, required, at every risk tier, no LLM involved. gitleaks is the KB default; the job is written as a required, fail-closed step in your CI pipeline alongside a starting .gitleaks.toml allowlist at the project root.

This is a mechanical CI gate, not a skill judgment call, see the secret-scanning guideline for the job template, the allowlist mechanism, and a reproducible verification.

Security judgment (authn/authz, injection, OWASP Top 10) is a separate concern, handled per-PR by /pair-capability-assess-security: the two never overlap.

More team options

Every option below is optional; the full catalog with defaults is Adoption settings; the recipe is Customize the Knowledge Base for your team. Each: hand edit, or ask /pair-assistant (optional, Claude Code; it shows the diff, validates, writes through record-decision).

• Autonomy (until, prepare, merge): how far cards go unattended (Automated development). "let green cards go up to merge"
• Cycle Hooks: commands at stage boundaries (Delivery cycle). "add a pre-verify hook that runs the tests"
• Blocking Severities and max-dispatches: which review findings block (Adoption settings). "only Major and above should block"
• Publish-PR Hooks: commands around PR publication (Adoption settings). "regenerate mirrors before publishing"
• Workflow profiles (workflowProfiles): engine and model per stage (Configuration). "use profile cheap-green for the review"
• skipRegistries: registries pair leaves alone (Quickstart). "keep my own AGENTS.md"
• format-check-command, worktree-setup-command: formatting gate; setup run in a fresh worktree (Adoption settings). "run pnpm install in new worktrees"
• Review enforcement, Review identity, Coverage guardrail, PR states: PR state flow, Review identity, Tag-driven gates. "make the review a required check"
• PM tool, code host, State Mapping (incl. unmapped states and not-planned): Canonical states, via /pair-capability-setup-pm. "map Won't Do to not-planned"
• Definition of Ready / Done tier requirements: Definition of Ready and Done. "red cards need two reviewers"
• Process Profile: which steps run (Adoption settings). "switch to the poc profile"
• Risk matrix and Tag Projection: Quality model. "also emit cost tags"
• Harness and Model Policy: /pair-capability-setup-harness. "switch the harness to pi"
• Gates and branch protection: /pair-capability-setup-gates. "set up the pre-push gate"
• Package-local adoption, template overrides: Package-local adoption, Customize templates.

7. Record key decisions

For significant decisions that need rationale, create Architecture Decision Records (/pair-next may suggest this when decisions are pending):

/pair-capability-record-decision

This is especially important for choices your team debated, "why TypeScript over Go?", "why PostgreSQL over MongoDB?". ADRs live in .pair/adoption/tech/adr/ and give future team members (and AI assistants) the context behind each choice.

8. Commit the pair setup

Stage and commit the full .pair/ directory:

git add .pair/ AGENTS.md .claude/ .github/ .cursor/
git commit -m "chore: pair KB + team adoption files"
git push

9. Onboard a team member

Have a teammate clone the repository and open it in their AI assistant. They should:

1. Open the project: the bridge files are already committed, so their assistant finds .pair/ automatically
2. Run /pair-next: pair reads the adoption files and knows the project context
3. Start working: the assistant uses your team's tech stack, architecture, and conventions

No manual onboarding needed. The Knowledge Base and adoption files are the onboarding.

10. Verify the team workflow

Have the onboarded teammate create a small change and go through the full cycle:

1. Pick a story from GitHub Projects
2. Run /pair-process-implement: the assistant creates a branch, follows TDD, runs quality gates
3. Review the PR: run /pair-process-review on the resulting pull request
4. Merge: confirm the squash-merge follows your commit template

If everything works end-to-end, your team setup is complete.

Troubleshooting

What you've learned

• Bootstrap configures pair for your team's specific context in one step
• Adoption files override KB defaults, your customizations survive upstream updates
• Quality gates ensure consistent standards across every developer and AI session
• PM tool integration connects pair's planning skills to your issue tracker
• Bridge files make every AI assistant read the same context: no per-tool configuration
• Onboarding is automatic: commit the .pair/ directory and teammates are ready

Next steps

• Customize the Knowledge Base for your team: Deep dive into all customization options
• Own and publish a Knowledge Base: Package your team's KB for distribution
• Enterprise Adoption tutorial: Rolling out pair across an organization
• Support: FAQ and troubleshooting when something doesn't work