opencode-skills-collection 3.1.0 → 3.1.1

package/bundled-skills/survey-generator/style_spec.json

@@ -0,0 +1,85 @@
+{
+  "reference_paper": "Gao et al. 2023, Retrieval-Augmented Generation for Large Language Models: A Survey (arXiv:2312.10997)",
+  "why_reference": "Clean academic layout, memorable taxonomy tree, paradigm comparison figure, structured progression from foundations to methods to evaluation. Good anchor for an agent harness survey.",
+  "layout": {
+    "format": "single self-contained HTML file, academic two-column inspired but responsive on modern browsers",
+    "page_width": "max-width 1100px, centered",
+    "columns": "two-column body text on viewport >= 900px, single column on mobile",
+    "margins": "generous, academic paper feel",
+    "background": "warm off-white (#fbfaf6 or similar)",
+    "body_text_color": "near-black (#1a1a1a)"
+  },
+  "typography": {
+    "body_font": "Georgia, 'Times New Roman', serif",
+    "heading_font": "Georgia, serif with slightly heavier weight",
+    "monospace": "SFMono-Regular, Menlo, Consolas, monospace",
+    "body_size": "15px or 16px, line-height 1.55",
+    "section_numbering": "numbered sections and subsections like 1, 1.1, 2, 2.1",
+    "title_size": "large, centered on title block",
+    "author_and_affiliation": "centered under title, smaller italic"
+  },
+  "structural_elements": {
+    "title_block": "Paper title, author placeholder, affiliation placeholder (Anonymous / DAIR Research Notes), date",
+    "abstract": "Italicized paragraph labeled 'Abstract', single column, set off with a subtle border or spacing",
+    "keywords": "line of 4 to 6 keywords below the abstract",
+    "section_headings": "bold, numbered, flush left",
+    "subsection_headings": "bold italic, numbered",
+    "paragraphs": "justified text, indented first line optional",
+    "inline_citations": "parenthetical like (Yao et al., 2022) matching bibliography keys",
+    "references_section": "numbered list, hanging indent, final section"
+  },
+  "required_figures": [
+    {
+      "id": "Figure 1",
+      "caption": "Taxonomy of the surveyed field. Derive node labels from research_bundle.taxonomy.",
+      "description": "Horizontal taxonomy tree rendered as inline SVG. Three vertical columns: root on the left, branches in the middle, leaves on the right. The viewport MUST be tall enough to stack every leaf without overlap: compute viewport_height as sum_over_branches(max(1, children_count) * 28) + 40 and set it explicitly, and set viewport_width to 820. Use preserveAspectRatio default.\n\nROOT NODE: one rounded rect at x=20, y=(viewport_height/2 - 18), width=200, height=36, rx=6, fill #8a2a2b. Text: bold Georgia 14px, fill #fbfaf6, text-anchor middle, x=120, y=(root_y + 23). The width of 200 guarantees 'Agentic Engineering' and similar labels fit; do not shrink below 200 even if the label is short.\n\nBRANCH COLUMN: one rounded rect per entry in research_bundle.taxonomy.branches, all at x=260, width=200, height=32, rx=4, fill #f0efe9, stroke #1a1a1a at 1.2. The vertical position of branch i must be the vertical center of its own leaf block (see below), minus 16. Label: Georgia 12px, text-anchor middle, x=360, y=(branch_y + 20).\n\nLEAF COLUMN: every leaf rect has x=500, width=300, height=22, rx=3, fill #fbfaf6, stroke #c0bdb0 at 0.8. The vertical pitch between consecutive leaves is EXACTLY 28 (rect height 22 plus 6px gap). The leaf block for branch i starts at cumulative_y, which is 20 for branch 0 and cumulative_y_of_previous_branch + 28 * children_count_of_previous_branch for branch i > 0. Within a branch's leaf block, leaf j is at y = branch_block_start_y + 28 * j. Leaf label: Georgia 10px, text-anchor middle, x=650, y=(leaf_y + 15). A leaf rect MUST never visually overlap another leaf rect, and leaf text MUST never cross a rect boundary.\n\nCONNECTORS: from the right edge of the root (x=220, y=root_y+18) to the left edge of each branch (x=260, y=branch_y+16), draw one smooth cubic bezier per branch. From the right edge of each branch (x=460, y=branch_y+16) to the left edge of each of its leaves (x=500, y=leaf_y+11), draw one short horizontal line per leaf.\n\nHARD INVARIANTS (check before emitting): no two rects in the same column have overlapping y ranges; every label stays inside its rect; viewport height equals sum_over_branches(children_count) * 28 + 40 (with a minimum of 360); bezier connectors use C commands, not L commands.",
+      "element_budget": "roughly 60 to 80 SVG elements"
+    },
+    {
+      "id": "Figure 2",
+      "caption": "Three paradigms of the surveyed field. Derive panels from research_bundle.paradigms.",
+      "description": "Three side-by-side panels as inline SVG, viewport exactly 780 wide by 280 tall. Each panel corresponds to an entry in research_bundle.paradigms (exactly three paradigms). CRITICAL LAYOUT CONTRACT: the three panel background rectangles are fixed at x=10 width=240, x=270 width=240, and x=530 width=240, all with y=10 height=260, rx=6, fill #faf9f4, stroke #d6d3c4. Every node and connector that belongs to paradigm index i MUST be rendered inside the interior of panel i. The interior x ranges are: panel 1 x in [30, 230], panel 2 x in [290, 490], panel 3 x in [550, 750]. The interior y range for nodes is [55, 250] in every panel (title sits at y=32). REQUIRED IMPLEMENTATION: wrap each panel's nodes and connectors in a single <g transform='translate(OFFSET,0)'> group where OFFSET is 10 for panel 1, 270 for panel 2, and 530 for panel 3 (these offsets match the panel background x positions, so panel-local x=120 maps to each panel's horizontal center). Use panel-local x coordinates in the range [10, 230] inside every group, and arrange the visible content so that its collective horizontal center sits on panel-local x=120. Concretely: if the content has a single row of nodes, center the row on panel-local x=120; if the content has multiple rows stacked vertically (for example, a parent node above a row of children), center each row independently on panel-local x=120 so parents and children share a vertical axis through x=120. Do NOT reuse the same absolute x coordinates for all three paradigms. Panel titles sit at y=32, bold Georgia 13px, text-anchor middle, x at the panel's horizontal center (130, 390, 650). Define a single <marker id='arrow'> with a small filled triangle and reuse it via marker-end on directional connectors. Render paradigm.nodes as rounded rectangles (rx=4, fill #f0efe9, stroke #1a1a1a at 1.2, Georgia 11px labels, text-anchor middle). Draw connectors described by paradigm.flow; flow strings use arrow syntax inside the data file (for example 'Observe -> Reason -> Act -> Observe' means a three-node cycle). Convert every such directed relation into an arrowed connector. If paradigm.flow contains 'bi:' prefix, render a bidirectional pair of arrows. Keep node sizing consistent across all three panels. This arrow notation appears only inside data files; the body prose must still avoid arrow symbols.\n\nMULTI-NODE ROW GEOMETRY (critical): whenever N sibling nodes sit on the same horizontal row inside a panel (for example Worker A, Worker B, Worker C in an orchestrator-workers panel, or three siblings in a fan-out layout), their rect widths and centers MUST follow this deterministic formula so rects never overlap AND the row is centered on panel-local x=120. Panel interior width is 220 (panel-local x in [10, 230], horizontal center at 120). Compute rect_width = floor((200 - 10 * (N + 1)) / N) and clamp to a minimum of 44 and a maximum of 72. Compute total_row_width = N * rect_width + (N - 1) * 10. Compute start_x (panel-local, left edge of leftmost rect) = 120 - total_row_width / 2. Compute center_x_i (panel-local) = start_x + (rect_width / 2) + (rect_width + 10) * i for i in 0..N-1. Use rect_height = 26. Adjacent rects MUST leave at least 10 panel-local pixels of horizontal gap between their facing edges. If a label does not fit inside the computed rect_width at 11px, drop the label to Georgia 10px; if it still does not fit, shorten the label (for example 'Worker A' rather than 'Worker Agent A'). Never widen a rect past its computed rect_width to accommodate a label.\n\nHARD INVARIANTS (check before emitting): no two rects in the same panel and same y-row have overlapping x ranges; every label stays fully inside its rect; no node rectangle from panel i overlaps the background of panel j for i != j; every connector's endpoints sit on the edge of a node rect, not inside it; the collective horizontal center of each panel's visible content aligns with panel-local x=120 (if a panel has multiple vertical rows, each row is independently centered on x=120).",
+      "element_budget": "roughly 60 to 80 SVG elements"
+    },
+    {
+      "id": "Figure 3",
+      "caption": "Representative stack for the surveyed field. Derive layers from research_bundle.stack.",
+      "description": "Vertical layered stack diagram rendered as inline SVG, viewport exactly 720 wide by 360 tall. Set both the SVG width attribute and the viewBox to '0 0 720 360'. One horizontal layer bar per entry in research_bundle.stack (ordered bottom-to-top as given in the array), each exactly 360 wide starting at x=40 (so the bar's right edge is at x=400) and 44 tall with rounded corners rx=4 and at least 8px of vertical gap between layers. Use a subtle fill gradient across the stack by varying fills from bottom to top through #e8e6dc, #ece9df, #f0ede2, #f4f1e6, #f8f5e9, #fbfaf6 (cycle or interpolate if there are more or fewer than six layers). Add a left accent bar (fill #8a2a2b, width 4) running the full height of the bottom-most layer only, to emphasize its foundational role. Layer label (research_bundle.stack[i].name) centered inside each bar in Georgia bold 13px. To the right of each bar, render research_bundle.stack[i].role as a short italic descriptive phrase (about 6 to 10 words) in Georgia 11px color #6b6b6b, vertically centered. Role text tspans start at x=420 and MUST wrap across at most two lines (dy=0 and dy=14) so the widest line fits within the viewport right edge at x=720. If a line would exceed x=700, break it at an earlier word boundary or shorten the role phrase; never allow text to run past x=710.",
+      "element_budget": "roughly 40 SVG elements"
+    }
+  ],
+  "figure_quality_note": "Figures should read as polished academic figures, not quick wireframes. Maintain a consistent visual vocabulary across all three: identical stroke weights, identical corner radii, identical typography (Georgia serif), and shared marker definitions for arrowheads. Avoid gradients and filters, but do use subtle fill differentiation, rounded corners, and bezier curves where appropriate. Every label must have enough padding to never touch a border or another label.",
+  "required_tables": [
+    {
+      "id": "Table 1",
+      "caption": "Representative systems across the surveyed dimensions. Derive columns from research_bundle.table.columns and rows from research_bundle.table.rows.",
+      "columns_source": "research_bundle.table.columns (array of 4 to 6 short column headers).",
+      "rows_source": "research_bundle.table.rows (array of 8 to 12 objects, one per representative system, with a value for every column)."
+    }
+  ],
+  "color_palette": {
+    "background": "#fbfaf6",
+    "text": "#1a1a1a",
+    "accent": "#8a2a2b",
+    "muted": "#6b6b6b",
+    "rule_lines": "#d6d3c4"
+  },
+  "tone_and_voice": {
+    "register": "academic survey, measured, precise",
+    "person": "third person, no first-person voice",
+    "claims": "descriptive rather than promotional, hedged where appropriate",
+    "avoid": ["marketing language", "exclamation points", "informal contractions", "em dashes", "arrow symbols in prose"]
+  },
+  "hard_rules_for_generation": [
+    "Output exactly one self-contained HTML document. No external CSS, no external JS, no external images, no web fonts. Inline everything.",
+    "All figures must be rendered as inline SVG elements within the HTML.",
+    "Emit figures in the exact order of required_figures and use the exact numeric IDs from required_figures[].id in each figcaption (Figure 1, Figure 2, Figure 3 in that sequence). Figure N must appear in document order before Figure N+1. Do not renumber, skip, or reorder figures even if it seems the surrounding prose would read better the other way. Place each figure inside the section whose topic best matches it, but if two figures would appear in the same section, keep them in numerical order.",
+    "Cite only bibliography entries that appear in the provided research_bundle. Do not invent citations.",
+    "Use the section structure from the research_bundle. Do not add or remove sections.",
+    "Total body length target: roughly 5000 to 6500 words across all sections combined. Each section should carry substantive discussion (at least 3 paragraphs) and integrate multiple cited works. Finish all sections and the References section before reaching the token budget.",
+    "Generate sections in order. Place figures inside their sections. If the token budget is tight, shorten prose rather than dropping sections or references.",
+    "Do not include any content before <!DOCTYPE html> or after </html>.",
+    "Do not use em dashes or arrow symbols in body prose.",
+    "Produce a References section at the end that lists every bibliography entry in numeric order, formatted consistently."
+  ]
+}

