Plain Upgrade
Developmentplain-upgradePlain Upgrade is an Agent Skill for development published in the dropseed/plain repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Upgrades Plain packages and applies required migration changes. Use when updating to newer package versions.
QUICK START
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/dropseed/plain/blob/HEAD/.claude/skills/plain-upgrade/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/plain-upgrade, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Upgrade Plain Packages
1. Run the upgrade
uv run plain upgrade [package-names...]
This will show which packages were upgraded (e.g., plain-postgres: 0.1.0 -> 0.2.0).
2. Review the changelog for each upgraded package
For each package that was upgraded:
- Run
uv run plain changelog <package> --from <old-version> --to <new-version> - Read both sections:
- "What's changed" — new features, behavior changes, bug fixes worth knowing about
- "Upgrade instructions" — required code changes (or "No changes required")
- If there are required code changes, apply them
- Capture a short summary of "What's changed" for the final report — surface new APIs, new settings, new CLI commands, performance improvements, and notable bug fixes even when no code changes are required. Skip pure internal cleanup.
3. Update agent rules and skills
Run uv run plain agent install to sync any updated rules and skills from the upgraded packages.
4. Validate
- Run
uv run plain fixto fix formatting - Run
uv run plain checkto validate (linting, preflight, migrations, tests)
5. Report
For each upgraded package, report:
- Version bump (e.g.,
plain-postgres: 0.103.0 -> 0.105.0) - A 1-3 bullet summary of notable changes from "What's changed" (new features, behavior changes, perf wins, notable fixes)
- What code changes were applied (or "no code changes required")
Guidelines
- Process ALL packages before testing
- DO NOT commit any changes
- Keep code changes minimal and focused
- Report any issues or conflicts encountered