chore: sync motoko family 1.8.2 / mops cli-v2.13.2; overhaul upstream sync workflow#194
Merged
Merged
Conversation
Updates all four upstream-tracked skills to their latest release tags. motoko (1.7.0 → 1.8.2): - Add Reserved Keywords section and Quick Reference - Incorporate multi-file architecture, Module with Self Pattern, Best Practices (from PR #192) - Update compatibility to moc >= 1.7.0, core >= 2.5.0 - Trim ownership comment (M0141/variant tag/transient var now in upstream) migrating-motoko (1.7.0 → 1.8.2): - Update upstream comment and compatibility (core >= 2.5.0) - Mark What This Is and Additional References as icskills-owned migrating-motoko-enhanced (1.7.0 → 1.8.2): - Add "Add field to each record in a Map" pattern - Add "Lifecycle Example: Todo App" (four-migration chain) - Expand Restrictions section (enhanced OP, final state validation) - Simplify mops.toml (remove experimental next/build-limit fields) - Remove mops migrate new/freeze workflow (experimental, removed upstream) - Update compatibility to moc >= 1.7.0, core >= 2.5.0 mops-cli (cli-v2.13.1 → cli-v2.13.2): - Bump pinned versions: moc 1.5.1→1.7.0, lintoko 0.9.0→0.10.0, core 2.2.0→2.5.0 - Replace Migration Workflow section with Enhanced migrations (no mops migrate commands) - Add Additional References section CLAUDE.md: - Add explicit release-only policy - Add agent checklist for upstream sync (versions, evals, ownership, cross-refs) - Update upstream table to new tags and SHAs evaluations/motoko.json: - Add "Reserved keyword as field name" eval (3/3 with skill, 2/3 without)
Skill Validation ReportProject Checks |
- Workflow now opens a labelled issue instead of an empty-commit PR - Per-repo labels (upstream-motoko, upstream-mops) created idempotently; used for exact issue detection with no title parsing - Stale issue handling: when a newer release arrives before the open issue is resolved, the old issue is closed with a "Superseded" comment and a fresh issue is opened for the latest release — always at most one open issue per upstream repo - Fix diff direction in CLAUDE.md (ours vs upstream, + = new in upstream) - Fix broken SHA script in CLAUDE.md (was pseudo-code, now executable) - Add upstream file paths to the sources table in CLAUDE.md - Add Upstream-tracked Skills section to CONTRIBUTING.md for humans - Remove unused upstream-sync meta-label; per-repo labels are sufficient
…e 1:1 - Follow upstream section order exactly (Compiler Flags, Import Path Conventions, Function Literals as Arguments, Explicit Type Instantiation now restored as standalone sections) - Add Counter State mixin example (structured mutable scalar state) - Restore fuller Implicit Parameters examples showing Map initialization - Trim Pitfalls from 16 to 6: keep upstream's 2 + 4 IC-specific ones (non-stable mo:base types, Text.join order, List.get vs at, M0064) - Drop references/control-flow.md and references/type-conversions.md; Control Flow is now inline (as upstream); type conversions live in examples.md - Replace examples.md with upstream's version 1:1 (including cleaner In-Place Mutation pattern using var fields + direct mutation) - Add 4 new evals: Text.join order, List.get vs at, Runtime.envVar, import path from nested file Filed caffeinelabs/motoko#6155 for the transient timerId discrepancy in upstream's examples.md (var timerId used where transient is correct).
SKILL.md upstream comment: - Add examples.md as a second tracked upstream file - Name the specific icskills-owned pitfalls (3-6) and error rows so a future agent knows exactly what to preserve CLAUDE.md: - Add "Upstream files" column to sources table, noting which skills have reference files to sync alongside SKILL.md - Add "Reference files synced" checklist item with explicit instructions for the motoko examples.md - Fix stale "What icskills changes" row (was M0141/M0145, now reflects current owned sections: Prerequisites, Canister Env Vars, Pitfalls 3-6) sync-upstream.yml: - Also diff references/examples.md against upstream's examples.md for the writing-motoko skill so changes surface in the sync issue
Previously the workflow hard-coded examples.md as the only reference to diff. If upstream adds a new .md file, agents and the workflow would silently miss it. Now: the workflow uses the GitHub contents API to list all .md files in the upstream skill directory, diffs each against our references/, and surfaces any file we don't have locally as "NEW upstream file" in the issue body. Updated the CLAUDE.md checklist to match: the reference files step is now general (not motoko-specific) and mentions the "NEW upstream file" flag in the issue body.
The rule is: sync any file referenced from the upstream SKILL.md that lives within the upstream skill's folder, placing it in our references/ directory regardless of how upstream organises its files. Updated three places: - Upstream comment format template: add Files: with → notation, explain the references/ placement rule - "Checking for upstream changes": add reference file diff commands and explain how to find what files to check (read upstream's links) - Agent checklist: reframe from "references/ directory" to "files referenced from upstream SKILL.md", making the rule source-driven not structure-driven
…dundant content - motoko: sync M0141 code comment; drop redundant pitfalls (mo:base already in Critical Requirements, M0064 moved to error table); drop Prerequisites (covered by mops-cli skill) and Canister Environment Variables (covered by icp-cli skill); update mops.one/core → mops.one/core/docs - migrating-motoko: 1:1 body with upstream (minor wording, What This Is removed) - migrating-motoko-enhanced: 1:1 body with upstream (Actor Syntax greet(), Common Patterns filename comments, mops.toml setup placement) - mops-cli: 1:1 body with upstream (remove all icskills additions: Prerequisites, icp-cli integration note, Common Pitfalls, Additional References) - evaluations/motoko.json: drop Canister Environment Variables eval (section removed from motoko skill; content now owned by icp-cli skill)
…then checklist - .claude/upstream.md: new single tracking file for all upstream skills (replaces HTML comment blocks in SKILL.md files); contains repo URL, tag, commit SHA, last synced date, file mappings, icskills-owned sections, and pending upstream issues - CLAUDE.md: point tracking to upstream.md; add two checklist items — 'All upstream additions applied' (review > lines in diff, including code block comments) and 'Icskills-only content audited' (every < line must be tracked or removed); fix diff notation (> not + for upstream additions); fix branch naming to use upstream repo name not skill name; update What icskills changes table with M0064/M0145 ownership and issue links - sync-upstream.yml: read pinned tag from .claude/upstream.md via awk instead of grepping SKILL.md HTML comments
…emoved commands mops migrate new/freeze were experimental commands dropped upstream. The "Migration workflow" (mops-cli) and "Workflow with mops" (migrating-motoko-enhanced) evals were still testing for those commands, causing false failures. Update both to test the current workflow: manually create a timestamped migration file, then mops check --fix and mops build. Also update the trigger query that referenced the removed commands.
"Actor with Map collection", "Mixin structure", and "Full canister with multiple features" were asking for full implementations that hit the 120s eval timeout. Scope each to "just the actor body / mixin file — no mops.toml or deploy steps" per the CLAUDE.md eval prompt guidelines. Also fix two actor-declaration expected behaviors: prompts scoped to actor body only (no mops.toml) should expect `persistent actor`, not plain `actor` — the flag has nowhere to go without mops.toml context. Full canister: reduce from 9 to 6 expected behaviors to match the narrowed prompt (3 operations instead of 4).
… behaviors - Simple actor: `persistent actor` needs no flag — flag only applies to plain `actor` - Mixin structure: read-only functions correctly use `public query func`, not shared
…o-enhanced, and mops-cli - motoko: case (null) with parens, matching skill examples - motoko: record spread eval uses mapInPlace (findIndex+put doesn't exist in mo:core) - motoko: full canister allows both spread and direct mutation for toggle - migrating-motoko-enhanced: mops.toml behavior 2 no longer implies manual per-canister flag - mops-cli: mo:base rejection is about deprecation, not persistence stability - mops-cli: scope migration file trigger to avoid overlap with migrating-motoko-enhanced - mops-cli: replace duplicate trigger with distinct moc toolchain query
…behaviors - migrating-motoko: NewUser type may be imported from types.mo — only OldUser must be inline - migrating-motoko-enhanced: Init migration return type may use var for mutable actor fields - mops-cli: Migration workflow eval now tests only mops-cli knowledge; file format details (timestamp prefix, func migration name) belong in migrating-motoko-enhanced, not here
…binary lazily on next build
… migrating-motoko - motoko: drop Caffeine-to-icp-cli eval — skill has no Caffeine content - motoko: drop Caffeine should_trigger - motoko: non-stable types — drop redundant mo:base import behavior (other behaviors cover it) - motoko: List.get vs List.at — scope prompt explicitly to mo:core/List to avoid base ambiguity - motoko: adversarial base imports — fix behavior 2: deprecated + no HashMap in mo:core - migrating-motoko: preupgrade adversarial — drop mechanism behavior the skill doesn't teach
… checks - motoko M0220: accept either fix (flag OR keyword) rather than requiring both - migrating-motoko implicit migration: drop "list all implicit changes" — correct answer doesn't require volunteering unrequested context - mops-cli running mops check: drop per-canister args explanation — correct command is what matters, not whether the agent explains the mechanism
- motoko: soften adversarial base-imports behavior 2 (exact phrasing too strict); rephrase Text.join behaviors to avoid JSON parse error in judge output - mops-cli: soften "Updating moc to latest" behavior 2; replace ambiguous "add migration file" trigger with mops-check-only query; drop specific module-path requirement from mo:base adversarial (mops not motoko's job) - migrating-motoko-enhanced: replace "Configure mops.toml" trigger with "set up migrations/ directory" to avoid routing to mops-cli
- upstream.md: migrating-motoko and migrating-motoko-enhanced entries now explicitly list the extra `mops-cli` cross-reference link in Additional References (previously undocumented — would be silently dropped on sync) - CLAUDE.md: split cross-reference row into two; add dedicated row for the extra mops-cli link in migration skills; clarify section rename (Additional Resources → Additional References)
This was referenced May 28, 2026
- Workflow now fetches all files in the upstream skill folder at both the old pinned commit and the new release commit, then diffs those two upstream versions against each other. The previous approach (local file vs upstream new) produced noise from all icskills-owned sections. - Any file type in the skill folder is diffed, not just .md files. - If no files changed between releases, the workflow exits silently — no issue is opened and upstream.md is not updated. - Stale issue management moved to after diff computation so it only runs when there are actual changes to surface. - Issue body wording updated: points to .claude/upstream.md for owned sections (the old "upstream comment block" no longer exists). - Issue body notes to check whether newly shipped upstream content now covers any icskills-owned section, so duplicates can be dropped. - CLAUDE.md: updated diff commands, checklist, and automated detection description to match the corrected upstream-vs-upstream approach.
Move the skill diff computation and issue body building out of the
inline workflow YAML into scripts/sync-upstream-check.sh. The workflow
is now thin orchestration (tag comparison, SHA resolution, issue
management); the script holds all the diff logic and is independently
runnable locally:
GH_TOKEN=<token> bash scripts/sync-upstream-check.sh \
caffeinelabs/motoko <old-sha> <new-sha> 1.8.2 1.9.0 /tmp/body.md
Exit codes: 0 = no changes, 1 = changes found (issue body written).
Skill mappings are keyed by org/repo inside the script; adding a new
upstream repo means adding a case entry there, not touching the workflow.
Move the label creation, stale issue detection, close-with-comment, and issue open logic out of both workflow jobs into scripts/sync-upstream-open-issue.sh. The workflow's "Manage and open sync issue" step in each job is now a single script call. The workflow is down to 189 lines; all logic lives in the two scripts.
Issue titles are work item labels, not commit messages. The chore: prefix is a Conventional Commits convention for commits and PRs — it does not belong on GitHub issue titles. The upstream-motoko/upstream-mops labels already categorize the issues. Updated CLAUDE.md to match.
…ling, pre-create labels - sync-upstream-check.sh: validate GH_TOKEN upfront — previously a missing token caused silent false negatives (file listings returned empty, "no changes" reported incorrectly) - Workflow: replace if/else exit code handling with set +e / rc=$? / case so unexpected errors (exit 2) propagate as step failures instead of being silently treated as "has_changes=true" - Pre-create upstream-motoko and upstream-mops labels in the repo; remove label creation from sync-upstream-open-issue.sh — it was a no-op on every run and the color/description were unnecessary params - sync-upstream-open-issue.sh simplified to 3 params: label, title, body-file
- Checking for upstream changes: replace vague "also diff reference files" paragraph with explicit file-listing API command and per-file diff loop; replace <path> placeholder with explicit instruction to read the upstream-skill-path from upstream.md - Agent checklist: upstream.md update item now calls out that all skill entries sharing an upstream repo (motoko x3) must be updated together - For humans and agents step 2: clarify the issue body diff is deterministic (upstream-vs-upstream, fixed SHAs) and does not go stale; drop the stale note from the issue body template in the script - For humans and agents step 3: explicitly say one branch covers all affected skills; instruct agent to update all corresponding upstream.md entries
raymondk
approved these changes
May 29, 2026
marc0olo
added a commit
that referenced
this pull request
May 29, 2026
raymondk
added a commit
that referenced
this pull request
Jun 1, 2026
…utor workflow (#198) * docs: recommend skill-creator for new skill drafting Replace the template-copy workflow with the Anthropic skill-creator skill as the recommended starting point. Add explicit callouts for the IC-specific metadata block (title, category) that skill-creator does not produce, and clarify the two-phase eval workflow: skill-creator's internal loop for iterative drafting vs. the committed evaluations/ file required for PRs. Also remove prescriptive body section recommendations from CLAUDE.md — structure is individual to each skill and better left to skill-creator. * docs: extend skill-creator guidance to cover skill improvements * docs: require eval review and testrun before any skill PR * docs: fix inconsistencies in contributing guide and agent instructions * docs: clarify IC evals are kept as regression safety net * feat: install skill-creator and fix remaining doc inconsistencies Install skill-creator as a project skill via `npx skills add` so it is auto-discovered by Claude Code without manual loading. Files land at .agents/skills/skill-creator/ (multi-agent canonical location) with a symlink at .claude/skills/skill-creator for Claude Code. Doc fixes: - Update skill-creator references to reflect it is pre-installed - Step 3 renamed "Review and finalize" to avoid implying manual authoring - Step 6 leads with porting evals from skill-creator's evals.json - "Keep it flat" bullet now correctly allows references/ subdirectory - "see step 5 above" cross-reference replaced with anchor link - CLAUDE.md: add three-file instruction for adding a new category - CLAUDE.md: mark _template/ as legacy in Project Structure * fix: correct upstream diff direction in CONTRIBUTING.md (introduced by #194) * chore: remove legacy skill template; use skill-creator to draft new skills * feat: add improve-ic-skill, patch skill-creator bugs, remove skills-lock - Add internal improve-ic-skill skill (.agents/skills/improve-ic-skill/) for token-efficient improvement of existing skills. Uses our toolchain (npm run validate, evaluate-skills.js with targeted flags), knows eval location (evaluations/<skill-name>.json), handles upstream-tracked skills, and seeds evals when none exist. Distinct from skill-creator which is for new skill creation only. - Fix 4 confirmed bugs in vendored skill-creator (documented in PATCHES.md): 1. generate_review.py: escape </script> in JSON output to prevent viewer breakage 2. SKILL.md: add missing run-1/ level in output paths (aggregate_benchmark.py requires it) 3. SKILL.md: require eval-0-descriptive-name/ format (aggregator globs eval-*) 4. SKILL.md: clarify --static is wrong for Claude Code; use server mode instead - Remove skills-lock.json from git and add to .gitignore. Our skill-creator copy is a patched fork — npx skills add would overwrite fixes silently. Intentional updates must re-apply patches from PATCHES.md. - Update CLAUDE.md: distinguish improve-ic-skill vs skill-creator, warn against npx skills add updates, clarify that PR eval results must come from evaluate-skills.js (with-skill vs baseline), not skill-creator internals. - Add gitignore entries for skill-creator artifacts (skills/*-workspace/, **/__pycache__/, skills-lock.json). * docs: add targeted eval guidance to upstream sync checklist * feat(improve-ic-skill): require explicit problem statement before starting any work * docs(skill-creator): add upstream commit SHA and install date to PATCHES.md * fix(skill-creator): replace PyYAML with stdlib parser in quick_validate.py (Patch 5) * fix(skill-creator): add explicit field name warning to grader.md (text/passed/evidence) * fix: address all review findings — improve-ic-skill, CONTRIBUTING.md, CLAUDE.md, PATCHES.md - CONTRIBUTING.md: route improvements to improve-ic-skill (not skill-creator); fix nonexistent skills/<name>/evals/evals.json path reference - improve-ic-skill: remove redundant eval run from Step 8 (Step 7 covers it); add upstream sync guidance for seeding evals from the diff when none exist - CLAUDE.md: add improve-ic-skill mention in upstream sync workflow; align sync checklist eval policy with general improvement policy - PATCHES.md: reorder patches 4 and 5 into sequential order * fix: correct diff notation, clarify Cowork in PATCHES.md, improve Step 8 PR link * fix: resolve all remaining review findings - CONTRIBUTING.md: rename 'That's it' step to 'No site edits needed' - CLAUDE.md: remove redundant eval command from Workflow section; point to Evaluations section for the full command reference - CLAUDE.md: fix stale Project Structure (src/data/ → src/lib/, remove non-existent SiteLayout, components/*) - CLAUDE.md: clarify branch naming — <skill-name> is the IC skill name; document combined-branch pattern for multi-skill syncs * fix: final consistency pass — all third-review findings addressed - CLAUDE.md: clarify 'Body content' row in upstream table (not icskills-owned) - CLAUDE.md: scope PR eval requirement to new skills only (line 67) - CLAUDE.md: fix Project Structure paths (already committed, included here) - improve-ic-skill: add #8-submit-a-pr anchor to CONTRIBUTING.md link - CONTRIBUTING.md: add improve-ic-skill and branch naming note to sync section - PATCHES.md: clarify upstream commit date vs vendored date labels * fix: clarify branch naming placeholder and PATCHES.md commit SHA label * feat(improve-ic-skill): hold the line — do not proceed without a clear problem statement * fix(improve-ic-skill): hard stop in Step 0 — no work without specific problem, no exceptions for pushback * feat(icp-cli): add instructions for running parallel pocket-ics in worktrees (#200) --------- Co-authored-by: raymondk <raymond.khalife@dfinity.org>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Upstream sync (motoko 1.8.2 / mops cli-v2.13.2)
motoko,migrating-motoko,migrating-motoko-enhancedto caffeinelabs/motoko 1.8.2 (commitf45204bc)mops-clito caffeinelabs/mops cli-v2.13.2 (commit59d4c5f2).claude/upstream.mdtracking entries for all four skills; documents icskills-owned sections by nameUpstream sync workflow overhaul
scripts/sync-upstream-check.sh; issue management →scripts/sync-upstream-open-issue.sh(both executable, locally runnable)set +e / case $rcin both jobs;GH_TOKENfail-fast in diff script; unexpected errors now fail the job rather than silently settinghas_changes=trueupstream-motokoandupstream-mopslabels created in repo; removed per-run label creation from scriptchore:prefix (that's a commit convention, not an issue title convention)<path>placeholder, one-branch-per-upstream-repo rule, three-skill update rule for caffeinelabs/motoko; removed incorrect "diff may be stale" note (upstream-vs-upstream diff is deterministic given fixed SHAs)Evals
Full eval runs (with baseline) for all four upstream-synced skills. Eval fixes across
motoko,migrating-motoko-enhanced,mops-cli.motoko — 34/35 output + 20/20 triggers
migrating-motoko — 18/18 output + 8/10 triggers
migrating-motoko-enhanced — 25/25 output + 12/12 triggers
mops-cli — 34/36 output + 20/20 triggers
Upstream Improvements Filed
Evals identified four areas where upstream content would help agents:
Map.map()module-level function in mo:corePreviously filed (covered by this sync): #6155, #6156, #6157
Closes #184