@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/php-testing/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: php-testing
+description: Writing and fixing PHP test suites with PHPUnit or Pest, including attribute-based data providers and Pest datasets, test doubles via createMock/createStub or Mockery, database tests isolated by transactions, HTTP controller and client tests, and coverage with Xdebug or PCOV. Use when adding PHP unit or integration tests, converting PHPUnit annotations to attributes, deciding what to mock in PHP, or making a flaky PHP test deterministic.
+license: MIT
+compatibility: Any Agent Skills host. Needs php and composer; Xdebug or PCOV only for coverage.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: testing
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "php, composer"
+  kete-loom/owner: "Kete-org"
+---
+
+# PHP testing
+
+Tests that are fast, isolated and readable, written in whichever framework the project already uses.
+
+## 0. Before you write
+
+1. Identify the runner: `vendor/bin/pest` if `pestphp/pest` is in `composer.json` `require-dev`, else `vendor/bin/phpunit`. Check `composer.json` `scripts` for a `test` script and use it (`composer test`).
+2. Read `phpunit.xml(.dist)`: test suites, bootstrap, `<php><env>` values (for example `APP_ENV=testing`, `DB_CONNECTION`), and `<source>` for coverage.
+3. Note the PHPUnit major version (`composer show phpunit/phpunit`). PHPUnit 10 introduced attributes; 11 deprecated docblock annotations; 12 removed them. Make data providers `public static`: non-static providers are deprecated from PHPUnit 10.
+4. Run the existing suite once. If it already fails, **stop and tell the user** which tests fail before you change anything.
+5. Find the framework helpers already in use (Laravel `Tests\TestCase`, Symfony `KernelTestCase`/`WebTestCase`, a project base class) and extend the same one.
+
+## 1. Layout and naming
+
+- Mirror `src/` under `tests/Unit` and `tests/Feature` (or `tests/Integration`). Test class name = class under test + `Test`, autoloaded via `autoload-dev`.
+- One behaviour per test. Name it as a sentence: `test_it_rejects_an_expired_coupon()` or `#[Test] public function rejectsExpiredCoupon()`; in Pest, `it('rejects an expired coupon', ...)`.
+- Arrange, act, assert. Use the most specific assertion: `assertSame` (strict) over `assertEquals`, `assertCount`, `assertInstanceOf`, `expectException(X::class)` plus `expectExceptionMessage()`.
+
+## 2. Data providers and datasets
+
+PHPUnit 10+:
+
+```php
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\Test;
+
+final class SlugTest extends TestCase
+{
+    public static function cases(): iterable
+    {
+        yield 'spaces' => ['Hello World', 'hello-world'];
+        yield 'unicode' => ['Crème Brûlée', 'creme-brulee'];
+        yield 'empty' => ['', ''];
+    }
+
+    #[Test]
+    #[DataProvider('cases')]
+    public function slugifies(string $input, string $expected): void
+    {
+        self::assertSame($expected, Slug::from($input));
+    }
+}
+```
+
+Pest:
+
+```php
+it('slugifies', function (string $input, string $expected) {
+    expect(Slug::from($input))->toBe($expected);
+})->with([
+    'spaces' => ['Hello World', 'hello-world'],
+    'empty' => ['', ''],
+]);
+```
+
+- Always key the cases so a failure names the case.
+- Converting annotations: `@dataProvider x` → `#[DataProvider('x')]`, `@test` → `#[Test]`, `@group g` → `#[Group('g')]`, `@covers` (class level) → `#[CoversClass(Foo::class)]`. Make provider methods `static`. Rector's PHPUnit sets can do this in bulk: ask before running it across the suite.
+
+## 3. Test doubles
+
+- Mock what you don't own and what is slow or nondeterministic: HTTP clients, mailers, queues, the clock, random sources. Don't mock value objects, entities or the class under test.
+- PHPUnit: `$this->createStub(Repo::class)` when you only need return values (`->method('find')->willReturn($user)`); `$this->createMock(Repo::class)` when the call itself is the behaviour (`->expects($this->once())->method('save')->with($order)`).
+- Mockery (if installed): `Mockery::mock(Repo::class)->shouldReceive('find')->once()->andReturn($user)`; make sure `Mockery::close()` runs (the `MockeryPHPUnitIntegration` trait or Pest does this).
+- Final classes can't be doubled by PHPUnit. Depend on an interface, or use a hand-written fake. Don't remove `final` just to mock it.
+- Time: inject a clock (`Psr\Clock\ClockInterface`, Symfony `MockClock`, Laravel `$this->travelTo()`/`Carbon::setTestNow()`). Never `sleep()` in a test.
+- Prefer a small in-memory fake (`InMemoryOrderRepository`) over a deep mock chain; if setup needs more than three expectations, rethink the seam.
+
+## 4. Database tests
+
+- Use a dedicated test database, configured in `phpunit.xml` `<env>` or `.env.testing`. Never point tests at a shared or production database: **stop and ask** if the configured DSN looks like one.
+- Isolate each test in a transaction that rolls back:
+  - Laravel: `use RefreshDatabase;` (migrates once, wraps each test) or `DatabaseTransactions` for an already-migrated database.
+  - Symfony + Doctrine: `dama/doctrine-test-bundle` (enable its PHPUnit extension in `phpunit.xml`).
+  - Plain PDO: `beginTransaction()` in `setUp()`, `rollBack()` in `tearDown()`.
+- Transactions don't cover code that opens its own connection, commits explicitly, or runs DDL (MySQL commits implicitly on DDL). Those tests need truncation or a fresh schema.
+- Create data with factories (Laravel model factories, Foundry for Symfony), only the fields the test cares about.
+- SQLite in memory is fast but is not MySQL or Postgres: JSON, collation, locking and constraint behaviour differ. Run integration tests against the production engine (a container in CI) when those matter.
+
+## 5. HTTP code
+
+- Your endpoints: use the framework's test client, not a running server.
+  - Laravel: `$this->postJson('/api/orders', $payload)->assertCreated()->assertJsonPath('data.status', 'paid');`, `actingAs($user)`.
+  - Symfony: `$client = static::createClient(); $client->request('POST', '/orders'); self::assertResponseStatusCodeSame(201);`.
+  - PSR-15 apps: build a `ServerRequest` and call the handler directly.
+- Cover per endpoint: success, validation failure (422/400), unauthenticated (401), forbidden (403), not found (404).
+- Outgoing HTTP: never hit real services. Use Guzzle `MockHandler` with a `HandlerStack`, Symfony `MockHttpClient`, or Laravel `Http::fake()` plus `Http::preventStrayRequests()`. Assert the request you sent (method, URL, body), not only how you handled the response.
+
+## 6. Running and coverage
+
+- Single test: `vendor/bin/phpunit --filter slugifies tests/Unit/SlugTest.php`, `vendor/bin/pest --filter "slugifies"`.
+- Random order shakes out hidden coupling: `--order-by=random` (PHPUnit), `--random-order-seed=<seed>` to reproduce.
+- Parallel: `vendor/bin/pest --parallel`, `php artisan test --parallel`, or `brianium/paratest`. Each worker needs its own database.
+- Coverage needs Xdebug (`XDEBUG_MODE=coverage`) or PCOV: `vendor/bin/phpunit --coverage-text`, `vendor/bin/pest --coverage --min=80`. Cover the new branches; don't chase a number.
+
+## 7. Flaky tests
+
+1. Rerun with `--order-by=random` and a fixed seed to see whether order matters.
+2. Look for shared state: static properties, singletons, the service container, global time, leftover rows, the filesystem.
+3. Replace the nondeterminism (clock, random, network) with a fake. Don't add retries or sleeps.
+
+## Never
+
+- Delete, skip (`markTestSkipped`) or weaken an assertion to make the suite pass without telling the user why.
+- Call real third-party APIs, send real email or charge real payment methods from tests.
+- Assert on `assertEquals` when the type matters, or `assertTrue($a == $b)` instead of a specific assertion.
+- Leave `dd()`, `dump()`, `var_dump()` or `->only()` (Pest) in committed tests.
+
+## Report
+
+When done, state: tests added or changed (file and test names), the command you ran and its result, and anything not run (for example "integration tests need MySQL, not run").

