A platform-neutral workflow that drives any coding agent to update your projects' dependencies to the latest versions (including majors), verify them, adapt your code to breaking changes, and ship only what stays green.
一个与平台无关的工作流，可驱动任意编码 agent 将项目依赖更新到最新版本（含大版本）， 完成验证，适配代码以应对破坏性变更，并且只提交那些保持绿灯的项目。
本文档为中文 / English 双语：每个章节先英文，后中文（简体）。
For each configured project, the workflow:
- Updates dependencies to the latest versions, including major bumps.
- Auto-runs that ecosystem's test + build to verify the result.
- Attempts to adapt your code to breaking changes, bounded by
maxAdaptRounds(default3). - Commits and pushes only the projects whose test + build stay green.
- Treats one project as one independent work unit, run in parallel where the runtime supports sub-agents, otherwise sequentially.
Supported ecosystems: Node (npm / pnpm / yarn), Rust (cargo), Go (modules), Python (pyproject / requirements).
对每个已配置的项目，工作流会：
- 将依赖更新到最新版本，包含大版本升级。
- 自动运行对应生态的测试 + 构建以验证结果。
- 尝试适配你的代码以应对破坏性变更，上限由
maxAdaptRounds控制（默认3）。 - 仅提交并推送那些测试 + 构建保持绿灯的项目。
- 将单个项目视为一个独立工作单元，在运行时支持子 agent 时并行执行，否则顺序执行。
支持的生态：Node（npm / pnpm / yarn）、Rust（cargo）、Go（modules）、 Python（pyproject / requirements）。
update-deps/
├── .claude-plugin/
│ ├── plugin.json # Claude Code plugin manifest
│ └── marketplace.json # repo doubles as its own 1-plugin marketplace
├── PLAYBOOK.md # core, platform-neutral source of truth
├── references/
│ ├── node.md
│ ├── rust.md
│ ├── go.md
│ └── python.md # per-ecosystem reference manuals
├── adapters/
│ ├── claude-code/SKILL.md # Claude Code skill adapter
│ ├── codex/update-deps.md # Codex prompt adapter
│ └── generic/PROMPT.md # paste-in prompt for any agent
├── projects.example.json # config template (committed)
├── projects.json # your real list — gitignored, NOT committed
├── .gitignore
└── LICENSE # MIT
Claude Code (plugin marketplace — recommended) — install straight from GitHub, no clone needed:
/plugin marketplace add JobinJia/update-deps
/plugin install update-deps@jobinjia
Your project list lives in the plugin's persistent data dir
(${CLAUDE_PLUGIN_DATA}/projects.json) so it survives updates; the skill
creates it from the bundled template on first run.
Claude Code (symlink — for local development) — symlink the adapter into your skills directory:
ln -s <repo>/adapters/claude-code ~/.claude/skills/update-depsCodex — copy the prompt into your prompts directory:
cp adapters/codex/update-deps.md ~/.codex/prompts/update-deps.mdGeneric — open adapters/generic/PROMPT.md and paste it into your agent.
Claude Code（plugin marketplace —— 推荐） —— 直接从 GitHub 安装，无需克隆：
/plugin marketplace add JobinJia/update-deps
/plugin install update-deps@jobinjia
你的项目清单会保存在 plugin 的持久化数据目录
（${CLAUDE_PLUGIN_DATA}/projects.json），更新时不会丢失；首次运行时 skill
会用内置模板自动创建它。
Claude Code（symlink —— 用于本地开发） —— 将适配器软链接到你的 skills 目录：
ln -s <repo>/adapters/claude-code ~/.claude/skills/update-depsCodex —— 将提示词复制到你的 prompts 目录：
cp adapters/codex/update-deps.md ~/.codex/prompts/update-deps.mdGeneric（通用） —— 打开 adapters/generic/PROMPT.md，将其内容粘贴到你的 agent 中。
Copy the template, then edit the paths:
cp projects.example.json projects.jsonprojects.json is gitignored, which keeps your local paths private and out of
version control. Edit it to list your own projects.
Config fields:
maxAdaptRounds— the cap on adaptation rounds per project (default3).branchStrategy— how to branch before committing (defaultauto):autobranches tochore/update-depsonly when the project is on its default branch,alwaysalways branches,currentcommits on the current branch as-is.path— the project path;~is expanded to your home directory.ecosystem—auto(detect automatically) or a pinned value:node/rust/go/python.skip— set totrueto temporarily exclude an entry without deleting it.
复制模板，然后编辑路径：
cp projects.example.json projects.jsonprojects.json 已被 gitignore，因此你的本地路径会保持私密、不进入版本控制。
编辑该文件以列出你自己的项目。
配置字段：
maxAdaptRounds—— 每个项目的适配轮数上限（默认3）。branchStrategy—— 提交前的分支策略（默认auto）：auto仅在项目处于默认 分支时切到chore/update-deps，always总是新建分支，current直接在当前 分支提交。path—— 项目路径；~会被展开为你的主目录。ecosystem——auto（自动检测）或固定值：node/rust/go/python。skip—— 设为true可临时排除某条目，而无需删除它。
- No args → use the projects listed in
projects.json. - A path list → update only those projects (overrides the
projects.jsonlist). --dry-run→ report what is updatable and how many majors are available; change nothing.
Per-platform trigger examples:
/update-deps
/update-deps ~/code/a ~/code/b
- 无参数 → 使用
projects.json中列出的项目。 - 路径列表 → 仅更新这些项目（覆盖
projects.json中的列表）。 --dry-run→ 报告哪些可更新、有多少个大版本可用；不做任何更改。
各平台触发示例：
/update-deps
/update-deps ~/code/a ~/code/b
- Only green projects are pushed — a project that fails test or build is never committed or pushed.
- Dirty working trees are skipped — projects with uncommitted changes are left untouched.
- Default branches are protected — by default (
branchStrategy: auto) updates land on achore/update-depsbranch rather than straight ontomain/master. - Unverifiable updates stop and ask — a project with no test and no build runs
no real verification, so it is reported as
needs-youinstead of being pushed. - Bottomed-out major upgrades stop and ask — when a major upgrade cannot be made
to pass within the adaptation budget, the workflow halts on that project (status
needs-you) and asks you instead of forcing it through.
See PLAYBOOK.md for the full, platform-neutral source of truth.
- 只有绿灯项目才会被推送 —— 测试或构建失败的项目永远不会被提交或推送。
- 脏工作树会被跳过 —— 存在未提交改动的项目将保持原样。
- 保护默认分支 —— 默认情况下（
branchStrategy: auto）更新会落到chore/update-deps分支，而不是直接推到main/master。 - 无法验证的更新会停下并询问 —— 既无测试又无构建的项目没有跑过任何真实验证，
会被报告为
needs-you而不是被推送。 - 触底的大版本升级会停下并询问 —— 当某个大版本升级在适配预算内仍无法通过时，
工作流会在该项目上停止（状态
needs-you）并询问你，而不是强行推进。
完整且与平台无关的事实来源请参见 PLAYBOOK.md。
MIT. See LICENSE.
MIT 许可证。详见 LICENSE。