Skip to content

ADR-132: Collaboration ways domain

Summary

  • Decided: A new top-level ways domain, collaboration, holds ways about working with other people and their agents. A domain is a top-level directory of ways: it groups them and is the unit a user enables or disables, and it does not affect matching. The first members are the new collaboration/onboarding-share way and teams, moved from meta/teams. meta/trust and meta/subagents stay in meta, and splitting meta/attend is deferred. The domain is named collaboration rather than agentic, and its ways sit directly under it.
  • Trades away: The project has one more domain boundary to enforce, or the new domain becomes a catch-all of its own. Moving teams required doc updates, and the locale translations and embedding corpus had to be regenerated before onboarding-share could match on more than its pattern.
  • One-way? No. The record calls a domain boundary a low-risk, reversible choice, because the directory decides organization and grouping, not matching.
  • Probes: Not confident (attend-split): Should the peer-awareness parts of meta/attend move into collaboration later? Yes or no. Not confident (subagents): Should subagents stay in meta? Yes or no.
  • Inversion: At one end, meta keeps every way about how the agent works, collaboration included. At the other, every way that involves another party moves into a collaboration domain. This sits between them: only ways that exist because the collaborators work through agents move, and foundational or execution ways stay in meta.

Context

Ways are organized into top-level domains (meta, softwaredev, ea, …). A domain is not a matching mechanism — disclosure is driven by frontmatter (description/vocabulary) and triggers (pattern/files/commands/state). The directory governs two other things: organization and the include/exclude unit (ways.json disabled domains, project-scope toggles per ADR-131). So a domain boundary is a low-risk, reversible choice — but it is the unit users reason about and toggle, so it's worth drawing on a real seam.

A new capability surfaced the gap: a way for when to publish a repo's onboarding guide as a share link a teammate's own agent opens directly. It had no natural home. Looking for one exposed that collaboration concerns are scattered or mis-filed under meta:

  • meta/teams — coordination norms for agents working in a team.
  • meta/trust — the relational model between Claude and the human.
  • meta/subagents — delegating work to ephemeral helpers.

meta is meant for how the agent itself operates (knowledge, memory, reasoning, persistence). "Working across the boundary to other people and their agents" is a distinct concern, and meta was drifting into a catch-all for it.

Decision

Create a top-level collaboration ways domain: ways about working across the boundary to other people and their agents — capabilities and norms that exist because the collaborators are agent-mediated.

Initial members:

  • collaboration/onboarding-share — new; when to surface publishing an onboarding guide as a teammate-openable share link.
  • collaboration/teams — moved from meta/teams (agent-team coordination norms).

Explicitly kept in meta, with rationale (so the boundary is enforceable, not aspirational):

  • meta/trust — a foundational model other domains derive from (5 referrers: ea, autonomy, delegation, onboarding-share). A root concept, not a collaboration occupant.
  • meta/subagents — execution/parallelization (referenced by delivery/implement). "How work gets done," not "collaborating with peers."

Deferred: meta/attend. Its children mix concerns — peer-session awareness is collaboration, but context-pressure is a solo signal. That's a per-child split, not a move; out of scope here.

Naming: chose collaboration over agentic. Every way is agent-run, so agentic fails to discriminate and invites junk-drawer growth. For the same reason, members sit flat (collaboration/onboarding-share) rather than under a redundant collaboration/agentic/ layer.

Consequences

Positive

  • A coherent home for a growing class of cross-agent collaboration ways; onboarding-share lands cleanly.
  • meta narrows back toward "how the agent itself operates," reducing catch-all drift.
  • Collaboration ways become a single include/exclude unit, toggleable as a group per project (ADR-131).

Negative

  • One more top-level domain to keep coherent — the boundary must be enforced or it becomes a different catch-all.
  • Moving teams carries a one-time doc-reconciliation tail (done: 3 live docs updated; legacy ADR-013 left pointing at the old path as a historical record).
  • Locale-alias translations and the embedding corpus for the new/moved ways must be regenerated; until then onboarding-share matches by pattern: only.

Neutral

  • No disclosure or behavior change — directory is organization + toggle unit, not a matching input. teams still fires identically (session-start, scope: teammate).
  • Future platform sharing/handoff capabilities now have an obvious destination.

Alternatives Considered

  • Keep onboarding-share in meta (e.g. meta/handoff) — rejected: meta is already absorbing collaboration concerns; the point is to stop that drift, not extend it.
  • Name the domain agentic — rejected: too broad to discriminate (all ways are agentic); a junk-drawer waiting to happen.
  • Sub-group as collaboration/agentic/… — rejected: redundant nesting; the whole domain is agent-mediated.
  • Move trust/subagents/attend in too — rejected/deferred: trust is foundational and heavily referenced, subagents is execution, attend mixes solo and collaboration signals (needs a split, not a move).