Quick Summary
Goal: Bring all four framework folders, .claude/, .codex/, .agents/ and .opencode/, up to the upstream version (default: the main branch of https://github.com/duc01226/easy-claude) by merging, never by copying, so every skill, hook, agent, setting and framework edit the project made survives. .claude/ is merged; the other three are rebuilt from it by the closing sync, so they also carry the project's own skills and hooks.
Summary: Preflight → dry run → settle what needs a decision → apply → resolve conflicts → verify and report. One script downloads the upstream and runs the merge engine; you handle only what it cannot decide.
Workflow:
- Preflight — clean framework folders, Node 18+, Git, network (or a local upstream checkout).
- Dry run —
--dry-run --json; read the base, counts, conflicts, mirror-only skills, mirror clashes and project-only files.
- Decide — ask the user only about mirror-only skills, mirror clashes, a doubtful base or a dirty tree.
- Apply — the same command without
--dry-run, pinned to the upstream commit and base the dry run showed.
- Resolve — read
references/merge-guide.md and settle every conflict, keeping both sides' intent.
- Verify and report — no markers, JSON parses, the sync passes; report what changed and what stayed.
Key Rules:
- MUST ATTENTION run only on the user's explicit request; never start it on your own or as a step of other work.
- MUST ATTENTION never delete, overwrite or "clean up" a project-owned file (a path upstream never shipped). The engine never merges, moves or deletes them, only recomputes their
<!-- COUNT --> values; you change one only with the user's agreement (for example renaming a skill whose name upstream now also uses).
- MUST ATTENTION never copy upstream files over the project, and never hand-edit
.agents/, .codex/, .opencode/ or AGENTS.md: they are regenerated from .claude/.
- MUST ATTENTION the update is finished only when the closing sync has passed: until then
.codex/, .agents/ and .opencode/ still hold the old version.
- Commit or push only when the user asks. The update and
.claude/framework-lock.json belong in the same commit.
Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).
Contents
The command
Run from the project root on Windows, macOS or Linux (plain node; no npm, no package.json):
node .claude/skills/framework-update/scripts/update-from-upstream.mjs --dry-run --json
node .claude/skills/framework-update/scripts/update-from-upstream.mjs --base=<commit from the dry run>
| Option |
Use it when |
--ref=<branch|tag|commit> |
the user names a version other than main |
--upstream=<git-url|folder> |
the user names another repository or a fork, or the network is blocked and a local easy-claude checkout exists; default is the URL in the lock, else the GitHub repository |
--base=<commit> / --base=auto |
no lock yet: the dry run detects the base by content (auto); pin that commit when applying |
--no-sync |
the user wants to run the mirror sync later |
--record-only |
the project was just synced by hand: record the version without changing files |
--project=<folder> |
updating another project from an easy-claude checkout |
--engine=local |
the upstream version's engine cannot run (the default upstream runs the newest merge rules) |
The script keeps a blobless clone in tmp/framework-update/upstream.git (commits and folder listings only; file contents download in batches), so later runs only fetch what is new. Exit code: 0 done · 1 fatal · 2 something left to resolve (a conflict or a mirror clash).
What is whose
| Path |
Owner |
What the update does |
A .claude/ file upstream ships, has shipped since the base, or the lock lists |
framework |
Unchanged in the project → takes upstream (or deletes it when upstream deleted it). Changed only in the project → kept. Changed on both sides → three-way merge; overlaps get conflict markers. |
Any other .claude/ file: project skills, hooks, agents, scripts, protocols, ledgers |
project |
Never merged, moved or deleted; only its <!-- COUNT --> values are recomputed. Listed as projectOnly. |
settings.local.json, .ck.local.json |
each person |
Never taken from upstream. |
SKILLS.yaml, skills_data.yaml, <!-- COUNT --> values |
generated |
Regenerated from the project's own skill set, never merged. |
.agents/, .codex/, .opencode/, AGENTS.md, opencode.json skill permissions |
generated mirrors |
Rebuilt from the merged .claude/ by the closing sync (/sync-codex, which hands off to the OpenCode sync when .opencode/ exists): upstream's new mirror files arrive, retired ones go, and the project's own skills, agents and hooks are mirrored too. |
.agents/skills/<name> with no .claude/skills/<name> source |
project |
The sync keeps it and prints one kept line, but it reaches no other host; the engine lists it as mirrorOnly and still runs the sync. When a framework skill new in this update takes its name, the new skill's mirror would replace it: the engine lists it as a mirror clash (mirrorClashes) and skips the sync. The mirror of a framework skill the project no longer has (upstream retired it) is the framework's: the engine removes it. |
docs/, CLAUDE.md, docs/project-config.json, everything outside the four folders |
project |
Never touched. |
Procedure
1. Preflight
git status --porcelain -- .claude .agents .codex .opencode AGENTS.md opencode.json must print nothing. Otherwise ask the user to commit or stash those changes first (the engine refuses, so the update stays one reviewable, undoable diff). Mention that a separate branch keeps the update easy to review.
node --version (18+) and git --version must work. Git 2.29 or newer downloads the upstream files in batches; older Git still works, file by file and much slower (the engine prints a WARNING). The script reports a network failure; offer --upstream=<local easy-claude checkout> as the fallback.
- When the project uses Codex or OpenCode mirrors, check them for hand edits before they are rebuilt:
node .claude/skills/sync-codex/scripts/run-codex-sync.mjs --only=sync-divergence. A reported file differs from what .claude/ generates; inspect it, and port a deliberate edit into its .claude/ source first (a merely stale mirror needs nothing).
2. Dry run
Run --dry-run --json (plus any --ref / --upstream the user gave) and read:
upstream.commit against the lock's source.commit: equal means the project is already current. Say so and stop.
upstream.url: when it is not https://github.com/duc01226/easy-claude.git (a fork or mirror the lock remembers from an earlier --upstream), name it to the user; its code is what will be merged.
baseDetection (projects without a lock): matched of projectFiles files match commit. Show its date and subject with git -C tmp/framework-update/upstream.git log -1 --format="%h %cs %s" <commit>. Below about 80% matched, the project was likely copied from a fork or another project, or heavily edited: ask the user to confirm the commit or name the version they copied.
taken, deleted, merged, kept, conflicts, mirrorOnly, mirrorClashes, projectOnly.
3. Decide
Ask once, in one question, only about what needs the user:
- Mirror-only skills (
mirrorOnly): recommend moving each into .claude/skills/<name>/, where it becomes canonical and is mirrored to every host; check the name is free and its SKILL.md frontmatter has name and description. The alternative is keeping it Codex-only in .agents/skills/ (right for a skill another tool installed there): the sync leaves it in place. Carry out the answer after step 4: the engine refuses to run on uncommitted changes.
- Mirror clashes (
mirrorClashes): a Codex-only skill whose name a framework skill new in this update also uses. Recommend renaming the project's skill (its folder and the name in its SKILL.md, then every reference: git grep -n <old-name>), so both stay. The alternative is letting upstream's skill take the name: remove the project's skill, then run the sync. Carry out the answer after step 4, before the sync.
- A doubtful base (step 2).
Proceed without asking when nothing needs a decision: the tree is clean and everything is undoable through Git.
4. Apply
Run the command without --dry-run, pinned to what the dry run showed: --ref=<upstream.commit>, and on a first update --base=<baseDetection.commit>. A newer main pushed in between is then not taken unseen. The engine writes the merge, the lock and regenerated catalogs and counts, then runs the mirror sync unless a conflict or a mirror clash stops it. Then carry out step 3's answers: move each mirror-only skill the user chose to move (git mv .agents/skills/<name> .claude/skills/<name>), and rename or remove each clashing one.
5. Resolve conflicts
Read references/merge-guide.md before touching a conflict. It covers marker conflicts, settings and other JSON files, a skill name upstream now also ships, files one side deleted, and code both sides fixed. Each conflict-side file has upstream's copy under tmp/framework-update/<path>.
6. Verify and report
- No markers left:
git grep -n -E "^(<<<<<<< project|=======$|>>>>>>> upstream)" -- .claude prints nothing (a reported ======= line can be a Markdown heading underline; check it).
- Every changed JSON file parses:
node -e "JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'))" <file>.
- Every hook command in
.claude/settings.json names a file that exists.
- After moving or renaming any skill (mirror-only skills, a name clash), rebuild the catalogs and counts:
node .claude/scripts/framework-update.mjs --regenerate.
- Run the sync if the engine skipped it, and again after moving or renaming a skill:
node .claude/skills/sync-codex/scripts/run-codex-sync.mjs. It rebuilds .agents/, .codex/ and .opencode/, and its verify-sync-divergence and verify-opencode-* stages prove they match the merged .claude/. A mirror-only skill the user kept in .agents/skills/ stays as it is, with one kept .agents/skills/<name> line. A sync failure is a finding: compare it with a run on the commit before the update before calling it new.
- A stale root
CLAUDE.md reported by the sync → offer /ai-context-refresh. New framework switches → node .claude/scripts/framework-features.cjs lists them with their defaults.
- Report: from and to versions, counts, how many project-only files stayed untouched, each conflict and how it was settled, what still needs the user, and verification results. Show
git status --short totals, not the full list.
A project without this skill yet
Update it once from any easy-claude checkout; the update brings this skill along:
git clone --filter=blob:none https://github.com/duc01226/easy-claude.git <scratch-folder>/easy-claude
node <scratch-folder>/easy-claude/.claude/skills/framework-update/scripts/update-from-upstream.mjs --project=<project> --dry-run
Troubleshooting
| Symptom |
Fix |
uncommitted changes in .claude, … |
commit or stash them; --allow-dirty-project only when the user accepts mixing them into the update diff |
No upstream commit shares a file with this project |
ask the user which version they copied and pass --base=<commit> |
… is not a branch, tag or commit of the upstream |
check --ref; a commit from a pull request needs its full hash |
| clone or fetch fails |
proxy or offline: clone easy-claude elsewhere and pass --upstream=<that folder>; its local main branch is taken, so pull it first |
| the user wants to undo before committing |
git restore --staged --worktree -- followed by only those of .claude .agents .codex .opencode AGENTS.md opencode.json that exist (a missing path makes Git refuse the whole command); then preview new files with git clean -n -- <same paths> and remove them only after the user confirms |
Closing Reminders
MUST ATTENTION run only on the user's explicit request. MUST ATTENTION never delete or overwrite a project-owned file, never copy upstream over the project, and never hand-edit a generated mirror. MUST ATTENTION the update covers .codex/, .agents/ and .opencode/ only once the closing sync passes. MUST ATTENTION read references/merge-guide.md before resolving any conflict and keep both sides' intent; ask the user when the intents clash. Commit or push only on request, with the lock in the same commit.
1---2name: framework-update-23description: '[Utilities] Use only when the user asks to update or upgrade the .claude/.codex/.agents/.opencode skills framework to the latest easy-claude version. Merges upstream main into the project and keeps its own skills, hooks, agents, settings and edits.'4metadata:5 source: https://skillmd.com/skills/duc01226/framework-update-26---78## Quick Summary910**Goal:** Bring all four framework folders, `.claude/`, `.codex/`, `.agents/` and `.opencode/`, up to the upstream version (default: the `main` branch of `https://github.com/duc01226/easy-claude`) by **merging**, never by copying, so every skill, hook, agent, setting and framework edit the project made survives. `.claude/` is merged; the other three are rebuilt from it by the closing sync, so they also carry the project's own skills and hooks.1112**Summary:** Preflight → dry run → settle what needs a decision → apply → resolve conflicts → verify and report. One script downloads the upstream and runs the merge engine; you handle only what it cannot decide.1314**Workflow:**15161. **Preflight** — clean framework folders, Node 18+, Git, network (or a local upstream checkout).172. **Dry run** — `--dry-run --json`; read the base, counts, conflicts, mirror-only skills, mirror clashes and project-only files.183. **Decide** — ask the user only about mirror-only skills, mirror clashes, a doubtful base or a dirty tree.194. **Apply** — the same command without `--dry-run`, pinned to the upstream commit and base the dry run showed.205. **Resolve** — read `references/merge-guide.md` and settle every conflict, keeping both sides' intent.216. **Verify and report** — no markers, JSON parses, the sync passes; report what changed and what stayed.2223**Key Rules:**2425- MUST ATTENTION run only on the user's explicit request; never start it on your own or as a step of other work.26- MUST ATTENTION never delete, overwrite or "clean up" a project-owned file (a path upstream never shipped). The engine never merges, moves or deletes them, only recomputes their `<!-- COUNT -->` values; you change one only with the user's agreement (for example renaming a skill whose name upstream now also uses).27- MUST ATTENTION never copy upstream files over the project, and never hand-edit `.agents/`, `.codex/`, `.opencode/` or `AGENTS.md`: they are regenerated from `.claude/`.28- MUST ATTENTION the update is finished only when the closing sync has passed: until then `.codex/`, `.agents/` and `.opencode/` still hold the old version.29- Commit or push only when the user asks. The update and `.claude/framework-lock.json` belong in the same commit.3031**Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).**3233## Contents3435- [Quick Summary](#quick-summary)36- [The command](#the-command)37- [What is whose](#what-is-whose)38- [Procedure](#procedure)39- [A project without this skill yet](#a-project-without-this-skill-yet)40- [Troubleshooting](#troubleshooting)41- [Closing Reminders](#closing-reminders)4243## The command4445Run from the project root on Windows, macOS or Linux (plain `node`; no npm, no `package.json`):4647```text48node .claude/skills/framework-update/scripts/update-from-upstream.mjs --dry-run --json49node .claude/skills/framework-update/scripts/update-from-upstream.mjs --base=<commit from the dry run>50```5152| Option | Use it when |53| --- | --- |54| `--ref=<branch\|tag\|commit>` | the user names a version other than `main` |55| `--upstream=<git-url\|folder>` | the user names another repository or a fork, or the network is blocked and a local easy-claude checkout exists; default is the URL in the lock, else the GitHub repository |56| `--base=<commit>` / `--base=auto` | no lock yet: the dry run detects the base by content (`auto`); pin that commit when applying |57| `--no-sync` | the user wants to run the mirror sync later |58| `--record-only` | the project was just synced by hand: record the version without changing files |59| `--project=<folder>` | updating another project from an easy-claude checkout |60| `--engine=local` | the upstream version's engine cannot run (the default `upstream` runs the newest merge rules) |6162The script keeps a blobless clone in `tmp/framework-update/upstream.git` (commits and folder listings only; file contents download in batches), so later runs only fetch what is new. Exit code: `0` done · `1` fatal · `2` something left to resolve (a conflict or a mirror clash).6364## What is whose6566| Path | Owner | What the update does |67| --- | --- | --- |68| A `.claude/` file upstream ships, has shipped since the base, or the lock lists | framework | Unchanged in the project → takes upstream (or deletes it when upstream deleted it). Changed only in the project → kept. Changed on both sides → three-way merge; overlaps get conflict markers. |69| Any other `.claude/` file: project skills, hooks, agents, scripts, protocols, ledgers | project | Never merged, moved or deleted; only its `<!-- COUNT -->` values are recomputed. Listed as `projectOnly`. |70| `settings.local.json`, `.ck.local.json` | each person | Never taken from upstream. |71| `SKILLS.yaml`, `skills_data.yaml`, `<!-- COUNT -->` values | generated | Regenerated from the project's own skill set, never merged. |72| `.agents/`, `.codex/`, `.opencode/`, `AGENTS.md`, `opencode.json` skill permissions | generated mirrors | Rebuilt from the merged `.claude/` by the closing sync (`/sync-codex`, which hands off to the OpenCode sync when `.opencode/` exists): upstream's new mirror files arrive, retired ones go, and the project's own skills, agents and hooks are mirrored too. |73| `.agents/skills/<name>` with no `.claude/skills/<name>` source | project | The sync keeps it and prints one `kept` line, but it reaches no other host; the engine lists it as `mirrorOnly` and still runs the sync. When a framework skill new in this update takes its name, the new skill's mirror would replace it: the engine lists it as a mirror clash (`mirrorClashes`) and skips the sync. The mirror of a framework skill the project no longer has (upstream retired it) is the framework's: the engine removes it. |74| `docs/`, `CLAUDE.md`, `docs/project-config.json`, everything outside the four folders | project | Never touched. |7576## Procedure7778### 1. Preflight7980- `git status --porcelain -- .claude .agents .codex .opencode AGENTS.md opencode.json` must print nothing. Otherwise ask the user to commit or stash those changes first (the engine refuses, so the update stays one reviewable, undoable diff). Mention that a separate branch keeps the update easy to review.81- `node --version` (18+) and `git --version` must work. Git 2.29 or newer downloads the upstream files in batches; older Git still works, file by file and much slower (the engine prints a `WARNING`). The script reports a network failure; offer `--upstream=<local easy-claude checkout>` as the fallback.82- When the project uses Codex or OpenCode mirrors, check them for hand edits before they are rebuilt: `node .claude/skills/sync-codex/scripts/run-codex-sync.mjs --only=sync-divergence`. A reported file differs from what `.claude/` generates; inspect it, and port a deliberate edit into its `.claude/` source first (a merely stale mirror needs nothing).8384### 2. Dry run8586Run `--dry-run --json` (plus any `--ref` / `--upstream` the user gave) and read:8788- `upstream.commit` against the lock's `source.commit`: equal means the project is already current. Say so and stop.89- `upstream.url`: when it is not `https://github.com/duc01226/easy-claude.git` (a fork or mirror the lock remembers from an earlier `--upstream`), name it to the user; its code is what will be merged.90- `baseDetection` (projects without a lock): `matched` of `projectFiles` files match `commit`. Show its date and subject with `git -C tmp/framework-update/upstream.git log -1 --format="%h %cs %s" <commit>`. Below about 80% matched, the project was likely copied from a fork or another project, or heavily edited: ask the user to confirm the commit or name the version they copied.91- `taken`, `deleted`, `merged`, `kept`, `conflicts`, `mirrorOnly`, `mirrorClashes`, `projectOnly`.9293### 3. Decide9495Ask once, in one question, only about what needs the user:9697- **Mirror-only skills** (`mirrorOnly`): recommend moving each into `.claude/skills/<name>/`, where it becomes canonical and is mirrored to every host; check the name is free and its `SKILL.md` frontmatter has `name` and `description`. The alternative is keeping it Codex-only in `.agents/skills/` (right for a skill another tool installed there): the sync leaves it in place. Carry out the answer after step 4: the engine refuses to run on uncommitted changes.98- **Mirror clashes** (`mirrorClashes`): a Codex-only skill whose name a framework skill new in this update also uses. Recommend renaming the project's skill (its folder and the `name` in its `SKILL.md`, then every reference: `git grep -n <old-name>`), so both stay. The alternative is letting upstream's skill take the name: remove the project's skill, then run the sync. Carry out the answer after step 4, before the sync.99- **A doubtful base** (step 2).100101Proceed without asking when nothing needs a decision: the tree is clean and everything is undoable through Git.102103### 4. Apply104105Run the command without `--dry-run`, pinned to what the dry run showed: `--ref=<upstream.commit>`, and on a first update `--base=<baseDetection.commit>`. A newer `main` pushed in between is then not taken unseen. The engine writes the merge, the lock and regenerated catalogs and counts, then runs the mirror sync unless a conflict or a mirror clash stops it. Then carry out step 3's answers: move each mirror-only skill the user chose to move (`git mv .agents/skills/<name> .claude/skills/<name>`), and rename or remove each clashing one.106107### 5. Resolve conflicts108109Read `references/merge-guide.md` before touching a conflict. It covers marker conflicts, settings and other JSON files, a skill name upstream now also ships, files one side deleted, and code both sides fixed. Each `conflict-side` file has upstream's copy under `tmp/framework-update/<path>`.110111### 6. Verify and report112113- No markers left: `git grep -n -E "^(<<<<<<< project|=======$|>>>>>>> upstream)" -- .claude` prints nothing (a reported `=======` line can be a Markdown heading underline; check it).114- Every changed JSON file parses: `node -e "JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'))" <file>`.115- Every hook command in `.claude/settings.json` names a file that exists.116- After moving or renaming any skill (mirror-only skills, a name clash), rebuild the catalogs and counts: `node .claude/scripts/framework-update.mjs --regenerate`.117- Run the sync if the engine skipped it, and again after moving or renaming a skill: `node .claude/skills/sync-codex/scripts/run-codex-sync.mjs`. It rebuilds `.agents/`, `.codex/` and `.opencode/`, and its `verify-sync-divergence` and `verify-opencode-*` stages prove they match the merged `.claude/`. A mirror-only skill the user kept in `.agents/skills/` stays as it is, with one `kept .agents/skills/<name>` line. A sync failure is a finding: compare it with a run on the commit before the update before calling it new.118- A stale root `CLAUDE.md` reported by the sync → offer `/ai-context-refresh`. New framework switches → `node .claude/scripts/framework-features.cjs` lists them with their defaults.119- Report: from and to versions, counts, how many project-only files stayed untouched, each conflict and how it was settled, what still needs the user, and verification results. Show `git status --short` totals, not the full list.120121## A project without this skill yet122123Update it once from any easy-claude checkout; the update brings this skill along:124125```text126git clone --filter=blob:none https://github.com/duc01226/easy-claude.git <scratch-folder>/easy-claude127node <scratch-folder>/easy-claude/.claude/skills/framework-update/scripts/update-from-upstream.mjs --project=<project> --dry-run128```129130## Troubleshooting131132| Symptom | Fix |133| --- | --- |134| `uncommitted changes in .claude, …` | commit or stash them; `--allow-dirty-project` only when the user accepts mixing them into the update diff |135| `No upstream commit shares a file with this project` | ask the user which version they copied and pass `--base=<commit>` |136| `… is not a branch, tag or commit of the upstream` | check `--ref`; a commit from a pull request needs its full hash |137| clone or fetch fails | proxy or offline: clone easy-claude elsewhere and pass `--upstream=<that folder>`; its local `main` branch is taken, so pull it first |138| the user wants to undo before committing | `git restore --staged --worktree --` followed by only those of `.claude .agents .codex .opencode AGENTS.md opencode.json` that exist (a missing path makes Git refuse the whole command); then preview new files with `git clean -n -- <same paths>` and remove them only after the user confirms |139140## Closing Reminders141142**MUST ATTENTION** run only on the user's explicit request. **MUST ATTENTION** never delete or overwrite a project-owned file, never copy upstream over the project, and never hand-edit a generated mirror. **MUST ATTENTION** the update covers `.codex/`, `.agents/` and `.opencode/` only once the closing sync passes. **MUST ATTENTION** read `references/merge-guide.md` before resolving any conflict and keep both sides' intent; ask the user when the intents clash. Commit or push only on request, with the lock in the same commit.