@xonovex/skills 0.1.0

package/skills/lua-opinionated-guidelines/reference/cache-lookups.md

@@ -0,0 +1,43 @@
+# cache-lookups: Cache Table Lookups
+
+**Guideline:** Cache repeated table field accesses in local variables to improve performance.
+
+**Rationale:** Table lookups are slower than local variable access. Caching reduces redundant table accesses, especially in hot paths and loops.
+
+**Example:**
+
+```lua
+-- ❌ Bad - repeated table lookups
+function update_position(entity, dt)
+    entity.x = entity.x + entity.velocity_x * dt
+    entity.y = entity.y + entity.velocity_y * dt
+end
+
+-- ✅ Good - cached lookups
+function update_position(entity, dt)
+    local x = entity.x
+    local y = entity.y
+    local vx = entity.velocity_x
+    local vy = entity.velocity_y
+
+    entity.x = x + vx * dt
+    entity.y = y + vy * dt
+end
+
+-- ✅ Good - cache module table
+local math_sin = math.sin
+local math_cos = math.cos
+
+function rotate_point(x, y, angle)
+    local cos_a = math_cos(angle)
+    local sin_a = math_sin(angle)
+    return x * cos_a - y * sin_a,
+           x * sin_a + y * cos_a
+end
+```
+
+**Techniques:**
+- Store frequently accessed table fields in locals
+- Cache standard library functions (math.sin, etc.)
+- Especially important in loops and hot paths
+- Balance readability vs performance

package/skills/lua-opinionated-guidelines/reference/coroutines.md

@@ -0,0 +1,66 @@
+# coroutines: Coroutines for Cooperative Tasks
+
+**Guideline:** Use coroutines for cooperative multitasking, timed actions, and state machines.
+
+**Rationale:** Coroutines enable writing sequential code for asynchronous operations without callbacks. Ideal for game timers, animations, and task scheduling.
+
+**Example:**
+
+```lua
+-- Coroutine for timed actions
+function create_timer(duration)
+    return coroutine.create(function()
+        local elapsed = 0
+        while elapsed < duration do
+            local dt = coroutine.yield()
+            elapsed = elapsed + dt
+        end
+        return true  -- Completed
+    end)
+end
+
+-- Task manager
+local TimerManager = {}
+
+function TimerManager:new()
+    return setmetatable({timers = {}}, {__index = self})
+end
+
+function TimerManager:add_timer(duration, callback)
+    local timer = {
+        coro = create_timer(duration),
+        callback = callback
+    }
+    table.insert(self.timers, timer)
+end
+
+function TimerManager:update(dt)
+    local i = 1
+    while i <= #self.timers do
+        local timer = self.timers[i]
+        local ok, done = coroutine.resume(timer.coro, dt)
+
+        if done then
+            timer.callback()
+            table.remove(self.timers, i)
+        else
+            i = i + 1
+        end
+    end
+end
+
+-- Usage
+local manager = TimerManager:new()
+manager:add_timer(2.0, function()
+    print("Timer fired after 2 seconds")
+end)
+
+-- In game loop
+manager:update(dt)
+```
+
+**Techniques:**
+- Create coroutine with `coroutine.create`
+- Use `coroutine.yield()` to pause execution
+- Resume with `coroutine.resume(coro, args)`
+- Check status with return values or `coroutine.status`

package/skills/lua-opinionated-guidelines/reference/error-handling.md

