@nockdev/awf 6.2.0

package/.agent/skills/cross-cutting/database/data/anti_patterns.yaml

@@ -0,0 +1,116 @@
+# Anti-Patterns - HSA Database Skill
+# Common database mistakes and how to fix them
+# Updated: 2026-02-05
+
+patterns:
+  - id: ap001
+    pattern: N+1 Query
+    category: query
+    description: Loop with individual queries instead of batch/join
+    fix: Use JOINs, batch loading, or ORM eager loading
+    example_bad: |
+      for user in users:
+        posts = db.query(Post).filter(Post.user_id == user.id)
+    example_good: |
+      users = db.query(User).options(joinedload(User.posts)).all()
+    severity: CRITICAL
+
+  - id: ap002
+    pattern: SELECT *
+    category: query
+    description: Fetching all columns when only few needed
+    fix: Select only required columns
+    example_bad: "SELECT * FROM users"
+    example_good: "SELECT id, name, email FROM users"
+    severity: HIGH
+
+  - id: ap003
+    pattern: Missing Index
+    category: optimization
+    description: Full table scan on frequently queried columns
+    fix: Add appropriate indexes, analyze with EXPLAIN
+    example_bad: "No index on WHERE clause columns"
+    example_good: "CREATE INDEX idx_users_email ON users(email)"
+    severity: CRITICAL
+
+  - id: ap004
+    pattern: Unbounded Query
+    category: query
+    description: SELECT without LIMIT returning millions of rows
+    fix: Always paginate with LIMIT/OFFSET or cursor
+    example_bad: "SELECT * FROM orders"
+    example_good: "SELECT * FROM orders LIMIT 100 OFFSET 0"
+    severity: HIGH
+
+  - id: ap005
+    pattern: String Concatenation SQL
+    category: security
+    description: Building SQL with string concatenation
+    fix: Use parameterized queries/prepared statements
+    example_bad: "SELECT * FROM users WHERE id = ' + id + '"
+    example_good: "SELECT * FROM users WHERE id = $1"
+    severity: CRITICAL
+
+  - id: ap006
+    pattern: No Connection Pooling
+    category: performance
+    description: New connection per query
+    fix: Use connection pool (PgBouncer, HikariCP)
+    example_bad: "Connect/disconnect for each request"
+    example_good: "max_pool_size=20, min_pool_size=5"
+    severity: HIGH
+
+  - id: ap007
+    pattern: Transaction Too Long
+    category: transaction
+    description: Holding locks for extended periods
+    fix: Keep transactions short, do I/O outside
+    example_bad: "BEGIN; long_operation(); external_api(); COMMIT;"
+    example_good: "fetch_data(); BEGIN; quick_update(); COMMIT;"
+    severity: HIGH
+
+  - id: ap008
+    pattern: No Retry Logic
+    category: resilience
+    description: Failing on transient errors
+    fix: Implement retry with exponential backoff
+    example_bad: "Single attempt, fail on error"
+    example_good: |
+      retry(max_attempts=3, backoff_factor=2)
+    severity: MEDIUM
+
+  - id: ap009
+    pattern: Storing Files in Database
+    category: data
+    description: Large binary data in DB columns
+    fix: Use object storage (S3, GCS), store URL in DB
+    example_bad: "BYTEA/BLOB for images"
+    example_good: "VARCHAR for S3 URL, files in object storage"
+    severity: MEDIUM
+
+  - id: ap010
+    pattern: Missing Soft Delete
+    category: data
+    description: Hard deleting records, losing audit trail
+    fix: Use deleted_at timestamp for soft deletes
+    example_bad: "DELETE FROM users WHERE id = 1"
+    example_good: "UPDATE users SET deleted_at = NOW() WHERE id = 1"
+    severity: MEDIUM
+
+  - id: ap011
+    pattern: No Read Replicas
+    category: scaling
+    description: Single DB for read-heavy workloads
+    fix: Use read replicas for read scaling
+    example_bad: "All queries to primary"
+    example_good: "Writes to primary, reads to replicas"
+    severity: MEDIUM
+
+  - id: ap012
+    pattern: Storing Secrets in DB
+    category: security
+    description: Plain text passwords or API keys
+    fix: Hash passwords (bcrypt/argon2), use secrets manager
+    example_bad: "password VARCHAR NOT NULL"
+    example_good: "password_hash VARCHAR NOT NULL (bcrypt)"
+    severity: CRITICAL

