@gallopsystems/agent-skills 1.0.0

package/plugins/kysely-postgres/skills/kysely-postgres/references/mutations.ts

@@ -0,0 +1,199 @@
+/**
+ * Mutation Patterns
+ * INSERT, UPDATE, DELETE, UPSERT
+ */
+import { db } from "./db";
+import { sql } from "kysely";
+
+// ============================================
+// INSERT
+// ============================================
+
+// Basic insert with RETURNING
+const newCategory = await db
+  .insertInto("category")
+  .values({ name: "New Category", sort_order: 99 })
+  .returning(["id", "name"])
+  .executeTakeFirst();
+
+// Insert multiple rows
+const newCategories = await db
+  .insertInto("category")
+  .values([
+    { name: "Category A", sort_order: 100 },
+    { name: "Category B", sort_order: 101 },
+  ])
+  .returning(["id", "name"])
+  .execute();
+
+// ============================================
+// UPSERT (ON CONFLICT)
+// ============================================
+
+// Insert or update if conflict
+const upsertedProduct = await db
+  .insertInto("product")
+  .values({
+    name: "Upsert Product",
+    sku: "UPSERT-001",
+    price: "99.99",
+    stock_quantity: 10,
+  })
+  .onConflict((oc) =>
+    oc.column("sku").doUpdateSet((eb) => ({
+      // Update these columns on conflict - type-safe!
+      stock_quantity: eb("product.stock_quantity", "+", eb.ref("excluded.stock_quantity")),
+    }))
+  )
+  .returning(["id", "sku", "stock_quantity"])
+  .executeTakeFirst();
+
+// OnConflict variations:
+// - oc.column("col") - single column constraint
+// - oc.columns(["col1", "col2"]) - composite constraint
+// - oc.constraint("constraint_name") - named constraint
+// - oc.doNothing() - ignore conflicts
+// - oc.doUpdateSet({...}) - update on conflict
+
+// Upsert with doNothing
+await db
+  .insertInto("user")
+  .values({ email: "exists@example.com", first_name: "Test", last_name: "User" })
+  .onConflict((oc) => oc.column("email").doNothing())
+  .execute();
+
+// ============================================
+// UPDATE
+// ============================================
+
+// Basic update
+const updatedCategory = await db
+  .updateTable("category")
+  .set({ sort_order: 999 })
+  .where("name", "=", "New Category")
+  .returning(["id", "name", "sort_order"])
+  .executeTakeFirst();
+
+// Update with expression (increment)
+const updatedStock = await db
+  .updateTable("product")
+  .set((eb) => ({
+    stock_quantity: eb("stock_quantity", "+", 5),
+  }))
+  .where("sku", "=", "UPSERT-001")
+  .returning(["id", "sku", "stock_quantity"])
+  .executeTakeFirst();
+
+// Update multiple columns with expressions
+await db
+  .updateTable("product")
+  .set((eb) => ({
+    stock_quantity: eb("stock_quantity", "-", 1),
+    price: eb("price", "*", eb.lit(1.1)), // 10% increase
+  }))
+  .where("id", "=", 1)
+  .execute();
+
+// ============================================
+// DELETE
+// ============================================
+
+// Delete with RETURNING
+const deleted = await db
+  .deleteFrom("category")
+  .where("name", "like", "Category%")
+  .returning(["id", "name"])
+  .execute();
+
+// Delete with subquery
+await db
+  .deleteFrom("order_item")
+  .where(
+    "order_id",
+    "in",
+    db.selectFrom("order").select("id").where("status", "=", "cancelled")
+  )
+  .execute();
+
+// ============================================
+// INSERT FROM SELECT
+// ============================================
+
+// Insert rows from another query
+const auditLogs = await db
+  .insertInto("inventory_log")
+  .columns(["product_id", "change_quantity", "reason"])
+  .expression(
+    db
+      .selectFrom("product")
+      .select([
+        "id as product_id",
+        sql`0`.as("change_quantity"),
+        sql`'Audit check'`.as("reason"),
+      ])
+      .where("is_active", "=", true)
+      .limit(10)
+  )
+  .returning(["id", "product_id", "reason"])
+  .execute();
+
+// ============================================
+// UNION
+// ============================================
+
+// Combine results from multiple queries
+const contacts = await db
+  .selectFrom("user")
+  .select(["email as contact", sql`'email'`.as("type")])
+  .where("role", "=", "admin")
+  .union(
+    db
+      .selectFrom("user")
+      .select(["email as contact", sql`'email'`.as("type")])
+      .where("role", "=", "manager")
+  )
+  .execute();
+
+// unionAll - includes duplicates
+// intersect - rows in both queries
+// except - rows in first but not second
+
+// ============================================
+// KEY PATTERNS SUMMARY
+// ============================================
+
+/*
+1. INSERT:
+   .insertInto("table")
+   .values({...}) or .values([...])
+   .returning([...])
+   .execute() or .executeTakeFirst()
+
+2. UPSERT (ON CONFLICT) - type-safe with eb callback:
+   .onConflict((oc) => oc.column("col").doUpdateSet((eb) => ({
+     col: eb("table.col", "+", eb.ref("excluded.col")),
+   })))
+   - eb.ref("excluded.col") for inserted values
+   - eb("table.col", ...) for existing values (type-safe!)
+
+3. UPDATE:
+   .updateTable("table")
+   .set({...}) or .set((eb) => ({...}))
+   .where(...)
+   - Use eb(col, op, value) for expressions
+
+4. DELETE:
+   .deleteFrom("table")
+   .where(...)
+   .returning([...]) - optional
+
+5. INSERT FROM SELECT:
+   .insertInto("table")
+   .columns([...])
+   .expression(db.selectFrom(...))
+
+6. RETURNING:
+   - Available on INSERT, UPDATE, DELETE
+   - Returns affected rows
+   - Use with executeTakeFirst() for single row
+*/