package/skills/php-testing/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Write PHPUnit tests with a data provider for my PriceCalculator class",
+    "Convert our PHPUnit @dataProvider annotations to attributes so we can upgrade to PHPUnit 12",
+    "How do I mock the Guzzle client in a Pest test for my weather service?",
+    "My Laravel feature tests leave rows in the database between runs, how do I isolate them?",
+    "Add tests for the POST /orders endpoint in our Symfony app covering validation and auth failures"
+  ],
+  "should_not_trigger": [
+    "Write a PHP 8.3 enum for invoice statuses with a label method",
+    "Review my PHP changes for type juggling bugs and missing strict_types",
+    "PHPStan fails at level 8 after upgrading Composer packages, fix it",
+    "Write pytest fixtures for my Django models",
+    "Set up Playwright end-to-end tests for the checkout page"
+  ]
+}

package/skills/postgres-patterns/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: postgres-patterns
+description: PostgreSQL schema, indexing and query-tuning guide covering data types and constraints, btree, partial, expression and GIN indexes, reading EXPLAIN (ANALYZE, BUFFERS) plans, isolation levels and lock conflicts, JSONB modelling, PgBouncer connection pooling, and pg_dump or point-in-time backups. Use when designing Postgres tables, a Postgres query is slow, you need to pick an index type, decode a lock wait or deadlock, store documents in JSONB, or set up pooling and backups for a PostgreSQL database.
+license: MIT
+compatibility: Any Agent Skills host. Running queries needs psql or the project's database client and a reachable PostgreSQL server; never point it at production without the user's say-so.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: data
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "psql"
+  kete-loom/owner: "Kete-org"
+---
+
+# PostgreSQL patterns
+
+Design tables the database can enforce, index for the queries you actually run, and prove every tuning change with a plan. For changing a live schema step by step, use the `database-migrations` skill; for MySQL or MariaDB, use `mysql-patterns`.
+
+## 0. Before you start
+
+1. Find the server version (`SELECT version();`) and how the app connects (ORM, driver, pooler). Advice differs across major versions; check the docs for that version.
+2. Ask which environment you may query. Run `EXPLAIN ANALYZE` only on a dev or staging copy unless the user agrees: it **executes** the statement, including writes.
+3. Wrap any `EXPLAIN ANALYZE` of an `INSERT`, `UPDATE` or `DELETE` in `BEGIN; ... ROLLBACK;`.
+
+## 1. Schema design rules
+
+- Primary keys: `bigint GENERATED ALWAYS AS IDENTITY`, or `uuid` when IDs are made outside the database. Never `serial` in new code, never `int` for a table that can grow past 2 billion rows.
+- Time: `timestamptz`, stored in UTC. Never `timestamp` without time zone for events.
+- Money: `numeric(p, s)` or integer minor units. Never `float`/`double precision`, never the `money` type.
+- Text: `text` with a `CHECK (char_length(col) <= n)` when a limit is a business rule. `varchar(n)` is fine; `char(n)` is not.
+- Enumerations: a lookup table or a `CHECK (status IN (...))`. Native `enum` types are hard to shrink later.
+- Constraints are the schema: `NOT NULL` by default, `UNIQUE` for natural keys, `FOREIGN KEY` for every reference, `CHECK` for invariants. App-only validation drifts.
+- Index every foreign key column you join or delete through. Postgres does not create them for you, and an unindexed FK makes parent deletes scan the child table.
+- Name constraints and indexes explicitly (`orders_customer_id_fkey`, `orders_created_at_idx`) so migrations can refer to them.
+
+## 2. Pick the index
+
+| Query shape | Index |
+|---|---|
+| `=`, `<`, `>`, `BETWEEN`, `ORDER BY`, `LIKE 'abc%'` (C collation or `text_pattern_ops`) | btree (default) |
+| Filter always on a subset (`WHERE deleted_at IS NULL`, `status = 'pending'`) | partial btree: `CREATE INDEX ... WHERE status = 'pending'` |
+| Filter on a function (`lower(email)`, `(data->>'sku')`) | expression index on exactly that expression |
+| JSONB containment `@>`, key exists `?`, arrays `&&`/`@>`, full-text `@@` | GIN (`jsonb_path_ops` when you only need `@>` and jsonpath) |
+| Substring / fuzzy text `ILIKE '%abc%'` | GIN with `pg_trgm` (`gin_trgm_ops`) |
+| Huge append-only table filtered by time | BRIN on the time column |
+| Ranges, geometry, exclusion constraints | GiST |
+
+Rules:
+
+1. Multicolumn btree: equality columns first, then the range or sort column. `(tenant_id, created_at)` serves `WHERE tenant_id = $1 ORDER BY created_at DESC`.
+2. Use `INCLUDE (...)` to make an index covering for an index-only scan, instead of adding columns to the key.
+3. Every index costs writes, disk and vacuum time. Check `pg_stat_user_indexes.idx_scan` before adding more; drop indexes that stay at 0 on the primary and every replica (stats are per server), except ones that back a `UNIQUE` or primary key constraint.
+4. On a table with live traffic, build with `CREATE INDEX CONCURRENTLY` (not inside a transaction). If it fails it leaves an `INVALID` index: drop it and retry.
+
+## 3. Tune a slow query
+
+1. Get the exact statement and real parameter values. Check `pg_stat_statements` for total and mean time if it is installed.
+2. Run `EXPLAIN (ANALYZE, BUFFERS) <query>` on a realistic copy.
+3. Read the plan bottom-up. Look for: estimated vs actual rows off by 10x or more, `Seq Scan` on a big table with a selective filter, `Rows Removed by Filter` much larger than rows returned, `Sort` with `external merge`, nested loops with a high `loops` count.
+4. Fix the cause, in this order: stale stats (`ANALYZE table`), a missing or wrong index, a non-sargable predicate (function on the column, implicit cast, leading `%`), then query shape (`EXISTS` instead of `IN` with a big subquery, keyset pagination instead of big `OFFSET`).
+5. Re-run the same `EXPLAIN` and compare time and buffers. Report before and after.
+
+Plan-node reference and worked examples: `references/explain.md`.
+
+## 4. Transactions, isolation and locks
+
+- Default isolation is `READ COMMITTED`: each statement sees a fresh snapshot. Read-then-write logic (check balance, then update) needs `SELECT ... FOR UPDATE`, a guarded `UPDATE ... WHERE balance >= $1`, or `SERIALIZABLE`.
+- `REPEATABLE READ` and `SERIALIZABLE` can fail with SQLSTATE `40001`. The app **must** retry the whole transaction; if it can't, don't use them.
+- Lock rows in a consistent order (for example by primary key) to avoid deadlocks (`40P01`).
+- Queues: `SELECT ... FOR UPDATE SKIP LOCKED LIMIT n` lets several workers claim jobs without blocking each other.
+- Keep transactions short. Never hold one open across a network call or user think-time. Set `idle_in_transaction_session_timeout` so a stuck client can't hold locks for hours.
+- Upserts: `INSERT ... ON CONFLICT (key) DO UPDATE` instead of select-then-insert.
+- Diagnose waits with `pg_stat_activity` (`wait_event_type = 'Lock'`) and `pg_blocking_pids(pid)`. Queries: `references/locks.md`.
+
+## 5. JSONB
+
+- Use JSONB for genuinely variable attributes, payload archives and sparse settings. Columns you filter, join or constrain on every request belong in real columns.
+- Index what you query: GIN for `@>`; an expression btree for one hot key (`((data->>'customer_id'))`).
+- Validate shape with `CHECK (jsonb_typeof(data->'items') = 'array')` or in the app; Postgres won't do it otherwise.
+- Updating one key rewrites the whole value. Large, frequently updated documents bloat the table.
+
+## 6. Connections and pooling
+
+- Each connection is a backend process. Keep the total across all app instances small (a rule of thumb is a few connections per database CPU core; measure from there), not one per request thread.
+- Put PgBouncer (or the platform's pooler) in front when many app instances or serverless functions connect. In `transaction` pool mode, session state does not survive between transactions: no session `SET`, advisory session locks, `LISTEN`, or temp tables across transactions. Server-side prepared statements need pooler support (PgBouncer 1.21+ `max_prepared_statements`) or must be disabled in the driver.
+- Set `statement_timeout` per role or per request for web traffic so a runaway query can't pin a connection.
+
+## 7. Backups
+
+- Logical: `pg_dump -Fc dbname > db.dump`, restore with `pg_restore -d target db.dump`. Good for small databases and moving data between versions.
+- Physical with point-in-time recovery: a base backup (`pg_basebackup` or a tool such as pgBackRest or WAL-G) plus continuous WAL archiving. Use this for production.
+- A backup you have never restored is not a backup. Schedule a restore test and record how long it takes.
+- Managed services: confirm the retention window and PITR setting rather than assuming.
+
+## Never
+
+- Never run `EXPLAIN ANALYZE`, `VACUUM FULL`, `REINDEX` without `CONCURRENTLY`, or any DDL against production without the user's explicit go-ahead.
+- Never disable a constraint or trigger to make a load "faster" without a plan to re-validate.
+- Never build SQL by string concatenation with user input. Use bind parameters.
+- Never change a `postgresql.conf` setting without stating the old value, the new value and how to revert.
+
+## Report back
+
+For a tuning task: the query, the plan's key problem (one line), the change made, before and after timings and buffers, and anything you could not test. For a design task: the DDL, one line per non-obvious choice, and the indexes with the query each one serves.

package/skills/postgres-patterns/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+  "should_trigger": [
+    "This Postgres query takes 4 seconds, here's the EXPLAIN ANALYZE, what index do I need?",
+    "Should I use a GIN index or an expression index for filtering on a JSONB column?",
+    "Design the PostgreSQL tables for subscriptions, invoices and payments with proper constraints",
+    "We keep getting deadlock detected errors in Postgres when two workers update balances",
+    "Set up PgBouncer for our Postgres database, the app keeps running out of connections",
+    "What's the right way to back up a production PostgreSQL database with point-in-time recovery?"
+  ],
+  "should_not_trigger": [
+    "Our MySQL InnoDB table has gap lock deadlocks on insert, how do we avoid them?",
+    "Plan a zero-downtime migration to change orders.id from int to bigint",
+    "Review this pull request's migrations for locking hazards and missing indexes",
+    "Write the Prisma schema and client queries for a blog with posts and comments",
+    "Add caching with Redis in front of the product lookup endpoint"
+  ]
+}

