understanding-development

Use when contributing to walkerOS, before writing code, or when unsure about project conventions. Covers build/test/lint workflow, XP principles, folder structure, and package usage.

⭐309stars🔀16forks📁View on GitHub🕐Updated Dec 19, 2025⬇️2downloads

When & Why to Use This Skill

This Claude skill serves as a comprehensive development guide and onboarding playbook for walkerOS. It streamlines the contribution process by defining mandatory Extreme Programming (XP) principles, project-specific coding conventions, and automated workflows for building, testing, and linting. By providing a clear roadmap of the monorepo structure and core package usage, it ensures all code contributions align with the project's architectural standards and quality requirements.

Use Cases

  • Developer Onboarding: Quickly familiarize new contributors with walkerOS-specific conventions, folder structures, and the 'Test-First' development philosophy.
  • Code Quality Compliance: Ensure all contributions adhere to XP principles such as DRY, KISS, and YAGNI, while strictly avoiding the use of 'any' in production code.
  • Workflow Standardization: Provide a quick reference for essential terminal commands (npm run build/test/lint) to maintain a consistent development environment.
  • Architectural Reference: Guide developers on where to implement features across the monorepo, distinguishing between core utilities, collectors, and platform-specific destinations.
  • Dependency Management: Ensure correct usage of @walkeros/core utilities and shared configurations to prevent redundant code and maintain system integrity.
nameunderstanding-development

Understanding walkerOS Development

Overview

walkerOS follows extreme programming principles with strict conventions. This skill is your foundation before writing any code.

Core principle: DRY, KISS, YAGNI. Test first. Verify before claiming complete.

Commands

Command Purpose
npm install Install all dependencies
npm run dev Watch mode for all packages
npm run build Build all packages
npm run test Run all tests
npm run lint ESLint + TypeScript check
npm run format Prettier formatting

Validation before commit: npm run build && npm run test && npm run lint

XP Principles (Non-Negotiable)

Principle In Practice
DRY Use @walkeros/core utilities, don't reimplement
KISS Minimal code to solve the problem
YAGNI Only implement what's requested
TDD Test first, watch it fail, then implement
No any Never use any in production code (tests are exception)

Folder Structure

packages/
├── core/           # Platform-agnostic types, utilities, schemas
├── collector/      # Central event processing engine
├── config/         # Shared config (eslint, jest, tsconfig, tsup)
├── web/
│   ├── core/       # Web-specific utilities
│   ├── sources/    # browser, dataLayer
│   └── destinations/ # gtag, meta, api, piwikpro, plausible
└── server/
    ├── core/       # Server-specific utilities
    ├── sources/    # gcp
    └── destinations/ # aws, gcp, meta

apps/
├── walkerjs/       # Ready-to-use browser bundle
├── quickstart/     # Code examples (source of truth for patterns)
└── demos/          # Demo applications

Core Package Usage

Always import from @walkeros/core:

// Types
import type { WalkerOS } from '@walkeros/core';

// Utilities
import {
  getEvent,
  createEvent, // Event creation
  getMappingEvent,
  getMappingValue, // Transformations
  isString,
  isObject,
  isDefined, // Type checking
  assign,
  clone, // Object operations
  tryCatch,
  tryCatchAsync, // Error handling
} from '@walkeros/core';

Config package for shared tooling:

  • ESLint config: @walkeros/config/eslint
  • Jest config: @walkeros/config/jest
  • TSConfig: @walkeros/config/tsconfig
  • Tsup config: @walkeros/config/tsup

Testing

REQUIRED SKILL: Use testing-strategy for detailed testing patterns.

Quick reference:

  • Use env pattern for mocking (not Jest mocks)
  • Import from dev.ts for examples
  • Test first, watch it fail
  • Verify before claiming complete