@@ -0,0 +1,41 @@
+# error-handling: Error Handling
+
+**Guideline:** Use explicit error return values (value, error) pattern instead of exceptions for expected failures.
+
+**Rationale:** Follows Lua conventions. Makes error handling explicit and visible. More appropriate for recoverable errors than `assert()`.
+
+**Example:**
+
+```lua
+-- ✅ Protected call with error handling
+local function load_config(path)
+    local f, err = io.open(path, "r")
+    if not f then
+        return nil, "Failed to open file: " .. err
+    end
+
+    local content = f:read("*all")
+    f:close()
+
+    local config, err = parse_config(content)
+    if not config then
+        return nil, "Failed to parse config: " .. err
+    end
+
+    return config
+end
+
+-- Usage
+local config, err = load_config("config.lua")
+if not config then
+    print("Error loading config:", err)
+    -- Use defaults
+    config = get_default_config()
+end
+```
+
+**Techniques:**
+- Return `nil, error_message` on failure
+- Return value on success
+- Check first return value before using
+- Use `pcall` for protecting risky operations

package/skills/lua-opinionated-guidelines/reference/idiomatic-patterns.md

@@ -0,0 +1,40 @@
+# idiomatic-patterns: Idiomatic Patterns
+
+**Guideline:** Use Lua's idiomatic patterns for common operations like ternary expressions, default values, and safe navigation.
+
+**Rationale:** These patterns are widely recognized in Lua community, concise, and leverage Lua's truthiness semantics effectively.
+
+**Example:**
+
+```lua
+-- ✅ Ternary operator pattern
+local value = condition and true_value or false_value
+
+-- ✅ Default value pattern
+local x = config.x or 0
+local name = user.name or "Anonymous"
+
+-- ✅ Safe navigation
+local value = obj and obj.field and obj.field.nested
+
+-- ✅ Multiple return values
+local ok, result = pcall(risky_function)
+if ok then
+    use_result(result)
+else
+    handle_error(result)
+end
+
+-- ✅ Swap variables
+a, b = b, a
+
+-- ✅ Unpack table
+local x, y, z = unpack(position)
+```
+
+**Techniques:**
+- Use `and`/`or` for conditional expressions
+- Use `or` for default values
+- Use `and` chain for safe navigation
+- Leverage multiple return values
+- Use tuple assignment for swapping

package/skills/lua-opinionated-guidelines/reference/input-validation.md

@@ -0,0 +1,42 @@
+# input-validation: Input Validation
+
+**Guideline:** Validate function arguments for type, range, and correctness using assertions.
+
+**Rationale:** Lua is dynamically typed. Explicit validation catches errors early, provides clear error messages, and documents expectations.
+
+**Example:**
+
+```lua
+-- ✅ Good - validate inputs
+function M.clamp(value, min, max)
+    assert(type(value) == "number", "value must be a number")
+    assert(type(min) == "number", "min must be a number")
+    assert(type(max) == "number", "max must be a number")
+    assert(min <= max, "min must be <= max")
+
+    if value < min then return min end
+    if value > max then return max end
+    return value
+end
+
+-- ✅ Good - type checking
+function M.divide(a, b)
+    assert(type(a) == "number", "a must be a number")
+    assert(type(b) == "number", "b must be a number")
+    assert(b ~= 0, "division by zero")
+    return a / b
+end
+
+-- ✅ Good - range checking
+function M.set_volume(volume)
+    assert(type(volume) == "number", "volume must be a number")
+    assert(volume >= 0 and volume <= 1, "volume must be between 0 and 1")
+    -- Implementation
+end
+```
+
+**Techniques:**
+- Use `assert()` with descriptive messages
+- Check types with `type()` function
+- Validate numeric ranges and constraints
+- Place validations at function start

package/skills/lua-opinionated-guidelines/reference/jit-friendly-tables.md