package/skills/postgres-patterns/references/explain.md

@@ -0,0 +1,59 @@
+# Reading PostgreSQL plans
+
+Run `EXPLAIN (ANALYZE, BUFFERS, VERBOSE) <query>;` on a realistic copy. Add `SETTINGS` to show non-default planner settings. For a write, wrap it:
+
+```sql
+BEGIN;
+EXPLAIN (ANALYZE, BUFFERS) UPDATE orders SET status = 'paid' WHERE id = 42;
+ROLLBACK;
+```
+
+## What each number means
+
+- `cost=startup..total`: planner estimate in arbitrary units. Compare only within one plan.
+- `rows=`: estimated rows (first parenthesis) vs actual rows (`actual ... rows=`). A 10x or bigger gap means the planner is guessing; fix stats before anything else.
+- `loops=`: how many times the node ran. Actual time and rows are **per loop**; multiply to get the total.
+- `Buffers: shared hit=` pages found in cache, `read=` pages read from disk or OS cache, `dirtied`/`written` for writes.
+- `Rows Removed by Filter`: rows read then discarded. Large numbers point to a missing or unusable index.
+
+## Nodes and what they suggest
+
+| Node | Usually fine when | Problem sign and fix |
+|---|---|---|
+| Seq Scan | small table, or most rows needed | big table, few rows returned: add an index matching the filter |
+| Index Scan | selective filter | many loops inside a nested loop: check join order and estimates |
+| Index Only Scan | `Heap Fetches` near 0 | high `Heap Fetches`: table needs `VACUUM` so the visibility map is current |
+| Bitmap Heap Scan | medium selectivity | `Recheck Cond` removing many rows with `lossy` blocks: raise `work_mem` for that query |
+| Nested Loop | outer side small | outer side large because of a bad estimate: fix stats or rewrite |
+| Hash Join | medium/large inputs | `Batches` > 1: hash spilled to disk, raise `work_mem` for that session |
+| Merge Join | both inputs already sorted | an explicit `Sort` below it on a huge input |
+| Sort | `Sort Method: quicksort Memory` | `external merge Disk`: add an index matching `ORDER BY`, or raise `work_mem` locally |
+| Limit + Sort | top-N heapsort | scanning the whole table to return 10 rows: index on the sort key |
+
+## Fixing bad estimates
+
+1. `ANALYZE table_name;` then re-plan.
+2. Correlated columns (`city`, `postcode`): `CREATE STATISTICS s (dependencies, ndistinct) ON city, postcode FROM addresses; ANALYZE addresses;`
+3. Skewed column: `ALTER TABLE t ALTER COLUMN c SET STATISTICS 1000; ANALYZE t;`
+4. Generic plan for prepared statements chose badly: test with literal values, and consider `plan_cache_mode = force_custom_plan` for that session only.
+
+## Non-sargable predicates and rewrites
+
+| Slow form | Index-friendly form |
+|---|---|
+| `WHERE date(created_at) = '2024-01-01'` | `WHERE created_at >= '2024-01-01' AND created_at < '2024-01-02'` |
+| `WHERE lower(email) = $1` with a plain index | expression index `ON users (lower(email))` |
+| `WHERE id::text = $1` | compare with the column's own type |
+| `WHERE a = $1 OR b = $1` | two indexed queries joined with `UNION` (or rely on a BitmapOr if both are indexed) |
+| `ORDER BY id LIMIT 20 OFFSET 100000` | keyset: `WHERE id > $last_id ORDER BY id LIMIT 20` |
+| `NOT IN (subquery)` with nullable column | `NOT EXISTS (...)` (also correct with NULLs) |
+
+## Finding the slow queries
+
+```sql
+-- needs the pg_stat_statements extension
+SELECT calls, round(total_exec_time) AS total_ms, round(mean_exec_time, 1) AS mean_ms, query
+FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT 20;
+```
+
+`auto_explain` (with `auto_explain.log_min_duration`) logs plans of slow statements as they run in staging or production.