package/bundled-skills/survey-generator/templates/research_bundle_template.json

@@ -0,0 +1,69 @@
+{
+  "title": "Survey Title: A Descriptive Subtitle",
+  "authors_placeholder": "Anonymous",
+  "anchor_source": "https://example.com/public-resource-used-as-anchor",
+  "abstract_hints": [
+    "One sentence framing the problem space.",
+    "One sentence describing why the field is coalescing now.",
+    "One sentence previewing the taxonomy and contributions of this survey."
+  ],
+  "taxonomy": {
+    "root": "Survey Topic",
+    "branches": [
+      { "name": "Branch A", "children": ["Leaf A1", "Leaf A2", "Leaf A3"] },
+      { "name": "Branch B", "children": ["Leaf B1", "Leaf B2"] },
+      { "name": "Branch C", "children": ["Leaf C1", "Leaf C2", "Leaf C3"] },
+      { "name": "Branch D", "children": ["Leaf D1", "Leaf D2"] },
+      { "name": "Branch E", "children": ["Leaf E1", "Leaf E2", "Leaf E3"] }
+    ]
+  },
+  "paradigms": [
+    {
+      "name": "Paradigm 1",
+      "nodes": ["Step A", "Step B", "Step C"],
+      "flow": "Step A -> Step B -> Step C -> Step A"
+    },
+    {
+      "name": "Paradigm 2",
+      "nodes": ["Plan", "Subtask 1", "Subtask 2", "Subtask 3"],
+      "flow": "Plan -> Subtask 1; Plan -> Subtask 2; Plan -> Subtask 3"
+    },
+    {
+      "name": "Paradigm 3",
+      "nodes": ["Act", "Reflect", "Memory"],
+      "flow": "Act -> Reflect -> Act; bi: Reflect -> Memory"
+    }
+  ],
+  "stack": [
+    { "name": "Layer 1 (foundational)", "role": "Short italic role description for layer 1." },
+    { "name": "Layer 2", "role": "Short italic role description for layer 2." },
+    { "name": "Layer 3", "role": "Short italic role description for layer 3." },
+    { "name": "Layer 4", "role": "Short italic role description for layer 4." },
+    { "name": "Layer 5", "role": "Short italic role description for layer 5." },
+    { "name": "Layer 6 (topmost)", "role": "Short italic role description for layer 6." }
+  ],
+  "sections": [
+    { "id": "1", "title": "Introduction", "guidance": "Frame the problem and preview the taxonomy." },
+    { "id": "2", "title": "Foundations", "guidance": "Cover the core primitives.", "papers": ["Key1", "Key2"] },
+    { "id": "3", "title": "Methods", "guidance": "Survey the main methodological families.", "papers": ["Key3", "Key4"] },
+    { "id": "4", "title": "Systems", "guidance": "Compare representative systems.", "papers": ["Key5", "Key6"] },
+    { "id": "5", "title": "Evaluation", "guidance": "Review benchmarks and metrics.", "papers": ["Key7"] },
+    { "id": "6", "title": "Open Problems and Future Directions", "guidance": "Discuss reliability, cost, portability, and open research questions." }
+  ],
+  "table": {
+    "columns": ["System", "Primary Mechanism", "Key Contribution", "Primary Evaluation"],
+    "rows": [
+      { "System": "Example System", "Primary Mechanism": "Short description", "Key Contribution": "Short description", "Primary Evaluation": "Short description" }
+    ]
+  },
+  "bibliography": [
+    {
+      "key": "Key1",
+      "authors": "Author, A. et al.",
+      "year": "2024",
+      "title": "Paper Title",
+      "venue": "Venue Year",
+      "summary": "One to two sentence summary of the paper's contribution."
+    }
+  ]
+}

