RoleX CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code when working with the RoleX project.

Project Overview

RoleX is an AI Agent Role Management Framework for defining, composing, and executing agent roles.

CommonX - Shared Infrastructure

All Deepractice projects should use commonxjs for common utilities.

Install:

bun add commonxjs

Repository: https://github.com/Deepractice/CommonX

---

SQLite

DO NOT use bun:sqlite, node:sqlite, better-sqlite3, or db0 directly.

Use commonxjs/sqlite for cross-runtime SQLite:

import { openDatabase } from "commonxjs/sqlite";

const db = openDatabase("./data/app.db"); // or ":memory:"

db.exec("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)");

const stmt = db.prepare("INSERT INTO users (name) VALUES (?)");
stmt.run("Alice");

const users = db.prepare("SELECT * FROM users").all();
console.log(users);

db.close();

Features:

• Auto-detects runtime (Bun → bun:sqlite, Node.js 22+ → node:sqlite)
• Auto-creates parent directories
• Zero external dependencies

---

Logger

DO NOT use console.log directly in production code.

Use commonxjs/logger:

import { createLogger } from "commonxjs/logger";

const logger = createLogger("rolex/module");

logger.debug("Debug message");
logger.info("Info message", { key: "value" });
logger.warn("Warning message");
logger.error("Error message");

Features:

• Lazy initialization (safe to call at module level)
• Pluggable backend via setLoggerFactory()
• Namespace-based logging

---

Path Utilities

DO NOT use import.meta.dir directly (Node.js incompatible).

Use commonxjs/path:

import {
  getModuleDir,
  getPackageRoot,
  getMonorepoRoot,
  resolveFromRoot,
  resolveFromPackage,
} from "commonxjs/path";

// Current module directory (cross-runtime __dirname)
const __dirname = getModuleDir(import.meta);

// Package root (where package.json is)
const pkgRoot = getPackageRoot(import.meta);

// Monorepo root
const root = getMonorepoRoot(import.meta);

// Resolve paths
const dataDir = resolveFromRoot(import.meta, "data");
const testFixtures = resolveFromPackage(import.meta, "tests", "fixtures");