Plan: IP-157 Curated Opensrc Example Repositories

Initial Situation

The scaffold catalog already carries pack-owned skills, lint assets, hooks, prompt surfaces, and prompt details. The current opensrc guidance covers direct package source inspection and upstream repository source lookup, but it does not model maintainer-curated example repositories per framework pack.

The requirements grill resolved the tension with the existing anti-guessing rule: scaffold setup must not invent arbitrary repositories, but framework packs may declare curated examples as maintained pack knowledge.

Issue

Agents using generated scoped prompts need concrete pack-specific examples when a framework pack applies to their workspace. Without cataloged examples, the prompt system can only give generic opensrc guidance or rely on ad hoc operator memory. That loses useful real-world architecture context and weakens repeatability.

Solution Shape

Add curated example repository metadata to the pack catalog and shared scaffold pack schema. Keep the entry shape minimal: repo, url, and packs, where each pack reference is { uid, version }. Seed only the Effect pack. Expose helper functions so prompt rendering can list selected-pack examples in scoped/workspace guidance while root shared guidance remains generic.

Inner Skill Phases

• $grill-me: no open decision remains. The requirements grill locked field shape, Effect-only seed scope, version source, and guidance placement.
• $parallel-research: intentionally skipped for subagents. Local readonly discovery was compact and tightly coupled across catalog, prompt helpers, tests, and docs; no disjoint research lane justified worker fan-out.
• $swarm-planner: one sequential chain because prompt guidance depends on catalog/schema helpers and Effect seed data.
• $tdd: every implementation task starts with a public behavior test before the production change.

Resolved Decision Ledger

Assumptions And Constraints

• The selected Effect examples have package manifests with Effect dependency declarations.
• packages/scaffold owns stable pack schema/type shape only; no prompt rendering moves there.
• apps/cli remains the owner of catalog data and prompt rendering behavior.
• Existing user work in docs/opensrc-knowledge-refactor-backlog.md is part of this delivery and must be preserved.
• No non-Effect curated examples are added.

Codebase Findings

• Pack catalog data lives in apps/cli/src/data/catalog/packs.ts.
• CLI content helpers live in apps/cli/src/content/packs.ts.
• Prompt rendering lives in apps/cli/src/content/prompts.ts and apps/cli/src/scaffold/output.ts.
• Prompt spec summaries already include opensrcReferences, currently empty for scoped prompts.
• Shared scaffold pack schema lives in packages/scaffold/src/index.ts.
• Tests already cover pack catalog helpers and seeded workspace prompt rendering in apps/cli/src/content/content.test.ts.
• Shared schema decoding tests live in packages/scaffold/src/index.test.ts.
• End-to-end scaffold behavior tests live in apps/cli/src/scaffold/run.test.ts.

External Research Used

Implementation must run opensrc path owner/repo for:

• AnswerOverflow/AnswerOverflow
• rhyssullivan/executor
• alchemy-run/alchemy-effect
• anomalyco/opencode
• pingdotgg/t3code

For each cloned path, read package manifests and record the Effect version from the repository dependency declaration before finalizing the catalog entry.

Dependency Graph

T1 -> T2 -> T3 -> T4 -> T5

Parallel Execution Waves

Implementation mode: parallel: false.

Reason: all tasks touch closely related TypeScript types, catalog helpers, prompt rendering, and tests. Worker handoff risk is higher than the expected gain.

Tasks

T1: Add Shared Pack Schema For Curated Examples

• depends_on: []
• location: packages/scaffold
• description: Extend the shared scaffold pack schema/type contract with curated example repository metadata using only repo, url, and packs, with each pack reference using only uid and version.
• validation: bun run --filter @punks/scaffold test
• status: Complete
• log: Added shared ScaffoldExampleRepository and pack-reference schema classes, then extended ScaffoldPackCatalogEntry with optional curated example metadata.
• files edited/created: packages/scaffold/src/index.ts, packages/scaffold/src/index.test.ts
• backlog_item_id: IP-158
• backlog_item_url: https://linear.app/devpunks/issue/IP-158/pack-catalog-carries-curated-example-repositories
• relation_mode: native
• assigned_skills: [quality-types, tdd, simplify]
• tdd_target: ScaffoldPackCatalogEntry decodes a pack with curated examples and rejects extra fields through the exact schema shape.
• review_mode: cli

T2: Seed Effect Pack Examples From Cloned Manifests

• depends_on: [T1]
• location: apps/cli/src/data/catalog/packs.ts, apps/cli/src/content/packs.ts
• description: Add curated example metadata to the Effect pack only, using versions read from cloned repository package manifests. Add content helpers for reading selected-pack examples from any baseline.
• validation: focused content tests for Effect seed repos, exact field shape, version presence, and helper output.
• status: Complete
• log: Used opensrc path owner/repo for all five Effect examples, read each cloned repository manifest/catalog, seeded the Effect pack, and added the exampleRepositoriesForPack helper.
• files edited/created: apps/cli/src/data/catalog/packs.ts, apps/cli/src/content/packs.ts, apps/cli/src/content/content.test.ts
• backlog_item_id: IP-161
• backlog_item_url: https://linear.app/devpunks/issue/IP-161/effect-pack-includes-curated-opensrc-example-repositories
• relation_mode: native
• assigned_skills: [quality-types, tdd, simplify]
• tdd_target: exampleRepositoriesForPack("effect") returns exactly the five curated repositories with manifest-derived versions.
• review_mode: cli

T3: Emit Selected-Pack Opensrc Example Guidance

