@damiangilgonzalez/harness 1.3.7

package/skills/muscle-memory/assets/library-seed/generators/card.md

@@ -0,0 +1,24 @@
+# Generators (`yield`)
+
+## What it is
+A generator function uses `yield` instead of `return` to produce a sequence of values lazily, one at a time, without building the whole list in memory. Each step of iteration (`next()`, or a `for` loop) resumes the function right after the last `yield`.
+
+## Idiomatic example
+```python
+def even_numbers(limit: int):
+    n = 0
+    while n < limit:
+        if n % 2 == 0:
+            yield n
+        n += 1
+```
+
+## Common mistakes
+- Calling the generator function and expecting a list back — it returns a generator object; you must iterate it (or wrap in `list(...)`) to get values.
+- Iterating a generator twice, expecting it to restart — generators are exhausted after one full pass and must be recreated.
+- Doing all the work eagerly and `yield`-ing only at the end, defeating the purpose of lazy evaluation.
+
+## Where you see it in real code
+- Streaming large files or query results line by line instead of loading everything into memory.
+- Data pipelines that chain generators (`read -> filter -> transform`), each stage lazily pulling from the previous one.
+- Unbounded sequences (retry delays, IDs) that would never fit in a list.

package/skills/muscle-memory/assets/library-seed/generators/katas/l2-error-lines.json

@@ -0,0 +1,9 @@
+{
+  "concept": "generators",
+  "level": 2,
+  "title_en": "Build a lazy error_lines generator",
+  "spec_html_en": "<p>Write generator function <code>error_lines(lines)</code> that yields each string in <code>lines</code> containing the substring <code>'ERROR'</code>, in order, using <code>yield</code> (not building an intermediate list).</p>",
+  "stub": "def error_lines(lines):\n    # TODO: implement per spec, using yield\n    ...\n",
+  "test": "def test_yields_only_error_lines():\n    lines = ['INFO: start', 'ERROR: disk full', 'INFO: ok', 'ERROR: timeout']\n    result = list(error_lines(lines))\n    assert result == ['ERROR: disk full', 'ERROR: timeout'], 'must yield only lines containing ERROR, in order'\n\ndef test_returns_a_generator():\n    import types\n    gen = error_lines(['ERROR: x'])\n    assert isinstance(gen, types.GeneratorType), 'error_lines must be a generator function (use yield, not return a list)'\n\ndef test_no_errors_yields_nothing():\n    result = list(error_lines(['INFO: fine', 'DEBUG: noop']))\n    assert result == [], 'if no line contains ERROR, nothing is yielded'",
+  "canonical": "def error_lines(lines):\n    for line in lines:\n        if 'ERROR' in line:\n            yield line\n"
+}

package/skills/muscle-memory/assets/library-seed/generators/katas/l3-job-pipeline.json

@@ -0,0 +1,9 @@
+{
+  "concept": "generators",
+  "level": 3,
+  "title_en": "Compose a job-queue generator pipeline",
+  "spec_html_en": "<p>Write generator <code>pending_jobs(jobs)</code> yielding each job dict from <code>jobs</code> whose <code>status</code> is <code>'pending'</code>. Write generator <code>describe_jobs(jobs)</code> yielding <code>f\"{job['id']}: {job['name']}\"</code> for each job in its input. Then write <code>pending_job_descriptions(jobs)</code> that pipes <code>jobs</code> through <code>pending_jobs</code> and then <code>describe_jobs</code>.</p>",
+  "stub": "def pending_jobs(jobs):\n    # TODO: implement per spec, using yield\n    ...\n\n\ndef describe_jobs(jobs):\n    # TODO: implement per spec, using yield\n    ...\n\n\ndef pending_job_descriptions(jobs):\n    # TODO: implement per spec, composing pending_jobs and describe_jobs\n    ...\n",
+  "test": "def test_pending_jobs_filters_by_status():\n    jobs = [{'id': 1, 'name': 'build', 'status': 'pending'}, {'id': 2, 'name': 'deploy', 'status': 'done'}]\n    result = list(pending_jobs(jobs))\n    assert result == [jobs[0]], 'pending_jobs must yield only jobs with status \"pending\"'\n\ndef test_describe_jobs_formats_each_job():\n    jobs = [{'id': 1, 'name': 'build', 'status': 'pending'}]\n    result = list(describe_jobs(jobs))\n    assert result == ['1: build'], 'describe_jobs must format each job as \"id: name\"'\n\ndef test_pipeline_combines_both_stages():\n    jobs = [\n        {'id': 1, 'name': 'build', 'status': 'pending'},\n        {'id': 2, 'name': 'deploy', 'status': 'done'},\n        {'id': 3, 'name': 'test', 'status': 'pending'},\n    ]\n    result = list(pending_job_descriptions(jobs))\n    assert result == ['1: build', '3: test'], 'the pipeline must filter to pending jobs and then describe them, in order'",
+  "canonical": "def pending_jobs(jobs):\n    for job in jobs:\n        if job['status'] == 'pending':\n            yield job\n\n\ndef describe_jobs(jobs):\n    for job in jobs:\n        yield f\"{job['id']}: {job['name']}\"\n\n\ndef pending_job_descriptions(jobs):\n    return describe_jobs(pending_jobs(jobs))\n"
+}

package/skills/muscle-memory/assets/library-seed/inheritance/card.md

