agentleFS
Sign inStart free
pdparchitectpdparchitect/noodle/.agents/skills/version-bound-cleanup/SKILL.md

version-bound-cleanup

Skill259 starsChanged 35 days agoApache-2.0View on GitHub

Gating migrations and clean-up code behind an update milestone. Use when writing code that moves, renames, rewrites or deletes data left by an earlier version, reads an old format, or backfills a new field for existing data, in Noodle, Hub, Applet, Computer, Browser or Mobile; and when asked what clean-up code can be removed.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Add the milestone to the app's Support/update-milestones.json, in ascending order.

    line 22
  2. Distinctive:

    Create the file for an app that has none.

    line 23
  3. Very specific:

    Never write TODO(NEXT_VERSION) or a TODO without a milestone behind it.

    line 34

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Version-bound clean-up

A migration runs only for people who install the release that ships it. Sparkle lets people skip releases, so every migration is tied to an update milestone: a release people must run before any later one. The code lives until the release after the milestone, then goes.

The milestone mechanism is described in docs/releases.md, under Update milestones. Read it first.

When writing a migration

  1. Find the app whose release ships the code: its VERSION and changelog. Shared code under Sources/ ships with every app that runs it; gate it for each one.
  2. The milestone is that app's next release: the dated section still being prepared, otherwise the next version after VERSION. Ask if unsure which.
  3. Add the milestone to the app's Support/update-milestones.json, in ascending order. Create the file for an app that has none; release packaging picks it up.

  4. Mark the code, its call site and its tests with the release that may delete it, the one after the milestone:

    // TODO(Hub 0.7.0): remove with its call in HubBots.init and
// HubTests.testBotsFromBeforeGetTheirOwnerWhenTheHubOpens. Milestone: Hub 0.6.0.

    Name the app unless it is Noodle; version numbers differ between apps. Name every call site and test so removal is one pass.

  5. Never write TODO(NEXT_VERSION) or a TODO without a milestone behind it.
  6. Mention the milestone in the report to the user; it forces an upgrade step on them.

Mobile ships through the App Store, which has no milestones. Ask the user how long a Mobile migration stays.

Where skipping the milestone could damage data, keep a startup check that names the release to run first instead of deleting the code outright.

When asked what can be removed

  • grep -rn 'TODO(' --include='*.swift' outside .build, and compare each with its app's VERSION and milestones file.
  • Removable: the named release is at or below the next one, and the milestone it depends on is listed and published.
  • Flag anything overdue, and any TODO(NEXT_VERSION) or migration with no milestone.
  • Removing it follows the TODO: the code, its call sites and its tests, together.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free