package/plugins/kysely-postgres/skills/kysely-postgres/references/orderby-pagination.ts

@@ -0,0 +1,117 @@
+/**
+ * ORDER BY and Pagination Patterns
+ * Sorting, NULLS handling, DISTINCT, pagination
+ */
+import { db } from "./db";
+
+// ============================================
+// ORDER BY
+// ============================================
+
+// Simple ORDER BY
+const productsByPrice = await db
+  .selectFrom("product")
+  .select(["name", "price"])
+  .orderBy("price", "desc")
+  .execute();
+
+// Multiple ORDER BY - chain calls
+// NOT array syntax - that's deprecated!
+const sortedProducts = await db
+  .selectFrom("product")
+  .select(["name", "price", "stock_quantity"])
+  .orderBy("is_active", "desc")  // Primary sort
+  .orderBy("price", "asc")       // Secondary sort
+  .execute();
+
+// ============================================
+// NULLS FIRST / NULLS LAST
+// ============================================
+
+// Use order builder callback (ob) - NOT sql``!
+const productsNullsLast = await db
+  .selectFrom("product")
+  .select(["name", "category_id"])
+  .orderBy("category_id", (ob) => ob.asc().nullsLast())
+  .execute();
+
+const productsNullsFirst = await db
+  .selectFrom("product")
+  .select(["name", "category_id"])
+  .orderBy("category_id", (ob) => ob.desc().nullsFirst())
+  .execute();
+
+// ============================================
+// PAGINATION
+// ============================================
+
+// LIMIT and OFFSET
+const page2 = await db
+  .selectFrom("product")
+  .selectAll()
+  .orderBy("name")
+  .limit(10)    // Items per page
+  .offset(10)   // Skip first page (page 1)
+  .execute();
+
+// Pagination helper pattern
+async function getPaginatedProducts(page: number, pageSize: number) {
+  return db
+    .selectFrom("product")
+    .selectAll()
+    .orderBy("created_at", "desc")
+    .limit(pageSize)
+    .offset((page - 1) * pageSize)
+    .execute();
+}
+
+// ============================================
+// DISTINCT
+// ============================================
+
+// DISTINCT - unique values
+const uniqueStatuses = await db
+  .selectFrom("order")
+  .select("status")
+  .distinct()
+  .execute();
+
+// DISTINCT ON (PostgreSQL only)
+// Get first row for each unique value of specified column(s)
+const latestOrderPerUser = await db
+  .selectFrom("order")
+  .distinctOn("user_id")
+  .select(["user_id", "id", "status", "created_at"])
+  .orderBy("user_id")
+  .orderBy("created_at", "desc") // Most recent first
+  .execute();
+// Returns one row per user - their latest order
+
+// ============================================
+// KEY PATTERNS SUMMARY
+// ============================================
+
+/*
+1. ORDER BY syntax:
+   .orderBy("column", "asc")   // ascending
+   .orderBy("column", "desc")  // descending
+
+2. Multiple columns - CHAIN, don't use array:
+   .orderBy("col1", "desc")
+   .orderBy("col2", "asc")
+
+3. NULLS handling - use order builder callback:
+   .orderBy("col", (ob) => ob.asc().nullsLast())
+   .orderBy("col", (ob) => ob.desc().nullsFirst())
+
+   AVOID sql`` for this - deprecated pattern!
+
+4. Pagination:
+   .limit(pageSize)
+   .offset((page - 1) * pageSize)
+
+5. DISTINCT ON (PostgreSQL):
+   - Gets first row per unique value
+   - ORDER BY must start with DISTINCT ON column(s)
+   - Then order by what determines "first"
+*/

