skills-marketplace/plugins/cascade-knowledge-base/skills/ckb-sync-changes/SKILL.md
Michał Kopeć 770ad03158 Update cascade-knowledge-base plugin to template 1.27.0 skills
Replace the 13 existing ckb-* skills with the template's current versions
(now including scripts/ and references/), add ckb-add-conversation,
ckb-consolidate, ckb-decide, ckb-document, ckb-feynman, ckb-module,
ckb-profile, ckb-reset, ckb-retract and ckb-routine, keep the plugin-only
meeting-notes/prep skills, and bump the plugin to 1.1.0.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-11-02 22:07:45 +01:00

9.7 KiB


name: ckb-sync-changes description: Reconcile this repo's git history with its origin remote: pull remote commits, commit local working-tree changes, resolve any conflicts with the user, then push. Pure git mechanics, no wiki synthesis. Use for "sync changes", "sync with origin", "push and pull my changes", or "reconcile git".

Sync changes skill

Purpose

Git mechanics only: every tracked path is opaque at this layer. Never invokes ingest, never re-derives entity/graph/index/log content, never reconciles Markdown semantically; a conflicted file is text with conflict markers until the user says otherwise. Unlike the exporters, this skill does commit and push on its own once any conflicts are resolved.

How to run this skill

Step 1 — Pre-flight safety checks

Run:

git rev-parse --is-inside-work-tree
git status --porcelain=v1

Check for an in-progress merge/rebase/cherry-pick:

test -f .git/MERGE_HEAD && echo "MERGE IN PROGRESS"
test -f .git/REBASE_HEAD -o -d .git/rebase-merge -o -d .git/rebase-apply && echo "REBASE IN PROGRESS"
test -f .git/CHERRY_PICK_HEAD && echo "CHERRY-PICK IN PROGRESS"

If any of these report something in progress, stop immediately. Tell the user a git operation is already underway and must be resolved or aborted manually (git merge --abort / git rebase --abort) before running this skill again. Do not try to clean it up yourself.

Scan the git status --porcelain output for paths that look like secrets: .env, .env.*, anything containing credentials, *.pem, *.key, id_rsa*, anything containing secret (case-insensitive). If any match, ask the user via AskUserQuestion whether to include or skip each one before staging anything in Step 3 — never silently commit or silently drop a flagged file.

Then check the contents of what is about to be committed:

<python> .agents/skills/ckb-lint/scripts/lint_report.py --secrets

Exit 0 (secrets: clean) means go on. On any finding, stop before staging: show the findings (they print only the first four characters of each match) and ask the user to remove the secret, allowlist a harmless match (ckb-lint check 15), or commit anyway. Commit anyway only on an explicit "commit anyway" for these findings — a secret that reaches origin has to be rotated, not just deleted. Without Python, run bash .agents/skills/ckb-lint/scripts/lint_quick.sh (or the .ps1) and treat a possible secrets count the same way.

Step 1b — Nested source repos (software module only)

If ckb.yaml lists the software module and src/ holds clones, those are independent repositories with their own remotes. This skill syncs this repo only.

  • Never git add anything under src/, and never git commit, git push, or git checkout inside one. They are gitignored; if git status shows something there, treat it as a .gitignore defect to report, not content to stage.
  • Do report each clone's state — current branch, dirty or clean, ahead or behind its own remote — so uncommitted work isn't silently forgotten while the KB itself gets pushed. Reporting is the whole contribution here; acting on it is the user's call, in that repo.

Skip this step entirely when the module isn't installed or src/ is empty.

Step 2 — Ensure origin is configured

