@nockdev/awf 6.2.0

package/.agent/skills/cross-cutting/sql/data/indexing.yaml

@@ -0,0 +1,147 @@
+# =============================================================================
+# PostgreSQL 17/18 Indexing Patterns (Feb 2026)
+# =============================================================================
+# Index optimization patterns including PG18 Index Skip Scan
+
+metadata:
+  skill: sql
+  domain: indexing
+  version: "18.0.0"
+  updated: "2026-02-05"
+  patterns_count: 7
+
+patterns:
+  - id: sql001
+    name: B-tree Index
+    category: index
+    version: "13+"
+    description: Default index type for equality and range queries
+    text: btree index primary key unique order sort range equality
+    example: |
+      -- Basic B-tree (default)
+      CREATE INDEX idx_users_email ON users (email);
+
+      -- Composite index (column order matters!)
+      CREATE INDEX idx_orders_date_status 
+        ON orders (created_at DESC, status);
+
+      -- Works for: =, <, >, <=, >=, BETWEEN, IN
+    severity: HIGH
+    docs_url: https://www.postgresql.org/docs/current/indexes-types.html
+
+  - id: sql002
+    name: GIN Index
+    category: index
+    version: "9.1+"
+    description: Generalized Inverted Index for JSONB, arrays, and full-text search
+    text: gin index jsonb full text search array contains fts
+    example: |
+      -- JSONB GIN index (for containment @>, @@ operators)
+      CREATE INDEX idx_data_jsonb ON products USING GIN (metadata);
+
+      -- Array GIN index
+      CREATE INDEX idx_tags ON products USING GIN (tags);
+
+      -- Full-text search
+      CREATE INDEX idx_fts ON articles 
+        USING GIN (to_tsvector('english', content));
+
+      -- Query:
+      SELECT * FROM products WHERE metadata @> '{"active": true}';
+    severity: HIGH
+    docs_url: https://www.postgresql.org/docs/current/gin.html
+
+  - id: sql003
+    name: Covering Index (INCLUDE)
+    category: index
+    version: "11+"
+    description: Include non-key columns to enable index-only scans
+    text: covering index include columns performance index only scan
+    example: |
+      -- Include columns that are frequently selected
+      CREATE INDEX idx_orders_status_covering 
+        ON orders (status) 
+        INCLUDE (total, customer_id, created_at);
+
+      -- This query can use index-only scan:
+      SELECT status, total, customer_id 
+        FROM orders WHERE status = 'pending';
+    severity: HIGH
+    docs_url: https://www.postgresql.org/docs/current/indexes-index-only-scans.html
+
+  - id: sql004
+    name: Partial Index
+    category: index
+    version: "8.0+"
+    description: Index subset of rows with WHERE clause for smaller index size
+    text: partial index filter where condition subset active
+    example: |
+      -- Only index active rows (smaller, faster)
+      CREATE INDEX idx_active_users 
+        ON users (email) 
+        WHERE is_active = true;
+
+      -- Only index unprocessed orders
+      CREATE INDEX idx_pending_orders 
+        ON orders (created_at) 
+        WHERE status = 'pending';
+
+      -- Query must match WHERE clause to use index
+    severity: MEDIUM
+    docs_url: https://www.postgresql.org/docs/current/indexes-partial.html
+
+  - id: sql005
+    name: Index Skip Scan
+    category: index
+    version: "18+"
+    description: PG18 feature - use composite index even when leading column not in WHERE
+    text: index skip scan composite btree leading column pg18 postgresql 18
+    example: |
+      -- Composite index on (country, email)
+      CREATE INDEX idx_users_country_email ON users (country, email);
+
+      -- Before PG18: Sequential scan if country not in WHERE
+      -- PG18+: Index Skip Scan works!
+      SELECT * FROM users WHERE email = 'user@example.com';
+
+      -- Up to 40% faster than sequential scan
+      -- Enable: SET enable_indexskipscan = on; (default in PG18)
+    severity: CRITICAL
+    docs_url: https://www.postgresql.org/docs/18/indexes-skip-scan.html
+
+  - id: sql006
+    name: Parallel GIN Build
+    category: index
+    version: "18+"
+    description: PG18 parallel index build for GIN indexes (faster JSONB/FTS)
+    text: parallel gin index build jsonb full text search performance pg18
+    example: |
+      -- PG18: GIN indexes can be built in parallel
+      SET max_parallel_maintenance_workers = 4;
+
+      CREATE INDEX CONCURRENTLY idx_products_data 
+        ON products USING GIN (data);
+
+      -- Significantly faster for large tables
+    severity: HIGH
+    docs_url: https://www.postgresql.org/docs/18/parallel-plans.html
+
+  - id: sql007
+    name: BRIN Index
+    category: index
+    version: "9.5+"
+    description: Block Range INdex for naturally ordered data (timestamps, sequences)
+    text: brin index block range timestamp sequential date time series
+    example: |
+      -- Perfect for append-only data (logs, events)
+      CREATE INDEX idx_logs_created 
+        ON logs USING BRIN (created_at);
+
+      -- Very small index size but requires data correlation
+      -- Works best when data is inserted in order
+
+      -- Query:
+      SELECT * FROM logs 
+        WHERE created_at >= '2026-01-01';
+    severity: MEDIUM
+    docs_url: https://www.postgresql.org/docs/current/brin.html