package/plugins/kysely-postgres/skills/kysely-postgres/references/relations.ts

@@ -0,0 +1,176 @@
+/**
+ * Relations Patterns
+ * jsonArrayFrom and jsonObjectFrom for nested data
+ */
+import { db } from "./db";
+import { jsonArrayFrom, jsonObjectFrom } from "kysely/helpers/postgres";
+
+// ============================================
+// IMPORTANT: Kysely is NOT an ORM
+// ============================================
+
+// Kysely doesn't have built-in relations like Prisma or TypeORM.
+// Instead, use PostgreSQL JSON functions to fetch related data
+// in a single query.
+
+// ============================================
+// jsonArrayFrom - One-to-Many
+// ============================================
+
+// User with their orders (one user -> many orders)
+const usersWithOrders = await db
+  .selectFrom("user")
+  .select((eb) => [
+    "user.id",
+    "user.email",
+    "user.first_name",
+    // Correlated subquery returns JSON array
+    jsonArrayFrom(
+      eb
+        .selectFrom("order")
+        .select(["order.id", "order.status", "order.total_amount"])
+        .whereRef("order.user_id", "=", "user.id") // Correlation!
+        .orderBy("order.created_at", "desc")
+    ).as("orders"),
+  ])
+  .where("user.is_active", "=", true)
+  .execute();
+
+// Result type: { id, email, first_name, orders: Array<{id, status, total_amount}> }
+
+// ============================================
+// jsonObjectFrom - Many-to-One
+// ============================================
+
+// Product with its category (many products -> one category)
+const productsWithCategory = await db
+  .selectFrom("product")
+  .select((eb) => [
+    "product.id",
+    "product.name",
+    "product.price",
+    // Correlated subquery returns single JSON object
+    jsonObjectFrom(
+      eb
+        .selectFrom("category")
+        .select(["category.id", "category.name"])
+        .whereRef("category.id", "=", "product.category_id") // Correlation!
+    ).as("category"),
+  ])
+  .execute();
+
+// Result type: { id, name, price, category: {id, name} | null }
+
+// ============================================
+// COMBINED NESTED RELATIONS
+// ============================================
+
+// Deep nesting: User -> Orders -> Products
+const userOrderDetails = await db
+  .selectFrom("user")
+  .select((eb) => [
+    "user.id",
+    "user.email",
+    jsonArrayFrom(
+      eb
+        .selectFrom("order")
+        .innerJoin("order_item", "order_item.order_id", "order.id")
+        .innerJoin("product", "product.id", "order_item.product_id")
+        .select([
+          "order.id as orderId",
+          "order.status",
+          "product.name as productName",
+          "order_item.quantity",
+        ])
+        .whereRef("order.user_id", "=", "user.id")
+    ).as("orderDetails"),
+  ])
+  .where("user.email", "=", "alice@example.com")
+  .executeTakeFirst();
+
+// ============================================
+// MULTIPLE RELATIONS
+// ============================================
+
+// Order with user (many-to-one) AND items (one-to-many)
+const ordersComplete = await db
+  .selectFrom("order")
+  .select((eb) => [
+    "order.id",
+    "order.status",
+    "order.total_amount",
+    // Many-to-one: user
+    jsonObjectFrom(
+      eb
+        .selectFrom("user")
+        .select(["user.id", "user.email", "user.first_name"])
+        .whereRef("user.id", "=", "order.user_id")
+    ).as("user"),
+    // One-to-many: items
+    jsonArrayFrom(
+      eb
+        .selectFrom("order_item")
+        .innerJoin("product", "product.id", "order_item.product_id")
+        .select([
+          "order_item.quantity",
+          "order_item.unit_price",
+          "product.name as productName",
+        ])
+        .whereRef("order_item.order_id", "=", "order.id")
+    ).as("items"),
+  ])
+  .execute();
+
+// ============================================
+// WITH FILTERING AND ORDERING
+// ============================================
+
+// Only include active items, ordered by price
+const productWithActiveReviews = await db
+  .selectFrom("product")
+  .select((eb) => [
+    "product.id",
+    "product.name",
+    jsonArrayFrom(
+      eb
+        .selectFrom("review")
+        .select(["review.id", "review.rating", "review.title"])
+        .whereRef("review.product_id", "=", "product.id")
+        .where("review.rating", ">=", 4) // Filter inside relation!
+        .orderBy("review.created_at", "desc")
+        .limit(5) // Limit inside relation!
+    ).as("topReviews"),
+  ])
+  .execute();
+
+// ============================================
+// KEY PATTERNS SUMMARY
+// ============================================
+
+/*
+1. jsonArrayFrom - One-to-Many:
+   - Returns JSON array of related rows
+   - Use whereRef() to correlate with outer query
+   - Can include joins, filters, ordering inside
+
+2. jsonObjectFrom - Many-to-One:
+   - Returns single JSON object or null
+   - Use whereRef() to correlate with outer query
+   - Returns null if no match (like LEFT JOIN)
+
+3. Key differences from ORMs:
+   - No automatic eager/lazy loading
+   - You explicitly define what to fetch
+   - Single query, no N+1 problem
+   - Full control over the SQL
+
+4. whereRef() is critical:
+   - Links subquery to outer query
+   - First arg: inner table column
+   - Third arg: outer table column (eb.ref())
+
+5. Performance benefits:
+   - Single database round trip
+   - PostgreSQL optimizes the JSON aggregation
+   - No N+1 queries ever
+*/