package/skills/postgres-patterns/references/locks.md

@@ -0,0 +1,53 @@
+# PostgreSQL locks: what blocks what
+
+## Table lock levels you meet most
+
+| Lock | Taken by | Blocks |
+|---|---|---|
+| ACCESS SHARE | `SELECT` | only ACCESS EXCLUSIVE |
+| ROW EXCLUSIVE | `INSERT`, `UPDATE`, `DELETE` | SHARE and stronger (for example plain `CREATE INDEX`) |
+| SHARE UPDATE EXCLUSIVE | `VACUUM`, `ANALYZE`, `CREATE INDEX CONCURRENTLY`, `VALIDATE CONSTRAINT` | other schema changes, not reads or writes |
+| SHARE | plain `CREATE INDEX` | all writes to the table |
+| SHARE ROW EXCLUSIVE | `ADD FOREIGN KEY` (on both tables) | writes |
+| ACCESS EXCLUSIVE | most `ALTER TABLE`, `DROP`, `TRUNCATE`, `VACUUM FULL` | everything, including `SELECT` |
+
+`REINDEX` without `CONCURRENTLY` takes SHARE on the table (blocks writes) and ACCESS EXCLUSIVE on the index (blocks queries that would use it).
+
+The queue matters: an `ALTER TABLE` waiting for ACCESS EXCLUSIVE behind one long transaction makes every later `SELECT` wait behind it. Always set `lock_timeout` before DDL on a busy table:
+
+```sql
+SET lock_timeout = '3s';
+SET statement_timeout = '15min';
+ALTER TABLE ...;
+```
+
+If it times out, retry later; don't raise the timeout to minutes.
+
+## Who is blocking whom
+
+```sql
+SELECT a.pid, a.state, a.wait_event_type, a.wait_event,
+       pg_blocking_pids(a.pid) AS blocked_by,
+       now() - a.xact_start AS xact_age, left(a.query, 120) AS query
+FROM pg_stat_activity a
+WHERE a.datname = current_database() AND a.pid <> pg_backend_pid()
+ORDER BY xact_age DESC NULLS LAST;
+```
+
+Long `idle in transaction` sessions at the top are the usual culprit. `pg_cancel_backend(pid)` cancels the query; `pg_terminate_backend(pid)` drops the connection. Ask the user before running either on a shared server.
+
+## Row locks
+
+- `FOR UPDATE`: you will update or delete the row.
+- `FOR NO KEY UPDATE`: you will update non-key columns; does not block inserts of child rows referencing it. Plain `UPDATE` of non-key columns takes this.
+- `FOR SHARE`: others must not update or delete it.
+- `FOR KEY SHARE`: others must not delete it or change its key; non-key updates still proceed. FK checks take this on the parent row.
+- `NOWAIT` fails immediately instead of waiting; `SKIP LOCKED` skips locked rows (job queues only, it gives an inconsistent view).
+
+## Deadlocks
+
+The server log line `deadlock detected` lists both statements. Fix by locking rows in one order everywhere (sort IDs before a batch update), keeping transactions short, and not mixing `SELECT ... FOR SHARE` then `UPDATE` on the same rows from two sessions.
+
+## Advisory locks
+
+`pg_advisory_xact_lock(key)` serialises work on an app-level key (for example one cron job at a time) and releases at commit. Session-level `pg_advisory_lock` does not work safely behind a transaction-mode pooler.