package/.agent/skills/cross-cutting/sql/data/json.yaml

@@ -0,0 +1,156 @@
+# =============================================================================
+# PostgreSQL 17/18 JSON & Data Patterns (Feb 2026)
+# =============================================================================
+# JSON_TABLE, JSONB operations, and modern data types
+
+metadata:
+  skill: sql
+  domain: json
+  version: "17.0.0"
+  updated: "2026-02-05"
+  patterns_count: 6
+
+patterns:
+  - id: sql020
+    name: JSONB Operators
+    category: datatype
+    version: "9.4+"
+    description: Binary JSON with efficient querying via operators
+    text: jsonb json binary operators query @ contains exists index
+    example: |
+      -- Access values
+      SELECT data->'name' AS name,       -- Returns JSONB
+             data->>'email' AS email     -- Returns text
+        FROM users;
+
+      -- Nested access
+      SELECT data->'address'->>'city' FROM users;
+
+      -- Check key exists
+      SELECT * FROM users WHERE data ? 'premium';
+
+      -- Contains operator (uses GIN index)
+      SELECT * FROM users 
+        WHERE data @> '{"role": "admin"}';
+    severity: HIGH
+    docs_url: https://www.postgresql.org/docs/current/functions-json.html
+
+  - id: sql021
+    name: JSON_TABLE (PG17)
+    category: function
+    version: "17+"
+    description: Convert JSON to table format for SQL analysis
+    text: json_table jsonb to table convert sql query standard
+    example: |
+      -- PG17: Convert JSON array to table
+      SELECT jt.*
+        FROM products,
+        JSON_TABLE(
+          products.data,
+          '$.items[*]'
+          COLUMNS (
+            id INTEGER PATH '$.id',
+            name TEXT PATH '$.name',
+            price DECIMAL(10,2) PATH '$.price'
+          )
+        ) AS jt;
+
+      -- Great for analytics on JSON data
+    severity: HIGH
+    docs_url: https://www.postgresql.org/docs/17/functions-json.html#FUNCTIONS-SQLJSON-TABLE
+
+  - id: sql022
+    name: JSON_EXISTS/QUERY/VALUE (PG17)
+    category: function
+    version: "17+"
+    description: SQL/JSON path functions for efficient querying
+    text: json_exists json_query json_value path standard sql json
+    example: |
+      -- Check if path exists
+      SELECT * FROM orders
+        WHERE JSON_EXISTS(data, '$.items[*] ? (@.qty > 10)');
+
+      -- Extract value
+      SELECT JSON_VALUE(data, '$.customer.name') FROM orders;
+
+      -- Extract JSON object
+      SELECT JSON_QUERY(data, '$.items[0]') FROM orders;
+    severity: HIGH
+    docs_url: https://www.postgresql.org/docs/17/functions-json.html#FUNCTIONS-SQLJSON-PATH
+
+  - id: sql023
+    name: UUIDv7 (PG18)
+    category: datatype
+    version: "18+"
+    description: Time-ordered UUIDs for better B-tree performance
+    text: uuidv7 uuid v7 timestamp ordered unique identifier pg18
+    example: |
+      -- PG18: Native UUIDv7 support
+      SELECT uuidv7();
+      -- Returns: 01902d1c-45e0-7000-8000-000000000001
+
+      -- Better than UUIDv4 for primary keys:
+      -- - Time-ordered = less B-tree fragmentation
+      -- - Better insert performance
+      -- - Contains timestamp for debugging
+
+      CREATE TABLE orders (
+        id uuid PRIMARY KEY DEFAULT uuidv7(),
+        created_at timestamp GENERATED ALWAYS AS (
+          uuid_extract_timestamp(id)
+        ) STORED
+      );
+    severity: HIGH
+    docs_url: https://www.postgresql.org/docs/18/functions-uuid.html
+
+  - id: sql024
+    name: JSONB Path Updates
+    category: function
+    version: "14+"
+    description: Update nested JSONB values efficiently
+    text: jsonb set path update nested modify
+    example: |
+      -- Update nested value
+      UPDATE users 
+        SET data = jsonb_set(
+          data, 
+          '{address,city}', 
+          '"San Francisco"'
+        )
+        WHERE id = 1;
+
+      -- Remove key
+      UPDATE users 
+        SET data = data - 'temporary_field';
+
+      -- Merge JSONB
+      UPDATE users 
+        SET data = data || '{"verified": true}';
+    severity: MEDIUM
+    docs_url: https://www.postgresql.org/docs/current/functions-json.html#FUNCTIONS-JSON-PROCESSING
+
+  - id: sql025
+    name: Generated Columns
+    category: ddl
+    version: "12+"
+    description: Computed columns that update automatically
+    text: generated column computed stored virtual
+    example: |
+      -- Stored generated column (persisted)
+      CREATE TABLE products (
+        price_cents integer,
+        price_dollars numeric 
+          GENERATED ALWAYS AS (price_cents / 100.0) STORED
+      );
+
+      -- Extract from JSONB
+      CREATE TABLE users (
+        data jsonb,
+        email text 
+          GENERATED ALWAYS AS (data->>'email') STORED
+      );
+
+      -- Can be indexed!
+      CREATE INDEX idx_users_email ON users (email);
+    severity: MEDIUM
+    docs_url: https://www.postgresql.org/docs/current/ddl-generated-columns.html

