Sync Template

Sync a project with Cove Stack

Integrate relevant changes from the project's Cove Stack template while preserving the project's own behavior.

For a comparison-only request, inspect and report without applying changes. For a sync request, prepare and validate a reviewable update. Follow existing user authorization for commits, pushes, pull requests, and deployment.

Establish the project state

• Confirm the destination repository and its Cove Stack provenance.

• Read .cove.jsonc when present. It may contain:

  {
    // Used by the sync-template skill to track this project's
    // Cove Stack source and applied template revision.
    "source": "https://github.com/mugnavo/cove",
    "revision": "<exact upstream commit>",
    "createdAt": "<ISO 8601 creation time>",
    "lastSyncedAt": "<ISO 8601 successful sync time>"
  }

  source identifies the template repository. revision is initially the downloaded commit and later the newest upstream commit fully reconciled with the project. createdAt is immutable and may be absent. lastSyncedAt is absent until the first completed sync.

• Read its current AGENTS.md, relevant project guidance, package scripts, environment schema, and previous sync records.

• Record the starting commit (PROJECT_START), branch, staged and unstaged changes, and untracked files.

• Use a dedicated sync branch following the repository's naming conventions.

• Preserve unrelated work. With a dirty checkout, prefer an isolated worktree from the relevant committed state and explain which uncommitted changes it excludes. If the update depends on those changes, resolve that dependency before integrating.

• Do not silently stash, commit, discard, or copy secret-bearing files to obtain a clean checkout.

• If a merge or rebase is already in progress, identify its purpose before modifying that state.

• Establish relevant baseline check results so existing failures can be distinguished from regressions.

Resolve the upstream target

Resolve TEMPLATE_SOURCE from an explicit user choice, .cove.jsonc, previous sync records, or reliable generation and history evidence. Supported Cove Stack sources are:

• https://github.com/mugnavo/cove
• https://github.com/mugnavo/cove-monorepo

Workspace structure is supporting evidence, not proof of provenance. Ask rather than guess when the source remains ambiguous. Do not rewrite a recorded source unless correcting it is part of the requested work and the evidence is clear.

Discover the canonical repository's default branch:

git ls-remote --symref "$TEMPLATE_SOURCE" HEAD

An explicitly requested upstream branch, tag, or commit takes precedence.

Verify a remote's URL before using it. Do not assume a remote named upstream points to TEMPLATE_SOURCE, and do not repoint an existing remote or the project's origin.

Fetch the verified ref and immediately resolve its immutable commit as TARGET. Record the source URL, ref, SHA, and fetch date. If using FETCH_HEAD, resolve it before another fetch replaces it.

If remote verification is unavailable, identify any inspected local revision as cached. Do not claim it is the latest upstream version.

Establish the comparison base

Projects created from a GitHub template or starter CLI may not share Git history with Cove Stack. Check the actual history rather than assuming the project is a fork.

Look for:

• A real Git merge base.
• A previously recorded upstream revision, including .cove.jsonc's revision.
• Generation metadata or an identifiable initial starter snapshot.
• Earlier sync commits and records of intentionally omitted changes.

Before using .cove.jsonc's revision as BASE, verify that it identifies a commit from source. Treat createdAt and lastSyncedAt only as context; timestamps and dependency versions do not establish a reliable base. Check for shallow or incomplete history before concluding that no common ancestor exists.

When a verified comparison base (BASE) exists, inspect the upstream delta:

git log --oneline "$BASE..$TARGET"
git diff --stat "$BASE" "$TARGET"
git diff --name-status -M "$BASE" "$TARGET"

Review renames, deletions, and the intent of relevant commits as well as file additions.

If no reliable base exists, compare the initial project snapshot and current implementation with the target by concern. Document the uncertainty. Do not invent a base or manufacture shared history.

If the target is already integrated, review previously omitted changes before reporting that no update is needed. An older requested target requires an explicit rollback strategy; merging it does not undo newer changes.

Classify the changes

Determine ownership from file contents and local history, not directory names alone.

Current user instructions and project guidance take precedence over historical examples.

Integrate the update

Choose the strategy that fits the actual history and previous sync process.

Shared history

On a clean, dedicated sync branch, prepare a normal merge:

git merge --no-ff --no-commit "$TARGET"

--no-ff keeps a fast-forward update reviewable before committing.

Resolve conflicts by intent. Inspect files that merged cleanly too; an automatic merge can still overwrite application behavior or introduce unwanted defaults.

Continue an established selective-sync process when that is more appropriate than merging the entire upstream tree.

Unrelated history or selective updates

Apply the upstream delta from the verified base to the target rather than replacing the project with the target snapshot.

For reviewed paths, a patch generated with git diff --binary --full-index can support git apply --3way when the required base blobs are available and the index/worktree are clean. Handle moved files, deletions, and semantic changes deliberately.

When the base is unknown, reconcile relevant changes manually by concern.

Do not use a blanket copy, rsync --delete, hard reset, automatic “ours/theirs” resolution, or --allow-unrelated-histories as a shortcut. Do not create an ancestry-only merge that represents unapplied changes as integrated.