agent-sync-action: Skill for Claude Code

Coordinate Repositories

Carry out the caller's task consistently across the selected repository collection without treating matching names or layouts as proof of matching behavior.

Workflow

1. Determine whether the workspace is local and sibling repositories can be safely coordinated. Use filesystem layout, remotes, environment markers, and accessible siblings as evidence. In a cloud, ephemeral, or ambiguous environment, do not search broadly or mutate other repositories; report the limitation or ask the user.
2. Repair malformed local Git refs before bypassing a repository. When Git identifies an invalid ref, resolve its exact path under the repository's common Git directory, confirm that target is malformed, delete only that ref, verify it is gone, and retry the failed Git operation. Do not preserve a known-bad ref by routing the row through another checkout or clone. Use a fresh isolated clone only when the original repository remains unusable for a different reason after the ref repair.
3. Determine the bounded repository collection from the current repository, accessible sibling repositories and worktrees, prior targets in the active coordination task, and the user's scope. A repository named in prose, shown in a screenshot, linked as an example, or currently checked out identifies evidence or an origin by default; it narrows the target collection only when the user explicitly limits scope to that repository. Discover Git repositories independently of task-specific files or configuration, search bounded collection roots first, normalize remote identities, and deduplicate multiple checkouts or worktrees of the same remote. Never crawl unrelated locations.
4. Freeze a typed target manifest before mutation. Add one repository row per normalized remote and, when the caller requests local convergence, one local-installation row per matching existing editable installation after resolving its real path and ownership. Record the intended outcome and explicit expected and forbidden postconditions for every row. Track repository rows through pending, changed, committed, pushed, and remote-verified; track local rows through pending, snapshotted, changed, restore-failed, and local-verified. A local row's snapshotted state includes the durable snapshot path, complete pre-change digest, and resolved target path. restore-failed is nonterminal; a terminal skipped or blocked row always carries a concrete reason and must either be unchanged or have its pre-change digest restored. Interruption, context compaction, tool failure, or partial success never shrinks the manifest; resume from its first nonterminal row.
5. Fetch each candidate and inspect its current remote default branch. Use that authoritative tree to read complete relevant artifacts and enough nearby guidance to establish applicability and repository-specific behavior. Never let a stale, dirty, non-default, or detached local checkout exclude a repository or determine applicability.
6. When the caller identifies or changes canonical artifacts, inspect every applicable repository before finalizing them. Never leave a reusable change only in the repository whose failure, screenshot, link, or checkout exposed the need. Fold repository-neutral consumer guidance into the canonical source and validate it first. Whenever a requested cross-repository change conflicts with a target repository's existing behavior, guidance, configuration, contract, or other relevant context, immediately pause the entire cross-repository operation. Present the exact target state and requested change, assess whether the target state is reusable as generic guidance, and use the platform's structured ask-question or input tool, when available, to ask whether to propagate the reusable guidance, leave the target unchanged, or choose another resolution. Recommend propagation when the target state is generic or can be expressed as useful generic guidance for other repositories; otherwise recommend removing the target-only state. If that tool is unavailable, times out, or returns no choice, ask the same question in chat and remain paused; never infer a resolution. Before the caller chooses, do not propagate any change to any repository or local installation, mutate or distribute the conflicting change, or commit, push, open or update pull requests, mark pull requests ready, merge, or otherwise advance any affected or unaffected repository row.
7. Choose the task mode:
   • For a read-only task, gather evidence from every applicable repository and merge it into one clearly attributed result.
   • For a change or review-and-fix task, use an isolated worktree based on that repository's remote default branch. Leave original checkouts, branches, and unrelated dirty work untouched.
   • For a caller-selected local-installation row, never create a missing installation. Confirm that the resolved target remains inside an exposed writable user-level skill root and is neither managed nor generated. Before changing canonical-managed files in place, create and verify a complete snapshot under codex/coordination/<run-id>/local-installations/ in the current repository's resolved common Git directory, then persist its real path and digest in the manifest. Never use an ephemeral temporary directory as the only recovery copy.
