Coding & Refactoring Agent Skills

Add or modify a custom GUC variable in a PostgreSQL backend patch or extension — covers DefineCustomBoolVariable / IntVariable / RealVariable / StringVariable / EnumVariable, picking the right GucContext (PGC_POSTMASTER / PGC_SIGHUP / PGC_SUSET / PGC_USERSET), MarkGUCPrefixReserved, the check/assign/show hook trio, GUC_LIST_INPUT / GUC_LIST_QUOTE / GUC_UNIT_MS / GUC_UNIT_KB / GUC_REPORT / GUC_EXPLAIN flags, and string-GUC guc_malloc rules. Use whenever a PG patch or extension calls DefineCustom*Variable, picks a GucContext, wires check/assign/show hooks, debugs a placeholder GUC, or marks a GUC reserved via MarkGUCPrefixReserved. Skip for DBA tuning of shared_buffers / max_connections / work_mem in production, dotenv / Viper / Dynaconf / Spring @Value configuration libraries, Kubernetes ConfigMap, Terraform variables, and non-PG application config systems.

PostgreSQL's ResourceOwner infrastructure — `src/backend/utils/resowner/resowner.c` — the tree of resource-tracking objects that release buffer pins, catcache refs, tuple descriptors, snapshots, plancache refs, DSM segments etc. automatically on transaction/subtransaction/portal boundaries. Loads when the user asks about `CurrentResourceOwner`, `ResourceOwnerCreate`/`ResourceOwnerRelease`, why a subtransaction cleanup didn't free a resource, the callback-based extension API (PG 17+), adding a new resource kind, or debugging "resource owner leak" WARNINGs. Skip when the ask is about MemoryContexts (parallel infrastructure but different lifecycle — see `memory-contexts`) or about locks (separate — `locking`).

Run and troubleshoot Windows PowerShell, cmd, and native Windows commands reliably from WSL, with separate safety guidance for Windows over SSH. Use for Windows host inspection, files, processes, services, registry, networking, packages, scheduled tasks, event logs, disks, installers, or any command containing PowerShell variables, pipelines, quotes, multiline code, paths with spaces, JSON, native executables, remote Windows targets, UAC boundaries, or WSL interop errors. Also use whenever a prior Windows command had a parser, quoting, exit-code, encoding, wrong-host, timeout, CLIXML, endpoint-security, or transport failure.

Allocate memory in PostgreSQL backend C — pick the right MemoryContext and use palloc / palloc0 / pstrdup / psprintf correctly. Covers CurrentMemoryContext / TopMemoryContext / per-query / per-tuple / ExecutorState context choice, MemoryContextSwitchTo discipline, the OOM-throws-ereport contract (no NULL checks), pfree vs MemoryContextReset vs MemoryContextDelete, the AllocSet vs Slab vs Generation vs Bump context-type cheat sheet, and leak-scoping in long-running backends. Use whenever a PG patch or extension calls palloc / palloc0 / MemoryContextAlloc, creates or switches a MemoryContext, picks AllocSet vs Slab vs Generation vs Bump, or debugs a context-shaped leak. Skip for plain malloc / free / jemalloc / mimalloc / tcmalloc, JVM / Go / .NET GC tuning, Rust Box / Rc / Arc / lifetimes, shared_buffers / work_mem production tuning, valgrind / heaptrack on non-PG programs, and C++ smart pointers.

Add parallel-aware C code in a PostgreSQL backend patch or extension — covers ParallelContext lifecycle (EnterParallelMode / CreateParallelContext / InitializeParallelDSM / LaunchParallelWorkers / WaitForParallelWorkersToFinish / DestroyParallelContext / ExitParallelMode), shm_toc DSM allocation + key lookup, ExecXXXInitializeDSM / ExecXXXInitializeWorker / ExecXXXReInitializeDSM hooks on plan nodes, and parallel-safety markings (pg_proc.proparallel s/r/u; PARALLEL SAFE / RESTRICTED / UNSAFE). Use whenever a PG patch or extension adds parallel-aware code, picks PARALLEL SAFE/RESTRICTED/UNSAFE for a SQL-callable function, extends execParallel.c, plumbs a worker shmem state via shm_toc, or debugs a parallel worker DSM/TOC issue. Skip for DBA tuning of max_parallel_workers GUC, OpenMP / CUDA / pthread / Tokio / Go-goroutine parallelism, JavaScript Promise.all and async-iter parallel fetches, generic worker-pool questions, and ML data-parallel training.