package/.agent/skills/cross-cutting/database/data/distributed.yaml

@@ -0,0 +1,152 @@
+# Distributed Database Patterns - HSA Database Skill
+# NewSQL, Cloud-native, Multi-region
+# Updated: 2026-02-05
+
+patterns:
+  # TiDB
+  - id: dist001
+    database: TiDB
+    type: NewSQL
+    category: distributed
+    description: MySQL-compatible, horizontal scaling, HTAP
+    use_cases:
+      - MySQL replacement at scale
+      - Real-time analytics + OLTP
+      - Multi-region deployment
+    example: "CREATE PLACEMENT POLICY asia PRIMARY_REGION='ap-east-1'"
+    connection: "Compatible with MySQL drivers"
+
+  # CockroachDB
+  - id: dist002
+    database: CockroachDB
+    type: NewSQL
+    category: distributed
+    description: PostgreSQL-compatible, survivable, serializable
+    use_cases:
+      - Global applications
+      - Zero-downtime deployments
+      - Regulatory compliance (data locality)
+    example: "SET locality = 'region=us-east,zone=a'"
+    connection: "Compatible with PostgreSQL drivers"
+
+  # PlanetScale
+  - id: dist003
+    database: PlanetScale
+    type: MySQL
+    category: managed
+    description: MySQL-powered serverless, branching, non-blocking migrations
+    use_cases:
+      - Serverless MySQL
+      - Schema branching (Git-like)
+      - Zero-downtime schema changes
+    example: "pscale branch create main feature-branch"
+    connection: "MySQL-compatible, edge-ready"
+
+  # Vitess
+  - id: dist004
+    database: Vitess
+    type: MySQL
+    category: sharding
+    description: MySQL sharding, YouTube-scale
+    use_cases:
+      - MySQL horizontal scaling
+      - Connection pooling
+      - Query routing
+    example: "VSchema defines sharding strategy"
+    connection: "VTGate handles routing"
+
+  # SurrealDB
+  - id: dist005
+    database: SurrealDB
+    type: Multi-model
+    category: distributed
+    description: Document, graph, relational in one database
+    use_cases:
+      - Real-time collaboration
+      - Graph traversal + documents
+      - Embedded or server mode
+    example: |
+      DEFINE TABLE user SCHEMAFULL;
+      RELATE user:1->knows->user:2;
+    connection: "HTTP, WebSocket, Rust SDK"
+
+  # DynamoDB
+  - id: dist006
+    database: DynamoDB
+    type: NoSQL
+    category: managed
+    description: AWS serverless key-value/document, single-digit ms
+    use_cases:
+      - Session storage
+      - Gaming leaderboards
+      - IoT data ingestion
+    example: "PK: USER#123, SK: ORDER#456"
+    connection: "AWS SDK, PartiQL"
+
+  # Neo4j
+  - id: dist007
+    database: Neo4j
+    type: Graph
+    category: specialized
+    description: Property graph, Cypher queries
+    use_cases:
+      - Social networks
+      - Recommendation engines
+      - Fraud detection
+    example: "MATCH (u:User)-[:FOLLOWS]->(f) RETURN f"
+    connection: "Bolt protocol, drivers for all languages"
+
+  # Neon
+  - id: dist008
+    database: Neon
+    type: PostgreSQL
+    category: serverless
+    description: Serverless PostgreSQL, branching, autoscaling
+    use_cases:
+      - Serverless PostgreSQL
+      - Database branching for dev/preview
+      - Pay-per-query
+    example: "neon branches create --name feature-x"
+    connection: "PostgreSQL-compatible"
+
+  # Supabase
+  - id: dist009
+    database: Supabase
+    type: PostgreSQL
+    category: platform
+    description: Open-source Firebase alternative, PostgreSQL
+    use_cases:
+      - Realtime subscriptions
+      - Auth + Storage + Edge Functions
+      - Rapid prototyping
+    example: "supabase.from('users').select('*').subscribe()"
+    connection: "PostgreSQL, REST, Realtime"
+
+  # ClickHouse
+  - id: dist010
+    database: ClickHouse
+    type: OLAP
+    category: analytics
+    description: Column-oriented, real-time analytics at scale
+    use_cases:
+      - Log analytics
+      - Time-series at scale
+      - Business intelligence
+    example: "SELECT toStartOfHour(ts), count() FROM logs GROUP BY 1"
+    connection: "HTTP, native protocol, JDBC"
+
+anti_patterns:
+  - id: dist_ap001
+    pattern: Single-region for global apps
+    description: High latency for distant users
+    fix: Use multi-region databases (CockroachDB, TiDB, DynamoDB Global Tables)
+
+  - id: dist_ap002
+    pattern: Traditional DB for serverless
+    description: Connection limits, cold starts
+    fix: Use serverless DBs (PlanetScale, Neon, DynamoDB)
+
+  - id: dist_ap003
+    pattern: Relational for highly connected data
+    description: JOIN explosions for graph queries
+    fix: Use graph databases (Neo4j, SurrealDB)

