sync-template git:20260723.1db5b32A

Immutable. This exact content never changes and is served at /api/v1/blob/c45fcef3dec84c67.

---
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 |
|------|------|
| `.agents/skills/*/SKILL.md` | All skill definitions (canonical) |
| `.claude/skills/*/SKILL.md` | Skill stubs (frontmatter + `@` pointer to canonical) |
| `.claude/agents/*.md` | Agent definitions (read by Claude Code and Copilot) |
| `.claude/prompt-snippets/*.md` | Shared prompt snippets |
| `.claude/rules/*.md` | Auto-applied rules (read by Claude Code and VS Code Copilot) |
| `CLAUDE.md` | One-line `@AGENTS.md` pointer (template-owned, copy as-is) |
| `_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 `.agents/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:
   - .agents/skills/create-task/SKILL.md
   - .agents/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). When removing a skill, delete BOTH the canonical `.agents/skills/<name>/` directory AND its stub `.claude/skills/<name>/` directory
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

### AGENTS.md

AGENTS.md (the canonical instruction file — `CLAUDE.md` is just a one-line `@AGENTS.md` pointer) 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.

**Pre-0.6.0 workspaces**: if the local workspace still has full instructions in `CLAUDE.md` and no `AGENTS.md`, migrate first — treat the local `CLAUDE.md` content as the local `AGENTS.md` for merging purposes, write the merged result to `AGENTS.md`, and replace `CLAUDE.md` with the one-line pointer.

**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 `AGENTS.md` / `CLAUDE.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)
- Cross-Tool Compatibility (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: `<!-- sync-template: upstream also changed this section — review manually -->`

**Project-only sections** — Anything in the local AGENTS.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 AGENTS.md may have a different title or opening line (e.g., `# aws-mk0` instead of `# AGENTS.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 AGENTS.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 |
|------|--------|
| `.agents/skills/pull-all-repos/SKILL.md` | Copied from upstream |
| `AGENTS.md` | Merged (added "Git vs Local Entries" section) |
| `.gitignore` | Merged (switched to per-repo entries) |
| ... | ... |

### New files
- `.agents/skills/sync-template/SKILL.md` (+ stub in `.claude/skills/sync-template/`)

### Removed files
- `.agents/skills/create-task/` *(template skill removed in v0.5.0)*
- `.agents/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)
- When copying a skill, keep the canonical file and its stub consistent: the stub's frontmatter must match the canonical frontmatter, followed only by `@../../../.agents/skills/<name>/SKILL.md`
- **Never touch** `repos/repos.md`, `repos/*/`, `_plans/*.plan.md` (user plans), `.claude/settings*.json`, `.mcp.json`, `.codex/config.toml`
- **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