matejformanek pg-claude — the master navigator
You're working inside pg-claude, a meta repo at /Users/matej/Work/postgres/postgres-claude/
that turns Claude into a deep PostgreSQL collaborator. Two upstream PG clones are mounted:
source/→../postgresql/— read-only reference. Allknowledge/cites use these paths so file:line refs stay stable.dev/→../postgresql-dev/— mutable test field. All builds + clusters live here; safe to wipe and re-clone.
This skill is the table of contents for everything pg-claude offers. Use it to pick the right specialized skill, slash command, or knowledge doc — don't construct equivalents by hand when one already exists.
Slash commands — the dev loop
Invoke these instead of constructing bash. They encode verified invocations,
correct dev/... paths, and macOS gotchas.
| User intent | Command |
|---|---|
| First-time setup from nothing (no clone yet) | /init-pg-dev |
| Hook pg-claude into an existing PG dev tree | /link-claude-corpus |
| Build / rebuild PG | /setup-pg (--force to wipe) |
| Start the cluster | /pg-start |
| Stop the cluster | /pg-stop |
Restart (after backend code change + ninja install) |
/pg-restart |
| Open psql | /pg-psql |
| Tail server.log | /pg-tail-log |
| Attach lldb to a backend | /pg-attach |
| Run tests | /pg-test [--suite X --test PAT] |
| Wipe data dir, keep build | /pg-fresh --yes |
| Nuke the dev clone and re-clone | /pg-reclone-dev --yes |
| Document a subsystem | /document-subsystem <path> |
| Brainstorm a PG feature (Phase 1 of planner) | /pg-brainstorm <idea> |
| Heavy plan for a brainstormed feature (Phase 2) | /pg-plan <slug> |
| Pull a scenario playbook + starter plan when change-class is already known | /pg-scenario <slug> |
| Execute a plan phase-by-phase (Phase 3, plan-linked commits) | /pg-implement <slug> |
| Multi-agent comprehensive patch review (CF# / PR# / .patch) | /pg-review <ref> |
Be proactive. If the user says "let's build", "start the server", "run tests",
"debug this backend", "let me query that", etc., invoke the command — don't ask
"want me to run /setup-pg?". The exception is destructive ones (/pg-fresh,
/pg-reclone-dev): if --yes wasn't explicit, run without it so the command's
own prompt fires.
Specialized skills — what to reach for and when
The skills below auto-load by their descriptions. This index is the quick-glance "what exists" view so you can route mentally even when a skill's description didn't trigger.
Writing / editing C code in source/dev
| Topic | Skill | Trigger |
|---|---|---|
| C style, includes, pgindent, C99 subset | coding-style |
any C edit under source/src/**/*.{c,h} |
| ereport/elog, SQLSTATE, PG_TRY/CATCH | error-handling |
any error-reporting or longjmp-safe cleanup |
| palloc, MemoryContexts, OOM behavior | memory-contexts |
any allocation, context creation, leak worry |
| LWLocks, heavyweight locks, atomics, SSI | locking |
any shared-state code |
| Catalog edits, pg_proc.dat, catversion | catalog-conventions |
any change under src/include/catalog/ |
| WAL records, redo functions, custom rmgr | wal-and-xlog |
any XLogInsert, redo, durability change |
| fmgr/PG_FUNCTION_INFO_V1, SPI lifecycle | fmgr-and-spi |
any SQL-callable C fn, any SPI work |
| Extension layout, hooks, custom GUCs | extension-development |
building an extension or hook |
| Custom GUCs (DefineCustomXxxVariable, check/assign hooks) | gucs-config |
any custom GUC add/change |
| Background workers + extension hooks | bgworker-and-extensions |
RegisterBackgroundWorker, shmem, hook layering |
| Parallel-query workers (Gather/GatherMerge, parallel-safe) | parallel-query |
any parallel-aware code |
| IndexAmRoutine / TableAmRoutine | access-method-apis |
any new AM or AM-pluggable code |
| Replication overview (physical + logical) | replication-overview |
walsender/walreceiver/slot/logical-decoding work |
Subsystem-focused reference (per-family deep-dives)
Each fills a gap:* signal from pg-user-question-harvester — reach for these when working in the named family.
| Topic | Skill | Trigger |
|---|---|---|
COPY FROM / COPY TO internals (copy*.c) |
copy-family |
any COPY internals / new option / new format / ON_ERROR |
Cumulative-stats + progress + wait events (utils/activity/) |
pgstat-framework |
pg_stat_* view work, pending-vs-shared flush surprises, wait events |
| Postmaster + backend + aux + bgworker + signals | process-lifecycle |
fork-model questions, aux processes, ProcessInterrupts, startup hooks |
AIO + read_stream API (storage/aio/, PG 17/18) |
aio-readstream |
migrating scans to read_stream, io_method tuning, AIO consumer |
| VACUUM engine + autovacuum daemon | vacuum-autovacuum |
vacuumlazy.c orchestration, autovac thresholds, TidStore, wraparound |
Logical decoding + apply (replication/logical/) |
logical-replication |
publications/subscriptions, output plugins, reorderbuffer, apply worker |
| Row-Level Security policies + security barriers + leakproof | row-level-security |
CREATE POLICY, security_barrier views, leakproof qualification pushdown |
Free Space Map (storage/freespace/) |
free-space-map |
FSM tree, category encoding, INSERT free-space search |
| MultiXactId + tuple-locking modes + wraparound | multixact |
HEAP_XMAX_IS_MULTI, FOR SHARE/UPDATE, multixact SLRU exhaustion |
| Collation providers (builtin / ICU / libc) + encoding | collation-provider |
pg_locale.c, collversion tracking, glibc-upgrade index issues |
Frontend/backend wire protocol (libpq/pqcomm* + tcop/postgres.c) |
wire-protocol |
new protocol message, Simple vs Extended query, pq_beginmessage lifecycle |
| PL/pgSQL parser + compiler + interpreter + trust boundary | plpgsql-internals |
pl_exec.c 268K, plan cache in PL/pgSQL, EXECUTE injection |
| Foreign Data Wrapper + postgres_fdw + pushdown | fdw-development |
writing a new FDW, extending pushdown, password_required pattern |
| jsonb + jsonpath + SQL/JSON | jsonpath-and-jsonb |
jsonpath_exec.c, jsonb GIN opclass, JSON_TABLE, -> vs ->> |
| Per-backend TypeCache + composite/domain/record | type-cache |
lookup_type_cache flags, RECORD typmod registry, SharedRecordTypmodRegistry |
| ResourceOwner tree + release phases + callback API | resource-owners |
pin/ref leaks, PG 17+ resource-kind extension seam |
| Extended statistics — CREATE STATISTICS + planner integration | extended-statistics |
dependencies/ndistinct/mcv/expressions kinds, bad estimates on correlated cols |
| TOAST out-of-line + compressed varlena storage | toast-storage |
storage strategies, 2 KB rule, pglz vs lz4, chunk_id wrap |
| Shared buffer manager + BufferAccessStrategy rings | buffer-manager |
pin/unpin discipline, clock-sweep, add-new-buffer-strategy |
| SLRU (bank-locked LRU) infrastructure — CLOG/MultiXact/etc. | slru-infrastructure |
new SLRU consumer, PG 17+ per-SLRU GUCs, bank-lock design |
| Physical streaming replication + syncrep + hot standby | physical-replication |
walsender/walreceiver state machine, synchronous_standby_names, hot_standby_feedback |
| MVCC snapshots + visibility + isolation levels | snapshot-management |
Register/Push snapshots, historic (logical decoding), pg_export_snapshot |
| Base backup + WAL archiving + PITR | backup-and-recovery |
pg_basebackup internals, archive_command/library, recovery_target_*, PG 17+ incremental |
| Custom Scan / Custom Path — pluggable executor node interface | custom-scan-api |
CustomPath registration, executor callbacks, parallel-safe custom nodes |
| Node type system + gen_node_support.pl + walker/mutator | node-infrastructure |
new Node type, T_ enum, generated copy/equal/out/read |
| pg_upgrade — in-place major-version upgrader | pg-upgrade-internals |
--link/--copy/--clone tradeoffs, relfilenumber preservation, upgrade blockers |
Running / testing / debugging
| Topic | Skill | Notes |
|---|---|---|
| Build, configure, run | build-and-run |
Underlies /setup-pg, /pg-start etc. |
| Test selection (regress vs isolation vs TAP) | testing |
What flavor to add, how to run only one |
| gdb/lldb attach, single-user, log instrumentation | debugging |
Per-connection fork-model implications |
Contributing upstream
| Topic | Skill | Trigger |
|---|---|---|
| Format-patch + CF registration + email etiquette | patch-submission |
"let's send this upstream" |
| Pre-submission self-review checklist (seven-phase scaffold) | review-checklist |
"review my patch" or pre-mailing pass |
| Multi-agent deep review of someone else's CF patch | pg-patch-review |
"/pg-review <CF#>", "deep-review this patch" |
| PG-style commit messages (no Co-Authored-By!) | commit-message-style |
drafting commits in dev/ intended for upstream |
| Parser, Node taxonomy, gen_node_support.pl | parser-and-nodes |
grammar/Node changes, new SQL statement |
| Executor + planner integration | executor-and-planner |
new node type, new path, planner change |
Planning + implementing a PG feature (the three-phase planner)
| Topic | Skill | Trigger |
|---|---|---|
| Phase 0: query the corpus graph (which scenarios/idioms/files apply?) | corpus-chain |
"what does this touch?", "/pg-chain ", auto-fired by brainstorm §2.5 + plan §0.4 |
| Phase 1: explore an idea, sketch 2-3 approaches | pg-feature-brainstorm |
"let's brainstorm X", "/pg-brainstorm" |
| Phase 2: heavy plan with file:line cites | pg-feature-plan |
"plan this", "/pg-plan " |
| Phase 3: execute plan phase-by-phase, plan-linked commits | pg-implement |
"/pg-implement " |
| Strict rules for plan-linked commits + scope discipline | .claude/rules/pg-implement-discipline.md (not a skill — binding rules) |
auto-loaded by pg-implement |
Project-internal
| Topic | Skill |
|---|---|
| Master command index (this skill) | pg-claude |
| Keep STATE.md / coverage.md / sessions/ in sync | memory-keeping |
| Commit-message style for THIS repo (with Co-Authored-By) | meta-commit-style |
Knowledge corpus — where to look things up
The knowledge/ tree is the durable corpus. Reach for it whenever you need to
recall a fact you don't already know.
knowledge/
├── architecture/ # PG-wide concepts (overview, process-model, query-lifecycle,
│ # executor, planner, wal, mvcc, replication, access-methods)
├── conventions/ # cross-cutting style: coding-style.md, testing.md, extension-layout.md
├── community/ # patch-workflow.md, review-patterns.md, wiki-index.md,
│ # developer-faq-distilled.md, so-you-want-to-be-a-developer.md
├── idioms/ # PG-wide patterns: error-handling, memory-contexts,
│ # locking-overview, fmgr, spi, catalog-conventions,
│ # node-types-and-lists, parser-pipeline, guc-variables,
│ # bgworker-and-parallel
├── subsystems/ # per-subsystem deep-dives (storage-buffer.md is the calibration
│ # anchor; more land via /document-subsystem)
├── data-structures/# focused notes on individual structs / invariant families
├── issues/ # corpus-surfaced issue register (Phase A) — one .md per subsystem
│ # with [ISSUE-*] tagged concerns: leaks, doc-drift, stale TODOs,
│ # undocumented invariants, questions. See issues/README.md.
├── scenarios/ # task-shaped playbooks — one .md per recurring change-class
│ # (add a data type, a SQL keyword, a GUC, a WAL record, ...).
│ # Each scenario has an authoritative file checklist that
│ # pg-feature-plan PINS as the §3 table (hard integration).
│ # See scenarios/README.md + scenarios/_index.md.
└── files/ # one .md per source file — 917+ docs mirroring source/src/
# layout. Use when you need precise file:line context for a
# specific .c or .h.
planning/ # forward-looking design docs for features in-flight (Phase B/C/D)
# one subdir per slug, with brainstorm.md / plan.md / notes.md
# See planning/README.md for the layout.
Routing rule:
- "What does PG do at a high level?" →
architecture/. - "How is this pattern done in PG?" →
idioms/. - "I want to add a new , what files do I touch?" →
scenarios/_index.md(the decision tree). Each scenario lists the full file-by-file sweep. - "Is there a doc for
bufmgr.c?" →files/src/backend/storage/buffer/bufmgr.c.md. - "What's odd / suspect / undocumented in subsystem X?" →
issues/X.md. - "What's the current state of pg-claude itself?" →
progress/STATE.md. - "Where can I help close the corpus gap?" →
progress/coverage-gaps.md(Phase A work queue). - "Give me the whole chain for feature X" / "what does this file/idiom touch?" →
/pg-chain <args>(invokescorpus-chain— traverses the graph across scenarios / idioms / data-structures / subsystems / files / past planning runs).
Corpus graph — the interconnection layer
Six auto-populated edge layers link the corpus into a queryable graph. Read what's there, then re-query via corpus-chain:
| Edge | Where it lives | Refreshed by |
|---|---|---|
| Idiom → file | ## Call sites in knowledge/idioms/*.md |
scripts/populate-idiom-callsites.py |
| Idiom → file (v2, glossary-based) | same block | scripts/populate-idiom-callsites-v2.py (4 identifier-only idioms) |
| Data-structure → file | ## Call sites in knowledge/data-structures/*.md |
scripts/populate-idiom-callsites.py --layer data-structures |
| Subsystem → file | ## Files owned in knowledge/subsystems/*.md |
scripts/populate-subsystem-files.py |
| Scenario ↔ idiom | ## Idioms invoked / ## Scenarios that use me + progress/scenario-idiom-matrix.md |
scripts/build-scenario-idiom-matrix.py |
| File → subsystem/idiom | <!-- backlinks:auto --> in knowledge/files/**/*.md |
pg-corpus-maintainer cloud routine |
Refresh runs nightly via pg-corpus-graph-refresh (04:17). Query via scripts/corpus-chain.py --scenario/--idiom/--file/--keywords. pg-feature-brainstorm and pg-feature-plan invoke the chain automatically at their §2.5 / §0.4 steps.
Progress files — the ledger
progress/STATE.md— current phase, what's done, what's next. Re-read at session start.progress/coverage.md— subsystems documented + per-file coverage summary (top-line numbers).progress/coverage-gaps.md— per-directory gap map; the Phase A work queue. Updated when coverage shifts ≥50 docs or a dir crosses a 10% boundary.progress/census.md— one-time enumeration of the source tree.progress/files-examined.md— append-only ledger: every source file read in non-trivial depth, with verification commit + produced-doc link.
If you read a source file in depth and there's no row for it, append to
files-examined.md — the user explicitly asked for file-by-file accountability.
Working rules (from CLAUDE.md)
- Cite or tag. Every concrete claim about PG behavior gets a
file:linecite intosource/...or is tagged[unverified]. Confident-but-wrong is the failure mode to avoid (Multigres lesson). - Confidence tags:
[verified-by-code][from-README][from-comment][from-docs][from-wiki][inferred][unverified]. Untagged = failure. - STATE.md authoritative. Update at end of any durable-output session.
- Scope discipline. Source patches live in
dev/on a branch. Never editsource/(read-only reference). Never edit.claude/orknowledge/from insidedev/. - Track what you read. Append to
progress/files-examined.md.
Quick-orientation flowchart
User asks for... You reach for...
───────────────── ────────────────
"set up PG" → /init-pg-dev (no clone) or /setup-pg (have clone)
or /link-claude-corpus (have own dev tree elsewhere)
"build" / "rebuild" → /setup-pg
"start" / "psql" → /pg-start then /pg-psql
"test" → /pg-test
"debug" → /pg-attach + debugging skill
"debug a deadlock" → /pg-attach + /pg-tail-log + locking skill
+ knowledge/subsystems/storage-lmgr.md
+ knowledge/idioms/locking-overview.md
(per-connection fork model — attach AFTER the psql
connect; the backend pid is fresh per session)
"reset" → /pg-fresh (data only) or /pg-reclone-dev (whole tree)
"how does X work" → knowledge/architecture/X.md or knowledge/subsystems/X.md
"what file does Y" → knowledge/files/src/backend/<...>.md
"edit C code" → coding-style + the relevant idiom skill
(error-handling / memory-contexts / locking / ...)
"add a feature" → relevant subsystem skill (catalog-conventions /
wal-and-xlog / access-method-apis /
extension-development / ...)
"add a built-in SQL fn" → catalog-conventions skill (pg_proc.dat, catversion)
+ fmgr-and-spi skill (PG_FUNCTION_INFO_V1)
+ knowledge/idioms/fmgr.md
+ knowledge/idioms/catalog-conventions.md
+ edit dev/src/backend/utils/adt/, then
/setup-pg → /pg-restart → /pg-psql → /pg-test
"send upstream" → patch-submission + review-checklist + commit-message-style
"review a CF patch" → /pg-review <CF#|PR#|file> (multi-agent, 4 critics + synthesizer)
"document subsystem" → /document-subsystem <path>
"brainstorm a feature"→ /pg-brainstorm <idea> (Phase 1; ~150-300 line sketch)
"plan that feature" → /pg-plan <slug> (Phase 2; heavy implementable plan)
"implement the plan" → /pg-implement <slug> (Phase 3; per-phase commits, plan-linked)
"commit in THIS repo" → meta-commit-style skill (with Co-Authored-By)
"commit in dev/" → commit-message-style skill (NO Co-Authored-By; upstream style)
"what was done" → progress/STATE.md + progress/coverage.md
Suggested reading orders for "explain how X works"
For broad concept questions, propose an ordered reading list rather than dumping a folder:
- MVCC:
architecture/overview.md→architecture/mvcc.md→architecture/wal.md→subsystems/access-heap.md→subsystems/access-transam.md - WAL / crash:
architecture/overview.md→architecture/wal.md→subsystems/access-transam.md(usewal-and-xlogskill for code edits) - Planner:
architecture/overview.md→architecture/query-lifecycle.md→architecture/planner.md→subsystems/optimizer.md - Executor:
architecture/overview.md→architecture/query-lifecycle.md→architecture/executor.md→subsystems/executor.md - Buffer mgr:
architecture/overview.md→subsystems/storage-buffer.md - Replication:
architecture/overview.md→architecture/replication.md(usereplication-overviewskill for code-level)
All cites inside those docs use source/... so file:line refs stay stable across upstream pulls.
After-action follow-up
When you finish a command or an edit, give the user one short "what now" line:
- After
/setup-pg: "Built. Next:/pg-start." - After
/pg-start: "Cluster up on /tmp./pg-psqlto connect." - After a code edit in
dev/src/: "Edited./pg-restartto pick up the new binary." - After a knowledge doc landed: "Wrote
knowledge/files/.../X.md. Registry row appended."
Don't recap what already showed in the tool output. Just point at the next move.