Implement squad:// URI resolver #1137

Problem

mfrieman/agentic-ai-collective
(v0.1.0-alpha) uses a canonical URI scheme to reference all atoms and compositions:

squad://<owner>/<repo>/<kind>/<name>@<version>

Examples:

squad://mfrieman/agentic-ai-collective/agents/code-reviewer@1.0.0
squad://mfrieman/agentic-ai-collective/skills/reviewer-protocol@^1.0.0
squad://mfrieman/agentic-ai-collective/squad-templates/general-dev@1.0.0
squad://mfrieman/agentic-ai-collective/workstreams/code-review@1.0.0

These URIs appear in:

• atom.json and manifest.json dependency lists
• .squad/assets.lock.json source_uri fields
• CLI target flows throughout the library's documentation

The upstream Squad CLI has no resolver for this scheme. There is no mechanism to
hand the CLI a squad:// URI and have it fetch, validate, and install the
referenced asset. Every consumer operation that mentions squad:// is currently
manual.

Current state

squad upstream add <git-url> registers a remote git repository. The CLI does not
parse or resolve squad:// URIs. There is no registry lookup, ref resolution, or
caching layer for the squad:// scheme.

Desired state

A URI resolver embedded in the Squad CLI that handles squad:// references
end-to-end, exposed through the commands that need it (squad template apply,
squad workstream add, squad asset add, etc.).

Resolution algorithm

squad://mfrieman/agentic-ai-collective/agents/code-reviewer@1.0.0
   │        │              │                 │         │        │
   scheme   owner          repo             kind      name    version-spec

1. Check local cache: ~/.squad/cache/<owner>/<repo>/<ref>/
2. If cache miss (or stale):
   a. Resolve repo → https://github.com/<owner>/<repo> (or configured registry)
   b. Fetch git ref that satisfies <version-spec> (exact tag or semver range)
   c. Walk <kind>/<name>/atom.json (or manifest.json for compositions)
   d. Store in local cache with content hash
3. Return resolved asset root path + metadata

Version spec support

Registry configuration

# Default registry: GitHub (https://github.com/<owner>/<repo>)
# Allow override for private registries or mirrors
squad config set registry.default https://github.com
squad config set registry.myorg https://github.myorg.com

Acceptance criteria

• squad://owner/repo/kind/name@exact-version resolves to the correct asset
  directory in the local cache.
• Semver range specs (@^1.0.0, @~1.0.0) resolve to the highest matching
  published git tag in the target repository.
• @latest resolves to the latest non-prerelease tag.
• Git SHA pinning works for both full and abbreviated SHAs.
• Resolved assets are cached in ~/.squad/cache/ (or platform equivalent)
  and reused on subsequent runs without a network call.
• Cache invalidation: squad cache clean or --no-cache forces a fresh
  fetch.
• The resolver raises a clear error with actionable message when a URI cannot
  be resolved (repo not found, version not found, asset path missing).
• Private/enterprise registry URLs can be configured via squad config.

References

• mfrieman/agentic-ai-collective v0.1.0-alpha — consumer library motivating this gap
• ARCHITECTURE.md — "Reference Syntax"
• ARCHITECTURE.md — "Today vs. Target"
• docs/usage/upstream-and-link-explained.md
• .squad/decisions.md line 560 — flags canonical URI resolution as upstream gap

Notes

• The resolver is infrastructure shared by squad template apply (feat: worktree awareness, Scribe auto-commit, and decision consolidation #1),
  squad workstream add (feat: GitHub Issues intake, PRD mode, and human team members #2), squad asset add (How to Update squad When a New Version is Released #7), and lockfile pin
  verification (Feature: Issue Assignment & Auto-Triage for Squad Members #4). Shipping it as a standalone internal module unlocks all
  the higher-level commands.
• Version range resolution requires reading git tags from the remote. For
  performance, the CLI should cache the tag list alongside the asset cache.
• Security: the CLI should verify content hashes against the lockfile when
  re-materializing from cache (see lockfile issue Feature: Issue Assignment & Auto-Triage for Squad Members #4).
• squad link <local-path> --as squad://... provides a development escape hatch
  to point the resolver at a local directory instead of fetching remotely. This
  already partially exists in the upstream CLI; the resolver should honor it.