Opensrc Knowledge Refactor Grill Log

Purpose: pin the requirements for extending opensrc guidance from one-to-one package/source inspection into curated framework-pack example repository context.

Initial situation:

• Current harness guidance treats opensrc mainly as package/library source inspection: use opensrc path <package> for npm packages and opensrc path owner/repo for upstream repositories.
• docs/reference/dp-requirements.md currently says scaffold output should not preselect concrete opensrc repositories.
• Framework packs already exist in the CLI pack catalog, including the effect pack.
• The proposed refactor adds a second opensrc context: curated example repositories attached to framework packs, starting with the Effect pack.

Branch: Opensrc Context Model

Status: active.

Open question: should curated example repositories be first-class pack metadata, generated prompt guidance, wiki/docs knowledge, or only prose inside scoped AGENTS.md files?

Q1

Question: Does the new curated example-repository context supersede the current rule that scaffold output should not preselect concrete opensrc repositories?

Accepted answer:

• Yes, but only for curated framework-pack knowledge, not arbitrary target-repo setup.
• Refined axiom: scaffold setup must not invent or auto-select arbitrary opensrc repositories, but framework packs may declare curated example repositories as maintained pack knowledge.
• This preserves the old guardrail against random source selection while allowing intentional pack-maintainer curation.

Q6

Question: Where is the source of truth for the example repository catalog?

Accepted answer:

• The source of truth is pack catalog metadata in apps/cli/src/data/catalog/packs.ts.
• Scaffold prompt generation should surface that metadata where relevant.
• Docs and wiki may describe the model, but code owns the scaffoldable catalog.

Branch: Effect Pack Example Repositories

Status: active.

Seed repositories:

• AnswerOverflow/AnswerOverflow — Effect v3 example.
• rhyssullivan/executor — Effect v4 example.
• alchemy-run/alchemy-effect
• anomalyco/opencode
• pingdotgg/t3code

Open question: what role should each repository play in the Effect pack, and should version/focus metadata be mandatory?

Q2

Question: What metadata is mandatory for each curated example repository?

Accepted answer:

• Only these fields are mandatory:
  • repo: repository owner/name.
  • url: repository URL.
  • packs: list of pack mappings, each shaped as { uid, version }.
• Do not add mandatory why, inspectFor, avoidUsingFor, or similar intent fields to the repository entry schema.

Q3

Question: Where should usage intent live if not in each example repository entry?

Accepted answer:

• Keep guidance generic, but make the real criterion explicit.
• Example repositories are there so agents can gather examples of real-world patterns and code architectures that follow the skills included by the relevant pack.
• Do not maintain per-repository intent fields in the example repository schema.
• This supersedes vaguer wording that described example repositories as general inspiration; they must be used as pack-skill-aligned evidence sources.

Q4

Question: How should unknown or partial versions be represented in packs[].version?

Accepted answer:

• Versions should not be unknown in curated example repository entries.
• Reference the package versions clearly from the cloned example repository manifests, such as the relevant package.json.
• Do not introduce nullable, partial, or "unknown" fallback version semantics unless a future concrete need appears.

Q5

Question: Should a repository be allowed in a pack only if at least one included skill can use it as evidence?

Accepted answer:

• No explicit validation gate is needed.
• Repositories are manually selected by the pack maintainer.
• The guidance still explains that curated repositories are used to gather real-world examples aligned with the pack's included skills, but inclusion itself is a maintainer curation decision.

Branch: Scoped AGENTS.md Guidance

Status: active.

Open question: which generated/scoped prompt surfaces must explicitly instruct agents to inspect package sources and curated example repositories, and under what trigger?

Q7

Question: Where should curated example repositories be emitted?

Accepted answer:

• Emit concrete curated example repositories in generated workspace/scoped prompt specs for scopes whose selected packs include those repositories.
• Those scoped prompts should include explicit opensrc guidance for the pack's curated example repositories.
• Root shared .agents/AGENTS.md should keep generic source-inspection guidance by default, not every concrete curated repo list.
• Setup summary or handoff output may surface the selected-pack example repositories as context for the follow-up authoring agent.