@@ -0,0 +1,57 @@
+# jit-friendly-tables: JIT-Friendly Table Operations
+
+**Guideline:** Keep table shapes stable by pre-allocating all fields and avoid adding fields after creation.
+
+**Rationale:** LuaJIT optimizes based on table shape. Adding fields later causes shape changes that prevent JIT compilation and reduce performance.
+
+**Example:**
+
+```lua
+-- ✅ Good - stable tables
+local function create_entity(x, y, type)
+    -- Pre-allocate all fields
+    return {
+        x = x,
+        y = y,
+        type = type,
+        velocity_x = 0,
+        velocity_y = 0,
+        health = 100,
+        active = true
+    }
+end
+
+-- ✅ Good - pre-allocated array
+local function create_array(size)
+    local arr = {}
+    for i = 1, size do
+        arr[i] = 0
+    end
+    return arr
+end
+
+-- ❌ Bad - unstable table (fields added after creation)
+local function create_entity_bad(x, y)
+    local entity = {x = x, y = y}
+    -- Adding fields later hurts JIT
+    entity.velocity_x = 0
+    entity.velocity_y = 0
+    return entity
+end
+
+-- ❌ Bad - using pairs in hot path
+for k, v in pairs(entities) do  -- Slow
+    update_entity(v)
+end
+
+-- ✅ Good - numeric for loop
+for i = 1, #entities do  -- Fast
+    update_entity(entities[i])
+end
+```
+
+**Techniques:**
+- Define all fields in table literal or constructor
+- Pre-allocate arrays with known size
+- Use numeric for loops instead of `pairs` for arrays
+- Avoid sparse arrays

package/skills/lua-opinionated-guidelines/reference/local-variables.md

@@ -0,0 +1,33 @@
+# local-variables: Always Use Local Variables
+
+**Guideline:** Declare all variables as `local` to avoid implicit globals.
+
+**Rationale:** Global variables pollute the namespace, create hard-to-find bugs, and are slower to access than local variables. Locals are also JIT-friendly.
+
+**Example:**
+
+```lua
+-- ✅ Good - all local
+local function calculate(a, b)
+    local result = a + b
+    local squared = result * result
+    return squared
+end
+
+local value = calculate(3, 4)
+
+-- ❌ Bad - implicit globals
+function calculate(a, b)
+    result = a + b        -- Global!
+    squared = result * result  -- Global!
+    return squared
+end
+
+value = calculate(3, 4)  -- Global!
+```
+
+**Techniques:**
+- Prefix all variable declarations with `local`
+- Prefix all function declarations with `local`
+- Only export through module return table
+- Use linters to catch missing `local` keywords

package/skills/lua-opinionated-guidelines/reference/metatables.md

@@ -0,0 +1,52 @@
+# metatables: Metatable Pattern for Simple OO
+
+**Guideline:** Use metatables with `__index` for simple object-oriented programming when needed.
+
+**Rationale:** Provides class-like behavior with inheritance and methods while remaining JIT-friendly. Simpler than complex OO frameworks.
+
+**Example:**
+
+```lua
+-- vector.lua
+local Vector = {}
+Vector.__index = Vector
+
+-- Constructor
+function Vector:new(x, y)
+    local instance = {
+        x = x or 0,
+        y = y or 0
+    }
+    return setmetatable(instance, self)
+end
+
+-- Methods
+function Vector:length()
+    return (self.x * self.x + self.y * self.y) ^ 0.5
+end
+
+function Vector:normalize()
+    local len = self:length()
+    if len == 0 then return self end
+    self.x = self.x / len
+    self.y = self.y / len
+    return self
+end
+
+function Vector:add(other)
+    return Vector:new(self.x + other.x, self.y + other.y)
+end
+
+-- Usage
+local v1 = Vector:new(3, 4)
+local len = v1:length()  -- 5
+local v2 = v1:add(Vector:new(1, 1))
+
+return Vector
+```
+
+**Techniques:**
+- Create table with `__index` pointing to itself
+- Use constructor pattern with `setmetatable`
+- Define methods using colon syntax
+- Pre-allocate all fields in constructor

package/skills/lua-opinionated-guidelines/reference/module-pattern.md

