Manual synchronization of AI coding instructions is a recipe for drift. Teams often agree on a shared AGENTS.md or CLAUDE.md file, only to discover that every repository in the fleet has a slightly different, stale copy. A new tool, team-ai-sync, addresses this by centralizing these assets in a single source repository and distributing them through reviewable pull requests rather than direct writes. The stable v1 release, documented by developer paladini on DEV.to, integrates with GitHub Actions to ensure that changes to AI guidance undergo the same scrutiny as code changes.

Configuration and Workflow Integration

The setup requires a sync-config.json file in the source repository, which explicitly names target repositories and relative paths for files like .editorconfig or prompt directories. The tool supports two sync modes: 'overwrite' for replacing existing configurations and 'skip' for installing starter files without clobbering local edits. Crucially, the Action runs on Node 24 and requires a fine-grained personal access token or GitHub App token with specific 'Contents' and 'Pull requests' read/write permissions on the target repositories. This separation ensures the automation can push branches and open PRs without having merge privileges.

Dry Runs and Safety Boundaries

Before enabling automated PR creation, the workflow supports a dry-run mode that validates the configuration and clones targets into temporary worktrees to check for differences. This step is critical for identifying potential issues with deleteOrphans, a setting that removes files from targets if they no longer exist in the source. The tool explicitly avoids merging pull requests, bypassing branch protection, or approving changes. This design choice preserves the review boundary, allowing target repository owners to reject instructions that may be inappropriate for their specific language, deployment model, or security requirements.

Security Considerations and Verification

Security is handled through strict path validation; the tool rejects absolute paths, '..' traversal, and '.git' segments to prevent unintended file manipulation. The token used for synchronization should be stored as a repository secret and never committed to the workflow file. Local verification of the v1 release involved running npm ci, linting, and testing, which passed 18 tests across 6 files. However, the dependency audit reported 9 findings, including 7 high-severity issues, indicating that while the tool's logic is sound, its dependency tree requires monitoring.

Key Takeaways

  • Use dry-run: true in your first workflow execution to validate path configurations and preview changes without creating branches.
  • Keep deleteOrphans set to false by default; only enable it after careful review to avoid accidentally removing target-specific files.
  • The tool does not merge pull requests, ensuring that human review remains the final gatekeeper for AI instruction updates.
  • Separate the GITHUB_TOKEN (for source checkout) from the github-token input (for target write access) to maintain least-privilege security.

The Bottom Line

Centralizing AI guidance is only useful if it remains reviewable. team-ai-sync successfully turns a shared-file problem into a standard pull request workflow, but you must treat the token as a high-privilege write credential and always validate changes with a dry run before letting automation touch your production repositories.