package/.agent/skills/cross-cutting/database/data/mongodb.yaml

@@ -0,0 +1,132 @@
+# MongoDB Patterns - HSA Database Skill
+# Version: MongoDB 8.2 (2025)
+# Updated: 2026-02-05
+
+patterns:
+  # Optimization
+  - id: mo001
+    pattern: Compound Index
+    category: optimization
+    version: all
+    description: Order indexes by equality, sort, range (ESR rule)
+    example: "db.collection.createIndex({ status: 1, date: -1 })"
+    severity: HIGH
+
+  - id: mo002
+    pattern: Express Path
+    category: performance
+    version: "8"
+    description: MongoDB 8 fast execution for simple index lookups
+    example: "Automatic for _id and simple equality queries"
+    severity: MEDIUM
+
+  - id: mo003
+    pattern: Embed vs Reference
+    category: data
+    version: all
+    description: Embed frequently accessed data, reference large/unbounded
+    example: "Embed: user.address, Reference: user.orders[]"
+    severity: HIGH
+
+  # Query
+  - id: mo004
+    pattern: Aggregation Pipeline
+    category: query
+    version: all
+    description: Use aggregation for complex queries, $match early
+    example: "db.orders.aggregate([{$match: {status: 'active'}}, {$group: ...}])"
+    severity: MEDIUM
+
+  - id: mo005
+    pattern: Text Search
+    category: query
+    version: all
+    description: Full-text search with text indexes
+    example: "db.articles.createIndex({ content: 'text' })"
+    severity: MEDIUM
+
+  # Security - Queryable Encryption
+  - id: mo006
+    pattern: Queryable Encryption
+    category: security
+    version: "7+"
+    description: Client-side encryption with query support
+    example: "encryptedFieldsMap: { 'ssn': { keyId: ..., queries: 'equality' } }"
+    severity: CRITICAL
+
+  - id: mo007
+    pattern: QE Range Queries
+    category: security
+    version: "8"
+    description: Range queries on encrypted fields ($gt, $lt, $gte, $lte)
+    example: "db.patients.find({ age: { $gte: 21 } }) // encrypted"
+    severity: HIGH
+
+  - id: mo008
+    pattern: QE Prefix/Suffix
+    category: security
+    version: "8.2"
+    description: Prefix, suffix, substring on encrypted (preview)
+    example: "queries: ['prefix', 'suffix'] // GA in 2026"
+    severity: LOW
+
+  # Realtime
+  - id: mo009
+    pattern: Change Streams
+    category: realtime
+    version: "3.6+"
+    description: React to data changes in real-time
+    example: "db.collection.watch([{ $match: { operationType: 'insert' } }])"
+    severity: MEDIUM
+
+  # Scaling
+  - id: mo010
+    pattern: Sharding Strategy
+    category: scaling
+    version: all
+    description: Choose shard key - high cardinality, even distribution
+    example: "sh.shardCollection('db.orders', { customerId: 'hashed' })"
+    severity: CRITICAL
+
+  # Debug
+  - id: mo011
+    pattern: Query Profiler
+    category: debug
+    version: all
+    description: Profile slow queries
+    example: "db.setProfilingLevel(1, { slowms: 100 })"
+    severity: HIGH
+
+  # Data Types
+  - id: mo012
+    pattern: Time Series
+    category: data
+    version: "5+"
+    description: Use time series collections for IoT/metrics
+    example: "db.createCollection('metrics', { timeseries: { timeField: 'ts' } })"
+    severity: LOW
+
+  - id: mo013
+    pattern: Vector Search
+    category: data
+    version: "7+"
+    description: Atlas Vector Search for semantic queries
+    example: "{ $vectorSearch: { queryVector: [...], path: 'embedding' } }"
+    severity: MEDIUM
+
+  # Transactions
+  - id: mo014
+    pattern: Multi-Document Transactions
+    category: transaction
+    version: "4.0+"
+    description: ACID transactions across multiple documents
+    example: "session.withTransaction(async () => { ... })"
+    severity: HIGH
+
+  - id: mo015
+    pattern: Read Concern
+    category: transaction
+    version: all
+    description: Control consistency vs availability
+    example: "{ readConcern: { level: 'majority' } }"
+    severity: MEDIUM