@@ -0,0 +1,37 @@
+# module-pattern: Module Pattern
+
+**Guideline:** Use table-based module pattern with local module table and single return statement.
+
+**Rationale:** Provides clean encapsulation, avoids global namespace pollution, and creates predictable module structure that's easy to reason about.
+
+**Example:**
+
+```lua
+-- math2d.lua
+local M = {}
+
+-- Simple function in module
+function M.length(x, y)
+    return (x * x + y * y) ^ 0.5
+end
+
+function M.distance(x1, y1, x2, y2)
+    local dx = x2 - x1
+    local dy = y2 - y1
+    return M.length(dx, dy)
+end
+
+function M.normalize(x, y)
+    local len = M.length(x, y)
+    if len == 0 then return 0, 0 end
+    return x / len, y / len
+end
+
+return M
+```
+
+**Techniques:**
+- Create local module table `local M = {}`
+- Define functions as `M.function_name`
+- Return module table at end
+- One module per file

package/skills/lua-opinionated-guidelines/reference/string-concatenation.md

@@ -0,0 +1,31 @@
+# string-concatenation: String Concatenation
+
+**Guideline:** Use `table.concat()` for building strings in loops instead of repeated concatenation.
+
+**Rationale:** String concatenation with `..` creates new string objects each time. For loops, this creates many intermediate strings. Table concatenation is O(n) instead of O(n²).
+
+**Example:**
+
+```lua
+-- ❌ Bad - repeated concatenation creates many strings
+local str = ""
+for i = 1, 1000 do
+    str = str .. tostring(i) .. ","
+end
+
+-- ✅ Good - table concatenation
+local parts = {}
+for i = 1, 1000 do
+    parts[i] = tostring(i)
+end
+local str = table.concat(parts, ",")
+
+-- ✅ Good - string.format for simple cases
+local message = string.format("Player %s scored %d points", name, score)
+```
+
+**Techniques:**
+- Build array of string parts
+- Use `table.concat(parts, separator)`
+- Use `string.format()` for simple interpolation
+- Avoid `..` in loops

package/skills/moon-guidelines/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: moon-guidelines
+description: >-
+  Trigger on `.moon/`, `moon.yml` files in project config. Use when working with moonrepo for monorepo task management. Apply for task configuration, project tagging, task inheritance. Keywords: moon, monorepo, .moon/tasks, tags, task inheritance, project queries, task caching, language toolchains.
+---
+
+# Moon Build System Guidelines
+
+## Requirements
+
+- Moon ≥ 1.0, Node.js for JavaScript/TypeScript projects.
+
+## Essentials
+
+- **Task configuration** - Define in `.moon/tasks/*.yml` for auto-inheritance, see [reference/task-configuration.md](reference/task-configuration.md), [reference/task-inheritance.md](reference/task-inheritance.md)
+- **Tags** - Use for categorization, filtering, boundaries, inheritance, see [reference/tag-based-filtering.md](reference/tag-based-filtering.md)
+- **Execution** - `project:task`, `#tag:task`, `:task` (all), `--query`, `--affected`
+- **Querying** - Query projects/tasks by tags, language, or query language, see [reference/query-language.md](reference/query-language.md)
+- **Configuration** - Projects use `moon.yml`, workspace uses `.moon/workspace.yml`
+- **Toolchain** - Moon manages language toolchains, configured in workspace
+- **Caching** - Built-in task caching with output definitions, see [reference/task-configuration.md](reference/task-configuration.md)
+
+## Progressive disclosure
+
+- Read [reference/task-configuration.md](reference/task-configuration.md) - When defining or modifying task configurations
+- Read [reference/tag-based-filtering.md](reference/tag-based-filtering.md) - When filtering projects or tasks by tags
+- Read [reference/query-language.md](reference/query-language.md) - When using advanced query syntax
+- Read [reference/task-inheritance.md](reference/task-inheritance.md) - When setting up task inheritance patterns
+- Read [reference/project-constraints.md](reference/project-constraints.md) - When enforcing project boundaries
+- Read [reference/docker-multistage.md](reference/docker-multistage.md) - When building Docker images with moon scaffold

package/skills/moon-guidelines/reference/docker-multistage.md

