agsync: Instructions file for Codex

Codebase and user instructions are shown below. Be sure to adhere to these instructions. IMPORTANT: These instructions OVERRIDE any default behavior and you MUST follow them exactly as written.

Overview

agsync is a Git-native CLI that syncs AI agent skill definitions, commands, and MCP tool bindings across Claude Code, Codex, Cursor, Windsurf, Copilot, Gemini, OpenCode, and Antigravity. It reads canonical definitions from .agsync/ and generates agent-specific output.

Architecture

src/
├── index.ts              # CLI entry point (commander)
├── agents/
│   └── registry.ts       # Agent registry — defines all agents and default feature configs
├── commands/
│   ├── init.ts           # agsync init — scaffolds project
│   ├── add.ts            # agsync skill add — imports from GitHub
│   ├── remove.ts         # agsync skill remove
│   ├── validate.ts       # agsync validate — schema + cross-ref checks
│   ├── plan.ts           # agsync plan — preview changes (dry-run)
│   ├── sync.ts           # agsync sync — config-driven plan + apply
│   ├── doctor.ts         # agsync doctor — environment health
│   └── help.ts           # agsync help — extended help text
├── loader/
│   ├── config.ts         # Loads agsync.yaml + SKILL.md/command/tool files
│   └── hierarchy.ts      # Walks up to git root merging parent configs
├── resolver/
│   └── skills.ts         # Resolves skill extends chains (local + GitHub)
├── schema/
│   └── config.ts         # Zod schemas for agsync.yaml, skills, tools
├── types/
│   └── index.ts          # All TypeScript interfaces
└── utils/
    └── env.ts            # $VAR / ${VAR} expansion for tool env values

Data flow

1. loader/ parses agsync.yaml and all referenced SKILL.md/command/tool files, validated by schema/
2. resolver/ resolves skill extends chains
3. agents/registry.ts resolves user agent config against built-in defaults
4. commands/sync.ts orchestrates: validate → plan → apply (generates .agents/ output, AGENTS.md, symlinks, MCP configs)