Guidelines & How-To Catalog
Complete catalog of all pair Knowledge Base guidelines (9 categories) and the 9 sequential how-to guides.
The pair Knowledge Base ships with opinionated guidelines organized into 9 categories and 9 sequential how-to guides covering the full AI-assisted development lifecycle. Guidelines live in .pair/knowledge/guidelines/, how-to guides in .pair/knowledge/how-to/.
Last updated: 2026-08-20. Source:
packages/knowledge-hub/dataset/.pair/knowledge/
How-To Guides
9 sequential guides that walk you through the complete development process, from product requirements to code review. Each guide can be followed manually or invoked as a skill (recommended). See the Process Lifecycle for the full step-by-step walkthrough.
| # | Guide | Tags | Skill (preferred) |
|---|---|---|---|
| 01 | Create a PRD | prd, requirements, planning | /pair-process-specify-prd |
| 02 | Complete Bootstrap Checklist | bootstrap, setup, onboarding, subdomain, bounded-context, domain-model | /pair-process-bootstrap |
| 03 | Create & Prioritize Initiatives | initiative, roadmap, P0/P1/P2, subdomain | /pair-process-plan-initiatives |
| 06 | Break Down Epics | epic, breakdown, 2-4 sprints, subdomain | /pair-process-plan-epics |
| 07 | Break Down User Stories | story, vertical slicing, INVEST | /pair-process-plan-stories |
| 08 | Refine a User Story | refine, Given-When-Then, technical analysis | /pair-process-refine-story |
| 09 | Create Tasks | task, breakdown, dependency mapping, bounded-context | /pair-process-plan-tasks |
| 10 | Implement a Task | implement, TDD, code | /pair-process-implement |
| 11 | Code Review | review, quality gates, ADR | /pair-process-review |
Numbering keeps the original sequence, 04 and 05 (subdomain/bounded-context definition) were removed as standalone guides when map-subdomains/map-contexts were reclassified from process to capability (D24, #246). Domain modeling is now invoked inline, scoped to the caller, at the point in 02/03/06/09 noted above, see the Callers Matrix for exactly which step invokes which capability.
How-To Flow
Guideline Categories
9 categories covering every aspect of software development. Each category contains multiple guideline files organized by topic.
Architecture
Patterns, decisions, and constraints for system design.
| Topic | What it covers |
|---|---|
| Architectural Patterns | Clean architecture, hexagonal, CQRS, event sourcing, layered, CRUD, transaction script |
| Decision Frameworks | ADR process, decision tracking |
| Design Patterns | DDD patterns, bounded contexts, aggregates, context map inline-maintenance, coupling balance |
| Deployment Architectures | Service topologies, scaling patterns |
| LLM Integration | AI/LLM integration patterns |
| Project Constraints | Budget, timeline, compliance constraints |
Code Design
Code organization, principles, and quality standards.
| Topic | What it covers |
|---|---|
| Code Organization | File structure, module boundaries, naming conventions |
| Design Principles | SOLID, DRY, KISS, composition over inheritance, evidence-based do/don't design rules |
| Framework Patterns | Framework-specific patterns and best practices |
| Package Management | Dependency management, monorepo patterns |
| Quality Standards | Code metrics, complexity thresholds, maintainability, shared lint/format config packages |
Collaboration
Process, methodology, and team coordination.
| Topic | What it covers |
|---|---|
| Automation | GitHub Actions, Azure DevOps board rules, filesystem scripts; the unattended-development eligibility policy and the tag→workflow mapping that routes a tagged card (tech/automation.md) |
| Methodology | Scrum, Kanban, Lean, hybrid approaches |
| Estimation | Story points, T-shirt sizing, estimation techniques |
| Issue Management | Issue tracking, triage, prioritization |
| Project Tracking | Velocity, burndown, sprint metrics |
| Project Management Tools | GitHub Projects, Linear, Jira configuration; canonical states + state-mapping schema; PR state flow (gate ≠ review); Definition of Ready & Done; task-progress feedback (checklist ticks + one batched comment per run iteration) |
| Team | Team structure, roles, communication patterns |
| Templates | Branch, commit, PR, epic, story, task, initiative, subdomain, bounded context, code review, context map |
Infrastructure
Cloud, CI/CD, deployment, and operations.
| Topic | What it covers |
|---|---|
| CI/CD Strategy | Pipeline design, build optimization, release automation |
| Cloud Providers | AWS, GCP, Azure patterns |
| Cloud Services | Managed services, serverless, containers |
| Container Orchestration | Docker, Kubernetes, scaling |
| Deployment Patterns | Blue-green, canary, rolling updates |
| Environments | Dev, staging, production configuration |
| Infrastructure as Code | Terraform, CloudFormation, Pulumi |
| Testing Infrastructure | Test environments, fixtures, data management |
Observability
Monitoring, logging, and alerting.
| Topic | What it covers |
|---|---|
| Alerting | Alert rules, escalation, on-call |
| Metrics | Application metrics, SLIs/SLOs/SLAs |
| Observability Principles | Three pillars: logs, metrics, traces |
| Structured Logging | Log formats, correlation IDs, log levels |
Quality Assurance
Security, accessibility, and performance standards.
| Topic | What it covers |
|---|---|
| Quality Model | 3-layer principle, 3 pillars (Cost/Security/Delivery), classification dimensions and tier resolution, per-tier requirements, tag projection, tech/risk-matrix.md adoption delta, see the dedicated page |
| Accessibility | WCAG compliance, screen reader support, keyboard navigation |
| Performance | Load times, Core Web Vitals, optimization |
| Delivery Metrics | Delivery pillar metric set (bug resolution time, PR lead time, process adoption), median/p75 aggregation and the low-sample rule, the adoption-declared bug mapping, and the per-tool query mapping applied by /pair-capability-analyze-delivery-metrics |
| Quality Monitoring | Quality dashboards, trend analysis; optional cost & billing telemetry (deploy-match for cost report mode: deploy-source and billing APIs, equal-length windows, minimum read-only permissions) |
| Quality Standards | Definition of Done, quality gates, acceptance criteria; canonical Definition of Ready & Done (6 DoR + 4 DoD criteria) |
| Security | OWASP top 10, authentication, authorization, input validation |
Technical Standards
Coding standards, git workflow, and tooling.
| Topic | What it covers |
|---|---|
| AI Development | AI tool configuration, prompt patterns, agent integration |
| AI Development → Agent Harness | Per-harness configuration guides (pi, opencode, Claude Code), config locations, skill-path discovery, auth, access paths, model providers, headless execution, verified-against version |
| AI Development → Skill Conventions | Single-source shared conventions for the SKILL.md corpus (resolution cascade, idempotency, graceful degradation, template resolution) |
| Coding Standards | Language-specific conventions, linting rules |
| Deployment Workflow | Release process, versioning, changelog |
| Development Tools | IDE setup, debugging, profiling |
| Git Workflow | Branching strategy, commit conventions, merge policies |
| Integration Standards | API design, event contracts, data formats |
| Technology Stack | Language selection, framework evaluation, version policies |
Testing
Strategies, frameworks, and testing patterns.
| Topic | What it covers |
|---|---|
| Test Strategy | Testing pyramid, TDD, coverage targets |
| Unit Testing | Isolation, mocking, assertions |
| Integration Testing | Service integration, database testing |
| E2E Testing | User journey testing, browser automation |
| Accessibility Testing | Automated a11y checks, manual testing |
| Performance Testing | Load testing, benchmarking, profiling |
| Test Automation | CI integration, parallel execution, reporting |
| Manual Testing | Test case design, critical path grouping, AI-assisted execution, report generation |
User Experience
Design systems, research, and content strategy.
| Topic | What it covers |
|---|---|
| Content Strategy | Writing guidelines, tone, information architecture |
| Design Principles | Visual hierarchy, consistency, feedback |
| Design Systems | Component libraries, tokens, theming |
| Interface Design | Layout patterns, responsive design, navigation |
| User Research | Personas, journey mapping, usability testing |
Related
- Quality Model: the single source of default quality rules (classification, tiers, tags)
- Skills Catalog: all 51 pair skills with commands and composition
- Process Lifecycle: step-by-step walkthrough of the full process
- KB Structure: directory layout and file purposes
- Customize the Knowledge Base for your team: override guidelines via adoption files