zylos-core: Instructions file for Codex

AGENTS.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

Tests

Tests and their fixtures are development-only. They are excluded from everything that reaches user machines: the npm package (.npmignore) and the GitHub source archive that zylos upgrade --self downloads and syncs core skills from (.gitattributes export-ignore). Users' security scanners must not find fake tokens or mock binaries in an installed zylos.