Pluggable capability layer — configure which skill/plugin fulfills a process skill's capability slot

[rucka]

Epic Information

Epic ID: [assigned on creation]
Initiative: Process Engine & Orchestration #200
Theme: Pluggable capability layer for process skills
Epic Owner: Foomakers Product Team
Status: Planning
Priority: P1
Epic Points: TBD (estimated during refinement)
Target Release: TBD

Epic Statement

As a project maintainer/adopter using pair
I need pair's process skills (implement, review, refine, plan-*, etc.) to declare configurable capability slots that can be fulfilled either by pair's own built-in capability skill or by an installed third-party skill/plugin
So that adopters can plug in specialized third-party expertise per capability (e.g. Matt Pocock's TypeScript skills, Vlad Khononov's domain-modeling skills, "compound engineering" skills) without forking pair's own process skills

Epic Context

Per initiative #200 (Process Engine & Orchestration), pair's differentiator is the process layer, not any single capability's implementation. Today a process skill composes a FIXED capability skill (e.g. /pair-process-review always composes /pair-capability-assess-security). This epic opens that binding: a process skill declares WHICH capability slot it needs, and adoption configuration resolves that slot to a concrete skill — pair's own default, or a third-party skill/plugin installed via the existing marketplace mechanism (#213, #277) — following the same Argument > Adoption > KB default cascade already used elsewhere in the framework.

Business Value & Objectives

Primary Business Goals

1. Goal 1: Any process skill's capability composition is swappable via adoption config, with pair's own skill as the zero-configuration default.
2. Goal 2: A third-party skill/plugin can declare "I provide capability X" and become selectable without pair core changes.
3. Goal 3: Misconfiguration (missing/incompatible provider) fails safely and legibly, never silently.

Problem Statement & Market Opportunity

Current State

Process skills hardcode which capability skill they compose. Adopting a third-party skill for a specific concern (e.g. a TypeScript-idiom reviewer, a DDD-aware domain modeler) means forking the process skill or running the third-party skill entirely outside pair's orchestration — losing checkpointing, gates, and the PR/review flow.

Target State

Process skills read an adoption-declared capability map (slot → skill) before composing, defaulting to pair's own skill when nothing is declared. Third-party skills are pilotable as drop-in capability providers.

Solution Overview

Core Solution Approach

Convention over configuration, consistent with the rest of the framework (D21): a capability slot is a named contract (inputs/outputs a process skill relies on); adoption declares slot→skill overrides; absent declaration resolves to pair's own default skill — zero-configuration path unchanged.

Key Capabilities

1. Capability-slot resolution convention — how a process skill names the capability it needs and how the resolution cascade (argument > adoption > KB default) picks the concrete skill to compose.
2. Adoption schema — a new section (e.g. ## Capability Providers in way-of-working.md or a dedicated adoption file) listing slot → skill-name overrides.
3. Third-party provider contract — how an installed skill/plugin declares "I fulfill capability slot X" (frontmatter or registry entry) so it's discoverable/selectable, building on the existing marketplace install path (Skill marketplace + Quickstart + external KB scaffold #213/Skill marketplace: marketplace.json + plugin packaging for native Claude Code install #277).
4. Guardrails — fail-safe behavior when a configured provider is missing, uninstalled, or doesn't satisfy the slot's contract (never a silent no-op).
5. Pilot integrations — validate the mechanism end-to-end with real third-party skills as reference adopters (e.g. Matt Pocock's TypeScript-idiom skills, Vlad Khononov's domain-modeling skills, "compound engineering" skills).

Epic Breakdown

User Stories (High-Level)

Must-Have Stories (P0/P1)

• As a framework maintainer I want a capability-slot resolution convention (KB doc) so that any process skill can declare a swappable capability
• As a maintainer I want an adoption schema for capability-provider overrides so that a project can point a slot at a third-party skill
• As a third-party skill author I want a documented "provides capability X" contract so that my skill/plugin becomes selectable without pair core changes
• As an adopter I want a fail-safe, legible error when a configured capability provider is missing or incompatible

Should-Have Stories (P2)

• Pilot: wire one real third-party skill (e.g. a TypeScript-idiom or DDD-modeling skill) into one process skill's capability slot, end to end

Epic Acceptance Criteria

• AC1: A process skill composing a capability slot resolves it via argument > adoption > KB default, pair's own skill being the zero-config default
• AC2: A project without any capability-provider override behaves exactly as today (D21 — no adoption file needed)
• AC3: A misconfigured/missing provider fails loudly with an actionable message, never silently degrading
• AC4: At least one third-party skill is proven pluggable end-to-end as a pilot

Appendix

Related Documentation

• Initiative #200 Process Engine & Orchestration
• Prior art: #213 Skill marketplace + Quickstart + external KB scaffold, #277 Skill marketplace: marketplace.json + plugin packaging — the install/distribution mechanism this epic's provider contract builds on.