@mseep/core 3.0.0

package/skills/animation-at-work/scripts/audit_animations.py

@@ -0,0 +1,295 @@
+#!/usr/bin/env python3
+"""
+audit_animations.py - Audit CSS/SCSS for animation anti-patterns.
+
+Usage:
+    python audit_animations.py <file_or_directory>
+
+Scans .css and .scss files for animation anti-patterns documented in
+"Animation at Work" by Rachel Nabors.
+
+Checks performed:
+  1. Animating layout-triggering properties (use transform instead)
+  2. transition: all (too broad)
+  3. Transitions > 500ms or animations > 1000ms (too slow)
+  4. Durations < 100ms (too fast to perceive)
+  5. linear easing on UI transitions (use ease-out or cubic-bezier)
+  6. Missing prefers-reduced-motion in files that animate
+  7. infinite animations without a pause mechanism
+
+Outputs: file, line, offending CSS, and recommended fix.
+Summary at end: total issues by category.
+"""
+
+import argparse
+import pathlib
+import re
+import sys
+from collections import defaultdict
+from typing import NamedTuple
+
+
+class Issue(NamedTuple):
+    file: str
+    line: int
+    category: str
+    snippet: str
+    advice: str
+
+
+# Properties that trigger layout recalculation — animating them is expensive.
+LAYOUT_TRIGGERING = [
+    "width", "height", "top", "left", "right", "bottom",
+    "margin", "margin-top", "margin-right", "margin-bottom", "margin-left",
+    "padding", "padding-top", "padding-right", "padding-bottom", "padding-left",
+]
+
+CATEGORIES = {
+    "layout_property": "Layout-triggering property animated",
+    "transition_all": "transition: all used",
+    "too_slow": "Duration too long (sluggish UI)",
+    "too_fast": "Duration too short (imperceptible)",
+    "linear_easing": "Linear easing on UI transition",
+    "no_reduced_motion": "Missing prefers-reduced-motion",
+    "infinite_no_pause": "Infinite animation without pause mechanism",
+}
+
+
+def parse_duration_ms(value: str) -> float | None:
+    """Convert a CSS duration string (e.g. '0.3s', '300ms') to milliseconds."""
+    value = value.strip()
+    if value.endswith("ms"):
+        try:
+            return float(value[:-2])
+        except ValueError:
+            return None
+    if value.endswith("s"):
+        try:
+            return float(value[:-1]) * 1000
+        except ValueError:
+            return None
+    return None
+
+
+def find_css_files(path: pathlib.Path) -> list[pathlib.Path]:
+    if path.is_file():
+        if path.suffix in {".css", ".scss"}:
+            return [path]
+        print(f"WARNING: {path} is not a .css or .scss file — skipping.")
+        return []
+    return sorted(path.rglob("*.css")) + sorted(path.rglob("*.scss"))
+
+
+def audit_file(filepath: pathlib.Path) -> list[Issue]:
+    issues: list[Issue] = []
+    try:
+        lines = filepath.read_text(encoding="utf-8", errors="replace").splitlines()
+    except OSError as exc:
+        print(f"ERROR reading {filepath}: {exc}")
+        return []
+
+    file_str = filepath.as_posix()
+    full_text = "\n".join(lines)
+
+    has_animation = bool(
+        re.search(r"\b(transition|animation)\s*:", full_text)
+    )
+    has_reduced_motion = "prefers-reduced-motion" in full_text
+
+    for lineno, raw_line in enumerate(lines, start=1):
+        line = raw_line.strip()
+        if not line or line.startswith("//") or line.startswith("/*"):
+            continue
+
+        # 1. Animating layout-triggering properties
+        transition_match = re.match(r"transition\s*:\s*(.+)", line, re.IGNORECASE)
+        if transition_match:
+            props_part = transition_match.group(1)
+            for prop in LAYOUT_TRIGGERING:
+                if re.search(r"\b" + re.escape(prop) + r"\b", props_part, re.IGNORECASE):
+                    issues.append(Issue(
+                        file=file_str,
+                        line=lineno,
+                        category="layout_property",
+                        snippet=line[:120],
+                        advice=(
+                            f"Animating '{prop}' triggers layout recalculation on every frame. "
+                            "Use 'transform: translate/scale' or 'opacity' instead — "
+                            "these are compositor-only and do not cause reflow."
+                        ),
+                    ))
+
+        # 2. transition: all
+        if re.search(r"transition\s*:\s*all\b", line, re.IGNORECASE):
+            issues.append(Issue(
+                file=file_str,
+                line=lineno,
+                category="transition_all",
+                snippet=line[:120],
+                advice=(
+                    "'transition: all' animates every animatable property, including "
+                    "layout-triggering ones you may not intend. List specific properties: "
+                    "e.g., 'transition: opacity 0.2s ease-out, transform 0.2s ease-out'."
+                ),
+            ))
+
+        # 3 & 4. Duration checks — transition and animation shorthand
+        duration_patterns = [
+            re.compile(r"transition\s*:[^;]+", re.IGNORECASE),
+            re.compile(r"animation\s*:[^;]+", re.IGNORECASE),
+            re.compile(r"transition-duration\s*:\s*([^;]+)", re.IGNORECASE),
+            re.compile(r"animation-duration\s*:\s*([^;]+)", re.IGNORECASE),
+        ]
+        for pat in duration_patterns:
+            m = pat.search(line)
+            if not m:
+                continue
+            value_str = m.group(0)
+            is_animation = "animation" in value_str.lower() and "transition" not in value_str.lower()
+            for dur_match in re.finditer(r"\d+(?:\.\d+)?(?:ms|s)\b", value_str):
+                dur_ms = parse_duration_ms(dur_match.group(0))
+                if dur_ms is None:
+                    continue
+                slow_limit = 1000 if is_animation else 500
+                if dur_ms > slow_limit:
+                    issues.append(Issue(
+                        file=file_str,
+                        line=lineno,
+                        category="too_slow",
+                        snippet=line[:120],
+                        advice=(
+                            f"Duration {dur_ms:.0f}ms feels sluggish for UI feedback. "
+                            f"Keep UI transitions under {slow_limit}ms. "
+                            "Aim for 200-300ms for most interactions."
+                        ),
+                    ))
+                elif dur_ms < 100 and dur_ms > 0:
+                    issues.append(Issue(
+                        file=file_str,
+                        line=lineno,
+                        category="too_fast",
+                        snippet=line[:120],
+                        advice=(
+                            f"Duration {dur_ms:.0f}ms is below the human perception threshold (~100ms). "
+                            "The animation will not be noticed. Use 100-200ms for snappy transitions."
+                        ),
+                    ))
+
+        # 5. Linear easing on transitions
+        if re.search(r"transition\s*:", line, re.IGNORECASE):
+            if re.search(r"\blinear\b", line, re.IGNORECASE):
+                issues.append(Issue(
+                    file=file_str,
+                    line=lineno,
+                    category="linear_easing",
+                    snippet=line[:120],
+                    advice=(
+                        "Linear easing feels mechanical and unnatural for UI elements. "
+                        "Use 'ease-out' for elements entering the screen, 'ease-in' for "
+                        "elements leaving, or a custom cubic-bezier for branded motion."
+                    ),
+                ))
+
+        # 7. Infinite animation without pause mechanism
+        if re.search(r"animation-iteration-count\s*:\s*infinite\b", line, re.IGNORECASE):
+            # Check nearby lines (±10) for a paused state or play-state control
+            start = max(0, lineno - 10)
+            end = min(len(lines), lineno + 10)
+            context_block = "\n".join(lines[start:end])
+            if "animation-play-state" not in context_block and "paused" not in context_block:
+                issues.append(Issue(
+                    file=file_str,
+                    line=lineno,
+                    category="infinite_no_pause",
+                    snippet=line[:120],
+                    advice=(
+                        "Infinite animations can be distracting and drain battery on mobile. "
+                        "Add 'animation-play-state: paused' controlled via :hover, :focus, "
+                        "or a JS toggle so users can pause it."
+                    ),
+                ))
+
+    # 6. Missing prefers-reduced-motion
+    if has_animation and not has_reduced_motion:
+        issues.append(Issue(
+            file=file_str,
+            line=0,
+            category="no_reduced_motion",
+            snippet="(entire file)",
+            advice=(
+                "This file contains animations but no '@media (prefers-reduced-motion: reduce)' "
+                "block. Add one to disable or reduce motion for users who request it — "
+                "required for WCAG 2.1 AA compliance."
+            ),
+        ))
+
+    return issues
+
+
+def print_issues(issues: list[Issue]) -> None:
+    for issue in issues:
+        loc = f"{issue.file}:{issue.line}" if issue.line else issue.file
+        category_label = CATEGORIES.get(issue.category, issue.category)
+        print(f"\n[{category_label}]")
+        print(f"  Location : {loc}")
+        print(f"  CSS      : {issue.snippet}")
+        print(f"  Fix      : {issue.advice}")
+
+
+def print_summary(issues: list[Issue]) -> None:
+    counts: dict[str, int] = defaultdict(int)
+    for issue in issues:
+        counts[issue.category] += 1
+    print("\n" + "=" * 60)
+    print("SUMMARY")
+    print("=" * 60)
+    if not counts:
+        print("No issues found.")
+        return
+    for cat, label in CATEGORIES.items():
+        count = counts.get(cat, 0)
+        if count:
+            print(f"  {count:3d}  {label}")
+    print(f"  ---")
+    print(f"  {sum(counts.values()):3d}  Total issues")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Audit CSS/SCSS files for animation anti-patterns."
+    )
+    parser.add_argument(
+        "path",
+        help="A .css/.scss file or directory to scan recursively.",
+    )
+    args = parser.parse_args()
+
+    target = pathlib.Path(args.path)
+    if not target.exists():
+        print(f"ERROR: Path not found: {target}")
+        sys.exit(1)
+
+    files = find_css_files(target)
+    if not files:
+        print("No .css or .scss files found.")
+        sys.exit(0)
+
+    print(f"Scanning {len(files)} file(s) ...\n")
+
+    all_issues: list[Issue] = []
+    for f in files:
+        file_issues = audit_file(f)
+        all_issues.extend(file_issues)
+
+    if all_issues:
+        print_issues(all_issues)
+    else:
+        print("No animation anti-patterns detected.")
+
+    print_summary(all_issues)
+
+    sys.exit(1 if all_issues else 0)
+
+
+if __name__ == "__main__":
+    main()