package/.agent/skills/cross-cutting/database/data/mysql.yaml

@@ -0,0 +1,130 @@
+# MySQL Patterns - HSA Database Skill
+# Version: MySQL 9.4 (Jul 2025)
+# Updated: 2026-02-05
+
+patterns:
+  # Performance
+  - id: my001
+    pattern: InnoDB Buffer Pool
+    category: performance
+    version: "8+"
+    description: Set innodb_buffer_pool_size to 50-70% RAM
+    example: "innodb_buffer_pool_size = 8G"
+    severity: CRITICAL
+
+  - id: my002
+    pattern: Parallel Query
+    category: performance
+    version: "9"
+    description: MySQL 9 parallel query execution across CPU cores
+    example: "SET SESSION parallel_degree = 4"
+    severity: MEDIUM
+
+  - id: my003
+    pattern: Covering Index
+    category: optimization
+    version: all
+    description: Include all columns in index to avoid table lookup
+    example: "CREATE INDEX idx ON orders (user_id, status, created_at)"
+    severity: HIGH
+
+  - id: my004
+    pattern: Invisible Indexes
+    category: optimization
+    version: "8+"
+    description: Test index removal impact without dropping
+    example: "ALTER TABLE orders ALTER INDEX idx_status INVISIBLE"
+    severity: MEDIUM
+
+  # New in MySQL 9
+  - id: my005
+    pattern: Vector Data Type
+    category: data
+    version: "9.0"
+    description: Native vector support for ML/AI workloads
+    example: "embedding VECTOR(1536)"
+    severity: MEDIUM
+
+  - id: my006
+    pattern: JSON Duality Views
+    category: data
+    version: "9.4"
+    description: Expose relational data as JSON documents
+    example: "CREATE JSON DUALITY VIEW users_json AS SELECT * FROM users"
+    severity: LOW
+
+  - id: my007
+    pattern: JavaScript Stored Programs
+    category: data
+    version: "9.0"
+    description: Create functions/procedures in JavaScript
+    example: "CREATE FUNCTION js_func() RETURNS ... LANGUAGE JAVASCRIPT ..."
+    severity: LOW
+
+  # Debug
+  - id: my008
+    pattern: Slow Query Log
+    category: debug
+    version: all
+    description: Enable and analyze slow query log
+    example: "slow_query_log = 1, long_query_time = 0.5"
+    severity: HIGH
+
+  - id: my009
+    pattern: EXPLAIN ANALYZE JSON
+    category: debug
+    version: "9.2"
+    description: JSON output for execution plans
+    example: "EXPLAIN ANALYZE FORMAT=JSON SELECT ..."
+    severity: MEDIUM
+
+  # Security
+  - id: my010
+    pattern: Prepared Statements
+    category: security
+    version: all
+    description: Always use prepared statements for SQL injection prevention
+    example: "PREPARE stmt FROM 'SELECT * FROM users WHERE id = ?'"
+    severity: CRITICAL
+
+  - id: my011
+    pattern: caching_sha2_password
+    category: security
+    version: "9"
+    description: Default auth method (mysql_native_password removed)
+    example: "CREATE USER 'app'@'%' IDENTIFIED BY 'password'"
+    severity: MEDIUM
+
+  # Scaling
+  - id: my012
+    pattern: Partitioning
+    category: scaling
+    version: all
+    description: Partition large tables by date/range
+    example: "PARTITION BY RANGE (YEAR(created_at))"
+    severity: MEDIUM
+
+  - id: my013
+    pattern: Group Replication
+    category: scaling
+    version: "8+"
+    description: Multi-primary clustering for high availability
+    example: "Plugin: group_replication"
+    severity: HIGH
+
+  # HeatWave
+  - id: my014
+    pattern: HeatWave Lakehouse
+    category: analytics
+    version: "9.1+"
+    description: Query data from object storage
+    example: "SELECT * FROM ... INTO OUTFILE 's3://bucket/'"
+    severity: LOW
+
+  - id: my015
+    pattern: HeatWave AutoML
+    category: analytics
+    version: "9.4"
+    description: Natural language to ML models
+    example: "CALL sys.ML_TRAIN('table', 'target', NULL)"
+    severity: LOW