package/skills/prd-writing/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: prd-writing
+description: Product requirements document (PRD) drafting that starts from the user problem and the evidence for it, sets goals and explicit non-goals, describes target users and scenarios, writes numbered requirements each with testable acceptance criteria and a priority, picks success and guardrail metrics with baselines, lists open questions with owners, and plans a staged rollout. Use when a product manager or engineer needs a PRD, product spec or feature brief written, reviewed or tightened before design and engineering commit to building it.
+license: MIT
+compatibility: Any Agent Skills host. No tools required; reads existing docs or code when the user points to them.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: docs
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# PRD writing
+
+A PRD says what problem to solve, for whom, and how you will know it worked. It does not say how to build it; that belongs in a design doc or an implementation plan.
+
+## 0. Before you write
+
+1. Collect what exists: the request, user research, support tickets, analytics, sales notes, earlier docs. Search the repo or docs folder if the user points to one.
+2. Answer these five questions. If you cannot answer the first two, **stop and ask the user**; do not invent a problem or evidence.
+   - What problem, for which users?
+   - What evidence says it is real and worth solving now (numbers, quotes, tickets, lost deals)?
+   - What does success look like, measurably?
+   - What is out of scope?
+   - What deadline or constraint is fixed (legal date, launch event, contract)?
+3. Find the house template. If the team has one, use its headings and add missing sections below rather than replacing it.
+
+## 1. Problem and evidence
+
+- State the problem from the user's side in two to four sentences. No solution words ("we need a dashboard") in the problem statement.
+- List evidence with its source and date. Mark anecdote as anecdote. If evidence is thin, say so and add "validate the problem" as an open question.
+- Say why now: what it costs to wait.
+
+## 2. Goals and non-goals
+
+- Goals: three at most, each an outcome, not a feature ("cut time to first invoice below 5 minutes", not "add an invoice wizard").
+- Non-goals: things a reader could reasonably expect that you will not do. Each non-goal prevents a later argument, so be specific.
+
+## 3. Users and scenarios
+
+- Name the primary user segment and any secondary ones. Use real segments the team already tracks, not invented personas with names and hobbies.
+- Write three to six scenarios: who, situation, what they try to do, what success looks like for them. Include at least one edge or failure scenario (no data yet, permissions missing, offline, large account).
+
+## 4. Requirements
+
+Number every requirement so reviews and tickets can cite it. Use this shape:
+
+```
+R3 (Must): An admin can invite a teammate by email from the Members page.
+  Acceptance:
+  - Given an admin on Members, when they submit a valid email, then an invite is sent and appears as Pending.
+  - Given an email already on the team, when they submit it, then they see "already a member" and no invite is sent.
+  - Invites expire after 7 days. (Open question Q2: confirm with security.)
+```
+
+Rules:
+
+- Priority on every requirement: Must, Should or Could. If more than about half are Must, push back: ask what ships if time runs out.
+- Acceptance criteria are observable and testable. Ban "fast", "easy", "intuitive" and "seamless" unless given a number or a check.
+- Cover non-functional needs the user cares about: performance targets, accessibility, privacy and data retention, localisation, permissions, audit.
+- Describe behaviour, not UI layout or architecture, unless the constraint is real (for example "must work inside the existing mobile app").
+
+## 5. Metrics
+
+- One primary success metric tied to the goals, with current baseline, target and the date you will read it.
+- One to three guardrail metrics that must not get worse (error rate, support tickets, churn, latency).
+- Say where each metric comes from. If the event or query does not exist yet, add tracking as a requirement.
+- If there is no baseline, say so; do not guess one.
+
+## 6. Open questions and risks
+
+Table of open questions, each with an owner and a date it must be answered by. Risks get a likelihood, an impact and a mitigation. Anything legal, privacy, security or pricing related gets flagged for the owning team; do not answer it yourself.
+
+## 7. Rollout
+
+- Stages: internal, beta or percentage rollout, general availability. Say who is in each and what signal moves you to the next.
+- Feature flag or kill switch, and what turning it off does to users mid-flow.
+- Migration of existing data or users, support and docs readiness, and who announces it.
+- For deploy mechanics (canary, blue-green, flags) defer to the `deployment-strategies` skill if available.
+
+## Output format
+
+Write the PRD as Markdown (or into the user's template) with these headings in order:
+
+```
+# <Feature>: PRD
+Status: Draft | In review | Approved   Owner: <name>   Last updated: <date>
+## Summary            (three sentences: problem, proposal, expected result)
+## Problem and evidence
+## Goals
+## Non-goals
+## Users and scenarios
+## Requirements        (R1..Rn, priority, acceptance criteria)
+## Metrics             (primary, guardrails, baseline, target, source)
+## Open questions      (Q1..Qn, owner, due)
+## Risks
+## Rollout
+## Appendix            (research links, mockups)
+```
+
+Keep it short enough to read in ten minutes. Move research detail to the appendix.
+
+## Reviewing an existing PRD
+
+Check in this order and report findings as a list, most serious first:
+
+1. Is the problem stated without a solution, and is there evidence?
+2. Are goals outcomes with numbers? Are non-goals present?
+3. Does every requirement have a priority and testable acceptance criteria?
+4. Is there a primary metric with a baseline and a guardrail?
+5. Do open questions have owners and dates?
+6. Is there a rollout and a way to turn it off?
+
+## Never
+
+- Never invent user quotes, research findings, metrics or baselines. Mark gaps as open questions.
+- Never pick an implementation (database, framework, architecture) in the PRD; record it as a constraint only if it truly is one.
+- Never mark the PRD Approved; only the named approvers can.
+
+## Neighbours
+
+- Recording a technical decision: `architecture-decision-records`.
+- Turning an agreed PRD into files and steps: the `planner` agent or `/plan-feature`.
+- Sizing the work: `estimation-and-scoping`.

package/skills/prd-writing/evals/triggers.json

@@ -0,0 +1,15 @@
+{
+  "should_trigger": [
+    "Write a PRD for letting admins invite teammates by email, here are the support tickets asking for it",
+    "Can you turn these customer interview notes into a product requirements doc with goals, non-goals and acceptance criteria?",
+    "Review this product spec draft and tell me what's missing before we hand it to engineering",
+    "I need a feature brief for offline mode in the field app: problem, success metrics and rollout stages"
+  ],
+  "should_not_trigger": [
+    "Break the invite-teammates feature down into files to change and tests to write first",
+    "Record our decision to use Postgres instead of DynamoDB as an architecture decision record",
+    "How many weeks will the offline mode feature take? Give me a range with confidence",
+    "Write the release notes for version 2.4 that shipped the invite feature",
+    "Rewrite the README getting-started section so new contributors can run the app"
+  ]
+}

package/skills/prisma-patterns/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: prisma-patterns
+description: Prisma ORM practice for TypeScript backends, detecting whether the project is on Prisma 6, 7 or the Prisma 8 contract-based release, then covering schema modelling, the migrate dev versus deploy workflow, include and select to kill N+1 queries, sequential and interactive transactions, pool sizing behind serverless functions and PgBouncer, and injection-safe raw SQL. Use when editing schema.prisma or a Prisma contract, creating or deploying Prisma migrations, debugging slow Prisma queries or connection pool timeouts, or writing $queryRaw.
+license: MIT
+compatibility: Any Agent Skills host. Needs Node and the project's package manager to run the Prisma CLI. Prisma 7 needs Node 20.19 or later and a driver adapter; Prisma 8 differs a lot, see the reference file.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: data
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "node, npx"
+  kete-loom/owner: "Kete-org"
+---
+
+# Prisma patterns
+
+Prisma changed shape twice in a short time. Find out which major version the project uses **before** writing a line, then follow the rules for that version.
+
+## 0. Detect the version first
+
+1. Read `package.json` for `prisma` and `@prisma/client` (Prisma 6 or 7) or `@prisma/orm-postgres` / `@prisma/orm-mongo` (Prisma 8). Confirm with the project's package manager, for example `npx prisma --version`.
+2. Look for the schema: `prisma/schema.prisma` with `generator` and `datasource` blocks means 6 or 7. A `contract.prisma` starting with `// use prisma-8` means 8.
+3. If it's Prisma 8, read `references/prisma-8.md` and use its command and API names. The rest of this file describes 6 and 7.
+4. **Never upgrade the major version as a side effect.** On a Prisma 7 project, a bare `npm install prisma` can pull the Prisma 8 CLI; pin it (`npm install --save-dev prisma@7`). Ask the user before any major upgrade.
+5. Find the migration history (`prisma/migrations/`) and how CI deploys it. Read `references/workflow.md` before creating or deploying a migration.
+
+## 1. Schema design (6 and 7)
+
+- In Prisma 7, the `generator` block needs an explicit `output` path, datasource URLs move to `prisma.config.ts`, and the client is created with a driver adapter (for example `@prisma/adapter-pg`). Follow the pattern already in the project.
+- Use `@id @default(cuid())`, `uuid()` or `autoincrement()` consistently with the existing models. Map to existing table and column names with `@@map` and `@map` instead of renaming the database.
+- Add `@@index` for every foreign key you filter or join on. PostgreSQL never indexes foreign key columns on its own. MySQL (InnoDB) does when real foreign keys exist, but not with `relationMode = "prisma"`, which needs the indexes added by hand.
+- Use `@@unique` for real invariants (`@@unique([tenantId, email])`), and set `onDelete` explicitly on relations (`Cascade`, `Restrict`, `SetNull`) rather than relying on defaults.
+- Money: `Decimal` (`@db.Decimal(12, 2)`) or integer minor units, never `Float`. Timestamps: `DateTime @default(now())` and `@updatedAt`.
+- Enums are fine for small closed sets; adding a value is a migration.
+
+## 2. Queries and N+1
+
+- Ask for related data in the same call: `include: { posts: true }` or a nested `select`. A loop that calls `findUnique` or `findMany` per parent row is N+1; replace it with one `findMany({ where: { id: { in: ids } } })` or an `include`.
+- `select` only the fields the caller needs, especially on wide tables and in list endpoints.
+- `relationLoadStrategy` is still a Preview feature: it needs `previewFeatures = ["relationJoins"]` in the generator and works on PostgreSQL, CockroachDB and MySQL. With the flag on, `"join"` (one SQL query) is the default and `"query"` sends one query per relation level. Measure both on deep includes, and don't add a preview flag without telling the user.
+- Paginate with `cursor` + `take` on an indexed unique field for large lists; `skip` scans skipped rows.
+- Use `createMany`, `updateMany`, `deleteMany` for bulk work instead of loops; they don't return the rows (use `createManyAndReturn` where supported).
+- To see the SQL, construct the client with `log: ["query"]` in development, then run `EXPLAIN` on the slow statement in the database.
+
+## 3. Transactions
+
+- **Nested writes** (`create` with nested `create`/`connect`) are already one transaction. Prefer them for parent-and-children writes.
+- **Sequential**: `prisma.$transaction([a, b])` runs independent operations atomically.
+- **Interactive**: `prisma.$transaction(async (tx) => { ... })` for read-then-write logic. Use `tx` for every query inside; a query on `prisma` runs outside the transaction. Defaults are `maxWait` 2000 ms and `timeout` 5000 ms; raise them only with a reason.
+- Never do network calls (payments, email, HTTP) inside an interactive transaction: it holds a connection and row locks while it waits.
+- For concurrency-sensitive updates, use an atomic update (`update({ where: { id, version }, data: { balance: { decrement: 10 }, version: { increment: 1 } } })`) or `isolationLevel: "Serializable"` with a retry on serialization failure (`P2034`).
+
+## 4. Connections and serverless
+
+- Create **one** client per process and reuse it. In dev servers with hot reload, keep it on `globalThis` so reloads don't open new pools.
+- Prisma 6: the pool size comes from `connection_limit` in the URL (default `num_physical_cpus * 2 + 1`) and `pool_timeout` (default 10 s). Prisma 7: the driver adapter owns the pool, for example `new PrismaPg({ connectionString, max: 10 })`; `pg` defaults to 10 connections and no acquire timeout, so set `connectionTimeoutMillis`.
+- Serverless functions multiply pools: every warm instance holds its own. Size per-instance pools small (1 to 5), and put a pooler in front (PgBouncer in transaction mode, Supabase's or Neon's pooler, or Prisma Accelerate). On Prisma 6 with PgBouncer, add `pgbouncer=true` to the URL.
+- Migrations must use a **direct** (unpooled) connection: `directUrl` in Prisma 6, the URL in `prisma.config.ts` in Prisma 7.
+- Pool timeout errors (`P2024`) mean the pool is exhausted: look for slow or long transactions and missing `await`s before raising the pool size.
+
+## 5. Raw SQL
+
+- Use tagged templates: ``prisma.$queryRaw`SELECT * FROM "User" WHERE email = ${email}` ``. Values become bound parameters.
+- Build dynamic fragments with `Prisma.sql` and lists with `Prisma.join(ids)`. Identifiers (table or column names) can't be parameters; pick them from a fixed allow-list in code.
+- `$queryRawUnsafe` / `$executeRawUnsafe` and `Prisma.raw` with any user input are SQL injection. Use them only with `$1` placeholders and parameters passed separately, and flag any other use in review.
+- Prefer TypedSQL (`.sql` files in `prisma/sql/`, run through `prisma generate --sql`) for complex reads that must stay typed. Check whether your version still needs the `typedSql` preview feature.
+
+## Never
+
+- Run `prisma migrate dev`, `prisma migrate reset` or `prisma db push` against a shared, staging or production database.
+- Edit a migration that has already been applied anywhere except your machine.
+- Swallow Prisma errors: map known codes (`P2002` unique violation, `P2025` record not found) to domain errors and rethrow the rest.
+- Return raw Prisma models from an API without choosing fields; it leaks columns such as password hashes.
+
+## Report format (when reviewing)
+
+```
+Prisma review: <scope>
+Version: Prisma <6|7|8>, provider <postgresql|mysql|sqlite|mongodb|...>
+Findings:
+1. [severity] <file:line>: <problem> → <fix>
+Migrations: <state of prisma/migrations, drift or pending>
+Not verified: <anything you could not run>
+```

package/skills/prisma-patterns/evals/triggers.json

@@ -0,0 +1,18 @@
+{
+  "should_trigger": [
+    "Our Prisma resolvers fire a query per post to load the author, how do I fix this N+1?",
+    "We get P2024 timed out fetching a new connection from the pool on Vercel with Prisma",
+    "Add a status enum to the Order model in schema.prisma and create the migration",
+    "Is this $queryRawUnsafe call with a template string safe from SQL injection?",
+    "Should we run prisma migrate dev or migrate deploy in our GitHub Actions release job?",
+    "How do interactive transactions work in Prisma when transferring a balance between two accounts?"
+  ],
+  "should_not_trigger": [
+    "Tune this slow Postgres query and add the right index with EXPLAIN ANALYZE",
+    "Write an Entity Framework Core migration for the new Orders table",
+    "Model a one-to-many relationship in Hibernate with JPA annotations",
+    "Design the document schema and indexes for a MongoDB collection of orders",
+    "Set up Redis as a session store with TTLs",
+    "Plan a zero-downtime column rename across our Django and Rails services"
+  ]
+}