Add squad asset add — install a single atom from a remote registry #1141

Problem

mfrieman/agentic-ai-collective
(v0.1.0-alpha) publishes individual atoms — agents, skills, instructions, and
hooks — as first-class versioned units, each addressable by a canonical
squad:// URI.

Often a team only needs a single atom, not an entire template or workstream. For
example:

• Add the code-reviewer agent to an existing squad without applying the full
  general-dev template.
• Pull the reviewer-protocol skill into a project that already has its own
  squad structure.
• Install the reviewer-lockout-enforcer hook into a project's .copilot/ tree.

Today the workflow is:

git clone https://github.com/mfrieman/agentic-ai-collective.git
cp -r catalog/agents/code-reviewer/ /your/project/.squad/agents/
# manually update .squad/assets.lock.json

There is no CLI command to do this. A consumer cannot squad asset add ... and
expect the CLI to fetch, place, and record the atom.

Current state

The squad upstream family can register and sync remote repositories. There is no
squad asset subcommand family and no mechanism to install a single atom from a
squad:// URI.

Desired state

A squad asset subcommand for installing, upgrading, and removing individual
atoms.

# Install a single agent by URI (pinned version)
squad asset add squad://mfrieman/agentic-ai-collective/agents/code-reviewer@1.0.0

# Install with a local alias (for namespace clarity)
squad asset add squad://mfrieman/agentic-ai-collective/agents/code-reviewer@1.0.0 --as reviewer

# Install a skill
squad asset add squad://mfrieman/agentic-ai-collective/skills/reviewer-protocol@1.0.0

# Install an instruction snippet
squad asset add squad://mfrieman/agentic-ai-collective/instructions/reviewer-lockout@1.0.0

# Install a hook
squad asset add squad://mfrieman/agentic-ai-collective/hooks/reviewer-lockout-enforcer@1.0.0

# Install from a registered upstream using short form
squad asset add collective/agents/code-reviewer@1.0.0

# Upgrade an installed atom
squad asset upgrade reviewer --to 1.1.0

# Remove an installed atom
squad asset remove reviewer

# List installed atoms
squad asset list

What add should do, by kind:

Install targets are defined in atom.json compatibility.consumerTargets and
should be honored by the CLI.

Acceptance criteria

• squad asset add squad://<owner>/<repo>/<kind>/<name>@<ver> fetches the
  atom and installs it to the correct target path for its kind.
• squad asset add <upstream>/<kind>/<name>@<ver> works with a registered
  upstream name in place of the full URI.
• --as <alias> allows the consumer to choose a local name independent of
  the atom's canonical name.
• After install, .squad/assets.lock.json contains an entry for the atom
  with source_uri, resolved_version, install_path, and content_hash.
• squad asset upgrade <alias> [--to <ver>] updates the atom to the specified
  (or latest compatible) version.
• squad asset remove <alias> removes the installed files and the lockfile
  entry.
• squad asset list shows all installed atoms with source URI, version, and
  install path.
• Installing an instruction atom merges its content into the appropriate
  copilot-instructions.md using the tagged-block mechanism (Issue feat: Issue Assignment & Auto-Triage for Squad Members #5), with
  assembly.order and assembly.scope from atom.json respected.

References

• mfrieman/agentic-ai-collective v0.1.0-alpha — consumer library motivating this gap
• ARCHITECTURE.md — "Lifecycle: Consumer Install"
• ARCHITECTURE.md — "Today vs. Target"
• README.md — "Cherry-pick an atom"
• docs/usage/consume-an-atom.md
• .squad/decisions.md line 544 — flags squad asset add as upstream gap
• .squad/decisions.md line 564 — flags remote atom install as upstream gap
• Related gap issues: Issue [TEST] API capability test — will be deleted #3 (URI resolver), Issue Feature: Issue Assignment & Auto-Triage for Squad Members #4 (lockfile), Issue feat: Issue Assignment & Auto-Triage for Squad Members #5 (tagged-block merge)

Notes

• Instruction installs are more complex than agent/skill installs because they
  need to be merged into an existing file rather than copied to a new path.
  The tagged-block merge engine (Issue feat: Issue Assignment & Auto-Triage for Squad Members #5) should handle this. If that issue is
  deferred, a simpler append-only behavior is acceptable as a first cut.
• Hook installs may need to wire into the project's package.json or squad
  config if the hook needs to be loaded at runtime. The exact wiring mechanism
  depends on Squad SDK hook registration — Brady should define this.
• The squad asset family is the smallest useful CLI surface — it should ship
  before or alongside template apply (feat: worktree awareness, Scribe auto-commit, and decision consolidation #1) and workstream add (feat: GitHub Issues intake, PRD mode, and human team members #2), since those
  commands depend on the same atom materialization logic internally.