Skip to content

AGENT.md

Latest commit

 

History

History
108 lines (87 loc) · 5.6 KB

AGENT.md

File metadata and controls

108 lines (87 loc) · 5.6 KB

AGENT.md - walkerOS Developer Hub

walkerOS is a privacy-first event data collection and tag management solution. Architecture: Source → Collector → Destination(s)

Quick Start

npm install        # Install dependencies
npm run dev        # Watch mode
npm run build      # Build all packages
npm run test       # Run tests
npm run lint       # Check code quality

Understanding walkerOS

Learn the concepts before coding:

Skill What You'll Learn
understanding-development Build workflow, XP principles, folder structure
understanding-flow Architecture, composability, data flow
understanding-events Event model, entity-action naming, properties
understanding-mapping Event transformation, data/map/loop
understanding-destinations Destination interface, env pattern
understanding-sources Source interface, capture patterns
understanding-transformers Transformer interface, chaining, pipeline
understanding-stores Store interface, $store: wiring, lifecycle
using-logger Logger access, DRY principles, when to log
using-step-examples Step examples lifecycle, Three Type Zones, testing

Creating Things

Task Skill
Write tests testing-strategy
Create destination create-destination
Create source create-source
Create transformer create-transformer
Configure mappings mapping-configuration
Debug event flow debugging
Write documentation writing-documentation

Package Navigation

packages/
├── core/           # Types, utilities, schemas (@walkeros/core)
├── collector/      # Event processing engine
├── config/         # Shared tooling config
├── mcps/           # Parent for MCP server packages
│   ├── mcp/            # Flow dev MCP server (@walkeros/mcp)
│   └── source-browser/ # Tagging MCP server (@walkeros/mcp-source-browser)
├── web/            # Browser: sources/, destinations/
└── server/         # Node.js: sources/, destinations/

apps/
├── explorer/       # Component & style library (@walkeros/explorer)
├── quickstart/     # Validated examples (source of truth)
├── walkerjs/       # Browser bundle
└── demos/          # Demo applications

Key Files

What Where
Event types packages/core/src/types/event.ts
Mapping functions packages/core/src/mapping.ts
Flow type packages/collector/src/types/flow.ts
Destination interface packages/core/src/types/destination.ts
Source interface packages/core/src/types/source.ts
Validated examples apps/quickstart/

Non-Negotiables

  • Event naming: "entity action" format with space ("page view", not "page_view")
  • No any: Never in production code
  • XP principles: DRY, KISS, YAGNI, TDD
  • Test first: Watch it fail before implementing
  • Verify: Run tests before claiming complete

Creating/Maintaining Skills

Skills are packaged as a Claude Code plugin via .claude-plugin/:

Location Purpose
skills/[name]/SKILL.md Primary content (source of truth)
.claude-plugin/plugin.json Plugin manifest listing all skills
.claude/skills/ Symlink to ../skills/ for local dev

To create a new skill:

  1. Create skill: skills/[name]/SKILL.md with frontmatter: 
    ---
name: [name]
description: [When to use - shown in Claude Code skill list]
---
  2. Add to .claude-plugin/plugin.json skills array
  3. Add to AGENT.md tables above (Understanding or Creating section)
  4. Add to skills/README.md index

External users install via: /plugin marketplace add elbwalker/walkerOS