Skip to content

Add collection members key with computed @library membership #887

Description

@williamthorsen

Problem

Collections express their constituents through the same dependencies: frontmatter key any artifact uses for prerequisite edges (#876). The two ideas are distinct (a collection contains members; a skill depends on a rulebook), and one key for both blurs them. There is also no way to mean "the whole catalog" without a hand-maintained member list that drifts as artifacts are added.

Context

Proposed solution

Separate collection membership from prerequisite edges, and add a computed whole-catalog token.

  • members: (new, collections only): a collection's constituents. Value is either an explicit per-type object (rulebooks:/skills:/subagents:/collections: slug lists, the shape dependencies: already uses) or the token '@library'.
  • dependencies: (retained, non-collections): genuine prerequisite edges on rulebooks, skills, and subagents. The resolver follows members: and dependencies: identically; the split is semantic, not mechanical.
  • '@library' token: resolves to every deployable artifact (all rulebooks, skills, and subagents), enumerated from the content library so a newly added artifact joins automatically. Collections are excluded: the resolver never emits them, and "all collections" would be self-referential. The @ sigil marks a sentinel directive, distinct from a literal slug, and is YAML-quoted.
  • all collection: a real content/collections/all.md carrying members: '@library', the canonical consumer of the token, appearing in library list.

Membership is kept orthogonal to delivery: @library answers what is in the catalog, not where or how it is delivered. So @library includes rulebooks (not a skills-and-subagents-only token); any global-delivery narrowing for repo-specific rulebooks is governed by delivery scope and the collection a domain declares, which is #878's concern, not the token's.

The user-facing declaration is unchanged: codeassembly.yaml still references collections via collections: use: [...]. Per-type computed tokens (e.g. skills: '@all') are out of scope; only the whole-catalog '@library' token is introduced.

Acceptance criteria

Must have

  • Collections declare constituents via a members: key; dependencies: is no longer used for collection membership, and recommended.md is migrated to members:.
  • members: accepts either an explicit per-type object (rulebooks:, skills:, subagents:, collections: slug lists) or the '@library' token.
  • '@library' resolves to every deployable artifact (all rulebooks, skills, and subagents) computed from the library with no hand-maintained list; collections are excluded.
  • dependencies: continues to resolve prerequisite edges on rulebooks, skills, and subagents.
  • content/collections/all.md exists with members: '@library'; resolving collections: use: [all] yields the full deployable catalog, deduped, and a newly added artifact joins that closure with no edit to all.md.
  • library list shows all.
  • New and modified behavior is covered by tests.
  • README documents the members:/dependencies: split, the '@library' token, and the all collection.

Should have

  • An unrecognized members: token (anything other than '@library') produces a clear error naming the offending collection.
  • A collection that declares dependencies: produces a clear error (membership moved to members:), naming the collection.
  • A non-collection that declares members: produces a clear error (membership is collections-only), naming the artifact.

Metadata

Metadata

Labels

featureAdded or improved external functionalityscope:agents

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions