Skip to content
/

foomakers/pair

ozzeron-foomakers-pair · foomakers/pair · ★ 3 · last commit 2026-04-18

Gives AI assistants the full team context — PRD, ADRs, guidelines, process — needed to execute a complete SDLC without context loss.

Best whenThe 34 skills split into process orchestrations and composable capability atoms, and process skills explicitly compose capability skills rather than being mo…
Skip ifMonolithic documentation, Skipping the idempotency gate
vs seeds
openspecwith a deep product-planning layer (PRD, initiati…
Primitive shape 34 total
Skills 34
00

Summary

foomakers/pair — Summary

foomakers/pair is a full-SDLC AI pairing framework that ships a structured Knowledge Base (.pair/), 34 Agent Skills following the agentskills.io open standard, and a TypeScript CLI (npx @foomakers/pair-cli install) that copies both into any project. Its central metaphor is "code is the easy part" — the real lift is giving AI assistants the team context, architecture decisions, process guidelines, and acceptance criteria they need to produce quality software from the very first sprint. The skill set splits cleanly into two families: pair-process-* (12 full workflow orchestrations covering PRD creation, story breakdown, implementation, review, and bootstrap) and pair-capability-* (22 composable atomic capabilities such as quality gate verification, debt assessment, flag management, and manual test design). The PRD skill alone is an eight-phase, hypothesis-driven interview process that produces a 13-section structured document via idempotency-aware check gates. Compared to seeds, pair is closest to openspec (mirrored command/skill pairs, full SDLC coverage) but goes further into the product planning layer — it ships PRD templates, initiative planning, epic/story breakdown, and a decision-log structure that openspec omits. Unlike superpowers, pair's skills invoke each other compositionally (pair-process-implement composes pair-capability-verify-quality and pair-capability-record-decision) rather than treating each skill as a standalone Iron Law.

01

Overview

foomakers/pair — Overview

Origin

Created by Foomakers (https://pair.foomakers.com). The repository uses pair itself for its own development ("pair is developed using pair itself"). First commit history not public but CLI is at version 0.4.1 (skills), pushed at 2026-04-18.

Philosophy

"Code is the easy part."

The framework premise is that AI coding assistants fail not because they cannot write code but because they lack the domain context, process knowledge, and project-specific adoption decisions that a human developer accumulates over months. pair solves this by externalizing that context into a navigable Knowledge Base that lives in .pair/ alongside the code — architecture decisions, ADRs, tech-stack choices, PRD, subdomain model, way-of-working guidelines.

The second premise is idempotency: every process skill begins with a Phase 0 detection gate that checks whether its artifact already exists and offers selective update rather than destructive re-creation.

Manifesto-style quotes

From README:

"AI-assisted software development — structured Knowledge Base, Agent Skills, and adoption files that give AI coding assistants the context they need to ship quality software."

From AGENTS.md:

"In all interactions and commit messages, be extremely coincise and sacrify grammar for the sake of coincision."

From way-of-working.md:

"The process is designed to: Accelerate development velocity through intelligent automation and AI-powered code generation. Maintain quality standards via systematic review processes and automated quality checks. Ensure business alignment by connecting technical implementation to strategic business objectives."

Target audience

Individual developers and small teams who want to run the complete SDLC — from PRD through deployment — inside their AI assistant with zero ceremony overhead. The pair-next skill reads the PM tool state and adoption files to recommend the most relevant next action, functioning as a session scheduler.

Cross-tool compatibility

Supports Claude Code, Cursor, Windsurf, GitHub Copilot (via AGENTS.md), and any agentskills.io-compatible tool. Each skill ships as a SKILL.md file that the host tool discovers.

02

Architecture

foomakers/pair — Architecture

Distribution

  • npm CLI: @foomakers/pair-cli (binary: pair-cli)
  • Install command: npx @foomakers/pair-cli install
  • Monorepo: Turborepo + pnpm workspaces
  • Packages: @pair/content-ops, @pair/knowledge-hub, @pair/brand
  • Apps: apps/pair-cli (CLI), apps/website

Required runtime

  • Node.js (implied; TypeScript CLI built with tsup/Commander)
  • No Docker required

Directory tree after install

<project-root>/
├── AGENTS.md                     # Universal agent entry point
├── CLAUDE.md                     # Claude Code agent entry point
├── .claude/
│   └── skills/                   # 34 Agent Skills (SKILL.md per skill)
│       ├── pair-process-specify-prd/
│       ├── pair-process-implement/
│       ├── pair-capability-verify-quality/
│       └── ...
└── .pair/
    ├── llms.txt                  # Machine-readable KB index (llmstxt.org)
    ├── adoption/
    │   ├── product/
    │   │   ├── PRD.md            # Product Requirements Document
    │   │   └── subdomain/
    │   └── tech/
    │       ├── architecture.md
    │       ├── tech-stack.md
    │       ├── infrastructure.md
    │       ├── way-of-working.md
    │       ├── ux-ui.md
    │       ├── adr/              # Architecture Decision Records
    │       └── boundedcontext/
    └── knowledge/
        ├── getting-started.md
        ├── skills-guide.md
        ├── way-of-working.md
        ├── assets/
        │   ├── PRD_template.md
        │   ├── PRD_example.md
        │   └── bootstrap-checklist.md
        ├── guidelines/           # 9 guideline areas (code-design, testing, security, ...)
        └── how-to/               # 11 how-to guides

Target AI tools

Claude Code, Cursor, Windsurf, GitHub Copilot, any agentskills.io compatible tool

Config files

AGENTS.md, CLAUDE.md, .pair/adoption/tech/way-of-working.md, .pair/adoption/product/PRD.md

CLI commands

Command Purpose
pair-cli install Copy KB + skills into project
pair-cli update Update KB to latest version
pair-cli kb-validate Validate KB structure
pair-cli kb-verify Verify KB integrity
pair-cli kb-info Show KB metadata
pair-cli validate-config Validate config
pair-cli update-link Update symlinks
pair-cli package Package for distribution
03

Components

foomakers/pair — Components

Skills (34 total)

Process Skills (12) — full workflow orchestrations

Name Purpose
pair-next Reads PM tool state + adoption files; recommends next action
pair-process-bootstrap Full project bootstrap checklist
pair-process-specify-prd Create / update PRD via 8-phase hypothesis interview
pair-process-map-subdomains Define subdomain model
pair-process-map-contexts Define bounded contexts
pair-process-plan-initiatives Create and prioritize initiatives
pair-process-plan-epics Break down epics
pair-process-plan-stories Create user stories
pair-process-plan-tasks Create implementation tasks
pair-process-refine-story Refine a user story with acceptance criteria
pair-process-implement Implement a user story (composes quality, decision, stack, adoption skills)
pair-process-review Code review skill

Capability Skills (22) — composable atomic capabilities

Name Purpose
pair-capability-verify-quality Quality gate verification
pair-capability-verify-done Definition-of-done check
pair-capability-verify-adoption Check adoption file compliance
pair-capability-record-decision Record architectural/technical decisions
pair-capability-assess-ai Assess AI tooling suitability
pair-capability-assess-architecture Architecture quality assessment
pair-capability-assess-code-quality Code quality assessment
pair-capability-assess-debt Technical debt assessment
pair-capability-assess-infrastructure Infrastructure assessment
pair-capability-assess-methodology Methodology assessment
pair-capability-assess-observability Observability assessment
pair-capability-assess-pm PM tool assessment
pair-capability-assess-stack Tech stack assessment (detects new deps)
pair-capability-assess-testing Testing strategy assessment
pair-capability-design-manual-tests Design manual test cases
pair-capability-estimate Estimation
pair-capability-execute-manual-tests Execute manual tests
pair-capability-manage-flags Feature flag management
pair-capability-setup-gates Setup quality gates
pair-capability-setup-pm Setup PM tool integration
pair-capability-write-issue Write issue to PM tool
agent-browser Browser automation capability

Templates / Knowledge Assets

Path Purpose
.pair/knowledge/assets/PRD_template.md Full 13-section PRD template
.pair/knowledge/assets/PRD_example.md Example PRD with quality bar
.pair/knowledge/assets/bootstrap-checklist.md Project bootstrap checklist
.pair/knowledge/guidelines/ 9 guideline areas
.pair/knowledge/how-to/ 11 how-to guides (index.json for AI discovery)
.pair/adoption/product/PRD.md Live PRD
.pair/adoption/tech/ Architecture, stack, ADR, bounded context

Scripts

  • pair-cli install — copies .pair/ tree and .claude/skills/ into project
  • Symlink: apps/website/public/skills../../.claude/skills (shared between CLI and website docs)

Hooks

None. Pair relies on skill autonomous activation via agentskills.io descriptor matching, not Claude Code lifecycle hooks.

05

Prompts

foomakers/pair — Prompts

Excerpt 1: pair-process-specify-prd — Phase 0 Idempotency Gate

Source: .claude/skills/pair-process-specify-prd/SKILL.md

## Phase 0: Detect Existing PRD (Idempotency Gate)

### Step 0.1: Check Current State

1. **Check**: Does [adoption/product/PRD.md](../../../.pair/adoption/product/PRD.md) exist?
2. **Act** (file exists): Read the file. Determine if it is a **template** (contains `[Product/feature name]` or `[Creation date]`) or a **populated** PRD.
   - If **template**: treat as new PRD. Proceed to Phase 1.
   - If **populated** and `$section` provided: jump to Phase 3 (selective update of that section).
   - If **populated** and no `$section`: present current PRD summary and ask:

     > PRD already exists for **[product name]**. Options:
     > 1. **Update specific sections** — tell me which sections need changes
     > 2. **Full review** — walk through the entire PRD for updates
     > 3. **Cancel** — no changes needed

3. **Verify**: Mode is set to `create`, `update-section`, `full-review`, or `cancelled`. If cancelled → stop.

Technique: Idempotency gate with explicit state enumeration. The skill detects context before acting, exposing a choice menu rather than blindly overwriting.


Excerpt 2: pair-process-implement — Phase 0 BLOCKING Gate

Source: .claude/skills/pair-process-implement/SKILL.md

### Step 0.1: Load Story

1. **Check**: Is the user story already loaded in this session?
2. **Skip**: If yes, confirm story ID and move to Step 0.1b.
3. **Act**: Read the story from the PM tool (per [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md)).
   - Understand business value and acceptance criteria.
   - Confirm epic context.
4. **Verify**: Story is fully loaded. If not → **HALT**.

### Step 0.1b: Activate Story in PM Tool (NEVER SKIP)

1. **Check**: Is the story already assigned to the current developer AND status is "In Progress"?
2. **Skip**: If BOTH conditions met, move to Step 0.2.
3. **Act**: Update the PM tool:
   - **Assign** the story to the current developer (if not already assigned).
   - **Set status to "In Progress"** in the PM tool board/project.
4. **Verify**: Story is assigned and In Progress. If PM tool is inaccessible → warn developer and continue.

Technique: Check-Skip-Act-Verify (CSAV) loop pattern with HALT escalation. Each step has a check for existing state (enabling idempotent re-runs), an optional skip (if already done), an action, and a verification gate.


Excerpt 3: pair-process-specify-prd — Section Checklist

Source: .claude/skills/pair-process-specify-prd/SKILL.md

### Step 1.2: Create Section Checklist

1. **Act**: Build a checklist of all PRD sections from the template:

   ```text
   PRD CHECKLIST:
   ├── [ ] 1. Overview (name, version, date, owner, summary)
   ├── [ ] 2. Vision & Mission
   ├── [ ] 3. Problem Statement (current state, pain points)
   ├── [ ] 4. Goals & Success Metrics (KPIs with targets)
   ├── [ ] 5. Target Users (personas, journey)
   ├── [ ] 6. Solution Overview (core solution, features P0/P1/P2)
   ├── [ ] 7. User Stories & Acceptance Criteria (epics, stories, ACs)
   ├── [ ] 8. Technical Considerations (architecture, requirements, constraints)
   ├── [ ] 9. Design Requirements (UI/UX, visual)
   ├── [ ] 10. Timeline & Milestones (phases, dependencies)
   ├── [ ] 11. Risks & Mitigations (table)
   ├── [ ] 12. Launch & Go-to-Market (strategy, marketing, support)
   └── [ ] 13. Post-Launch (monitoring, iteration plan)

**Technique**: Explicit checklist rendering before Q&A — the agent tracks coverage visually in the conversation so neither the agent nor user loses context of which PRD sections are still pending.
09

Uniqueness

foomakers/pair — Uniqueness

Differs from Seeds

Closest seed is openspec (mirrored command/skill coverage, full SDLC, markdown-first). pair extends beyond openspec in three ways: (1) it adds a deep product-planning layer — PRD, initiatives, epics, stories, tasks — that openspec omits; (2) its skills compose each other explicitly (pair-process-implement lists its composed capabilities in a Composed Skills table), whereas openspec skills are standalone; and (3) it ships a navigable Knowledge Base (.pair/knowledge/) with 11 how-to guides, 9 guideline areas, and a machine-readable llms.txt index, making the framework's guidance system self-documenting. Compared to BMAD-Method, pair uses the same skill-composition philosophy but is less opinionated about persona activation and more grounded in agile/Kanban terminology (epics, stories, ADRs vs BMAD's "analyst/architect/developer" persona cast). Compared to superpowers, pair lacks the Iron Law enforcement model and worktree isolation but offers far deeper product management coverage.

Positioning

pair fills the gap between lightweight CLAUDE.md stubs and heavyweight orchestrators like claude-flow: it gives teams a structured but non-ceremonial SDLC framework that degrades gracefully — teams that skip the PRD phase can still use the implement/review skills without adopting the full planning stack.

Observable Failure Modes

  1. PM tool agnosticism is manual: way-of-working.md says "read PM tool state" but the tool must be configured per-project (GitHub Issues, filesystem, etc.) — a new project must read guidelines/project-management-tool/ and set this up before pair-next works correctly.
  2. No enforcement mechanism: Skills are recommendations, not Iron Laws. An agent can skip the quality gate without failing an automated check.
  3. CSAV pattern overhead: The Check-Skip-Act-Verify structure in every step is thorough but verbose — deeply nested step descriptions can exceed context budget on long workflows.
  4. Monorepo complexity: The npm package is part of a Turborepo monorepo with multiple sub-packages; understanding what actually gets installed vs what's internal requires digging into apps/pair-cli/src/commands/install/.
04

Workflow

foomakers/pair — Workflow

Overall SDLC Phases

Phase Skills Key Artifacts
Induction pair-process-bootstrap, pair-process-specify-prd .pair/adoption/product/PRD.md, bootstrap checklist
Strategic pair-process-plan-initiatives, pair-process-map-subdomains, pair-process-map-contexts initiatives list, subdomain map, bounded context docs
Iteration pair-process-plan-epics, pair-process-plan-stories, pair-process-plan-tasks, pair-process-refine-story epics, stories with ACs, task breakdown
Execution pair-process-implement PR, commits, quality gate report
Review pair-process-review review comments, merge

PRD Creation Phases (pair-process-specify-prd)

Phase Description Artifact
Phase 0 Idempotency gate — detect existing PRD; offer create/update-section/full-review mode decision
Phase 1 Template & reference analysis — read PRD_template.md + PRD_example.md section checklist
Phase 2 Information gathering — ask for existing docs; map coverage covered sections
Phase 3 Hypothesis-driven questions (12-section loop) — ask clarifying Qs per uncovered section answers
Phase 4–7 Section authoring, review loop, approval PRD.md

Implementation Phases (pair-process-implement)

Phase Description Artifact
Phase 0 Story & task analysis (BLOCKING) loaded story
Phase 0b Activate story in PM tool story status → In Progress
Phase 1 Setup — branch, task ordering git branch
Phase 2 Per-task 5-step cycle: context → branch → implement → quality → commit committed code
Phase 3 PR creation pull request
Phase 4 Post-review merge merged branch

Approval Gates

  1. PRD exists? → offer mode choice before any new PRD work
  2. Story fully loaded? → HALT if not
  3. All tasks complete? → HALT if incomplete task structure
  4. Per-task quality gate (pair-capability-verify-quality) before commit
  5. PR ready? → after all tasks complete
  6. Decision needed? → invoke pair-capability-record-decision before continuing

Composition Pattern

pair-process-implement explicitly composes:

  • pair-capability-verify-quality (required, quality phase)
  • pair-capability-record-decision (required, when decision detected)
  • pair-capability-assess-stack (optional, on new dependency)
  • pair-capability-verify-adoption (optional, before commit)

This is pair's most distinctive architectural choice: process skills compose capability skills rather than being monolithic.

06

Memory Context

foomakers/pair — Memory & Context

State Storage

All state is file-based under .pair/adoption/:

File/Dir Role
.pair/adoption/product/PRD.md Live product requirements document
.pair/adoption/product/subdomain/ Subdomain model
.pair/adoption/tech/architecture.md Architecture decisions
.pair/adoption/tech/tech-stack.md Tech stack choices
.pair/adoption/tech/way-of-working.md Process agreements
.pair/adoption/tech/adr/ Architecture Decision Records
.pair/adoption/tech/boundedcontext/ Bounded context guidelines
.pair/adoption/decision-log/ Non-architectural decision records

Context Discovery

.pair/llms.txt — machine-readable index for AI tools to discover available knowledge base content without reading every file (follows llmstxt.org convention).

AGENTS.md / CLAUDE.md — universal and Claude-specific entry points that direct the agent to read adoption files first.

Persistence Scope

Project-level persistence. All state lives in the repo alongside code. No global state, no external database.

Cross-Session Handoff

Yes — every adoption file is a durable artifact. The CSAV pattern in skills checks existing state before acting, so a skill can be interrupted and resumed without duplication.

Compaction Handling

The way-of-working.md instructs agents to read adoption files at session start. There is no explicit compaction hook but the .pair/llms.txt index enables efficient selective loading of only the relevant subset of adoption files for a given task.

Memory Type

File-based markdown. No vector search, no SQLite, no graph DB.

07

Orchestration

foomakers/pair — Orchestration

Multi-Agent

No dedicated multi-agent orchestration. Skills compose each other within a single agent session using explicit skill invocation references (e.g., "invoke /pair-capability-verify-quality") rather than spawning subagents via the Task tool.

Orchestration Pattern

Sequential with explicit composition. Process skills invoke capability skills as sub-routines within the same agent context. The CSAV (Check-Skip-Act-Verify) loop within each step gives each skill an internal retry/skip logic.

Isolation Mechanism

None specified. Skills run in the agent's current working directory; no worktree or container isolation.

Multi-Model

No. Single model.

Execution Mode

Interactive-loop. Skills respond to explicit invocation by the user or another skill.

Crash Recovery

Partial — the idempotency gate in each skill (Phase 0) allows safe re-invocation. If a skill was interrupted, re-running it detects existing state and either continues or offers selective update rather than starting over.

Context Compaction Handling

Skills read adoption files at the start of each invocation. The pair-next skill reads PM tool state + adoption files to re-establish session context automatically.

Cross-Session Handoff

Yes — via .pair/adoption/ file system. Durable artifacts survive session boundaries.

Subagent Definition Format

None (no subagents). Capability skills are invoked compositionally by process skills as named skill references, not spawned as separate agent threads.

08

Ui Cli Surface

foomakers/pair — UI & CLI Surface

CLI Binary

  • Name: pair-cli
  • Package: @foomakers/pair-cli
  • Install: npx @foomakers/pair-cli install
  • Entry: dist/cli.js
  • Framework: Commander.js + TypeScript

Subcommands

Command Purpose
install Copy KB + skills into project
update Update KB to latest version
kb-info Show KB metadata
kb-validate Validate KB structure
kb-verify Verify KB integrity
update-link Update symlinks
validate-config Validate config
package Package for distribution

Local UI

Website exists at apps/website (the pair documentation site at pair.foomakers.com). This is a documentation/marketing site, not an operational dashboard. No local dashboard shipped.

IDE Integration

Via SKILL.md files in .claude/skills/ for Claude Code, and cursor/windsurf equivalent directories via the clavix init-style multi-tool install. The CLI installs into ~/.config/agents/skills/ (global) or .skills/ (project) depending on host tool.

Observability

No audit log, no structured observability beyond the PM tool integration (stories/tasks tracked in the user's PM tool of choice). The pair-capability-verify-quality skill produces a quality report as a conversational artifact.

CI Integration

Repo ships with GitHub Actions CI pipeline (Node 18/20/22 matrix) for the CLI itself, but pair does not ship CI templates for user projects.

Related frameworks

same archetype · same primary tool · same memory type

claude-mem (thedotmack) ★ 78k

Background worker service captures every tool call as an observation, AI-compresses sessions, and auto-injects relevant past…

pi (badlogic/earendil) ★ 55k

A minimal, hackable, multi-provider terminal coding agent that adapts to your workflows via npm-installable TypeScript Extensions…

Agent Skills (Addy Osmani) ★ 46k

Encodes senior-engineer software development lifecycle as 23 auto-routed skills and 7 slash commands for any AI coding agent.

wshobson/agents Plugin Marketplace ★ 36k

Single Markdown source for 83 domain-specialized plugins that auto-generates idiomatic artifacts for five AI coding harnesses.

TabbyML/Tabby ★ 34k

Self-hosted AI coding assistant server (alternative to GitHub Copilot) with admin dashboard, RAG-based completions, and multi-IDE…

Compound Engineering ★ 17k

Make each unit of engineering work compound into easier future work via brainstorm→plan→execute→review→learn cycles.