RoleSync

RoleSync keeps one canonical set of agent roles and skills under .agents/ and renders native definitions for both Claude Code and Codex. Generated files are tracked by checksum so accidental hand-edits are detected rather than silently overwritten.

The project is intentionally a generator, not an agent runtime: it does not run a scheduler, broker credentials, enforce GitHub permissions, or provide durable background orchestration.

Install

Python 3.11+ is required. Claude Code and Codex are optional runtime dependencies and are installed separately.

# Recommended isolated CLI install
uv tool install rolesync

# Alternative
pipx install rolesync

# One-off execution
uvx rolesync --version

rolesync is currently a pre-release (1.0.0rc1) on PyPI. Since it's the only version published so far, pip/pipx/uv install it by default with no extra flags.

Quick start

rolesync init . --preset minimal --platform both
rolesync check
rolesync doctor

init refuses to replace an existing .agents/ directory. Add --install-root-guidance if you want RoleSync to append a small managed block to root AGENTS.md and, for Claude projects, CLAUDE.md. Existing files are appended to rather than replaced.

Built-in presets:

• minimal — three generic roles (orchestrator, coder, reviewer) with no mandatory GitHub planning workflow.
• github-workflow — the richer example catalog shipped by this repository for issue → implementation → review → PR work. It is an opinionated starting point, not a universal policy.

Choose --platform claude, --platform codex, or --platform both. The selection is stored in .agents/loom.json.

Commands

rolesync init [ROOT] [--preset minimal|github-workflow] [--platform both|claude|codex]
rolesync sync [--root ROOT]
rolesync check [--root ROOT]
rolesync doctor [--root ROOT]
rolesync --version

• init installs user-owned canonical sources from a built-in preset, then renders native output.
• sync validates the catalog and reconciles generated files.
• check performs the same validation/drift calculation without writing.
• doctor validates configuration and reports whether the selected Claude/Codex CLIs are currently on PATH; it does not launch paid/provider sessions.

The legacy source-tree command remains available:

python scripts/sync_agents.py
python scripts/sync_agents.py --check

Canonical project layout

.agents/
  catalog.json
  common.md
  loom.json                 optional RoleSync project settings
  policy.json               optional workflow policy; informational to the generator
  roles/<role>.md
  skills/<skill>/SKILL.md
  references/*.md           optional supporting guidance
  generated-manifest.json   generated ownership/checksum record

.claude/agents/*.md          generated when Claude is enabled
.claude/skills/**            generated byte-for-byte mirrors of canonical skill resources
.codex/agents/*.toml         generated when Codex is enabled

Only paths recorded in the validated generated manifest are owned by RoleSync. Unrelated files under .claude/ and .codex/ remain untouched.

Safety and ownership

RoleSync treats repository paths and the generated manifest as untrusted input. Managed output paths must stay inside .claude/agents/, .claude/skills/, or .codex/agents/; traversal and escaping symlink paths are rejected. Stale entries receive the same containment validation before deletion.

Synchronization is staged and guarded by a cross-process lock. Before applying a multi-file update, RoleSync stores recovery copies and a transaction journal. A later sync restores an interrupted transaction before generating new output.

Canonical skill directories may contain binary resources; they are mirrored byte-for-byte for Claude. Common transient files are ignored, while likely secret files such as .env, private keys, and PKCS#12 bundles are rejected rather than copied. This is a guardrail, not a replacement for repository secret scanning.

Defining agents

Each catalog role supplies an internal ID, lowercase-kebab-case generated name, description, role source under .agents/roles/, a skill under .agents/skills/, and provider-specific native settings. RoleSync validates required types and boundaries but intentionally does not hard-code every provider model or effort value; provider availability changes and must be verified in the installed runtime. Optional roles can set "enabled": false; disabled roles remain in canonical sources but are omitted from native discovery output until enabled.

policy.json, role activation notes, and prose permissions do not become enforcement just because they are rendered. Filesystem sandboxing, connector credentials, repository protections, and runtime settings remain the actual security boundaries.

Development and release checks

python -m unittest discover -s scripts/tests -v
python -m unittest discover -s tests -v
python scripts/sync_agents.py --check
python -m build

CI runs the test suites on Linux, Windows, and macOS using the minimum supported Python and the newest explicitly supported Python. It also installs the built wheel into a clean environment and exercises the CLI outside the source tree.

Releases are built by GitHub Actions and published to PyPI via Trusted Publishing through the protected pypi environment: publishing a GitHub Release triggers the publish.yml workflow, which builds and uploads the package automatically.

Example workflow catalog

The repository's own .agents/ catalog remains a worked example of a larger GitHub-centered team. Model routing is a starting hypothesis rather than a benchmark. The generator does not turn this example into a daemon or promise that a runtime will enforce prose-only limits.

License

MIT — see LICENSE.

Built by Brian Grubba (@ceponatia) at Snarebox LLC.