Add squad workstream add / remove / upgrade commands #1136

Problem

mfrieman/agentic-ai-collective
(v0.1.0-alpha) ships workstream compositions — named, additive bundles of
agents, skills, routing overlays, and merge patches that layer a discrete workflow
onto an existing squad without replacing it. These live under
compositions/workstreams/<name>/ with a manifest.json, an overlay/ subtree,
and a merge/ subtree containing .merge files for existing squad documents.

There is no upstream CLI command to install, remove, or upgrade a workstream. The
current workaround is a multi-step manual copy:

squad upstream sync collective
cp -r ~/.squad/upstream/collective/compositions/workstreams/code-review/overlay/ .squad/
# manually process merge/ patches against existing team.md, routing.md, etc.
# manually copy and install referenced atoms
# manually update .squad/assets.lock.json

Manual merge processing is error-prone. There is no record of which workstreams
are installed, so there is nothing to remove or upgrade later.

Current state

squad upstream sync can pull a remote library. There is no squad workstream
subcommand family. The .merge file format has no CLI consumer today.

Note: there are two open upstream issues that touch adjacent territory:
#200 PRD: Squad Workstreams
(broader workstream concept) and
#271 rename workstreams → SubSquads
(naming). This issue is specifically about the install / lifecycle CLI surface,
not the conceptual model or naming.

Desired state

A squad workstream subcommand for lifecycle management of installed workstreams.

# Install a workstream from a registered upstream
squad workstream add collective/code-review --as review

# Install by canonical URI (pinned version)
squad workstream add squad://mfrieman/agentic-ai-collective/workstreams/code-review@1.0.0 --as review

# List installed workstreams
squad workstream list

# Remove an installed workstream (reverting tagged-block merges)
squad workstream remove review

# Upgrade an installed workstream to a newer version
squad workstream upgrade review --to 1.1.0

What add should do:

1. Resolve the workstream manifest from the upstream registry.
2. Copy overlay/ files into .squad/ (new files, no conflicts).
3. Process merge/ patches — insert tagged blocks into existing squad documents
   (see Issue feat: Issue Assignment & Auto-Triage for Squad Members #5 for the merge engine).
4. Materialize all referenced atoms to their canonical install targets.
5. Record the workstream in .squad/assets.lock.json so remove and upgrade
   know what was installed, what was overlaid, and which blocks were merged.

What remove should do:

1. Look up the workstream record in the lockfile.
2. Remove tagged blocks from merged files (see Issue feat: Issue Assignment & Auto-Triage for Squad Members #5).
3. Delete overlay files that are unmodified since install.
4. Remove materialized atoms that are not shared with other installed workstreams.

What upgrade should do:

1. Diff the old manifest against the new version.
2. Add/remove overlay files and merge blocks as needed.
3. Update the lockfile entry.

Acceptance criteria

• squad workstream add <upstream>/<name> [--as <alias>] installs overlay
  files, processes merge patches, and materializes atoms.
• squad workstream add squad://<uri>@<ver> works without a pre-registered
  upstream.
• squad workstream list shows installed workstreams with their source URI,
  installed version, and local alias.
• squad workstream remove <alias> cleanly reverses the install: removes
  tagged blocks, removes unmodified overlay files, and updates the lockfile.
• squad workstream upgrade <alias> [--to <ver>] upgrades to the specified
  (or latest) version, preserving user edits outside tagged blocks.
• After any operation, .squad/assets.lock.json accurately reflects the
  current installed state.
• squad workstream add --dry-run prints what would change without writing.

References

• mfrieman/agentic-ai-collective v0.1.0-alpha — consumer library motivating this gap
• ARCHITECTURE.md — "Workstream Anatomy"
• ARCHITECTURE.md — "Today vs. Target"
• docs/usage/add-a-workstream.md
• .squad/decisions.md lines 539–540 — flags squad workstream list/add/remove/upgrade as upstream gaps
• Related upstream: #200 PRD: Squad Workstreams,
  #271 rename workstreams → SubSquads
• Related gap issues: Issue [TEST] API capability test — will be deleted #3 (squad:// URI resolver), Issue feat: Issue Assignment & Auto-Triage for Squad Members #5 (tagged-block merge engine),
  Issue Feature: Get squads to use project boards #6 (workstream directory layout)

Notes

• remove must not delete user content that was added inside a tagged block
  region. Safest behavior: warn and skip modified blocks, leaving them in place.
• The --as <alias> flag is important for teams that install the same workstream
  type twice (e.g., two separate review flows). The alias becomes the key in the
  lockfile.
• Workstream install order may matter if two workstreams merge into the same file;
  a deterministic ordering rule (alphabetical by alias, or explicit
  --after <alias>) should be defined.
• The naming question (workstream vs SubSquad per feat: rename workstreams → SubSquads (community decision) #271) is orthogonal to this
  feature; whatever name wins, this CLI surface is needed.