package/skills/animation-at-work/scripts/example.py

@@ -0,0 +1 @@
+

package/skills/booklib-mcp-guide/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: booklib-mcp-guide
+version: "1.0"
+license: MIT
+tags: [meta, mcp, tools, agent-guide]
+description: "Use when working with BookLib MCP tools. Reference for lookup, review, remember, verify, guard — parameters, workflows, and anti-patterns."
+---
+
+# BookLib MCP Tool Guide
+
+BookLib exposes 5 MCP tools to AI coding agents. Each tool has a single purpose. This guide covers when to call each one, what parameters to pass, and common workflows.
+
+## Tool Reference
+
+| Tool | When to call | Key params |
+|------|-------------|------------|
+| `lookup` | Before working with unfamiliar APIs or post-training deps | `query` (required), `file`, `limit`, `source` |
+| `review` | User asks for deep code review of a specific file | `skill_name`, `file_path` (both required) |
+| `remember` | User says "remember this", "capture", or makes a team decision | `title` (required), `content`, `type`, `tags` |
+| `verify` | After writing code that uses unfamiliar or new APIs | `file_path` (required) |
+| `guard` | After writing code that touches architecture or API choices | `file_path` (required) |
+
+## Decision Tree
+
+```
+Need current docs for a post-training library  -> lookup
+Need a full expert review of a file            -> review
+User wants to save a decision or insight       -> remember
+Code uses unknown imports                      -> verify
+Code might violate team rules                  -> guard
+```
+
+## Tool Details
+
+### lookup
+
+Searches across post-training corrections, team knowledge, and expert skills. Returns structured principles with source citations.
+
+Parameters:
+- `query` (string, required): What you need to know. Include the library name and task.
+- `file` (string): Path to the file being worked on. Adds language and component context.
+- `limit` (number): Maximum results. Default: 3.
+- `source` (enum: all/skills/knowledge): Filter by source type.
+
+Prioritization order: (1) post-training gap corrections, (2) team knowledge nodes, (3) expert skill principles.
+
+### review
+
+Audits a file against a named skill's principles. Returns structured findings with line references and citations.
+
+Parameters:
+- `skill_name` (string, required): The skill to review against (e.g., "effective-kotlin", "clean-code-reviewer").
+- `file_path` (string, required): Path to the file to review.
+
+### remember
+
+Creates a searchable knowledge node. Automatically indexed and auto-linked to related nodes.
+
+Parameters:
+- `title` (string, required): Short descriptive title.
+- `content` (string): Detailed description in markdown.
+- `type` (enum: insight/decision/pattern/note/research): Node type. Default: "insight".
+- `tags` (string): Comma-separated tags.
+- `links` (string): Link targets as "target:edge-type" pairs.
+
+### verify
+
+Checks if a file's imports are covered by BookLib's index. Flags unknown post-training APIs that may need current docs.
+
+Parameters:
+- `file_path` (string, required): Path to the source file.
+
+Returns: list of unknown imports with suggested documentation URLs.
+
+### guard
+
+Checks if code contradicts captured team decisions. Compares code patterns against decision nodes.
+
+Parameters:
+- `file_path` (string, required): Path to the source file.
+
+Returns: list of contradictions with the violated decision and source.
+
+## Common Workflows
+
+### 1. Gap detection and resolution
+
+```
+verify file.ts            -> finds unknown import "@stripe/stripe-js"
+lookup "stripe js v5 api" -> returns current v5 docs
+                          -> write correct code using current API
+```
+
+### 2. Team knowledge enforcement
+
+```
+write code                -> make architectural choice
+guard file.ts             -> flags: contradicts "use PaymentIntents not Charges"
+                          -> fix the violation, commit
+```
+
+### 3. Knowledge capture during work
+
+```
+discover a useful pattern -> remember "retry with exponential backoff" --type pattern
+make a team decision      -> remember "use PaymentIntents not Charges" --type decision
+```
+
+## Anti-Patterns
+
+- **Don't call `lookup` for standard patterns.** React hooks, Python builtins, Go stdlib -- you already know these. Only call for project-specific or post-training knowledge.
+- **Don't call `verify` on stdlib imports.** Standard library imports are always known. Only check third-party imports.
+- **Don't call `remember` for ephemeral notes.** Only capture durable decisions, patterns, and insights that future sessions should know about.
+- **Don't call `review` without a specific skill.** The skill_name parameter is required -- pick the most relevant one or use "clean-code-reviewer" as default.
+- **Don't over-call tools.** One `lookup` per topic is enough. Don't repeat the same query hoping for different results.
+
+## CLI-Only Commands (Not MCP Tools)
+
+These features are available via the `booklib` CLI but not exposed as MCP tools:
+
+- `booklib connect <path>` -- connect a documentation source
+- `booklib connect github releases <repo>` -- index GitHub changelogs
+- `booklib connect notion database <id>` -- index Notion pages
+- `booklib link <from> <to> --type <edge>` -- connect two knowledge nodes
+- `booklib save-state --goal "..." --next "..."` -- save session for handoff
+- `booklib nodes list` / `booklib nodes show <id>` -- list and inspect knowledge
+- `booklib gaps` / `booklib resolve-gaps` -- detect and fix knowledge gaps
+- `booklib analyze` -- show affected files and post-training APIs
+- `booklib doctor` -- health check

