KB Structure

The .pair/ directory is the root of pair's Knowledge Base. It contains all guidelines, adoption decisions, and project context that AI coding assistants use to understand your project.

Directory Tree

.pair/
├── knowledge/                    # Upstream guidelines (updated by `pair-cli update`)
│   ├── getting-started.md
│   ├── skills-guide.md
│   ├── way-of-working.md
│   ├── how-to/                   # Step-by-step process guides
│   │   ├── 01-how-to-create-PRD.md
│   │   ├── 02-how-to-complete-bootstrap-checklist.md
│   │   ├── 03-how-to-create-and-prioritize-initiatives.md
│   │   ├── 06-how-to-breakdown-epics.md
│   │   ├── 07-how-to-breakdown-user-stories.md
│   │   ├── 08-how-to-refine-a-user-story.md
│   │   ├── 09-how-to-create-tasks.md
│   │   ├── 10-how-to-implement-a-task.md
│   │   └── 11-how-to-code-review.md
│   ├── guidelines/               # Technical and process standards
│   │   ├── collaboration/        # Team process guidelines
│   │   │   ├── templates/        # Issue, commit, PR, branch templates
│   │   │   ├── methodology/      # Scrum, Kanban, Lean, etc.
│   │   │   ├── estimation/       # Story points, T-shirt sizing, etc.
│   │   │   ├── issue-management/ # GitHub Issues, filesystem-based
│   │   │   ├── project-management-tool/  # PM tool implementations
│   │   │   ├── decision-records.md
│   │   │   └── team/             # Team structure and roles
│   │   ├── quality-assurance/    # Testing, CI/CD, quality gates
│   │   ├── technical-standards/  # Feature flags, security
│   │   └── code-design/          # Code quality, design principles
│   │       ├── quality-standards/    # Linting, coverage, metrics
│   │       ├── design-principles/    # SOLID, functional, error handling
│   │       ├── package-management/   # pnpm, workspaces, shared deps
│   │       ├── code-organization/    # Naming, file structure
│   │       └── framework-patterns/   # React, TypeScript, state management
│   └── assets/                   # Templates and examples
│       ├── PRD_template.md
│       ├── PRD_example.md
│       └── bootstrap-checklist.md
│
├── adoption/                     # Project-specific decisions (never overwritten)
│   ├── decision-log/             # Non-architectural decision log (ADL) + Analysis-Log (category: Analysis)
│   ├── product/                  # Product decisions
│   │   ├── PRD.md                # Product Requirements Document
│   │   ├── subdomain/            # DDD subdomain definitions
│   │   └── ddr/                  # Domain Decision Records
│   └── tech/                     # Technical decisions
│       ├── architecture.md       # Architecture pattern
│       ├── tech-stack.md         # Approved libraries and versions
│       ├── way-of-working.md     # Development process and quality gates
│       ├── infrastructure.md     # Cloud, CI/CD, deployment
│       ├── ux-ui.md              # UI/UX standards
│       ├── adr/                  # Architecture Decision Records
│       └── boundedcontext/       # DDD bounded context definitions
│
├── working/                      # Operational area - excluded from every registry (D14)
│   ├── checkpoints/               # Resumable state for multi-task flows
│   └── reports/
│       └── <category>/            # Generated reports, grouped by category
│
└── product/                      # (alias) Points to adoption/product/

Directory Purposes

knowledge/: Upstream Guidelines

Contains all opinionated defaults from the pair KB. These files are updated by pair-cli update and should not be edited directly, your changes would be overwritten.

• how-to/: Step-by-step guides for each phase of the development lifecycle (PRD creation through code review)
• guidelines/: Technical standards organized by domain (collaboration, quality, code design)
• assets/: Templates used by skills and how-to guides

adoption/: Your Decisions

Contains project-specific decisions that override knowledge-layer defaults. These files are never overwritten by pair-cli update.

• product/PRD.md: Your Product Requirements Document
• product/subdomain/: DDD subdomain definitions for your domain
• product/ddr/: Domain Decision Records (why a domain rule was decided; the domain context file holds the current state)
• tech/architecture.md: Your chosen architecture pattern
• tech/tech-stack.md: Your approved libraries with pinned versions
• tech/way-of-working.md: Your development process, quality gates, PM tool
• tech/adr/: Architecture Decision Records documenting significant choices
• tech/boundedcontext/: DDD bounded context definitions

working/: Operational Area (D14)

Holds state produced during execution (checkpoints and reports) not knowledge. Outside every asset registry by design: pair-cli install and pair-cli update never create, modify, or delete anything under it.

• checkpoints/: Resumable state for multi-task flows (e.g. an interrupted /implement run)
• reports/<category>/: Generated reports, grouped by category (e.g. quality, monitoring)

Neither subdirectory is scaffolded by pair-cli install: a skill creates them on demand the first time it writes a checkpoint or report. The path defaults to .pair/working and can be overridden with working_path in config.json (see Configuration Reference); pair-cli validate-config rejects any registry whose target overlaps with it, default or overridden.

Reports come in two shapes. A one-shot audit is keyed by its run date (reports/security/<YYYY-MM-DD>-audit.md). A panel is a recurring, period-scoped report (reports/cost/2026-07-cost-panel.md) whose filename carries a period key, YYYY-MM, YYYY-Wnn, or YYYY-MM-DD_YYYY-MM-DD: re-running for the same period updates that one file in place (one file per period, no duplicates), a headline sits at the top with breakdowns collapsed, an empty period still produces a panel saying so, and an unwritable reports area degrades to presenting the panel inline. The in-place update has one exception, coverage never regresses: if the panel already on disk processed more items than the current run did, it is kept (the run reports its shortfall in its own output instead), so a partial re-run can never overwrite a fuller panel's figures. One convention for every periodic report, see working-area.md.

Precedence Rule

Adoption always wins over knowledge. When a skill reads guidelines, it checks adoption files first. If a decision is recorded there, it takes precedence over the corresponding knowledge-layer guideline.

Update Behavior

Related

• Customize the Knowledge Base for your team: How to override guidelines
• Configuration Reference: config.json options
• Skills Catalog: All 51 pair skills
• llms.txt: How pair makes docs and project context consumable by AI assistants
• knowledge-hub README: KB package operations, scripts, and maintainer guide
• content-ops README: File operations API, copy behaviors, and transform configuration