Your First Project
Install pair, bootstrap a project, create a PRD, generate your first initiative/epic/story, implement, and review, all in one session.
A complete walkthrough for solo developers. You'll go from zero to a fully scaffolded project with AI-assisted planning in about 30 minutes.
Prerequisites
Before starting, make sure you have:
- Node.js v18 or later (download)
- pnpm v9+ or npm v9+ (install pnpm)
- Git initialized in your project (or a new empty directory)
- A terminal (macOS Terminal, iTerm2, WSL2 or Git Bash on Windows, or the VS Code integrated terminal)
- An AI coding assistant that supports Agent Skills, Claude Code, GitHub Copilot, Cursor, or similar
pair works with any AI coding assistant that can read structured files. This tutorial uses generic skill invocation syntax, your assistant's exact interface may vary.
What you'll build
By the end of this tutorial you'll have:
- pair-cli installed globally
- A
.pair/directory with the full Knowledge Base - A Product Requirements Document (PRD) tailored to your idea
- Strategic initiatives prioritized by business impact
- Epics broken down from those initiatives
- User stories ready for development
- Experience running your first pair skill
Estimated time
~30 minutes (depending on how detailed you make your PRD).
Step-by-step instructions
At any step, you can run /pair-next instead of a specific skill. pair reads your project state and suggests the right action, so you never need to remember which skill comes next.
1. Install pair-cli
The three install options (global, as a dev dependency with npx pair-cli, or a manual download for projects without a Node toolchain) are in the Quickstart. Every pair-cli command below works the same way whichever you chose.
2. Create and initialize your project
If you don't already have a project directory:
3. Install the Knowledge Base
With /pair-assistant (optional, Claude Code): ask for "pair in this project, first time" (how to ask).
This creates .pair/ with knowledge/ (guidelines, how-tos, templates) and adoption/ (empty templates for your decisions), and the bridge files (AGENTS.md, .claude/, .github/copilot/, .cursor/) so every AI assistant finds the same context. A repository that already has an AGENTS.md: Adopt pair in an existing repository.
4. Start your AI assistant
Open your project in your AI coding assistant. If you're using Claude Code:
The assistant will detect the .pair/ directory and load the Knowledge Base automatically.
5. Ask pair what to do next
In your assistant, run:
Since this is a fresh project with no PRD and no adoption files, pair will recommend starting with the PRD.
6. Create your PRD
Follow pair's recommendation (or run /pair-next: it will suggest this same action):
The skill will guide you through a structured conversation:
- Project overview: What are you building? Who is it for?
- Problem statement: What problem does it solve?
- Success metrics: How will you measure success?
- Scope: What's in and out for the first release?
- Constraints: Budget, timeline, technology, compliance?
Answer each question. pair writes the PRD to .pair/adoption/product/PRD.md.
You don't need a perfect PRD. Start with what you know: you can refine it later by re-running the skill.
7. Bootstrap the project
Run the full bootstrap (or /pair-next: it knows PRD is done and bootstrap is next):
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).
Bootstrap walks you through:
- Project categorization: type, complexity, team size
- Tech stack assessment: language, framework, testing, CI/CD
- Architecture decisions: monolith, microservices, serverless
- Way of working: methodology, commit strategy, quality gates
Each decision is recorded in .pair/adoption/tech/ as an adoption file. The AI reads these files in every future session, your decisions never drift.
8. Generate initiatives
With the PRD in place, break it down into strategic initiatives (/pair-next would suggest this):
pair analyzes your PRD and creates prioritized initiatives (P0 = must-have, P1 = should-have, P2 = nice-to-have). Each initiative becomes an issue in your PM tool (GitHub Projects if you configured it during bootstrap).
9. Break down into epics
Pick a P0 initiative and break it into epics (/pair-next guides you here):
pair suggests an epic structure including "Epic 0": the foundational setup work every project needs (repo scaffold, CI/CD, quality gates).
10. Create user stories
Break an epic into user stories (/pair-next suggests this when epics exist):
pair applies vertical slicing and INVEST validation to create stories that are independently deliverable.
11. Refine and start developing
You now have a complete planning hierarchy: PRD → Initiatives → Epics → Stories. From here, /pair-next continues guiding you through refinement and implementation.
To refine a story with acceptance criteria and task breakdown:
To implement a refined story with TDD:
12. Review your code
After implementation creates a PR, run a structured code review (/pair-next suggests this when a PR is open):
The review skill checks adoption compliance, quality gates, Definition of Done, and produces a structured review following your team's review template.
What you've learned
- pair-cli install sets up the Knowledge Base and bridge files
/pair-nextalways tells you what to do next based on project state- Process skills follow the SDLC: PRD → Bootstrap → Initiatives → Epics → Stories → Implement → Review
- Adoption files in
.pair/adoption/record your decisions and persist across sessions - Knowledge files in
.pair/knowledge/provide reference material, updated by pair-cli, never edited manually
Next steps
- Concepts: Understand how the Knowledge Base, Skills, and Adoption Files work together
- Guides: configure card states, quality gates, templates and the Knowledge Base for your team
- Team Setup tutorial: Ready to share pair with your team? Follow the team configuration tutorial
- Support: FAQ and troubleshooting when something doesn't work