package/skills/booklib-mcp-guide/evals/evals.json

@@ -0,0 +1,37 @@
+{
+  "evals": [
+    {
+      "id": "eval-01-lookup-trigger",
+      "prompt": "You are editing frontend/src/lib/supabase.ts which imports @supabase/supabase-js.\nThe file currently has:\n\nimport { createClient } from '@supabase/supabase-js'\n\nconst supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL!\nconst supabaseKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!\n\nexport const supabase = createClient(supabaseUrl, supabaseKey)\n\nYou need to add user authentication with email/password sign-in.\nBefore writing auth code, what BookLib tool should you call and why?",
+      "expectations": [
+        "Should call lookup with a query about supabase auth",
+        "Should NOT call lookup for standard TypeScript features",
+        "Should mention that supabase may be post-training",
+        "Should wait for lookup results before writing auth code",
+        "Should use the results to write correct v2 auth patterns"
+      ]
+    },
+    {
+      "id": "eval-02-guard-trigger",
+      "prompt": "You just wrote a payment processing module at src/payments/charge.ts:\n\nimport Stripe from 'stripe'\n\nconst stripe = new Stripe(process.env.STRIPE_SECRET_KEY!)\n\nexport async function processPayment(amount: number) {\n  const charge = await stripe.charges.create({\n    amount,\n    currency: 'usd',\n    source: 'tok_visa',\n  })\n  return charge\n}\n\nThe team previously decided to use PaymentIntents instead of Charges.\nWhat BookLib tool catches this violation and how does it work?",
+      "expectations": [
+        "Should mention the guard tool",
+        "Should explain guard checks code against team decisions",
+        "Should note the team decision about PaymentIntents",
+        "Should suggest fixing the code to use PaymentIntents",
+        "Should mention that guard runs automatically via PostToolUse hooks"
+      ]
+    },
+    {
+      "id": "eval-03-verify-trigger",
+      "prompt": "You added zod@3.25 to the project and wrote this validation module at src/lib/validate.ts:\n\nimport { z } from 'zod'\n\nexport const UserSchema = z.object({\n  name: z.string().min(1),\n  email: z.string().email(),\n  age: z.number().int().positive(),\n  role: z.enum(['admin', 'user', 'guest']),\n})\n\nexport type User = z.infer<typeof UserSchema>\n\nHow do you check if BookLib has documentation for this version of zod?\nWhat happens if zod@3.25 is a post-training library?",
+      "expectations": [
+        "Should mention the verify tool",
+        "Should explain verify checks if imports are in the BookLib index",
+        "Should note that zod@3.25 may be post-training",
+        "Should suggest running booklib verify on the file",
+        "Should mention that verify also runs automatically via hooks"
+      ]
+    }
+  ]
+}

