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

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

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 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 → Refined → 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.

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 for Your Team — Deep dive into all customization options
• Publish a Knowledge Base — Package your team's KB for distribution
• Enterprise Adoption tutorial — Rolling out pair across an organization
• Guides — Goal-oriented guides for specific tasks