package/plugins/kysely-postgres/skills/kysely-postgres/references/select-where.ts

@@ -0,0 +1,146 @@
+/**
+ * SELECT and WHERE Patterns
+ * Basic query patterns for fetching and filtering data
+ */
+import { db } from "./db";
+import { sql } from "kysely";
+
+// ============================================
+// SELECT PATTERNS
+// ============================================
+
+// Select all columns
+const allUsers = await db.selectFrom("user").selectAll().execute();
+
+// Select specific columns
+const userNames = await db
+  .selectFrom("user")
+  .select(["id", "email", "first_name", "last_name"])
+  .execute();
+
+// Column aliases with eb.ref().as()
+const aliasedUsers = await db
+  .selectFrom("user")
+  .select((eb) => [
+    eb.ref("first_name").as("firstName"),
+    eb.ref("last_name").as("lastName"),
+    eb.ref("email").as("emailAddress"),
+  ])
+  .execute();
+
+// executeTakeFirst - returns T | undefined (for 0 or 1 row)
+const maybeUser = await db
+  .selectFrom("user")
+  .selectAll()
+  .where("email", "=", "alice@example.com")
+  .executeTakeFirst();
+
+// executeTakeFirstOrThrow - throws if no row found
+const definiteUser = await db
+  .selectFrom("user")
+  .selectAll()
+  .where("email", "=", "alice@example.com")
+  .executeTakeFirstOrThrow();
+
+// ============================================
+// WHERE CLAUSES
+// ============================================
+
+// Equality
+const admins = await db
+  .selectFrom("user")
+  .selectAll()
+  .where("role", "=", "admin")
+  .execute();
+
+// Comparison operators (<, >, <=, >=, !=)
+const expensiveProducts = await db
+  .selectFrom("product")
+  .select(["name", "price"])
+  .where("price", ">", "100")
+  .execute();
+
+// IN clause - array of values
+const pendingOrShipped = await db
+  .selectFrom("order")
+  .selectAll()
+  .where("status", "in", ["pending", "shipped"])
+  .execute();
+
+// LIKE pattern matching
+const bookProducts = await db
+  .selectFrom("product")
+  .select(["name", "sku"])
+  .where("name", "like", "%Book%")
+  .execute();
+
+// IS NULL / IS NOT NULL
+const uncategorized = await db
+  .selectFrom("product")
+  .select(["name", "category_id"])
+  .where("category_id", "is", null)
+  .execute();
+
+// ============================================
+// COMBINING CONDITIONS
+// ============================================
+
+// Multiple WHERE = AND (chained)
+// Chaining .where() creates AND conditions
+const activeAffordable = await db
+  .selectFrom("product")
+  .select(["name", "price", "is_active"])
+  .where("is_active", "=", true)
+  .where("price", "<", "100")
+  .execute();
+
+// OR conditions using eb.or()
+const adminOrManager = await db
+  .selectFrom("user")
+  .selectAll()
+  .where((eb) =>
+    eb.or([
+      eb("role", "=", "admin"),
+      eb("role", "=", "manager"),
+    ])
+  )
+  .execute();
+
+// Complex AND/OR with eb.and() and eb.or()
+const complexFilter = await db
+  .selectFrom("product")
+  .select(["name", "price", "stock_quantity"])
+  .where((eb) =>
+    eb.and([
+      eb("is_active", "=", true),
+      eb.or([
+        eb("price", "<", "50"),
+        eb("stock_quantity", ">", 100),
+      ]),
+    ])
+  )
+  .execute();
+
+// ============================================
+// KEY PATTERNS SUMMARY
+// ============================================
+
+/*
+1. selectAll() vs select([...])
+   - selectAll() gets all columns
+   - select([...]) for specific columns - better performance
+
+2. executeTakeFirst() vs execute()
+   - execute() returns array
+   - executeTakeFirst() returns single row or undefined
+   - executeTakeFirstOrThrow() throws if not found
+
+3. WHERE chaining = AND
+   - .where(...).where(...) creates AND
+   - Use eb.or([...]) for OR
+   - Use eb.and([...]) for explicit AND
+
+4. eb() inside where callbacks
+   - eb("column", "=", value) creates comparison
+   - Returns Expression<SqlBool> for composability
+*/

package/plugins/linear/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "linear",
+  "description": "Create, triage, and manage Linear issues at Gallop Systems following team conventions: cycle placement, issue templates, project / milestone hierarchy, project refresh, and cycle rebalance. Includes a bash GraphQL CLI for the operations the Linear MCP server doesn't expose.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Gallop Systems"
+  }
+}