rolesync 1.0.0rc1__tar.gz

rolesync-1.0.0rc1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Snarebox LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rolesync-1.0.0rc1/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: rolesync
+Version: 1.0.0rc1
+Summary: Generate native Claude Code and Codex agent definitions from one canonical catalog.
+Author: Brian Grubba
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ceponatia/rolesync
+Project-URL: Repository, https://github.com/ceponatia/rolesync
+Project-URL: Issues, https://github.com/ceponatia/rolesync/issues
+Keywords: ai,agents,claude,codex,developer-tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# 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.
+
+```bash
+# Recommended isolated CLI install after the package is published
+uv tool install rolesync
+
+# Alternative
+pipx install rolesync
+
+# One-off execution
+uvx rolesync --version
+```
+
+Until a PyPI release exists, install from a tagged/reviewed source checkout instead of assuming the registry name is live.
+
+## Quick start
+
+```bash
+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
+
+```text
+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:
+
+```bash
+python scripts/sync_agents.py
+python scripts/sync_agents.py --check
+```
+
+## Canonical project layout
+
+```text
+.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
+
+```bash
+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 the publish workflow is configured for PyPI Trusted Publishing through the protected `pypi` environment. Configure the matching Trusted Publisher on PyPI before publishing the first release.
+
+## 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](LICENSE).
+
+Built by Brian Grubba ([@ceponatia](https://github.com/ceponatia)) at Snarebox LLC.

rolesync-1.0.0rc1/README.md

@@ -0,0 +1,118 @@
+# 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.
+
+```bash
+# Recommended isolated CLI install after the package is published
+uv tool install rolesync
+
+# Alternative
+pipx install rolesync
+
+# One-off execution
+uvx rolesync --version
+```
+
+Until a PyPI release exists, install from a tagged/reviewed source checkout instead of assuming the registry name is live.
+
+## Quick start
+
+```bash
+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
+
+```text
+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:
+
+```bash
+python scripts/sync_agents.py
+python scripts/sync_agents.py --check
+```
+
+## Canonical project layout
+
+```text
+.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
+
+```bash
+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 the publish workflow is configured for PyPI Trusted Publishing through the protected `pypi` environment. Configure the matching Trusted Publisher on PyPI before publishing the first release.
+
+## 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](LICENSE).
+
+Built by Brian Grubba ([@ceponatia](https://github.com/ceponatia)) at Snarebox LLC.

rolesync-1.0.0rc1/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rolesync"
+version = "1.0.0rc1"
+description = "Generate native Claude Code and Codex agent definitions from one canonical catalog."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Brian Grubba"}]
+keywords = ["ai", "agents", "claude", "codex", "developer-tools"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Software Development :: Code Generators",
+]
+
+[project.urls]
+Homepage = "https://github.com/ceponatia/rolesync"
+Repository = "https://github.com/ceponatia/rolesync"
+Issues = "https://github.com/ceponatia/rolesync/issues"
+
+[project.scripts]
+rolesync = "rolesync.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+rolesync = [
+  "presets/*/*",
+  "presets/*/*/*",
+  "presets/*/*/*/*",
+  "presets/*/*/*/*/*",
+]

rolesync-1.0.0rc1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

rolesync-1.0.0rc1/src/rolesync/__init__.py

@@ -0,0 +1,4 @@
+"""RoleSync: generate native Claude Code and Codex agents from canonical sources."""
+
+__all__ = ["__version__"]
+__version__ = "1.0.0rc1"

rolesync-1.0.0rc1/src/rolesync/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

rolesync-1.0.0rc1/src/rolesync/cli.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import sys
+from importlib import metadata, resources
+from pathlib import Path
+
+from .core import RoleSyncError, CONFIG, render, sync, validate_project
+
+
+def version() -> str:
+    try:
+        return metadata.version("rolesync")
+    except metadata.PackageNotFoundError:
+        return "1.0.0rc1"
+
+
+def _preset_root(name: str):
+    base = resources.files("rolesync").joinpath("presets", name)
+    if not base.is_dir():
+        raise RoleSyncError(f"Unknown preset: {name}")
+    return base
+
+
+def _copy_resource_tree(source, destination: Path) -> None:
+    destination.mkdir(parents=True, exist_ok=True)
+    for child in source.iterdir():
+        target = destination / child.name
+        if child.is_dir():
+            _copy_resource_tree(child, target)
+        else:
+            if target.exists():
+                raise RoleSyncError(f"Refusing to overwrite existing file during init: {target}")
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_bytes(child.read_bytes())
+
+
+def _append_managed_block(path: Path, body: str) -> bool:
+    start = "<!-- rolesync:start -->"
+    end = "<!-- rolesync:end -->"
+    if path.exists():
+        text = path.read_text(encoding="utf-8")
+        if start in text or end in text:
+            raise RoleSyncError(f"{path.name} already contains a rolesync managed block")
+        prefix = text.rstrip() + "\n\n" if text.strip() else ""
+    else:
+        prefix = ""
+    path.write_text(prefix + start + "\n" + body.rstrip() + "\n" + end + "\n", encoding="utf-8", newline="\n")
+    return True
+
+
+def _prune_empty_subdirs(path: Path) -> None:
+    if not path.is_dir():
+        return
+    for child in sorted(path.iterdir()):
+        if child.is_dir():
+            _prune_empty_subdirs(child)
+            try:
+                child.rmdir()
+            except OSError:
+                pass
+
+
+def init_project(root: Path, preset: str, platform: str, install_root_guidance: bool = False) -> None:
+    root = root.resolve()
+    root.mkdir(parents=True, exist_ok=True)
+    agents = root / ".agents"
+    if agents.exists():
+        raise RoleSyncError(f"Refusing to initialize over existing {agents}; adopt it manually or run sync/check instead")
+    source = _preset_root(preset)
+    managed_dirs = (root / ".codex" / "agents", root / ".claude" / "agents", root / ".claude" / "skills")
+    preexisting_dirs = {d for d in managed_dirs if d.exists()}
+    output_paths: list[Path] = []
+    preexisting_outputs: set[Path] = set()
+    guidance_writes: list[tuple[Path, bytes | None]] = []
+    try:
+        _copy_resource_tree(source, agents)
+        platforms = ["claude", "codex"] if platform == "both" else [platform]
+        (root / CONFIG).write_text(
+            json.dumps({"schema_version": 1, "preset": preset, "platforms": platforms}, indent=2) + "\n",
+            encoding="utf-8",
+            newline="\n",
+        )
+        output_paths = [root / rel for rel in render(root)]
+        preexisting_outputs = {p for p in output_paths if p.exists()}
+        sync(root)
+        if install_root_guidance:
+            guidance = [(
+                root / "AGENTS.md",
+                "Agent definitions are maintained under `.agents/`. Follow `.agents/AGENTS.md` for agent-system maintenance. Do not hand-edit generated files under `.claude/agents/`, `.claude/skills/`, or `.codex/agents/`.",
+            )]
+            if "claude" in platforms:
+                guidance.append((root / "CLAUDE.md", "@AGENTS.md"))
+            for path, body in guidance:
+                original = path.read_bytes() if path.exists() else None
+                _append_managed_block(path, body)
+                guidance_writes.append((path, original))
+    except BaseException:
+        for path, original in guidance_writes:
+            if original is None:
+                path.unlink(missing_ok=True)
+            else:
+                path.write_bytes(original)
+        if agents.exists():
+            shutil.rmtree(agents, ignore_errors=True)
+        for path in output_paths:
+            if path not in preexisting_outputs and path.exists():
+                path.unlink(missing_ok=True)
+        for managed_dir in managed_dirs:
+            if managed_dir.exists():
+                _prune_empty_subdirs(managed_dir)
+                if managed_dir not in preexisting_dirs:
+                    try:
+                        managed_dir.rmdir()
+                    except OSError:
+                        pass
+        raise
+
+
+def _sync_command(root: Path, check: bool) -> int:
+    try:
+        problems = sync(root, check=check)
+    except (OSError, UnicodeError, RoleSyncError, KeyError, TypeError) as exc:
+        print(f"rolesync: {exc}", file=sys.stderr)
+        return 2
+    if check and problems:
+        print("Generated files differ:", file=sys.stderr)
+        for problem in problems:
+            print(problem, file=sys.stderr)
+        return 1
+    print("Generated files are current." if check else "Native agent files and mirrored skills generated.")
+    return 0
+
+
+def _doctor(root: Path) -> int:
+    root = root.resolve()
+    issues = validate_project(root)
+    if issues:
+        print(f"Project: {root}")
+        for issue in issues:
+            print(f"ERROR: {issue}")
+        return 1
+    drift = sync(root, check=True)
+    config_path = root / CONFIG
+    platforms = ["claude", "codex"]
+    if config_path.is_file():
+        config = json.loads(config_path.read_text(encoding="utf-8"))
+        platforms = config.get("platforms", platforms)
+    print(f"Project: {root}")
+    print("Configuration: valid")
+    print("Generated output: " + ("current" if not drift else "drifted"))
+    for platform in platforms:
+        executable = "claude" if platform == "claude" else "codex"
+        found = shutil.which(executable)
+        print(f"{platform}: {'found at ' + found if found else 'CLI not found on PATH (generation still works)'}")
+    if drift:
+        print("Drift:")
+        for item in drift:
+            print(f"  {item}")
+        return 1
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="rolesync", description="Generate native Claude Code and Codex agent definitions from one canonical catalog.")
+    parser.add_argument("--version", action="version", version=f"rolesync {version()}")
+    sub = parser.add_subparsers(dest="command")
+
+    init = sub.add_parser("init", help="Initialize a project from a built-in preset")
+    init.add_argument("root", nargs="?", type=Path, default=Path.cwd())
+    init.add_argument("--preset", choices=["minimal", "github-workflow"], default="minimal")
+    init.add_argument("--platform", choices=["both", "claude", "codex"], default="both")
+    init.add_argument("--install-root-guidance", action="store_true", help="Append a small managed guidance block to root AGENTS.md and CLAUDE.md")
+
+    for name, help_text in (("sync", "Validate and render native agent files"), ("check", "Report drift without writing"), ("doctor", "Validate setup and local runtime availability")):
+        cmd = sub.add_parser(name, help=help_text)
+        cmd.add_argument("--root", type=Path, default=Path.cwd())
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not args.command:
+        parser.print_help()
+        return 0
+    try:
+        if args.command == "init":
+            init_project(args.root, args.preset, args.platform, args.install_root_guidance)
+            print(f"Initialized rolesync in {args.root.resolve()}")
+            return 0
+        if args.command == "sync":
+            return _sync_command(args.root, check=False)
+        if args.command == "check":
+            return _sync_command(args.root, check=True)
+        if args.command == "doctor":
+            return _doctor(args.root)
+    except (OSError, UnicodeError, RoleSyncError, KeyError, TypeError, json.JSONDecodeError) as exc:
+        print(f"rolesync: {exc}", file=sys.stderr)
+        return 2
+    return 2
+
+
+def legacy_sync_main(default_root: Path) -> int:
+    parser = argparse.ArgumentParser(description="Render native Codex/Claude agents and mirror portable skills.")
+    parser.add_argument("--root", type=Path, default=default_root)
+    parser.add_argument("--check", action="store_true", help="Report missing/stale/drifted outputs without writing")
+    args = parser.parse_args()
+    return _sync_command(args.root, check=args.check)