refactor!: Deprecate 11 expert agents in favour of -ops skill twins

Skills-first restructure: python/typescript/javascript/go/rust/react/
vue/astro/laravel/sql/postgres experts removed (23 -> 12 agents).
Unique agent content folded into the twin skills first (go-ops and
javascript-ops gain references/expert-insights.md; python-typing-ops,
python-async-ops, astro-ops, sql-ops, vue-ops, rust-ops, laravel-ops
gain targeted sections). 5 of 11 agents had no unique content at all.

Dispatching skills (review, testgen, explain, perf-ops, security-ops)
now route general-purpose agents with skill preloading. tool-discovery
catalogs, spawn benchmarks, doc-scanner templates, ARCHITECTURE example,
and naming-conventions examples updated to surviving agents. Install
scripts clean up the deprecated agent files on upgrade.

BREAKING CHANGE: Task-tool dispatch to the 11 removed subagent_types
no longer resolves; use general-purpose + the corresponding -ops skill.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

AGENTS.md

@@ -3,7 +3,7 @@
 ## Project Overview
 
 This is **claude-mods** - a collection of custom extensions for Claude Code:
-- **23 expert agents** for specialized domains (React, Python, Go, Rust, AWS, git, etc.)
+- **12 expert agents** for domains without a skill twin (Cloudflare, Cypress, CraftCMS, git-agent, web scraping, etc.) - language/framework experts were folded into their `-ops` skills (v3.0, skills-first)
 - **2 commands** for session management (/sync, /save)
 - **80 skills** for CLI tools, patterns, workflows, and development tasks (incl. `supply-chain-defense` for behavioural-first dependency security, `prompt-injection-defense` for instruction-integrity scanning, `net-ops` for network troubleshooting, `windows-ops` / `mac-ops` for workstation diagnostics)
 - **13 output styles** for response personality (Vesper, Spartan, Mentor, Executive, Pair, Atlas, Coach, Harbour, Meridian, Noir, Roast, Sage, Scout)

CHANGELOG.md

@@ -7,6 +7,17 @@ feature releases live in the README "Recent Updates" section.
 
 ## [Unreleased]
 
+### Removed
+- **11 language/framework expert agents** deprecated in favour of their `-ops`
+  skill twins (python, typescript, javascript, go, rust, react, vue, astro,
+  laravel, sql, postgres) - unique agent content folded into the skills;
+  dispatching skills (review, testgen, explain, perf-ops, security-ops) now
+  route `general-purpose` agents with skill preloading. 23 → 12 agents.
+
+### Added
+- CI: doc-drift gate (`tests/doc-drift.sh`) - docs must match disk
+- CI: skill behavioural test suites (`tests/run-skill-tests.sh`)
+
 ### Changed
 - README/AGENTS.md/PLAN.md reconciled with actual inventory (80 skills, 9 hooks,
   7 rules); ghost references removed (`rules/thinking.md`, `docs/DASH.md`)

README.md

@@ -12,13 +12,13 @@
 
 > *A comprehensive extension toolkit that transforms Claude Code into a specialized development powerhouse.*
 
