create-yss-spec 3.0.1 → 3.1.0

package/template/.agents/skills/scaffold-exercises/SKILL.md

@@ -1,106 +0,0 @@
----
-name: scaffold-exercises
-description: Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. Use when user wants to scaffold exercises, create exercise stubs, or set up a new course section.
----
-
-# Scaffold Exercises
-
-Create exercise directory structures that pass `pnpm ai-hero-cli internal lint`, then commit with `git commit`.
-
-## Directory naming
-
-- **Sections**: `XX-section-name/` inside `exercises/` (e.g., `01-retrieval-skill-building`)
-- **Exercises**: `XX.YY-exercise-name/` inside a section (e.g., `01.03-retrieval-with-bm25`)
-- Section number = `XX`, exercise number = `XX.YY`
-- Names are dash-case (lowercase, hyphens)
-
-## Exercise variants
-
-Each exercise needs at least one of these subfolders:
-
-- `problem/` - student workspace with TODOs
-- `solution/` - reference implementation
-- `explainer/` - conceptual material, no TODOs
-
-When stubbing, default to `explainer/` unless the plan specifies otherwise.
-
-## Required files
-
-Each subfolder (`problem/`, `solution/`, `explainer/`) needs a `readme.md` that:
-
-- Is **not empty** (must have real content, even a single title line works)
-- Has no broken links
-
-When stubbing, create a minimal readme with a title and a description:
-
-```md
-# Exercise Title
-
-Description here
-```
-
-If the subfolder has code, it also needs a `main.ts` (>1 line). But for stubs, a readme-only exercise is fine.
-
-## Workflow
-
-1. **Parse the plan** - extract section names, exercise names, and variant types
-2. **Create directories** - `mkdir -p` for each path
-3. **Create stub readmes** - one `readme.md` per variant folder with a title
-4. **Run lint** - `pnpm ai-hero-cli internal lint` to validate
-5. **Fix any errors** - iterate until lint passes
-
-## Lint rules summary
-
-The linter (`pnpm ai-hero-cli internal lint`) checks:
-
-- Each exercise has subfolders (`problem/`, `solution/`, `explainer/`)
-- At least one of `problem/`, `explainer/`, or `explainer.1/` exists
-- `readme.md` exists and is non-empty in the primary subfolder
-- No `.gitkeep` files
-- No `speaker-notes.md` files
-- No broken links in readmes
-- No `pnpm run exercise` commands in readmes
-- `main.ts` required per subfolder unless it's readme-only
-
-## Moving/renaming exercises
-
-When renumbering or moving exercises:
-
-1. Use `git mv` (not `mv`) to rename directories - preserves git history
-2. Update the numeric prefix to maintain order
-3. Re-run lint after moves
-
-Example:
-
-```bash
-git mv exercises/01-retrieval/01.03-embeddings exercises/01-retrieval/01.04-embeddings
-```
-
-## Example: stubbing from a plan
-
-Given a plan like:
-
-```
-Section 05: Memory Skill Building
-- 05.01 Introduction to Memory
-- 05.02 Short-term Memory (explainer + problem + solution)
-- 05.03 Long-term Memory
-```
-
-Create:
-
-```bash
-mkdir -p exercises/05-memory-skill-building/05.01-introduction-to-memory/explainer
-mkdir -p exercises/05-memory-skill-building/05.02-short-term-memory/{explainer,problem,solution}
-mkdir -p exercises/05-memory-skill-building/05.03-long-term-memory/explainer
-```
-
-Then create readme stubs:
-
-```
-exercises/05-memory-skill-building/05.01-introduction-to-memory/explainer/readme.md -> "# Introduction to Memory"
-exercises/05-memory-skill-building/05.02-short-term-memory/explainer/readme.md -> "# Short-term Memory"
-exercises/05-memory-skill-building/05.02-short-term-memory/problem/readme.md -> "# Short-term Memory"
-exercises/05-memory-skill-building/05.02-short-term-memory/solution/readme.md -> "# Short-term Memory"
-exercises/05-memory-skill-building/05.03-long-term-memory/explainer/readme.md -> "# Long-term Memory"
-```

package/template/.agents/skills/scaffold-exercises/agents/openai.yaml

@@ -1,3 +0,0 @@
-interface:
-  display_name: "Scaffold Exercises"
-  short_description: "Scaffold lint-ready course exercises"

package/template/.agents/skills/setup-pre-commit/SKILL.md

