waldronlab / waldronlab/agent-protocol-standard
Define a canonical fully-qualified name syntax for protocols
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 3
- Forks
- 1
- Avg merge
- 14h 8m
- Merged PRs (30d)
- 23
Description
As the federation grows, name collisions across repositories are inevitable — deseq2-differential-expression is not a name any one lab owns. The protocols_used object already disambiguates in frontmatter, but there is no canonical string form for naming a protocol unambiguously in a log line, a provenance block, a tool call, or a sentence.
The runner already needs this. Step 2.1 treats a user-named repository or version as a hard filter — "the waldronlab/agent-protocols version", "v1.2.0" — but there is no defined way to write that reference down. The behavior exists; the syntax for invoking it does not.
Proposed
Define a canonical fully-qualified form in PROTOCOL_STANDARD.md:
<owner>/<repository>::<protocol-name>@<version>
waldronlab/agent-protocols::humann4-sgb-aggregation@1.0.0
:: separates repository from protocol because a bare @repository/protocol collides with version pinning, and because repository names cannot contain ::. Since protocols_used.version is an exact requirement rather than a minimum, the version belongs in the canonical form; a reference without one is a query, not an identifier.
Standardize it for:
- agent tool calls and user requests,
- execution logs,
- the Method Provenance block,
- the departures summary and drafted Methods section.
Scope: display and reference, not storage
The three-field object form in protocols_used stays:
protocols_used:
- name: humann4-sgb-aggregation
repository: waldronlab/agent-protocols
version: 1.0.0
It is what the validator checks, it is more readable in YAML, and it diffs field-by-field. This issue adds a string rendering for the places a YAML object cannot go — it is not a migration of the frontmatter, and the two forms must round-trip.
Notes
- The grammar needs to say what is permitted in each position so the form is parseable rather than merely conventional; protocol names are already constrained to kebab-case by
PROTOCOL_STANDARD.md. - Worth deciding whether a version-less
owner/repo::nameis legal as an explicit "any version" query, or whether that ambiguity is best refused outright. Given that the runner aborts rather than substituting a different release, refusing is more consistent.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading PROTOCOL_STANDARD.md, especially the existing kebab-case protocol-name constraint and the protocols_used object definition. Specify the grammar and version requirement for the fully-qualified string, resolve the version-less query question, and document its use in tool calls, requests, logs, provenance, departures, and Methods text. Done means the string and object forms round-trip without changing storage.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100