/walkeros-create-cmp-source

name: walkeros-create-cmp-source
description:
  Use when creating a new walkerOS CMP (consent management platform) source.
  Structured fill-in-the-blanks workflow that turns any CMP's consent API into a
  walkerOS source package. Covers CookieFirst, Usercentrics, CookiePro/OneTrust
  patterns and generalizes to any CMP.

Create a CMP Source

A CMP source is a specialized walkerOS source that listens to a consent management platform's events and translates consent states into `elb('walker consent', state)` calls.

Every CMP source follows the same skeleton with only 5-6 decision points that vary per CMP. This skill turns "build a new CMP source" into a structured fill-in-the-blanks workflow.

Prerequisites

Before starting, read these skills:

• [understanding-flow](../walkeros-understanding-flow/SKILL.md) - How sources

fit in architecture

• [understanding-sources](../walkeros-understanding-sources/SKILL.md) - Source

interface

• [create-source](../walkeros-create-source/SKILL.md) - General source creation

workflow

• [testing-strategy](../walkeros-testing-strategy/SKILL.md) - How to test
• [writing-documentation](../walkeros-writing-documentation/SKILL.md) -

Documentation standards (for Phase 8)

Supporting files

This skill includes reference files you can copy:

• **[examples/](examples/)** - Generic CMP consent examples to adapt for your

CMP

• [inputs.ts](examples/inputs.ts) - Consent input scenarios (full, partial,

minimal, revocation)

• [outputs.ts](examples/outputs.ts) - Expected walkerOS consent states after

mapping

• [env.ts](examples/env.ts) - Mock environment factories (createMockElb,

createMockWindow)

• **[templates/cmp/](templates/cmp/)** - Complete CMP source implementation

template

• [index.ts](templates/cmp/index.ts) - Source implementation with detection

paths + handleConsent

• [types.ts](templates/cmp/types.ts) - Type definitions (Settings, CMP API,

Types bundle)

• [test-utils.ts](templates/cmp/test-utils.ts) - Test utilities (MockWindow,

createMockElb, createCmpSource)

• [index.test.ts](templates/cmp/index.test.ts) - Test suite skeleton (8

describe blocks)

**Note:** These are generic templates for the skill. The actual CMP package's examples go in `packages/web/sources/cmps/[name]/src/examples/`.

Canonical template

**CookieFirst** at `packages/web/sources/cmps/cookiefirst/` is the canonical template. Copy its structure for every new CMP source.

**Note:** The CookieFirst README and package.json predate this skill and are missing some sections required by mandatory check #10 (walkerOS.json, Type definitions, Related, Timing considerations) and the `walkerOS-source` keyword. New CMP sources MUST include all required sections. The CookieFirst package will be updated to match.

Process overview

1. Research     -> Fill in the CMP research template
2. Examples     -> Create input/output examples (full, partial, minimal, revocation, edge cases)
3. Mapping      -> Define category map with sensible defaults
4. Scaffold     -> Copy from CookieFirst template
5. Convention   -> walkerOS.json, buildDev
6. Test         -> Write tests FIRST (TDD): 25-32 tests across 8-9 describe blocks
7. Implement    -> Wire up detection paths + handleConsent + destroy
8. Document     -> README + update existing consent guide page

---

Phase 1: Research the CMP

**Goal:** Fill in every field of this template before writing any code.

CMP research template

Fill in ALL of these fields for the target CMP:

| Field | Description | Example (CookieFirst) | | --------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | **CMP name** | Official product name | CookieFirst | | **Global window object** | `window.X` shape and key properties | `window.CookieFirst.consent` (boolean map) | | **SDK events** | Event names, `CustomEvent` detail structure | `cf_init` (Event), `cf_consent` (CustomEvent with consent detail) | | **Callbacks/hooks** | Function wrapping patterns | None | | **Category naming** | Human-readable vs opaque IDs | Human-readable (`necessary`, `functional`, `performance`, `advertising`) | | **Consent access pattern** | Is consent read from a property (`window.CMP.consent`) or an API method (`CMP.getConsent()`)? | Property: `window.CookieFirst.consent` | | **Explicit consent detection** | API or mechanism to check if user actively chose | `consent === null` means no explicit choice | | **"Already loaded" detection** | How to detect CMP loaded before source | `window.CookieFirst.consent` exists and is non-null | | **Official docs URL** | Link to CMP's developer/API documentation | CookieFirst Public API docs | | **npm packages / TS types** | Available type packages