package/skills/booklib-mcp-guide/examples/after.md

@@ -0,0 +1,34 @@
+# After: Agent calls BookLib lookup before writing code
+
+The agent calls lookup("supabase auth session") and gets the current v2.95 API.
+It then writes code using the correct patterns.
+
+```typescript
+import { createClient } from '@supabase/supabase-js'
+
+const supabase = createClient(url, key, {
+  auth: {
+    autoRefreshToken: true,
+    persistSession: true,
+  },
+})
+
+// Correct: v2.95 session pattern
+const { data: { session } } = await supabase.auth.getSession()
+
+// Correct: v2 sign-in with password
+const { data, error } = await supabase.auth.signInWithPassword({
+  email: 'user@example.com',
+  password: 'password123',
+})
+
+// Correct: v2 realtime channel pattern
+const channel = supabase
+  .channel('messages')
+  .on('postgres_changes', { event: 'INSERT', schema: 'public' }, payload => {
+    console.log(payload)
+  })
+  .subscribe()
+```
+
+The agent used current APIs because BookLib injected the correct knowledge.

package/skills/booklib-mcp-guide/examples/before.md

@@ -0,0 +1,27 @@
+# Before: Agent writes code without checking BookLib for post-training knowledge
+
+The agent is asked to create a Supabase auth flow. Without calling the BookLib
+lookup tool, it uses patterns from its training data which are outdated.
+
+```typescript
+import { createClient } from '@supabase/supabase-js'
+
+const supabase = createClient(url, key)
+
+// Wrong: uses deprecated v1 auth pattern
+const { data, error } = await supabase.auth.session()
+
+// Wrong: old sign-in method
+const { user, error: signInError } = await supabase.auth.signIn({
+  email: 'user@example.com',
+  password: 'password123',
+})
+
+// Wrong: old subscription pattern  
+const subscription = supabase
+  .from('messages')
+  .on('INSERT', payload => console.log(payload))
+  .subscribe()
+```
+
+The code compiles but uses deprecated APIs that will fail at runtime.

package/skills/booklib-mcp-guide/references/tool-catalog.md

@@ -0,0 +1,9 @@
+# BookLib MCP Tool Catalog
+
+| Tool | Purpose | Key Parameters |
+|------|---------|---------------|
+| lookup | Search for post-training docs, team decisions, expert knowledge | query, file, limit, source |
+| review | Deep code review against a named skill | skill_name, file_path |
+| remember | Capture a team decision or insight | title, type, tags |
+| verify | Check if imports are covered by the index | file_path |
+| guard | Check if code contradicts team decisions | file_path |