From walkeros
Guides creation of walkerOS transformers for event validation, enrichment, or redaction using example-driven TDD workflow, TypeScript templates, and Zod schemas.
npx claudepluginhub elbwalker/walkerosThis skill uses the workspace's default tool permissions.
Before starting, read these skills:
Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
Before starting, read these skills:
| 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 |
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
This skill includes reference files you can copy:
Goal: Understand what the transformer needs to do.
# Reference implementation
ls packages/transformers/validator/
# Transformer types
cat packages/core/src/types/transformer.ts
Goal: Define event transformations in dev entry FIRST.
mkdir -p packages/transformers/[name]/src/{examples,schemas,types}
Adapt examples/events.ts for your transformer's use case. Each example file should include:
Adapt examples/config.ts for your transformer's settings.
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 for the
Three Type Zones.
export * as schemas from './schemas';
export * as examples from './examples';
npm run build)Template transformer: packages/transformers/validator/
cp -r packages/transformers/validator 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
Every walkerOS package ships a walkerOS.json file for CDN-based schema
discovery.
walkerOS field to package.json{
"walkerOS": {
"type": "transformer"
},
"keywords": ["walkerOS", "walkerOS-transformer", ...]
}
buildDev() in tsup.config.tsReplace buildModules({ entry: ['src/dev.ts'] }) with buildDev():
import { buildDev } from '@walkeros/config/tsup';
// In defineConfig array:
buildDev(),
This auto-generates dist/walkerOS.json from your Zod schemas at build time.
If your transformer has capabilities, behaviors, or troubleshooting patterns not
obvious from schemas alone, add hints. See walkeros-writing-documentation
skill for full guidelines.
Create src/hints.ts:
import type { Hint } from '@walkeros/core';
export const hints: Hint.Hints = {
'validation-behavior': {
text: 'Describes how validation works. See settings schema for options.',
code: [{ lang: 'json', code: '{ "settings": { ... } }' }],
},
};
Export from src/dev.ts:
export * as schemas from './schemas';
export * as examples from './examples';
export { hints } from './hints';
Guidelines:
walkerOS field in package.json with type: "transformer"buildDev() in tsup.config.tsdist/walkerOS.jsonwalkerOS and walkerOS-transformerNow write code to transform examples as expected.
See templates/validation/types.ts for the
pattern. Define Settings and Types interfaces.
Transformers use the context pattern - they receive a single context
object containing config, env, logger, id, and collector.
See templates/validation/index.ts for a complete implementation example.
Key patterns:
config, logger, id from init contextpush function gets event + push context{ event } (continue), void (passthrough), false
(cancel)src/index.ts:
export { transformerRedact } from './transformer';
export type { Settings, Types } from './types';
npm run build passesnpm run lint passesVerify implementation produces expected outputs.
See templates/validation/index.test.ts for a complete test suite showing:
createTransformerContext() helper - Standardizes init context creationcreatePushContext() helper - Standardizes push context creationevent, void, or false returnsnpm run test passesFollow the writing-documentation skill for:
Key requirements for transformer documentation:
Beyond
understanding-development
requirements (build, test, lint, no any):
dev.ts exports schemas and exampleswalkerOS.json generated at build timewalkerOS field in package.json| What | Where |
|---|---|
| Template | packages/transformers/validator/ |
| Types | packages/core/src/types/transformer.ts |
| Chaining logic | packages/collector/src/transformer.ts |