waldronlab / waldronlab/agent-protocol-standard

Add an `update-protocol` skill

Open
#36 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
Python
Stars
3
Forks
1
Avg merge
14h 8m
Merged PRs (30d)
23

Description

The version-bump path is bookkeeping, and bookkeeping is what a human gets wrong. Bumping a protocol means:

  • version and date in the frontmatter
  • a new ### Version X.Y.Z (YYYY-MM-DD) entry at the top of ## History & Reviews, with a #### Changes list and *No reviews yet.* under #### Reviews
  • that top entry agreeing with the frontmatter on both version and date, which the validator does check
  • updating the pin in every composite that lists this protocol in protocols_used

A skill should do all four, and refuse to bump a protocol whose dependents it can't see rather than leaving a half-finished bump.

On the last one

The pin has to change today only because the index carries HEAD and nothing else. Once an atomic protocol is at 1.1.0, the index no longer has an entry for 1.0.0, so a composite pinning 1.0.0 can't resolve it. That's H1, not a property of composites — if the index carried every released version, the pin would keep resolving and the composite wouldn't need touching at all.

The composite's own version is a separate question, and probably doesn't need to bump for provenance reasons: the runner emits the Method Provenance block for every protocol in the chain, each at its own version, so a chain of composite v1.0.0foo v1.1.0 is cited accurately without a bump. The argument for bumping is narrower — if the pin changed, composite v1.0.0 means different things before and after, so the version number stops identifying a fixed behaviour. Worth settling deliberately rather than by habit, and it goes away entirely when H1 does.

Also worth knowing

Nothing currently checks the pinned version. scripts/validate-protocol.R requires protocols_used[].version to be a string and, for a dependency in the same repository, checks the file exists — it never compares the pin against the dependency's actual version. A stale pin passes CI and fails later in the runner, at resolution time.

The five pins in humann4-database-build all match at 1.0.0 right now, so nothing is broken. Nothing would have caught it if they weren't. A local check is a few lines next to the existing existence check, and worth adding whether or not this skill gets written.

Lives at skills/update-protocol. Pairs with #35 and #37.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in skills/update-protocol and inspect the protocol frontmatter, History & Reviews structure, and composite protocols_used entries it must update. Read scripts/validate-protocol.R, especially its dependency existence check; done means the skill performs all four updates, refuses incomplete dependent discovery, and the local pin check is addressed or deliberately separated.

Written by the indexing model from the issue text.

Assessment

Tech stack
python, r
Domain
tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.