Spec: Curated Opensrc Example Repositories

User Input

/goal Deliver Linear epic IP-157, "Curated opensrc example repositories for framework packs", and all child issues IP-158, IP-159, IP-160, and IP-161 end to end in /Users/stefan/Desktop/repos/wearedevpunks-cli through $delivery-phase.

Relevant pinned requirements:

• Framework packs may declare maintainer-curated example repositories as maintained pack metadata.
• Example repository entries use only repo, url, and packs.
• Each packs entry uses only uid and version.
• Example repository versions come from cloned example repository package manifests.
• Example repositories are evidence sources for real-world patterns and code architectures aligned with a selected pack's included skills.
• Scaffold setup must not invent, infer, or auto-select arbitrary opensrc repositories.
• Root shared guidance stays generic; concrete example repository lists belong in selected-pack scoped or workspace prompt guidance.

Context

The scaffold catalog already maps framework packs to skills, prompt surfaces, hooks, lint assets, and prompt details. Agents also have opensrc guidance for direct package or upstream source inspection, but pack-selected examples are a different kind of context: curated real-world repositories that help agents study architecture and usage patterns for the skills a pack includes.

Operators and generated agents need this context to be explicit where a pack applies, without weakening the anti-guessing guardrail that prevents scaffold setup from inventing arbitrary repositories.

Non-Goals

• Adding curated example repositories for non-Effect packs.
• Validating whether a repository belongs in a pack beyond maintainer curation.
• Adding per-repository explanatory fields such as why, inspectFor, or avoidUsingFor.
• Representing versions as unknown or partial fallbacks.
• Listing every concrete example repository in root shared guidance by default.
• Moving scaffold behavior into the shared scaffold model package.

Acceptance Criteria

• Pack metadata can represent curated example repositories attached to one or more packs.
• Every curated example repository records only repo, url, and packs.
• Every packs entry records only uid and version.
• Catalog consumers can read curated example repository metadata from the same pack source of truth as skills, prompt surfaces, hooks, lint assets, and prompt details.
• The Effect pack includes AnswerOverflow/AnswerOverflow.
• The Effect pack includes rhyssullivan/executor.
• The Effect pack includes alchemy-run/alchemy-effect.
• The Effect pack includes anomalyco/opencode.
• The Effect pack includes pingdotgg/t3code.
• Every seeded Effect example repository records an Effect version read from that cloned repository's package manifest.
• Generated scoped or workspace guidance for a scope with the Effect pack lists the curated examples and tells agents to inspect them with opensrc path owner/repo.
• Generated guidance explains that curated examples are for gathering real-world patterns and code architectures aligned with the pack's included skills.
• Root shared guidance remains generic and does not list every concrete example repository by default.
• Scaffold setup still does not invent or auto-select arbitrary repositories outside maintained pack metadata.
• Requirements docs distinguish direct package source context from curated example repository context.
• Wiki/project context links the grill and backlog artifacts for this refactor.
• Current-behavior docs describe curated example repositories only after the implementation lands.

Constraints

• Keep prompt/spec resolution logic in this repository.
• Keep consumer-repo business logic out of the CLI.
• Keep packages/scaffold limited to stable schemas and types; prompt rendering remains app-owned.
• Preserve the existing opensrc path <package> and opensrc path owner/repo distinction.
• Keep changes surgical to the pack catalog, prompt generation, tests, and required docs/wiki surfaces.

Technical Notes

• Source requirements live in docs/opensrc-knowledge-refactor-grill-status.md, docs/opensrc-knowledge-refactor-grill-log.md, and docs/opensrc-knowledge-refactor-backlog.md.
• Existing pack catalog and content helpers live under apps/cli/src/data/catalog and apps/cli/src/content.
• Shared scaffold model schemas live under packages/scaffold and must remain behavior-free.

Decision Log