package/.agent/skills/cross-cutting/database/data/orm.yaml

@@ -0,0 +1,104 @@
+# ORM Patterns - HSA Database Skill
+# Supports: Prisma, Drizzle, TypeORM, SQLAlchemy, GORM, Ecto
+# Updated: 2026-02-05
+
+patterns:
+  # Prisma
+  - id: orm001
+    orm: Prisma
+    language: typescript
+    n_plus_one: "include: { posts: true }"
+    raw_query: "prisma.$queryRaw`SELECT * FROM users`"
+    transactions: "prisma.$transaction([...])"
+    relation: "@relation(fields: [authorId], references: [id])"
+    strength: Type-safe, migrations, Prisma Studio
+
+  # Drizzle
+  - id: orm002
+    orm: Drizzle
+    language: typescript
+    n_plus_one: "with: { posts: true }"
+    raw_query: "sql`SELECT * FROM users`"
+    transactions: "db.transaction(async (tx) => {...})"
+    relation: "relations(users, ({ many }) => ({ posts: many(posts) }))"
+    strength: SQL-first, lightweight, serverless-friendly
+
+  # TypeORM
+  - id: orm003
+    orm: TypeORM
+    language: typescript
+    n_plus_one: "relations: ['posts']"
+    raw_query: "dataSource.query('SELECT * FROM users')"
+    transactions: "@Transaction() / queryRunner.startTransaction()"
+    relation: "@ManyToOne(() => User)"
+    strength: Decorator-based, NestJS integration
+
+  # SQLAlchemy
+  - id: orm004
+    orm: SQLAlchemy
+    language: python
+    n_plus_one: "joinedload(User.posts)"
+    raw_query: "session.execute(text('SELECT * FROM users'))"
+    transactions: "with session.begin():"
+    relation: "relationship('Post', back_populates='author')"
+    strength: Industry standard, async 2.0, flexible
+
+  # Django ORM
+  - id: orm005
+    orm: Django ORM
+    language: python
+    n_plus_one: "select_related('author') / prefetch_related('posts')"
+    raw_query: "Model.objects.raw('SELECT * FROM users')"
+    transactions: "@transaction.atomic"
+    relation: "ForeignKey(User, on_delete=CASCADE)"
+    strength: Batteries included, admin panel
+
+  # GORM
+  - id: orm006
+    orm: GORM
+    language: go
+    n_plus_one: "Preload('Posts')"
+    raw_query: "db.Raw('SELECT * FROM users').Scan(&users)"
+    transactions: "db.Transaction(func(tx *gorm.DB) error {...})"
+    relation: "Has Many / Belongs To"
+    strength: Go standard, AutoMigrate
+
+  # Ecto
+  - id: orm007
+    orm: Ecto
+    language: elixir
+    n_plus_one: "preload: [:posts]"
+    raw_query: "Ecto.Adapters.SQL.query(Repo, 'SELECT * FROM users')"
+    transactions: "Repo.transaction(fn -> ... end)"
+    relation: "has_many :posts, Post"
+    strength: Functional, composable, Phoenix
+
+  # Mongoose
+  - id: orm008
+    orm: Mongoose
+    language: typescript
+    n_plus_one: ".populate('posts')"
+    raw_query: "Model.collection.findOne({})"
+    transactions: "session.withTransaction(async () => {...})"
+    relation: "{ type: Schema.Types.ObjectId, ref: 'User' }"
+    strength: MongoDB ODM, schema validation
+
+  # Sequelize
+  - id: orm009
+    orm: Sequelize
+    language: typescript
+    n_plus_one: "include: [{ model: Post }]"
+    raw_query: "sequelize.query('SELECT * FROM users')"
+    transactions: "sequelize.transaction(async (t) => {...})"
+    relation: "User.hasMany(Post)"
+    strength: Multi-dialect, mature ecosystem
+
+  # Kysely
+  - id: orm010
+    orm: Kysely
+    language: typescript
+    n_plus_one: "Manual JOINs (SQL builder)"
+    raw_query: "sql`SELECT * FROM users`"
+    transactions: "db.transaction().execute(async (trx) => {...})"
+    relation: "N/A (SQL builder)"
+    strength: Type-safe SQL builder, minimal overhead