Native resolution of .squad/workstreams/<name>/ directory layout #1140

Problem

mfrieman/agentic-ai-collective
(v0.1.0-alpha) defines a workstream-as-directory layout where each installed
workstream lives as a self-contained directory under .squad/workstreams/<name>/,
containing its own manifest, agents, and configuration. The workstream's agents
are additionally namespaced under .squad/agents/<alias>--<agent-id>/ to prevent
naming collisions when multiple workstreams install the same agent type.

The upstream Squad CLI has no concept of this layout. When Squad resolves agents,
routing, and ceremonies, it looks at a flat .squad/ structure with no
sub-directory namespace awareness. This means:

1. Installing a workstream that adds agents requires placing them directly in
   .squad/agents/ with no provenance record of which workstream owns them.
2. Two workstreams that both install a code-reviewer agent would collide without
   an aliasing convention.
3. Removing a workstream requires knowing exactly which files it contributed —
   information the CLI has no way to track without a workstream-aware layout.

Current state

The Squad CLI resolves agents from .squad/agents/<name>/ (flat). There is no
.squad/workstreams/ directory traversal, no namespace support for
<alias>--<agent-id>, and no manifest scan within a workstream subdirectory.

Desired state

The Squad CLI should natively understand the workstream-as-directory layout:

.squad/
├── workstreams/
│   └── review/                         ← installed workstream alias
│       ├── manifest.json               ← workstream metadata (source_uri, version)
│       ├── agents/
│       │   └── reviewer--code-reviewer/ ← namespaced: <alias>--<agent-id>
│       │       └── charter.md
│       └── config.md                   ← workstream-specific config (optional)
├── agents/                             ← flat agent namespace (non-workstream agents)
│   └── ...
└── routing.md

What the CLI should do

1. Discovery: When scanning for available agents, scan both .squad/agents/
   (flat) and .squad/workstreams/*/agents/ (workstream-owned). Merge the results
   into a single resolved agent set.

2. Namespace aliasing: Treat <alias>--<agent-id> as "agent <agent-id>
   owned by workstream <alias>". Route to the namespaced copy when the workstream
   context is active.

3. Manifest reading: Each .squad/workstreams/<name>/manifest.json records
   the source workstream URI and version. squad workstream list reads these
   manifests to report installed workstreams even if the lockfile is absent.

4. Isolation: Changes to files inside .squad/workstreams/review/ should not
   be confused with changes to .squad/agents/ by squad's file-watching or
   routing resolution.

Example manifest at .squad/workstreams/review/manifest.json

{
  "alias": "review",
  "source_uri": "squad://mfrieman/agentic-ai-collective/workstreams/code-review@1.0.0",
  "installed_at": "2026-05-19T13:42:00Z",
  "agents": ["reviewer--code-reviewer"],
  "merge_targets": [".squad/team.md", ".squad/routing.md"]
}

Acceptance criteria

• The Squad CLI scans .squad/workstreams/*/agents/ and merges discovered
  agents into the routing resolution set alongside .squad/agents/.
• Agent names of the form <alias>--<agent-id> are parsed correctly: the
  <alias> identifies the owning workstream, <agent-id> is the canonical
  agent kind.
• squad workstream list reads .squad/workstreams/*/manifest.json to report
  installed workstreams, their source URI, and version — without requiring the
  lockfile to be present.
• Two workstreams can install the same agent kind (different aliases) without
  collision.
• squad does not error or warn on a .squad/workstreams/ directory it
  doesn't understand — graceful degradation is acceptable as an interim state
  before full support lands.

References

• mfrieman/agentic-ai-collective v0.1.0-alpha — consumer library motivating this gap
• ARCHITECTURE.md — "Workstream Anatomy"
• .squad/decisions.md line 563 — flags native workstream directory layout as upstream gap
• .squad/decisions.md line 602 — ratified workstream install model with namespace aliasing
• Related gap issues: Issue feat: GitHub Issues intake, PRD mode, and human team members #2 (workstream lifecycle commands), Issue feat: Issue Assignment & Auto-Triage for Squad Members #5 (tagged-block merge)

Notes

• The .squad/workstreams/<name>/ layout is intentionally parallel to
  compositions/workstreams/<name>/ in the library — installed form mirrors
  source form.
• The namespace separator -- (double-dash) was chosen to be unambiguous
  in kebab-case contexts. Brady may want to pick a different separator; the
  important requirement is that some separator distinguishes ownership.
• If squad ever supports multiple concurrent squads in a monorepo, the
  workstream layout would naturally extend to per-subproject namespacing.
• This is a foundational issue: the workstream lifecycle commands (feat: GitHub Issues intake, PRD mode, and human team members #2) can't
  install to a sensible layout without this being defined.