Pair Framework

---
name: "Pair Framework"
slug: "pair"
version: "4.0-alpha"
description: "Entry skill for assistants working on the Pair v4 framework repository."
tags:
  - php
  - pair
  - framework
  - review
language: "en"
---

# Pair Framework v4 — SKILL

Use this file as the **compact quick-start companion** to `AGENTS.md`.

Read `AGENTS.md` first.
Then use this file to move quickly through the repository without losing the main workflow and output rules.
This quick-start assumes Pair v4 on the default branch. The authoritative version-scope note lives in `AGENTS.md`.

---

## Scope

Framework development in this repository:

- src/
- assets/
- translations/
- tests

The goal is to produce **safe, minimal, reviewable changes**.

---

## Quick Guardrails

Use this file for navigation, not as a second source of truth.

- Workflow, technical conventions, change hygiene, clarification rules, and final output format are owned by `AGENTS.md`.
- Reuse existing framework patterns before introducing helpers or abstractions.
- Prefer additive changes over rewrites.
- Use the smallest set of documents needed for the current task.

---

## Fast path

Use this decision guide to avoid reading too much documentation:

- For any code change: read `AGENTS.md`, then use this file for navigation.
- For architecture or framework internals: read `PAIR_ARCHITECTURE.md`.
- For implementation style and nearby code shape: read `PAIR_PATTERNS.md`.
- To avoid importing patterns from heavier frameworks: read `PAIR_CONTEXT.md`.
- For larger features, refactors, migrations, or performance work: read `PAIR_TASKS.md`.

Start with `AGENTS.md` and `SKILL.md`, then stop unless the task still needs deeper context.

---

## Official Docs Shortcuts

Use the official Pair wiki when the task touches one of these areas:

- Routing, URL params, ordering, and pagination state: `Router`
- Controller lifecycle, `_init()`, model/view loading, and PRG flows: `Controller`
- View responsibility, `render()`, assigned variables, and layout behavior: `View`
- Table-mapped entities, request population, persistence, and relations: `ActiveRecord`
- Control rendering, CSRF, generated forms, and select conventions: `Form`
- Progressive enhancement with `data-*` directives and lightweight helpers: `PairUI.js`
- Runtime configuration or new environment keys: `.env configuration`

Prefer these official docs over generic framework assumptions when behavior is unclear.

---

## Component map

Use this map to find the right area quickly before searching broadly:

- `src/Core`: application lifecycle, router, controller, model, view, logger, environment.
- `src/Orm`: ActiveRecord, query builder, collections, database access.
- `src/Api`: API controllers, request/response wrappers, middleware, throttling, OpenAPI support.
- `src/Html`: forms, widgets, menus, render helpers, form controls.
- `src/Helpers`: reusable framework helpers and utility-style classes.
- `src/Services`: integrations with external services and provider-specific logic.
- `src/Models`: framework models built on Pair ORM.
- `src/Push`: push notification delivery and subscription handling.
- `src/Exceptions`: framework exception types and error codes.
- `src/Traits`: small reusable behavior shared across classes.
- `assets`: PairUI and frontend-side JavaScript helpers.
- `translations`: localization resources.

If the task touches request handling, check `src/Core`, `src/Api`, and nearby helpers before creating new flow logic.
If the task touches UI or forms, check `src/Html` and `assets` before adding new frontend patterns.

---

## Search heuristics

When locating code, prefer targeted searches over broad grep-style scans:

- Search by namespace or class name first.
- Search by method name only after identifying the likely component area.
- Search for one nearby concrete example before designing a new approach.
- For forms and UI, search in `src/Html` and `assets` together.
- For API flows, search in `src/Api` first, then `src/Core`, then related models/helpers.
- For ORM behavior, search in `src/Orm` and then in the model using that behavior.

Useful starting points:

- request or validation logic: `src/Api/Request.php`, `src/Core/Controller.php`
- form rendering: `src/Html/Form.php`, `src/Html/FormControl.php`
- frontend progressive enhancement: `assets/PairUI.js`
- application lifecycle: `src/Core/Application.php`, `src/Core/Router.php`

If a search returns too many matches, narrow by namespace or directory before reading more files.

---

## Accuracy checklist

Before editing, confirm these high-risk assumptions:

- The change follows an existing Pair pattern nearby.
- The public API remains compatible unless the task explicitly says otherwise.
- ORM helpers are not being bypassed without a concrete reason.
- Server-rendered behavior is preserved unless the task explicitly moves logic client-side.
- Security behavior is not weakened.

---

## Task recipes

Use these default flows for common tasks.

### Small bug fix

1. Reproduce or isolate the failing behavior.
2. Find the closest class handling the same responsibility.
3. Implement the smallest safe fix.
4. Check that adjacent behavior did not change.
5. Update or add tests if they exist for that area.

### Small feature

1. Identify the correct layer: controller, model, helper, service, or frontend helper.
2. Reuse an existing pattern in the same namespace.
3. Prefer additive behavior over changing an existing public contract.
4. Keep frontend behavior progressive and lightweight.

### Local refactor

1. Confirm the goal is clarity, duplication removal, or maintainability.
2. Keep external behavior unchanged.
3. Limit the refactor to the smallest useful scope.
4. Do not expand into nearby unrelated cleanup.
5. Verify public APIs and tests remain valid.

### Documentation update

1. Update only the document that owns the topic.
2. Keep examples aligned with current Pair behavior.
3. Avoid copying rules across multiple files.
4. Preserve the distinction between entrypoint, workflow, and technical reference.

---

## Capabilities of the Pair framework

The framework provides:

- MVC routing system
- ActiveRecord ORM
- migration tools
- push notification system
- PWA helpers
- PairUI frontend helper library
- optional integrations with external services

Agents should reuse existing framework components instead of reimplementing similar functionality.

---

## Documentation map

Document ownership and conflict resolution are defined in `AGENTS.md`.

Use deeper docs only for their narrow role:

- `AGENTS.md`: authoritative workflow, technical conventions, and output contract
- `PAIR_ARCHITECTURE.md`: framework internals and request flow
- `PAIR_CONTEXT.md`: anti-import guardrails
- `PAIR_PATTERNS.md`: idiomatic code shape and examples
- `PAIR_TASKS.md`: extra guidance for broader or higher-risk tasks

Read the minimum set needed for the task. More documentation is not automatically better if it delays a safe, pattern-consistent change.