Ag Shared Sync Log

Explicit range

When ${ARGUMENTS} contains --range <from>..<to>:

BASE="<from>"
TARGET="<to>"
# Use the provided range
CHANGES=$(git diff "$BASE"..."$TARGET" --name-only -- external/ag-shared/)

If no changes are found in external/ag-shared/, report "No ag-shared changes found in the specified range" and STOP.

STEP 2: Analyse Changes

Run these commands to understand what changed:

# File-level summary
git diff "$BASE"..."$TARGET" --stat -- external/ag-shared/

# Detailed diff
git diff "$BASE"..."$TARGET" -- external/ag-shared/

# Commit log scoped to ag-shared
git log --oneline "$BASE"..."$TARGET" -- external/ag-shared/

# Detect added/removed files
git diff "$BASE"..."$TARGET" --diff-filter=A --name-only -- external/ag-shared/
git diff "$BASE"..."$TARGET" --diff-filter=D --name-only -- external/ag-shared/
git diff "$BASE"..."$TARGET" --diff-filter=R --name-only -- external/ag-shared/

Categorise Each Changed File

Sort every changed file into one of these categories based on its path within external/ag-shared/:

STEP 3: Determine Companion Actions

Map each category of change to the companion actions consuming repos need to perform. Use this decision tree:

Symlink changes (add/remove/rename)

For added items:

• New skill directory → Add directory symlink: .rulesync/skills/<name> -> ../../external/ag-shared/prompts/skills/<name>/
• New guide/rule file → Add file symlink: .rulesync/rules/<name>.md -> ../../external/ag-shared/prompts/guides/<name>.md
• New command file → Add file symlink: .rulesync/commands/<name>.md -> ../../external/ag-shared/prompts/commands/<name>.md
• New agent file → Add file symlink: .rulesync/subagents/<name>.md -> ../../external/ag-shared/prompts/agents/<name>.md

For removed items:

• Removed skill → Remove directory symlink from .rulesync/skills/
• Removed guide → Remove file symlink from .rulesync/rules/
• Removed command → Remove file symlink from .rulesync/commands/
• Removed agent → Remove file symlink from .rulesync/subagents/

For renamed items: combine a remove + add.

Script and config changes

• scripts/setup-prompts/ changed → Run ./external/ag-shared/scripts/setup-prompts/setup-prompts.sh
• scripts/sync-rulesync/ changed → Run ./external/ag-shared/scripts/sync-rulesync/sync-rulesync.sh --apply
• prompts/patches/ changed → Run ./external/ag-shared/scripts/sync-rulesync/sync-rulesync.sh --apply
• scripts/git-hooks/ changed → Hooks auto-install; verify with ls -la .git/hooks/
• github/ changed → Review .github/workflows/ in consuming repos for alignment
• scripts/ci/ changed → Review CI configuration in consuming repos
• package.json changed → Check consuming repos' dependency declarations

Baseline actions (always include)

Every sync should end with:

• Run ./external/ag-shared/scripts/setup-prompts/setup-prompts.sh
• Run ./external/ag-shared/scripts/setup-prompts/verify-rulesync.sh

STEP 4: Generate Log Entry

Format the entry using this template:

## YYYY-MM-DD -- <short-description>

**Branch:** `<branch-name>`
**Commits:** `<base-sha>..<head-sha>` (<N> commits)

### Changes

- **[category]** <description of change>
- **[category]** <description of change>

### Migration Actions

- [ ] <action 1>
- [ ] <action 2>
- [ ] Run `./external/ag-shared/scripts/setup-prompts/setup-prompts.sh`
- [ ] Run `./external/ag-shared/scripts/setup-prompts/verify-rulesync.sh`

### Notes

<optional context, gotchas, or special instructions — omit section if nothing to note>

Guidelines for the entry:

• Short description: Derive from commit messages — summarise the theme of changes in a few words.
• Changes: One bullet per logical change, grouped by category tag. Summarise bulk changes rather than listing every file (e.g. "Updated 12 skill files to add frontmatter" not 12 separate bullets).
• Migration Actions: Concrete, actionable checklist items. Use exact commands and paths. Place symlink changes before script-run actions.
• Notes: Include only if there are gotchas, breaking changes, or special instructions. Omit the section entirely if empty.

Present the draft entry to the user for review. If ${ARGUMENTS} contains --dry-run, show the entry and STOP without writing.

STEP 5: Write to Log

1. Read external/ag-shared/docs/SYNC-LOG.md. If the file does not exist, create it with this header:

# ag-shared Sync Log

Migration log for `external/ag-shared/` changes. Each entry documents what changed and what companion actions consuming repos need to perform when syncing.

Newest entries first. Generated by `/ag-shared-sync-log`.

---

2. Insert the new entry immediately after the --- separator line following the header (i.e. prepend to the entry list so newest is first).

3. Write the updated file.

4. Report the entry was added and show the final result.

Arguments

${ARGUMENTS} can optionally include:

• --range <from>..<to> — analyse a specific commit range instead of auto-detecting.
• --dry-run — generate and display the entry without writing to the log file.
• help — show usage information.