zylos-core: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code when working with code in this repository.

Project Standards

Programming Language

• Language: Node.js (JavaScript)
• Runtime: Node.js 20+

Module System

This project is ESM-only.

• ✅ Always use import / export
• ❌ Do NOT use CommonJS (require, module.exports)
• ❌ Do NOT mix module systems

Examples:

// ✅ Correct (ESM)
import { execFileSync } from 'child_process';
import path from 'path';
import os from 'os';
import fs from 'fs';

export function myFunction() {
  // ...
}

export default myClass;

// ❌ Wrong (CommonJS)
const { execFileSync } = require('child_process');
const path = require('path');

module.exports = myFunction;

Release Process

When releasing a new version:

1. Update package.json — bump version field to the new version number
2. Update package-lock.json — run npm install to sync the lock file with the new version
3. Update CHANGELOG.md — add a new section following Keep a Changelog format with Added/Fixed/Changed/Removed subsections as applicable
4. Commit and push — include all three files in the PR
5. Merge PR first — all changes must be merged to main before tagging
6. Tag and release — after merge, create a git tag (vX.Y.Z) on main and a GitHub release with release notes summarizing the changelog

Version numbers follow Semantic Versioning.

Project Structure

• skills/ - Claude Code skills (modular workflows)
• cli/ - Command-line interface tools

Skills

Each skill is a self-contained module in skills/<skill-name>/:

• SKILL.md - Skill documentation (YAML frontmatter + usage guide)
• <skill-name>.js - Main implementation (ESM)
• package.json - Must include {"type":"module"} (add dependencies if needed)
• Other supporting files as needed

Skill Data Directory

Runtime data (logs, databases, config) goes in ~/zylos/<skill-name>/, NOT in the skill source directory.