Version refs: support pinning dependencies to git tags, branches, and commits

[kasperjunge]

Summary

Allow dependencies to specify a git tag, branch, or commit SHA in their handle, e.g.:

• user/skill#v1.0.0 (tag)
• user/skill#main (branch)
• user/skill#abc123 (commit)

Currently agr always resolves to the default branch HEAD, which means any upstream push silently changes what you get.

Why

This is a prerequisite for lockfiles, update workflows, and reproducibility. Without version refs, there is no way to pin a dependency to a known-good state.

Scope

• Extend ParsedHandle in handle.py to parse #ref suffix
• Extend Dependency in config.py to store the ref
• Update agr.toml format to support refs in handle strings
• Update git operations in git.py to checkout specific refs
• Update agr add to accept and store refs

🤖 Generated with Claude Code

[kasperjunge]

Design update: defer version refs behind lockfile

After discussion, we've decided to implement the lockfile (#497) first using implicit SHA pinning, rather than requiring explicit #ref syntax as a prerequisite.

How it works without version refs

When a user runs agr add user/skill, the lockfile silently records the resolved HEAD commit SHA. Reproducibility comes from the lockfile, not from user-specified version refs.

This follows the uv model: users write loose constraints, the lockfile pins exact versions. Skill authors don't need to create git tags or manage versioning.

Version refs become a power-user feature

The #ref syntax (user/skill#v1.0.0, user/skill#main) is still valuable as an optional power-user feature for pinning to a specific tag/branch/commit. But it's no longer a prerequisite for lockfile or reproducibility.

Updated priority

• Prerequisite for Lockfile: add agr.lock for reproducible installs #497 → Now independent of Lockfile: add agr.lock for reproducible installs #497
• Can be implemented after lockfile lands
• Lower priority than lockfile

🤖 Generated with Claude Code