@@ -0,0 +1,42 @@
+# docker-multistage: Moon Docker Scaffold Pattern
+
+**Guideline:** Use moon's docker scaffold command in multistage Dockerfiles for efficient monorepo builds.
+
+**Rationale:** Moon's scaffold command extracts only the necessary workspace files and dependencies, reducing build context and enabling efficient layer caching.
+
+**Example:**
+
+```dockerfile
+# Base stage
+FROM node:22-alpine AS base
+WORKDIR /app
+RUN npm install -g @moonrepo/cli
+
+# Skeleton stage
+FROM base AS skeleton
+COPY . .
+RUN moon docker scaffold my-service
+
+# Build stage
+FROM base AS build
+COPY --from=skeleton /app/.moon/docker/workspace .
+RUN npm ci
+COPY --from=skeleton /app/.moon/docker/sources .
+RUN moon run my-service:build
+RUN moon docker prune
+
+# Runtime stage
+FROM gcr.io/distroless/nodejs22-debian12:nonroot AS runtime
+WORKDIR /app
+COPY --from=build --chown=65532:65532 /app/node_modules ./node_modules
+COPY --from=build --chown=65532:65532 /app/packages ./packages
+WORKDIR /app/packages/my-service
+CMD ["dist/src/server.js"]
+```
+
+**Techniques:**
+- moon docker scaffold: Extracts workspace config and package dependencies
+- moon docker prune: Removes dev dependencies and build artifacts
+- Skeleton stage: Separates dependency resolution from source copying
+- Distroless runtime: Minimal production image with nonroot user
+- Layer ordering: Dependencies before sources for cache efficiency

package/skills/moon-guidelines/reference/project-constraints.md

@@ -0,0 +1,25 @@
+# project-constraints: Enforce Architectural Boundaries
+
+**Guideline:** Define tag-based constraints in workspace to enforce dependency rules between projects.
+
+**Rationale:** Tag-based constraints prevent architectural violations by restricting which project tags can depend on others, enforcing clear module boundaries in monorepos.
+
+**Example:**
+
+```yaml
+# .moon/workspace.yml
+constraints:
+  tagRelationships:
+    frontend: [frontend, shared]
+    backend: [backend, shared]
+    tenant-example: [tenant-example, shared]
+```
+
+**Techniques:**
+- tagRelationships: Define which tags can depend on which tags
+- Validation: Constraints checked during project graph creation and task execution
+- Violations: Prevent execution if dependencies violate constraints
+- Frontend tags: Can depend on frontend and shared tags only
+- Tenant isolation: Each tenant can depend only on own tenant and shared
+- moon check: Validate constraints without running tasks
+- Tag refactoring: Update moon.yml tags to align with constraints

package/skills/moon-guidelines/reference/query-language.md

@@ -0,0 +1,27 @@
+# query-language: Advanced Project and Task Filtering
+
+**Guideline:** Use Moon Query Language (MQL) for advanced filtering of projects and tasks.
+
+**Rationale:** MQL allows precise selection of projects using language, type, tags, and other criteria for targeted task execution and querying.
+
+**Example:**
+
+```bash
+# Query projects by language and type
+moon query projects "language=javascript && projectType=library"
+
+# Run build for typescript projects
+moon run :build --query "language=typescript"
+
+# Complex filtering
+moon run :test --query "(language=javascript || language=typescript) && projectType=application"
+```
+
+**Techniques:**
+- Operators: `=` (equals), `!=` (not), `~` (regex), `!~` (not regex), `&&` (AND), `||` (OR)
+- Project fields: language, projectType, tags, projectName, projectAlias, projectSource
+- #tag:task syntax: Use for simple single-tag filtering
+- --query flag: Use for complex multi-criterion conditions
+- Performance: Prefer exact matches (`=`) over regex when possible
+- Parentheses: Group conditions for complex boolean logic
+- Field types: language=javascript|typescript, projectType=library|application

package/skills/moon-guidelines/reference/tag-based-filtering.md

