agents-sync 0.1.0

package/SCHEMA.MD

@@ -0,0 +1,156 @@
+# Canonical Agents Schema (Markdown)
+
+This repo treats `.agents` as the source of truth. Each file is Markdown with an optional metadata block at the top. The watcher parses these files and generates tool-specific outputs for Claude, Gemini, and Codex.
+
+## Folder Layout
+
+`.agents/commands/` holds command definitions.
+`.agents/hooks/` holds hook definitions.
+`.agents/skills/` holds skill definitions.
+`AGENTS.MD` is the global config document.
+
+## Canonical File Format
+
+Each file is Markdown. At the top you can include a metadata fence:
+
+```agents
+id: hi
+type: command
+title: Say Hello
+description: Greet the user politely.
+aliases: hello, greet
+```
+
+Everything after the `agents` fence is the body. The body becomes the tool-specific prompt or instructions.
+
+### Required Fields
+
+`id` or `name` must be present, or it will be inferred from the filename.
+`type` can be omitted if the folder implies it (`commands`, `hooks`, `skills`).
+
+### Optional Fields
+
+`title` short label for humans.
+`description` short summary.
+`aliases` comma-separated list of alternate names.
+`event` for hooks (example: `event: pre-commit`).
+`tags` and `tools` are allowed but currently not emitted to targets.
+
+### List Fields
+
+For list fields (`aliases`, `tags`, `tools`) you can use:
+
+`aliases: hello, greet` or `aliases: ["hello", "greet"]`.
+
+## AGENTS.MD Schema
+
+`AGENTS.MD` is the canonical global configuration document. It uses the same metadata fence and body rules.
+
+Recommended template:
+
+```agents
+id: workspace
+type: config
+title: Workspace Defaults
+description: Global guidance applied across tools.
+```
+
+Use the body for shared rules, style, and constraints that should apply everywhere.
+
+## Canonical Examples
+
+### Command
+
+```agents
+id: hi
+type: command
+title: Say Hello
+description: Greet the user politely.
+aliases: hello, greet
+```
+
+Write a friendly hello and ask how the user wants to proceed.
+
+### Hook
+
+```agents
+id: before_commit
+type: hook
+title: Pre-Commit Guard
+event: pre-commit
+```
+
+Check for unstaged files and remind the user to run tests.
+
+### Skill
+
+```agents
+id: bug_triage
+type: skill
+title: Bug Triage
+description: Quick triage checklist.
+```
+
+Classify severity, confirm reproduction steps, and identify owners.
+
+### Config (Root)
+
+`AGENTS.MD` is the shared config document.
+
+```agents
+type: config
+title: Workspace Defaults
+```
+
+This is the global guidance for the workspace, shared across tools.
+
+## Translation Rules
+
+The translation layer renders tool-specific files using the canonical metadata and body.
+
+### Claude
+
+Output format: Markdown.
+Output paths:
+`.claude/commands/<id>.md`
+`.claude/hooks/<id>.md`
+`.claude/skills/<id>.md`
+`CLAUDE.MD` from `AGENTS.MD`.
+
+Mapping:
+`id` becomes the command name.
+`description`, `title`, `aliases`, and `event` are emitted as YAML frontmatter.
+Body is emitted as the command or hook prompt.
+
+### Gemini
+
+Output format: TOML.
+Output paths:
+`.gemini/commands/<id>.toml`
+`.gemini/hooks/<id>.toml`
+`.gemini/skills/<id>.toml`
+`GEMINI.MD` from `AGENTS.MD`.
+
+Mapping:
+`type`, `name`, `title`, `description`, `aliases`, and `event` become TOML keys.
+Body becomes `prompt = """..."""`.
+
+### Codex
+
+Output format: Markdown.
+Output paths:
+`.codex/commands/<id>.md`
+`.codex/hooks/<id>.md`
+`.codex/skills/<id>.md`
+`CODEX.MD` from `AGENTS.MD`.
+
+Mapping:
+Top heading `# <type>: <id>`.
+`title`, `description`, `aliases`, and `event` emitted as labeled lines.
+Body emitted as the prompt.
+
+## Notes
+
+The metadata fence must be the first block in the file to be parsed.
+Everything after the metadata fence is treated as the body.
+If metadata is missing, `type` is inferred from the folder and `id` from the filename.