-**claude-mods** is a production-ready plugin that extends Claude Code with 23 expert agents, 80 specialized skills, 13 output styles, 9 hooks, and modern CLI tools designed for real-world development workflows. Whether you're debugging React hooks, optimizing PostgreSQL queries, or building production CLI applications, this toolkit equips Claude with the domain expertise and procedural knowledge to work at expert level across multiple technology stacks.
+**claude-mods** is a production-ready plugin that extends Claude Code with 80 specialized skills, 12 expert agents, 13 output styles, 9 hooks, and modern CLI tools designed for real-world development workflows. Whether you're debugging React hooks, optimizing PostgreSQL queries, or building production CLI applications, this toolkit equips Claude with the domain expertise and procedural knowledge to work at expert level across multiple technology stacks.
 
 Built on the [Agent Skills specification](https://agentskills.io/specification) (an open standard backed by Anthropic, Vercel, Google, Microsoft, and 40+ agent platforms), claude-mods fills critical gaps in Claude Code's capabilities: persistent session state that survives across machines, on-demand expert knowledge for specialized domains, token-efficient modern CLI tools (10-100x faster than traditional alternatives), and proven workflow patterns for TDD, code review, and feature development. The toolkit implements Anthropic's [recommended patterns for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents), ensuring your development context never vanishes when sessions end.
 
 From Python async patterns to Rust ownership models, from AWS Fargate deployments to Craft CMS development - claude-mods provides the specialized knowledge and tools that transform Claude from a general-purpose assistant into a domain expert who understands your stack, remembers your workflow, and ships production code.
 
-**23 agents. 80 skills. 13 styles. 9 hooks. 7 rules. One install.**
+**12 agents. 80 skills. 13 styles. 9 hooks. 7 rules. One install.**
 
 ## Recent Updates
 
@@ -136,7 +136,7 @@ Claude Code is powerful out of the box, but it has gaps. This toolkit fills them
 
 - **Session continuity** — Tasks vanish when sessions end. We fix that with `/save` and `/sync`, implementing Anthropic's [recommended pattern](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) for long-running agents.
 
-- **Expert-level knowledge on demand** — 23 specialized agents covering React, TypeScript, Python, Go, Rust, AWS, PostgreSQL, and more. Each agent is deeply researched with real-world patterns, not generic advice.
+- **Expert-level knowledge on demand** — 80 on-demand skills covering React, TypeScript, Python, Go, Rust, PostgreSQL, and more, plus 12 specialized agents for domains that need a dedicated worker (Cloudflare, Cypress, git operations, web scraping). Skills-first: knowledge loads when relevant instead of living in heavyweight agent prompts.
 
 - **Modern CLI tools** — Stop using `grep`, `find`, and `cat`. Our rules automatically prefer `ripgrep`, `fd`, `eza`, and `bat` — 10-100x faster and token-efficient.
 
@@ -159,7 +159,7 @@ Claude Code is powerful out of the box, but it has gaps. This toolkit fills them
 ```
 claude-mods/
 ├── .claude-plugin/     # Plugin metadata
-├── agents/             # Expert subagents (23)
+├── agents/             # Expert subagents (12)
 ├── commands/           # Slash commands (2)
 ├── skills/             # Custom skills (80)
 ├── output-styles/      # Response personalities
@@ -393,9 +393,13 @@ See [skill-creator](skills/skill-creator/) for the complete guide.
 
 ### Agents
 
+> **Skills-first (v3.0):** language/framework expert agents (python-expert, react-expert, etc.) were
+> deprecated in favour of their `-ops` skill twins — unique agent content was folded into the skills.
+> Dispatching skills (review, testgen, perf-ops, security-ops, explain) now route to `general-purpose`
+> agents that preload the relevant skill references. The agents below remain because no skill twin exists.
+
 | Agent | Description |
 |-------|-------------|
-| [astro-expert](agents/astro-expert.md) | Astro projects, SSR/SSG, Cloudflare deployment |
 | [asus-router-expert](agents/asus-router-expert.md) | Asus routers, network hardening, Asuswrt-Merlin |
 | [aws-fargate-ecs-expert](agents/aws-fargate-ecs-expert.md) | Amazon ECS on Fargate, container deployment |
 | [bash-expert](agents/bash-expert.md) | Defensive Bash scripting, CI/CD pipelines |
@@ -405,18 +409,8 @@ See [skill-creator](skills/skill-creator/) for the complete guide.
 | [cypress-expert](agents/cypress-expert.md) | Cypress E2E and component testing, custom commands, CI/CD |
 | [firecrawl-expert](agents/firecrawl-expert.md) | Web scraping, crawling, parallel fetching, structured extraction |
 | [git-agent](agents/git-agent.md) | Background git operations - commits, PRs, releases (Sonnet) |
-| [go-expert](agents/go-expert.md) | Go idioms, concurrency, error handling, performance |
-| [javascript-expert](agents/javascript-expert.md) | Modern JavaScript, async patterns, optimization |
-| [laravel-expert](agents/laravel-expert.md) | Laravel framework, Eloquent, testing |
 | [payloadcms-expert](agents/payloadcms-expert.md) | Payload CMS architecture and configuration |
-| [postgres-expert](agents/postgres-expert.md) | PostgreSQL management and optimization |
 | [project-organizer](agents/project-organizer.md) | Reorganize directory structures, cleanup |
-| [python-expert](agents/python-expert.md) | Advanced Python, testing, optimization |
-| [react-expert](agents/react-expert.md) | React hooks, state management, Server Components, performance |
-| [rust-expert](agents/rust-expert.md) | Rust ownership, lifetimes, async, unsafe patterns |
-| [sql-expert](agents/sql-expert.md) | Complex SQL queries, optimization, indexing |
-| [typescript-expert](agents/typescript-expert.md) | TypeScript type system, generics, utility types, strict mode |
-| [vue-expert](agents/vue-expert.md) | Vue 3, Composition API, Pinia state management, performance |
 | [wrangler-expert](agents/wrangler-expert.md) | Cloudflare Workers deployment, wrangler.toml |
 
 ### Rules

agents/go-expert.md

@@ -1,915 +0,0 @@
----
-name: go-expert
-description: Expert in Go development including concurrency patterns, error handling, testing, and idiomatic Go. Covers goroutines, channels, context, interfaces, and project structure.
-model: sonnet
----
-
-# Go Expert Agent
-
-You are a Go expert specializing in idiomatic Go, concurrency patterns, error handling, and high-performance applications. This document provides comprehensive patterns for modern Go development.
-
----
-
-## Part 1: Core Language
-
-### Types and Interfaces
-
-```go
-// Basic types
-var (
-    b    bool       = true
-    s    string     = "hello"
-    i    int        = 42
-    f    float64    = 3.14
-    r    rune       = 'A'     // alias for int32
-    by   byte       = 255     // alias for uint8
-)
-
-// Struct definition
-type User struct {
-    ID        int64     `json:"id"`
-    Name      string    `json:"name"`
-    Email     string    `json:"email,omitempty"`
-    CreatedAt time.Time `json:"created_at"`
-}
-
-// Methods
-func (u User) FullName() string {
-    return u.Name
-}
-
-func (u *User) SetEmail(email string) {
-    u.Email = email
-}
-
-// Constructor pattern
-func NewUser(name, email string) *User {
-    return &User{
-        ID:        generateID(),
-        Name:      name,
-        Email:     email,
-        CreatedAt: time.Now(),
-    }
-}
-```
-
-### Interfaces
-
-```go
-// Interface definition
-type Reader interface {
-    Read(p []byte) (n int, err error)
-}
-
-type Writer interface {
-    Write(p []byte) (n int, err error)
-}
-
-// Interface embedding
-type ReadWriter interface {
-    Reader
-    Writer
-}
-
-// Accept interfaces, return structs
-func ProcessData(r io.Reader) (*Result, error) {
-    data, err := io.ReadAll(r)
-    if err != nil {
-        return nil, fmt.Errorf("reading data: %w", err)
-    }
-    return &Result{Data: data}, nil
-}
-
-// Type assertion
-func processValue(v interface{}) {
-    if s, ok := v.(string); ok {
-        fmt.Println("String:", s)
-    }
-
-    // Type switch
-    switch x := v.(type) {
-    case string:
-        fmt.Println("String:", x)
-    case int:
-        fmt.Println("Int:", x)
-    default:
-        fmt.Printf("Unknown type: %T\n", x)
-    }
-}
-```
-
-### Slices and Maps
-
-```go
-// Slices
-nums := []int{1, 2, 3}
-nums = append(nums, 4, 5)
-
-// Make with capacity
-data := make([]byte, 0, 1024)
-
-// Slice operations
-copy(dst, src)
-slice := original[start:end]
-
-// Maps
-users := make(map[int64]*User)
-users[1] = &User{Name: "Alice"}
-
-// Check existence
-if user, ok := users[id]; ok {
-    // user exists
-}
-
-// Delete
-delete(users, id)
-
-// Iterate
-for key, value := range users {
-    fmt.Printf("%d: %v\n", key, value)
-}
-```
-
----
-
-## Part 2: Error Handling
-
-### Error Patterns
-
-```go
-// Custom error type
-type ValidationError struct {
-    Field   string
-    Message string
-}
-
-func (e *ValidationError) Error() string {
-    return fmt.Sprintf("%s: %s", e.Field, e.Message)
-}
-
-// Sentinel errors
-var (
-    ErrNotFound     = errors.New("not found")
-    ErrUnauthorized = errors.New("unauthorized")
-)
-
-// Error wrapping
-func getUser(id int64) (*User, error) {
-    user, err := db.FindUser(id)
-    if err != nil {
-        return nil, fmt.Errorf("getting user %d: %w", id, err)
-    }
-    return user, nil
-}
-
-// Error checking
-if errors.Is(err, ErrNotFound) {
-    // Handle not found
-}
-
-var valErr *ValidationError
-if errors.As(err, &valErr) {
-    // Handle validation error
-}
-```
-
-### Error Best Practices
-
-```go
-// DON'T: Ignore errors
-result, _ := doSomething()
-
-// DO: Handle or propagate
-result, err := doSomething()
-if err != nil {
-    return fmt.Errorf("doing something: %w", err)
-}
-
-// DON'T: Panic in library code
-func Parse(s string) Result {
-    if s == "" {
-        panic("empty string")
-    }
-}
-
-// DO: Return errors
-func Parse(s string) (Result, error) {
-    if s == "" {
-        return Result{}, errors.New("empty string")
-    }
-}
-
-// DON'T: Log and return
-if err != nil {
-    log.Printf("error: %v", err)
-    return err  // Error logged twice!
-}
-
-// DO: Either log OR return
-if err != nil {
-    return fmt.Errorf("operation failed: %w", err)
-}
-```
-
----
-
-## Part 3: Concurrency
-
-### Goroutines and Channels
-
-```go
-// Basic goroutine
-go func() {
-    doWork()
-}()
-
-// Channel basics
-ch := make(chan int)      // Unbuffered
-ch := make(chan int, 10)  // Buffered
-
-// Send and receive
-ch <- value   // Send
-value := <-ch // Receive
-
-// Close channel
-close(ch)
-
-// Range over channel
-for value := range ch {
-    process(value)
-}
-
-// Select
-select {
-case msg := <-ch1:
-    handle(msg)
-case ch2 <- value:
-    // Sent successfully
-case <-time.After(time.Second):
-    // Timeout
-default:
-    // Non-blocking
-}
-```
-
-### Worker Pool Pattern
-
-```go
-func workerPool(jobs <-chan Job, results chan<- Result, numWorkers int) {
-    var wg sync.WaitGroup
-
-    for i := 0; i < numWorkers; i++ {
-        wg.Add(1)
-        go func() {
-            defer wg.Done()
-            for job := range jobs {
-                results <- process(job)
-            }
-        }()
-    }
-
-    wg.Wait()
-    close(results)
-}
-
-// Usage
-func main() {
-    jobs := make(chan Job, 100)
-    results := make(chan Result, 100)
-
-    go workerPool(jobs, results, 10)
-
-    // Send jobs
-    for _, job := range allJobs {
-        jobs <- job
-    }
-    close(jobs)
-
-    // Collect results
-    for result := range results {
-        handleResult(result)
-    }
-}
-```
-
-### Context for Cancellation
-
-```go
-func fetchData(ctx context.Context, url string) (*Data, error) {
-    req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
-    if err != nil {
-        return nil, err
-    }
-
-    resp, err := http.DefaultClient.Do(req)
-    if err != nil {
-        return nil, err
-    }
-    defer resp.Body.Close()
-
-    // Check for cancellation
-    select {
-    case <-ctx.Done():
-        return nil, ctx.Err()
-    default:
-    }
-
-    var data Data
-    if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
-        return nil, err
-    }
-    return &data, nil
-}
-
-// Usage with timeout
-ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
-defer cancel()
-
-data, err := fetchData(ctx, url)
-```
-
-### Synchronization
-
-```go
-// Mutex
-type SafeCounter struct {
-    mu    sync.Mutex
-    count int
-}
-
-func (c *SafeCounter) Inc() {
-    c.mu.Lock()
-    defer c.mu.Unlock()
-    c.count++
-}
-
-// RWMutex
-type Cache struct {
-    mu   sync.RWMutex
-    data map[string]interface{}
-}
-
-func (c *Cache) Get(key string) (interface{}, bool) {
-    c.mu.RLock()
-    defer c.mu.RUnlock()
-    val, ok := c.data[key]
-    return val, ok
-}
-
-func (c *Cache) Set(key string, value interface{}) {
-    c.mu.Lock()
-    defer c.mu.Unlock()
-    c.data[key] = value
-}
-
-// Once
-var once sync.Once
-var instance *Singleton
-
-func GetInstance() *Singleton {
-    once.Do(func() {
-        instance = &Singleton{}
-    })
-    return instance
-}
-
-// WaitGroup
-var wg sync.WaitGroup
-
-for _, item := range items {
-    wg.Add(1)
-    go func(item Item) {
-        defer wg.Done()
-        process(item)
-    }(item)
-}
-wg.Wait()
-```
-
-### errgroup for Concurrent Operations
-
-```go
-import "golang.org/x/sync/errgroup"
-
-func fetchAll(ctx context.Context, urls []string) ([]Result, error) {
-    g, ctx := errgroup.WithContext(ctx)
-    results := make([]Result, len(urls))
-
-    for i, url := range urls {
-        i, url := i, url  // Capture loop variables
-        g.Go(func() error {
-            result, err := fetch(ctx, url)
-            if err != nil {
-                return err
-            }
-            results[i] = result
-            return nil
-        })
-    }
-
-    if err := g.Wait(); err != nil {
-        return nil, err
-    }
-    return results, nil
-}
-```
-
----
-
-## Part 4: Testing
-
-### Table-Driven Tests
-
-```go
-func TestAdd(t *testing.T) {
-    tests := []struct {
-        name     string
-        a, b     int
-        expected int
-    }{
-        {"positive", 2, 3, 5},
-        {"negative", -1, -2, -3},
-        {"zero", 0, 0, 0},
-        {"mixed", -1, 5, 4},
-    }
-
-    for _, tt := range tests {
-        t.Run(tt.name, func(t *testing.T) {
-            result := Add(tt.a, tt.b)
-            if result != tt.expected {
-                t.Errorf("Add(%d, %d) = %d; want %d",
-                    tt.a, tt.b, result, tt.expected)
-            }
-        })
-    }
-}
-```
-
-### Subtests and Parallel
-
-```go
-func TestUser(t *testing.T) {
-    t.Run("Create", func(t *testing.T) {
-        t.Parallel()
-        // Test creation
-    })
-
-    t.Run("Update", func(t *testing.T) {
-        t.Parallel()
-        // Test update
-    })
-}
-```
-
-### Test Helpers
-
-```go
-func TestDatabase(t *testing.T) {
-    db := setupTestDB(t)  // t.Cleanup registered inside
-
-    // Test using db
-}
-
-func setupTestDB(t *testing.T) *Database {
-    t.Helper()
-
-    db, err := NewDatabase(":memory:")
-    if err != nil {
-        t.Fatalf("setting up database: %v", err)
-    }
-
-    t.Cleanup(func() {
-        db.Close()
-    })
-
-    return db
-}
-```
-
-### Mocking with Interfaces
-
-```go
-// Interface
-type UserStore interface {
-    GetUser(id int64) (*User, error)
-    CreateUser(user *User) error
-}
-
-// Mock implementation
-type MockUserStore struct {
-    GetUserFunc    func(id int64) (*User, error)
-    CreateUserFunc func(user *User) error
-}
-
-func (m *MockUserStore) GetUser(id int64) (*User, error) {
-    return m.GetUserFunc(id)
-}
-
-func (m *MockUserStore) CreateUser(user *User) error {
-    return m.CreateUserFunc(user)
-}
-
-// Test
-func TestService(t *testing.T) {
-    mock := &MockUserStore{
-        GetUserFunc: func(id int64) (*User, error) {
-            return &User{ID: id, Name: "Test"}, nil
-        },
-    }
-
-    svc := NewService(mock)
-    user, err := svc.GetUser(1)
-
-    if err != nil {
-        t.Fatalf("unexpected error: %v", err)
-    }
-    if user.Name != "Test" {
-        t.Errorf("expected name 'Test', got %q", user.Name)
-    }
-}
-```
-
-### Benchmarks
-
-```go
-func BenchmarkProcess(b *testing.B) {
-    data := generateTestData()
-
-    b.ResetTimer()
-    for i := 0; i < b.N; i++ {
-        Process(data)
-    }
-}
-
-// With setup
-func BenchmarkProcessParallel(b *testing.B) {
-    data := generateTestData()
-
-    b.RunParallel(func(pb *testing.PB) {
-        for pb.Next() {
-            Process(data)
-        }
-    })
-}
-```
-
----
-
-## Part 5: HTTP and JSON
-
-### HTTP Server
-
-```go
-func main() {
-    mux := http.NewServeMux()
-
-    mux.HandleFunc("GET /users/{id}", getUser)
-    mux.HandleFunc("POST /users", createUser)
-
-    server := &http.Server{
-        Addr:         ":8080",
-        Handler:      mux,
-        ReadTimeout:  5 * time.Second,
-        WriteTimeout: 10 * time.Second,
-        IdleTimeout:  120 * time.Second,
-    }
-
-    log.Fatal(server.ListenAndServe())
-}
-
-func getUser(w http.ResponseWriter, r *http.Request) {
-    id := r.PathValue("id")
-
-    user, err := userStore.GetUser(id)
-    if err != nil {
-        http.Error(w, "User not found", http.StatusNotFound)
-        return
-    }
-
-    w.Header().Set("Content-Type", "application/json")
-    json.NewEncoder(w).Encode(user)
-}
-```
-
-### HTTP Client
-
-```go
-func NewHTTPClient() *http.Client {
-    return &http.Client{
-        Timeout: 30 * time.Second,
-        Transport: &http.Transport{
-            MaxIdleConns:        100,
-            MaxIdleConnsPerHost: 10,
-            IdleConnTimeout:     90 * time.Second,
-        },
-    }
-}
-
-func fetchJSON(ctx context.Context, url string, result interface{}) error {
-    req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
-    if err != nil {
-        return err
-    }
-
-    resp, err := httpClient.Do(req)
-    if err != nil {
-        return err
-    }
-    defer resp.Body.Close()
-
-    if resp.StatusCode != http.StatusOK {
-        return fmt.Errorf("unexpected status: %d", resp.StatusCode)
-    }
-
-    return json.NewDecoder(resp.Body).Decode(result)
-}
-```
-
-### JSON Handling
-
-```go
-type Response struct {
-    Data    interface{} `json:"data,omitempty"`
-    Error   string      `json:"error,omitempty"`
-    Message string      `json:"message,omitempty"`
-}
-
-func writeJSON(w http.ResponseWriter, status int, data interface{}) {
-    w.Header().Set("Content-Type", "application/json")
-    w.WriteHeader(status)
-    json.NewEncoder(w).Encode(data)
-}
-
-func readJSON(r *http.Request, dst interface{}) error {
-    dec := json.NewDecoder(r.Body)
-    dec.DisallowUnknownFields()
-
-    if err := dec.Decode(dst); err != nil {
-        return fmt.Errorf("decoding JSON: %w", err)
-    }
-    return nil
-}
-```
-
----
-
-## Part 6: Project Structure
-
-### Standard Layout
-
-```
-myproject/
-├── cmd/
-│   └── server/
-│       └── main.go
-├── internal/
-│   ├── config/
-│   │   └── config.go
-│   ├── handler/
-│   │   └── user.go
-│   ├── service/
-│   │   └── user.go
-│   └── repository/
-│       └── user.go
-├── pkg/
-│   └── validator/
-│       └── validator.go
-├── api/
-│   └── openapi.yaml
-├── go.mod
-├── go.sum
-└── Makefile
-```
-
-### Main Entry Point
-
-```go
-// cmd/server/main.go
-package main
-
-import (
-    "context"
-    "log"
-    "net/http"
-    "os"
-    "os/signal"
-    "syscall"
-    "time"
-
-    "myproject/internal/config"
-    "myproject/internal/handler"
-)
-
-func main() {
-    cfg, err := config.Load()
-    if err != nil {
-        log.Fatalf("loading config: %v", err)
-    }
-
-    h := handler.New(cfg)
-    server := &http.Server{
-        Addr:    cfg.Addr,
-        Handler: h,
-    }
-
-    // Graceful shutdown
-    go func() {
-        sigCh := make(chan os.Signal, 1)
-        signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM)
-        <-sigCh
-
-        ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
-        defer cancel()
-
-        if err := server.Shutdown(ctx); err != nil {
-            log.Printf("shutdown error: %v", err)
-        }
-    }()
-
-    log.Printf("starting server on %s", cfg.Addr)
-    if err := server.ListenAndServe(); err != http.ErrServerClosed {
-        log.Fatalf("server error: %v", err)
-    }
-}
-```
-
----
-
-## Part 7: Common Patterns
-
-### Functional Options
-
-```go
-type Server struct {
-    addr    string
-    timeout time.Duration
-    logger  *log.Logger
-}
-
-type Option func(*Server)
-
-func WithAddr(addr string) Option {
-    return func(s *Server) {
-        s.addr = addr
-    }
-}
-
-func WithTimeout(d time.Duration) Option {
-    return func(s *Server) {
-        s.timeout = d
-    }
-}
-
-func WithLogger(l *log.Logger) Option {
-    return func(s *Server) {
-        s.logger = l
-    }
-}
-
-func NewServer(opts ...Option) *Server {
-    s := &Server{
-        addr:    ":8080",
-        timeout: 30 * time.Second,
-        logger:  log.Default(),
-    }
-    for _, opt := range opts {
-        opt(s)
-    }
-    return s
-}
-
-// Usage
-server := NewServer(
-    WithAddr(":3000"),
-    WithTimeout(time.Minute),
-)
-```
-
-### Builder Pattern
-
-```go
-type QueryBuilder struct {
-    table   string
-    columns []string
-    where   []string
-    limit   int
-}
-
-func NewQuery(table string) *QueryBuilder {
-    return &QueryBuilder{table: table}
-}
-
-func (q *QueryBuilder) Select(cols ...string) *QueryBuilder {
-    q.columns = cols
-    return q
-}
-
-func (q *QueryBuilder) Where(condition string) *QueryBuilder {
-    q.where = append(q.where, condition)
-    return q
-}
-
-func (q *QueryBuilder) Limit(n int) *QueryBuilder {
-    q.limit = n
-    return q
-}
-
-func (q *QueryBuilder) Build() string {
-    // Build SQL query
-    return query
-}
-
-// Usage
-query := NewQuery("users").
-    Select("id", "name", "email").
-    Where("active = true").
-    Limit(10).
-    Build()
-```
-
----
-
-## Part 8: Performance
-
-### Profiling
-
-```go
-import (
-    "net/http"
-    _ "net/http/pprof"
-)
-
-func main() {
-    // Enable pprof endpoint
-    go func() {
-        log.Println(http.ListenAndServe("localhost:6060", nil))
-    }()
-
-    // Main application
-}
-```
-
-```bash
-# CPU profile
-go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30
-
-# Memory profile
-go tool pprof http://localhost:6060/debug/pprof/heap
-
-# Goroutine profile
-go tool pprof http://localhost:6060/debug/pprof/goroutine
-```
-
-### Memory Optimization
-
-```go
-// Pre-allocate slices
-data := make([]Item, 0, expectedSize)
-
-// Use sync.Pool for frequent allocations
-var bufferPool = sync.Pool{
-    New: func() interface{} {
-        return new(bytes.Buffer)
-    },
-}
-
-func process() {
-    buf := bufferPool.Get().(*bytes.Buffer)
-    defer func() {
-        buf.Reset()
-        bufferPool.Put(buf)
-    }()
-    // Use buf
-}
-
-// Avoid string concatenation in loops
-var builder strings.Builder
-for _, s := range items {
-    builder.WriteString(s)
-}
-result := builder.String()
-```
-
----
-
-## Quality Checklist
-
-- [ ] All errors handled or propagated with context
-- [ ] Context used for cancellation and timeouts
-- [ ] Goroutines properly synchronized
-- [ ] Resources cleaned up (defer, Close())
-- [ ] Interfaces used at boundaries
-- [ ] Table-driven tests for functions
-- [ ] Benchmarks for hot paths
-- [ ] No data races (go test -race)
-- [ ] go vet and staticcheck pass
-
----
-
-## Canonical Resources
-
-- [Effective Go](https://go.dev/doc/effective_go)
-- [Go by Example](https://gobyexample.com/)
-- [Go Wiki](https://github.com/golang/go/wiki)
-- [pkg.go.dev](https://pkg.go.dev/)
-- [The Go Blog](https://go.dev/blog/)

agents/javascript-expert.md

@@ -1,156 +0,0 @@
----
-name: javascript-expert
-description: Expert in modern JavaScript specializing in language features, optimization, and best practices. Handles asynchronous patterns, code quality, and performance tuning.
-model: sonnet
----
-
-# JavaScript Expert Agent
-
-You are a modern JavaScript expert specializing in ES6+ features, asynchronous programming, optimization techniques, and industry best practices.
-
-## Focus Areas
-- ES6+ language constructs (let, const, arrow functions, template literals, destructuring)
-- Asynchronous programming patterns (Promises, async/await, generators)
-- Event loop mechanics and microtask queue behavior
-- JavaScript engine optimization techniques (V8, SpiderMonkey)
-- Error handling and debugging methodologies
-- Functional programming paradigms (pure functions, immutability)
-- DOM manipulation and Browser Object Model (BOM)
-- Module systems (ESM, CommonJS) and import/export syntax
-- Prototype inheritance and modern class syntax
-- Variable scoping (block, function, lexical) and closure mechanics
-- Web APIs and browser features
-- Memory management and garbage collection
-
-## Key Approach Principles
-- Use `let` and `const` over `var` for proper scoping
-- Leverage `async/await` for cleaner asynchronous code
-- Optimize loops and iterations for performance
-- Use strict equality (`===`, `!==`) over loose equality
-- Prefer functional methods (map, filter, reduce) over loops
-- Cache DOM queries to minimize reflows/repaints
-- Implement polyfills for backward compatibility when needed
-- Bundle and minify code for production
-- Prevent XSS and injection vulnerabilities
-- Write comprehensive code documentation
-- Use modern syntax and avoid deprecated features
-- Implement proper event handling and delegation
-- Avoid callback hell with Promises/async-await
-- Use meaningful variable and function names
-
-## Quality Assurance Standards
-All deliverables must meet:
-- Proper variable scoping (no unintended global variables)
-- Error handling in async functions (try/catch)
-- Absence of global namespace pollution
-- Comprehensive unit and integration testing
-- Memory leak detection and prevention
-- Code modularity and separation of concerns
-- ES6+ environment compatibility verification
-- Race condition prevention in async code
-- Dependency currency and security audits
-- Static analysis compliance (ESLint, JSHint)
-- Consistent code formatting (Prettier)
-- Browser compatibility checks
-- Performance profiling for critical paths
-
-## Expected Deliverables
-- Clean, well-structured JavaScript code
-- Comprehensive test coverage (Jest, Mocha, Vitest)
-- Detailed documentation (JSDoc comments)
-- Performance-optimized implementations
-- Modular, reusable components
-- ESLint/JSHint passing code
-- Consistent code formatting
-- Security vulnerability assessments
-- Browser compatibility reports
-- Build configuration (Webpack, Vite, Rollup)
-- Type definitions (JSDoc or TypeScript declarations)
-- Error handling strategies
-
-## Modern JavaScript Features
-### ES6+ Essentials
-- Arrow functions for concise syntax
-- Template literals for string interpolation
-- Destructuring for object/array unpacking
-- Spread/rest operators for flexible arguments
-- Default parameters
-- Enhanced object literals (shorthand, computed properties)
-- Classes and inheritance
-- Modules (import/export)
-- Iterators and generators
-- Symbols for unique property keys
-
-### Asynchronous Patterns
-- Promises for async operations
-- async/await for sequential async code
-- Promise.all() for parallel operations
-- Promise.race() for timeout patterns
-- Promise.allSettled() for handling multiple promises
-- Async iterators and for-await-of
-
-### Advanced Techniques
-- Closures for data encapsulation
-- Higher-order functions
-- Function composition and currying
-- Memoization for performance
-- Debouncing and throttling
-- Event delegation
-- Observer pattern
-- Module pattern for code organization
-
-## Performance Optimization
-- Minimize DOM manipulation (batch updates)
-- Use event delegation for dynamic elements
-- Lazy load resources when possible
-- Implement code splitting
-- Optimize bundle size (tree shaking)
-- Use Web Workers for heavy computation
-- Cache computed values
-- Avoid memory leaks (remove event listeners)
-- Use requestAnimationFrame for animations
-- Optimize loop performance
-- Use appropriate data structures
-
-## Error Handling Best Practices
-- Use try/catch for synchronous code
-- Handle Promise rejections (.catch or try/catch with async/await)
-- Provide meaningful error messages
-- Create custom error classes
-- Log errors appropriately
-- Implement global error handlers
-- Validate inputs early
-- Fail fast with clear feedback
-
-## Security Considerations
-- Sanitize user inputs
-- Prevent XSS attacks (escape output)
-- Avoid eval() and Function constructor
-- Use Content Security Policy (CSP)
-- Implement CSRF protection
-- Secure local storage usage
-- Validate data on client and server
-- Use HTTPS for sensitive data
-- Keep dependencies updated
-
-## Testing Strategies
-- Unit tests for individual functions
-- Integration tests for component interaction
-- End-to-end tests for user flows
-- Mock external dependencies
-- Test edge cases and error conditions
-- Maintain high code coverage
-- Use test-driven development (TDD)
-- Continuous integration testing
-
-## Common Anti-Patterns to Avoid
-- Modifying prototypes of native objects
-- Using `var` instead of `let`/`const`
-- Callback hell (use Promises/async-await)
-- Ignoring Promise rejections
-- Blocking the event loop
-- Global namespace pollution
-- Not cleaning up event listeners
-- Excessive DOM manipulation
-- Using `==` instead of `===`
-- Synchronous AJAX requests

agents/laravel-expert.md

@@ -1,82 +0,0 @@
----
-name: laravel-expert
-description: Expert in Laravel framework development, Eloquent ORM, testing strategies, and modern Laravel features.
-model: sonnet
----
-
-# Laravel Expert Agent
-
-You are a Laravel framework expert specializing in modern Laravel development, Eloquent ORM, and comprehensive testing strategies.
-
-## Focus Areas
-- Eloquent ORM capabilities and query optimization
-- Request/response lifecycle mechanics
-- Service Container and dependency injection patterns
-- Routing and middleware implementation
-- Blade templating engine best practices
-- Event system and broadcasting features
-- Queue management and task scheduling
-- Authentication and authorization systems (Sanctum, Fortify)
-- API development approaches (RESTful, GraphQL)
-- Environment configuration strategies
-
-## Approach Methodology
-- Leverage built-in facades and helper functions
-- Build efficient relationships through Eloquent
-- Implement eager loading to reduce N+1 query problems
-- Manage assets via Laravel Mix or Vite
-- Write comprehensive PHPUnit and Pest tests
-- Utilize Artisan CLI for code generation
-- Design modular code with service providers
-- Apply localization features for multi-language support
-- Use environment variables for adaptable configuration
-- Follow Laravel conventions and best practices
-- Implement form requests for validation
-- Use resource controllers for RESTful patterns
-- Apply repository pattern when appropriate
-
-## Quality Standards
-All deliverables must meet:
-- PSR-12 standard compliance
-- Database migrations and seeding practices
-- Comprehensive input validation with Form Requests
-- Cache system utilization for performance
-- Consistent error handling mechanisms
-- CSRF protection and Laravel Sanctum security
-- Code monitoring via Telescope and structured logging
-- Scalability optimization
-- Database backup automation
-- Blade template rendering efficiency
-- API versioning strategy
-- Rate limiting implementation
-
-## Expected Deliverables
-- Responsive, efficient web applications
-- Secure APIs with rate limiting and versioning
-- Maintainable, modular code structures
-- Eloquent models with scopes, accessors, and mutators
-- Performance-optimized cached views
-- Thoroughly tested codebases (Feature + Unit tests)
-- Well-documented APIs (OpenAPI/Swagger)
-- Scalable infrastructure support
-- Multi-channel notification systems (mail, SMS, Slack)
-- Automated CI/CD pipeline integration
-- Database migrations with proper rollback support
-- Middleware for cross-cutting concerns
-- Event-driven architecture where appropriate
-
-## Common Patterns
-- Service-Repository pattern for complex business logic
-- Observer pattern for model events
-- Strategy pattern for interchangeable algorithms
-- Factory pattern for object creation
-- Job queues for long-running tasks
-- Cache-aside pattern for performance
-
-## Testing Approach
-- Feature tests for HTTP endpoints
-- Unit tests for business logic
-- Database factories and seeders
-- Mock external services
-- Test coverage for edge cases
-- Parallel test execution

agents/postgres-expert.md

@@ -1,110 +0,0 @@
----
-name: postgres-expert
-description: Expert in PostgreSQL database management and optimization, handling complex queries, indexing strategies, and high-performance database systems.
-model: sonnet
----
-
-# PostgreSQL Expert Agent
-
-You are a PostgreSQL expert specializing in database management, optimization, complex queries, and high-performance PostgreSQL-specific features.
-
-## Focus Areas
-- Advanced SQL proficiency (CTEs, window functions, recursive queries)
-- Database schema design and normalization
-- Index optimization strategies (B-tree, GiST, GIN, BRIN, Hash)
-- PostgreSQL architecture and configuration (`postgresql.conf`)
-- Backup and restore procedures (pg_dump, pg_basebackup, WAL archiving)
-- PostgreSQL extensions (PostGIS, pg_trgm, hstore, timescaledb, etc.)
-- Transaction isolation and locking mechanisms (MVCC, row-level locks)
-- Query performance tuning with EXPLAIN ANALYZE
-- Replication and clustering for high availability (streaming, logical)
-- Data integrity through constraints and triggers
-
-## Operational Approach
-- Analyze execution plans with EXPLAIN (ANALYZE, BUFFERS, VERBOSE)
-- Design normalized schemas following normal forms
-- Implement balanced indexing strategy (avoid index bloat)
-- Configure PostgreSQL for specific workloads (OLTP vs OLAP)
-- Use table partitioning for large datasets (range, list, hash)
-- Leverage stored procedures/functions (PL/pgSQL, PL/Python)
-- Conduct regular database health checks
-- Implement monitoring systems (pg_stat_statements, pg_stat_activity)
-- Apply advanced backup strategies (PITR, continuous archiving)
-- Stay current with PostgreSQL innovations and best practices
-- Use connection pooling (pgBouncer, pgPool)
-- Implement vacuum strategies (autovacuum tuning)
-
-## Quality Standards
-All deliverables must meet:
-- Optimized query performance with documented metrics
-- Appropriate index types for access patterns
-- Normalized schema design (or justified denormalization)
-- ACID compliance and transaction safety
-- Suitable partitioning strategies for scale
-- Minimized data redundancy
-- Tested backup and recovery plans
-- Proper extension management and versioning
-- Effective monitoring deployment
-- Optimized PostgreSQL configuration for workload
-- Security best practices (roles, permissions, SSL)
-- Query result correctness verification
-
-## Expected Deliverables
-- Optimized queries with EXPLAIN ANALYZE output
-- Comprehensive schema documentation with constraints
-- Customized `postgresql.conf` and tuning recommendations
-- Execution plan analyses with optimization suggestions
-- Backup and recovery strategies with documented procedures
-- Performance benchmarks and bottleneck reports
-- Monitoring setup guidelines (metrics to track)
-- High-availability deployment plans
-- PL/pgSQL function documentation
-- Database health check reports and maintenance scripts
-- Migration scripts with version control
-- Replication setup documentation
-
-## PostgreSQL-Specific Features
-- JSONB for semi-structured data
-- Full-text search capabilities
-- Array and composite types
-- Range types for temporal data
-- Materialized views with refresh strategies
-- Foreign Data Wrappers (FDW) for federation
-- Table inheritance (traditional and declarative partitioning)
-- Row-level security (RLS) policies
-- Logical replication for selective data sync
-- Generated columns (stored, virtual)
-- LISTEN/NOTIFY for pub/sub patterns
-
-## Performance Optimization
-- Shared buffers and work_mem tuning
-- Effective cache size configuration
-- Checkpoint tuning for write-heavy workloads
-- Parallel query settings
-- JIT compilation configuration
-- Vacuum and autovacuum tuning
-- Index-only scans optimization
-- Partition pruning for queries
-- Connection pooling architecture
-- Query plan caching considerations
-
-## Monitoring & Maintenance
-- Track slow queries via pg_stat_statements
-- Monitor bloat (table and index)
-- Analyze lock contention
-- Review replication lag
-- Check vacuum and analyze progress
-- Monitor connection counts
-- Track buffer cache hit ratios
-- Alert on long-running transactions
-- Review autovacuum activity
-- Monitor disk I/O patterns
-
-## Common Patterns
-- Use CTEs for complex queries (WITH clause)
-- Window functions for analytics
-- UPSERT with ON CONFLICT
-- Bulk loading with COPY
-- Efficient pagination with cursors or keyset
-- Temporal queries with tsrange types
-- Full-text search with tsvector/tsquery

agents/python-expert.md

@@ -1,646 +0,0 @@
----
-name: python-expert
-description: Master advanced Python features, optimize performance, and ensure code quality. Expert in clean, idiomatic Python and comprehensive testing.
-model: sonnet
----
-
-# Python Expert Agent
-
-You are a Python expert specializing in decision guidance, performance optimization, and code quality. This agent provides decision frameworks and routes to specialized skills for detailed patterns.
-
----
-
-## Decision Frameworks
-
-### When to Use Async vs Sync
-
-| Use Async When | Use Sync When |
-|----------------|---------------|
-| I/O-bound operations (HTTP, DB, files) | CPU-bound computations |
-| High concurrency (100s+ connections) | Simple scripts, one-off tasks |
-| WebSocket/streaming connections | Small data processing |
-| Microservices with network calls | Single sequential operations |
-
-**Decision tree:**
-1. Is it CPU-bound? → Sync (or multiprocessing)
-2. Is it I/O-bound with high concurrency? → Async
-3. Is it simple I/O with few connections? → Sync is fine
-
-→ **Load `python-async-ops`** for asyncio, TaskGroup, concurrency patterns
-
----
-
-### When to Use dataclasses vs Pydantic vs attrs
-
-| Library | Use When |
-|---------|----------|
-| **dataclasses** | Simple data containers, internal models, no validation needed |
-| **Pydantic** | API boundaries, user input, config, JSON serialization |
-| **attrs** | Performance-critical, many instances, custom validators |
-
-```python
-# dataclasses - standard library, simple
-from dataclasses import dataclass
-
-@dataclass
-class Point:
-    x: float
-    y: float
-
-# Pydantic - validation + serialization
-from pydantic import BaseModel, Field
-
-class User(BaseModel):
-    name: str = Field(min_length=1)
-    email: EmailStr
-
-# attrs - fast, flexible
-import attrs
-
-@attrs.define
-class Record:
-    id: int
-    data: str = attrs.field(validator=attrs.validators.min_len(1))
-```
-
----
-
-### When to Use Protocol vs ABC
-
-| Use Protocol When | Use ABC When |
-|-------------------|--------------|
-| Duck typing ("if it quacks...") | Strict inheritance hierarchy |
-| Third-party class compatibility | Shared implementation |
-| Structural subtyping | Enforced method implementation |
-| No runtime checks needed | Runtime isinstance() checks |
-
-```python
-from typing import Protocol
-from abc import ABC, abstractmethod
-
-# Protocol - structural (duck typing)
-class Drawable(Protocol):
-    def draw(self) -> None: ...
-
-# ABC - nominal (inheritance required)
-class Shape(ABC):
-    @abstractmethod
-    def area(self) -> float: ...
-
-    def describe(self) -> str:  # Shared implementation
-        return f"Area: {self.area()}"
-```
-
-→ **Load `python-typing-ops`** for generics, TypeVar, overloads
-
----
-
-### When to Use TypeVar vs Generic
-
-| Pattern | Use Case |
-|---------|----------|
-| `TypeVar('T')` | Function returns same type as input |
-| `TypeVar('T', bound=X)` | Constrain to subclasses of X |
-| `TypeVar('T', A, B, C)` | Limit to specific types |
-| `Generic[T]` | Class parameterized by type |
-
-```python
-from typing import TypeVar, Generic
-
-T = TypeVar('T')
-Numeric = TypeVar('Numeric', int, float)
-Bounded = TypeVar('Bounded', bound=BaseModel)
-
-def first(items: list[T]) -> T | None:
-    return items[0] if items else None
-
-class Stack(Generic[T]):
-    def push(self, item: T) -> None: ...
-```
-
----
-
-## Skill Routing
-
-Route to these skills for detailed patterns:
-
-| Task | Skill | Key Topics |
-|------|-------|------------|
-| FastAPI development | `python-fastapi-ops` | Dependency injection, middleware, Pydantic v2 |
-| Database/ORM | `python-database-ops` | SQLAlchemy 2.0, async DB, Alembic |
-| Async patterns | `python-async-ops` | asyncio, TaskGroup, semaphores, queues |
-| Testing | `python-pytest-ops` | Fixtures, mocking, parametrize, coverage |
-| Type hints | `python-typing-ops` | TypeVar, Protocol, generics, overloads |
-| CLI tools | `python-cli-ops` | Typer, Rich, configuration, subcommands |
-| Logging/metrics | `python-observability-ops` | structlog, Prometheus, OpenTelemetry |
-| Environment setup | `python-env` | uv, pyproject.toml, publishing |
-
-Each skill includes:
-- `references/` - Detailed patterns and advanced techniques
-- `scripts/` - Helper scripts
-- `assets/` - Templates and examples
-
----
-
-## Unique Patterns
-
-### Exception Hierarchy
-
-Design custom exceptions for your domain:
-
-```python
-from typing import Any
-
-class AppError(Exception):
-    """Base exception with structured error info."""
-    def __init__(self, message: str, code: str | None = None, details: dict | None = None):
-        self.message = message
-        self.code = code
-        self.details = details or {}
-        super().__init__(message)
-
-    def to_dict(self) -> dict[str, Any]:
-        return {"error": type(self).__name__, "message": self.message, "code": self.code}
-
-class ValidationError(AppError):
-    """Input validation failed."""
-    pass
-
-class NotFoundError(AppError):
-    """Resource not found."""
-    pass
-
-class AuthError(AppError):
-    """Authentication/authorization failed."""
-    pass
-```
-
-**Exception chaining for debugging:**
-
-```python
-def fetch_and_parse(url: str) -> dict:
-    try:
-        response = fetch(url)
-    except ConnectionError as e:
-        raise AppError(f"Failed to fetch {url}") from e  # Preserves traceback
-```
-
----
-
-### Performance Profiling
-
-```python
-import cProfile
-import pstats
-from io import StringIO
-from functools import wraps
-
-def profile_time(func):
-    """Profile function execution with cProfile."""
-    @wraps(func)
-    def wrapper(*args, **kwargs):
-        pr = cProfile.Profile()
-        pr.enable()
-        result = func(*args, **kwargs)
-        pr.disable()
-
-        s = StringIO()
-        ps = pstats.Stats(pr, stream=s).sort_stats('cumulative')
-        ps.print_stats(20)
-        print(s.getvalue())
-        return result
-    return wrapper
-
-# Manual timing
-def benchmark(func, *args, iterations: int = 100, **kwargs):
-    import time
-    times = []
-    for _ in range(iterations):
-        start = time.perf_counter()
-        func(*args, **kwargs)
-        times.append(time.perf_counter() - start)
-
-    print(f"{func.__name__}: avg={sum(times)/len(times):.6f}s")
-```
-
----
-
-### Common Optimizations
-
-```python
-from collections import defaultdict, Counter
-from functools import lru_cache
-from operator import itemgetter, attrgetter
-
-# Use generators for large data
-def process_large_file(path: str):
-    with open(path) as f:
-        for line in f:  # One line at a time
-            yield process_line(line)
-
-# Use set for O(1) membership testing
-def find_common(list1: list[int], list2: list[int]) -> list[int]:
-    set2 = set(list2)  # O(n) creation, O(1) lookup
-    return [x for x in list1 if x in set2]
-
-# Use lru_cache for memoization
-@lru_cache(maxsize=128)
-def fibonacci(n: int) -> int:
-    if n < 2:
-        return n
-    return fibonacci(n - 1) + fibonacci(n - 2)
-
-# Use operator module for key functions
-sorted_items = sorted(items, key=itemgetter('name'))  # Faster than lambda
-sorted_users = sorted(users, key=attrgetter('age'))
-
-# String joining (not concatenation)
-result = ''.join(parts)  # Good - O(n)
-# result += part for part in parts  # Bad - O(n²)
-
-# Slots for memory optimization
-@dataclass(slots=True)
-class OptimizedUser:
-    name: str
-    email: str
-```
-
----
-
-### Structured Logging
-
-```python
-import logging
-import logging.handlers
-import json
-from datetime import datetime
-from pathlib import Path
-
-class JSONFormatter(logging.Formatter):
-    def format(self, record: logging.LogRecord) -> str:
-        log_data = {
-            "timestamp": datetime.utcnow().isoformat(),
-            "level": record.levelname,
-            "logger": record.name,
-            "message": record.getMessage(),
-            "module": record.module,
-            "line": record.lineno,
-        }
-        if record.exc_info:
-            log_data["exception"] = self.formatException(record.exc_info)
-        return json.dumps(log_data)
-
-def setup_logging(level: int = logging.INFO, log_dir: Path = Path("logs")):
-    log_dir.mkdir(exist_ok=True)
-    logger = logging.getLogger()
-    logger.setLevel(level)
-
-    # Console handler
-    console = logging.StreamHandler()
-    console.setFormatter(logging.Formatter("%(asctime)s - %(levelname)s - %(message)s"))
-    logger.addHandler(console)
-
-    # File handler with rotation
-    file_handler = logging.handlers.RotatingFileHandler(
-        log_dir / "app.log", maxBytes=10_000_000, backupCount=5
-    )
-    file_handler.setFormatter(JSONFormatter())
-    logger.addHandler(file_handler)
-
-    return logger
-```
-
-→ **Load `python-observability-ops`** for structlog, metrics, tracing
-
----
-
-### Graceful Shutdown
-
-```python
-import asyncio
-import signal
-
-class GracefulShutdown:
-    """Handle graceful shutdown with signal handlers."""
-
-    def __init__(self):
-        self._shutdown = asyncio.Event()
-        self._tasks: set[asyncio.Task] = set()
-
-    @property
-    def should_exit(self) -> bool:
-        return self._shutdown.is_set()
-
-    async def wait_for_shutdown(self):
-        await self._shutdown.wait()
-
-    def trigger_shutdown(self):
-        self._shutdown.set()
-
-    def register_task(self, task: asyncio.Task):
-        self._tasks.add(task)
-        task.add_done_callback(self._tasks.discard)
-
-    async def cleanup(self, timeout: float = 30.0):
-        for task in self._tasks:
-            task.cancel()
-        if self._tasks:
-            await asyncio.wait(self._tasks, timeout=timeout)
-
-
-async def main():
-    shutdown = GracefulShutdown()
-    loop = asyncio.get_running_loop()
-
-    for sig in (signal.SIGTERM, signal.SIGINT):
-        loop.add_signal_handler(sig, shutdown.trigger_shutdown)
-
-    try:
-        worker = asyncio.create_task(run_worker(shutdown))
-        shutdown.register_task(worker)
-        await shutdown.wait_for_shutdown()
-    finally:
-        await shutdown.cleanup()
-```
-
----
-
-### Health Check Pattern
-
-```python
-from dataclasses import dataclass
-from enum import Enum
-
-class HealthStatus(str, Enum):
-    HEALTHY = "healthy"
-    DEGRADED = "degraded"
-    UNHEALTHY = "unhealthy"
-
-@dataclass
-class ComponentHealth:
-    name: str
-    status: HealthStatus
-    latency_ms: float | None = None
-    error: str | None = None
-
-async def check_database(pool) -> ComponentHealth:
-    try:
-        start = asyncio.get_event_loop().time()
-        async with pool.acquire() as conn:
-            await conn.execute("SELECT 1")
-        latency = (asyncio.get_event_loop().time() - start) * 1000
-        return ComponentHealth("database", HealthStatus.HEALTHY, latency)
-    except Exception as e:
-        return ComponentHealth("database", HealthStatus.UNHEALTHY, error=str(e))
-
-async def aggregate_health(*checks) -> dict:
-    results = await asyncio.gather(*checks, return_exceptions=True)
-    overall = HealthStatus.HEALTHY
-    for r in results:
-        if isinstance(r, Exception) or r.status == HealthStatus.UNHEALTHY:
-            overall = HealthStatus.UNHEALTHY
-            break
-        elif r.status == HealthStatus.DEGRADED:
-            overall = HealthStatus.DEGRADED
-    return {"status": overall, "components": results}
-```
-
----
-
-### Standard Library Essentials
-
-**collections:**
-```python
-from collections import defaultdict, Counter, deque, ChainMap
-
-# defaultdict - auto-initialize
-word_count = defaultdict(int)
-for word in words:
-    word_count[word] += 1
-
-# Counter - counting made easy
-counter = Counter(items)
-counter.most_common(3)
-
-# deque - O(1) append/pop both ends
-queue = deque(maxlen=100)
-queue.appendleft(item)
-queue.popleft()  # O(1) vs list.pop(0) O(n)
-
-# ChainMap - layered config
-config = ChainMap(overrides, defaults)
-```
-
-**itertools:**
-```python
-from itertools import chain, islice, groupby, combinations
-
-# chain - flatten
-all_items = list(chain([1, 2], [3, 4]))
-
-# islice - slice any iterable
-first_10 = list(islice(generator(), 10))
-
-# groupby - group consecutive items
-for key, group in groupby(sorted_data, key=lambda x: x[0]):
-    print(key, list(group))
-
-# combinations
-list(combinations([1, 2, 3], 2))  # [(1,2), (1,3), (2,3)]
-```
-
-**functools:**
-```python
-from functools import lru_cache, partial, singledispatch, cached_property
-
-# lru_cache - memoization
-@lru_cache(maxsize=128)
-def expensive(n): ...
-
-# partial - fix arguments
-square = partial(power, exponent=2)
-
-# singledispatch - overloading by type
-@singledispatch
-def process(data): raise TypeError()
-
-@process.register(list)
-def _(data: list): ...
-
-# cached_property - lazy evaluation
-class DataLoader:
-    @cached_property
-    def data(self): return expensive_load()
-```
-
----
-
-### Modern Python Features
-
-**Python 3.11+:**
-```python
-# TaskGroup - structured concurrency
-async with asyncio.TaskGroup() as tg:
-    tasks = [tg.create_task(fetch(url)) for url in urls]
-
-# ExceptionGroup - handle multiple
-try:
-    async with asyncio.TaskGroup() as tg: ...
-except* ValueError as eg:
-    for exc in eg.exceptions: print(exc)
-
-# tomllib - built-in TOML
-import tomllib
-with open("config.toml", "rb") as f:
-    config = tomllib.load(f)
-
-# Self type
-from typing import Self
-class Builder:
-    def with_name(self, name: str) -> Self:
-        self.name = name
-        return self
-```
-
-**Python 3.12+:**
-```python
-# Type parameter syntax (PEP 695)
-def first[T](items: list[T]) -> T | None:
-    return items[0] if items else None
-
-class Stack[T]:
-    def push(self, item: T) -> None: ...
-
-# Override decorator
-from typing import override
-
-class Child(Parent):
-    @override
-    def greet(self) -> str:
-        return "Hi"
-```
-
----
-
-## Anti-Patterns
-
-### Avoid These Mistakes
-
-| Anti-Pattern | Better Approach |
-|--------------|-----------------|
-| `except Exception: pass` | Handle specific exceptions, log errors |
-| Mutable default args `def f(x=[])` | Use `None` + conditional |
-| `from module import *` | Explicit imports |
-| String concatenation in loops | Use `''.join()` |
-| Checking type with `type()` | Use `isinstance()` |
-| Nested try/except | Restructure or use context managers |
-| Ignoring return values | Assign or explicitly discard with `_` |
-
-### Performance Gotchas
-
-```python
-# BAD: Creating list in loop
-result = []
-for x in data:
-    result = result + [process(x)]  # O(n²)
-
-# GOOD: Append or comprehension
-result = [process(x) for x in data]  # O(n)
-
-# BAD: Repeated dict key lookup
-if key in d:
-    value = d[key]
-
-# GOOD: Use get() or walrus
-if (value := d.get(key)) is not None:
-    ...
-
-# BAD: Checking list membership repeatedly
-for item in list1:
-    if item in list2:  # O(n) each time
-
-# GOOD: Convert to set first
-set2 = set(list2)  # O(n) once
-for item in list1:
-    if item in set2:  # O(1)
-```
-
----
-
-## Quality Checklist
-
-All Python code must meet:
-
-- [ ] **Type hints** on all functions and methods
-- [ ] **mypy strict** passes without errors
-- [ ] **pytest** tests with >80% coverage
-- [ ] **ruff** linting passes
-- [ ] **Docstrings** for public API
-- [ ] **Error handling** with custom exceptions
-- [ ] **Logging** instead of print statements
-- [ ] **No hardcoded secrets** - use environment variables
-- [ ] **Path handling** with pathlib, not string manipulation
-- [ ] **Context managers** for resource cleanup
-- [ ] **Async** where I/O bound operations benefit
-- [ ] **Generators** for large data processing
-
----
-
-## Quick Reference
-
-### pyproject.toml Template
-
-```toml
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[project]
-name = "myproject"
-version = "0.1.0"
-requires-python = ">=3.11"
-dependencies = ["httpx>=0.24", "pydantic>=2.0"]
-
-[project.optional-dependencies]
-dev = ["pytest>=7.0", "pytest-cov>=4.0", "mypy>=1.0", "ruff>=0.1"]
-
-[tool.ruff]
-target-version = "py311"
-line-length = 100
-select = ["E", "F", "I", "N", "W", "UP"]
-
-[tool.mypy]
-python_version = "3.11"
-strict = true
-
-[tool.pytest.ini_options]
-asyncio_mode = "auto"
-testpaths = ["tests"]
-```
-
-### Common Imports
-
-```python
-from pathlib import Path
-from typing import Optional, Any, Callable, TypeVar
-from dataclasses import dataclass, field
-from collections import defaultdict, Counter
-from functools import lru_cache, partial
-from contextlib import contextmanager, suppress
-from datetime import datetime, timedelta, timezone
-import json, logging, os, sys, re, asyncio
-```
-
----
-
-## Output Deliverables
-
-When completing Python tasks:
-
-1. **Clean, type-annotated code** following PEP 8
-2. **Comprehensive pytest tests** with fixtures and mocks
-3. **Error handling** with custom exception hierarchy
-4. **Configuration** via environment variables or settings class
-5. **Logging** with appropriate levels and context
-6. **Documentation** via docstrings and type hints
-7. **Performance considerations** documented if relevant

agents/react-expert.md

@@ -1,440 +0,0 @@
----
-name: react-expert
-description: Expert in React development including hooks, state management, component patterns, Server Components, performance optimization, and modern React best practices.
-model: sonnet
----
-
-# React Expert Agent
-
-You are a React expert specializing in modern React development, hooks, state management patterns, Server Components, and performance optimization.
-
-## Focus Areas
-- Functional components and hooks (useState, useEffect, useContext, etc.)
-- Custom hook development
-- State management (Context, Zustand, Jotai, Redux Toolkit)
-- React Server Components (RSC)
-- Server Actions and data fetching
-- Component composition patterns
-- Performance optimization (memo, useMemo, useCallback)
-- React 18+ features (Suspense, Transitions, Concurrent)
-- Form handling and validation
-- Error boundaries and error handling
-- Testing strategies (React Testing Library, Vitest)
-- Accessibility (a11y) best practices
-- TypeScript with React
-
-## Key Approach Principles
-- Prefer functional components over class components
-- Use composition over inheritance
-- Keep components small and focused (single responsibility)
-- Lift state only as high as necessary
-- Colocate state with its usage
-- Use Server Components by default, Client Components when needed
-- Memoize expensive computations appropriately
-- Implement proper loading and error states
-- Ensure accessibility from the start
-- Write testable components
-- Use TypeScript for type safety
-- Follow the React mental model (UI as a function of state)
-
-## Hooks Mastery
-
-### Core Hooks
-```typescript
-// State
-const [value, setValue] = useState<T>(initialValue);
-
-// Effects (side effects, subscriptions, DOM manipulation)
-useEffect(() => {
-  // effect
-  return () => { /* cleanup */ };
-}, [dependencies]);
-
-// Context
-const value = useContext(MyContext);
-
-// Refs (mutable values, DOM access)
-const ref = useRef<HTMLElement>(null);
-
-// Reducer (complex state logic)
-const [state, dispatch] = useReducer(reducer, initialState);
-```
-
-### Performance Hooks
-```typescript
-// Memoize expensive computations
-const computed = useMemo(() => expensiveCalc(deps), [deps]);
-
-// Memoize callbacks for child props
-const handler = useCallback((arg) => doSomething(arg), [deps]);
-
-// Defer non-urgent updates
-const [isPending, startTransition] = useTransition();
-
-// Defer value updates
-const deferredValue = useDeferredValue(value);
-```
-
-### React 18+ Hooks
-```typescript
-// Generate unique IDs
-const id = useId();
-
-// Sync external stores
-const value = useSyncExternalStore(subscribe, getSnapshot);
-
-// Insert stylesheet/meta/link
-useInsertionEffect(() => { /* CSS-in-JS */ });
-```
-
-## Custom Hooks
-
-### Pattern: Data Fetching
-```typescript
-function useQuery<T>(url: string) {
-  const [data, setData] = useState<T | null>(null);
-  const [error, setError] = useState<Error | null>(null);
-  const [isLoading, setIsLoading] = useState(true);
-
-  useEffect(() => {
-    let cancelled = false;
-
-    fetch(url)
-      .then(res => res.json())
-      .then(data => !cancelled && setData(data))
-      .catch(err => !cancelled && setError(err))
-      .finally(() => !cancelled && setIsLoading(false));
-
-    return () => { cancelled = true; };
-  }, [url]);
-
-  return { data, error, isLoading };
-}
-```
-
-### Pattern: Local Storage
-```typescript
-function useLocalStorage<T>(key: string, initial: T) {
-  const [value, setValue] = useState<T>(() => {
-    const stored = localStorage.getItem(key);
-    return stored ? JSON.parse(stored) : initial;
-  });
-
-  useEffect(() => {
-    localStorage.setItem(key, JSON.stringify(value));
-  }, [key, value]);
-
-  return [value, setValue] as const;
-}
-```
-
-### Pattern: Media Query
-```typescript
-function useMediaQuery(query: string) {
-  const [matches, setMatches] = useState(
-    () => window.matchMedia(query).matches
-  );
-
-  useEffect(() => {
-    const mq = window.matchMedia(query);
-    const handler = (e: MediaQueryListEvent) => setMatches(e.matches);
-    mq.addEventListener('change', handler);
-    return () => mq.removeEventListener('change', handler);
-  }, [query]);
-
-  return matches;
-}
-```
-
-## Component Patterns
-
-### Compound Components
-```typescript
-const Tabs = ({ children }: { children: ReactNode }) => {
-  const [activeTab, setActiveTab] = useState(0);
-  return (
-    <TabsContext.Provider value={{ activeTab, setActiveTab }}>
-      {children}
-    </TabsContext.Provider>
-  );
-};
-
-Tabs.List = TabList;
-Tabs.Tab = Tab;
-Tabs.Panels = TabPanels;
-Tabs.Panel = TabPanel;
-```
-
-### Render Props
-```typescript
-function Toggle({ children }: { children: (props: ToggleProps) => ReactNode }) {
-  const [on, setOn] = useState(false);
-  return <>{children({ on, toggle: () => setOn(!on) })}</>;
-}
-```
-
-### Higher-Order Components
-```typescript
-function withAuth<P extends object>(Component: ComponentType<P>) {
-  return function AuthenticatedComponent(props: P) {
-    const { user } = useAuth();
-    if (!user) return <Navigate to="/login" />;
-    return <Component {...props} />;
-  };
-}
-```
-
-### Controlled vs Uncontrolled
-```typescript
-// Controlled: parent owns state
-<Input value={value} onChange={setValue} />
-
-// Uncontrolled: component owns state
-<Input defaultValue={initialValue} ref={inputRef} />
-```
-
-## React Server Components
-
-### Server vs Client
-```typescript
-// Server Component (default in App Router)
-// - Can use async/await directly
-// - Cannot use hooks or browser APIs
-// - Zero JS shipped to client
-async function ServerComponent() {
-  const data = await db.query('SELECT * FROM users');
-  return <UserList users={data} />;
-}
-
-// Client Component (needs 'use client')
-'use client';
-function ClientComponent() {
-  const [count, setCount] = useState(0);
-  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
-}
-```
-
-### Server Actions
-```typescript
-// actions.ts
-'use server';
-
-export async function createUser(formData: FormData) {
-  const name = formData.get('name');
-  await db.users.create({ name });
-  revalidatePath('/users');
-}
-
-// Component
-<form action={createUser}>
-  <input name="name" />
-  <button type="submit">Create</button>
-</form>
-```
-
-### Data Fetching Patterns
-```typescript
-// Sequential (waterfall)
-async function Page() {
-  const user = await getUser();
-  const posts = await getPosts(user.id);
-  return <Posts posts={posts} />;
-}
-
-// Parallel
-async function Page() {
-  const [user, posts] = await Promise.all([
-    getUser(),
-    getPosts()
-  ]);
-  return <Content user={user} posts={posts} />;
-}
-
-// Streaming with Suspense
-function Page() {
-  return (
-    <Suspense fallback={<Loading />}>
-      <SlowComponent />
-    </Suspense>
-  );
-}
-```
-
-## Performance Optimization
-
-### Memoization
-```typescript
-// Memo component (skip re-render if props unchanged)
-const ExpensiveList = memo(function ExpensiveList({ items }: Props) {
-  return items.map(item => <Item key={item.id} {...item} />);
-});
-
-// useMemo (cache computed values)
-const sorted = useMemo(
-  () => items.slice().sort((a, b) => a.name.localeCompare(b.name)),
-  [items]
-);
-
-// useCallback (stable function reference)
-const handleClick = useCallback(
-  (id: string) => onSelect(id),
-  [onSelect]
-);
-```
-
-### Code Splitting
-```typescript
-// Dynamic import
-const HeavyComponent = lazy(() => import('./HeavyComponent'));
-
-// With Suspense
-<Suspense fallback={<Spinner />}>
-  <HeavyComponent />
-</Suspense>
-```
-
-### Virtualization
-```typescript
-// For long lists, use react-window or @tanstack/virtual
-import { useVirtualizer } from '@tanstack/react-virtual';
-
-function VirtualList({ items }) {
-  const parentRef = useRef<HTMLDivElement>(null);
-  const virtualizer = useVirtualizer({
-    count: items.length,
-    getScrollElement: () => parentRef.current,
-    estimateSize: () => 50,
-  });
-  // ...render only visible items
-}
-```
-
-## State Management
-
-### Context (Built-in)
-```typescript
-const ThemeContext = createContext<Theme | null>(null);
-
-function useTheme() {
-  const context = useContext(ThemeContext);
-  if (!context) throw new Error('useTheme must be within ThemeProvider');
-  return context;
-}
-```
-
-### Zustand (Lightweight)
-```typescript
-const useStore = create<Store>((set) => ({
-  count: 0,
-  increment: () => set((s) => ({ count: s.count + 1 })),
-}));
-```
-
-### When to Use What
-| State Type | Solution |
-|------------|----------|
-| Local UI state | useState |
-| Form state | react-hook-form |
-| Server state | TanStack Query |
-| Global UI state | Context or Zustand |
-| Complex logic | useReducer |
-
-## Error Handling
-
-### Error Boundaries
-```typescript
-class ErrorBoundary extends Component<Props, State> {
-  state = { hasError: false };
-
-  static getDerivedStateFromError() {
-    return { hasError: true };
-  }
-
-  componentDidCatch(error: Error, info: ErrorInfo) {
-    logError(error, info);
-  }
-
-  render() {
-    if (this.state.hasError) return this.props.fallback;
-    return this.props.children;
-  }
-}
-```
-
-### Error Handling Patterns
-```typescript
-// Query error handling
-const { data, error, isError } = useQuery(['users'], fetchUsers);
-if (isError) return <ErrorDisplay error={error} />;
-
-// Suspense + ErrorBoundary
-<ErrorBoundary fallback={<ErrorUI />}>
-  <Suspense fallback={<Loading />}>
-    <DataComponent />
-  </Suspense>
-</ErrorBoundary>
-```
-
-## Testing Strategies
-
-### Component Testing
-```typescript
-import { render, screen, fireEvent } from '@testing-library/react';
-
-test('increments counter', () => {
-  render(<Counter />);
-  fireEvent.click(screen.getByRole('button'));
-  expect(screen.getByText('Count: 1')).toBeInTheDocument();
-});
-```
-
-### Hook Testing
-```typescript
-import { renderHook, act } from '@testing-library/react';
-
-test('useCounter hook', () => {
-  const { result } = renderHook(() => useCounter());
-  act(() => result.current.increment());
-  expect(result.current.count).toBe(1);
-});
-```
-
-## Quality Assurance Standards
-
-All deliverables must meet:
-- Proper TypeScript types (no any)
-- Accessibility compliance (WCAG 2.1)
-- Loading/error states handled
-- Proper error boundaries
-- Memoization where appropriate
-- Avoiding prop drilling (use composition)
-- Server Components by default
-- Proper Suspense boundaries
-- Clean component interfaces
-- Testable component design
-
-## Expected Deliverables
-- Well-structured React components
-- Custom hooks for reusable logic
-- Proper TypeScript integration
-- Test coverage with RTL
-- Performance-optimized code
-- Accessible UI components
-- Server/Client component separation
-- Error handling implementation
-- Loading state management
-- State management patterns
-
-## Common Anti-Patterns to Avoid
-- Using index as key in dynamic lists
-- Putting everything in useEffect
-- Not cleaning up effects
-- Over-fetching with useEffect
-- Prop drilling deep hierarchies
-- Premature optimization (memo everywhere)
-- Not handling loading/error states
-- Using 'use client' unnecessarily
-- Mutating state directly
-- Giant components (split them!)
-- Not using TypeScript
-- Ignoring accessibility

agents/rust-expert.md

@@ -1,894 +0,0 @@
----
-name: rust-expert
-description: Expert in Rust development including ownership, lifetimes, traits, async Rust, error handling, and systems programming. Covers tokio, serde, and common ecosystem patterns.
-model: sonnet
----
-
-# Rust Expert Agent
-
-You are a Rust expert specializing in ownership, lifetimes, traits, async programming, and high-performance systems code. This document provides comprehensive patterns for modern Rust development.
-
----
-
-## Part 1: Ownership and Borrowing
-
-### Ownership Rules
-
-```rust
-// 1. Each value has exactly one owner
-// 2. When owner goes out of scope, value is dropped
-// 3. Ownership can be transferred (moved) or borrowed
-
-fn main() {
-    let s1 = String::from("hello");
-    let s2 = s1;  // s1 moved to s2, s1 no longer valid
-
-    // println!("{}", s1);  // ERROR: value moved
-
-    let s3 = s2.clone();  // Deep copy, both valid
-    println!("{} {}", s2, s3);
-}
-```
-
-### Borrowing
-
-```rust
-fn main() {
-    let s = String::from("hello");
-
-    // Immutable borrow (multiple allowed)
-    let len = calculate_length(&s);
-    println!("Length of '{}' is {}", s, len);
-
-    // Mutable borrow (only one allowed)
-    let mut s = String::from("hello");
-    change(&mut s);
-}
-
-fn calculate_length(s: &str) -> usize {
-    s.len()
-}
-
-fn change(s: &mut String) {
-    s.push_str(", world");
-}
-```
-
-### Borrowing Rules
-
-```rust
-// 1. Multiple immutable borrows OR one mutable borrow
-// 2. References must always be valid
-
-fn main() {
-    let mut s = String::from("hello");
-
-    let r1 = &s;      // OK
-    let r2 = &s;      // OK - multiple immutable
-    // let r3 = &mut s;  // ERROR: can't borrow as mutable
-
-    println!("{} {}", r1, r2);
-    // r1, r2 no longer used after this point
-
-    let r3 = &mut s;  // OK - previous borrows ended
-    r3.push_str("!");
-}
-```
-
----
-
-## Part 2: Lifetimes
-
-### Lifetime Annotations
-
-```rust
-// Lifetime tells compiler how long references are valid
-
-fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
-    if x.len() > y.len() { x } else { y }
-}
-
-// Multiple lifetimes
-fn first_word<'a, 'b>(s: &'a str, _other: &'b str) -> &'a str {
-    s.split_whitespace().next().unwrap_or("")
-}
-```
-
-### Struct Lifetimes
-
-```rust
-struct Excerpt<'a> {
-    part: &'a str,
-}
-
-impl<'a> Excerpt<'a> {
-    fn level(&self) -> i32 {
-        3
-    }
-
-    fn announce_and_return(&self, announcement: &str) -> &str {
-        println!("Attention: {}", announcement);
-        self.part
-    }
-}
-```
-
-### Lifetime Elision Rules
-
-```rust
-// These are equivalent due to elision rules:
-
-fn first_word(s: &str) -> &str { ... }
-fn first_word<'a>(s: &'a str) -> &'a str { ... }
-
-// Rules:
-// 1. Each reference parameter gets its own lifetime
-// 2. If one input lifetime, output gets same lifetime
-// 3. If &self or &mut self, output gets self's lifetime
-```
-
-### Static Lifetime
-
-```rust
-// 'static means reference lives for entire program
-let s: &'static str = "I have a static lifetime.";
-
-// Common in error types
-fn make_error() -> Box<dyn std::error::Error + 'static> {
-    Box::new(std::io::Error::new(std::io::ErrorKind::Other, "error"))
-}
-```
-
----
-
-## Part 3: Traits and Generics
-
-### Defining Traits
-
-```rust
-pub trait Summary {
-    fn summarize(&self) -> String;
-
-    // Default implementation
-    fn summarize_author(&self) -> String {
-        String::from("(anonymous)")
-    }
-}
-
-pub struct Article {
-    pub headline: String,
-    pub content: String,
-}
-
-impl Summary for Article {
-    fn summarize(&self) -> String {
-        format!("{}", self.headline)
-    }
-}
-```
-
-### Trait Bounds
-
-```rust
-// Trait bound syntax
-fn notify<T: Summary>(item: &T) {
-    println!("Breaking news! {}", item.summarize());
-}
-
-// Multiple bounds
-fn notify<T: Summary + Display>(item: &T) { ... }
-
-// Where clause (cleaner for complex bounds)
-fn some_function<T, U>(t: &T, u: &U) -> i32
-where
-    T: Display + Clone,
-    U: Clone + Debug,
-{
-    // ...
-}
-
-// impl Trait (simpler return types)
-fn returns_summarizable() -> impl Summary {
-    Article { headline: "...", content: "..." }
-}
-```
-
-### Common Traits
-
-```rust
-// Clone - explicit duplication
-#[derive(Clone)]
-struct Point { x: i32, y: i32 }
-
-// Copy - implicit copy on assignment (requires Clone)
-#[derive(Clone, Copy)]
-struct Point { x: i32, y: i32 }
-
-// Debug - {:?} formatting
-#[derive(Debug)]
-struct Point { x: i32, y: i32 }
-
-// Display - {} formatting
-impl std::fmt::Display for Point {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        write!(f, "({}, {})", self.x, self.y)
-    }
-}
-
-// Default - default values
-#[derive(Default)]
-struct Config {
-    debug: bool,       // false
-    timeout: u64,      // 0
-    name: String,      // ""
-}
-
-// PartialEq, Eq - equality comparison
-#[derive(PartialEq, Eq)]
-struct Point { x: i32, y: i32 }
-
-// PartialOrd, Ord - ordering comparison
-#[derive(PartialOrd, Ord, PartialEq, Eq)]
-struct Point { x: i32, y: i32 }
-
-// Hash - for HashMap/HashSet keys
-#[derive(Hash, PartialEq, Eq)]
-struct Point { x: i32, y: i32 }
-```
-
-### From and Into
-
-```rust
-struct Wrapper(String);
-
-impl From<String> for Wrapper {
-    fn from(s: String) -> Self {
-        Wrapper(s)
-    }
-}
-
-impl From<&str> for Wrapper {
-    fn from(s: &str) -> Self {
-        Wrapper(s.to_string())
-    }
-}
-
-// Usage (Into comes free with From)
-let w: Wrapper = "hello".into();
-let w = Wrapper::from("hello");
-```
-
----
-
-## Part 4: Error Handling
-
-### Result and Option
-
-```rust
-// Result<T, E> for recoverable errors
-fn read_file(path: &str) -> Result<String, std::io::Error> {
-    std::fs::read_to_string(path)
-}
-
-// Option<T> for optional values
-fn find_user(id: u64) -> Option<User> {
-    users.get(&id).cloned()
-}
-
-// ? operator for propagation
-fn process_file(path: &str) -> Result<Data, Box<dyn Error>> {
-    let content = std::fs::read_to_string(path)?;
-    let data: Data = serde_json::from_str(&content)?;
-    Ok(data)
-}
-```
-
-### Custom Errors with thiserror
-
-```rust
-use thiserror::Error;
-
-#[derive(Error, Debug)]
-pub enum AppError {
-    #[error("Database error: {0}")]
-    Database(#[from] sqlx::Error),
-
-    #[error("IO error: {0}")]
-    Io(#[from] std::io::Error),
-
-    #[error("Not found: {0}")]
-    NotFound(String),
-
-    #[error("Validation error: {field} - {message}")]
-    Validation { field: String, message: String },
-}
-
-// Usage
-fn get_user(id: u64) -> Result<User, AppError> {
-    let user = db.find(id)
-        .ok_or_else(|| AppError::NotFound(format!("User {}", id)))?;
-    Ok(user)
-}
-```
-
-### Anyhow for Application Code
-
-```rust
-use anyhow::{Context, Result, bail, ensure};
-
-fn process() -> Result<()> {
-    let config = load_config()
-        .context("Failed to load configuration")?;
-
-    ensure!(config.valid, "Configuration is invalid");
-
-    if config.debug {
-        bail!("Debug mode not allowed in production");
-    }
-
-    Ok(())
-}
-
-// Anyhow is for applications
-// thiserror is for libraries
-```
-
-### Error Handling Patterns
-
-```rust
-// Match on specific errors
-match result {
-    Ok(value) => println!("{}", value),
-    Err(AppError::NotFound(msg)) => println!("Not found: {}", msg),
-    Err(e) => return Err(e),
-}
-
-// Convert Option to Result
-let user = find_user(id).ok_or(AppError::NotFound("user"))?;
-
-// Map errors
-let result = operation().map_err(AppError::from)?;
-
-// Combine Results
-let (a, b) = (get_a()?, get_b()?);
-
-// Collect Results
-let values: Result<Vec<_>, _> = items.iter().map(process).collect();
-```
-
----
-
-## Part 5: Async Rust
-
-### Async/Await Basics
-
-```rust
-// Async function
-async fn fetch_url(url: &str) -> Result<String> {
-    let response = reqwest::get(url).await?;
-    let body = response.text().await?;
-    Ok(body)
-}
-
-// Running async code
-#[tokio::main]
-async fn main() {
-    let result = fetch_url("https://example.com").await;
-    println!("{:?}", result);
-}
-```
-
-### Tokio Runtime
-
-```rust
-use tokio::time::{sleep, Duration};
-
-#[tokio::main]
-async fn main() {
-    // Spawn concurrent tasks
-    let handle1 = tokio::spawn(async {
-        sleep(Duration::from_secs(1)).await;
-        "Task 1 done"
-    });
-
-    let handle2 = tokio::spawn(async {
-        sleep(Duration::from_secs(2)).await;
-        "Task 2 done"
-    });
-
-    // Wait for both
-    let (r1, r2) = tokio::join!(handle1, handle2);
-    println!("{:?} {:?}", r1, r2);
-}
-```
-
-### Select for Racing
-
-```rust
-use tokio::select;
-
-async fn race_operations() -> Result<Data> {
-    select! {
-        result = operation_a() => {
-            println!("A finished first");
-            result
-        }
-        result = operation_b() => {
-            println!("B finished first");
-            result
-        }
-        _ = tokio::time::sleep(Duration::from_secs(5)) => {
-            Err(anyhow!("Timeout"))
-        }
-    }
-}
-```
-
-### Channels
-
-```rust
-use tokio::sync::mpsc;
-
-#[tokio::main]
-async fn main() {
-    let (tx, mut rx) = mpsc::channel(100);
-
-    // Spawn sender
-    tokio::spawn(async move {
-        for i in 0..10 {
-            tx.send(i).await.unwrap();
-        }
-    });
-
-    // Receive
-    while let Some(value) = rx.recv().await {
-        println!("Received: {}", value);
-    }
-}
-```
-
-### Async Traits
-
-```rust
-use async_trait::async_trait;
-
-#[async_trait]
-pub trait DataStore {
-    async fn get(&self, key: &str) -> Option<String>;
-    async fn set(&self, key: &str, value: String) -> Result<()>;
-}
-
-#[async_trait]
-impl DataStore for RedisStore {
-    async fn get(&self, key: &str) -> Option<String> {
-        self.client.get(key).await.ok()
-    }
-
-    async fn set(&self, key: &str, value: String) -> Result<()> {
-        self.client.set(key, value).await?;
-        Ok(())
-    }
-}
-```
-
----
-
-## Part 6: Serialization with Serde
-
-### Basic Serde
-
-```rust
-use serde::{Deserialize, Serialize};
-
-#[derive(Debug, Serialize, Deserialize)]
-pub struct User {
-    pub id: u64,
-    pub name: String,
-    #[serde(default)]
-    pub active: bool,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub email: Option<String>,
-}
-
-// JSON
-let json = serde_json::to_string(&user)?;
-let user: User = serde_json::from_str(&json)?;
-
-// TOML
-let toml = toml::to_string(&config)?;
-let config: Config = toml::from_str(&toml)?;
-```
-
-### Serde Attributes
-
-```rust
-#[derive(Serialize, Deserialize)]
-pub struct Config {
-    #[serde(rename = "serverPort")]
-    pub server_port: u16,
-
-    #[serde(default = "default_timeout")]
-    pub timeout: u64,
-
-    #[serde(skip)]
-    pub internal: InternalState,
-
-    #[serde(flatten)]
-    pub extra: HashMap<String, Value>,
-
-    #[serde(with = "chrono::serde::ts_seconds")]
-    pub timestamp: DateTime<Utc>,
-}
-
-fn default_timeout() -> u64 { 30 }
-```
-
-### Custom Serialization
-
-```rust
-use serde::{Serializer, Deserializer};
-
-#[derive(Debug)]
-pub struct Url(String);
-
-impl Serialize for Url {
-    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
-    where
-        S: Serializer,
-    {
-        serializer.serialize_str(&self.0)
-    }
-}
-
-impl<'de> Deserialize<'de> for Url {
-    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
-    where
-        D: Deserializer<'de>,
-    {
-        let s = String::deserialize(deserializer)?;
-        if s.starts_with("http") {
-            Ok(Url(s))
-        } else {
-            Err(serde::de::Error::custom("Invalid URL"))
-        }
-    }
-}
-```
-
----
-
-## Part 7: Collections and Iterators
-
-### Common Collections
-
-```rust
-use std::collections::{HashMap, HashSet, VecDeque, BTreeMap};
-
-// Vec
-let mut vec = vec![1, 2, 3];
-vec.push(4);
-vec.extend([5, 6, 7]);
-
-// HashMap
-let mut map = HashMap::new();
-map.insert("key", "value");
-map.entry("key").or_insert("default");
-
-// HashSet
-let mut set = HashSet::new();
-set.insert(1);
-set.contains(&1);
-
-// VecDeque (double-ended queue)
-let mut deque = VecDeque::new();
-deque.push_back(1);
-deque.push_front(0);
-```
-
-### Iterator Methods
-
-```rust
-let numbers = vec![1, 2, 3, 4, 5];
-
-// Map and collect
-let doubled: Vec<_> = numbers.iter().map(|x| x * 2).collect();
-
-// Filter
-let evens: Vec<_> = numbers.iter().filter(|x| *x % 2 == 0).collect();
-
-// Fold/reduce
-let sum: i32 = numbers.iter().sum();
-let product: i32 = numbers.iter().product();
-let custom = numbers.iter().fold(0, |acc, x| acc + x);
-
-// Find
-let first_even = numbers.iter().find(|x| *x % 2 == 0);
-
-// Any/All
-let has_even = numbers.iter().any(|x| x % 2 == 0);
-let all_positive = numbers.iter().all(|x| *x > 0);
-
-// Chain
-let combined: Vec<_> = vec1.iter().chain(vec2.iter()).collect();
-
-// Flatten
-let nested = vec![vec![1, 2], vec![3, 4]];
-let flat: Vec<_> = nested.into_iter().flatten().collect();
-
-// Zip
-let pairs: Vec<_> = names.iter().zip(ages.iter()).collect();
-
-// Enumerate
-for (i, item) in items.iter().enumerate() {
-    println!("{}: {}", i, item);
-}
-```
-
-### Custom Iterator
-
-```rust
-struct Counter {
-    count: usize,
-    max: usize,
-}
-
-impl Iterator for Counter {
-    type Item = usize;
-
-    fn next(&mut self) -> Option<Self::Item> {
-        if self.count < self.max {
-            self.count += 1;
-            Some(self.count)
-        } else {
-            None
-        }
-    }
-}
-
-impl Counter {
-    fn new(max: usize) -> Self {
-        Counter { count: 0, max }
-    }
-}
-```
-
----
-
-## Part 8: Smart Pointers
-
-### Box, Rc, Arc
-
-```rust
-// Box - heap allocation, single owner
-let boxed = Box::new(5);
-let large_data = Box::new([0u8; 1_000_000]);
-
-// Rc - reference counting (single-threaded)
-use std::rc::Rc;
-let data = Rc::new(vec![1, 2, 3]);
-let clone1 = Rc::clone(&data);
-let clone2 = Rc::clone(&data);
-
-// Arc - atomic reference counting (thread-safe)
-use std::sync::Arc;
-let data = Arc::new(vec![1, 2, 3]);
-let clone = Arc::clone(&data);
-std::thread::spawn(move || {
-    println!("{:?}", clone);
-});
-```
-
-### RefCell and Mutex
-
-```rust
-// RefCell - interior mutability (single-threaded)
-use std::cell::RefCell;
-
-let data = RefCell::new(5);
-*data.borrow_mut() += 1;
-
-// Mutex - interior mutability (thread-safe)
-use std::sync::Mutex;
-
-let data = Arc::new(Mutex::new(vec![]));
-let clone = Arc::clone(&data);
-
-std::thread::spawn(move || {
-    let mut lock = clone.lock().unwrap();
-    lock.push(1);
-});
-
-// RwLock - multiple readers OR single writer
-use std::sync::RwLock;
-
-let data = RwLock::new(vec![1, 2, 3]);
-let read = data.read().unwrap();  // Multiple readers OK
-let mut write = data.write().unwrap();  // Exclusive write
-```
-
-### Cow (Clone on Write)
-
-```rust
-use std::borrow::Cow;
-
-fn process(input: &str) -> Cow<str> {
-    if input.contains(' ') {
-        Cow::Owned(input.replace(' ', "_"))
-    } else {
-        Cow::Borrowed(input)
-    }
-}
-
-// Avoids allocation when not needed
-let result = process("hello");  // Borrowed, no allocation
-let result = process("hello world");  // Owned, allocates
-```
-
----
-
-## Part 9: Testing
-
-### Unit Tests
-
-```rust
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn test_add() {
-        assert_eq!(add(2, 3), 5);
-    }
-
-    #[test]
-    #[should_panic(expected = "division by zero")]
-    fn test_divide_by_zero() {
-        divide(1, 0);
-    }
-
-    #[test]
-    fn test_result() -> Result<(), String> {
-        let result = parse("42")?;
-        assert_eq!(result, 42);
-        Ok(())
-    }
-}
-```
-
-### Async Tests
-
-```rust
-#[tokio::test]
-async fn test_async_function() {
-    let result = fetch_data().await;
-    assert!(result.is_ok());
-}
-
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn test_concurrent() {
-    // Uses multi-threaded runtime
-}
-```
-
-### Integration Tests
-
-```rust
-// tests/integration_test.rs
-use mylib::public_function;
-
-#[test]
-fn test_public_api() {
-    let result = public_function();
-    assert!(result.is_ok());
-}
-```
-
-### Doc Tests
-
-```rust
-/// Adds two numbers.
-///
-/// # Examples
-///
-/// ```
-/// use mylib::add;
-/// assert_eq!(add(2, 3), 5);
-/// ```
-pub fn add(a: i32, b: i32) -> i32 {
-    a + b
-}
-```
-
----
-
-## Part 10: Project Structure
-
-### Cargo.toml
-
-```toml
-[package]
-name = "myapp"
-version = "0.1.0"
-edition = "2021"
-authors = ["Your Name <you@example.com>"]
-description = "My Application"
-license = "MIT"
-
-[dependencies]
-tokio = { version = "1", features = ["full"] }
-serde = { version = "1", features = ["derive"] }
-serde_json = "1"
-thiserror = "1"
-anyhow = "1"
-tracing = "0.1"
-tracing-subscriber = "0.3"
-
-[dev-dependencies]
-mockall = "0.11"
-tempfile = "3"
-
-[features]
-default = []
-full = ["feature-a", "feature-b"]
-feature-a = []
-feature-b = ["dep:optional-dep"]
-
-[profile.release]
-lto = true
-codegen-units = 1
-```
-
-### Module Structure
-
-```
-src/
-├── main.rs
-├── lib.rs
-├── config.rs
-├── error.rs
-├── models/
-│   ├── mod.rs
-│   └── user.rs
-├── services/
-│   ├── mod.rs
-│   └── user_service.rs
-└── handlers/
-    ├── mod.rs
-    └── user_handler.rs
-```
-
-```rust
-// src/lib.rs
-pub mod config;
-pub mod error;
-pub mod models;
-pub mod services;
-pub mod handlers;
-
-pub use error::Error;
-```
-
----
-
-## Quality Checklist
-
-- [ ] No unnecessary clones (use references)
-- [ ] Proper error handling (Result, ?)
-- [ ] Thread safety verified (Arc, Mutex where needed)
-- [ ] Lifetimes explicit where required
-- [ ] Tests cover edge cases
-- [ ] clippy warnings resolved
-- [ ] cargo fmt applied
-- [ ] Documentation for public API
-- [ ] No unwrap() in library code
-
----
-
-## Canonical Resources
-
-- [The Rust Book](https://doc.rust-lang.org/book/)
-- [Rust by Example](https://doc.rust-lang.org/rust-by-example/)
-- [Rustlings](https://github.com/rust-lang/rustlings)
-- [docs.rs](https://docs.rs/)
-- [Tokio Tutorial](https://tokio.rs/tokio/tutorial)
-- [Serde Documentation](https://serde.rs/)

agents/sql-expert.md

@@ -1,75 +0,0 @@
----
-name: sql-expert
-description: Master complex SQL queries, optimize execution plans, and ensure database integrity. Expert in index strategies and data modeling.
-model: sonnet
----
-
-# SQL Expert Agent
-
-You are a SQL expert specializing in complex queries, performance optimization, execution plan analysis, and database design.
-
-## Focus Areas
-- Creating sophisticated queries with CTEs and window functions
-- Query performance optimization and execution plan analysis
-- Normalized schema design for efficiency (1NF, 2NF, 3NF, BCNF)
-- Strategic index implementation (B-tree, hash, covering indexes)
-- Database statistics maintenance and review
-- Stored procedure encapsulation techniques
-- Transaction management for data integrity
-- Transaction isolation level understanding (READ COMMITTED, SERIALIZABLE, etc.)
-- Efficient join and subquery construction
-- Database performance monitoring and improvement
-
-## Methodology
-- Prioritize understanding business requirements first
-- Use CTEs for query readability and maintainability
-- Analyze EXPLAIN/EXPLAIN ANALYZE plans before optimization
-- Design balanced indexes (avoid over-indexing)
-- Choose appropriate data types to minimize storage
-- Handle NULL values explicitly in logic
-- Validate optimizations with benchmarking
-- Focus on query refactoring for performance gains
-- Write clear, well-commented SQL code
-- Update statistics regularly for query planner accuracy
-- Avoid premature optimization
-- Consider query plan caching implications
-
-## Quality Standards
-All deliverables must meet:
-- Consistent SQL formatting and style
-- Execution plan analysis documentation
-- Appropriate indexing strategy
-- Data integrity constraints (FK, CHECK, NOT NULL)
-- Efficient subquery and join usage
-- Stored procedure documentation
-- SQL best practices compliance
-- Comprehensive error handling
-- Normalized schema design (unless denormalization justified)
-- Removal of obsolete or unused indexes
-- Query result verification
-- Performance baseline measurements
-
-## Expected Deliverables
-- Optimized SQL queries with performance metrics
-- Execution plan analysis and recommendations
-- Index strategy recommendations with rationale
-- Schema documentation with ER diagrams
-- Transaction management details
-- Performance bottleneck identification
-- Query optimization reports (before/after metrics)
-- Well-commented, readable SQL code
-- Database health reports
-- Maintenance strategies (vacuum, reindex, etc.)
-- Migration scripts with rollback support
-- Data validation rules
-
-## Optimization Focus
-- Execution plan analysis (EXPLAIN ANALYZE)
-- Index strategy design and review
-- Query plan caching behavior
-- Partitioning decisions for large tables
-- Materialized view candidates
-- Connection pooling tuning
-
-## Related Skill
-For pattern reference (CTEs, window functions, JOINs), use **sql-ops** skill.

agents/typescript-expert.md

@@ -1,303 +0,0 @@
----
-name: typescript-expert
-description: Expert in TypeScript type system, generics, utility types, strict mode, declaration files, and type guards. Specializes in advanced type-level programming and type safety.
-model: sonnet
----
-
-# TypeScript Expert Agent
-
-You are a TypeScript expert specializing in the type system, advanced generics, utility types, and type-safe programming patterns.
-
-## Focus Areas
-- Type system fundamentals (primitive, union, intersection, literal types)
-- Advanced generics (constraints, inference, conditional types)
-- Built-in utility types (Partial, Required, Pick, Omit, Record, etc.)
-- Custom utility type creation
-- Strict mode configuration and benefits
-- Declaration files (.d.ts) authoring
-- Type guards and narrowing
-- Discriminated unions and exhaustive checking
-- Template literal types
-- Mapped types and key remapping
-- Module augmentation and declaration merging
-- Type inference optimization
-- tsconfig.json best practices
-- Migration from JavaScript to TypeScript
-
-## Key Approach Principles
-- Enable strict mode for maximum type safety
-- Use `unknown` over `any` when type is uncertain
-- Prefer type inference over explicit annotations when clear
-- Create reusable utility types for common patterns
-- Use discriminated unions for state management
-- Implement exhaustive checking with `never`
-- Define clear API boundaries with explicit types
-- Use branded/nominal types for type-safe IDs
-- Leverage const assertions for literal inference
-- Prefer interfaces for object shapes, types for unions/computed
-- Document complex types with JSDoc comments
-- Use satisfies operator for type checking without widening
-
-## Type System Mastery
-
-### Primitive Types
-```typescript
-string, number, boolean, null, undefined, symbol, bigint
-```
-
-### Special Types
-```typescript
-any       // Opt out of type checking (avoid)
-unknown   // Type-safe any (requires narrowing)
-never     // Impossible type (exhaustive checks)
-void      // No return value
-object    // Non-primitive type
-```
-
-### Union & Intersection
-```typescript
-type StringOrNumber = string | number;
-type Named = { name: string } & { age: number };
-```
-
-### Literal Types
-```typescript
-type Direction = 'north' | 'south' | 'east' | 'west';
-type HTTPStatus = 200 | 404 | 500;
-```
-
-## Advanced Generics
-
-### Basic Constraints
-```typescript
-function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
-  return obj[key];
-}
-```
-
-### Conditional Types
-```typescript
-type IsString<T> = T extends string ? true : false;
-type Flatten<T> = T extends Array<infer U> ? U : T;
-```
-
-### Mapped Types
-```typescript
-type Readonly<T> = { readonly [K in keyof T]: T[K] };
-type Optional<T> = { [K in keyof T]?: T[K] };
-```
-
-### Template Literal Types
-```typescript
-type EventName<T extends string> = `on${Capitalize<T>}`;
-type Getter<T extends string> = `get${Capitalize<T>}`;
-```
-
-## Built-in Utility Types
-
-### Object Manipulation
-```typescript
-Partial<T>        // All properties optional
-Required<T>       // All properties required
-Readonly<T>       // All properties readonly
-Pick<T, K>        // Select properties
-Omit<T, K>        // Exclude properties
-Record<K, T>      // Create object type
-```
-
-### Union Manipulation
-```typescript
-Exclude<T, U>     // Remove types from union
-Extract<T, U>     // Extract types from union
-NonNullable<T>    // Remove null/undefined
-```
-
-### Function Types
-```typescript
-ReturnType<T>     // Get function return type
-Parameters<T>     // Get function parameters tuple
-ConstructorParameters<T>  // Get constructor params
-InstanceType<T>   // Get class instance type
-```
-
-### String Manipulation
-```typescript
-Uppercase<T>      // Convert to uppercase
-Lowercase<T>      // Convert to lowercase
-Capitalize<T>     // Capitalize first letter
-Uncapitalize<T>   // Uncapitalize first letter
-```
-
-## Custom Utility Types
-
-### Deep Partial
-```typescript
-type DeepPartial<T> = {
-  [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
-};
-```
-
-### Deep Readonly
-```typescript
-type DeepReadonly<T> = {
-  readonly [K in keyof T]: T[K] extends object
-    ? DeepReadonly<T[K]>
-    : T[K];
-};
-```
-
-### Branded Types
-```typescript
-type Brand<T, B> = T & { __brand: B };
-type UserId = Brand<string, 'UserId'>;
-type OrderId = Brand<string, 'OrderId'>;
-```
-
-### Path Types
-```typescript
-type Path<T, P extends string> = P extends `${infer K}.${infer Rest}`
-  ? K extends keyof T
-    ? Path<T[K], Rest>
-    : never
-  : P extends keyof T
-    ? T[P]
-    : never;
-```
-
-## Type Guards & Narrowing
-
-### typeof Guards
-```typescript
-function process(value: string | number) {
-  if (typeof value === 'string') {
-    return value.toUpperCase(); // narrowed to string
-  }
-  return value.toFixed(2); // narrowed to number
-}
-```
-
-### Custom Type Guards
-```typescript
-function isUser(obj: unknown): obj is User {
-  return typeof obj === 'object'
-    && obj !== null
-    && 'id' in obj
-    && 'name' in obj;
-}
-```
-
-### Discriminated Unions
-```typescript
-type Success = { type: 'success'; data: string };
-type Error = { type: 'error'; message: string };
-type Result = Success | Error;
-
-function handle(result: Result) {
-  switch (result.type) {
-    case 'success': return result.data;
-    case 'error': return result.message;
-  }
-}
-```
-
-### Exhaustive Checking
-```typescript
-function assertNever(x: never): never {
-  throw new Error(`Unexpected value: ${x}`);
-}
-```
-
-## Strict Mode Configuration
-
-### Recommended tsconfig.json
-```json
-{
-  "compilerOptions": {
-    "strict": true,
-    "noUncheckedIndexedAccess": true,
-    "noImplicitReturns": true,
-    "noFallthroughCasesInSwitch": true,
-    "exactOptionalPropertyTypes": true,
-    "noPropertyAccessFromIndexSignature": true
-  }
-}
-```
-
-### Individual Strict Flags
-```
-strictNullChecks        // null/undefined not assignable
-strictFunctionTypes     // Contravariant function params
-strictBindCallApply     // Type-check bind/call/apply
-strictPropertyInitialization  // Require property init
-noImplicitAny           // Error on implicit any
-noImplicitThis          // Error on implicit this
-alwaysStrict            // Emit "use strict"
-```
-
-## Declaration Files
-
-### Ambient Declarations
-```typescript
-// global.d.ts
-declare global {
-  interface Window {
-    myApi: MyApiType;
-  }
-}
-
-declare module 'untyped-module' {
-  export function something(): void;
-}
-```
-
-### Module Augmentation
-```typescript
-// augment.d.ts
-import 'express';
-
-declare module 'express' {
-  interface Request {
-    user?: User;
-  }
-}
-```
-
-## Quality Assurance Standards
-
-All deliverables must meet:
-- Strict mode enabled (all strict flags)
-- No `any` types without justification
-- Explicit return types on exported functions
-- Comprehensive type coverage
-- Proper null/undefined handling
-- Type-safe error handling
-- Discriminated unions for state
-- Exhaustive switch statements
-- Proper generic constraints
-- No type assertions without validation
-
-## Expected Deliverables
-- Type-safe, well-structured TypeScript code
-- Custom utility types for project patterns
-- Declaration files for untyped dependencies
-- Strict tsconfig.json configuration
-- Type guard implementations
-- JSDoc documentation for complex types
-- Migration guides (JS to TS)
-- Type testing (with tsd or similar)
-- Generic type implementations
-- Error type hierarchies
-
-## Common Anti-Patterns to Avoid
-- Using `any` instead of `unknown`
-- Overusing type assertions (`as`)
-- Not enabling strict mode
-- Ignoring null/undefined checks
-- Using `!` non-null assertion excessively
-- Not constraining generics properly
-- Creating overly complex conditional types
-- Using `object` when specific type is known
-- Not using discriminated unions for state
-- Ignoring index signature access safety
-- Using type assertions instead of type guards
-- Not handling all union variants

agents/vue-expert.md

@@ -1,144 +0,0 @@
----
-name: vue-expert
-description: Expert in Vue.js 3 development including Composition API, Pinia state management, Vue Router, performance optimization, and modern Vue patterns. Use this agent for Vue component architecture, reactivity system, composables, SSR/SSG with Nuxt, TypeScript integration, and Vue ecosystem best practices.
-model: sonnet
----
-
-# Vue.js Expert Agent
-
-You are a Vue.js expert specializing in Vue 3, Composition API, state management with Pinia, performance optimization, and modern Vue development patterns.
-
-## Core Capabilities
-
-- Vue 3 Composition API and `<script setup>` syntax
-- Pinia state management (stores, getters, actions)
-- Vue Router configuration and navigation guards
-- Reactivity system (ref, reactive, computed, watch)
-- Custom composables for reusable logic
-- TypeScript integration with Vue
-- Performance optimization and lazy loading
-- SSR/SSG with Nuxt 3
-- Component design patterns and architecture
-- Testing with Vitest and Vue Test Utils
-
-## Official Documentation & Resources
-
-- [Vue.js Official Guide](https://vuejs.org/guide/introduction.html)
-- [Vue.js API Reference](https://vuejs.org/api/)
-- [Composition API FAQ](https://vuejs.org/guide/extras/composition-api-faq.html)
-- [Pinia Official Documentation](https://pinia.vuejs.org/)
-- [Vue Router Documentation](https://router.vuejs.org/)
-- [Nuxt 3 Documentation](https://nuxt.com/docs)
-- [VueUse Composables Library](https://vueuse.org/)
-- [Vue.js Style Guide](https://vuejs.org/style-guide/)
-- [Vue DevTools](https://devtools.vuejs.org/)
-- [Vue School Tutorials](https://vueschool.io/)
-- [Vue Mastery Courses](https://www.vuemastery.com/)
-- [Awesome Vue](https://github.com/vuejs/awesome-vue)
-
-## Expertise Areas
-
-### Composition API
-- `<script setup>` single-file component syntax
-- `ref()` for primitives, `reactive()` for objects
-- `computed()` for derived state
-- `watch()` and `watchEffect()` for side effects
-- `provide/inject` for dependency injection
-- Lifecycle hooks (onMounted, onUnmounted, etc.)
-- Template refs with `ref()` and `useTemplateRef()`
-
-### State Management (Pinia)
-- Store definition with `defineStore()`
-- State, getters, and actions
-- Store composition and modularity
-- Plugins and extensions
-- SSR hydration
-- DevTools integration and time-travel debugging
-- Lazy loading stores for performance
-
-### Performance Optimization
-- Component lazy loading with `defineAsyncComponent()`
-- Route-based code splitting
-- `v-memo` for expensive list rendering
-- `shallowRef` and `shallowReactive` for large objects
-- `markRaw()` for non-reactive data
-- Virtual scrolling for long lists
-- Suspense for async component loading
-- Keep-alive for component caching
-
-### Vue Router
-- Route configuration and nested routes
-- Navigation guards (beforeEach, beforeEnter)
-- Route meta fields
-- Lazy loading routes
-- Dynamic route matching
-- Scroll behavior customization
-- Route transitions
-
-## When to Use This Agent
-
-- Designing Vue 3 component architecture
-- Implementing Composition API patterns
-- Setting up Pinia stores for complex state
-- Optimizing Vue application performance
-- Migrating from Options API to Composition API
-- Integrating TypeScript with Vue
-- Building SSR/SSG applications with Nuxt
-- Creating reusable composables
-- Debugging reactivity issues
-- Configuring Vue Router for SPAs
-
-## Component Patterns
-
-### Composables (Reusable Logic)
-- Prefix with `use` (e.g., `useCounter`, `useFetch`)
-- Return refs and functions
-- Handle cleanup in `onUnmounted`
-- Accept refs as arguments for reactivity
-
-### Props and Events
-- Use `defineProps()` with TypeScript generics
-- Use `defineEmits()` for type-safe events
-- `withDefaults()` for default prop values
-- `defineModel()` for v-model bindings (Vue 3.4+)
-
-### Slots and Provide/Inject
-- Named slots for flexible composition
-- Scoped slots for data passing
-- `provide()` / `inject()` for deep prop drilling avoidance
-- Use InjectionKey for type-safe injection
-
-## Anti-Patterns to Avoid
-
-- Mutating props directly (use events instead)
-- Overusing reactive() when ref() suffices
-- Not cleaning up side effects in composables
-- Putting too much logic in components (extract to composables)
-- Using Vuex in new Vue 3 projects (use Pinia)
-- Ignoring TypeScript benefits
-- Not leveraging `<script setup>` syntax
-- Creating God components (split into smaller units)
-- Blocking renders with synchronous operations
-- Not using Vue DevTools for debugging
-
-## TypeScript Integration
-
-- Use `defineComponent()` for type inference in Options API
-- Prefer `<script setup lang="ts">` for Composition API
-- Type props with generics: `defineProps<{ msg: string }>()`
-- Type emits: `defineEmits<{ change: [id: number] }>()`
-- Use `PropType` for complex prop types
-- Leverage IDE support with Volar extension
-
-## Testing Strategies
-
-- Unit test composables in isolation
-- Use `@vue/test-utils` for component testing
-- Mock Pinia stores with `createTestingPinia()`
-- Test with Vitest for speed
-- Snapshot testing for UI consistency
-- E2E testing with Cypress or Playwright
-
----
-
-*Refer to official Vue.js documentation for code samples and implementation details.*

docs/ARCHITECTURE.md

@@ -317,20 +317,20 @@ Agents are markdown files in `agents/` or `.claude/agents/`:
 
 ```yaml
 ---
-name: react-expert
-description: Expert in React hooks, state management, and performance
+name: cypress-expert
+description: Expert in Cypress E2E and component testing, custom commands, and CI integration
 model: sonnet
 ---
 
-# React Expert
+# Cypress Expert
 
-You are a React expert specializing in modern React patterns...
+You are a Cypress expert specializing in reliable end-to-end testing...
 
 ## Core Expertise
-- Hooks and custom hooks
-- State management (Context, Zustand, Jotai)
-- Performance optimization
-- Server Components
+- E2E and component test architecture
+- Custom commands and page objects
+- Network stubbing and fixtures
+- CI integration and flake reduction
 
 ## Patterns
 [Detailed patterns and examples...]
@@ -338,13 +338,13 @@ You are a React expert specializing in modern React patterns...
 
 ### Example Usage
 
-When Claude encounters a React-specific question, it can spawn the react-expert:
+When Claude encounters a Cypress-specific question, it can spawn the cypress-expert:
 
 ```
-User: "How should I optimize this component that re-renders too often?"
+User: "Why do these E2E tests pass locally but flake in CI?"
 
-Claude: I'll consult the react-expert agent for specialized guidance.
-[Uses Task tool with subagent_type="react-expert"]
+Claude: I'll consult the cypress-expert agent for specialized guidance.
+[Uses Task tool with subagent_type="cypress-expert"]
 ```
 
 ### References

docs/PLAN.md

@@ -15,7 +15,7 @@
 
 | Component | Count | Notes |
 |-----------|-------|-------|
-| Agents | 23 | Domain experts + git-agent background worker (cull in progress — see below) |
+| Agents | 12 | Domain experts without skill twins + git-agent background worker |
 | Skills | 80 | Operational skills, CLI tools, workflows, diagnostics, security |
 | Commands | 2 | Session management (sync, save) |
 | Rules | 7 | cli-tools, commit-style, naming-conventions, prompt-injection, skill-agent-updates, supply-chain, worktree-boundaries |
@@ -39,10 +39,10 @@ Counts are enforced by the CI doc-drift gate (see roadmap) — if this table rot
 
 ### Phase 2 — Skills-first restructure (v3.0)
 
-- [ ] **Agent cull**: deprecate language/framework experts with `-ops` skill twins
-      (python, typescript, javascript, go, rust, react, vue, astro, laravel).
-      Fold unique agent content into the twin skill first. Keep: git-agent,
-      claude-architect, firecrawl-expert, niche experts without skill twins.
+- [x] **Agent cull**: deprecated 11 experts with `-ops` skill twins (python,
+      typescript, javascript, go, rust, react, vue, astro, laravel, sql,
+      postgres). Unique content folded into twin skills; dispatching skills
+      now route general-purpose agents with skill preloading. 23 → 12 agents.
 - [ ] **claude-code-internals**: merge + refresh claude-code-debug /
       claude-code-headless / claude-code-hooks against current official docs
       (new hook events, skill frontmatter fields, CLI flags).

rules/naming-conventions.md

@@ -19,17 +19,16 @@ Consistent naming patterns for all claude-mods components.
 
 | Pattern | Example | Notes |
 |---------|---------|-------|
-| Language | `python-expert.md` | Programming languages |
-| Framework | `laravel-expert.md` | Frameworks |
-| Tool | `docker-expert.md` | Specific tools |
+| Framework | `craftcms-expert.md` | Frameworks/CMS |
+| Tool | `cypress-expert.md` | Specific tools |
 | Domain | `aws-fargate-ecs-expert.md` | Compound domains |
-| Specialized | `playwright-roulette-expert.md` | Project-specific |
+| Specialized | `asus-router-expert.md` | Niche/device-specific |
 
 **Frontmatter:**
 
 ```yaml
 ---
-name: python-expert          # Match filename (without .md)
+name: cypress-expert         # Match filename (without .md)
 description: <one line>      # Concise capability summary
 model: sonnet|opus|haiku     # Recommended model
 ---
@@ -181,13 +180,13 @@ depends_on: [bad]     # snake_case wrong
 ## Anti-patterns
 
 ```
-BAD:  Python-Expert.md       - PascalCase
-BAD:  python_expert.md       - snake_case
-BAD:  pythonExpert.md        - camelCase
-GOOD: python-expert.md       - kebab-case
+BAD:  Cypress-Expert.md      - PascalCase
+BAD:  cypress_expert.md      - snake_case
+BAD:  cypressExpert.md       - camelCase
+GOOD: cypress-expert.md      - kebab-case
 
 BAD:  skills/PythonPatterns/ - PascalCase directory
-GOOD: skills/python-ops/
+GOOD: skills/python-pytest-ops/
 
 BAD:  commands/TestGen.md    - PascalCase
 GOOD: commands/testgen.md    - Concatenated lowercase
@@ -200,7 +199,7 @@ GOOD: vesper.md              - lowercase
 
 | Component | Pattern | Example |
 |-----------|---------|---------|
-| Agent | `{domain}-expert.md` | `docker-expert.md` |
+| Agent | `{domain}-expert.md` | `cypress-expert.md` |
 | Skill | `{topic}-ops/SKILL.md` | `postgres-ops/SKILL.md` |
 | Command | `{action}.md` | `review.md` |
 | Rule | `{topic}.md` | `commit-style.md` |

scripts/install.ps1

@@ -42,7 +42,20 @@ $deprecated = @(
     "$claudeDir\commands\pulse.md",
     "$claudeDir\skills\conclave",
     "$claudeDir\skills\claude-code-templates",  # Replaced by skill-creator
-    "$claudeDir\skills\agentmail"               # Renamed to pigeon (v2.3.0)
+    "$claudeDir\skills\agentmail",              # Renamed to pigeon (v2.3.0)
+
+    # Deprecated agents (v3.0): folded into their -ops skill twins
+    "$claudeDir\agents\python-expert.md",
+    "$claudeDir\agents\typescript-expert.md",
+    "$claudeDir\agents\javascript-expert.md",
+    "$claudeDir\agents\go-expert.md",
+    "$claudeDir\agents\rust-expert.md",
+    "$claudeDir\agents\react-expert.md",
+    "$claudeDir\agents\vue-expert.md",
+    "$claudeDir\agents\astro-expert.md",
+    "$claudeDir\agents\laravel-expert.md",
+    "$claudeDir\agents\sql-expert.md",
+    "$claudeDir\agents\postgres-expert.md"
 )
 
 # Renamed skills: -patterns -> -ops (March 2026)

scripts/install.sh

@@ -57,6 +57,19 @@ deprecated_items=(
     "$CLAUDE_DIR/skills/conclave"                # Deprecated
     "$CLAUDE_DIR/skills/claude-code-templates"   # Replaced by skill-creator
     "$CLAUDE_DIR/skills/agentmail"               # Renamed to pigeon (v2.3.0)
+
+    # Deprecated agents (v3.0): folded into their -ops skill twins
+    "$CLAUDE_DIR/agents/python-expert.md"
+    "$CLAUDE_DIR/agents/typescript-expert.md"
+    "$CLAUDE_DIR/agents/javascript-expert.md"
+    "$CLAUDE_DIR/agents/go-expert.md"
+    "$CLAUDE_DIR/agents/rust-expert.md"
+    "$CLAUDE_DIR/agents/react-expert.md"
+    "$CLAUDE_DIR/agents/vue-expert.md"
+    "$CLAUDE_DIR/agents/astro-expert.md"
+    "$CLAUDE_DIR/agents/laravel-expert.md"
+    "$CLAUDE_DIR/agents/sql-expert.md"
+    "$CLAUDE_DIR/agents/postgres-expert.md"
 )
 
 # Renamed skills: -patterns -> -ops (March 2026)

skills/astro-ops/SKILL.md

@@ -177,6 +177,19 @@ const { Content, headings } = await post.render();
 <Content />
 ```
 
+### Content Collections vs External CMS
+
+| Criterion | Content Collections | External CMS (Payload, etc.) |
+|-----------|--------------------|-----------------------------|
+| Content type | Local markdown/MDX, docs, blogs | Relational data models |
+| Authors | Developers (version-controlled) | Editors (admin UI, multi-user auth) |
+| Validation | Type-safe via Zod at build time | CMS-side schemas + API contracts |
+| Update cadence | Deploys with the site | Independent of deployments |
+| API needs | None (build-time queries) | REST/GraphQL for other consumers |
+| Workflow | Git PRs, simple review | Editorial workflows, drafts, roles |
+
+Rule of thumb: start with Content Collections; reach for a CMS only when non-developers need to publish without a deploy, or when content is genuinely relational.
+
 ## Project Structure Reference
 
 ```
@@ -371,6 +384,17 @@ npx astro add node
 | View Transitions break scripts | `DOMContentLoaded` only fires once with View Transitions | Use `astro:page-load` event instead, which fires on every navigation |
 | Env vars missing in production | `.env` not loaded or platform env vars not configured | Use `envField` in astro.config.mjs for validation; set vars in platform dashboard |
 
+## Production Security Checklist
+
+For every production deployment, address:
+
+- **CSP headers** - configure a restrictive `Content-Security-Policy` (see middleware patterns in `references/deployment.md`)
+- **Remote image restrictions** - enforce explicit `image.domains` / `remotePatterns` allow-lists; never derive image URLs from user input (SSRF risk)
+- **Host header validation** - verify the request host matches expected domains in middleware (SSR/hybrid only)
+- **Secrets management** - on Cloudflare, use Workers Bindings (`wrangler secret put`), not env vars baked into code; elsewhere use platform secret stores
+- **HTTPS only** - ensure all external resources (scripts, images, fonts) load over HTTPS
+- **Input validation** - sanitize all user input in SSR contexts (query params, form bodies, cookies)
+
 ## Reference Files
 
 | File | Contents | Lines |

skills/doc-scanner/templates.md

@@ -13,8 +13,8 @@ Brief description of the project and what it does.
 
 | Task | Agent | Example Prompt |
 |------|-------|----------------|
-| Code review | `javascript-expert` | "Review this PR for issues" |
-| Database work | `sql-expert` | "Optimize this query" |
+| E2E testing | `cypress-expert` | "Stabilize these flaky tests" |
+| Web scraping | `firecrawl-expert` | "Extract structured data from this site" |
 | Deployment | `bash-expert` | "Deploy to staging" |
 
 ## Primary Agents

skills/explain/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: explain
-description: "Deep explanation of complex code, files, or concepts. Routes to expert agents, uses structural search, generates mermaid diagrams. Triggers on: explain, deep dive, how does X work, architecture, data flow."
+description: "Deep explanation of complex code, files, or concepts. Dispatches skill-preloaded agents, uses structural search, generates mermaid diagrams. Triggers on: explain, deep dive, how does X work, architecture, data flow."
 license: MIT
 compatibility: "Uses ast-grep, tokei, rg, fd if available. Falls back to standard tools."
 allowed-tools: "Read Glob Grep Bash Task"
@@ -11,7 +11,7 @@ metadata:
 
 # Explain - Deep Code Explanation
 
-Get a comprehensive explanation of code, files, directories, or architectural concepts. Automatically routes to the most relevant expert agent and uses modern CLI tools for analysis.
+Get a comprehensive explanation of code, files, directories, or architectural concepts. Automatically dispatches a general-purpose agent preloaded with the most relevant `-ops` skill and uses modern CLI tools for analysis.
 
 ## Arguments
 
@@ -38,14 +38,14 @@ $ARGUMENTS
     |     +- Find related: tests, types, docs
     |     +- Load: AGENTS.md, CLAUDE.md conventions
     |
-    +-> Step 3: Route to Expert Agent
-    |     +- .ts/.tsx -> typescript-expert or react-expert
-    |     +- .py -> python-expert
-    |     +- .vue -> vue-expert
-    |     +- .sql/migrations -> postgres-expert
+    +-> Step 3: Route to Explainer (general-purpose + skill preload)
+    |     +- .ts/.tsx -> general-purpose, preload typescript-ops or react-ops
+    |     +- .py -> general-purpose, preload python-* skill by topic
+    |     +- .vue -> general-purpose, preload vue-ops
+    |     +- .sql/migrations -> general-purpose, preload postgres-ops
     |     +- agents/skills/commands -> claude-architect
     |     +- Default -> general-purpose
-    |     +- All experts preload: debug-ops (systematic analysis)
+    |     +- All explainers preload: debug-ops (systematic analysis)
     |
     +-> Step 4: Generate Explanation
     |     +- Structured markdown with sections
@@ -115,30 +115,31 @@ fd -e d.ts -e types.ts | xargs rg -l "$TARGET" 2>/dev/null
 - Read CLAUDE.md if exists
 - Check for framework-specific patterns
 
-### Step 3: Route to Expert Agent
+### Step 3: Route to Explainer
 
-Determine the best expert based on file extension and content:
+Dispatch is skills-first: the generic `general-purpose` subagent preloads the relevant `-ops` skill based on file extension and content:
 
-| Pattern | Primary Agent | Condition |
-|---------|---------------|-----------|
-| `.ts` | typescript-expert | No JSX/React imports |
-| `.tsx` | react-expert | JSX present |
-| `.js`, `.jsx` | javascript-expert | - |
-| `.py` | python-expert | - |
-| `.vue` | vue-expert | - |
-| `.sql`, `migrations/*` | postgres-expert | - |
-| `agents/*.md`, `skills/*`, `commands/*` | claude-architect | Claude extensions |
-| `*.test.*`, `*.spec.*` | (framework expert) | Route by file type |
-| Other | general-purpose | Fallback |
+| Pattern | Dispatch | Preload | Condition |
+|---------|----------|---------|-----------|
+| `.ts` | general-purpose | `skills/typescript-ops/SKILL.md` | No JSX/React imports |
+| `.tsx` | general-purpose | `skills/react-ops/SKILL.md` | JSX present |
+| `.js`, `.jsx` | general-purpose | `skills/javascript-ops/SKILL.md` | - |
+| `.py` | general-purpose | relevant `skills/python-*/SKILL.md` by topic | - |
+| `.vue` | general-purpose | `skills/vue-ops/SKILL.md` | - |
+| `.sql`, `migrations/*` | general-purpose | `skills/postgres-ops/SKILL.md` | - |
+| `agents/*.md`, `skills/*`, `commands/*` | claude-architect | - | Claude extensions |
+| `*.test.*`, `*.spec.*` | general-purpose | (framework skill by file type) | - |
+| Other | general-purpose | - | Fallback |
 
 **Invoke via Task tool:**
 ```
-Task tool with subagent_type: "[detected]-expert"
+Task tool with subagent_type: "general-purpose" (or claude-architect for Claude extensions)
 model: "sonnet"
 Prompt includes:
   - Skill preloading (domain knowledge):
-    "First, read this file for systematic analysis methodology:
-     - Read: skills/debug-ops/SKILL.md"
+    "First, read these files for analysis context:
+     - Read: skills/debug-ops/SKILL.md
+     - Read: [Preload column for the matched pattern]"
   - File content
   - Related files found
   - Project conventions
@@ -147,7 +148,7 @@ Prompt includes:
 
 ### Step 4: Generate Explanation
 
-The expert agent produces a structured explanation:
+The dispatched agent produces a structured explanation:
 
 ```markdown
 # Explanation: [target]
@@ -337,4 +338,4 @@ This keeps valuable architectural knowledge in git-tracked documentation.
 - Complex systems may need multiple `/explain` calls
 - Use `--deep` for unfamiliar codebases
 - Mermaid diagrams render in GitHub, GitLab, VSCode, and most markdown viewers
-- Expert agents provide framework-specific insights
+- Preloaded `-ops` skills provide framework-specific insights

skills/go-ops/SKILL.md

@@ -302,6 +302,7 @@ Load these for deep-dive topics. Each is self-contained.
 | `./references/interfaces-generics.md` | Interface design, embedding, type assertions, generics, type constraints |
 | `./references/project-structure.md` | Standard layout, go.mod, workspaces, build tags, ldflags, golangci-lint |
 | `./references/performance.md` | pprof, trace, benchmarks, escape analysis, sync.Pool, struct alignment |
+| `./references/expert-insights.md` | HTTP server (Go 1.22 routing), graceful shutdown, http.Client tuning, JSON helpers |
 
 ## See Also
 

skills/go-ops/references/expert-insights.md

@@ -0,0 +1,154 @@
+# Go HTTP and Service Patterns Reference
+
+## Table of Contents
+
+1. [HTTP Server (Go 1.22+ Routing)](#1-http-server-go-122-routing)
+2. [Graceful Shutdown](#2-graceful-shutdown)
+3. [HTTP Client Configuration](#3-http-client-configuration)
+4. [JSON Request/Response Helpers](#4-json-requestresponse-helpers)
+
+---
+
+## 1. HTTP Server (Go 1.22+ Routing)
+
+Go 1.22 added method matching and path wildcards to `net/http.ServeMux` — no router dependency needed for most services.
+
+```go
+func main() {
+    mux := http.NewServeMux()
+
+    mux.HandleFunc("GET /users/{id}", getUser)
+    mux.HandleFunc("POST /users", createUser)
+
+    server := &http.Server{
+        Addr:         ":8080",
+        Handler:      mux,
+        ReadTimeout:  5 * time.Second,
+        WriteTimeout: 10 * time.Second,
+        IdleTimeout:  120 * time.Second,
+    }
+
+    log.Fatal(server.ListenAndServe())
+}
+
+func getUser(w http.ResponseWriter, r *http.Request) {
+    id := r.PathValue("id") // Wildcard value from the pattern
+
+    user, err := userStore.GetUser(id)
+    if err != nil {
+        http.Error(w, "User not found", http.StatusNotFound)
+        return
+    }
+
+    w.Header().Set("Content-Type", "application/json")
+    json.NewEncoder(w).Encode(user)
+}
+```
+
+Always set `ReadTimeout`, `WriteTimeout`, and `IdleTimeout` on `http.Server` — the zero values mean no timeout, which leaves the server open to slow-client resource exhaustion.
+
+## 2. Graceful Shutdown
+
+Drain in-flight requests on SIGINT/SIGTERM instead of dropping them.
+
+```go
+func main() {
+    cfg, err := config.Load()
+    if err != nil {
+        log.Fatalf("loading config: %v", err)
+    }
+
+    server := &http.Server{
+        Addr:    cfg.Addr,
+        Handler: handler.New(cfg),
+    }
+
+    go func() {
+        sigCh := make(chan os.Signal, 1)
+        signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM)
+        <-sigCh
+
+        ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+        defer cancel()
+
+        if err := server.Shutdown(ctx); err != nil {
+            log.Printf("shutdown error: %v", err)
+        }
+    }()
+
+    log.Printf("starting server on %s", cfg.Addr)
+    if err := server.ListenAndServe(); err != http.ErrServerClosed {
+        log.Fatalf("server error: %v", err)
+    }
+}
+```
+
+`server.Shutdown` stops accepting new connections, then waits for active requests up to the context deadline. Compare against `http.ErrServerClosed` — a clean shutdown returns it, and treating it as fatal masks the difference between intentional and crashed exits.
+
+## 3. HTTP Client Configuration
+
+Never use `http.DefaultClient` for production calls — it has no timeout. Build a client once and reuse it (the transport pools connections).
+
+```go
+func NewHTTPClient() *http.Client {
+    return &http.Client{
+        Timeout: 30 * time.Second,
+        Transport: &http.Transport{
+            MaxIdleConns:        100,
+            MaxIdleConnsPerHost: 10,
+            IdleConnTimeout:     90 * time.Second,
+        },
+    }
+}
+
+func fetchJSON(ctx context.Context, url string, result any) error {
+    req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
+    if err != nil {
+        return err
+    }
+
+    resp, err := httpClient.Do(req)
+    if err != nil {
+        return err
+    }
+    defer resp.Body.Close()
+
+    if resp.StatusCode != http.StatusOK {
+        return fmt.Errorf("unexpected status: %d", resp.StatusCode)
+    }
+
+    return json.NewDecoder(resp.Body).Decode(result)
+}
+```
+
+`MaxIdleConnsPerHost` defaults to 2 — far too low when hammering a single upstream; raise it for service-to-service traffic.
+
+## 4. JSON Request/Response Helpers
+
+Centralize encoding/decoding so every handler behaves the same.
+
+```go
+type Response struct {
+    Data    any    `json:"data,omitempty"`
+    Error   string `json:"error,omitempty"`
+    Message string `json:"message,omitempty"`
+}
+
+func writeJSON(w http.ResponseWriter, status int, data any) {
+    w.Header().Set("Content-Type", "application/json")
+    w.WriteHeader(status)
+    json.NewEncoder(w).Encode(data)
+}
+
+func readJSON(r *http.Request, dst any) error {
+    dec := json.NewDecoder(r.Body)
+    dec.DisallowUnknownFields() // Reject payloads with unexpected keys
+
+    if err := dec.Decode(dst); err != nil {
+        return fmt.Errorf("decoding JSON: %w", err)
+    }
+    return nil
+}
+```
+
+`DisallowUnknownFields` turns silent typos in client payloads (`"emial"`) into explicit 400s instead of zero-valued fields.

skills/javascript-ops/SKILL.md

@@ -273,6 +273,7 @@ class AppError extends Error {
 | `references/modules-runtime.md` | ESM/CJS/dual packages, dynamic import, V8 internals, memory management, event loop deep dive |
 | `references/modern-features.md` | ES2022-2025 feature details, Proxy/Reflect, Decorators, Temporal, Explicit Resource Management |
 | `references/node-patterns.md` | node:test runner, fs/promises, worker_threads, streams, crypto, graceful shutdown, permission model |
+| `references/expert-insights.md` | Browser-side patterns: DOM batching, event delegation, debounce/throttle, memoization, lazy loading, XSS/CSP client security |
 
 ---
 

skills/javascript-ops/references/expert-insights.md

@@ -0,0 +1,272 @@
+# Browser Performance & Security Reference
+
+Browser-side patterns — DOM performance, rate limiting user events, and client-side security hardening.
+
+---
+
+## DOM Performance
+
+### Batch DOM Updates
+
+Every DOM read after a write forces a synchronous layout (reflow). Batch reads together, then writes.
+
+```javascript
+// BAD — interleaved read/write forces layout thrashing
+elements.forEach(el => {
+  const height = el.offsetHeight;     // read (forces layout)
+  el.style.height = `${height * 2}px`; // write (invalidates layout)
+});
+
+// GOOD — read everything, then write everything
+const heights = elements.map(el => el.offsetHeight); // all reads
+elements.forEach((el, i) => {
+  el.style.height = `${heights[i] * 2}px`;           // all writes
+});
+
+// GOOD — build off-DOM, insert once
+const fragment = document.createDocumentFragment();
+for (const item of items) {
+  const li = document.createElement('li');
+  li.textContent = item.name;
+  fragment.append(li);
+}
+list.append(fragment); // single reflow
+```
+
+### Cache DOM Queries
+
+```javascript
+// BAD — re-queries the DOM on every call
+function updateCounter(value) {
+  document.querySelector('#counter').textContent = value;
+}
+
+// GOOD — query once, reuse the reference
+const counter = document.querySelector('#counter');
+function updateCounter(value) {
+  counter.textContent = value;
+}
+```
+
+### requestAnimationFrame for Visual Updates
+
+```javascript
+// Sync visual updates to the browser's paint cycle — never setInterval for animation
+function animate(timestamp) {
+  element.style.transform = `translateX(${computePosition(timestamp)}px)`;
+  if (!done) requestAnimationFrame(animate);
+}
+requestAnimationFrame(animate);
+
+// Coalesce rapid events (scroll, resize, mousemove) to one update per frame
+let scheduled = false;
+window.addEventListener('scroll', () => {
+  if (scheduled) return;
+  scheduled = true;
+  requestAnimationFrame(() => {
+    updateScrollIndicator();
+    scheduled = false;
+  });
+});
+```
+
+---
+
+## Event Delegation
+
+Attach one listener to a common ancestor instead of one per element — essential for dynamic lists where children come and go.
+
+```javascript
+// BAD — N listeners, breaks for elements added later
+document.querySelectorAll('.item button').forEach(btn => {
+  btn.addEventListener('click', handleClick);
+});
+
+// GOOD — one listener handles all current AND future children
+document.querySelector('#list').addEventListener('click', (event) => {
+  const button = event.target.closest('button[data-action]');
+  if (!button) return;
+
+  switch (button.dataset.action) {
+    case 'delete': deleteItem(button.closest('.item')); break;
+    case 'edit':   editItem(button.closest('.item'));   break;
+  }
+});
+```
+
+**Cleanup discipline:** every `addEventListener` needs a removal path. Prefer `{ signal }` for bulk cleanup:
+
+```javascript
+const controller = new AbortController();
+window.addEventListener('resize', onResize, { signal: controller.signal });
+window.addEventListener('scroll', onScroll, { signal: controller.signal });
+
+// Tear down everything at once
+controller.abort();
+```
+
+---
+
+## Debounce and Throttle
+
+| Pattern | Behavior | Use For |
+|---------|----------|---------|
+| Debounce | Fires once after events STOP for N ms | Search-as-you-type, form validation, resize-end |
+| Throttle | Fires at most once per N ms while events continue | Scroll handlers, mousemove, drag, analytics pings |
+
+```javascript
+function debounce(fn, ms) {
+  let timer;
+  return function (...args) {
+    clearTimeout(timer);
+    timer = setTimeout(() => fn.apply(this, args), ms);
+  };
+}
+
+function throttle(fn, ms) {
+  let last = 0;
+  let trailing;
+  return function (...args) {
+    const now = Date.now();
+    const remaining = ms - (now - last);
+    if (remaining <= 0) {
+      last = now;
+      fn.apply(this, args);
+    } else {
+      // Trailing call so the final event isn't dropped
+      clearTimeout(trailing);
+      trailing = setTimeout(() => {
+        last = Date.now();
+        fn.apply(this, args);
+      }, remaining);
+    }
+  };
+}
+
+// Usage
+searchInput.addEventListener('input', debounce(e => search(e.target.value), 300));
+window.addEventListener('scroll', throttle(updatePosition, 100));
+```
+
+---
+
+## Memoization
+
+Cache results of pure, expensive functions keyed by their arguments.
+
+```javascript
+function memoize(fn, keyFn = (...args) => JSON.stringify(args)) {
+  const cache = new Map();
+  return function (...args) {
+    const key = keyFn(...args);
+    if (!cache.has(key)) {
+      cache.set(key, fn.apply(this, args));
+    }
+    return cache.get(key);
+  };
+}
+
+const expensiveLayout = memoize(computeLayout);
+
+// For object arguments, key on identity with WeakMap — entries GC with the object
+function memoizeByRef(fn) {
+  const cache = new WeakMap();
+  return (obj) => {
+    if (!cache.has(obj)) cache.set(obj, fn(obj));
+    return cache.get(obj);
+  };
+}
+```
+
+**Caveats:** only memoize pure functions; bound caches (Map) grow forever — use `WeakMap`, an LRU, or explicit invalidation for long-lived apps.
+
+---
+
+## Lazy Loading
+
+```javascript
+// Native — images and iframes
+// <img src="photo.jpg" loading="lazy" alt="...">
+
+// IntersectionObserver — anything else (infinite scroll, deferred widgets)
+const observer = new IntersectionObserver((entries) => {
+  for (const entry of entries) {
+    if (!entry.isIntersecting) continue;
+    hydrateWidget(entry.target);
+    observer.unobserve(entry.target); // one-shot
+  }
+}, { rootMargin: '200px' }); // start loading before it's visible
+
+document.querySelectorAll('[data-lazy-widget]').forEach(el => observer.observe(el));
+```
+
+---
+
+## Client-Side Security
+
+### XSS — Never Interpolate Untrusted Data into HTML
+
+```javascript
+// BAD — untrusted string becomes live markup
+element.innerHTML = `<p>${userComment}</p>`; // <img src=x onerror=...> executes
+
+// GOOD — textContent never parses HTML
+const p = document.createElement('p');
+p.textContent = userComment;
+element.append(p);
+
+// GOOD — when HTML structure is required, sanitize first (DOMPurify)
+element.innerHTML = DOMPurify.sanitize(userHtml);
+```
+
+Other injection sinks to treat the same way: `outerHTML`, `insertAdjacentHTML`, `document.write`, `eval`, `new Function(string)`, `setTimeout('string')`, and `javascript:` URLs in `href`/`src`.
+
+### URL and Attribute Context
+
+```javascript
+// Validate URLs before assigning to href/src — block javascript: scheme
+function safeUrl(raw) {
+  try {
+    const url = new URL(raw, location.origin);
+    return ['https:', 'http:', 'mailto:'].includes(url.protocol) ? url.href : '#';
+  } catch {
+    return '#';
+  }
+}
+link.href = safeUrl(userProvidedUrl);
+```
+
+### Content Security Policy
+
+A CSP header is the backstop when an injection slips through — it blocks inline scripts and unauthorized sources.
+
+```
+Content-Security-Policy: default-src 'self';
+  script-src 'self' 'nonce-{random}';
+  object-src 'none';
+  base-uri 'none'
+```
+
+- Prefer nonces or hashes over `'unsafe-inline'`
+- `object-src 'none'` and `base-uri 'none'` close legacy vectors
+- Start with `Content-Security-Policy-Report-Only` to find violations before enforcing
+
+### Storage and Secrets
+
+| Data | Where | Why |
+|------|-------|-----|
+| Session tokens | `httpOnly` + `Secure` + `SameSite` cookie | JS cannot read it — XSS can't exfiltrate |
+| Non-sensitive prefs | `localStorage` | Fine — but any XSS can read it |
+| Secrets / API keys | Never in client code | Bundles are public; proxy through a server |
+
+```javascript
+// localStorage values are untrusted on read — they survive across sessions
+// and any prior XSS could have poisoned them
+const raw = localStorage.getItem('prefs');
+let prefs;
+try {
+  prefs = PrefsSchema.parse(JSON.parse(raw)); // validate, don't trust
+} catch {
+  prefs = DEFAULT_PREFS;
+}
+```

skills/laravel-ops/SKILL.md

@@ -422,6 +422,7 @@ $this->assertSoftDeleted('posts', ['id' => $post->id]);
 - [Laravel 11 Documentation](https://laravel.com/docs/11.x)
 - [Pest PHP](https://pestphp.com/)
 - [Laravel Horizon](https://laravel.com/docs/11.x/horizon) - Queue monitoring
+- [Laravel Telescope](https://laravel.com/docs/11.x/telescope) - Local debugging and request/query monitoring
 - [Laravel Octane](https://laravel.com/docs/11.x/octane) - High-performance serving
 - [Laravel Forge](https://forge.laravel.com/) - Server management
 - [Laravel Vapor](https://vapor.laravel.com/) - Serverless deployment

skills/perf-ops/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: perf-ops
-description: "Performance profiling and optimization orchestrator - diagnoses symptoms, dispatches profiling to language experts, manages before/after comparisons. Triggers on: performance, profiling, flamegraph, pprof, py-spy, clinic.js, memray, heaptrack, bundle size, webpack analyzer, load testing, k6, artillery, vegeta, locust, benchmark, hyperfine, criterion, slow query, EXPLAIN ANALYZE, N+1, caching, optimization, latency, throughput, p99, memory leak, CPU spike, bottleneck."
+description: "Performance profiling and optimization orchestrator - diagnoses symptoms, dispatches skill-preloaded profiling agents, manages before/after comparisons. Triggers on: performance, profiling, flamegraph, pprof, py-spy, clinic.js, memray, heaptrack, bundle size, webpack analyzer, load testing, k6, artillery, vegeta, locust, benchmark, hyperfine, criterion, slow query, EXPLAIN ANALYZE, N+1, caching, optimization, latency, throughput, p99, memory leak, CPU spike, bottleneck."
 license: MIT
 allowed-tools: "Read Edit Write Bash Glob Grep Agent TaskCreate TaskUpdate"
 metadata:
@@ -10,7 +10,7 @@ metadata:
 
 # Performance Operations
 
-Orchestrator for cross-language performance profiling and optimization. Classifies symptoms inline, dispatches profiling to language expert agents (background), and manages optimization with confirmation.
+Orchestrator for cross-language performance profiling and optimization. Classifies symptoms inline, dispatches profiling to general-purpose agents preloaded with the relevant language `-ops` skill (background), and manages optimization with confirmation.
 
 ## Architecture
 
@@ -25,11 +25,11 @@ User describes performance issue or requests profiling
     |       +---> Gather system baseline (CPU/mem/disk)
     |       +---> Present: diagnosis + recommended profiling approach
     |
-    +---> T2: Profile (dispatch to language expert, background)
-    |       +---> Select expert agent from routing table
+    +---> T2: Profile (dispatch general-purpose + skill preload, background)
+    |       +---> Select skill preload from routing table
     |       +---> Build perf-focused dispatch prompt
-    |       +---> Expert runs profiler, collects data, interprets results
-    |       |       +---> Fallback: general-purpose with tool commands inlined
+    |       +---> Agent runs profiler, collects data, interprets results
+    |       |       +---> Fallback: tool commands inlined (no skill preload)
     |       +---> Returns: findings + bottleneck identification + suggestions
     |       |
     |       +---> [Optional parallel dispatch]:
@@ -37,8 +37,8 @@ User describes performance issue or requests profiling
     |             +---> Memory profiling agent --+--> Consolidate findings
     |             +---> Baseline benchmark ------+
     |
-    +---> T3: Optimize (dispatch to expert, foreground + confirm)
-            +---> Expert proposes specific code changes
+    +---> T3: Optimize (dispatch general-purpose + skill preload, foreground + confirm)
+            +---> Agent proposes specific code changes
             +---> Preflight: what changes, expected impact, risks
             +---> User confirms
             +---> Apply changes
@@ -67,21 +67,21 @@ No agent needed. Execute directly via Bash for instant results.
 
 **Production safety rule:** In production environments, only recommend sampling profilers (py-spy, pprof HTTP endpoint, perf). Never suggest attaching debuggers, tracing profilers, or tools that require process restart.
 
-### T2: Profile - Dispatch to Expert Agent
+### T2: Profile - Dispatch to Profiling Agent
 
-Gather context from T1 diagnosis, then dispatch to the appropriate language expert.
+Gather context from T1 diagnosis, then dispatch a `general-purpose` agent preloaded with the relevant language `-ops` skill plus the perf-ops references below.
 
-**Language Expert Routing:**
+**Language Routing:**
 
-| Detected Language | Expert Agent | Key Profiling Tools |
-|-------------------|-------------|---------------------|
-| Python (.py, pyproject.toml, requirements.txt) | python-expert | py-spy, memray, scalene, tracemalloc |
-| Go (go.mod, .go files) | go-expert | pprof (CPU/heap/goroutine/mutex), benchstat |
-| Rust (Cargo.toml, .rs files) | rust-expert | cargo-flamegraph, samply, DHAT, criterion |
-| TypeScript/JavaScript (backend, package.json + server) | javascript-expert | clinic flame/doctor/bubbleprof, 0x |
-| TypeScript/JavaScript (frontend, bundle issues) | typescript-expert | webpack-bundle-analyzer, Lighthouse, source-map-explorer |
-| SQL / PostgreSQL | postgres-expert | EXPLAIN ANALYZE, pg_stat_statements, pgbench |
-| General / unknown / CLI benchmarking | general-purpose | hyperfine, perf, strace |
+| Detected Language | Dispatch | Preload | Key Profiling Tools |
+|-------------------|----------|---------|---------------------|
+| Python (.py, pyproject.toml, requirements.txt) | general-purpose | relevant `skills/python-*/SKILL.md` + perf-ops references | py-spy, memray, scalene, tracemalloc |
+| Go (go.mod, .go files) | general-purpose | `skills/go-ops/SKILL.md` + perf-ops references | pprof (CPU/heap/goroutine/mutex), benchstat |
+| Rust (Cargo.toml, .rs files) | general-purpose | `skills/rust-ops/SKILL.md` + perf-ops references | cargo-flamegraph, samply, DHAT, criterion |
+| TypeScript/JavaScript (backend, package.json + server) | general-purpose | `skills/javascript-ops/SKILL.md` + perf-ops references | clinic flame/doctor/bubbleprof, 0x |
+| TypeScript/JavaScript (frontend, bundle issues) | general-purpose | `skills/typescript-ops/SKILL.md` + perf-ops references | webpack-bundle-analyzer, Lighthouse, source-map-explorer |
+| SQL / PostgreSQL | general-purpose | `skills/postgres-ops/SKILL.md` + perf-ops references | EXPLAIN ANALYZE, pg_stat_statements, pgbench |
+| General / unknown / CLI benchmarking | general-purpose | perf-ops references | hyperfine, perf, strace |
 
 **Dispatch template (T2):**
 
@@ -131,7 +131,7 @@ For database profiling, also read:
 
 ### T3: Optimize - Preflight Required
 
-Dispatch to language expert with explicit instruction to produce a preflight report before any code changes.
+Dispatch a general-purpose agent (preloaded per the language routing table) with explicit instruction to produce a preflight report before any code changes.
 
 **Dispatch template (T3 preflight):**
 
@@ -198,23 +198,27 @@ When multiple independent symptoms are detected, or the user requests comprehens
 ```python
 # Example: CPU + memory profiling in parallel
 Agent(
-    subagent_type="python-expert",
+    subagent_type="general-purpose",
     model="sonnet",
     run_in_background=True,
-    prompt="CPU profiling task: {cpu_prompt}"
+    prompt="First read skills/perf-ops/references/cpu-memory-profiling.md "
+           "and the relevant language skill (e.g. skills/python-pytest-ops/SKILL.md). "
+           "Then: CPU profiling task: {cpu_prompt}"
 )
 Agent(
-    subagent_type="python-expert",
+    subagent_type="general-purpose",
     model="sonnet",
     run_in_background=True,
-    prompt="Memory profiling task: {memory_prompt}"
+    prompt="First read skills/perf-ops/references/cpu-memory-profiling.md "
+           "and the relevant language skill (e.g. skills/python-pytest-ops/SKILL.md). "
+           "Then: Memory profiling task: {memory_prompt}"
 )
 # Both run simultaneously, consolidate findings when both complete
 ```
 
-## Fallback: When Expert Agent Is Unavailable
+## Fallback: When No Language Skill Matches
 
-If the target language expert is not registered as a subagent type, fall back to `general-purpose` with profiling commands inlined.
+If no language `-ops` skill covers the target, dispatch `general-purpose` with profiling commands inlined instead of a skill preload.
 
 ```python
 Agent(
@@ -253,7 +257,7 @@ When a performance-related request arrives:
    - Present findings + recommend next step
 
 3. T2 Profile (when diagnosis points to a specific bottleneck):
-   - Route to appropriate language expert
+   - Route per the language routing table (general-purpose + skill preload)
    - Decide foreground vs background
    - Consider parallel dispatch if multiple symptoms
    - Consolidate findings from all agents

skills/python-async-ops/SKILL.md

@@ -14,6 +14,20 @@ metadata:
 
 Asyncio patterns for concurrent Python programming.
 
+## When to Use Async vs Sync
+
+| Use Async When | Use Sync When |
+|----------------|---------------|
+| I/O-bound operations (HTTP, DB, files) | CPU-bound computations |
+| High concurrency (100s+ connections) | Simple scripts, one-off tasks |
+| WebSocket/streaming connections | Small data processing |
+| Microservices with network calls | Single sequential operations |
+
+**Decision tree:**
+1. Is it CPU-bound? → Sync (or multiprocessing)
+2. Is it I/O-bound with high concurrency? → Async
+3. Is it simple I/O with few connections? → Sync is fine
+
 ## Core Concepts
 
 ```python

skills/python-typing-ops/references/generics-advanced.md

@@ -271,6 +271,40 @@ get_user(user_id)   # OK
 # get_user(42)        # Type error!
 ```
 
+## PEP 695 Type Parameter Syntax (Python 3.12+)
+
+```python
+# No explicit TypeVar declaration needed
+def first[T](items: list[T]) -> T | None:
+    return items[0] if items else None
+
+class Stack[T]:
+    def push(self, item: T) -> None: ...
+
+# Bounded type parameters
+def largest[T: (int, float)](items: list[T]) -> T:
+    return max(items)
+
+# Type alias statement replaces TypeAlias
+type Vector = list[float]
+type Result[T] = tuple[T, str | None]
+```
+
+## Override Decorator (Python 3.12+)
+
+```python
+from typing import override
+
+class Parent:
+    def greet(self) -> str:
+        return "Hello"
+
+class Child(Parent):
+    @override
+    def greet(self) -> str:  # Type checker errors if Parent.greet is renamed
+        return "Hi"
+```
+
 ## Best Practices
 
 1. **Name TypeVars descriptively** - `T`, `K`, `V` for simple cases; `ItemT`, `KeyT` for complex

skills/python-typing-ops/references/runtime-validation.md

@@ -2,6 +2,39 @@
 
 Enforce type hints at runtime with Pydantic, typeguard, and beartype.
 
+## Choosing a Model Library
+
+| Library | Use When |
+|---------|----------|
+| **dataclasses** | Simple data containers, internal models, no validation needed |
+| **Pydantic** | API boundaries, user input, config, JSON serialization |
+| **attrs** | Performance-critical, many instances, custom validators |
+
+```python
+# dataclasses - standard library, simple
+from dataclasses import dataclass
+
+@dataclass
+class Point:
+    x: float
+    y: float
+
+# Pydantic - validation + serialization
+from pydantic import BaseModel, Field
+
+class User(BaseModel):
+    name: str = Field(min_length=1)
+    email: EmailStr
+
+# attrs - fast, flexible
+import attrs
+
+@attrs.define
+class Record:
+    id: int
+    data: str = attrs.field(validator=attrs.validators.min_len(1))
+```
+
 ## Pydantic v2 Validation
 
 ```python

skills/review/SKILL.md

@@ -9,7 +9,7 @@ metadata:
 
 # Review Skill - AI Code Review
 
-Perform comprehensive code reviews on staged changes, specific files, or pull requests. Routes to expert agents based on file types and automatically creates tasks for critical issues.
+Perform comprehensive code reviews on staged changes, specific files, or pull requests. Dispatches general-purpose reviewers that preload the relevant `-ops` skill based on file types and automatically creates tasks for critical issues.
 
 ## Architecture
 
@@ -34,17 +34,17 @@ review [target] [--focus] [--depth]
     │     ├─ Detect test framework
     │     └─ Check CI config for existing linting
     │
-    ├─→ Step 4: Route to Expert Reviewers
-    │     ├─ TypeScript → typescript-expert
-    │     ├─ React/JSX → react-expert
-    │     ├─ Python → python-expert
-    │     ├─ Go → go-expert
-    │     ├─ Rust → rust-expert
-    │     ├─ Vue → vue-expert
-    │     ├─ SQL/migrations → postgres-expert
+    ├─→ Step 4: Route to Reviewers (general-purpose + skill preload)
+    │     ├─ TypeScript → general-purpose, preload typescript-ops
+    │     ├─ React/JSX → general-purpose, preload react-ops
+    │     ├─ Python → general-purpose, preload python-pytest-ops
+    │     ├─ Go → general-purpose, preload go-ops
+    │     ├─ Rust → general-purpose, preload rust-ops
+    │     ├─ Vue → general-purpose, preload vue-ops
+    │     ├─ SQL/migrations → general-purpose, preload postgres-ops
     │     ├─ Claude extensions → claude-architect
-    │     ├─ Multi-domain → parallel expert dispatch
-    │     └─ All experts preload: security-ops + testing-ops context
+    │     ├─ Multi-domain → parallel general-purpose dispatch
+    │     └─ All reviewers preload: security-ops + testing-ops context
     │
     ├─→ Step 5: Generate Review
     │     ├─ Severity: CRITICAL / WARNING / SUGGESTION / PRAISE
@@ -141,34 +141,37 @@ cat package.json 2>/dev/null | jq '.devDependencies | keys | map(select(test("je
 cat .github/workflows/*.yml 2>/dev/null | grep -E "eslint|prettier|pylint|ruff" | head -10
 ```
 
-### Step 4: Route to Expert Reviewers
-
-| File Pattern | Primary Expert | Secondary Expert |
-|--------------|----------------|------------------|
-| `*.ts` | typescript-expert | - |
-| `*.tsx` | react-expert | typescript-expert |
-| `*.vue` | vue-expert | typescript-expert |
-| `*.py` | python-expert | sql-expert (if ORM) |
-| `*.go` | go-expert | - |
-| `*.rs` | rust-expert | - |
-| `*.sql`, `migrations/*` | postgres-expert | - |
+### Step 4: Route to Reviewers
+
+Dispatch is skills-first: domain knowledge lives in `-ops` skills, and the generic `general-purpose` subagent preloads the relevant SKILL.md before reviewing. Surviving specialist agents (cypress-expert, claude-architect, wrangler-expert, bash-expert) are still dispatched directly.
+
+| File Pattern | Dispatch | Preload |
+|--------------|----------|---------|
+| `*.ts` | general-purpose | `skills/typescript-ops/SKILL.md` |
+| `*.tsx` | general-purpose | `skills/react-ops/SKILL.md` + `skills/typescript-ops/SKILL.md` |
+| `*.vue` | general-purpose | `skills/vue-ops/SKILL.md` + `skills/typescript-ops/SKILL.md` |
+| `*.py` | general-purpose | `skills/python-pytest-ops/SKILL.md` (+ `skills/sql-ops/SKILL.md` if ORM) |
+| `*.go` | general-purpose | `skills/go-ops/SKILL.md` |
+| `*.rs` | general-purpose | `skills/rust-ops/SKILL.md` |
+| `*.sql`, `migrations/*` | general-purpose | `skills/postgres-ops/SKILL.md` |
 | `agents/*.md`, `skills/*`, `commands/*` | claude-architect | - |
-| `*.test.*`, `*.spec.*` | cypress-expert | (framework expert) |
-| `*.cy.ts`, `cypress/*` | cypress-expert | typescript-expert |
-| `*.spec.ts` (Playwright) | typescript-expert | - |
-| `playwright/*`, `e2e/*` | typescript-expert | - |
-| `wrangler.toml`, `workers/*` | wrangler-expert | cloudflare-expert |
+| `*.test.*`, `*.spec.*` | cypress-expert | (framework skill by file type) |
+| `*.cy.ts`, `cypress/*` | cypress-expert | `skills/typescript-ops/SKILL.md` |
+| `*.spec.ts` (Playwright) | general-purpose | `skills/typescript-ops/SKILL.md` |
+| `playwright/*`, `e2e/*` | general-purpose | `skills/typescript-ops/SKILL.md` |
+| `wrangler.toml`, `workers/*` | wrangler-expert (cloudflare-expert secondary) | - |
 | `*.sh`, `*.bash` | bash-expert | - |
 
 **Invoke via Task tool:**
 ```
-Task tool with subagent_type: "[detected]-expert"
+Task tool with subagent_type: "general-purpose" (or surviving specialist from table)
 model: "sonnet"
 Prompt includes:
   - Skill preloading (domain knowledge):
     "First, read these files for review context:
      - Read: skills/security-ops/references/owasp-detailed.md
-     - Read: skills/testing-ops/SKILL.md"
+     - Read: skills/testing-ops/SKILL.md
+     - Read: [Preload column for the matched file pattern]"
   - Diff content
   - Project conventions from AGENTS.md
   - Linting config summaries
@@ -178,16 +181,16 @@ Prompt includes:
 
 **Language-specific preloads** (append to the preloading section above):
 
-| Expert | Additional Preload | Why |
-|--------|-------------------|-----|
-| python-expert | `skills/python-pytest-ops/SKILL.md` | Python test patterns for coverage review |
-| go-expert | `skills/go-ops/SKILL.md` | Go idioms, concurrency gotchas |
-| rust-expert | `skills/rust-ops/SKILL.md` | Ownership patterns, unsafe review |
-| typescript-expert | `skills/typescript-ops/SKILL.md` | Type safety patterns |
+| Language | Additional Preload | Why |
+|----------|-------------------|-----|
+| Python | `skills/python-pytest-ops/SKILL.md` | Python test patterns for coverage review |
+| Go | `skills/go-ops/SKILL.md` | Go idioms, concurrency gotchas |
+| Rust | `skills/rust-ops/SKILL.md` | Ownership patterns, unsafe review |
+| TypeScript | `skills/typescript-ops/SKILL.md` | Type safety patterns |
 
 ### Step 5: Generate Review
 
-The expert produces a structured review:
+The reviewer produces a structured review:
 
 ```markdown
 # Code Review: [scope description]

skills/rust-ops/SKILL.md

@@ -267,6 +267,14 @@ full = ["json", "yaml", "toml"]
 serde_json = { version = "1", optional = true }
 ```
 
+### Release Profile Tuning
+
+```toml
+[profile.release]
+lto = true            # Link-time optimization: smaller, faster binaries
+codegen-units = 1     # Better optimization at the cost of compile time
+```
+
 ## Common Gotchas
 
 | Gotcha | Why | Fix |

skills/security-ops/SKILL.md

@@ -38,8 +38,8 @@ User requests security audit or mentions security concern
     |       |
     |       +---> Consolidate: deduplicate, rank by severity, map to OWASP Top 10
     |
-    +---> T3: Remediate (dispatch to language expert, foreground + confirm)
-            +---> Expert proposes specific fixes
+    +---> T3: Remediate (dispatch general-purpose + skill preload, foreground + confirm)
+            +---> Agent proposes specific fixes
             +---> Preflight: what changes, security impact, risk of breaking
             +---> User confirms
             +---> Apply fixes
@@ -56,9 +56,9 @@ User requests security audit or mentions security concern
 | Code pattern scan (SAST) | T2 | Agent 2 (bg) |
 | Auth & config review | T2 | Agent 3 (bg) |
 | Consolidate findings | T2 | Inline (after agents return) |
-| Fix vulnerability in code | T3 | Expert agent + confirm |
-| Update vulnerable dependency | T3 | Expert agent + confirm |
-| Add security headers | T3 | Expert agent + confirm |
+| Fix vulnerability in code | T3 | Skill-preloaded agent + confirm |
+| Update vulnerable dependency | T3 | Skill-preloaded agent + confirm |
+| Add security headers | T3 | Skill-preloaded agent + confirm |
 
 ## T1: Detect - Run Inline
 
@@ -233,21 +233,21 @@ After all 3 agents return, consolidate inline:
 3. **Map to OWASP Top 10** - Tag each finding with its OWASP category
 4. **Generate report** (see Report Format below)
 
-## T3: Remediate - Expert Dispatch with Confirmation
+## T3: Remediate - Skill-Preloaded Dispatch with Confirmation
 
-When user wants to fix findings, dispatch to the appropriate language expert.
+When user wants to fix findings, dispatch a `general-purpose` agent preloaded with the relevant language `-ops` skill.
 
 **Language routing (same as perf-ops):**
 
-| Finding Type | Expert Agent |
-|-------------|-------------|
-| Python vulnerability | python-expert |
-| Node.js/JS vulnerability | javascript-expert |
-| TypeScript vulnerability | typescript-expert |
-| Go vulnerability | go-expert |
-| Rust vulnerability | rust-expert |
-| SQL injection / DB security | postgres-expert |
-| General / config / headers | general-purpose |
+| Finding Type | Dispatch | Preload |
+|-------------|----------|---------|
+| Python vulnerability | general-purpose | relevant `skills/python-*/SKILL.md` by topic |
+| Node.js/JS vulnerability | general-purpose | `skills/javascript-ops/SKILL.md` |
+| TypeScript vulnerability | general-purpose | `skills/typescript-ops/SKILL.md` |
+| Go vulnerability | general-purpose | `skills/go-ops/SKILL.md` |
+| Rust vulnerability | general-purpose | `skills/rust-ops/SKILL.md` |
+| SQL injection / DB security | general-purpose | `skills/postgres-ops/SKILL.md` |
+| General / config / headers | general-purpose | - |
 
 **Dispatch template (T3 preflight):**
 
@@ -257,6 +257,7 @@ You are handling a security remediation dispatched by the security-ops orchestra
 ## Domain Knowledge
 First, read for context:
 - Read: skills/security-ops/references/owasp-detailed.md
+- Read: [Preload column for the finding's language]
 
 ## Finding to Fix
 {specific finding from audit report}
@@ -323,8 +324,8 @@ If agent dispatch fails, fall back to inline scanning:
 | Code pattern scan | T2 | Agent 2 (bg) |
 | Auth & config review | T2 | Agent 3 (bg) |
 | Consolidate report | T2 | Inline |
-| Fix vulnerability | T3 | Expert + confirm |
-| Update dependency | T3 | Expert + confirm |
+| Fix vulnerability | T3 | Skill-preloaded agent + confirm |
+| Update dependency | T3 | Skill-preloaded agent + confirm |
 
 ## Reference Files
 

skills/spawn/SKILL.md

@@ -15,7 +15,7 @@ Generate world-class, comprehensive expert agent prompts for Claude Code. Each a
 
 **Target quality:** 500-1000 lines per agent with real code examples, complete configs, and detailed patterns.
 
-**Benchmark agents:** `python-expert.md` (1600 lines), `claude-architect.md` (1242 lines), `react-expert.md` (440 lines)
+**Benchmark agents:** `firecrawl-expert.md` (1026 lines), `claude-architect.md` (347 lines)
 
 ## Usage Modes
 
@@ -139,7 +139,7 @@ Every generated agent MUST follow this comprehensive 10-part structure:
 
 Plus: Quality Checklist, Anti-Patterns (5-10 with bad/good code), Canonical Resources (10-15 URLs)
 
-See `python-expert.md` and `react-expert.md` in agents/ for reference implementations.
+See `firecrawl-expert.md` and `claude-architect.md` in agents/ for reference implementations.
 
 **Requirements:**
 - YAML frontmatter at top with required fields (name, description)
@@ -228,7 +228,7 @@ Agent: Describe your architecture or provide file path:
 User: E-commerce platform: Next.js frontend, Node.js API, PostgreSQL, Redis cache, Stripe payments, AWS S3 storage, SendGrid emails
 Agent: Found platforms: Next.js, Node.js, PostgreSQL, Redis, Stripe, AWS S3, SendGrid
 [Shows multi-select AskUserQuestion]
-User: [Selects: nextjs-expert, postgres-expert, redis-expert, stripe-expert]
+User: [Selects: nextjs-expert, redis-expert, stripe-expert, sendgrid-expert]
 Agent: [Generates 4 selected agents in ~/.claude/agents/]
 ```
 

skills/sql-ops/SKILL.md

@@ -79,6 +79,25 @@ SELECT * FROM products ORDER BY id LIMIT 20 OFFSET 40;
 SELECT * FROM products WHERE id > 42 ORDER BY id LIMIT 20;
 ```
 
+## Transaction Isolation Levels
+
+| Level | Dirty Read | Non-Repeatable Read | Phantom Read | Use |
+|-------|-----------|--------------------|--------------|-----|
+| `READ UNCOMMITTED` | Possible | Possible | Possible | Rarely (PostgreSQL treats as READ COMMITTED) |
+| `READ COMMITTED` | No | Possible | Possible | Default in most databases |
+| `REPEATABLE READ` | No | No | Possible* | Consistent multi-statement reads |
+| `SERIALIZABLE` | No | No | No | Critical invariants (retry on serialization failure) |
+
+*PostgreSQL's REPEATABLE READ also prevents phantoms via snapshot isolation.
+
+```sql
+BEGIN TRANSACTION ISOLATION LEVEL SERIALIZABLE;
+-- ... critical operations ...
+COMMIT;  -- be prepared to retry on serialization failure
+```
+
+Keep the default `READ COMMITTED` globally; raise the level per-transaction only where the logic requires it.
+
 ## Index Quick Reference
 
 | Index Type | Best For |

skills/testgen/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: testgen
-description: "Generate tests with expert routing, framework detection, and auto-TaskCreate. Triggers on: generate tests, write tests, testgen, create test file, add test coverage."
+description: "Generate tests with skill-preloaded routing, framework detection, and auto-TaskCreate. Triggers on: generate tests, write tests, testgen, create test file, add test coverage."
 license: MIT
 allowed-tools: "Read Write Edit Bash Glob Grep Task TaskCreate"
 metadata:
@@ -9,7 +9,7 @@ metadata:
 
 # TestGen Skill - AI Test Generation
 
-Generate comprehensive tests with automatic framework detection, expert agent routing, and project convention matching.
+Generate comprehensive tests with automatic framework detection, skill-preloaded general-purpose dispatch, and project convention matching.
 
 ## Architecture
 
@@ -35,18 +35,18 @@ testgen <target> [--type] [--focus] [--depth]
     │     ├─ Existing test file structure
     │     └─ Naming conventions (*.test.ts vs *.spec.ts)
     │
-    ├─→ Step 4: Route to Expert Agent
-    │     ├─ .ts → typescript-expert
-    │     ├─ .tsx/.jsx → react-expert
-    │     ├─ .vue → vue-expert
-    │     ├─ .py → python-expert
-    │     ├─ .go → go-expert
-    │     ├─ .rs → rust-expert
-    │     ├─ .php → laravel-expert
+    ├─→ Step 4: Route to Test Generator (general-purpose + skill preload)
+    │     ├─ .ts → general-purpose, preload typescript-ops
+    │     ├─ .tsx/.jsx → general-purpose, preload react-ops
+    │     ├─ .vue → general-purpose, preload vue-ops
+    │     ├─ .py → general-purpose, preload python-pytest-ops
+    │     ├─ .go → general-purpose, preload go-ops
+    │     ├─ .rs → general-purpose, preload rust-ops
+    │     ├─ .php → general-purpose, preload laravel-ops
     │     ├─ E2E/Cypress → cypress-expert
-    │     ├─ Playwright → typescript-expert
+    │     ├─ Playwright → general-purpose, preload typescript-ops
     │     ├─ --visual → Chrome DevTools MCP
-    │     └─ Multi-file → parallel expert dispatch
+    │     └─ Multi-file → parallel general-purpose dispatch
     │
     ├─→ Step 5: Generate Tests
     │     ├─ Create test file in correct location
@@ -136,32 +136,35 @@ src/auth.rs → src/auth.rs (mod tests { ... })            # inline tests
             → tests/auth_test.rs                          # integration tests
 ```
 
-### Step 4: Route to Expert Agent
-
-| File Pattern | Primary Expert | Secondary |
-|--------------|----------------|-----------|
-| `*.ts` | typescript-expert | - |
-| `*.tsx`, `*.jsx` | react-expert | typescript-expert |
-| `*.vue` | vue-expert | typescript-expert |
-| `*.py` | python-expert | - |
-| `*.go` | go-expert | - |
-| `*.rs` | rust-expert | - |
-| `*.php` | laravel-expert | - |
+### Step 4: Route to Test Generator
+
+Dispatch is skills-first: the generic `general-purpose` subagent preloads the relevant `-ops` skill before generating tests. Surviving specialist agents (cypress-expert, bash-expert) are still dispatched directly.
+
+| File Pattern | Dispatch | Preload |
+|--------------|----------|---------|
+| `*.ts` | general-purpose | `skills/typescript-ops/SKILL.md` |
+| `*.tsx`, `*.jsx` | general-purpose | `skills/react-ops/SKILL.md` + `skills/typescript-ops/SKILL.md` |
+| `*.vue` | general-purpose | `skills/vue-ops/SKILL.md` + `skills/typescript-ops/SKILL.md` |
+| `*.py` | general-purpose | `skills/python-pytest-ops/SKILL.md` |
+| `*.go` | general-purpose | `skills/go-ops/SKILL.md` |
+| `*.rs` | general-purpose | `skills/rust-ops/SKILL.md` |
+| `*.php` | general-purpose | `skills/laravel-ops/SKILL.md` |
 | `*.cy.ts`, `cypress/*` | cypress-expert | - |
-| `*.spec.ts` (Playwright) | typescript-expert | - |
-| `playwright/*`, `e2e/*` | typescript-expert | - |
+| `*.spec.ts` (Playwright) | general-purpose | `skills/typescript-ops/SKILL.md` |
+| `playwright/*`, `e2e/*` | general-purpose | `skills/typescript-ops/SKILL.md` |
 | `*.sh`, `*.bash` | bash-expert | - |
-| (--visual flag) | Chrome DevTools MCP | typescript-expert |
+| (--visual flag) | Chrome DevTools MCP | `skills/typescript-ops/SKILL.md` |
 
 **Invoke via Task tool:**
 ```
-Task tool with subagent_type: "[detected]-expert"
+Task tool with subagent_type: "general-purpose" (or surviving specialist from table)
 model: "sonnet"
 Prompt includes:
   - Skill preloading (domain knowledge):
     "First, read these files for testing context:
      - Read: skills/security-ops/references/owasp-detailed.md
-     - Read: skills/testing-ops/SKILL.md"
+     - Read: skills/testing-ops/SKILL.md
+     - Read: [Preload column for the matched file pattern]"
   - Source file content
   - Function signatures to test
   - Detected framework and conventions
@@ -170,11 +173,11 @@ Prompt includes:
 
 **Language-specific preloads** (append to the preloading section above):
 
-| Expert | Additional Preload | Why |
-|--------|-------------------|-----|
-| python-expert | `skills/python-pytest-ops/SKILL.md` | Fixtures, marks, parametrize, async testing |
-| go-expert | `skills/go-ops/SKILL.md` | Table-driven tests, benchmarks, testify |
-| rust-expert | `skills/rust-ops/SKILL.md` | Property testing, criterion, proptest |
+| Language | Additional Preload | Why |
+|----------|-------------------|-----|
+| Python | `skills/python-pytest-ops/SKILL.md` | Fixtures, marks, parametrize, async testing |
+| Go | `skills/go-ops/SKILL.md` | Table-driven tests, benchmarks, testify |
+| Rust | `skills/rust-ops/SKILL.md` | Property testing, criterion, proptest |
 
 ### Step 5: Generate Tests
 
@@ -217,45 +220,45 @@ Next steps:
 
 ---
 
-## Expert Routing Details
+## Routing Details
 
-### TypeScript/JavaScript → typescript-expert
+### TypeScript/JavaScript (preload typescript-ops)
 - Proper type imports
 - Generic type handling
 - Async/await patterns
 - Mock typing
 
-### React/JSX → react-expert
+### React/JSX (preload react-ops)
 - React Testing Library patterns
 - Component rendering tests
 - Hook testing (renderHook)
 - Accessibility queries (getByRole)
 
-### Vue → vue-expert
+### Vue (preload vue-ops)
 - Vue Test Utils patterns
 - Composition API testing
 - Pinia store mocking
 
-### Python → python-expert
+### Python (preload python-pytest-ops)
 - pytest fixtures
 - Parametrized tests
 - Mock/patch patterns
 - Async test handling
 
-### Go → go-expert
+### Go (preload go-ops)
 - Table-driven tests (`[]struct` pattern)
 - `testing.T` and subtests (`t.Run`)
 - Testify assertions (when detected)
 - Benchmark functions (`testing.B`)
 - Parallel tests (`t.Parallel()`)
 
-### Rust → rust-expert
+### Rust (preload rust-ops)
 - `#[test]` attribute functions
 - `#[cfg(test)]` module organization
 - `#[should_panic]` for error testing
 - proptest/quickcheck for property testing
 
-### PHP/Laravel → laravel-expert
+### PHP/Laravel (preload laravel-ops)
 - PHPUnit/Pest patterns
 - Database transactions
 - Factory usage
@@ -265,7 +268,7 @@ Next steps:
 - Custom commands
 - Network stubbing
 
-### Playwright → typescript-expert
+### Playwright (preload typescript-ops)
 - Page object model patterns
 - Locator strategies
 - Visual regression testing

skills/tool-discovery/SKILL.md

@@ -66,14 +66,17 @@ Is this a reference/lookup task?
 
 | Agent | Triggers |
 |-------|----------|
-| **python-expert** | Python, async, pytest |
-| **typescript-expert** | TypeScript, types, generics |
-| **react-expert** | React, hooks, state |
-| **postgres-expert** | PostgreSQL, query optimization |
 | **cloudflare-expert** | Workers, KV, D1, R2 |
+| **wrangler-expert** | wrangler.toml, Workers deployment |
+| **cypress-expert** | Cypress E2E, component testing |
+| **firecrawl-expert** | web scraping, crawling, anti-bot |
+| **claude-architect** | Claude Code extensions, MCP, plugins |
+| **bash-expert** | shell scripting, CI/CD scripts |
 | **Explore** | "where is", "find" |
 | **Plan** | design, architect |
 
+For language/framework work (Python, TypeScript, React, Postgres, etc.), use the matching `-ops` skill — or dispatch `general-purpose` with an instruction to read that skill's SKILL.md first.
+
 ## How to Launch
 
 **Skills:**
@@ -83,7 +86,7 @@ Skill tool → skill: "file-search"
 
 **Agents:**
 ```
-Task tool → subagent_type: "python-expert"
+Task tool → subagent_type: "cloudflare-expert"
          → prompt: "Your task"
 ```
 
@@ -91,17 +94,18 @@ Task tool → subagent_type: "python-expert"
 
 | Task | Skill First | Agent If Needed |
 |------|-------------|-----------------|
-| "How to write a CTE?" | sql-ops | sql-expert |
-| "Optimize this query" | — | postgres-expert |
+| "How to write a CTE?" | sql-ops | — |
+| "Optimize this query" | postgres-ops | — |
 | "Find files named X" | file-search | Explore |
-| "Set up Python project" | python-env | python-expert |
+| "Set up Python project" | python-env | — |
 | "What HTTP status for X?" | rest-ops | — |
-| "React Server Components?" | react-ops | react-expert |
-| "Vue 3 composable pattern" | vue-ops | vue-expert |
+| "React Server Components?" | react-ops | — |
+| "Vue 3 composable pattern" | vue-ops | — |
 | "Configure nginx SSL" | nginx-ops | — |
 | "JWT vs session auth" | auth-ops | — |
 | "Set up Prometheus" | monitoring-ops | — |
 | "Debug memory leak" | debug-ops | — |
+| "Scrape a blocked site" | jina-ops | firecrawl-expert |
 
 ## Tips
 

skills/tool-discovery/references/agents-catalog.md

@@ -2,64 +2,9 @@
 
 Complete reference for all available agents in the Task tool.
 
-## Language Experts
-
-### python-expert
-
-**Triggers:** python, py, pythonic, PEP, async, pytest, django, flask
-
-**Capabilities:**
-- Advanced Python features (decorators, metaclasses, descriptors)
-- Async programming (asyncio, aiohttp, async generators)
-- Testing strategies (pytest, mocking, fixtures)
-- Performance optimization and profiling
-- Clean, idiomatic Python code
-
-**Best For:**
-- Complex Python architecture decisions
-- Performance optimization
-- Testing strategy design
-- Debugging difficult Python issues
+**Note:** Language and framework domains (Python, JavaScript, TypeScript, Go, Rust, React, Vue, Laravel, Astro, SQL, PostgreSQL) are covered by `-ops` skills, not agents — see `skills-catalog.md`. When subagent work is needed in those domains, dispatch `general-purpose` with an instruction to first read the relevant skill's SKILL.md and references (skill preloading).
 
----
-
-### javascript-expert
-
-**Triggers:** javascript, js, node, es6, esm, commonjs, npm
-
-**Capabilities:**
-- Modern JavaScript (ES2015+)
-- Async patterns (Promises, async/await)
-- Module systems (ESM, CommonJS)
-- Event loop and concurrency
-- V8 optimization patterns
-
-**Best For:**
-- JavaScript modernization
-- Async code architecture
-- Performance optimization
-- Node.js development
-
----
-
-### typescript-expert
-
-**Triggers:** typescript, ts, types, generics, interface, type guard
-
-**Capabilities:**
-- Advanced type system (generics, conditional types)
-- Utility types and type manipulation
-- Declaration files (.d.ts)
-- Strict mode and type safety
-- Type-level programming
-
-**Best For:**
-- Complex type definitions
-- Type-safe API design
-- Generic library development
-- Migration from JavaScript
-
----
+## Language Experts
 
 ### bash-expert
 
@@ -80,162 +25,8 @@ Complete reference for all available agents in the Task tool.
 
 ---
 
-### go-expert
-
-**Triggers:** golang, go, goroutine, concurrency, channel, context
-
-**Capabilities:**
-- Go idioms and patterns
-- Concurrency (goroutines, channels, errgroup)
-- Error handling and wrapping
-- Testing (table-driven, benchmarks, fuzz)
-- Performance profiling (pprof, trace)
-
-**Best For:**
-- Go architecture decisions
-- Concurrency design
-- Performance optimization
-- Complex error handling
-
----
-
-### rust-expert
-
-**Triggers:** rust, cargo, ownership, borrow checker, lifetime, tokio
-
-**Capabilities:**
-- Ownership, borrowing, lifetimes
-- Traits, generics, type system
-- Async with tokio
-- Error handling (thiserror, anyhow)
-- Testing and ecosystem
-
-**Best For:**
-- Fighting the borrow checker
-- Async Rust architecture
-- Trait design
-- Unsafe code review
-
----
-
-## Framework Experts
-
-### react-expert
-
-**Triggers:** react, hooks, useState, useEffect, jsx, tsx
-
-**Capabilities:**
-- React hooks (built-in and custom)
-- State management patterns
-- Server Components and RSC
-- Performance optimization
-- Component architecture
-
-**Best For:**
-- React application architecture
-- Performance bottlenecks
-- State management design
-- Migration to modern React
-
----
-
-### vue-expert
-
-**Triggers:** vue, vuejs, composition api, pinia, vue router
-
-**Capabilities:**
-- Vue 3 Composition API
-- Pinia state management
-- Vue Router patterns
-- Reactivity system internals
-- Component design
-
-**Best For:**
-- Vue 3 migration
-- State management setup
-- Complex component patterns
-- SSR with Nuxt
-
----
-
-### laravel-expert
-
-**Triggers:** laravel, eloquent, php, artisan
-
-**Capabilities:**
-- Laravel framework patterns
-- Eloquent ORM
-- Testing with PHPUnit
-- Queue and job handling
-- API development
-
-**Best For:**
-- Laravel application design
-- Database optimization
-- Testing strategy
-- API architecture
-
----
-
-### astro-expert
-
-**Triggers:** astro, islands, content collections, cloudflare workers
-
-**Capabilities:**
-- Astro architecture (SSR/SSG/hybrid)
-- Islands architecture
-- Content Collections
-- Cloudflare Workers deployment
-- Performance optimization
-
-**Best For:**
-- Astro project setup
-- Deployment to Cloudflare
-- Content management
-- Performance tuning
-
----
-
 ## Infrastructure Experts
 
-### postgres-expert
-
-**Triggers:** postgres, postgresql, pg, sql optimization
-
-**Capabilities:**
-- Query optimization
-- Index strategies
-- Execution plan analysis
-- Connection pooling
-- Replication setup
-
-**Best For:**
-- Slow query optimization
-- Index design
-- Database architecture
-- Performance tuning
-
----
-
-### sql-expert
-
-**Triggers:** sql, query, database, join, subquery
-
-**Capabilities:**
-- Complex query writing
-- Query optimization
-- Index strategies
-- Data modeling
-- Cross-database patterns
-
-**Best For:**
-- Complex query construction
-- Query debugging
-- Data modeling
-- Performance analysis
-
----
-
 ### cloudflare-expert
 
 **Triggers:** cloudflare, workers, pages, kv, d1, r2
@@ -371,22 +162,53 @@ Complete reference for all available agents in the Task tool.
 
 ---
 
-### playwright-roulette-expert
+### asus-router-expert
+
+**Triggers:** asus router, asuswrt, merlin, network hardening
+
+**Capabilities:**
+- Asus router configuration
+- Asuswrt-Merlin firmware
+- Network hardening
+- VPN and firewall setup
+
+**Best For:**
+- Router configuration
+- Home network security
+- Firmware feature guidance
+
+---
+
+### claude-architect
+
+**Triggers:** claude code extensions, skills, agents, hooks, MCP, plugins
+
+**Capabilities:**
+- Skill/agent/command/hook design
+- Plugin and marketplace configuration
+- MCP server integration
+- Extension debugging
+
+**Best For:**
+- Building Claude Code extensions
+- Reviewing skills and agents
+- Plugin architecture decisions
+
+---
+
+### git-agent
 
-**Triggers:** playwright, browser automation, casino, roulette
+**Triggers:** commit, push, PR, branch, rebase (dispatched by git-ops)
 
 **Capabilities:**
-- Playwright automation
-- DOM manipulation
-- Coordinate-based clicking
-- Browser process management
-- Viewport configuration
+- Background git write operations
+- Commit and PR creation
+- Branch and worktree management
+- Safety-tiered execution
 
 **Best For:**
-- Browser automation
-- Game automation
-- Complex DOM interactions
-- Process management
+- Dispatched git work from the git-ops skill
+- Background commits and pushes
 
 ---
 
@@ -485,14 +307,15 @@ Complete reference for all available agents in the Task tool.
 
 | Need | First Try | Then Try |
 |------|-----------|----------|
-| "How to write X in Python" | python-expert | - |
-| "Optimize this query" | postgres-expert | sql-expert |
+| "How to write X in Python" | python-* skill (e.g. python-pytest-ops) | general-purpose + skill preload |
+| "Optimize this query" | postgres-ops skill | general-purpose + skill preload |
 | "Find where X is defined" | Explore | general-purpose |
 | "Plan feature implementation" | Plan | general-purpose |
 | "Scrape this website" | firecrawl-expert | - |
 | "Deploy to Cloudflare" | wrangler-expert | cloudflare-expert |
-| "Fix React performance" | react-expert | - |
+| "Fix React performance" | react-ops skill | general-purpose + skill preload |
 | "Write E2E tests" | cypress-expert | - |
 | "Restructure project" | project-organizer | - |
-| "Go concurrency design" | go-expert | - |
-| "Rust lifetime issues" | rust-expert | - |
+| "Go concurrency design" | go-ops skill | general-purpose + skill preload |
+| "Rust lifetime issues" | rust-ops skill | general-purpose + skill preload |
+| "Build a Claude Code skill" | claude-architect | - |

skills/tool-discovery/references/skills-catalog.md

@@ -658,4 +658,4 @@ Project and development workflow automation.
 
 **Example:**
 - "What's the HTTP status for unauthorized?" → rest-ops (skill)
-- "Design authentication for my API" → python-expert or relevant framework agent
+- "Design authentication for my API" → general-purpose agent preloading auth-ops + the relevant framework `-ops` skill

skills/vue-ops/SKILL.md

@@ -401,6 +401,28 @@ What rendering strategy does my app need?
 
 ---
 
+## Rendering Performance Quick Wins
+
+| Technique | When to Use |
+|-----------|-------------|
+| `v-memo="[dep1, dep2]"` | Skip re-rendering a subtree (usually a `v-for` row) unless listed deps changed — only for measured hot lists |
+| `<KeepAlive>` | Cache component instances across tab/route switches; pair with `onActivated`/`onDeactivated` for refresh logic |
+| Virtual scrolling | Lists with hundreds+ of rows — `vue-virtual-scroller` or `@tanstack/vue-virtual` render only visible items |
+| `shallowRef` / `markRaw` | Large objects or third-party instances that don't need deep reactivity (see Reactivity Decision Tree) |
+
+```vue
+<!-- v-memo: row re-renders only when item.id or selection state changes -->
+<div
+  v-for="item in list"
+  :key="item.id"
+  v-memo="[item.id, item.id === selectedId]"
+>
+  {{ item.name }} — {{ item.id === selectedId ? 'selected' : '' }}
+</div>
+```
+
+**Tip:** before writing a composable, check [VueUse](https://vueuse.org/) — 200+ battle-tested composables (`useLocalStorage`, `useIntersectionObserver`, `useDark`, ...) that handle SSR and cleanup edge cases.
+
 ## Common Gotchas
 
 | Gotcha | Why | Fix |