/walkeros-create-transformer

name: walkeros-create-transformer
description:
  Use when creating a new walkerOS transformer to modify events in the pipeline
  (validate, enrich, or redact) at a before/next chain position. Example-driven
  workflow for the transformer interface, return values, and chaining.

Create a New Transformer

Prerequisites

Before starting, read these skills:

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

transformers fit in architecture

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

Transformer interface

• [understanding-events](../walkeros-understanding-events/SKILL.md) - Event

structure

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

Documentation standards (for Phase 7)

Transformer Categories

| Category | Purpose | Example | | ------------ | ----------------------------- | ---------------------------- | | **Validate** | Check event structure/content | JSON Schema, required fields | | **Enrich** | Add data to events | Server timestamps, geo data | | **Redact** | Remove/mask sensitive data | Strip PII, anonymize IPs |

Process Overview

1. Research     → Understand use case (validate/enrich/redact)
2. Examples     → Create event before/after examples FIRST
3. Scaffold     → Copy template, configure package.json
4. Convention   → Add walkerOS.json metadata and buildDev
5. Implement    → Build transformer with TDD
6. Test         → Verify against example transformations
7. Document     → Write README

Supporting Files

This skill includes reference files you can copy:

• **[examples/](examples/)** - Example events and configs to adapt for your

transformer

• [events.ts](examples/events.ts) - Before/after event examples
• [config.ts](examples/config.ts) - Configuration examples
• **[templates/validation/](templates/validation/)** - Complete redact

transformer template

• [index.ts](templates/validation/index.ts) - Implementation with context

pattern

• [types.ts](templates/validation/types.ts) - Type definitions
• [schemas.ts](templates/validation/schemas.ts) - Zod validation schemas
• [index.test.ts](templates/validation/index.test.ts) - Test suite with

helpers

---

Phase 1: Research

**Goal:** Understand what the transformer needs to do.

1.1 Define Use Case

• [ ] **Category**: Validate, Enrich, or Redact?
• [ ] **Input**: What events will this process?
• [ ] **Output**: What should change? What should be blocked?
• [ ] **Configuration**: What settings does user need?

1.2 Check Existing Patterns

# Reference implementation
ls packages/transformers/fingerprint/

# Transformer types
cat packages/core/src/types/transformer.ts

Gate: Research Complete

• [ ] Category identified (validate/enrich/redact)
• [ ] Input/output transformation defined
• [ ] Configuration options listed

---

Phase 2: Create Examples (BEFORE Implementation)

**Goal:** Define event transformations in `dev` entry FIRST.

2.1 Scaffold Directory Structure

mkdir -p packages/transformers/[name]/src/{examples,schemas,types}

2.2 Create Event Examples

Adapt [examples/events.ts](examples/events.ts) for your transformer's use case. Each example file should include:

• Events that should pass through (modified)
• Expected output after processing
• Events that should be blocked (for validators)

2.3 Create Config Examples

Adapt [examples/config.ts](examples/config.ts) for your transformer's settings.

2.4 Step Examples

Add step examples with `{ in, out }` pairs for end-to-end step testing:

// examples/step.ts
export const step = {
  'order-passes': {
    in: { name: 'order complete', data: { id: 'ORD-123' } },
    out: { name: 'order complete', data: { id: 'ORD-123' } },
  },
  'debug-filtered': {
    in: { name: 'debug test', data: { message: 'noise' } },
    out: false, // Transformer rejects this event
  },
};

For transformers, both `in` and `out` are walkerOS events, except `out: false` which indicates the transformer filters (rejects) the event. Set `title` + `description` for public examples; mark test-only fixtures with `public: false`. See [using-step-examples](../walkeros-using-step-examples/SKILL.md) for the Three Type Zones.

2.5 Export via dev.ts

export * as schemas from './schemas';
export * as examples from './examples';

Gate: Examples Valid

• [ ] All example files compile (`npm run build`)
• [ ] Can trace: input event → expected output for each example

---

Phase 3: Scaffold

**Template transformer:** `packages/transformers/fingerprint/`

cp -r packages/transformers/fingerprint packages/transformers/[name]
cd packages/transformers/[name]

# Update package.json: name, description, repository.directory

**Directory structure:**

packages/transformers/[name]/
├── src/
│   ├── index.ts           # Main export
│   ├── transformer.ts       # Transformer implementation
│   ├── index.test.ts      # Tests against examples
│   ├── dev.ts             # Exports schemas and examples
│   ├── examples/
│   │   ├── index.ts       # Re-exports
│   │   ├── events.ts      # Before/after event examples
│   │   └── config.ts      # Configuration examples
│   ├── schemas/
│   │   └── index.ts       # Zod schemas for settings
│   └── types/
│       └── index.ts       # Settings, Types interfaces
├── package.json
├── tsconfig.json
├── tsup.config.ts
├── jest.config.mjs
└── README.md

---

Phase 4: walkerOS.json Convention

Every walkerOS package ships a `walkerOS.json` file for CDN-based schema discovery.

Add `walkerOS` field to package.json

{
  "walkerOS": {
    "type": "transformer"
  },
  "keywords": ["walkerOS", "walkerOS-transformer", ...]
}

Use `buildDev()` in tsup.config.ts

Replace `buildMod