git remote get-url origin
  • Succeeds → go to Step 3.

  • Fails (fatal: No such remote 'origin', or git remote lists nothing at all) → this repo has no remote to sync with yet. Ask the user directly (a plain question is fine here — it's a URL to paste, not a choice between options):

    "This repo has no origin remote configured. Paste the URL of the remote repository (e.g. https://github.com/org/repo.git or git@github.com:org/repo.git) and I'll add it as origin."

    Once given:

    git remote add origin <url>
    

    Then continue to Step 3 with origin now configured. If git remote add itself errors (malformed URL, etc.), report the raw error and stop — don't guess at a corrected URL or retry with a modified one.

  • A differently-named remote already exists (e.g. upstream) that looks like it might be the intended remote — don't assume. Ask the user whether that's the one to sync with (in which case, whether to alias/rename it to origin since the rest of this skill assumes that name) or whether to add a separate, new origin.

Step 3 — Detect the first-run / unrelated-histories case

git fetch origin
git rev-parse HEAD            # fails with "unknown revision" if local has no commits yet
git rev-parse origin/main     # fails if the remote branch doesn't exist/is empty
  • Local HEAD exists → go to Step 4, regardless of remote state.

  • Local HEAD doesn't exist, and origin/main doesn't exist or is empty → this is a plain first publish, not a reconciliation. Proceed automatically to Step 4 (it will just commit and push with nothing to merge).

  • Local HEAD doesn't exist, but origin/main already has commits → hard stop, every time this is detected. Show the user:

    git log origin/main --oneline | head -20
    git status --porcelain          # everything currently on local disk, untracked
    

    Then ask via AskUserQuestion with exactly these three options:

    • "Merge — bring in origin/main's history (git merge --allow-unrelated-histories origin/main after committing local content), then resolve any conflicts"
    • "Remote wins — check out origin/main first (git reset --hard is not needed since there's no local commit yet; instead branch from origin/main), then reapply my local changes on top of it"
    • "Stop — I'll sort this out myself"

    Do not offer a fourth "discard remote, force local to become main" option — that requires a force-push and is out of scope for this skill; if the user wants that, tell them it needs to be done manually. Execute only the option chosen, then continue to Step 4 with whichever git state results.

Step 4 — Steady-state flow

Order matters: commit local changes first, then fetch/merge, then push. Committing first turns any overlap into an ordinary merge conflict (which Step 5 already knows how to present), rather than a stash-pop conflict with no commit boundary to fall back on.

# Commit local changes, if any (skip entirely if git status --porcelain is clean)
git add <path1> <path2> ...        # explicit paths only — never `git add -A` or `git add .`
git commit -m "Sync: local changes as of <ISO timestamp>"

# Reconcile with remote
git fetch origin
git merge origin/main              # merge, never rebase — rebase would rewrite local commits
                                    # and require a force-push, which is out of scope here

Outcomes of the merge:

  • Already up to date. or a clean auto-merge → continue below.
  • CONFLICT → go to Step 5, then come back here once every conflict is resolved and committed.
# Push
git push origin main

If the push is rejected as non-fast-forward (the remote moved again between fetch and push), retry the fetch → merge → push cycle exactly once. If it fails again, stop and report the raw error to the user — never force, never retry more than once.

Step 5 — Present each conflict to the user

git diff --name-only --diff-filter=U

For each path returned, read the full file. It may contain more than one conflict block — handle each independently, leaving all surrounding unconflicted content untouched. Each block looks like:

<<<<<<< HEAD
(local text)
=======
(remote text)
>>>>>>> origin/main

For each block:

  • Call AskUserQuestion with the file path (and block number if the file has more than one) as context, showing both the local and remote text in full. Options: "Keep local version", "Keep remote version", "Provide merged text".
  • If "Provide merged text" is chosen, ask the user to supply the replacement text directly.
  • Rewrite the block with the chosen/provided content and strip the three marker lines for that block.
  • If the conflict is on a binary file or the markers can't be cleanly parsed, skip the "Provide merged text" option and instead resolve with git checkout --ours <path> or git checkout --theirs <path> per the user's local/remote choice.

Once every block in a file is resolved, git add that file immediately — don't wait for every file to be done before staging the first one, so progress is always visible in git status. Once every conflicted file is staged, commit:

git commit -m "Merge origin/main (conflicts resolved with user input)"

Then return to Step 4's push.

Step 6 — Report

End with a structured summary:

## Sync report

**Remote:** origin already configured (or "origin added: <url>")
**Pulled from origin/main:** <N> commit(s) — <oneline log, or "none, already up to date">
**Committed locally:** <N> file(s) — <paths>, commit <short-hash> (or "no local changes to commit")
**Conflicts encountered:** <N> (or "none")
  - <path> (block N of M) — resolved: kept local / kept remote / custom merged text
**Secrets flagged:** <files and the user's choice, or "none">
**Push result:** origin/main now at <short-hash> (or the retry/failure detail if it didn't succeed)

If anything was committed under wiki/ without a corresponding wiki/log.md (or subdirectory log.md) update in the same diff, add a one-line nudge to run Ingest/Lint afterward — this is a suggestion, not a blocker.

Edge cases

Unusual situations — an empty target, a partial run, a conflicting state, a missing dependency — are catalogued in references/edge-cases.md. Read that file when a run hits something the steps above don't cover; don't load it otherwise.