1---2name: update-dependencies3description: Repository-agnostic dependency maintenance workflow. Use when a task should check for dependency updates, apply safe upgrades, validate the target repository with its own tooling and runtime surfaces, and deliver the result through review-friendly automation.4---56# Update Dependencies78This checked-in skill is the shared source-of-truth copy for dependency-update workflow behavior. It is packaged with the worker so customer-repo Dependabot follow-up tasks can invoke `$update-dependencies` without depending on a repo-local skill checkout.910<role>11You are a dependency maintenance specialist. Keep dependency upgrades small, safe, validated, and repeatable. Derive package manager, validation commands, runtime proof, and workspace scope from the target repository instead of assuming Roomote-specific tooling.12</role>1314<workflow>15 <overview>Execute a dependency update workflow with two first-class modes: recurring maintenance and Dependabot alert follow-up. Inspect manifests and lockfiles, choose a narrow safe update scope, apply compatible updates, run the strongest practical repository-defined validation, and deliver the result through a review-friendly path. Maintenance runs should stay scheduled-friendly, while Dependabot follow-ups should start with alert re-verification, stay scoped to the named package or manifest slice, and widen only to the smallest cohesive remediation that actually clears the alert instead of defaulting to deferral. When an updated dependency can affect a running service, prove the service still works at runtime instead of stopping at manifest or lockfile hygiene.</overview>1617 <phase name="analysis">18 <description>Understand the repository and the safest update scope before changing manifests or lockfiles.</description>19 <steps>20 <step number="1">21 <title>Classify the run mode</title>22 <description>Decide whether this is a recurring maintenance run or an explicit Dependabot alert follow-up before doing broader dependency discovery.</description>23 <actions>24 <action>Read the task context for explicit run-mode clues such as `alert_follow_up`, Dependabot alert URLs or numbers, requested package names, manifest paths, or triage investigation context.</action>25 <action>If the run is a Dependabot alert follow-up, branch immediately into the alert-first path for the rest of analysis: re-verify the cited alert before any generic outdated-report logic, keep the working scope limited to the named package, manifest, or tightly related workspace slice, and do not broaden into repository-wide maintenance unless the user explicitly asks.</action>26 <action>If the run is ordinary maintenance, continue with the scheduled-friendly discovery path and use non-mutating outdated reports to pick a safe narrow update set.</action>27 </actions>28 <validation>You know whether this run should behave like maintenance or like a Dependabot remediation task, and the rest of analysis is scoped accordingly.</validation>29 </step>30 <step number="2">31 <title>Initialize task tracking</title>32 <description>Create an explicit todo list that matches a dependency-maintenance run.</description>33 <actions>34 <action>Create a todo list covering dependency surface discovery, update selection, implementation, validation, and delivery or no-op reporting.</action>35 <action>For Dependabot alert follow-up runs, reflect the narrower alert-driven sequence in the todo list: re-verify alert -> resolve the named package or manifest slice -> validate -> deliver or report no-op or deferred.</action>36 <action>Keep the visible plan scoped to dependency maintenance; do not add unrelated refactoring or feature work.</action>37 </actions>38 <validation>A todo list exists and reflects the dependency-maintenance lifecycle.</validation>39 </step>40 <step number="3">41 <title>Discover dependency surfaces</title>42 <description>Identify package managers, manifests, lockfiles, workspace structure, and existing update policy.</description>43 <actions>44 <action>Inspect dependency manifests and lockfiles such as `package.json`, `pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `bun.lock`, `Cargo.toml`, `Cargo.lock`, `pyproject.toml`, `uv.lock`, `poetry.lock`, `requirements*.txt`, `go.mod`, `go.sum`, `Gemfile`, and `Gemfile.lock`.</action>45 <action>Read repository guidance files, package-manager configuration, Renovate or Dependabot config, CI definitions, and docs that define supported update cadence or validation commands.</action>46 <action>Infer the authoritative package manager from lockfiles and project tooling rather than mixing package managers.</action>47 <action>For monorepos, identify the smallest workspace slice that can be updated and validated safely.</action>48 <action>Map the selected package to the runtime surfaces it can affect: build-only tooling, shared libraries, backend services, CLIs, worker processes, or user-facing web apps. Use that impact map to decide which test suites and live-service checks are required later.</action>49 <action>For Dependabot alert follow-up runs, stop discovery as soon as you have enough surface information to resolve the named package or manifest slice safely; do not keep exploring adjacent dependency surfaces just for awareness.</action>50 </actions>51 <validation>The update surface, package manager, and validation candidates are grounded in repository files.</validation>52 </step>53 <step number="4">54 <title>Select a safe update set</title>55 <description>Choose updates that are appropriate for unattended or periodic execution.</description>56 <actions>57 <action>For recurring maintenance runs, use the package manager's non-mutating outdated-report command before selecting updates when one is available. For pnpm workspaces, prefer `pnpm outdated --recursive --compatible --format json` to identify updates that satisfy existing specs, and use broader `pnpm outdated --recursive --format json` output only as awareness for deferred major or incompatible updates. For single-package pnpm repositories, use the same commands without `--recursive` when workspace recursion does not apply.</action>58 <action>For Dependabot alert follow-up runs, re-verify the alert with the GitHub data available in the task environment. Confirm it is still open and capture the verified package, ecosystem, manifest path, vulnerable range, and first patched version.</action>59 <action>For Dependabot alert follow-up runs, resolve any explicitly configured review ownership before changing dependencies. First inspect `.github/dependabot.yml` and match the alert's package ecosystem and manifest directory to the applicable `updates` entry. If that entry has no usable review owner, inspect supported local Renovate config names in precedence order: `.github/renovate.json`, `.github/renovate.json5`, `renovate.json`, `renovate.json5`, `.renovaterc`, and `.renovaterc.json`; resolve the effective `reviewers`, `additionalReviewers`, `assignees`, and `additionalAssignees` from the base config and matching `packageRules` for the affected package, manager or ecosystem, and manifest path. Respect Renovate's override and additive field semantics, and do not treat unrelated update entries or package rules as ownership for the remediation.</action>60 <action>Keep only concrete GitHub user or team targets from the matching config. Preserve the config's distinction between `reviewers` and `assignees`, normalize supported GitHub team forms such as `org/team-slug` or Renovate's `team:team-slug` for the GitHub API, and ignore templates, dynamic values, unsupported host-specific syntax, or inherited presets that cannot be resolved from repository files. Do not infer reviewers from `CODEOWNERS` or enable Renovate `reviewersFromCodeOwners` behavior.</action>61 <action>Select the intended version transition from the verified alert's first patched version and the repository's compatibility constraints. Keep the update set constrained to that selected package, manifest, or tightly related workspace slice.</action>62 <action>After alert re-verification and target-version selection, inspect the upstream changelog, release notes, or version diff when that information is available. Record material behavioral changes, deprecations, breaking changes, security-relevant fixes, and the affected runtime surfaces; do not infer release details when upstream information is unavailable.</action>63 <action>Use the upstream change analysis to select targeted validation and runtime checks for the affected behavior. When the analysis identifies no relevant runtime surface, state that conclusion and use the strongest applicable repository-defined static or package-level validation instead.</action>64 <action>For Dependabot alert follow-up runs, do not run a generic outdated report unless the alert has already closed and the user explicitly asks to broaden the task into ordinary maintenance.</action>65 <action>Prefer patch and minor updates within existing semver ranges, lockfile refreshes, security fixes, and tightly related dependency groups that can be validated together.</action>66 <action>For Dependabot-driven work, prefer the smallest manifest or workspace-scoped update that resolves the named alert package or tightly related alert bundle. If the narrowest single-package update is not enough, widen only to the smallest cohesive remediation that is still directly tied to the alert, such as aligned workspace version bumps, lockfile refreshes, or a small related dependency bundle. Do not turn one alert-driven task into a broad dependency sweep.</action>67 <action>When the same dependency is used across multiple affected workspaces, prefer keeping versions aligned when that can be done safely within the task scope. Avoid introducing an additional version into the monorepo unless compatibility constraints, alert scope, or validation evidence justify it.</action>68 <action>Avoid broad "update everything" runs unless the user explicitly requested a broad sweep and the repository has validation strong enough to support it.</action>69 <action>Do not take major-version upgrades, framework migrations, package-manager migrations, or peer-dependency-breaking changes unless the user explicitly requested that scope.</action>70 <action>Respect explicit pins, overrides, resolutions, and engines unless repository evidence shows the old decision is obsolete.</action>71 <action>If only noisy, risky, or low-confidence updates are available, skip dependency changes and report a useful deferred decision only when it will help a future run.</action>72 </actions>73 <validation>The selected update set is narrow, explainable, and compatible with the repository's policy.</validation>74 </step>75 </steps>76 </phase>7778 <phase name="implementation">79 <description>Apply the chosen dependency updates without unrelated churn.</description>80 <steps>81 <step number="1">82 <title>Apply dependency updates</title>83 <description>Use the repository's package manager and keep manifest and lockfile changes coherent.</description>84 <actions>85 <action>Run the package-manager command that updates only the selected packages or workspace slice when the tooling supports a constrained update.</action>86 <action>Update lockfiles through the package manager, not by hand.</action>87 <action>Do not edit generated lockfile content manually except when repository tooling explicitly requires a deterministic checked-in patch that the package manager cannot produce.</action>88 <action>Keep unrelated formatting, generated files, and package-manager metadata out of the diff.</action>89 <action>If package-manager install or update commands fail, diagnose the failure and either choose a smaller compatible update set or report a useful blocker. Do not keep pushing through a broken dependency graph blindly.</action>90 </actions>91 <validation>Any manifest and lockfile edits were produced coherently by the repository's package manager.</validation>92 </step>93 <step number="2">94 <title>Handle failures safely</title>95 <description>Keep the repository clean when an attempted update cannot be made trustworthy.</description>96 <actions>97 <action>If an attempted update cannot pass install or validation after a focused fix attempt, revert only the dependency and lockfile changes made by this workflow run. Do not revert unrelated user or pre-existing workspace changes.</action>98 <action>For Dependabot alert follow-up runs whose cited alert is already closed, dismissed, or no longer actionable, prefer a quiet no-op report unless the run surfaced a durable blocker or compatibility fact that matters to the next alert-driven run.</action>99 <action>If the only outcome is "checked and nothing worth updating," leave the repository unchanged and report a no-op result.</action>100 </actions>101 <validation>Failed attempts do not leave untrusted dependency changes behind, and useful lessons are retained without noisy no-op edits.</validation>102 </step>103 </steps>104 </phase>105106 <phase name="validation">107 <description>Prove the update works with checks that match the repository and update risk.</description>108 <steps>109 <step number="1">110 <title>Run the strongest repository-defined validation gate and runtime proof</title>111 <description>Dependency changes can ripple through multiple surfaces, so use the best validation the repository itself defines and prove affected services still behave correctly at runtime.</description>112 <actions>113 <action>When manifests or lockfiles changed, run any install or lockfile consistency check the repository already expects before broader validation.</action>114 <action>When the run is happening in a prewarmed, environment-backed, or otherwise non-fresh workspace, do not assume the current install tree already matches the edited manifests or lockfiles just because a lightweight repeat install succeeds. Refresh the repository's authoritative install state before broader validation when task context says workspace readiness is not fully settled, when repository commands may still be running in the background, or when the workspace was clearly prepared before this update run began.</action>115 <action>For pnpm repositories, prefer a full workspace reinstall after dependency or lockfile edits, and escalate to `pnpm install --frozen-lockfile --force` when the ordinary reinstall appears to trust stale `.pnpm`, `node_modules`, or symlink state. Use the repository's equivalent clean refresh for other package managers.</action>116 <action>Then run the strongest practical validation commands grounded in repository guidance, package scripts, CI definitions, or surrounding task instructions. Prefer the repository's documented full gate when one exists instead of guessing from Roomote-specific conventions.</action>117 <action>If the changed package can affect a running service or shared runtime library, default to the full relevant test matrix for that service or workspace slice. When unit, integration, smoke, or end-to-end suites exist for the affected surface, run the available suites rather than stopping after a single narrow test.</action>118 <action>If only targeted checks are realistic for the changed workspace slice, choose the smallest set that still gives honest confidence for the change and record why broader suites were not applicable or available.</action>119 <action>When the dependency update can affect a browser-reachable web app or web service, start the service in the repository's normal validation mode, exercise the primary impacted workflow against the updated dependency, and capture at least one screenshot with `agent-browser` as proof that the service still renders and behaves correctly.</action>120 <action>When the dependency update can affect a non-browser service such as an API, worker, or CLI runtime, run the strongest available service-level smoke or integration checks against the live process or its normal test harness instead of relying only on static or compile-time checks.</action>121 <action>If a post-update validation failure appears in an unrelated workspace or package graph, rerun the install once with a clean or forced refresh and repeat the failing validation before treating it as a real blocker. Do not mistake warmed-workspace dependency drift for a genuine regression in the proposed update.</action>122 <action>If any required validation step fails, decide once: either tighten the update set and re-run the same validation surface, or revert this run's dependency changes and report a useful deferred decision. Do not ship a dependency update with failing validation.</action>123 <action>If the strongest validation or runtime proof requires unavailable services, secrets, browsers, or environments, report the exact missing dependency, command, and confidence gap, and treat the run as blocked until the missing prerequisite is available.</action>124 </actions>125 <validation>The strongest practical repository-defined validation and any required runtime proof ran cleanly against the proposed dependency change, or the run was reverted or blocked with a recorded reason.</validation>126 </step>127 <step number="2">128 <title>Review the dependency diff</title>129 <description>Self-review changed manifests and lockfiles before delivery.</description>130 <actions>131 <action>Review the full diff for unintended package-manager switches, unexpected major upgrades, peer-dependency warnings, duplicate packages, newly introduced multi-version drift for the same dependency across workspaces, workspace drift, and accidental generated-file churn.</action>132 <action>Fix any issue introduced by this workflow before delivery.</action>133 </actions>134 <validation>The final diff is intentional and minimal.</validation>135 </step>136 </steps>137 </phase>138139 <phase name="delivery">140 <description>Finish through a review-friendly delivery path for code-changing runs.</description>141 <steps>142 <step number="1">143 <title>Reach delivery or no-op state</title>144 <description>Default successful dependency updates to a draft PR.</description>145 <actions>146 <action>For Dependabot alert follow-ups, pass separately configured assignees from the matching dependency-update config into the PR-delivery skill's existing `assignees` contract rather than converting assignees into reviewers.</action>147 <action>If the final diff changes dependency manifests, lockfiles, or other code, transition into the `create-draft-pr` skill so the run lands as a new draft pull request that the team can review before marking ready.</action>148 <action>Only override the draft-PR default when the user explicitly asked for a different delivery path in the task prompt (for example, "push directly" for a hand-curated security fix). When overriding, name the override and the reason in the run report so the audit trail is clear.</action>149 <action>If the task is in Interactive mode, pause after validation and diff review before invoking `create-draft-pr`, `create-pr`, or `push`. Hand the diff and validation summary to the user for approval first.</action>150 <action>If the final diff is empty, report the no-op, failed, or deferred outcome directly without launching a delivery skill.</action>151 <action>Use commit messages that name the chore: `chore(deps): <scope>` or an equivalent repository-appropriate dependency update summary. Do not bundle unrelated changes into the delivery.</action>152 <action>The PR body that `create-draft-pr` produces should summarize the applied updates (package + version-from -> version-to), the validation and runtime-proof result, and any deferred packages with their reasons. Keep the body concise and scannable; do not paste full lockfile diffs.</action>153 <action>After `create-draft-pr` (or an explicitly requested PR-delivery skill) returns the GitHub pull request number, request the concrete reviewers resolved from the matching dependency-update config. Call `manage_source_control` with action `request_pull_request_reviewers`, passing user logins as `reviewers` and team slugs as `teamReviewers`.</action>154 <action>If no supported config exists, no update entry or package rule matches, or the matching rule contains no concrete reviewer or assignee, preserve the existing delivery behavior and finish without an ownership mutation. A genuine GitHub API rejection for a resolved target must be reported with the PR result; do not claim the reviewer or owner was assigned.</action>155 </actions>156 <validation>The run delivered dependency changes that passed required validation and runtime proof through `create-draft-pr` (or the explicitly-requested override), paused for user approval in Interactive mode, or ended as an honest no-op or deferred result.</validation>157 </step>158 <step number="2">159 <title>Report the maintenance outcome</title>160 <description>Summarize the result in repository-facing terms.</description>161 <actions>162 <action>For successful updates, name the dependency scope, notable version changes, validation and runtime-proof result, and delivery outcome.</action>163 <action>For Dependabot alert follow-ups, include a concise user-facing impact summary: what upstream behavior or security change was identified, what relevant code path was verified, and any remaining risk or uncertainty. If changelog or diff evidence was unavailable, say so plainly instead of inventing release analysis.</action>164 <action>For no-op runs, say what was checked and why nothing changed.</action>165 <action>For failed or deferred updates, name the blocked package or version, the validation, runtime-proof, or compatibility evidence, and the next step needed.</action>166 <action>Keep the final report concise and avoid dumping package-manager logs unless the exact failure line is needed.</action>167 </actions>168 <validation>The final response matches the actual dependency, validation, and delivery state.</validation>169 </step>170 </steps>171 </phase>172173<completion_criteria>174<criterion>The package manager and update scope were grounded in repository manifests, lockfiles, and local guidance.</criterion>175<criterion>Major, migration-scale, or peer-breaking updates were avoided unless explicitly requested.</criterion>176<criterion>Any dependency changes were produced through package-manager tooling and validated by the strongest practical repository-defined checks plus any required service-level runtime proof. The run was not delivered with failing validation or missing required runtime verification.</criterion>177<criterion>Failed attempts reverted only this run's untrusted dependency changes without unrelated rollback.</criterion>178<criterion>Repository-changing successful runs were delivered through `create-draft-pr` (or an explicitly-requested override), the PR body summarized the applied updates, validation and runtime-proof result, and any deferred packages, and Dependabot follow-up PRs requested any concrete reviewers or assignees from the matching local dependency-update config after creation.</criterion>179<criterion>Dependabot follow-ups inspect available upstream release changes, use them to target validation, and report the resulting impact and remaining uncertainty.</criterion>180</completion_criteria>181</workflow>182183<best_practices>184<guideline priority="high">185<rule>Optimize for a repeatable update workflow, not a heroic one-time upgrade.</rule>186<rationale>Small validated updates compound safely across runs.</rationale>187<exceptions>Use a broader scope only when the user explicitly asks for it and validation is strong enough to trust.</exceptions>188</guideline>189<guideline priority="high">190<rule>Let the repository's package manager own lockfile changes.</rule>191<rationale>Manual lockfile edits are easy to corrupt and hard to review.</rationale>192<exceptions>Only apply deterministic generated-file patches when repository tooling explicitly requires them.</exceptions>193</guideline>194<guideline priority="high">195<rule>Never leave unvalidated dependency changes behind after a failed run.</rule>196<rationale>Dependency churn without passing checks creates review burden and erodes trust in automated updates.</rationale>197<exceptions>None.</exceptions>198</guideline>199<guideline priority="high">200<rule>For service-affecting updates, validate the live surface and not just the package graph.</rule>201<rationale>A dependency bump that passes install and unit checks can still break a running API, worker, or web app.</rationale>202<exceptions>Purely build-time or tooling-only updates may stop at repository-defined non-runtime validation when repository evidence shows no live surface is affected.</exceptions>203</guideline>204</best_practices>205206<patterns>207 <pattern name="daily_patch_minor_update">208 <description>Safe default for scheduled maintenance.</description>209 <template>inspect manifests and lockfiles -> run a non-mutating outdated report when useful -> select a patch or minor update set -> update with package manager -> run the strongest repository-defined validation plus any required service-level proof -> transition into `create-draft-pr` with a body summarizing the applied updates, validation result, runtime proof, and any deferred packages</template>210 </pattern>211 <pattern name="failed_upgrade_learning">212 <description>Preserve useful knowledge when an update is not safe to ship.</description>213 <template>attempt constrained update -> validation fails -> diagnose once -> revert this run's dependency changes if still unsafe -> report deferred outcome with the exact blocker</template>214 </pattern>215 <pattern name="major_upgrade_deferral">216 <description>Keep routine automation from turning into migration work.</description>217 <template>detect major update -> check explicit request -> if absent, defer -> continue with safer updates or no-op</template>218 </pattern>219 <pattern name="dependabot_alert_follow_up">220 <description>Resolve one explicit Dependabot alert or one tightly related alert bundle.</description>221 <template>classify run as `alert_follow_up` immediately -> re-fetch the open alert via GitHub before any generic outdated scan -> resolve concrete reviewers or assignees from the matching local Dependabot or Renovate rule -> constrain the update set to the named package or manifest or workspace -> apply the smallest safe update that is likely to clear the alert, widening only to a tightly related workspace or dependency bundle when necessary -> run the strongest practical repository-defined validation plus any required service-level proof -> create the draft PR -> request the resolved GitHub reviewers or assignees, or preserve the existing no-owner behavior when none resolve -> report whether the alert-backed update landed, was already closed, or was deferred</template>222 </pattern>223</patterns>
RooCodeInc