Generate migration log entries for ag-shared changes. Use when changes have been made to external/ag-shared/ and you need to document what changed and what companion actions consuming repos need to perform when syncing. Also use when preparing to sync ag-shared across repos, after completing work that touched ag-shared files, or when the user asks about migration steps for ag-shared changes.
Generate structured migration log entries for changes to external/ag-shared/. The log captures what changed and what companion actions consuming repos need to perform when they pull these changes, so sync operations have a ready-made checklist instead of re-deriving everything from scratch.
The log lives at external/ag-shared/docs/SYNC-LOG.md and travels with the subrepo.
If the user provides a command option of help:
Identify the commit range to analyse for ag-shared changes.
When no explicit range is provided:
# Find the default branch
DEFAULT_BRANCH="latest"
git rev-parse --verify "origin/$DEFAULT_BRANCH" >/dev/null 2>&1 || DEFAULT_BRANCH="main"
# Find the merge base
BASE=$(git merge-base HEAD "origin/$DEFAULT_BRANCH")
TARGET="HEAD"
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
# Verify there are ag-shared changes
CHANGES=$(git diff "$BASE"..."$TARGET" --name-only -- external/ag-shared/)
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.
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/
Sort every changed file into one of these categories based on its path within external/ag-shared/:
| Path Pattern | Category | Tag |
|---|---|---|
prompts/skills/<name>/ | Skill | [prompts/skills] |
prompts/guides/<name>.md | Guide/Rule | [prompts/guides] |
prompts/commands/<name>.md | Command | [prompts/commands] |
prompts/agents/<name>.md | Agent/Subagent | [prompts/agents] |
prompts/patches/ | Patch | [prompts/patches] |
prompts/.claude-settings.json | Config | [prompts/config] |
prompts/.mcp.json | MCP Config | [prompts/config] |
scripts/setup-prompts/ | Setup Scripts | [scripts/setup-prompts] |
scripts/sync-rulesync/ | Sync Scripts | [scripts/sync-rulesync] |
scripts/git-hooks/ | Git Hooks | [scripts/git-hooks] |
scripts/ci/ | CI Scripts | [scripts/ci] |
scripts/subrepo/ | Subrepo Wrapper | [scripts/subrepo] |
scripts/* (other) | General Scripts | [scripts] |
github/ | GitHub Workflows | [github] |
src/ | Runtime Code | [src] |
docs/ | Documentation | [docs] |
| Other | Miscellaneous | [other] |
Map each category of change to the companion actions consuming repos need to perform. Use this decision tree:
For added items:
.rulesync/skills/<name> -> ../../external/ag-shared/prompts/skills/<name>/.rulesync/rules/<name>.md -> ../../external/ag-shared/prompts/guides/<name>.md.rulesync/commands/<name>.md -> ../../external/ag-shared/prompts/commands/<name>.md.rulesync/subagents/<name>.md -> ../../external/ag-shared/prompts/agents/<name>.mdFor removed items:
.rulesync/skills/.rulesync/rules/.rulesync/commands/.rulesync/subagents/For renamed items: combine a remove + add.
scripts/setup-prompts/ changed → Run ./external/ag-shared/scripts/setup-prompts/setup-prompts.shscripts/sync-rulesync/ changed → Run ./external/ag-shared/scripts/sync-rulesync/sync-rulesync.sh --applyprompts/patches/ changed → Run ./external/ag-shared/scripts/sync-rulesync/sync-rulesync.sh --applyscripts/git-hooks/ changed → Hooks auto-install; verify with ls -la .git/hooks/github/ changed → Review .github/workflows/ in consuming repos for alignmentscripts/ci/ changed → Review CI configuration in consuming repospackage.json changed → Check consuming repos' dependency declarationsEvery sync should end with:
./external/ag-shared/scripts/setup-prompts/setup-prompts.sh./external/ag-shared/scripts/setup-prompts/verify-rulesync.shFormat 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:
Present the draft entry to the user for review. If ${ARGUMENTS} contains --dry-run, show the entry and STOP without writing.
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`.
---
Insert the new entry immediately after the --- separator line following the header (i.e. prepend to the entry list so newest is first).
Write the updated file.
Report the entry was added and show the final result.
${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.