@@ -1,91 +0,0 @@
----
-name: setup-pre-commit
-description: Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing.
----
-
-# Setup Pre-Commit Hooks
-
-## What This Sets Up
-
-- **Husky** pre-commit hook
-- **lint-staged** running Prettier on all staged files
-- **Prettier** config (if missing)
-- **typecheck** and **test** scripts in the pre-commit hook
-
-## Steps
-
-### 1. Detect package manager
-
-Check for `package-lock.json` (npm), `pnpm-lock.yaml` (pnpm), `yarn.lock` (yarn), `bun.lockb` (bun). Use whichever is present. Default to npm if unclear.
-
-### 2. Install dependencies
-
-Install as devDependencies:
-
-```
-husky lint-staged prettier
-```
-
-### 3. Initialize Husky
-
-```bash
-npx husky init
-```
-
-This creates `.husky/` dir and adds `prepare: "husky"` to package.json.
-
-### 4. Create `.husky/pre-commit`
-
-Write this file (no shebang needed for Husky v9+):
-
-```
-npx lint-staged
-npm run typecheck
-npm run test
-```
-
-**Adapt**: Replace `npm` with detected package manager. If repo has no `typecheck` or `test` script in package.json, omit those lines and tell the user.
-
-### 5. Create `.lintstagedrc`
-
-```json
-{
-  "*": "prettier --ignore-unknown --write"
-}
-```
-
-### 6. Create `.prettierrc` (if missing)
-
-Only create if no Prettier config exists. Use these defaults:
-
-```json
-{
-  "useTabs": false,
-  "tabWidth": 2,
-  "printWidth": 80,
-  "singleQuote": false,
-  "trailingComma": "es5",
-  "semi": true,
-  "arrowParens": "always"
-}
-```
-
-### 7. Verify
-
-- [ ] `.husky/pre-commit` exists and is executable
-- [ ] `.lintstagedrc` exists
-- [ ] `prepare` script in package.json is `"husky"`
-- [ ] `prettier` config exists
-- [ ] Run `npx lint-staged` to verify it works
-
-### 8. Commit
-
-Stage all changed/created files and commit with message: `Add pre-commit hooks (husky + lint-staged + prettier)`
-
-This will run through the new pre-commit hooks — a good smoke test that everything works.
-
-## Notes
-
-- Husky v9+ doesn't need shebangs in hook files
-- `prettier --ignore-unknown` skips files Prettier can't parse (images, etc.)
-- The pre-commit runs lint-staged first (fast, staged-only), then full typecheck and tests

package/template/.agents/skills/setup-pre-commit/agents/openai.yaml

@@ -1,3 +0,0 @@
-interface:
-  display_name: "Setup Pre-Commit"
-  short_description: "Add pre-commit quality checks"

package/template/.agents/skills/setup-ts-deep-modules/SKILL.md

