chore(sync): track caffeinelabs/skills (commit-based) instead of retired caffeinelabs/motoko

[marc0olo]

Wires the upstream sync automation to the new Motoko upstream (caffeinelabs/skills), which #345 switched us to. That repo publishes no releases, so this reworks the detection + docs from release-based to commit-based for it. mops-cli (caffeinelabs/mops) and static-site (dfinity/certified-assets) stay release-based and are untouched.

Completes the second half of #327 (the skill migration was #345).

Changes

• .github/workflows/sync-upstream.yml — replace the check-motoko job (which polled gh release view on the retired caffeinelabs/motoko) with check-caffeinelabs-skills: it reads the pinned commit from .claude/upstream.md (the writing-motoko section — all three skills share one pin), compares it to the upstream default-branch HEAD, and on drift opens an issue labelled upstream-skills (label already created). No tag/release resolution step needed.
• scripts/sync-upstream-check.sh — swap the caffeinelabs/motoko case for caffeinelabs/skills (upstream base path skills/, three skill mappings: writing-motoko, migrating-motoko-actors, troubleshooting-motoko-migrations). Clarify that the label args are display-only (a release tag, or a short SHA for commit-tracked repos).
• .claude/CLAUDE.md — document the two tracking models (release-tracked vs commit-tracked), update the sync checklist, rewrite the "What icskills changes vs upstream" summary table (frontmatter transform, mops-cli cross-ref, references/ paths; drop the obsolete motoko-pitfalls / caffeinelabs/motoko#6156/6157 row), and generalise the automated-detection section.

Tested locally

awk pin           → 02e531673bad… (writing-motoko section)
same commit       → exit 0  "no content changes"
pinned → HEAD     → exit 1, correct issue body (branch suggestion chore/sync-upstream-skills-<sha>, per-skill diffs)

No skill content changes; npm run validate green.

Note

The local test showed upstream has already advanced (writing-motoko 0.1.3 → 0.1.5, plus more). So once this merges, the weekly job (or a manual workflow_dispatch) will open an upstream-skills sync issue — that content sync is a separate follow-up, not this PR.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Updates the upstream sync automation to track the new Motoko upstream (caffeinelabs/skills) by pinned commit SHA (since it has no releases), while keeping the existing release-based tracking for caffeinelabs/mops and dfinity/certified-assets.

Changes:

• Replaces the retired caffeinelabs/motoko release check with a commit-based caffeinelabs/skills check in the sync workflow.
• Updates the upstream-diff script’s repo mapping from caffeinelabs/motoko → caffeinelabs/skills.
• Documents the two upstream tracking models (release-tracked vs commit-tracked) and updates the automated detection docs accordingly.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
scripts/sync-upstream-check.sh	Switches Motoko upstream mapping to caffeinelabs/skills and updates commit-based framing.
.github/workflows/sync-upstream.yml	Adds a new commit-based job for caffeinelabs/skills and removes the old caffeinelabs/motoko release-based logic.
.claude/CLAUDE.md	Updates upstream-sync documentation to describe commit-tracked vs release-tracked models and the new automation behavior.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (1)

scripts/sync-upstream-check.sh:82

• list_skill_files currently treats GitHub API failures as “no files” (JSON parse errors sys.exit(0) and the trailing || true) and only warns on truncated trees. That can produce false “no changes” results and prevent the workflow from opening a sync issue when the file listing is incomplete/untrusted. Prefer failing fast when the tree can’t be reliably enumerated (API error, parse error, or truncated: true).

list_skill_files() {
  curl -sf "https://api.github.com/repos/${REPO}/git/trees/$1?recursive=1" \
    -H "Authorization: Bearer $GH_TOKEN" | \
  python3 -c "
import sys, json
prefix = sys.argv[1].rstrip('/') + '/'
try:
    d = json.load(sys.stdin)
except Exception:
    sys.exit(0)
if d.get('truncated'):
    sys.stderr.write('WARNING: git tree truncated; files under %s may be missed\n' % sys.argv[1])
for e in d.get('tree', []):
    if e.get('type') == 'blob' and e['path'].startswith(prefix):
        print(e['path'][len(prefix):])
" "$2" || true
}

[marc0olo]

Re the suppressed comment on list_skill_files (b33e763): valid — applied it. The helper now fails loudly instead of treating an untrusted listing as "no changes": a fetch error, unparseable JSON, or truncated: true returns non-zero, and the caller aborts with exit 3 (the workflow's diff step re-raises any non-0/1 code, so the job fails visibly rather than silently skipping a real upstream change). Verified: happy path still exits 1 with the nested references/* diffs; a bogus SHA now exits 3 with a clear error instead of exit 0.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (1)

scripts/sync-upstream-check.sh:74

• list_skill_files downloads the full repo tree JSON every time it’s called. Because this function is invoked once per skill (and twice per skill for OLD/NEW), the workflow ends up re-fetching the same large tree multiple times in a single run. Caching the tree per SHA within the run reduces API load and lowers the risk of rate-limit/timeout flakiness.

list_skill_files() {
  local tree
  # Fail (non-zero) on a fetch error, unparseable response, or a truncated tree — the caller
  # aborts rather than treating an incomplete/untrusted listing as "no changes" (a silent miss).
  tree=$(curl -sf "https://api.github.com/repos/${REPO}/git/trees/$1?recursive=1" \

[marc0olo]

Re the suppressed comment on list_skill_files re-fetching the tree (a2d680b): applied — split out fetch_tree() which caches each recursive tree to /tmp/upstream-tree-<sha>.json (git trees are immutable per SHA, so caching is safe) and reads from it. For caffeinelabs/skills that's now 2 fetches per run instead of 6 (3 skills × OLD/NEW). Bonus: fewer fetch points also means fewer transient-failure aborts under the fail-fast change. Verified: happy path exit 1 with exactly 2 cache files created and nested references/* still diffed; bogus SHA exit 3; same-commit exit 0.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (2)

scripts/sync-upstream-check.sh:78

• fetch_tree caches the Git Trees API response at a predictable, repo-agnostic path (/tmp/upstream-tree-${sha}.json). This can collide across different upstream repos that happen to share the same commit SHA, and it also risks leaving a partially-written cache file behind (which then won’t be refetched because it is non-empty). Use a per-run/per-repo cache directory (e.g. $RUNNER_TEMP) and write atomically via a temp file + mv.

  local cache="/tmp/upstream-tree-${sha}.json"
  if [ ! -s "$cache" ]; then
    curl -sf "https://api.github.com/repos/${REPO}/git/trees/${sha}?recursive=1" \
      -H "Authorization: Bearer $GH_TOKEN" > "$cache" || {
      echo "ERROR: could not fetch git tree for ${REPO}@${sha}" >&2

.claude/CLAUDE.md:152

• The example says it “lists all files … in the upstream skill folder”, but the git/trees/<SHA>?recursive=1 request actually returns the full repo tree for that commit and the Python filters by prefix locally. Clarifying this avoids surprising readers about the API response size and potential rate limiting.

# List all files (recursively) in the upstream skill folder at a given commit.
# Recursive matters: some skills nest files (e.g. writing-motoko/references/*).
curl -s "https://api.github.com/repos/<org>/<repo>/git/trees/<SHA>?recursive=1" | \
  python3 -c "import sys,json; p='<upstream-skill-path>/'; [print(e['path'][len(p):]) for e in json.load(sys.stdin).get('tree',[]) if e.get('type')=='blob' and e['path'].startswith(p)]"

[marc0olo]

Both suppressed comments applied (f3e1204 review):

1. fetch_tree cache — now repo-scoped and atomic: cache path is ${RUNNER_TEMP:-/tmp}/upstream-tree-<repo>-<sha>.json (keyed by repo + SHA), and the response is written to a .tmp.$$ file then mv'd into place — so the cache is only ever complete or absent (no partial/corrupt file that [ -s ] would wrongly trust). Verified: bogus SHA exits 3 leaving no partial cache.
2. CLAUDE.md manual snippet — clarified that git/trees/<SHA>?recursive=1 returns the whole repo tree and the Python filters to the skill path locally.

Both are our own content, so patched directly.

[github-actions]

Skill Validation Report

No skill files were changed in this PR — validation skipped.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.