Hack the PostgreSQL parser or add a new Node type — covers scan.l flex tokenizer, gram.y bison grammar, parse_analyze in analyze.c, kwlist.h keywords, and adding/modifying Node types in parsenodes.h / primnodes.h / plannodes.h that flow through copy/equal/out/read funcs auto-generated by gen_node_support.pl. Spans the AST→Query→Plan three-tree pipeline, mutator/walker conventions (expression_tree_walker, query_tree_mutator), the node-type reference table, List/lappend/foreach idioms, and shift-reduce conflict resolution. Use whenever a PG patch edits src/backend/parser/**, edits src/include/nodes/*.h, adds a new SQL keyword to kwlist.h, extends a parse-tree node, writes a tree mutator/walker, or resolves a gram.y shift-reduce conflict. Skip for non-PG parsers (ANTLR, Babel, nom, tree-sitter, LALRPOP, Yacc/Bison on other projects, LLVM IR / Clang AST), JSON / XML / YAML parsing, and executor-node additions (use executor-and-planner instead).

Execute a PostgreSQL `planning/<slug>/plan.md` phase-by-phase under upstream-grade discipline — Phase 3 of the PG planner suite. Per-phase commits, per-phase regress/iso/TAP runs, plan-linked commit messages, and a running notes log; enforces .claude/rules/pg-implement-discipline.md (R1-R12 — every commit references the plan slug + phase number; every code claim has a file:line cite; phase-end check must pass before the next phase starts). Use when the user says "/pg-implement <slug>", "implement the plan", "let's start implementing the X plan", "execute the planning/<slug>/plan.md", or has a finalized planning/<slug>/plan.md ready to execute. Skip for ad-hoc coding without a plan (no phase structure), non-PG implementation (app code, infra, scripts), the generic /implement flow (multi-project, doesn't enforce PG R1-R12 rules), and exploratory hacking where the plan is still being shaped (use pg-feature-plan instead).

PostgreSQL's MVCC snapshot infrastructure — `src/backend/utils/time/snapmgr.c` — `GetTransactionSnapshot` / `GetLatestSnapshot` / `PushActiveSnapshot` / `RegisterSnapshot` and the tuple-visibility machinery in `heapam_visibility.c`. Covers the ActiveSnapshot stack, RegisteredSnapshots heap, snapshot export for parallel workers, historic snapshots for logical decoding, and the interaction with xmin horizon. Loads when the user asks about `Snapshot` semantics, MVCC visibility (`HeapTupleSatisfiesMVCC`), catalog snapshots vs transaction snapshots, isolation levels, exported snapshots for pg_dump, or `SET LOCAL transaction_isolation`. Skip when the ask is about xact.c commit/abort mechanics or about xid horizons for freezing (see `vacuum-autovacuum`).

Plan and track cross-project multi-repo campaigns — YAML overlays, repo rollups, objective fan-out, and MR status. Use for umbrella-scale coordinated work.

Fix a failing function by reproducing the failure, localizing the smallest wrong expression, making the minimal change, and re-verifying — for small bug-fix tasks with a known expected behaviour.

Inspect and sync the repo-owned agent skill links for the dotagents repo across primary coding agents. Use when the user asks for dotagents status, dotagents sync, dotagents setup, or wants to reconcile ~/.agents with Claude/Codex/Hermes/Droid/Pi skill roots; Amp/OpenClaw/OpenCode-style harnesses are compatibility-only unless explicitly configured.

Rules for delegating work to subagents and judging what comes back — when to spawn vs. do it yourself, how to write a dispatch packet, how to review agent-produced changes without rubber-stamping, when to retry vs. change approach vs. ask the user, and how to hand off long-running work across sessions. Load when about to spawn a subagent or write a dispatch prompt, when fanning out parallel work, when the diff you are reviewing was produced by an agent, or when work will outlive this session. Do NOT load for small single-context tasks — just do those under operational-rigor.

Product-owner planning partner — turns a goal plus the repo's actual state into a verdict, a Now/Next/Later/Not-now roadmap, milestones with acceptance criteria, and agent-ready tasks. Load when the user asks "what should we build next?", any roadmap/milestone/release/MVP/priority/PRD question, wants the current repo assessed for product direction, or wants similar GitHub projects mined for insight. NOT for picking today's coding task inside an already-agreed milestone, and not marketing/pricing strategy.

AWS cloud expertise. Use when the user asks about AWS services (EC2, S3, Lambda, IAM, DynamoDB, RDS, ECS, EKS, CloudWatch, Bedrock, SageMaker), architecture design on AWS, boto3 / AWS CLI usage, cost optimization, or cloud security best practices. Provides decision frameworks, CLI/boto3 workflows, and worked examples.

Expert Python programming skill. Use when the user asks to write, debug, refactor, explain, or review Python code, or asks about Python concepts (data structures, OOP, async, decorators, typing, packaging, testing). Provides coding standards, step-by-step workflows, and worked examples.

Use when the user wants a thorough PR or branch review. Triages by diff size — small PRs get a single-pass review, large PRs fan out to parallel sub-agents (correctness, architecture, security, scope, and an Agentic & Evals lens that activates on AI/agent code) with a validation phase that drops false positives.

Convert existing automation — shell scripts, Python glue, Makefile targets, CI jobs, prompt chains in docs — into checkable .nika.yaml workflows. Use when a script wraps LLM calls or HTTP/file plumbing, a prompt chain lives in a README or notebook, or ad-hoc automation needs audit, cost bounds and replayable traces.

PostgreSQL's async I/O subsystem + the read-stream API — `src/backend/storage/aio/` (introduced PG 17, matured PG 18). Loads when the user asks about the read_stream API, AIO methods (sync / worker / io_uring), how sequential + bitmap scans issue prefetch, migrating a code path from `StartReadBuffer`+`WaitReadBuffer` to `read_stream_*`, adding a new read-stream consumer, tuning `io_max_concurrency` / `io_workers` / `io_method`, or debugging AIO-related buildfarm failures. Also for the read-stream callbacks (per-block-lookup / per-buffer-release), completion callbacks (`aio_callback.c`), and the io_uring linkage. Skip when the ask is about client-side async (libpq) or about the WAL writer / walreceiver (those have their own I/O paths).

PostgreSQL's backup + point-in-time recovery — `pg_basebackup` + WAL archiving (archive_command / archive_library) + `restore_command` + `pg_wal_replay_*` targets + the pg_backup_start/stop API + `pg_receivewal`. Covers `src/backend/backup/` (basebackup server code) + `src/backend/postmaster/pgarch.c` (archiver aux process) + `src/backend/access/transam/xlogrecovery.c` (recovery driver). Loads when the user asks about how base backups work, WAL archiving vs streaming replication, PITR targets (`recovery_target_*`), `pg_backup_start`/`pg_backup_stop` low-level API, `.backup` files, restore_command semantics, or incremental backup (PG 17+ with `WAL_SUMMARIZED`). Skip when the ask is about `pg_dump` (logical dump — different tool) or about physical replication streaming (`physical-replication` — related but sibling).

PostgreSQL's collation-provider abstraction — the 3-way split between `builtin` (PG-owned), `icu` (ICU library), and `libc` (OS-provided). Covers `src/backend/utils/adt/pg_locale.c` (the dispatcher) + `pg_locale_builtin.c` / `pg_locale_icu.c` / `pg_locale_libc.c` (per-provider implementations) plus the encoding conversion layer (`src/backend/utils/mb/`). Loads when the user asks about `CREATE COLLATION`, provider semantics, `LC_COLLATE` / `LC_CTYPE`, ICU integration + version tracking, the `builtin` provider added PG 17, `collversion` upgrade detection, why an ORDER BY differs between PGs on the same OS, `pg_c_utf8` builtin, or multibyte encoding conversion. Skip when the ask is about client encoding (server-client convert is included but psql `\encoding` is client-side), full-text search dictionaries (different subsystem `tsearch`), or `CREATE TEXT SEARCH CONFIGURATION`.

Understand and modify the COPY FROM / COPY TO family in PostgreSQL — `src/backend/commands/copy*.c`. Loads when the user asks about COPY-command internals, bulk-load performance, custom COPY formats, extending COPY options, COPY error-handling / ON_ERROR, COPY progress reporting, tablesync (which is built on COPY), or any patch touching `copy.c` / `copyfrom.c` / `copyfromparse.c` / `copyto.c`. Also use when investigating why COPY behaves differently from INSERT (partition routing, defaults, generated columns, extended statistics, RLS, triggers, DEFAULT expressions), and when adding a new bulk-load code path that reuses the COPY machinery. Skip when the question is about `pg_dump` / `psql \copy` (client-side) or logical-replication apply (different subsystem — but note that tablesync's initial copy IS this machinery, see `knowledge/idioms/tablesync-initial-copy.md`).

PostgreSQL's Custom Scan / Custom Path API — the pluggable executor node interface that lets extensions add new physical operators (custom joins, custom aggregates, custom scan providers like columnar backends). Covers `CustomScanMethods` + `CustomExecMethods` + `CustomPathMethods` in `src/backend/executor/nodeCustom.c` + `src/backend/optimizer/util/plannodes.c` (for CustomPath / CustomScan). Loads when the user asks about custom scan providers, how citus / timescaledb / greenplum-style columnar backends integrate, CustomPath cost registration, `RegisterCustomScanMethods`, or "how does the planner know about my extension's node type". Skip when the ask is about extending the built-in AM (table AM / index AM — different pluggable interface) or about GetForeignPaths (FDW — sibling but has its own skill).

PostgreSQL's extended statistics — `CREATE STATISTICS`, `pg_statistic_ext`, `pg_statistic_ext_data` — the 4 stat kinds (dependencies / ndistinct / mcv / expressions) that help the planner handle correlated columns, multi-column NDVs, and expression cardinality. Covers `src/backend/statistics/extended_stats.c` + `dependencies.c` + `mcv.c` + `mvdistinct.c`. Loads when the user asks about extended stats syntax, when to `CREATE STATISTICS`, why a query has bad estimates on correlated columns, ndistinct for GROUP BY estimation, MCV lists in the extended-stats context, or the planner's `clauselist_selectivity_ext` selectivity path. Skip when the ask is about `pg_statistic` (single-column stats — the sibling; see `analyze-block-and-reservoir-sampling` idiom) or about ANALYZE mechanics (that's `analyze.c` — different code path).

Install and operate a governed multi-agent software engineering runtime through the authenticated Codex CLI. Use when a repository change should pass through specification, architecture, specialist delegation, human approvals, implementation, independent review, security review, testing, persistent memory, and Git checkpoints rather than being edited immediately.