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, Windows Terminal, or 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
Option A: Global install (recommended)
Then run it anywhere:
If the command is not found, make sure pnpm's global bin directory is in your PATH. Run pnpm bin -g to check the location.
Option B: Dev dependency (JavaScript/TypeScript projects)
Add pair-cli to your project so it's pinned to a specific version and available to every developer via package.json:
Then run it via npx or pnpm:
All pair-cli commands in this tutorial work the same way — just prefix them with npx or pnpm.
Option C: Manual download (non-JavaScript projects)
If your project uses Python, Go, Rust, or any language without a Node.js toolchain, download the CLI directly:
- Download
pair-cli-manual-vX.Y.Z.zipfrom GitHub Releases - Extract the archive
- Run the CLI from the extracted folder:
The manual download still requires Node.js 18+ to run — pair-cli is a Node.js application. You don't need npm/pnpm as a package manager though.
Verify the installation (any option):
You should see a version number like 0.4.0.
2. Create and initialize your project
If you don't already have a project directory:
3. Install the Knowledge Base
This downloads the Knowledge Base and creates the .pair/ directory with:
knowledge/— guidelines, how-tos, templates (reference material)adoption/— empty templates for your project decisions
It also installs bridge files (AGENTS.md, .claude/, .github/copilot/, .cursor/) so every AI assistant finds the same context.
The .pair/knowledge/ directory is managed by pair-cli. Don't edit files there — your changes would be overwritten on the next update. Your decisions go in .pair/adoption/.
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/adopted/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):
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
- Customization — Adjust guidelines and quality gates for your specific needs
- Team Setup tutorial — Ready to share pair with your team? Follow the team configuration tutorial
- Guides — Goal-oriented guides for specific tasks