skilledagent 1.0.0

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

@@ -0,0 +1,91 @@
+---
+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/.agents/skills/setup-ts-deep-modules/SKILL.md

@@ -0,0 +1,102 @@
+---
+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/.agents/skills/setup-ts-deep-modules/dependency-cruiser.config.cjs

@@ -0,0 +1,95 @@
+// @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/.agents/skills/tdd/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: tdd
+description: Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.
+---
+
+# Test-Driven Development
+
+TDD is the red → green loop. This skill is the reference that makes that loop produce tests worth keeping: what a good test is, where tests go, the anti-patterns, and the rules of the loop. Every section applies on every cycle — consult them before and during the loop, not after.
+
+When exploring the codebase, read `CONTEXT.md` (if it exists) so test names and interface vocabulary match the project's domain language, and respect ADRs in the area you're touching.
+
+## What a good test is
+
+Tests verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't. A good test reads like a specification — "user can checkout with valid cart" tells you exactly what capability exists — and survives refactors because it doesn't care about internal structure.
+
+See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
+
+## Seams — where tests go
+
+A **seam** is the public boundary you test at: the interface where you observe behavior without reaching inside. Tests live at seams, never against internals.
+
+**Test only at pre-agreed seams.** Before writing any test, write down the seams under test and confirm them with the user. No test is written at an unconfirmed seam. You can't test everything — agreeing the seams up front is how testing effort lands on the critical paths and complex logic instead of every edge case.
+
+Ask: "What's the public interface, and which seams should we test?"
+
+## Anti-patterns
+
+- **Implementation-coupled** — mocks internal collaborators, tests private methods, or verifies through a side channel (querying the database instead of using the interface). The tell: the test breaks when you refactor but behavior hasn't changed.
+- **Tautological** — the assertion recomputes the expected value the way the code does (`expect(add(a, b)).toBe(a + b)`, a snapshot derived by hand the same way, a constant asserted equal to itself), so it passes by construction and can never disagree with the code. Expected values must come from an independent source of truth — a known-good literal, a worked example, the spec.
+- **Horizontal slicing** — writing all tests first, then all implementation. Bulk tests verify _imagined_ behavior: you test the _shape_ of things rather than user-facing behavior, the tests go insensitive to real changes, and you commit to test structure before understanding the implementation. Work in **vertical slices** instead — one test → one implementation → repeat, each test a **tracer bullet** that responds to what the last cycle taught you.
+
+## Rules of the loop
+
+- **Red before green.** Write the failing test first, then only enough code to pass it. Don't anticipate future tests or add speculative features.
+- **One slice at a time.** One seam, one test, one minimal implementation per cycle.
+- **Refactoring is not part of the loop.** It belongs to the review stage (see the `code-review` skill), not the red → green implementation cycle.

package/.agents/skills/tdd/mocking.md

@@ -0,0 +1,59 @@
+# When to Mock
+
+Mock at **system boundaries** only:
+
+- External APIs (payment, email, etc.)
+- Databases (sometimes - prefer test DB)
+- Time/randomness
+- File system (sometimes)
+
+Don't mock:
+
+- Your own classes/modules
+- Internal collaborators
+- Anything you control
+
+## Designing for Mockability
+
+At system boundaries, design interfaces that are easy to mock:
+
+**1. Use dependency injection**
+
+Pass external dependencies in rather than creating them internally:
+
+```typescript
+// Easy to mock
+function processPayment(order, paymentClient) {
+  return paymentClient.charge(order.total);
+}
+
+// Hard to mock
+function processPayment(order) {
+  const client = new StripeClient(process.env.STRIPE_KEY);
+  return client.charge(order.total);
+}
+```
+
+**2. Prefer SDK-style interfaces over generic fetchers**
+
+Create specific functions for each external operation instead of one generic function with conditional logic:
+
+```typescript
+// GOOD: Each function is independently mockable
+const api = {
+  getUser: (id) => fetch(`/users/${id}`),
+  getOrders: (userId) => fetch(`/users/${userId}/orders`),
+  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
+};
+
+// BAD: Mocking requires conditional logic inside the mock
+const api = {
+  fetch: (endpoint, options) => fetch(endpoint, options),
+};
+```
+
+The SDK approach means:
+- Each mock returns one specific shape
+- No conditional logic in test setup
+- Easier to see which endpoints a test exercises
+- Type safety per endpoint

package/.agents/skills/tdd/tests.md

@@ -0,0 +1,77 @@
+# Good and Bad Tests
+
+## Good Tests
+
+**Integration-style**: Test through real interfaces, not mocks of internal parts.
+
+```typescript
+// GOOD: Tests observable behavior
+test("user can checkout with valid cart", async () => {
+  const cart = createCart();
+  cart.add(product);
+  const result = await checkout(cart, paymentMethod);
+  expect(result.status).toBe("confirmed");
+});
+```
+
+Characteristics:
+
+- Tests behavior users/callers care about
+- Uses public API only
+- Survives internal refactors
+- Describes WHAT, not HOW
+- One logical assertion per test
+
+## Bad Tests
+
+**Implementation-detail tests**: Coupled to internal structure.
+
+```typescript
+// BAD: Tests implementation details
+test("checkout calls paymentService.process", async () => {
+  const mockPayment = jest.mock(paymentService);
+  await checkout(cart, payment);
+  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
+});
+```
+
+Red flags:
+
+- Mocking internal collaborators
+- Testing private methods
+- Asserting on call counts/order
+- Test breaks when refactoring without behavior change
+- Test name describes HOW not WHAT
+- Verifying through external means instead of interface
+
+```typescript
+// BAD: Bypasses interface to verify
+test("createUser saves to database", async () => {
+  await createUser({ name: "Alice" });
+  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
+  expect(row).toBeDefined();
+});
+
+// GOOD: Verifies through interface
+test("createUser makes user retrievable", async () => {
+  const user = await createUser({ name: "Alice" });
+  const retrieved = await getUser(user.id);
+  expect(retrieved.name).toBe("Alice");
+});
+```
+
+**Tautological tests**: Expected value restates the implementation, so the test passes by construction.
+
+```typescript
+// BAD: Expected value is recomputed the way the code computes it
+test("calculateTotal sums line items", () => {
+  const items = [{ price: 10 }, { price: 5 }];
+  const expected = items.reduce((sum, i) => sum + i.price, 0);
+  expect(calculateTotal(items)).toBe(expected);
+});
+
+// GOOD: Expected value is an independent, known literal
+test("calculateTotal sums line items", () => {
+  expect(calculateTotal([{ price: 10 }, { price: 5 }])).toBe(15);
+});
+```

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

@@ -0,0 +1,35 @@
+# 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/.agents/skills/teach/LEARNING-RECORD-FORMAT.md

@@ -0,0 +1,46 @@
+# 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/.agents/skills/teach/MISSION-FORMAT.md

@@ -0,0 +1,31 @@
+# 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/.agents/skills/teach/RESOURCES-FORMAT.md

@@ -0,0 +1,32 @@
+# 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.