package/agents.config.json

@@ -0,0 +1,22 @@
+{
+  "sourceDir": ".agents",
+  "agentsSubdir": "",
+  "targets": {
+    "claude": {
+      "outputDir": ".claude"
+    },
+    "codex": {
+      "outputDir": ".codex"
+    },
+    "gemini": {
+      "outputDir": ".gemini",
+      "agentFileExtension": ".toml"
+    }
+  },
+  "rootDoc": "AGENTS.MD",
+  "rootTargets": {
+    "claude": "CLAUDE.MD",
+    "gemini": "GEMINI.MD",
+    "codex": "CODEX.MD"
+  }
+}

package/dist/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "./index.js";

package/dist/config.js

@@ -0,0 +1,21 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { existsSync } from "node:fs";
+const DEFAULT_CONFIG = {
+    sourceDir: ".agents",
+    agentsSubdir: "",
+    targets: {},
+    rootDoc: "AGENTS.MD",
+    rootTargets: {}
+};
+export const loadConfig = async (configPath) => {
+    if (!existsSync(configPath))
+        return DEFAULT_CONFIG;
+    const raw = await fs.readFile(configPath, "utf8");
+    const parsed = JSON.parse(raw);
+    return { ...DEFAULT_CONFIG, ...parsed };
+};
+export const resolveTargetAgentsDir = (cwd, target, agentsSubdir) => {
+    const base = target.agentsOutputDir ?? path.join(target.outputDir, agentsSubdir);
+    return path.resolve(cwd, base);
+};

package/dist/index.js