8. Carry only user-authorized task artifacts into each isolated worktree or local installation. Never copy unrelated work, generated outputs, credentials, secrets, machine-specific configuration, or provider metadata such as agents/openai.yaml. Do not automatically preserve, adapt, or remove a target's conflicting state; the explicit conflict decision in step 6 controls it. If the task manages generated files, resolve canonical sources first and use the owning generator rather than hand-editing generated outputs.
9. Validate every completed repository with its relevant native checks. When the complete diff is non-runtime — it does not change executable source, package or dependency definitions, tests, runtime configuration, CI workflows, generated runtime artifacts, or another executed-behavior contract — validate only the checks appropriate to its artifacts, exact contents, and git diff --check; application tests and CI are irrelevant and must not be run or awaited. This is semantic rather than path-based: agent instructions, documentation, policies, static metadata, and non-executable configuration can live anywhere. When behavior changes, tests must exercise current functional outcomes through the normal interface. A test is invalid when its reason for existing depends on knowing the prior implementation or contract, even if it asserts only the replacement. Do not add rename, migration, compatibility, rejection, absence, source-text, AST, grep, count, or structural tests whose purpose is to distinguish the result from retired behavior. Update behavior-oriented tests to use the resulting contract and remove tests that exist only because something was replaced. A valid test must still make sense to a reader with no knowledge of what came before.
10. Before selecting a worktree or reusing a pull request, query the hosting service for the branch's current pull request and verify its state, branch, and task scope. Never infer active state from a local branch, remote-tracking branch, remembered URL, or prior output. Treat a merged, closed, missing, or branch-deleted pull request as absent: create a fresh isolated worktree and branch from the current remote default branch, then open a focused pull request. Reuse only a verified open pull request for the same active branch and task scope.
11. Immediately before committing and again before pushing, fetch the current remote pull-request head and base with explicit refspecs, verify the fetched object IDs equal the hosting service's current head and base object IDs, and reconcile drift. Never assume a fetch updated a remote-tracking ref merely because it downloaded an object.
12. Query current remote mergeability against the latest default-branch head. Treat UNKNOWN or an equivalent pending state as nonterminal. When a pull request conflicts, merge its current fetched base into its current fetched head and resolve every file semantically. Preserve the authorized result and compatible newer base behavior; never select an entire ours or theirs side without inspecting both meanings. Regenerate owned outputs and lockfiles from resolved sources, remove every conflict marker, run git diff --check and native checks, commit and push the resolution, then re-query mergeability. Block only the affected row when safe resolution requires an unauthorized product or contract decision.
13. Write each commit from the receiving repository's perspective with generic, repository-independent wording. Never name an origin, destination, sibling, or comparison repository in another repository's commit history.
14. After pushing changed repository rows and updating local rows, give an independent validation sub-agent the frozen manifest and exact expected and forbidden postconditions, including current mergeability and local-installation ownership. It must read every current remote pull-request head, or the current remote default branch when no open pull request exists, and every current local-installation path, returning every mismatch rather than samples. Reconcile mismatches and repeat the audit until every row is terminal. If a local mutation or verification fails, restore the complete installation from its recorded snapshot and verify the restored digest equals the pre-change digest before marking the row blocked with both paths and the failure evidence. A failed restore enters restore-failed; it remains nonterminal, prevents overall completion, and must be retried or escalated until restoration succeeds. If a validation sub-agent is unavailable, perform the same full remote and local audit in a separate pass after discarding local assumptions. Immediately recheck remote head stability and local file digests after the audit.
15. Report every completed, skipped, or blocked repository and local installation; the applied or gathered result; validation; and a clickable Markdown link for every pull request created, updated, reviewed, or merged. Never substitute a count, repository name, pull-request number, or bare URL for a required link. Never report completion while any row is nonterminal, conflicting, mergeability-unknown, head-unstable, locally unverified, or otherwise unverified.