Customize the Knowledge Base

Quick recipe to override a KB guideline using adoption files — identify, override, verify.

Need to change a single KB default? This is the quick recipe. For the full customization journey — from adopting a KB to publishing your own — see the Customization section.

Override a Guideline in 3 Steps

Step 1: Identify What to Change

Browse the knowledge layer to find the guideline:

# List all guideline categories
ls .pair/knowledge/guidelines/
 
# Example: see testing guidelines
ls .pair/knowledge/guidelines/quality-assurance/

Step 2: Record Your Decision

Create or update the corresponding adoption file. For example, to change the testing framework, edit .pair/adoption/tech/tech-stack.md:

## Testing
 
- jest is adopted as the testing framework (jest v29.x).

Adoption files always override knowledge files — no need to touch .pair/knowledge/.

Step 3: Verify

pair-cli kb validate
pair-cli update-link --dry-run

Quick Reference: Which File to Edit

You want to change...	Edit this adoption file
Testing framework, language, library	`.pair/adoption/tech/tech-stack.md`
Architecture pattern	`.pair/adoption/tech/architecture.md`
Methodology, quality gates	`.pair/adoption/tech/way-of-working.md`
Add a new guideline	Create a new file in `.pair/adoption/`
Record a significant decision	Create an ADR in `.pair/adoption/tech/adr/`

What's Safe to Edit

Directory	On `pair-cli update`	Safe to edit?
`.pair/knowledge/`	Overwritten	No — don't edit
`.pair/adoption/`	Preserved	Yes — your decisions stay

Going Deeper

Customize for Your Team — full guide to adapting guidelines, quality gates, and way-of-working
Publish a Knowledge Base — package and distribute a KB for your organization
KB Structure Reference — directory layout and file purposes
Configuration Reference — config.json options