@@ -1,102 +0,0 @@
----
-name: setup-ts-deep-modules
-description: Wire dependency-cruiser into a TypeScript repo so each package is a deep module — implementation hidden in subfolders, reachable only through its entry-point files. User-invoked.
-disable-model-invocation: true
----
-
-# Setup TS Deep Modules
-
-Make every package in this repo a **deep module**: a lot of behaviour behind a small interface. A package's public surface is its **entry points** — the files at the package root — and everything in its subfolders is hidden. This skill installs [dependency-cruiser](https://github.com/sverweij/dependency-cruiser) and the rules that make the entry points the only way in, then proves the rules bite.
-
-For the vocabulary (deep module, interface, seam, depth), run the `/codebase-design` skill — use its language throughout.
-
-## The shape this enforces
-
-```
-src/packages/
-  <name>/
-    index.ts        ← an entry point (public). Import this from outside.
-    client.ts       ← another entry point. Packages may expose SEVERAL.
-    lib/            ← implementation: hidden from outside, free to import each other.
-    tests/          ← co-located tests + fixtures (a subfolder, so private).
-```
-
-The public surface is the package's **root files** — not one designated `index.ts`. By convention implementation lives in `lib/` and tests in `tests/`, giving every package the same two-folder shape. The rule itself is general, though: *anything* in *any* subfolder is private, so you never extend the config to add a folder.
-
-Four rules, all `error`:
-
-1. **Entry-point boundary** — code outside a package (app code or another package) may import only that package's entry points (its root files), never anything in its subfolders.
-2. **Intra-package freedom** — a package's own files import each other freely.
-3. **Tests through the entry points** — files under `<pkg>/tests/` may import any package's entry points and their own `tests/` fixtures, but never any package's subfolder internals (not even their own). Integration tests across packages are fine; deep imports are not.
-4. **No cycles** — no dependency cycles.
-
-**Entry points, not a barrel.** Because the public surface is *every* root file, a package can expose several small entry points (`index.ts`, `client.ts`, `server.ts`) instead of funnelling everything through one giant `index.ts`. Barrel files that re-export a whole subtree are discouraged — keep entry points small and hide implementation in subfolders.
-
-Layering (which packages may depend on which) is a *different* concern and is left as a commented stub in the config for this repo to fill in.
-
-## Steps
-
-### 1. Detect the environment
-
-- **Package manager** — `pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `bun.lockb` → bun, else npm. Use it for every command below (`pnpm`/`yarn`/`npm run`/`bunx`).
-- **Packages root** — if `src/` exists use `src/packages`, else `packages`. Confirm the choice with the user if the repo already has a different obvious convention.
-- **Existing config** — check for a `.dependency-cruiser.*` file. If one exists, do **not** overwrite it: merge the four rules and the options in, and tell the user what you added.
-
-**Done when:** package manager, packages root, and existing-config status are all known.
-
-### 2. Install dependency-cruiser
-
-Install `dependency-cruiser` as a devDependency with the detected package manager.
-
-**Done when:** `dependency-cruiser` is in `devDependencies`.
-
-### 3. Write the config
-
-Copy [`dependency-cruiser.config.cjs`](./dependency-cruiser.config.cjs) to the repo root as `.dependency-cruiser.cjs`. Set `PACKAGES_ROOT` to the root detected in step 1. The rules are path-depth based and extension-agnostic, so nothing else needs adapting.
-
-**Done when:** `.dependency-cruiser.cjs` exists with the correct `PACKAGES_ROOT`, and the four forbidden rules are present.
-
-### 4. Wire it into the checks
-
-- Add a `lint:boundaries` script: `depcruise <packages-root>` (or `depcruise src`).
-- Fold it into the repo's umbrella check command — the one that already runs typecheck (e.g. a `check` / `ci` / `validate` script). Do **not** touch `tsconfig` or add path aliases.
-- If there is no umbrella script, add `lint:boundaries` and tell the user to include it in CI.
-
-**Done when:** `lint:boundaries` exists and runs as part of the same command as typecheck.
-
-### 5. Scaffold the example package
-
-Create a committed `<packages-root>/example/` as a copy-me template:
-
-- `index.ts` — an entry point. Export one function that delegates to an internal file (so the package is visibly *deep*, not a pass-through).
-- `lib/impl.ts` — an internal file in a **subfolder**, imported by `index.ts`, not reachable from outside.
-- `tests/example.test.ts` — imports **only** `../index` (an entry point), and asserts against the public function.
-
-Tell the user this is a starter template to copy or delete.
-
-**Done when:** the example package exists, exposes its behaviour through a root entry point, and hides `impl` in a subfolder.
-
-### 6. Prove the rules bite
-
-This is the completion criterion for the whole skill — a config that doesn't fail on a violation is worthless.
-
-1. Run `lint:boundaries`. It must **pass** on the clean example.
-2. Temporarily add a deep import to `tests/example.test.ts` (e.g. `import { thing } from "../lib/impl"`). Run `lint:boundaries` again — it must **fail** with `tests-through-entrypoints`.
-3. Revert the deep import. Run once more — it must **pass**.
-
-**Done when:** you have observed a pass, then a fail on the deep import, then a pass again. If step 2 does not fail, the rules are not wired correctly — fix before finishing.
-
-### 7. Document the convention
-
-Write a `README.md` **in the packages folder** (`<packages-root>/README.md`) — next to the packages it governs — covering: the `src/packages/<name>/` layout (entry points at the root, `lib/` for implementation, `tests/` for tests), "import only through a package's entry points (its root files)", and how to run `lint:boundaries`. **Discourage barrel files** explicitly — expose several small entry points instead of re-exporting a whole subtree through one index. Keep it to the copy-me snippet plus the four rules in one paragraph each.
-
-Then add a **context pointer** to it from the repo's agent-instructions file — `CLAUDE.md` if present, else `AGENTS.md` (create `AGENTS.md` if neither exists). One line is enough, e.g. `Packages are deep modules — see [src/packages/README.md](./src/packages/README.md) before adding or importing one.` This is what makes an agent discover the boundary rule instead of tripping over it.
-
-**Done when:** `<packages-root>/README.md` exists and discourages barrels, and the repo's `CLAUDE.md`/`AGENTS.md` links to it.
-
-## Notes
-
-- The config's `$1` back-references (dependency-cruiser's group matching) are what let a package reach its own internals while outsiders can't — don't flatten them into separate per-package rules.
-- Public vs private is decided by **depth**: a package's root files are entry points; anything in a subfolder is private. The conventional subfolders are `lib/` (implementation) and `tests/`, but the rule doesn't hardcode them — any subfolder is private, so a new folder never needs a config change. Adding an entry point is just adding a root file — no barrel.
-- Packages are **flat**: one tier of immediate children under the root. A package's internals may nest as deep as you like; a package may not contain another package.
-- Use `.cjs` (not `.js`) so the config's `module.exports` works even in `"type": "module"` repos.

package/template/.agents/skills/setup-ts-deep-modules/agents/openai.yaml

@@ -1,5 +0,0 @@
-interface:
-  display_name: "Setup TS Deep Modules"
-  short_description: "Enforce deep TypeScript modules"
-policy:
-  allow_implicit_invocation: false

package/template/.agents/skills/setup-ts-deep-modules/dependency-cruiser.config.cjs

@@ -1,95 +0,0 @@
-// @ts-check
-// Deep-module enforcement for dependency-cruiser.
-//
-// Each package under the packages root is a DEEP MODULE: a lot of behaviour
-// behind a small interface. A package's PUBLIC SURFACE is its ENTRY POINTS —
-// the files at the package root. Implementation lives in SUBFOLDERS and is
-// private — by convention `lib/` for implementation and `tests/` for tests,
-// though any subfolder is private. A package may expose several small entry
-// points (index.ts, client.ts, server.ts, …) — prefer that over one giant
-// barrel index.
-//
-// The only thing you should ever need to edit here is PACKAGES_ROOT.
-
-/** Where packages live. One immediate child dir per package (flat, no nesting). */
-const PACKAGES_ROOT = "src/packages";
-
-// --- derived patterns (no need to edit) -------------------------------------
-const R = PACKAGES_ROOT;
-/**
- * A package's private internals: anything nested inside a package subfolder.
- * The package's root files are its entry points and are NOT matched here —
- * they stay importable from outside.
- */
-const PACKAGE_INTERNALS = `^${R}/[^/]+/[^/]+/`;
-
-/** @type {import('dependency-cruiser').IConfiguration} */
-module.exports = {
-  forbidden: [
-    {
-      name: "entrypoint-boundary-from-app",
-      comment:
-        "App/root code may import a package's entry points (its root files), but nothing inside its subfolders.",
-      severity: "error",
-      from: { pathNot: `^${R}/` }, // importer is NOT inside any package
-      to: { path: PACKAGE_INTERNALS },
-    },
-    {
-      name: "entrypoint-boundary-across-packages",
-      comment:
-        "A package's own files import each other freely, but may reach OTHER packages only through their entry points — never their internals.",
-      severity: "error",
-      // importer is inside a package ($1), but is not a test file
-      from: { path: `^${R}/([^/]+)/`, pathNot: `^${R}/[^/]+/tests/` },
-      to: {
-        path: PACKAGE_INTERNALS,
-        pathNot: `^${R}/$1/`, // same package → intra-package freedom
-      },
-    },
-    {
-      name: "tests-through-entrypoints",
-      comment:
-        "A package's tests exercise it through its entry points like everyone else: they may import any package's entry points and their own tests/ fixtures, but never any package's internals — not even their own.",
-      severity: "error",
-      from: { path: `^${R}/([^/]+)/tests/` }, // a test file, in package $1
-      to: {
-        path: PACKAGE_INTERNALS,
-        pathNot: `^${R}/$1/tests/`, // own tests/ fixtures → allowed
-      },
-    },
-    {
-      name: "tests-folder-is-private",
-      comment:
-        "A package's tests/ folder is reachable only from tests — nothing else may import fixtures.",
-      severity: "error",
-      from: { pathNot: `^${R}/[^/]+/tests/` }, // importer is not itself a test
-      to: { path: `^${R}/[^/]+/tests/` },
-    },
-    {
-      name: "no-circular",
-      comment: "No dependency cycles. Scope to `^${R}/` if you want to allow cycles outside packages.",
-      severity: "error",
-      from: {},
-      to: { circular: true },
-    },
-
-    // --- Layering (optional, off by default) ----------------------------------
-    // Interface-hiding controls HOW you import (through the entry points).
-    // Layering controls WHICH packages may depend on which. Add your own rules
-    // here, e.g.:
-    //
-    // {
-    //   name: "ui-may-not-depend-on-billing",
-    //   severity: "error",
-    //   from: { path: `^${R}/ui/` },
-    //   to:   { path: `^${R}/billing/` },
-    // },
-  ],
-  options: {
-    doNotFollow: { path: "node_modules" },
-    tsConfig: { fileName: "tsconfig.json" },
-    enhancedResolveOptions: {
-      extensions: [".ts", ".tsx", ".js", ".jsx", ".json"],
-    },
-  },
-};

package/template/.agents/skills/teach/GLOSSARY-FORMAT.md

@@ -1,35 +0,0 @@
-# GLOSSARY.md Format
-
-`GLOSSARY.md` is the canonical language for this teaching workspace. All explainers, exercises, and learning records should adhere to its terminology. Building it is itself part of learning: compressing a concept into a tight definition is evidence the user understands it.
-
-## Structure
-
-```md
-# {Topic} Glossary
-
-{One or two sentence description of the topic this glossary covers.}
-
-## Terms
-
-**Hypertrophy**:
-Muscle growth driven by mechanical tension and metabolic stress over repeated training sessions.
-_Avoid_: Bulking, getting big
-
-**Progressive overload**:
-Systematically increasing the demand on a muscle over time — via load, volume, or intensity.
-_Avoid_: Pushing harder, levelling up
-
-**RPE (Rate of Perceived Exertion)**:
-A 1–10 self-rating of how hard a set felt, where 10 is failure and 8 means two reps left in the tank.
-_Avoid_: Effort score, intensity rating
-```
-
-## Rules
-
-- **Add a term only when the user understands it.** The glossary is a record of compressed knowledge, not a dictionary the user reads to learn. If the user has just been introduced to a concept, wait until they can use it correctly before promoting it here.
-- **Be opinionated.** When several words exist for the same concept, pick the best one and list the rest as aliases to avoid. This is how language compresses.
-- **Keep definitions tight.** One or two sentences. Define what the term IS, not what it does or how to do it.
-- **Use the glossary's own terms inside definitions.** Once a term is in the glossary, prefer it everywhere — including inside other definitions. This is what makes complex terms easier to grasp later.
-- **Group under subheadings** when natural clusters emerge (e.g. `## Anatomy`, `## Programming`). A flat list is fine when terms cohere.
-- **Flag ambiguities explicitly.** If a term is used loosely in the wider field, note the resolution: "In this workspace, 'set' always means a working set — warm-ups are tracked separately."
-- **Revise as understanding deepens.** A definition the user wrote in week one may be wrong by week six. Update in place; do not leave stale entries.