package/.agent/skills/cross-cutting/sql/data/performance.yaml

@@ -0,0 +1,204 @@
+# =============================================================================
+# PostgreSQL 17/18 Performance Patterns (Feb 2026)
+# =============================================================================
+# Query optimization and performance monitoring
+
+metadata:
+  skill: sql
+  domain: performance
+  version: "18.0.0"
+  updated: "2026-02-05"
+  patterns_count: 9
+
+patterns:
+  - id: sql010
+    name: EXPLAIN ANALYZE
+    category: monitoring
+    version: "8.0+"
+    description: Analyze query execution plan with timing and buffers
+    text: explain analyze buffers query plan execution performance
+    example: |
+      EXPLAIN (ANALYZE, BUFFERS, TIMING, VERBOSE)
+      SELECT * FROM orders 
+        WHERE customer_id = 123 
+        AND created_at > '2026-01-01';
+
+      -- Look for:
+      -- - Sequential scans on large tables (bad)
+      -- - High buffer reads (caching issue)
+      -- - Actual vs Planned rows mismatch (stats outdated)
+    severity: HIGH
+    docs_url: https://www.postgresql.org/docs/current/sql-explain.html
+
+  - id: sql011
+    name: Async I/O (PG18)
+    category: performance
+    version: "18+"
+    description: PG18 asynchronous I/O for 3x faster sequential scans
+    text: aio async io performance sequential scan vacuum pg18
+    example: |
+      -- PG18: Async I/O enabled by default for read-heavy workloads
+      -- Up to 3x faster sequential scans
+      -- Up to 3x faster VACUUM operations
+
+      -- Check if AIO is being used:
+      SELECT * FROM pg_stat_io;
+
+      -- Good for: Data warehousing, analytics, bulk operations
+    severity: CRITICAL
+    docs_url: https://www.postgresql.org/docs/18/asynchronous-io.html
+
+  - id: sql012
+    name: pg_stat_statements
+    category: monitoring
+    version: "8.4+"
+    description: Track execution statistics of all SQL statements
+    text: pg_stat_statements monitoring slow query execution stats
+    example: |
+      -- Enable extension
+      CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
+
+      -- Find slowest queries
+      SELECT query, calls, total_exec_time / calls AS avg_time
+        FROM pg_stat_statements
+        ORDER BY total_exec_time DESC
+        LIMIT 10;
+
+      -- Find most frequent queries
+      SELECT query, calls FROM pg_stat_statements
+        ORDER BY calls DESC LIMIT 10;
+    severity: HIGH
+    docs_url: https://www.postgresql.org/docs/current/pgstatstatements.html
+
+  - id: sql013
+    name: pg_stat_io (PG16+)
+    category: monitoring
+    version: "16+"
+    description: I/O statistics for understanding disk/buffer activity
+    text: pg_stat_io statistics monitoring reads writes buffer io
+    example: |
+      -- View I/O statistics by backend type
+      SELECT backend_type, reads, writes, hits
+        FROM pg_stat_io
+        WHERE backend_type = 'client backend';
+
+      -- Calculate cache hit ratio
+      SELECT 
+        sum(hits) / nullif(sum(hits) + sum(reads), 0) 
+          AS cache_hit_ratio
+        FROM pg_stat_io;
+    severity: MEDIUM
+    docs_url: https://www.postgresql.org/docs/current/monitoring-stats.html#MONITORING-PG-STAT-IO
+
+  - id: sql014
+    name: Connection Pooling
+    category: performance
+    version: "all"
+    description: Use connection pooler (PgBouncer) for high concurrency
+    text: connection pool pgbouncer connectionlimit performance
+    example: |
+      -- Check current connections
+      SELECT count(*) FROM pg_stat_activity;
+
+      -- PostgreSQL max_connections (default 100)
+      SHOW max_connections;
+
+      -- PgBouncer config (pgbouncer.ini)
+      [databases]
+      mydb = host=localhost dbname=mydb
+
+      [pgbouncer]
+      pool_mode = transaction
+      max_client_conn = 1000
+      default_pool_size = 20
+    severity: HIGH
+    docs_url: https://www.pgbouncer.org/
+
+  - id: sql015
+    name: VACUUM and ANALYZE
+    category: maintenance
+    version: "8.0+"
+    description: Reclaim storage and update query planner statistics
+    text: vacuum analyze maintenance autovacuum statistics bloat
+    example: |
+      -- Manual vacuum
+      VACUUM (VERBOSE) orders;
+
+      -- Update statistics
+      ANALYZE orders;
+
+      -- Check autovacuum status
+      SELECT schemaname, relname, 
+             last_vacuum, last_autovacuum,
+             n_dead_tup
+        FROM pg_stat_user_tables
+        WHERE n_dead_tup > 10000;
+
+      -- PG18: pg_upgrade preserves optimizer stats!
+    severity: HIGH
+    docs_url: https://www.postgresql.org/docs/current/routine-vacuuming.html
+
+  - id: sql016
+    name: Parallel Query
+    category: performance
+    version: "9.6+"
+    description: Parallelize sequential scans, aggregates, and joins
+    text: parallel query workers sequential scan aggregate
+    example: |
+      -- Check parallel settings
+      SHOW max_parallel_workers_per_gather;
+
+      -- Enable more parallelism
+      SET max_parallel_workers_per_gather = 4;
+
+      -- Parallel-eligible query
+      EXPLAIN SELECT count(*) FROM large_table 
+        WHERE status = 'active';
+
+      -- Look for "Gather" node in plan
+    severity: MEDIUM
+    docs_url: https://www.postgresql.org/docs/current/parallel-query.html
+
+  - id: sql017
+    name: pg_aios View (PG18)
+    category: monitoring
+    version: "18+"
+    description: Monitor async I/O operations with real-time statistics
+    text: pg_aios async io monitoring statistics view aio operations
+    example: |
+      -- View active async I/O operations
+      SELECT * FROM pg_aios;
+
+      -- Monitor AIO by backend
+      SELECT 
+        pid, 
+        state, 
+        io_type,
+        blocks_requested,
+        blocks_completed
+      FROM pg_aios 
+      WHERE state = 'in_progress';
+    severity: HIGH
+    docs_url: https://www.postgresql.org/docs/18/asynchronous-io.html
+
+  - id: sql018
+    name: io_uring (PG18 Linux)
+    category: performance
+    version: "18+"
+    description: Linux io_uring backend for maximum async I/O performance
+    text: io_uring linux kernel async io performance ring buffer
+    example: |
+      -- PG18 supports two AIO backends:
+      -- 1. io_uring (Linux 5.1+) - fastest, uses kernel ring buffers
+      -- 2. worker - cross-platform, uses worker processes
+
+      -- Check AIO configuration
+      SHOW io_method;
+      -- Default: io_uring on Linux, worker on other platforms
+
+      -- Benefits:
+      -- - 2-3x faster sequential scans
+      -- - 2-3x faster bitmap heap scans
+      -- - No application code changes needed
+    severity: CRITICAL
+    docs_url: https://www.postgresql.org/docs/18/asynchronous-io.html