• depends_on: [T2]
• location: apps/cli/src/content/prompts.ts, apps/cli/src/scaffold/output.ts, apps/cli/src/content/scaffold-copy.ts
• description: Render curated example repository guidance for scoped/workspace prompts whose selected packs include examples. Keep root guidance generic. Feed example repositories into prompt specs and handoff opensrc references without auto-selecting arbitrary repos.
• validation: focused prompt/content tests and scaffold run tests proving Effect workspaces list opensrc path owner/repo, explain the architecture-pattern purpose, and non-Effect scopes remain empty.
• status: Complete
• log: Added curated example guidance rendering for selected-pack workspace prompts, prompt specs, scaffold manifests, handoff references, and scaffold results. Root/shared guidance remains generic.
• files edited/created: apps/cli/src/content/prompts.ts, apps/cli/src/content/scaffold-copy.ts, apps/cli/src/scaffold/output.ts, apps/cli/src/scaffold/run.ts, apps/cli/src/core/models.ts, apps/cli/src/content/content.test.ts, apps/cli/src/scaffold/run.test.ts
• backlog_item_id: IP-159
• backlog_item_url: https://linear.app/devpunks/issue/IP-159/scoped-prompt-guidance-emits-selected-pack-opensrc-examples
• relation_mode: native
• assigned_skills: [quality-types, tdd, simplify]
• tdd_target: resolveSeededWorkspacePrompt and generated prompt specs include Effect curated example guidance only when the Effect pack applies.
• review_mode: cli

T4: Update Docs And Wiki For Implemented Contract

• depends_on: [T3]
• location: docs, apps/wiki
• description: Run $docs-ingest-phase for the implemented opensrc example repository contract. Update docs/readme/runbook surfaces, wiki source concepts, routed pages, metadata, and log entries so current behavior is accurate.
• validation: docs metadata checks, git diff --check, and any routed Fumadocs JSON validation needed for changed meta.json files.
• status: Complete
• log: Ran docs ingest for the implemented behavior: updated repo docs wording, source/routed wiki concepts, SPEC/implementation-note ingest frontmatter, and wiki log bookkeeping.
• files edited/created: docs/README.md, apps/wiki/content/docs/cli/concepts/opensrc-example-repository-context.md, apps/wiki/content/docs/cli/concepts/scaffold-pack.md, apps/wiki/content/docs/cli/opensrc-example-repository-context.mdx, apps/wiki/content/docs/cli/scaffold-pack.mdx, apps/wiki/specs/cli/IP-157-curated-opensrc-example-repositories/SPEC.md, apps/wiki/specs/cli/IP-157-curated-opensrc-example-repositories/IMPLEMENTATION-NOTES.md, apps/wiki/log.md
• backlog_item_id: IP-160
• backlog_item_url: https://linear.app/devpunks/issue/IP-160/documentation-captures-the-refined-opensrc-contract
• relation_mode: native
• assigned_skills: [docs-ingest-phase, simplify]
• tdd_target: Human docs distinguish package source context from curated examples and mark the concept as implemented only after code lands.
• review_mode: cli

T5: Review, Validate, Finalize, And Close Linear

• depends_on: [T4]
• location: apps/cli, packages/scaffold, docs, apps/wiki
• description: Run $review-phase, fix blocking findings, run full validation, update implementation notes/final checklist, then comment and close IP-158, IP-161, IP-159, IP-160, and IP-157 in Linear.
• validation: git diff --check, targeted tests, bun run test, manual acceptance audit against every Linear issue.
• status: Complete
• log: Ran local review, fixed one prompt-spec wording issue, resolved validation blockers, completed full validation, commented evidence on Linear, and moved IP-158/IP-161/IP-159/IP-160/IP-157 to Done.
• files edited/created: apps/cli/src/content/scaffold-copy.ts, packages/scaffold/src/index.test.ts, apps/cli/src/data/scripts/sync-subagents.mjs, .agents/scripts/sync-subagents.mjs, spec folder bookkeeping files
• backlog_item_id: IP-157
• backlog_item_url: https://linear.app/devpunks/issue/IP-157/curated-opensrc-example-repositories-for-framework-packs
• relation_mode: native
• assigned_skills: [review-phase, quality-types, tdd, simplify]
• tdd_target: Acceptance audit maps every child issue checkbox to changed files and passing validation.
• review_mode: cli

Testing Strategy

• Start with focused RED tests in packages/scaffold/src/index.test.ts and apps/cli/src/content/content.test.ts.
• Add scaffold output coverage where prompt spec summaries or generated prompt files must expose example repos.
• Run package-targeted tests after each green slice when possible.
• Finish with git diff --check and bun run test.

Risks And Mitigations

• Missing manifest version: stop and report the exact repository and missing manifest/dependency path.
• Over-modeling metadata: keep tests asserting no why, inspectFor, avoidUsingFor, or unknown-version fields.
• Prompt overreach: assert root guidance stays generic and non-Effect prompt specs have no curated example repo list.
• Shared package behavior creep: keep packages/scaffold to schemas/types only.

Validation Gates

1. Schema gate: shared pack schema decodes minimal curated example entries.
2. Catalog gate: Effect pack contains exactly the five seed repositories and manifest-derived versions.
3. Prompt gate: selected-pack scoped/workspace prompts emit explicit opensrc path owner/repo guidance.
4. Docs gate: docs/wiki reflect implemented behavior and no routed pages are orphaned.
5. Closeout gate: review, git diff --check, bun run test, and Linear closeout pass.

Unresolved Questions

None.