@@ -0,0 +1,132 @@
+import chokidar from "chokidar";
+import path from "node:path";
+import fs from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { loadConfig, resolveTargetAgentsDir } from "./config.js";
+import { parseAgentsMarkdown, inferKindFromPath } from "./schema.js";
+import { translators } from "./translation/index.js";
+const CWD = process.cwd();
+const CONFIG_PATH = path.join(CWD, "agents.config.json");
+const ensureDir = async (dirPath) => {
+    await fs.mkdir(dirPath, { recursive: true });
+};
+const writeIfChanged = async (filePath, content) => {
+    let existing = null;
+    try {
+        existing = await fs.readFile(filePath, "utf8");
+    }
+    catch {
+        existing = null;
+    }
+    if (existing === content)
+        return;
+    await ensureDir(path.dirname(filePath));
+    await fs.writeFile(filePath, content, "utf8");
+};
+const walkFiles = async (dirPath) => {
+    const entries = await fs.readdir(dirPath, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const full = path.join(dirPath, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await walkFiles(full)));
+        }
+        else if (entry.isFile()) {
+            files.push(full);
+        }
+    }
+    return files;
+};
+const main = async () => {
+    const config = await loadConfig(CONFIG_PATH);
+    const sourceDir = path.resolve(CWD, config.sourceDir);
+    const rootDoc = path.resolve(CWD, config.rootDoc);
+    const targetEntries = Object.entries(config.targets);
+    for (const [, target] of targetEntries) {
+        await ensureDir(resolveTargetAgentsDir(CWD, target, config.agentsSubdir));
+    }
+    const syncSourceFile = async (filePath) => {
+        const rel = path.relative(sourceDir, filePath);
+        const kind = inferKindFromPath(rel);
+        if (!kind)
+            return;
+        const id = path.basename(rel, path.extname(rel));
+        const content = await fs.readFile(filePath, "utf8");
+        const doc = parseAgentsMarkdown(content, { kind, id });
+        await Promise.all(targetEntries.map(async ([targetKey, target]) => {
+            const translator = translators[targetKey];
+            if (!translator)
+                return;
+            const baseDir = resolveTargetAgentsDir(CWD, target, config.agentsSubdir);
+            const subdir = translator.subdir(doc, target);
+            const ext = translator.fileExtension(doc, target);
+            const outPath = path.join(baseDir, subdir, `${doc.id}${ext}`);
+            const translated = translator.renderDoc(doc, target);
+            await writeIfChanged(outPath, translated);
+        }));
+    };
+    const removeSourceFile = async (filePath) => {
+        const rel = path.relative(sourceDir, filePath);
+        const kind = inferKindFromPath(rel);
+        if (!kind)
+            return;
+        const id = path.basename(rel, path.extname(rel));
+        const doc = parseAgentsMarkdown("", { kind, id });
+        await Promise.all(targetEntries.map(async ([targetKey, target]) => {
+            const translator = translators[targetKey];
+            if (!translator)
+                return;
+            const baseDir = resolveTargetAgentsDir(CWD, target, config.agentsSubdir);
+            const subdir = translator.subdir(doc, target);
+            const ext = translator.fileExtension(doc, target);
+            const outPath = path.join(baseDir, subdir, `${id}${ext}`);
+            await fs.rm(outPath, { force: true });
+        }));
+    };
+    const syncRootDoc = async () => {
+        if (!existsSync(rootDoc))
+            return;
+        const content = await fs.readFile(rootDoc, "utf8");
+        const doc = parseAgentsMarkdown(content, { kind: "config", id: "root" });
+        const rootTargets = config.rootTargets;
+        await Promise.all(Object.entries(rootTargets).map(async ([targetKey, outName]) => {
+            const translator = translators[targetKey];
+            if (!translator)
+                return;
+            const outPath = path.resolve(CWD, outName);
+            const translated = translator.renderDoc(doc, config.targets[targetKey]);
+            await writeIfChanged(outPath, translated);
+        }));
+    };
+    if (existsSync(sourceDir)) {
+        const files = await walkFiles(sourceDir);
+        for (const filePath of files) {
+            await syncSourceFile(filePath);
+        }
+    }
+    await syncRootDoc();
+    const agentsWatcher = chokidar.watch(sourceDir, {
+        ignoreInitial: true,
+        awaitWriteFinish: {
+            stabilityThreshold: 150,
+            pollInterval: 50
+        }
+    });
+    agentsWatcher.on("add", syncSourceFile);
+    agentsWatcher.on("change", syncSourceFile);
+    agentsWatcher.on("unlink", removeSourceFile);
+    const rootWatcher = chokidar.watch(rootDoc, {
+        ignoreInitial: true,
+        awaitWriteFinish: {
+            stabilityThreshold: 150,
+            pollInterval: 50
+        }
+    });
+    rootWatcher.on("add", syncRootDoc);
+    rootWatcher.on("change", syncRootDoc);
+    process.stdout.write("agents-sync watching .agents and AGENTS.MD\n");
+};
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/schema.js

@@ -0,0 +1,83 @@
+import path from "node:path";
+const LIST_FIELDS = new Set(["aliases", "tags", "tools"]);
+const parseList = (raw) => {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return [];
+    if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (Array.isArray(parsed))
+                return parsed.map(String);
+        }
+        catch {
+            // fall through to comma parsing
+        }
+    }
+    return trimmed
+        .split(",")
+        .map((v) => v.trim())
+        .filter(Boolean);
+};
+const parseMetaBlock = (raw) => {
+    const meta = {};
+    const lines = raw.split(/\r?\n/);
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const idx = trimmed.indexOf(":");
+        if (idx === -1)
+            continue;
+        const key = trimmed.slice(0, idx).trim();
+        const value = trimmed.slice(idx + 1).trim();
+        if (!key)
+            continue;
+        if (LIST_FIELDS.has(key)) {
+            meta[key] = parseList(value);
+        }
+        else {
+            meta[key] = value;
+        }
+    }
+    return meta;
+};
+export const parseAgentsMarkdown = (content, fallback) => {
+    const fenceMatch = content.match(/^```agents\s*\n([\s\S]*?)\n```\s*\n?/i);
+    const meta = fenceMatch ? parseMetaBlock(fenceMatch[1]) : {};
+    const body = fenceMatch
+        ? content.slice(fenceMatch[0].length).trim()
+        : content.trim();
+    const kind = meta.type ||
+        meta.kind ||
+        fallback.kind;
+    const id = meta.id ||
+        meta.name ||
+        fallback.id;
+    const title = meta.title || undefined;
+    const description = meta.description || undefined;
+    const aliases = meta.aliases || undefined;
+    const event = meta.event || undefined;
+    return {
+        kind,
+        id,
+        title,
+        description,
+        aliases,
+        event,
+        body,
+        meta
+    };
+};
+export const inferKindFromPath = (relPath) => {
+    const parts = relPath.split(path.sep).map((p) => p.toLowerCase());
+    if (parts.includes("commands"))
+        return "command";
+    if (parts.includes("hooks"))
+        return "hook";
+    if (parts.includes("skills"))
+        return "skill";
+    if (parts.includes("config") || parts.includes("configs"))
+        return "config";
+    return null;
+};