package/bundled-skills/tdd/SKILL.md

@@ -0,0 +1,139 @@
+---
+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.
+category: "development"
+risk: "safe"
+source: "community"
+source_repo: "mattpocock/skills"
+source_type: "community"
+date_added: "2026-06-19"
+author: "Matt Pocock"
+license: "MIT"
+license_source: "https://github.com/mattpocock/skills/blob/main/LICENSE"
+tags:
+  - engineering
+  - workflow
+  - coding-agents
+tools:
+  - claude-code
+  - codex-cli
+  - cursor
+---
+
+# Test-Driven Development
+
+## When to Use
+
+Use when this workflow matches the user request: Use this skill for its documented workflow.
+
+
+_Source: [mattpocock/skills](https://github.com/mattpocock/skills) (MIT)._
+
+## Philosophy
+
+**Core principle**: Tests should verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't.
+
+**Good tests** are integration-style: they exercise real code paths through public APIs. They describe _what_ the system does, not _how_ it does it. A good test reads like a specification - "user can checkout with valid cart" tells you exactly what capability exists. These tests survive refactors because they don't care about internal structure.
+
+**Bad tests** are coupled to implementation. They mock internal collaborators, test private methods, or verify through external means (like querying a database directly instead of using the interface). The warning sign: your test breaks when you refactor, but behavior hasn't changed. If you rename an internal function and tests fail, those tests were testing implementation, not behavior.
+
+See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
+
+## Anti-Pattern: Horizontal Slices
+
+**DO NOT write all tests first, then all implementation.** This is "horizontal slicing" - treating RED as "write all tests" and GREEN as "write all code."
+
+This produces **crap tests**:
+
+- Tests written in bulk test _imagined_ behavior, not _actual_ behavior
+- You end up testing the _shape_ of things (data structures, function signatures) rather than user-facing behavior
+- Tests become insensitive to real changes - they pass when behavior breaks, fail when behavior is fine
+- You outrun your headlights, committing to test structure before understanding the implementation
+
+**Correct approach**: Vertical slices via tracer bullets. One test → one implementation → repeat. Each test responds to what you learned from the previous cycle. Because you just wrote the code, you know exactly what behavior matters and how to verify it.
+
+```
+WRONG (horizontal):
+  RED:   test1, test2, test3, test4, test5
+  GREEN: impl1, impl2, impl3, impl4, impl5
+
+RIGHT (vertical):
+  RED→GREEN: test1→impl1
+  RED→GREEN: test2→impl2
+  RED→GREEN: test3→impl3
+  ...
+```
+
+## Workflow
+
+### 1. Planning
+
+When exploring the codebase, read `CONTEXT.md` (if it exists) so that test names and interface vocabulary match the project's domain language, and respect ADRs in the area you're touching.
+
+Before writing any code:
+
+- [ ] Confirm with user what interface changes are needed
+- [ ] Confirm with user which behaviors to test (prioritize)
+- [ ] Identify opportunities for deep modules (small interface, deep implementation) — run the `/codebase-design` skill for the vocabulary and the testability checks
+- [ ] List the behaviors to test (not implementation steps)
+- [ ] Get user approval on the plan
+
+Ask: "What should the public interface look like? Which behaviors are most important to test?"
+
+**You can't test everything.** Confirm with the user exactly which behaviors matter most. Focus testing effort on critical paths and complex logic, not every possible edge case.
+
+### 2. Tracer Bullet
+
+Write ONE test that confirms ONE thing about the system:
+
+```
+RED:   Write test for first behavior → test fails
+GREEN: Write minimal code to pass → test passes
+```
+
+This is your tracer bullet - proves the path works end-to-end.
+
+### 3. Incremental Loop
+
+For each remaining behavior:
+
+```
+RED:   Write next test → fails
+GREEN: Minimal code to pass → passes
+```
+
+Rules:
+
+- One test at a time
+- Only enough code to pass current test
+- Don't anticipate future tests
+- Keep tests focused on observable behavior
+
+### 4. Refactor
+
+After all tests pass, look for [refactor candidates](refactoring.md):
+
+- [ ] Extract duplication
+- [ ] Deepen modules (move complexity behind simple interfaces)
+- [ ] Apply SOLID principles where natural
+- [ ] Consider what new code reveals about existing code
+- [ ] Run tests after each refactor step
+
+**Never refactor while RED.** Get to GREEN first.
+
+## Checklist Per Cycle
+
+```
+[ ] Test describes behavior, not implementation
+[ ] Test uses public interface only
+[ ] Test would survive internal refactor
+[ ] Code is minimal for this test
+[ ] No speculative features added
+```
+
+
+## Limitations
+
+- Requires the upstream tool, account, API key, or local setup when the workflow names one.
+- Does not authorize destructive, production, paid, or external-message actions without explicit user approval.
+- Validate generated artifacts or recommendations against the user's real sources before treating them as final.

package/bundled-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/bundled-skills/tdd/refactoring.md

@@ -0,0 +1,10 @@
+# Refactor Candidates
+
+After TDD cycle, look for:
+
+- **Duplication** → Extract function/class
+- **Long methods** → Break into private helpers (keep tests on public interface)
+- **Shallow modules** → Combine or deepen
+- **Feature envy** → Move logic to where data lives
+- **Primitive obsession** → Introduce value objects
+- **Existing code** the new code reveals as problematic

package/bundled-skills/tdd/tests.md

@@ -0,0 +1,61 @@
+# 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");
+});
+```

package/bundled-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/bundled-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/bundled-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/bundled-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.