package/.agent/skills/cross-cutting/sql/data/queries.yaml

@@ -0,0 +1,150 @@
+# =============================================================================
+# PostgreSQL Query Patterns (Feb 2026)
+# =============================================================================
+# Common query patterns and advanced SQL features
+
+metadata:
+  skill: sql
+  domain: queries
+  version: "17.0.0"
+  updated: "2026-02-05"
+  patterns_count: 6
+
+patterns:
+  - id: sql030
+    name: Common Table Expression (CTE)
+    category: query
+    version: "8.4+"
+    description: WITH clause for readable, reusable query parts
+    text: cte common table expression with recursive query readable
+    example: |
+      WITH active_customers AS (
+        SELECT id, name, email
+          FROM customers
+          WHERE is_active = true
+      ),
+      recent_orders AS (
+        SELECT customer_id, count(*) as order_count
+          FROM orders
+          WHERE created_at > now() - interval '30 days'
+          GROUP BY customer_id
+      )
+      SELECT c.name, r.order_count
+        FROM active_customers c
+        JOIN recent_orders r ON c.id = r.customer_id;
+
+      -- PG17: Improved CTE planning and materialization
+    severity: HIGH
+    docs_url: https://www.postgresql.org/docs/current/queries-with.html
+
+  - id: sql031
+    name: Window Functions
+    category: query
+    version: "8.4+"
+    description: Perform calculations across related rows
+    text: window function rank row_number partition over running total
+    example: |
+      -- Row number by category
+      SELECT 
+        product_name,
+        category,
+        price,
+        ROW_NUMBER() OVER (
+          PARTITION BY category 
+          ORDER BY price DESC
+        ) as rank
+        FROM products;
+
+      -- Running total
+      SELECT 
+        date, 
+        amount,
+        SUM(amount) OVER (ORDER BY date) as running_total
+        FROM transactions;
+    severity: HIGH
+    docs_url: https://www.postgresql.org/docs/current/tutorial-window.html
+
+  - id: sql032
+    name: UPSERT (ON CONFLICT)
+    category: dml
+    version: "9.5+"
+    description: Insert or update on conflict
+    text: upsert insert on conflict update nothing do merge
+    example: |
+      -- Update on conflict
+      INSERT INTO products (sku, name, price)
+        VALUES ('ABC123', 'Widget', 29.99)
+        ON CONFLICT (sku) 
+        DO UPDATE SET 
+          name = EXCLUDED.name,
+          price = EXCLUDED.price,
+          updated_at = now();
+
+      -- Insert or ignore
+      INSERT INTO logs (event_id, message)
+        VALUES ('evt123', 'User login')
+        ON CONFLICT (event_id) DO NOTHING;
+    severity: HIGH
+    docs_url: https://www.postgresql.org/docs/current/sql-insert.html#SQL-ON-CONFLICT
+
+  - id: sql033
+    name: LATERAL Join
+    category: query
+    version: "9.3+"
+    description: Subquery that references preceding FROM items
+    text: lateral join subquery correlated top n per group
+    example: |
+      -- Top 3 orders per customer
+      SELECT c.name, o.*
+        FROM customers c
+        CROSS JOIN LATERAL (
+          SELECT * FROM orders
+            WHERE customer_id = c.id
+            ORDER BY created_at DESC
+            LIMIT 3
+        ) o;
+
+      -- More efficient than correlated subqueries
+    severity: MEDIUM
+    docs_url: https://www.postgresql.org/docs/current/queries-table-expressions.html#QUERIES-LATERAL
+
+  - id: sql034
+    name: Transaction & Savepoints
+    category: safety
+    version: "8.0+"
+    description: ACID transactions with partial rollback support
+    text: transaction begin commit rollback savepoint isolation
+    example: |
+      BEGIN;
+
+      INSERT INTO orders (id, total) VALUES (1, 100.00);
+      SAVEPOINT order_created;
+
+      -- Try to update inventory
+      UPDATE products SET stock = stock - 1 WHERE id = 42;
+
+      -- If error, rollback to savepoint
+      ROLLBACK TO order_created;
+
+      -- Or commit all
+      COMMIT;
+    severity: HIGH
+    docs_url: https://www.postgresql.org/docs/current/sql-savepoint.html
+
+  - id: sql035
+    name: Parallel COPY (PG18)
+    category: bulk
+    version: "18+"
+    description: PG18 parallel COPY FROM for faster bulk imports
+    text: parallel copy from import bulk load csv pg18
+    example: |
+      -- PG18: Parallel COPY FROM
+      SET max_parallel_workers = 4;
+
+      COPY large_table FROM '/data/input.csv'
+        WITH (FORMAT csv, HEADER true);
+
+      -- Significant speedup for large imports
+      -- Works with CSV, binary formats
+    severity: HIGH
+    docs_url: https://www.postgresql.org/docs/18/sql-copy.html