@@ -0,0 +1,26 @@
+# Inheritance and `super()`
+
+## What it is
+Inheritance lets a subclass reuse and extend a base class's behavior. `super().__init__(...)` calls the parent's constructor so you don't duplicate its setup logic, and overriding a method lets a subclass replace or extend specific behavior while keeping the rest.
+
+## Idiomatic example
+```python
+class Employee:
+    def __init__(self, name: str):
+        self.name = name
+
+class Manager(Employee):
+    def __init__(self, name: str, team_size: int):
+        super().__init__(name)
+        self.team_size = team_size
+```
+
+## Common mistakes
+- Forgetting to call `super().__init__()` in the subclass, so the parent's attributes never get set.
+- Overriding a method and losing the parent's behavior entirely when the intent was to extend it (missing a `super().method()` call inside the override).
+- Deep inheritance chains where a small change in the base class breaks unrelated subclasses — prefer composition when behaviors don't share a true "is-a" relationship.
+
+## Where you see it in real code
+- Framework base classes (e.g. Django `Model`, FastAPI's exception classes) that you subclass and extend.
+- Domain hierarchies like `Vehicle` -> `Car`/`Truck`, or `Notification` -> `EmailNotification`/`SMSNotification`.
+- Overriding a `process()` or `validate()` method per subclass while sharing the rest of the workflow.

package/skills/muscle-memory/assets/library-seed/inheritance/katas/l1-email-notification.json

@@ -0,0 +1,9 @@
+{
+  "concept": "inheritance",
+  "level": 1,
+  "title_en": "Subclass Notification with super().__init__",
+  "spec_html_en": "<p>Define class <code>EmailNotification(Notification)</code> with <code>__init__(self, message, address)</code> that calls <code>super().__init__(message)</code> and stores <code>address</code>.</p>",
+  "stub": "class Notification:\n    def __init__(self, message: str):\n        self.message = message\n\n    def send(self):\n        return f'Sending: {self.message}'\n\n\n# TODO: define class EmailNotification(Notification) with __init__(self, message, address)\n# that calls super().__init__(message) and stores address\n",
+  "test": "def test_email_stores_message_via_super():\n    n = EmailNotification('Server down', 'ops@example.com')\n    assert n.message == 'Server down', 'EmailNotification must call super().__init__ to store message'\n\ndef test_email_stores_address():\n    n = EmailNotification('Server down', 'ops@example.com')\n    assert n.address == 'ops@example.com', 'EmailNotification must store its own address'\n\ndef test_email_inherits_send():\n    n = EmailNotification('Server down', 'ops@example.com')\n    assert n.send() == 'Sending: Server down', 'EmailNotification must inherit send() from Notification'",
+  "canonical": "class Notification:\n    def __init__(self, message):\n        self.message = message\n\n    def send(self):\n        return f'Sending: {self.message}'\n\n\nclass EmailNotification(Notification):\n    def __init__(self, message, address):\n        super().__init__(message)\n        self.address = address\n"
+}

package/skills/muscle-memory/assets/library-seed/inheritance/katas/l2-square.json

@@ -0,0 +1,9 @@
+{
+  "concept": "inheritance",
+  "level": 2,
+  "title_en": "Build Shape and an overriding Square",
+  "spec_html_en": "<p>The base class <code>Shape</code> (given below) has <code>__init__(self, name)</code> storing <code>name</code> and method <code>describe()</code> returning <code>f\"{name}: no area defined\"</code>. Implement subclass <code>Square(Shape)</code> with <code>__init__(self, side)</code> calling <code>super().__init__(\"square\")</code>, storing <code>side</code>, and overriding <code>describe()</code> to return <code>f\"square: area is {side * side}\"</code>.</p>",
+  "stub": "class Shape:\n    def __init__(self, name: str):\n        self.name = name\n\n    def describe(self) -> str:\n        return f'{self.name}: no area defined'\n\n\n# TODO: define Square(Shape) that calls super().__init__('square'), stores side,\n# and overrides describe() to return f'square: area is {side * side}'\n",
+  "test": "def test_shape_describe():\n    s = Shape('triangle')\n    assert s.describe() == 'triangle: no area defined', 'base Shape.describe must use the generic message'\n\ndef test_square_overrides_describe():\n    sq = Square(4)\n    assert sq.describe() == 'square: area is 16', 'Square.describe must override with the computed area'\n\ndef test_square_stores_side_and_name():\n    sq = Square(5)\n    assert sq.side == 5, 'Square must store side'\n    assert sq.name == 'square', 'Square must call super().__init__ to set name'",
+  "canonical": "class Shape:\n    def __init__(self, name):\n        self.name = name\n\n    def describe(self):\n        return f'{self.name}: no area defined'\n\n\nclass Square(Shape):\n    def __init__(self, side):\n        super().__init__('square')\n        self.side = side\n\n    def describe(self):\n        return f'square: area is {self.side * self.side}'\n"
+}

package/skills/muscle-memory/assets/library-seed/iterators/card.md

@@ -0,0 +1,32 @@
+# Iterators (`__iter__`/`__next__`)
+
+## What it is
+An iterator is any object with `__next__` (returns the next value, or raises `StopIteration` when exhausted) and `__iter__` (returns itself). Implementing both by hand — the "iterator protocol" — is how `for` loops and `next()` work under the hood, and lets you build custom lazy sequences without a generator function.
+
+## Idiomatic example
+```python
+class Countdown:
+    def __init__(self, start: int):
+        self.current = start
+
+    def __iter__(self):
+        return self
+
+    def __next__(self):
+        if self.current < 0:
+            raise StopIteration
+        value = self.current
+        self.current -= 1
+        return value
+```
+
+## Common mistakes
+- Forgetting `__iter__` must return `self` (or another iterator) — without it the object isn't recognized as iterable.
+- Forgetting to raise `StopIteration` at all, causing an infinite loop when the object is used in a `for` loop.
+- Mutating the "current position" state incorrectly, so the iterator skips a value or repeats one.
+- Confusing an *iterable* (has `__iter__` returning a fresh iterator each time, like a `list`) with an *iterator* (also has `__next__` and gets exhausted after one pass).
+
+## Where you see it in real code
+- Custom paginators that fetch one page from an API at a time via `__next__`.
+- Database cursors that stream rows lazily instead of loading a full result set.
+- Wrapping an external stream (socket, sensor feed) so it can be used directly in a `for` loop.

package/skills/muscle-memory/assets/library-seed/iterators/katas/l2-unread-messages.json

@@ -0,0 +1,9 @@
+{
+  "concept": "iterators",
+  "level": 2,
+  "title_en": "Build UnreadMessages with __iter__/__next__",
+  "spec_html_en": "<p>Write class <code>UnreadMessages</code> implementing the iterator protocol over a list of message dicts (each with a <code>read</code> key). <code>__init__(self, messages)</code> stores them. <code>__iter__</code> returns <code>self</code>. <code>__next__</code> returns the next message whose <code>read</code> is <code>False</code> (skipping read ones), and raises <code>StopIteration</code> when there are no more.</p>",
+  "stub": "class UnreadMessages:\n    # TODO: implement __init__, __iter__ and __next__ per spec\n    pass\n",
+  "test": "def test_iterates_only_unread():\n    messages = [{'text': 'hi', 'read': True}, {'text': 'call me', 'read': False}, {'text': 'urgent', 'read': False}]\n    result = list(UnreadMessages(messages))\n    assert result == [messages[1], messages[2]], 'must yield only messages with read=False, in order'\n\ndef test_iter_returns_self():\n    it = UnreadMessages([])\n    assert iter(it) is it, '__iter__ must return self so the object is its own iterator'\n\ndef test_raises_stop_iteration_when_exhausted():\n    it = UnreadMessages([{'text': 'a', 'read': False}])\n    next(it)\n    try:\n        next(it)\n        assert False, 'calling next() past the last unread message must raise StopIteration'\n    except StopIteration:\n        pass",
+  "canonical": "class UnreadMessages:\n    def __init__(self, messages):\n        self.messages = messages\n        self.index = 0\n\n    def __iter__(self):\n        return self\n\n    def __next__(self):\n        while self.index < len(self.messages):\n            message = self.messages[self.index]\n            self.index += 1\n            if not message['read']:\n                return message\n        raise StopIteration\n"
+}

package/skills/muscle-memory/assets/library-seed/iterators/katas/l3-paginator.json

@@ -0,0 +1,9 @@
+{
+  "concept": "iterators",
+  "level": 3,
+  "title_en": "Build Paginator that stops on an empty page",
+  "spec_html_en": "<p>Write class <code>Paginator</code> implementing the iterator protocol. <code>__init__(self, fetch_page)</code> stores a zero-argument callable <code>fetch_page</code> that returns a list of items for the next page, or an empty list when there is no more data. <code>__iter__</code> returns <code>self</code>. <code>__next__</code> calls <code>fetch_page()</code>: if it returns a non-empty list, return it; if it returns an empty list, raise <code>StopIteration</code>.</p>",
+  "stub": "class Paginator:\n    # TODO: implement __init__, __iter__ and __next__ per spec\n    pass\n",
+  "test": "def test_yields_each_nonempty_page():\n    pages = [['a', 'b'], ['c'], []]\n\n    def fetch_page():\n        return pages.pop(0)\n\n    paginator = Paginator(fetch_page)\n    assert next(paginator) == ['a', 'b'], 'the first call must return the first non-empty page'\n    assert next(paginator) == ['c'], 'the second call must return the second non-empty page'\n\ndef test_stops_on_empty_page():\n    pages = [['x'], []]\n\n    def fetch_page():\n        return pages.pop(0)\n\n    paginator = Paginator(fetch_page)\n    next(paginator)\n    try:\n        next(paginator)\n        assert False, 'an empty page from fetch_page must raise StopIteration'\n    except StopIteration:\n        pass\n\ndef test_works_in_a_for_loop():\n    pages = [['a'], ['b'], []]\n\n    def fetch_page():\n        return pages.pop(0)\n\n    collected = [page for page in Paginator(fetch_page)]\n    assert collected == [['a'], ['b']], 'a for-loop over the paginator must collect pages until StopIteration'",
+  "canonical": "class Paginator:\n    def __init__(self, fetch_page):\n        self.fetch_page = fetch_page\n\n    def __iter__(self):\n        return self\n\n    def __next__(self):\n        page = self.fetch_page()\n        if not page:\n            raise StopIteration\n        return page\n"
+}

package/skills/muscle-memory/assets/library-seed/methods/card.md

@@ -0,0 +1,32 @@
+# Instance, `@staticmethod` and `@classmethod`
+
+## What it is
+A regular method receives the instance as `self` and can read/change its state. `@staticmethod` drops that first argument entirely — it's just a function namespaced under the class. `@classmethod` receives the class itself as `cls`, which is the idiomatic way to build alternative constructors.
+
+## Idiomatic example
+```python
+class Temperature:
+    def __init__(self, celsius: float):
+        self.celsius = celsius
+
+    def to_fahrenheit(self) -> float:
+        return self.celsius * 9 / 5 + 32
+
+    @staticmethod
+    def is_valid(celsius: float) -> bool:
+        return celsius >= -273.15
+
+    @classmethod
+    def from_fahrenheit(cls, fahrenheit: float) -> "Temperature":
+        return cls((fahrenheit - 32) * 5 / 9)
+```
+
+## Common mistakes
+- Marking a method `@staticmethod` when it actually needs `self` or `cls`.
+- Using `ClassName` hardcoded inside a `@classmethod` instead of `cls`, which breaks subclassing.
+- Forgetting the decorator and calling `self.method()` when the intent was a helper that ignores instance state.
+
+## Where you see it in real code
+- `@classmethod` alternative constructors like `dict.fromkeys()` or `datetime.fromisoformat()`.
+- `@staticmethod` utility/validation helpers grouped under a class for namespacing.
+- Factory classes that pick an implementation via a `@classmethod` based on config.

package/skills/muscle-memory/assets/library-seed/methods/katas/l1-coupon.json

@@ -0,0 +1,9 @@
+{
+  "concept": "methods",
+  "level": 1,
+  "title_en": "Add a staticmethod code validator",
+  "spec_html_en": "<p>The class <code>Coupon</code> already applies a discount. Add a <code>@staticmethod</code> <code>is_valid_code(code)</code> that returns <code>True</code> if <code>code</code> starts with <code>\"SALE-\"</code>, <code>False</code> otherwise.</p>",
+  "stub": "class Coupon:\n    def __init__(self, code: str, percent_off: float):\n        self.code = code\n        self.percent_off = percent_off\n\n    def apply(self, price: float) -> float:\n        return price * (1 - self.percent_off / 100)\n\n    # TODO: add a staticmethod is_valid_code(code) -> bool, True if code starts with 'SALE-'\n",
+  "test": "def test_apply_discount():\n    c = Coupon('SALE-10', 10)\n    assert c.apply(100) == 90, 'apply(100) with 10% off must be 90'\n\ndef test_valid_code_true():\n    assert Coupon.is_valid_code('SALE-5') is True, \"codes starting with 'SALE-' are valid\"\n\ndef test_valid_code_false():\n    assert Coupon.is_valid_code('XYZ') is False, \"codes not starting with 'SALE-' are invalid\"",
+  "canonical": "class Coupon:\n    def __init__(self, code, percent_off):\n        self.code = code\n        self.percent_off = percent_off\n\n    def apply(self, price):\n        return price * (1 - self.percent_off / 100)\n\n    @staticmethod\n    def is_valid_code(code):\n        return code.startswith('SALE-')\n"
+}

package/skills/muscle-memory/assets/library-seed/methods/katas/l2-duration.json

@@ -0,0 +1,9 @@
+{
+  "concept": "methods",
+  "level": 2,
+  "title_en": "Build Duration with an alternative constructor",
+  "spec_html_en": "<p>Write class <code>Duration</code> with <code>__init__(self, seconds)</code> storing <code>seconds</code>. Add a <code>classmethod</code> <code>from_minutes(cls, minutes)</code> that builds a <code>Duration</code> from minutes (<code>minutes * 60</code>).</p>",
+  "stub": "class Duration:\n    # TODO: implement __init__ and classmethod from_minutes per spec\n    pass\n",
+  "test": "def test_stores_seconds():\n    d = Duration(90)\n    assert d.seconds == 90, 'constructor must store seconds'\n\ndef test_from_minutes():\n    d = Duration.from_minutes(2)\n    assert d.seconds == 120, 'from_minutes(2) must create a Duration of 120 seconds'\n\ndef test_from_minutes_returns_duration():\n    d = Duration.from_minutes(1)\n    assert isinstance(d, Duration), 'from_minutes must return a Duration instance'",
+  "canonical": "class Duration:\n    def __init__(self, seconds):\n        self.seconds = seconds\n\n    @classmethod\n    def from_minutes(cls, minutes):\n        return cls(minutes * 60)\n"
+}

package/skills/muscle-memory/assets/library-seed/observer/card.md

@@ -0,0 +1,28 @@
+# Observer
+
+## What it is
+The Observer pattern lets a subject keep a list of dependents ("observers"/subscribers) and notify all of them when something happens, without the subject knowing anything about what each observer does with the notification. It decouples "the thing that changes" from "the things that react to the change."
+
+## Idiomatic example
+```python
+class Publisher:
+    def __init__(self):
+        self.subscribers = []
+
+    def subscribe(self, callback):
+        self.subscribers.append(callback)
+
+    def notify(self, event):
+        for callback in self.subscribers:
+            callback(event)
+```
+
+## Common mistakes
+- Mutating the subscriber list while iterating over it inside `notify` (e.g. a callback that unsubscribes itself), which can skip subscribers or raise.
+- Forgetting to provide an `unsubscribe`, so observers accumulate forever and keep getting notified even after they should have stopped listening.
+- Letting `notify` swallow exceptions from one observer silently, hiding bugs, or letting one failing observer stop every other observer from being notified.
+
+## Where you see it in real code
+- GUI/event systems: button `on_click` handlers, DOM `addEventListener`.
+- Pub/sub messaging (Redis pub/sub, `asyncio` event emitters) notifying all consumers of a topic.
+- Reactive state: signals/stores that re-render every subscribed component when the underlying value changes.

package/skills/muscle-memory/assets/library-seed/observer/katas/l2-publisher.json

@@ -0,0 +1,9 @@
+{
+  "concept": "observer",
+  "level": 2,
+  "title_en": "Build Publisher with subscribe and notify",
+  "spec_html_en": "<p>Write class <code>Publisher</code>. <code>__init__(self)</code> sets up an empty list of subscribers. <code>subscribe(self, callback)</code> adds <code>callback</code> to that list. <code>notify(self, event)</code> calls every subscribed callback with <code>event</code>, in the order they subscribed.</p>",
+  "stub": "class Publisher:\n    # TODO: implement __init__, subscribe and notify per spec\n    pass\n",
+  "test": "def test_notifies_single_subscriber():\n    received = []\n    publisher = Publisher()\n    publisher.subscribe(lambda event: received.append(event))\n    publisher.notify('breaking news')\n    assert received == ['breaking news'], 'notify must call the subscribed callback with the event'\n\ndef test_notifies_multiple_subscribers_in_order():\n    received = []\n    publisher = Publisher()\n    publisher.subscribe(lambda event: received.append(('a', event)))\n    publisher.subscribe(lambda event: received.append(('b', event)))\n    publisher.notify('update')\n    assert received == [('a', 'update'), ('b', 'update')], 'notify must call every subscriber, in the order they subscribed'\n\ndef test_no_subscribers_does_not_raise():\n    publisher = Publisher()\n    publisher.notify('anything')\n",
+  "canonical": "class Publisher:\n    def __init__(self):\n        self.subscribers = []\n\n    def subscribe(self, callback):\n        self.subscribers.append(callback)\n\n    def notify(self, event):\n        for callback in self.subscribers:\n            callback(event)\n"
+}

package/skills/muscle-memory/assets/library-seed/observer/katas/l3-stock-ticker.json

@@ -0,0 +1,9 @@
+{
+  "concept": "observer",
+  "level": 3,
+  "title_en": "Build StockTicker with unsubscribe",
+  "spec_html_en": "<p>Write class <code>StockTicker</code> with <code>subscribe(self, callback)</code>, <code>unsubscribe(self, callback)</code> and <code>notify(self, price)</code>. <code>subscribe</code> adds a callback. <code>unsubscribe</code> removes it if present, doing nothing if it was never subscribed. <code>notify</code> calls every currently subscribed callback with <code>price</code>, in subscription order.</p>",
+  "stub": "class StockTicker:\n    # TODO: implement __init__, subscribe, unsubscribe and notify per spec\n    pass\n",
+  "test": "def test_subscriber_receives_notifications():\n    received = []\n    ticker = StockTicker()\n    ticker.subscribe(lambda price: received.append(price))\n    ticker.notify(100)\n    assert received == [100], 'a subscribed callback must receive the notified price'\n\ndef test_unsubscribed_callback_stops_receiving():\n    received = []\n    def watcher(price):\n        received.append(price)\n    ticker = StockTicker()\n    ticker.subscribe(watcher)\n    ticker.notify(100)\n    ticker.unsubscribe(watcher)\n    ticker.notify(200)\n    assert received == [100], 'after unsubscribe, the callback must not receive further notifications'\n\ndef test_unsubscribing_unknown_callback_is_a_no_op():\n    ticker = StockTicker()\n    def never_subscribed(price):\n        pass\n    ticker.unsubscribe(never_subscribed)\n    ticker.notify(50)\n",
+  "canonical": "class StockTicker:\n    def __init__(self):\n        self.subscribers = []\n\n    def subscribe(self, callback):\n        self.subscribers.append(callback)\n\n    def unsubscribe(self, callback):\n        if callback in self.subscribers:\n            self.subscribers.remove(callback)\n\n    def notify(self, price):\n        for callback in self.subscribers:\n            callback(price)\n"
+}

package/skills/muscle-memory/assets/library-seed/properties/card.md

@@ -0,0 +1,25 @@
+# The `@property` decorator
+
+## What it is
+`@property` turns a method into something accessed like a plain attribute (no parentheses), letting you compute a value on the fly or add validation on write, without changing the calling code. Pair it with `@name.setter` when the attribute also needs to be assignable.
+
+## Idiomatic example
+```python
+class Circle:
+    def __init__(self, radius: float):
+        self._radius = radius
+
+    @property
+    def area(self) -> float:
+        return 3.14159 * self._radius ** 2
+```
+
+## Common mistakes
+- Defining a setter without a matching getter property first (the `@x.setter` decorator needs `x` to already be a property).
+- Forgetting the leading underscore convention for the backing attribute (`self._radius`), which causes infinite recursion if the property and attribute share the same name.
+- Putting expensive or side-effecting work behind a property, surprising callers who expect attribute access to be cheap.
+
+## Where you see it in real code
+- Read-only computed fields on models (`full_name` from `first_name` + `last_name`).
+- Validated setters (e.g. rejecting a negative `price` or empty `email`).
+- Lazy-loaded attributes that fetch or cache a value the first time they're read.

package/skills/muscle-memory/assets/library-seed/properties/katas/l1-rectangle.json

@@ -0,0 +1,9 @@
+{
+  "concept": "properties",
+  "level": 1,
+  "title_en": "Add a read-only area property",
+  "spec_html_en": "<p>The class <code>Rectangle</code> stores <code>width</code> and <code>height</code>. Add a read-only property <code>area</code> returning <code>width * height</code>.</p>",
+  "stub": "class Rectangle:\n    def __init__(self, width: float, height: float):\n        self.width = width\n        self.height = height\n\n    # TODO: add a read-only property `area` returning width * height\n",
+  "test": "def test_area_basic():\n    r = Rectangle(3, 4)\n    assert r.area == 12, 'area must be width * height'\n\ndef test_area_no_parentheses():\n    r = Rectangle(2, 5)\n    assert r.area == 10, 'area must be accessed without parentheses, like an attribute'\n\ndef test_area_updates_with_dimensions():\n    r = Rectangle(1, 1)\n    r.width = 10\n    assert r.area == 10, 'area must reflect the current width and height'",
+  "canonical": "class Rectangle:\n    def __init__(self, width, height):\n        self.width = width\n        self.height = height\n\n    @property\n    def area(self):\n        return self.width * self.height\n"
+}

package/skills/muscle-memory/assets/library-seed/properties/katas/l2-thermostat.json

@@ -0,0 +1,9 @@
+{
+  "concept": "properties",
+  "level": 2,
+  "title_en": "Build Thermostat with a validated setter",
+  "spec_html_en": "<p>Write class <code>Thermostat</code> with <code>__init__(self, target_temp)</code>. Expose <code>target_temp</code> as a property; the setter must raise <code>ValueError</code> if the value is below 0 or above 40.</p>",
+  "stub": "class Thermostat:\n    # TODO: implement __init__ and target_temp property+setter per spec\n    pass\n",
+  "test": "def test_initial_value():\n    t = Thermostat(21)\n    assert t.target_temp == 21, 'constructor must store target_temp'\n\ndef test_setter_accepts_valid_value():\n    t = Thermostat(21)\n    t.target_temp = 25\n    assert t.target_temp == 25, 'setter must update target_temp within range'\n\ndef test_setter_rejects_out_of_range():\n    t = Thermostat(21)\n    try:\n        t.target_temp = 100\n        assert False, 'setting target_temp above 40 must raise ValueError'\n    except ValueError:\n        pass",
+  "canonical": "class Thermostat:\n    def __init__(self, target_temp):\n        self._target_temp = None\n        self.target_temp = target_temp\n\n    @property\n    def target_temp(self):\n        return self._target_temp\n\n    @target_temp.setter\n    def target_temp(self, value):\n        if value < 0 or value > 40:\n            raise ValueError('target_temp must be between 0 and 40')\n        self._target_temp = value\n"
+}

package/skills/muscle-memory/assets/library-seed/singleton/card.md

@@ -0,0 +1,25 @@
+# Singleton
+
+## What it is
+The Singleton pattern restricts a class to a single shared instance, usually enforced via `__new__`: the first call creates the instance and stores it; every later call returns that same stored instance instead of creating a new one.
+
+## Idiomatic example
+```python
+class Singleton:
+    _instance = None
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+```
+
+## Common mistakes
+- Forgetting that `__init__` still runs on *every* call to `Singleton()`, even when `__new__` returns the cached instance — re-initializing shared state by accident unless you guard it (e.g. `if not hasattr(self, ...)`).
+- Sharing the `_instance` attribute across unrelated subclasses instead of keying storage by `cls`, so every subclass ends up returning the base class's single instance.
+- **Reaching for Singleton at all**: it is global mutable state with a design-pattern name, which makes it hard to test (state leaks between tests unless explicitly reset) and hides a class's dependencies, since any code can silently reach the shared instance instead of receiving it explicitly.
+
+## Where you see it in real code
+- Usually a mistake: a "singleton database connection" or "singleton config" that becomes impossible to swap out in tests without monkeypatching class internals.
+- **Better alternatives, almost always preferable**: a plain **module** (Python modules are already singletons — imported once, shared everywhere — with no `__new__` gymnastics needed), or **dependency injection** (construct the shared object once at startup and pass it explicitly to whoever needs it, keeping dependencies visible and testable).
+- Legitimate uses are narrow: a process-wide resource that must genuinely be unique (e.g. a hardware lock), and even then a module-level instance usually beats a `__new__`-based class.

package/skills/muscle-memory/assets/library-seed/singleton/katas/l2-config-manager.json

@@ -0,0 +1,9 @@
+{
+  "concept": "singleton",
+  "level": 2,
+  "title_en": "Build ConfigManager as a singleton with __new__",
+  "spec_html_en": "<p>Write class <code>ConfigManager</code> using <code>__new__</code> so that every call to <code>ConfigManager()</code> returns the exact same instance. <code>__init__</code> is already implemented and only creates <code>self.settings</code> as an empty dict the first time, so re-running <code>__init__</code> on later calls does not wipe existing state.</p>",
+  "stub": "class ConfigManager:\n    _instance = None\n\n    def __new__(cls):\n        # TODO: implement per spec: return the same instance on every call\n        ...\n\n    def __init__(self):\n        if not hasattr(self, 'settings'):\n            self.settings = {}\n",
+  "test": "def test_returns_same_instance():\n    a = ConfigManager()\n    b = ConfigManager()\n    assert a is b, 'ConfigManager() must always return the same instance'\n\ndef test_shared_state_across_references():\n    a = ConfigManager()\n    a.settings['debug'] = True\n    b = ConfigManager()\n    assert b.settings['debug'] is True, 'all references must share the same underlying state'\n\ndef test_settings_not_reset_on_new_call():\n    a = ConfigManager()\n    a.settings['x'] = 1\n    b = ConfigManager()\n    assert b.settings['x'] == 1, 'creating a \"new\" instance must not wipe previously set state'\n",
+  "canonical": "class ConfigManager:\n    _instance = None\n\n    def __new__(cls):\n        if cls._instance is None:\n            cls._instance = super().__new__(cls)\n        return cls._instance\n\n    def __init__(self):\n        if not hasattr(self, 'settings'):\n            self.settings = {}\n"
+}

package/skills/muscle-memory/assets/library-seed/singleton/katas/l3-per-subclass-singleton.json

@@ -0,0 +1,9 @@
+{
+  "concept": "singleton",
+  "level": 3,
+  "title_en": "Build a Singleton base class with one instance per subclass",
+  "spec_html_en": "<p>Write class <code>Singleton</code> implementing <code>__new__</code> so that each concrete subclass gets its own single shared instance: <code>_instances</code> must be a dict keyed by the class itself, so two different subclasses never share the same instance, but two calls to the same subclass always return the same one.</p>",
+  "stub": "class Singleton:\n    _instances = {}\n\n    def __new__(cls):\n        # TODO: implement per spec: one shared instance per concrete subclass,\n        # keyed by cls in _instances\n        ...\n",
+  "test": "class Logger(Singleton):\n    pass\n\nclass Cache(Singleton):\n    pass\n\ndef test_same_subclass_returns_same_instance():\n    a = Logger()\n    b = Logger()\n    assert a is b, 'two calls to the same subclass must return the same instance'\n\ndef test_different_subclasses_get_different_instances():\n    logger = Logger()\n    cache = Cache()\n    assert logger is not cache, 'different subclasses of Singleton must not share the same instance'\n\ndef test_each_subclass_keeps_its_own_state():\n    logger = Logger()\n    logger.name = 'app-logger'\n    same_logger = Logger()\n    assert same_logger.name == 'app-logger', 'the shared instance for a subclass must keep its state across references'\n",
+  "canonical": "class Singleton:\n    _instances = {}\n\n    def __new__(cls):\n        if cls not in cls._instances:\n            cls._instances[cls] = super().__new__(cls)\n        return cls._instances[cls]\n"
+}

package/skills/muscle-memory/assets/library-seed/strategy/card.md

@@ -0,0 +1,24 @@
+# Strategy
+
+## What it is
+The Strategy pattern extracts an algorithm into an interchangeable unit — often just a plain function in Python — so the object using it doesn't hardcode *how* something is computed. The caller passes in "the strategy" (a function or callable object) and the surrounding code stays the same no matter which strategy is used, including swapping it at runtime.
+
+## Idiomatic example
+```python
+def apply_shipping(order, shipping_strategy):
+    return shipping_strategy(order)
+
+
+def standard_shipping(order):
+    return order.weight * 0.5
+```
+
+## Common mistakes
+- Reaching for a class hierarchy (`ShippingStrategy` base class + subclasses) when a plain function already satisfies the interface — Python doesn't need inheritance for this.
+- Hardcoding the choice of strategy with `if/elif` inside the calling code instead of accepting the strategy as a parameter.
+- Storing the strategy once at construction time with no way to change it later, when the whole point of a runtime strategy is being able to swap it.
+
+## Where you see it in real code
+- `sorted(items, key=...)` and `list.sort(key=...)` — the `key` function is a strategy for comparison.
+- Pricing/discount engines that plug in a different calculation function per promotion or customer tier.
+- Compression or serialization libraries that accept a `codec`/`format` callable to swap the algorithm without touching the caller.

package/skills/muscle-memory/assets/library-seed/strategy/katas/l2-checkout-discount.json

@@ -0,0 +1,9 @@
+{
+  "concept": "strategy",
+  "level": 2,
+  "title_en": "Build checkout using a function as a strategy",
+  "spec_html_en": "<p>Write function <code>checkout(total, discount_strategy)</code>. Call <code>discount_strategy(total)</code> to get the discount amount, then return <code>total</code> minus that discount, clamped so the result never goes below <code>0</code>.</p>",
+  "stub": "def checkout(total, discount_strategy):\n    # TODO: implement per spec: apply discount_strategy(total) and clamp at 0\n    ...\n",
+  "test": "def test_percentage_discount():\n    def ten_percent_off(total):\n        return total * 0.1\n    assert checkout(200, ten_percent_off) == 180, 'a 10% discount on 200 must leave 180'\n\ndef test_flat_discount():\n    def flat_20_off(total):\n        return 20\n    assert checkout(50, flat_20_off) == 30, 'a flat 20 discount on 50 must leave 30'\n\ndef test_discount_never_goes_negative():\n    def flat_100_off(total):\n        return 100\n    assert checkout(30, flat_100_off) == 0, 'a discount larger than the total must clamp the result at 0, never negative'\n",
+  "canonical": "def checkout(total, discount_strategy):\n    discount = discount_strategy(total)\n    return max(total - discount, 0)\n"
+}

package/skills/muscle-memory/assets/library-seed/strategy/katas/l3-router-swap.json

@@ -0,0 +1,9 @@
+{
+  "concept": "strategy",
+  "level": 3,
+  "title_en": "Build Router that swaps strategy at runtime",
+  "spec_html_en": "<p>Write class <code>Router</code>. <code>__init__(self, strategy)</code> stores the initial strategy. <code>set_strategy(self, strategy)</code> replaces the active strategy. <code>plan(self, distance)</code> calls the current strategy with <code>distance</code> and returns its result.</p>",
+  "stub": "class Router:\n    # TODO: implement __init__, set_strategy and plan per spec\n    pass\n",
+  "test": "def test_uses_initial_strategy():\n    def fastest(distance):\n        return distance / 2\n    router = Router(fastest)\n    assert router.plan(100) == 50, 'plan must delegate to the strategy passed to __init__'\n\ndef test_swaps_strategy_at_runtime():\n    def fastest(distance):\n        return distance / 2\n    def cheapest(distance):\n        return distance * 1.5\n    router = Router(fastest)\n    router.set_strategy(cheapest)\n    assert router.plan(10) == 15, 'after set_strategy, plan must use the new strategy, not the old one'\n\ndef test_can_swap_back():\n    def a(distance):\n        return distance + 1\n    def b(distance):\n        return distance + 2\n    router = Router(a)\n    router.set_strategy(b)\n    router.set_strategy(a)\n    assert router.plan(0) == 1, 'set_strategy must allow swapping back to a previously used strategy'\n",
+  "canonical": "class Router:\n    def __init__(self, strategy):\n        self.strategy = strategy\n\n    def set_strategy(self, strategy):\n        self.strategy = strategy\n\n    def plan(self, distance):\n        return self.strategy(distance)\n"
+}

package/skills/muscle-memory/assets/library-seed/typing/card.md

@@ -0,0 +1,23 @@
+# Type hints: `Optional`, `|`, `TypedDict`
+
+## What it is
+Type hints document what a function expects and returns without changing runtime behavior; tools like mypy and editors use them to catch mistakes early. `Optional[X]` (or `X | None`) means "X or nothing"; `TypedDict` describes the expected shape of a dict with named, typed keys.
+
+## Idiomatic example
+```python
+from typing import Optional
+
+def find_user(user_id: int) -> Optional[str]:
+    users = {1: "Ana", 2: "Bo"}
+    return users.get(user_id)
+```
+
+## Common mistakes
+- Annotating a parameter as `Optional[X]` but forgetting the default is also `None` (`def f(x: Optional[int] = None)`), or forgetting to actually handle the `None` case in the body.
+- Confusing `TypedDict` (a typing-only shape check, zero runtime behavior) with a real class or `dataclass` — a `TypedDict` is still just a plain `dict` at runtime.
+- Using `Union`/`|` in a signature but never narrowing the type before using type-specific behavior, which is what type checkers flag.
+
+## Where you see it in real code
+- API layer functions where a lookup may legitimately return nothing (`Optional[User]`).
+- `TypedDict` for JSON payloads exchanged with external APIs where a full class would be overkill.
+- Public library functions annotated so IDEs autocomplete correctly for callers.

package/skills/muscle-memory/assets/library-seed/typing/katas/l1-order-status.json

@@ -0,0 +1,9 @@
+{
+  "concept": "typing",
+  "level": 1,
+  "title_en": "Annotate a lookup with Optional",
+  "spec_html_en": "<p>Implement <code>get_order_status(order_id, statuses)</code>: return the status stored for <code>order_id</code> in the <code>statuses</code> dict, or <code>None</code> if it is not present. Annotate the return type as <code>Optional[str]</code>.</p>",
+  "stub": "from typing import Optional\n\n\ndef get_order_status(order_id: int, statuses: dict):\n    # TODO: return statuses[order_id] if present, otherwise None; annotate the return type\n    # as Optional[str]\n    ...\n",
+  "test": "def test_known_order():\n    statuses = {1: 'shipped', 2: 'pending'}\n    assert get_order_status(1, statuses) == 'shipped', 'must return the stored status for a known order_id'\n\ndef test_unknown_order_returns_none():\n    statuses = {1: 'shipped'}\n    assert get_order_status(99, statuses) is None, 'an unknown order_id must return None, not raise'\n\ndef test_annotation_uses_optional():\n    from typing import Optional\n    ann = get_order_status.__annotations__\n    assert ann.get('return') == Optional[str], 'return type must be annotated as Optional[str] (or equivalently str | None)'",
+  "canonical": "from typing import Optional\n\n\ndef get_order_status(order_id: int, statuses: dict) -> Optional[str]:\n    return statuses.get(order_id)\n"
+}

package/skills/muscle-memory/assets/library-seed/typing/katas/l2-typed-dict-product.json

@@ -0,0 +1,9 @@
+{
+  "concept": "typing",
+  "level": 2,
+  "title_en": "Build a TypedDict and a function that uses it",
+  "spec_html_en": "<p>Define a <code>TypedDict</code> named <code>Product</code> with keys <code>name: str</code>, <code>price: float</code>, <code>qty: int</code>. Write function <code>total_value(product) -> float</code> returning <code>price * qty</code>.</p>",
+  "stub": "from typing import TypedDict\n\n\nclass Product(TypedDict):\n    # TODO: define keys name: str, price: float, qty: int\n    pass\n\n\ndef total_value(product: Product) -> float:\n    # TODO: return price * qty\n    pass\n",
+  "test": "def test_total_value():\n    p = {'name': 'Widget', 'price': 2.5, 'qty': 4}\n    assert total_value(p) == 10.0, 'total_value must be price * qty'\n\ndef test_total_value_zero_qty():\n    p = {'name': 'Gadget', 'price': 99.0, 'qty': 0}\n    assert total_value(p) == 0.0, 'total_value with qty 0 must be 0'\n\ndef test_product_is_plain_dict_at_runtime():\n    p = {'name': 'Widget', 'price': 1.0, 'qty': 1}\n    assert isinstance(p, dict), 'a TypedDict instance is still a plain dict at runtime'",
+  "canonical": "from typing import TypedDict\n\n\nclass Product(TypedDict):\n    name: str\n    price: float\n    qty: int\n\n\ndef total_value(product: Product) -> float:\n    return product['price'] * product['qty']\n"
+}

package/skills/muscle-memory/assets/user-readme.md

@@ -0,0 +1,45 @@
+# muscle-memory
+
+Your local training folder for the `muscle-memory` Claude Code skill. It lives
+inside the project you're working in and is git-ignored, so it never enters
+commits, CI, or pull requests. Everything here is yours and local; the rest of
+the repo is only ever read, never written to. Progress and history are
+per-project — practice follows the code you're actually working on.
+
+## What's in here
+
+- **`app/index.html`** — the training app. Self-contained (Pyodide + CodeMirror
+  load from CDN, everything else is inline). Open it by double-clicking, no
+  server needed.
+- **`sessions/`** — one file per training session (`<date>-<project>.js`),
+  plus `manifest.js` (which sessions the app shows, most recent first) and
+  `canonical/` (reference solutions used for review; not shown in the app).
+- **`library/`** — the concept catalog: one folder per concept (e.g.
+  `context-managers/`, `strategy/`), each with a `card.md` study note and a
+  `katas/` folder of ready-made kata skeletons. Read `card.md` files directly
+  as a cheat sheet, or ask Claude to pull from them.
+- **`solutions/`** — drop your downloaded `.py` solutions here for Claude to
+  review them.
+- **`progress.json`** — machine-readable progress: per-concept level, hits and
+  misses, and any topics you've retired.
+- **`history.md`** — a human-readable training log: what you practiced, what
+  passed/failed, and any topics you asked to stop seeing.
+
+## Opening the app
+
+Double-click `app/index.html` (or open it in a browser). It reads
+`sessions/manifest.js` to list your sessions — after Claude generates a new
+one, just reload the page.
+
+## Asking Claude for things
+
+- **Start a session**: "quiero practicar" / "ponme ejercicios" / "keep my
+  coding sharp" — Claude scans your current repo's recent code and builds a
+  3-kata session out of it.
+- **Get a solution reviewed**: drop the downloaded `.py` file in `solutions/`
+  (or just paste your code) and say "revisa mi solucion" / "review my
+  solution".
+- **Check progress**: "como voy" / "how am I doing" — a short summary of
+  what's solid, what's weak, and what's due next.
+- **Retire a topic**: "ya no quiero practicar X" / "ya me lo se" — Claude
+  stops proposing it. Ask again later to bring it back.