package/dist/translation/claude.js

@@ -0,0 +1,43 @@
+/** Docs
+ * @see https://platform.claude.com/docs/en/home
+ */
+const yamlList = (label, items) => {
+    if (!items.length)
+        return [];
+    const lines = [label + ":"];
+    for (const item of items)
+        lines.push(`  - ${item}`);
+    return lines;
+};
+const renderFrontmatter = (doc) => {
+    const lines = ["---", `name: ${doc.id}`];
+    if (doc.title)
+        lines.push(`title: ${doc.title}`);
+    if (doc.description)
+        lines.push(`description: ${doc.description}`);
+    if (doc.kind === "hook" && doc.event)
+        lines.push(`event: ${doc.event}`);
+    if (doc.aliases?.length)
+        lines.push(...yamlList("aliases", doc.aliases));
+    lines.push("---");
+    return lines.join("\n");
+};
+export const renderDoc = (doc) => {
+    const parts = [renderFrontmatter(doc)];
+    if (doc.body)
+        parts.push(doc.body);
+    return parts.join("\n\n");
+};
+export const fileExtension = (_doc) => ".md";
+export const subdir = (doc) => {
+    switch (doc.kind) {
+        case "command":
+            return "commands";
+        case "hook":
+            return "hooks";
+        case "skill":
+            return "skills";
+        default:
+            return "";
+    }
+};

package/dist/translation/codex.js

@@ -0,0 +1,47 @@
+/** Docs
+ * @see https://developers.openai.com/codex/
+ */
+const sectionLine = (label, value) => {
+    if (!value)
+        return null;
+    if (Array.isArray(value)) {
+        if (!value.length)
+            return null;
+        return `${label}: ${value.join(", ")}`;
+    }
+    return `${label}: ${value}`;
+};
+export const renderDoc = (doc) => {
+    const lines = [];
+    lines.push(`# ${doc.kind}: ${doc.id}`);
+    const titleLine = sectionLine("Title", doc.title);
+    if (titleLine)
+        lines.push(titleLine);
+    const descLine = sectionLine("Description", doc.description);
+    if (descLine)
+        lines.push(descLine);
+    const aliasLine = sectionLine("Aliases", doc.aliases);
+    if (aliasLine)
+        lines.push(aliasLine);
+    if (doc.kind === "hook" && doc.event) {
+        lines.push(`Event: ${doc.event}`);
+    }
+    if (doc.body) {
+        lines.push("");
+        lines.push(doc.body);
+    }
+    return lines.join("\n");
+};
+export const fileExtension = (_doc) => ".md";
+export const subdir = (doc) => {
+    switch (doc.kind) {
+        case "command":
+            return "commands";
+        case "hook":
+            return "hooks";
+        case "skill":
+            return "skills";
+        default:
+            return "";
+    }
+};

package/dist/translation/gemini.js