@@ -0,0 +1,28 @@
+# tag-based-filtering: Filter Tasks by Project Tags
+
+**Guideline:** Use `#tag:task` syntax to run tasks for all projects matching a specific tag.
+
+**Rationale:** Tag-based filtering enables efficient execution of tasks across related projects without listing each individually, supporting tenant isolation and feature organization.
+
+**Example:**
+
+```bash
+# Run build for all frontend projects
+moon run '#frontend:build'
+
+# Run tests for tenant-specific projects
+moon run '#tenant-example:test'
+moon run '#tenant-other:lint'
+
+# Multiple tags with query
+moon run :build --query "tags~frontend|backend"
+```
+
+**Techniques:**
+- #tag:task syntax: Target all projects with specific tag
+- Tenant tags: Use #tenant-NAME:task for tenant-specific execution
+- Multiple tags: Combine with --query and regex for complex filtering
+- Task inheritance: Define .moon/tasks/tag-*.yml for tag-specific tasks
+- Project tags: Assign tags in moon.yml for filtering categorization
+- Scoped execution: Run across multiple projects without enumeration
+- Override behavior: Project-level tasks override tag-inherited tasks

package/skills/moon-guidelines/reference/task-configuration.md

@@ -0,0 +1,38 @@
+# task-configuration: Define Inherited Tasks
+
+**Guideline:** Define tasks in `.moon/tasks/*.yml` files with inputs, outputs, and dependencies for automatic inheritance by projects.
+
+**Rationale:** Centralized task configuration prevents duplication and ensures consistent task execution across projects of the same type or language.
+
+**Example:**
+
+```yaml
+# .moon/tasks/node.yml - Inherited by all Node.js projects
+tasks:
+  build:
+    command: 'vite build'
+    inputs: [src/**, vite.config.ts]
+    outputs: [dist]
+
+  typecheck:
+    command: 'tsc --noEmit'
+    inputs: [src/**, tsconfig.json]
+    deps: ['~:build']
+
+  test:
+    command: 'vitest run'
+    inputs: [src/**, vitest.config.ts]
+    options:
+      runInCI: true
+```
+
+**Techniques:**
+- command: Shell command to execute
+- inputs: Files/globs affecting caching and task invalidation
+- outputs: Directories/files produced, cached and restored
+- deps: Task dependencies using ~:task syntax
+- options: runInCI, persistent, optional settings
+- env: Environment variables for task execution
+- platform: Constraint (node, system) for execution environment
+- Inheritance: Tasks inherit to projects based on language/type matching
+- Override: Project moon.yml can override or extend inherited tasks

package/skills/moon-guidelines/reference/task-inheritance.md

@@ -0,0 +1,30 @@
+# task-inheritance: Task Inheritance Hierarchy
+
+**Guideline:** Define tasks at appropriate levels (global, type, language, tag, project) with later definitions overriding earlier ones.
+
+**Rationale:** Hierarchical task inheritance allows global defaults with project-specific customizations, reducing configuration duplication while maintaining flexibility.
+
+**Example:**
+
+```yaml
+# .moon/tasks/node.yml - Type-based inheritance
+tasks:
+  install:
+    command: 'npm install'
+    inputs: [package.json, package-lock.json]
+
+# moon.yml - Project override
+tasks:
+  install:
+    command: 'npm ci --frozen-lockfile'
+    inputs: [package.json, package-lock.json]
+```
+
+**Techniques:**
+- Inheritance order: Global → type → language → tag → project (later overrides)
+- Type-based: .moon/tasks/node.yml, .moon/tasks/rust.yml for runtime types
+- Language-based: .moon/tasks/javascript.yml, .moon/tasks/typescript.yml
+- Tag-based: .moon/tasks/tag-TAGNAME.yml for tag-specific tasks
+- Merging: Project tasks merge with inherited tasks
+- Complete override: Redefine entire task in moon.yml to fully replace
+- Selective override: Define only fields you need to change