sync

# Sync Child Project from Parent Template Pull improvements from a parent template into the current child project. This is the counterpart to the `feedback` skill — feedback pushes changes UP, sync pulls changes DOWN. ## When to Use - After the `feedback` skill commits changes to a parent template - When a child project was forked before recent parent improvements - When the user notices their template files are outdated compared to the parent - Periodically, to keep child projects aligned with the latest template conventions ## Prerequisites - **`$PROJECT_TEMPLATES_DIR`** — directory containing all template repos - The current project must have a `stack.json` with a `parent` field - The parent template must be available locally (or cloneable from GitHub) ## Step 1: Identify Parent and Current Level Read `stack.json` from the current project: ```bash cat stack.json ``` Extract: `level`, `parent`, `stack`. If `parent` is null (Level 0), there is nothing to sync from — inform the user and stop. ## Step 2: Locate Parent Template Use the same fallback chain as the `feedback` skill: 1. `$PROJECT_TEMPLATES_DIR/{parent}/` 2. `../{parent}/` 3. Offer to clone from `git@github.com:$PROJECT_TEMPLATES_GITHUB_ORG/{parent}.git` ## Step 3: Compare Files Compare key template files between parent and child. Focus on files that are inherited (not project-specific): ### Files to Compare | Category | Files | |----------|-------| | Process skills | `.claude/skills/brainstorming/`, `planning/`, `tdd/`, `debugging/`, `verification/` | | Core workflow skills | `.claude/skills/commit/`, `pr/`, `plan-feature/`, `code-review-project/`, `retro/`, `sync/`, `fix-issue/`, `init-stack/` (templates that predate the skills layout: `.claude/commands/<name>.md`, including `plan.md` and `review.md`) | | Rules | `.claude/rules/safety.md`, `search-before-building.md`, `project-conventions.md` | | Agent | `.claude/agents/code-reviewer.md` | | Settings template | `.claude/settings.local.json.example` | | Docs structure | `docs/architecture.md`, `docs/code-style.md`, `docs/api-conventions.md` | | Scripts | `scripts/sync-context.sh` (mirrors the shared rules into `.cursor/`) | | Editor config | `.editorconfig` | ### Files to Skip (project-specific) Do NOT sync these — they contain project-specific content: - `stack.json` (different level and parent) - `CLAUDE.md` and `AGENTS.md` (customized per project) - `.env.example` (may have project-specific additions) - `.mcp.json` (the server set follows the project's stack) and `.claude/settings.json` (its `enabledPlugins` follow the project's `stack.json`) - `project-config/SKILL.md` (contains resource IDs) - Any domain-specific skills, agents, or rules ### How to Compare For each file in the comparison list: ```bash # Check if file exists in both PARENT_FILE="$PARENT_DIR/$FILE_PATH" CHILD_FILE="./$FILE_PATH" if [ -f "$PARENT_FILE" ] && [ -f "$CHILD_FILE" ]; then # Compare content diff "$PARENT_FILE" "$CHILD_FILE" elif [ -f "$PARENT_FILE" ] && [ ! -f "$CHILD_FILE" ]; then echo "NEW in parent: $FILE_PATH" elif [ ! -f "$PARENT_FILE" ] && [ -f "$CHILD_FILE" ]; then echo "ONLY in child: $FILE_PATH (may be project-specific)" fi ``` ## Step 4: Present Diff Summary Show the user what changed: ``` ## Sync Report: {child-project} ← {parent-template} ### New in Parent (not in your project) - .claude/skills/new-skill/SKILL.md — {description from skill frontmatter} - .claude/rules/new-rule.md ### Modified in Parent (your version differs) - .claude/skills/commit/SKILL.md — {brief description of changes} - .claude/rules/safety.md — {brief description of changes} - scripts/sync-context.sh — {brief description of changes} ### Unchanged - .claude/skills/brainstorming/SKILL.md — identical - (... list of identical files) ### Skipped (project-specific) - stack.json, CLAUDE.md, AGENTS.md, .env.example, .mcp.json, .claude/settings.json, project-config/SKILL.md ``` ## Step 5: User Decision For each changed file, ask the user: > "How should I handle each difference? > (a) **Accept parent** — overwrite your version with the parent's version > (b) **Keep yours** — keep your project's version unchanged > (c) **Merge** — manually merge the changes (I'll show both versions) > (d) **Skip all** — don't sync anything" For new files from the parent, default to accepting them (they're new capabilities). For modified files, show the diff and let the user decide per file. ## Step 6: Apply Changes For each file the user chose to accept or merge: 1. Copy the parent version to the child project (or apply the merge) 2. Track which files were synced ## Step 7: Check .env.example, .mcp.json and CLAUDE.md These project-specific files are skipped from automatic sync, but may have relevant additions in the parent. Compare them separately and suggest manual updates. For `.mcp.json` suggest only servers and `${VAR}` references that are new in the parent; never write a literal URL or token into the child's `.mcp.json`: > "The parent template's `.env.example` has new variables that your project doesn't have: > - `VERCEL_PROJECT_ID` (added in parent on 2026-03-28) > > Want me to add these to your `.env.example`? (Your existing values won't be affected.)" For CLAUDE.md, highlight new sections or gotchas added to the parent: > "The parent template's CLAUDE.md has a new Gotchas section. Want me to add these gotchas to your CLAUDE.md?" ## Step 8: Summary ``` Sync complete: {child-project} ← {parent-template} - Accepted: {N} files from parent - Kept: {N} files as-is - Merged: {N} files manually - New additions: {N} files - .env.example: {updated/skipped} - CLAUDE.md: {updated/skipped} ```