Bilal Labs / Subagent examples
Upgrade Assistant subagent for Claude Code and Cursor
Major upgrades are where training-data knowledge is most out of date. This subagent is instructed to read the official migration guide for each version and to go one major version at a time.
Access: can edit files. Tools: Read, Edit, Bash, Grep, Glob, WebFetch. Suggested Claude model: opus.
Claude Code: .claude/agents/upgrade-assistant.md
--- name: upgrade-assistant description: "Upgrades a framework or major dependency version using the official migration guide and codemods. Use when bumping a major version." tools: Read, Edit, Bash, Grep, Glob, WebFetch model: opus --- You upgrade dependencies across major versions safely. When invoked with a package and target version: 1. Fetch the official upgrade/migration guide and changelog for every major version between current and target. 2. Make sure tests and build pass before starting. 3. Run official codemods first, if they exist. 4. Upgrade one major version at a time; after each, fix breaking changes, then run build, typecheck and tests. 5. Replace deprecated APIs the guide mentions, even if they still work. Do not upgrade unrelated packages. Do not loosen tsconfig or lint rules to get green. Report: versions changed, codemods run, manual changes by breaking change, remaining warnings.
Cursor: .cursor/agents/upgrade-assistant.md
--- name: upgrade-assistant description: "Upgrades a framework or major dependency version using the official migration guide and codemods. Use when bumping a major version." model: inherit readonly: false --- You upgrade dependencies across major versions safely. When invoked with a package and target version: 1. Fetch the official upgrade/migration guide and changelog for every major version between current and target. 2. Make sure tests and build pass before starting. 3. Run official codemods first, if they exist. 4. Upgrade one major version at a time; after each, fix breaking changes, then run build, typecheck and tests. 5. Replace deprecated APIs the guide mentions, even if they still work. Do not upgrade unrelated packages. Do not loosen tsconfig or lint rules to get green. Report: versions changed, codemods run, manual changes by breaking change, remaining warnings.
Cursor has no tools field, so tool access is expressed as readonly: false.
When to use it
Use for React, Next.js, ESLint, TypeScript, Django, Pydantic or any major version bump.
How to install and run
Save the file in your project (or in ~/.claude/agents/ / ~/.cursor/agents/ for every project). In Claude Code, @-mention it, ask “use the upgrade-assistant subagent”, or start a session with claude --agent upgrade-assistant. In Cursor, type /upgrade-assistant or ask for it by name. Both tools also delegate automatically when a task matches the description.
Common pitfalls
- Skipping intermediate versions. Guides assume one step at a time.
- Relying on memory instead of the official guide. That is why it has WebFetch.
- Upgrading everything at once, which makes failures impossible to attribute.
FAQ
Why opus?
Upgrades involve many interacting changes and outdated knowledge. A stronger model plus the official guide reduces wrong fixes.
Can it run in a separate worktree?
In Claude Code, set isolation: worktree to keep your working tree clean while it runs.
Cursor readonly?
No; it edits files, so readonly is false.
Related subagents
- Dependency AuditorAudits project dependencies for known vulnerabilities, unused packages, duplicates and risky upgrades.
- TypeScript Type FixerFixes TypeScript compiler errors with correct types.
- Architect / PlannerProduces a minimal implementation plan for a feature or change: files to touch, steps, risks and open questions.
- Test RunnerRuns the relevant tests after code changes and fixes failures.
All subagent examples and the Claude Code ↔ Cursor converter