package/template/.agents/skills/teach/LEARNING-RECORD-FORMAT.md

@@ -1,46 +0,0 @@
-# Learning Record Format
-
-Learning records live in `./learning-records/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc. Create the directory lazily — only when the first record is written.
-
-They are the teaching equivalent of ADRs: they capture non-obvious lessons, key insights, and stated prior knowledge that will steer future sessions. They are used to calculate the zone of proximal development.
-
-## Template
-
-```md
-# {Short title of what was learned or established}
-
-{1-3 sentences: what was learned (or what prior knowledge was established), and why it matters for future sessions.}
-```
-
-That is the whole format. A learning record can be a single paragraph. The value is recording _that_ this is now known and _why_ it changes what to teach next — not in filling out sections.
-
-## Optional sections
-
-Only include these when they add genuine value. Most records won't need them.
-
-- **Status** frontmatter (`active | superseded by LR-NNNN`) — useful when an earlier understanding turns out to be wrong and is replaced.
-- **Evidence** — how the user demonstrated the understanding (a question answered, an exercise completed, prior experience cited). Useful when the claim might be revisited.
-- **Implications** — what this unlocks or rules out for future sessions. Worth recording when non-obvious.
-
-## Numbering
-
-Scan `./learning-records/` for the highest existing number and increment by one.
-
-## When to write a learning record
-
-Write one when any of these is true:
-
-1. **The user demonstrated genuine understanding of something non-trivial** — not just exposure, but evidence they can use the concept correctly. This sets a new floor for what to teach next.
-2. **The user disclosed prior knowledge** — "I already know X." Record it so future sessions don't re-teach it. Also record the _depth_ claimed.
-3. **A misconception was corrected** — the user previously believed something wrong and now sees why. These are high-value: they predict future stumbling blocks for related topics.
-4. **The mission shifted in response to learning** — the user discovered they cared about something different than they thought. Cross-link to [[MISSION.md]] and update it.
-
-### What does _not_ qualify
-
-- Material that was merely covered. Coverage is not learning. Wait for evidence.
-- Anything already captured tersely in [[GLOSSARY.md]] as a term definition. Don't duplicate.
-- Session-by-session activity logs. Learning records are not a journal — they are decision-grade insights.
-
-## Supersession
-
-When a later record contradicts an earlier one (the user's understanding deepened or corrected), mark the old record `Status: superseded by LR-NNNN` rather than deleting it. The history of how understanding evolved is itself useful signal.

package/template/.agents/skills/teach/MISSION-FORMAT.md

@@ -1,31 +0,0 @@
-# MISSION.md Format
-
-`MISSION.md` lives at the workspace root. It captures the _reason_ the user is learning this topic. Every teaching decision — what to teach next, which resources to surface, which exercises to design — should trace back to this document.
-
-## Template
-
-```md
-# Mission: {Topic}
-
-## Why
-{1-3 sentences. The concrete real-world goal the user is chasing. What changes in their life or work when they have this skill? Avoid abstract framings like "to understand X" — push for the underlying outcome.}
-
-## Success looks like
-- {A specific, observable thing the user will be able to do}
-- {Another specific thing}
-- {…}
-
-## Constraints
-- {Time, budget, prior commitments, learning preferences, anything that bounds the approach}
-
-## Out of scope
-- {Adjacent topics the user explicitly does not want to chase right now — protects the zone of proximal development}
-```
-
-## Rules
-
-- **One mission per workspace.** If the user wants to learn two unrelated things, that is two workspaces.
-- **Concrete over abstract.** "Run a half marathon by October" beats "get fitter." "Ship a Rust CLI to my team" beats "learn Rust."
-- **Push back on vagueness.** If the user cannot articulate why, interview them before writing anything. A bad mission is worse than no mission.
-- **Revise when reality shifts.** Missions change. When the user's goal moves, update this file — don't leave a stale mission steering future sessions.
-- **Keep it short.** If `MISSION.md` runs past a screen, it has stopped being a compass and started being a plan.

package/template/.agents/skills/teach/RESOURCES-FORMAT.md

@@ -1,32 +0,0 @@
-# RESOURCES.md Format
-
-`RESOURCES.md` is the curated set of trusted sources for this topic. Knowledge for explainers should be drawn from here, not from parametric guesses. Wisdom comes from the communities listed here.
-
-## Structure
-
-```md
-# {Topic} Resources
-
-## Knowledge
-
-- [Book: _The Science and Practice of Strength Training_ — Zatsiorsky & Kraemer](https://example.com)
-  Foundational text on programming and adaptation. Use for: anything to do with periodisation, recovery, intensity zones.
-- [Article: "How Much Should I Train?" — Greg Nuckols (Stronger By Science)](https://example.com)
-  Evidence-based review of volume landmarks. Use for: weekly set targets per muscle group.
-
-## Wisdom (Communities)
-
-- [r/weightroom](https://reddit.com/r/weightroom)
-  High-signal subreddit, moderated against bro-science. Use for: programme critique, plateau troubleshooting.
-- Local: Tuesday strength class at {gym name}
-  Use for: real-time coaching feedback on lifts.
-```
-
-## Rules
-
-- **High-trust only.** Prefer primary sources, recognised experts, peer-reviewed work, and communities with strong moderation. If a resource is marketing dressed as education, leave it out.
-- **Annotate every entry.** A bare link is useless in three months. Add one line: what it covers and when to reach for it.
-- **Group by Knowledge / Wisdom.** Mirrors the philosophy in [SKILL.md](./SKILL.md). It is fine for a resource to appear in only one group.
-- **Surface gaps explicitly.** If no good resource exists for an area the mission needs, write a `## Gaps` section listing what is missing. This drives future search.
-- **Prune ruthlessly.** A resource that turned out to be wrong, shallow, or off-mission should be removed, not buried. Better five sharp sources than thirty mediocre ones.
-- **Record community preferences.** If the user has opted out of joining communities, note it here so future sessions don't keep proposing them.