Windsurf

Set up pair with Windsurf — configure .windsurf/rules, discover skills, and follow the bridge pattern.

Prerequisites

Windsurf (by Codeium) installed
A pair-enabled project (pair-cli init completed, .pair/ directory exists)
Node.js 18+

Configure Agent File

Windsurf reads project-level rules from .windsurf/rules/ at the repository root. pair generates these bridge files during pair-cli init.

.windsurf/rules/

pair creates rule files in .windsurf/rules/ that point Windsurf to your .pair/ directory:

your-project/
├── .windsurf/
│   ├── rules/             ← Windsurf reads these automatically
│   └── skills/            ← symlinks to .claude/skills/
├── .pair/
│   ├── knowledge/
│   └── adoption/
└── ...

The rules file contains the same project context as AGENTS.md — task selection, essential commands, key references, and quick rules — formatted for Windsurf's conventions.

The Bridge Pattern

.windsurf/rules/ points to .pair/ — the single source of truth:

.windsurf/rules/  ──→ .pair/knowledge/   (guidelines)
                  ──→ .pair/adoption/    (your decisions)

Use Skills

Skills are available in .windsurf/skills/ as symlinks to the canonical copies in .claude/skills/. Reference a skill by asking Windsurf to follow it:

Follow the instructions in .windsurf/skills/pair-process-implement/SKILL.md to implement story #42

Common Skills

Skill	Purpose
`pair-next`	Determine next action based on project state
`pair-process-implement`	Implement a story task by task
`pair-process-review`	Structured code review
`pair-process-refine-story`	Refine a story with acceptance criteria

For the full catalog, see Skills Catalog.

Windsurf's Cascade feature works well with pair's structured process. When following a skill like /pair-process-implement, Cascade can execute multi-step workflows autonomously while respecting your adoption files.

Multi-Agent Teams

If your team uses Windsurf alongside other AI tools, the bridge pattern ensures consistency. .windsurf/rules/ and .claude/skills/ both point to the same .pair/ source of truth.

Skills as Symlinks

Skills in .windsurf/skills/ are symlinks to .claude/skills/. pair-cli update refreshes all tool directories simultaneously. On Windows, pair falls back to full copies.

Verify It Works

Open Windsurf in your pair-enabled project and ask:

Read the pair rules in .windsurf/rules/ and tell me what project I'm working on

Expected output: Windsurf reads the rules, follows the references to .pair/adoption/, and describes your project context. If it can't find the rules, check that pair-cli init completed successfully.