@@ -0,0 +1,50 @@
+/** Docs
+ * @see https://geminicli.com/docs/
+ */
+const tomlString = (value) => {
+    const escaped = value.replace(/"""/g, "\\\"\\\"\\\"");
+    return `"""${escaped}"""`;
+};
+const tomlLine = (key, value) => {
+    if (!value)
+        return null;
+    return `${key} = ${JSON.stringify(value)}`;
+};
+const tomlArray = (key, items) => {
+    if (!items?.length)
+        return null;
+    return `${key} = [${items.map((i) => JSON.stringify(i)).join(", ")}]`;
+};
+export const renderDoc = (doc) => {
+    const lines = [];
+    lines.push(`type = ${JSON.stringify(doc.kind)}`);
+    lines.push(`name = ${JSON.stringify(doc.id)}`);
+    const titleLine = tomlLine("title", doc.title);
+    if (titleLine)
+        lines.push(titleLine);
+    const descLine = tomlLine("description", doc.description);
+    if (descLine)
+        lines.push(descLine);
+    const aliasLine = tomlArray("aliases", doc.aliases);
+    if (aliasLine)
+        lines.push(aliasLine);
+    if (doc.kind === "hook" && doc.event) {
+        lines.push(`event = ${JSON.stringify(doc.event)}`);
+    }
+    const body = doc.body ?? "";
+    lines.push(`prompt = ${tomlString(body)}`);
+    return lines.join("\n");
+};
+export const fileExtension = (_doc) => ".toml";
+export const subdir = (doc) => {
+    switch (doc.kind) {
+        case "command":
+            return "commands";
+        case "hook":
+            return "hooks";
+        case "skill":
+            return "skills";
+        default:
+            return "";
+    }
+};

package/dist/translation/index.js

@@ -0,0 +1,13 @@
+import * as claude from "./claude.js";
+import * as gemini from "./gemini.js";
+import * as codex from "./codex.js";
+const withOverrides = (base) => ({
+    renderDoc: (doc, _target) => base.renderDoc(doc),
+    fileExtension: (doc, target) => target?.agentFileExtension ?? base.fileExtension(doc),
+    subdir: (doc, target) => base.subdir(doc, target)
+});
+export const translators = {
+    claude: withOverrides(claude),
+    gemini: withOverrides(gemini),
+    codex: withOverrides(codex)
+};

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "agents-sync",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "agents-sync": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "SCHEMA.MD",
+    "agents.config.json"
+  ],
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc -p tsconfig.json",
+    "postbuild": "node scripts/add-shebang.mjs",
+    "start": "node dist/index.js",
+    "prepare": "npm run build"
+  },
+  "dependencies": {
+    "chokidar": "^3.6.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0"
+  }
+}

package/readme.md

@@ -0,0 +1,46 @@
+# agents-sync
+
+A small TypeScript watcher that keeps `.agents` as the shared source of truth and mirrors translated files into `.claude`, `.codex`, and `.gemini`. It also mirrors `AGENTS.MD` into `CLAUDE.MD`, `GEMINI.MD`, and `CODEX.MD` using the same translation rules.
+
+## Setup
+
+```bash
+npm install
+npm run dev
+```
+
+## Using As A CLI
+
+After `npm install` you can run:
+
+```bash
+npm run build
+npm link
+agents-sync
+```
+
+To use in another project:
+
+```bash
+npm i -D agents-sync
+npx agents-sync
+```
+
+## Canonical Schema
+
+The canonical format is Markdown with an optional `agents` metadata fence. See `SCHEMA.MD` for the full schema and translation rules.
+
+## Configuration
+
+Edit `agents.config.json` to change output folders or extensions.
+
+- `sourceDir`: shared canonical folder.
+- `agentsSubdir`: optional subdir within each target output (empty by default).
+- `targets`: output directories and file extensions per tool.
+- `rootDoc`: shared canonical root doc.
+- `rootTargets`: which target docs to emit.
+
+## Notes
+
+- Output files are only written when content changes.
+- Unknown folders under `.agents` are ignored unless they are `commands`, `hooks`, or `skills`.