sync-template · diff

git:20260410.879fbaf to git:20260723.1db5b32

1 added, 257 removed. Audit A to B.

---

name: sync-template

description: Pull latest repo-of-repos template updates into this workspace

user-invocable: true

origin: template

---

- # Sync Template

- Pull the latest repo-of-repos template changes into this workspace without overwriting project-specific content.

- ## Overview

- This workspace was created from the [repo-of-repos](https://github.com/raffertyuy/repo-of-repos) template. The template evolves — new skills, improved agents, better docs. This skill brings those updates into your workspace while preserving your project-specific configuration.

- ## Arguments

- The user may optionally specify:

- - `/sync-template` — use default upstream (`raffertyuy/repo-of-repos`, branch `main`)

- - `/sync-template <github-org/repo>` — use a custom upstream fork

- - `/sync-template --branch <branch>` — use a specific branch

- ## Order of Operations

- 1. **Check versions** — compare local vs upstream

- 2. **Fetch upstream** — clone template to a temp directory

- 3. **Read changelog** — understand what changed and why

- 4. **Copy safe files** — framework files that have no project-specific content

- 5. **Smart-merge mixed files** — files with both template and project content

- 6. **Update version** — write the new `TEMPLATE_VERSION`

- 7. **Report** — summarize what changed

- ## Step 1: Check Versions

- 1. Read the local `TEMPLATE_VERSION` file at the project root. If it doesn't exist, assume `0.0.0` (pre-versioned workspace).

- 2. Fetch only the upstream `TEMPLATE_VERSION` file:

- ```bash

- gh api repos/<upstream>/contents/TEMPLATE_VERSION --jq '.content' | base64 -d

- ```

- 3. Compare versions. If already up to date, inform the user and stop.

- 4. If the upstream is newer, continue.

- ## Step 2: Fetch Upstream

- Clone the upstream template to a temporary directory:

- ```bash

- git clone --depth 1 --branch <branch> https://github.com/<upstream>.git /tmp/repo-of-repos-upstream

- ```

- Clean up this directory when done (in the final step).

- ## Step 3: Read Changelog

- Read `TEMPLATE_CHANGELOG.md` from the upstream clone. Identify all versions between the local version and the upstream version. This tells you:

- - **What files changed** and why

- - **Migration notes** — special handling needed (e.g., `.gitignore` strategy change)

- - **New files** that need to be created locally

- Present a summary to the user before proceeding: which versions will be applied and what the key changes are.

- ## Step 4: Copy Safe Files

- These are framework files with no project-specific content. Copy them directly from the upstream clone, overwriting local versions:

- | Path | What |

- |------|------|

- | `.claude/skills/*/SKILL.md` | All skill definitions |

- | `.claude/agents/*.md` | Agent definitions |

- | `.claude/prompt-snippets/*.md` | Shared prompt snippets |

- | `.claude/rules/*.md` | Auto-applied rules |

- | `.github/agents/*.md` | Copilot agent mirrors |

- | `.github/instructions/*.instructions.md` | Copilot instruction mirrors |

- | `_plans/README.md` | Plan system docs |

- | `docs/*.md` | Reference documentation |

- **New files**: If the upstream has new skills, agents, rules, or prompt snippets that don't exist locally, create them (including any new directories). When creating skill or agent files, ensure the `origin: template` frontmatter field is present (copy it from upstream as-is).

- **Removed template files**: Some skills or agents may have been removed from the template (e.g., `/create-task` and `/list-tasks` were removed in v0.5.0). To detect these:

- 1. Scan local `.claude/skills/*/SKILL.md` and `.claude/agents/*.md` for files that have `origin: template` in their frontmatter

- 2. For each such file, check if the corresponding path exists in the upstream clone

- 3. If a local `origin: template` file is **NOT** present in upstream → it was intentionally removed from the template

- 4. Show the user a list of these orphaned template files and ask for confirmation before deleting:

- ```

- The following template-owned skills/agents no longer exist in the upstream template:

- - .claude/skills/create-task/SKILL.md

- - .claude/skills/list-tasks/SKILL.md

- Delete these? [y/N]

- ```

- 5. If confirmed, delete the files and their parent directories (only if the directory contains no other files)

- 6. Local skills/agents **without** `origin: template` are project-custom — never touch them

- ## Step 5: Smart-Merge Mixed Files

- These files contain both template content and project-specific content. You (the agent) are the merge tool. For each file:

- 1. Read the **upstream version** (from temp clone)

- 2. Read the **local version** (from workspace)

- 3. Read the relevant **changelog entries** for context on what changed and why

- 4. **Intelligently merge** — apply the template updates while preserving project-specific content

- ### CLAUDE.md

- CLAUDE.md is the most complex merge target. Live projects customize it heavily — different persona, project-specific architecture, custom coding standards, additional sections. The template evolves its framework sections independently.

- **Classify every section as one of:**

- | Classification | What it means | Merge strategy |

- |----------------|---------------|----------------|

- | **Template-owned** | Section exists in both template and local, content is purely framework | Replace with upstream version |

- | **Template-seeded, project-customized** | Section originated from template but the project has modified it | Three-way merge (see below) |

- | **Project-only** | Section exists only in the local file | Preserve as-is, keep in its current position |

- **Template-owned sections** (replace with upstream):

- - Project Structure (intro paragraph, bullet list of git repos / local folders)

- - Per-Repo Instructions (table of `CLAUDE.md` / `AGENTS.md` / `copilot-instructions.md`)

- - Workspace Manifest (the `repos.yaml` description paragraph)

- - Git vs Local Entries (comparison table)

- - Read/Write Separation

- - Plan System

- - Prompt Snippets (the explanation paragraph)

- - Agentic Configuration Sync (table + rules)

- - Self-Improvement

- **Template-seeded sections that projects commonly customize** (three-way merge):

- - **Persona / Voice & Personality** — The template ships a default persona (Tony Stark). Projects may keep it, modify it, or replace it entirely. If the local version differs from the template default, **preserve the local persona**. Only apply upstream changes if the template's persona section gained new structural elements (e.g., new `Do NOT` rules) — append those to the local version.

- - **Writing Style** — Projects may add style rules. Preserve local additions, update template-originated rules.

- - **Coding Standards** — The template references a prompt snippet. Projects may add inline standards. Preserve local additions.

- - **Commit Message Style** — Same as above.

- **Three-way merge procedure:**

- 1. Read the **upstream** section

- 2. Read the **local** section

- 3. Identify what the local version **added, removed, or changed** relative to what the template would have had

- 4. Apply the upstream update as the new base

- 5. Re-apply the local modifications on top

- 6. If a local modification conflicts with an upstream change (both changed the same content), **prefer the local version** and add a comment: ``

- **Project-only sections** — Anything in the local CLAUDE.md that has no counterpart in the upstream template. Common examples:

- - Architecture notes, system diagrams

- - Data flow descriptions

- - API contracts, schema references

- - Team conventions, on-call notes

- - Environment-specific setup

- - Custom rules or overrides

- These must be **preserved in their current position** in the file. If an upstream update adds a new template section, insert it in the correct position relative to other template sections, but never displace project-only sections.

- **Section ordering:** Follow the upstream's section order for template sections. Project-only sections stay where the user placed them. If a project-only section is between two template sections, keep it between them (or at the end if the surrounding template sections were reordered).

- **First-line / title:** The local CLAUDE.md may have a different title or opening line (e.g., `# aws-mk0` instead of `# CLAUDE.md`). Preserve the local title.

- ### README.md

- README.md is the public face of the project. Live projects replace the template description, customize the project tree, add project-specific sections, and may remove template sections that don't apply.

- **Classify every section as one of:**

- | Classification | What it means | Merge strategy |

- |----------------|---------------|----------------|

- | **Template-owned** | Pure framework documentation | Replace with upstream version |

- | **Template-seeded, project-customized** | Originated from template, modified by project | Three-way merge |

- | **Project-only** | Exists only in the local file | Preserve as-is |

- | **Template-removed** | Exists in template but project intentionally deleted it | Do NOT re-add |

- **Template-owned sections** (replace with upstream):

- - Plan-Implement Workflow

- - Slash Commands (tables)

- - Agents (table + read/write separation explanation)

- - MCP Servers

- - Keeping Up to Date

- - Further Reading

- - Customization

- - Prior Art & Inspiration

- - License

- **Template-seeded sections that projects commonly customize** (three-way merge):

- - **Project title and description** — The very top of the README. Projects replace the template name, description, and "The Problem / The Solution" with their own. **Always preserve the local version.** If the upstream added an "upstream template link" line and the local doesn't have it, suggest adding it but don't force it.

- - **Project Structure (tree)** — Projects add their own repos, remove example entries, add non-repo directories. Preserve the local tree structure. Only update the **template framework entries** (`.claude/`, `.github/`, `_plans/`, `docs/`, etc.) if the upstream added new files or directories to those paths. Never remove project-specific tree entries.

- - **Getting Started** — Projects may simplify or customize setup steps. Preserve local modifications. Update only if the upstream changed core workflow (e.g., new required step, changed command syntax).

- - **Slash Commands** — The tables of available commands. **Regenerate from upstream** but preserve any project-specific skills the local version added. Check: if the local table has a skill not in the upstream, keep it. If upstream added a new skill, add it.

- - **Agents** — Same strategy as Slash Commands — merge table, preserve local additions.

- - **MCP Servers** — Preserve the local table (projects add their own servers). Only add new entries from upstream if the template introduced a new default MCP server.

- **Detecting intentionally removed sections:**

- If a template section exists in the upstream but NOT in the local README, the project likely removed it intentionally. **Do NOT re-add it.** Instead, note it in the sync report:

- ```

- | Further Reading | Skipped (not present locally — likely intentionally removed) |

- ```

- If unsure whether removal was intentional, ask the user before re-adding.

- **Three-way merge procedure:** Same as CLAUDE.md (see above).

- **Section ordering:** Follow the local file's ordering. If upstream introduces a new section, insert it in a logical position relative to existing sections.

- ### .gitignore

- - Apply the template's ignore strategy (e.g., per-repo entries vs blanket glob)

- - Preserve any project-specific ignore entries

- - If the strategy changed (e.g., blanket `repos/*/` → per-repo entries), generate the correct entries based on the current `repos/repos.yaml`

- ### repos/repos.yaml

- - Update **header comments only** (field documentation)

- - **NEVER** touch actual repo entries — those are entirely project-specific

- ### TEMPLATE_CHANGELOG.md

- - Copy directly from upstream (this file is template-owned)

- ## Step 6: Update Version

- Write the upstream version string to the local `TEMPLATE_VERSION` file.

- ## Step 7: Cleanup and Report

- 1. Remove the temp clone directory: `rm -rf /tmp/repo-of-repos-upstream`

- 2. Report a summary:

- ```

- ## Template Sync: v0.2.0 → v0.3.0

- ### Files updated

- | File | Action |

- |------|--------|

- | `.claude/skills/pull-all-repos/SKILL.md` | Copied from upstream |

- | `CLAUDE.md` | Merged (added "Git vs Local Entries" section) |

- | `.gitignore` | Merged (switched to per-repo entries) |

- | ... | ... |

- ### New files

- - `.claude/skills/sync-template/SKILL.md`

- ### Removed files

- - `.claude/skills/create-task/` *(template skill removed in v0.5.0)*

- - `.claude/skills/list-tasks/` *(template skill removed in v0.5.0)*

- ### Key changes

- - Local source folder support (see TEMPLATE_CHANGELOG.md for details)

- ### Next steps

- - Review the changes with `git diff`

- - Commit when satisfied: `/commit`

- ```

- ## Notes

- - **Never delete local files** unless they have `origin: template` in frontmatter AND are absent from upstream (and even then, always confirm with user first)

- - Local skills/agents without `origin: template` are project-custom — ignore them entirely during sync

- - When copying any skill or agent file from upstream, preserve the `origin: template` frontmatter field (it will already be there — don't strip it)

- - **Never touch** `repos/repos.md`, `repos/*/`, `_plans/*.plan.md` (user plans), `.claude/settings*.json`, `.mcp.json`, `.vscode/mcp.json`

- - **Always preserve** project-specific content in mixed files — when in doubt, keep both

- - If the merge is ambiguous, show both versions to the user and ask which to keep

- - The changelog is your guide — read it before merging to understand intent, not just diffs

+ @../../../.agents/skills/sync-template/SKILL.md