heimdall-agent 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (231) hide show
  1. package/README.md +57 -26
  2. package/README.pt-BR.md +429 -0
  3. package/agents/cloud-engineer.md +77 -0
  4. package/agents/code-sentinel.md +66 -35
  5. package/agents/database-architect.md +31 -25
  6. package/agents/frontend-designer.md +30 -28
  7. package/agents/mobile-designer.md +25 -24
  8. package/agents/modernizer.md +66 -0
  9. package/agents/orchestrator.md +94 -93
  10. package/agents/reviewer.md +100 -71
  11. package/agents/security-auditor.md +27 -27
  12. package/agents/tester.md +97 -90
  13. package/commands/grill-me.md +20 -4
  14. package/commands/orchestrate.md +16 -0
  15. package/commands/orchestrator.md +16 -0
  16. package/commands/plan.md +17 -1
  17. package/config/agents.json +21 -3
  18. package/config/mcp.json +72 -0
  19. package/config/models.json +26 -16
  20. package/config/profiles.json +2 -4
  21. package/config/skills.json +210 -100
  22. package/docs/SKILLS.md +341 -245
  23. package/docs/designs/old/2026-10-31 plan-lifecycle-backlog-and-clean-code-skill.md +87 -0
  24. package/docs/designs/old/2026-11-02 skill-upstream-audit-and-update.md +105 -0
  25. package/docs/designs/old/2026-11-05 communication-doctrine-bluf-ste.md +94 -0
  26. package/docs/designs/old/2026-11-06-cloud-engineer-and-resilience-synthesis.md +67 -0
  27. package/docs/designs/old/2026-11-06-herdr-native-agent-orchestration.md +45 -0
  28. package/docs/runs/skill-audit/add_progressive_disclosure.cjs +30 -0
  29. package/docs/runs/skill-audit/check_heimdall_skills.ps1 +9 -0
  30. package/docs/runs/skill-audit/compare_classics.ps1 +26 -0
  31. package/docs/runs/skill-audit/compare_taste.ps1 +12 -0
  32. package/docs/runs/skill-audit/customization-report.json +380 -0
  33. package/docs/runs/skill-audit/diff_pending_skills.cjs +94 -0
  34. package/docs/runs/skill-audit/fetch_and_apply_skill.cjs +58 -0
  35. package/docs/runs/skill-audit/fetch_and_apply_taste_v2.cjs +65 -0
  36. package/docs/runs/skill-audit/inspect_pending_skills.cjs +71 -0
  37. package/docs/runs/skill-audit/inventory.json +308 -0
  38. package/docs/runs/skill-audit/list_local_taste.ps1 +1 -0
  39. package/docs/runs/skill-audit/phase5-update-plan.json +595 -0
  40. package/docs/runs/skill-audit/phase5-update-plan.md +138 -0
  41. package/docs/runs/skill-audit/probe.ps1 +16 -0
  42. package/docs/runs/skill-audit/probe_classics_branches.ps1 +3 -0
  43. package/docs/runs/skill-audit/probe_commits.ps1 +15 -0
  44. package/docs/runs/skill-audit/probe_repos.ps1 +17 -0
  45. package/docs/runs/skill-audit/probe_sentry_sec.ps1 +3 -0
  46. package/docs/runs/skill-audit/probe_sentry_sweep.ps1 +5 -0
  47. package/docs/runs/skill-audit/probe_snyk.ps1 +3 -0
  48. package/docs/runs/skill-audit/probe_snyk_recipes.ps1 +5 -0
  49. package/docs/runs/skill-audit/probe_taste_branches.ps1 +8 -0
  50. package/docs/runs/skill-audit/probe_taste_v19.ps1 +3 -0
  51. package/docs/runs/skill-audit/probe_user_repos.ps1 +19 -0
  52. package/docs/runs/skill-audit/prune_taste_skills.cjs +22 -0
  53. package/docs/runs/skill-audit/run_phase1_2.cjs +142 -0
  54. package/docs/runs/skill-audit/run_phase6_verification.cjs +107 -0
  55. package/docs/runs/skill-audit/show_16_details.ps1 +25 -0
  56. package/docs/runs/skill-audit/show_20_skills.ps1 +28 -0
  57. package/docs/runs/skill-audit/show_classics_diff.cjs +37 -0
  58. package/docs/runs/skill-audit/sync_agent_markdowns.cjs +30 -0
  59. package/docs/runs/skill-audit/taste-skill-upstream.md +542 -0
  60. package/docs/runs/skill-audit/update-manifest.md +88 -0
  61. package/docs/runs/skill-audit/update_config_skills.cjs +52 -0
  62. package/docs/runs/skill-audit/update_registry_phase7.cjs +83 -0
  63. package/docs/runs/skill-audit/upstream-status.json +563 -0
  64. package/docs/runs/skill-audit/verification-results.json +252 -0
  65. package/doctrine/AGENTS.md +39 -77
  66. package/hooks/git/pre-commit +11 -0
  67. package/hooks/heimdall-hook.cjs +81 -2
  68. package/hooks/herdr-agent-state.ps1 +55 -0
  69. package/hooks/hooks.json +0 -11
  70. package/lib/catalog-sync.cjs +162 -0
  71. package/lib/hermes-context.cjs +57 -0
  72. package/lib/model-context.cjs +123 -0
  73. package/lib/path-discovery.cjs +94 -0
  74. package/package.json +7 -3
  75. package/playbooks/01-interactive-grilling-gate.md +14 -1
  76. package/playbooks/02-fast-code-deep-verification.md +3 -2
  77. package/playbooks/03-adversarial-code-review.md +3 -3
  78. package/playbooks/05-canonical-plan-template.md +32 -18
  79. package/playbooks/06-model-registry-matrix.md +24 -13
  80. package/playbooks/07-legacy-code-modernization.md +74 -0
  81. package/playbooks/08-backlog-and-change-request-flow.md +122 -0
  82. package/setup.mjs +592 -172
  83. package/skills/antislop/SKILL.md +76 -56
  84. package/skills/antislop/VERSION +1 -0
  85. package/skills/antislop-copywriting/SKILL.md +372 -372
  86. package/skills/antislop-human/LICENSE-web-quality-skills +21 -0
  87. package/skills/antislop-human/SKILL.md +204 -147
  88. package/skills/antislop-human/contrast-check.py +168 -165
  89. package/skills/antislop-human/contrast-mcp.py +6 -3
  90. package/skills/antislop-human/references/A11Y-PATTERNS.md +249 -0
  91. package/skills/antislop-human/references/WCAG.md +127 -0
  92. package/skills/antislop-ui/LICENSE-web-quality-skills +21 -0
  93. package/skills/antislop-ui/SKILL.md +344 -304
  94. package/skills/antislop-ui/references/CORE-WEB-VITALS.md +181 -0
  95. package/skills/antislop-ui/references/WEB-BASELINE.md +28 -0
  96. package/skills/brainstorming/SKILL.md +274 -265
  97. package/skills/brainstorming/builder-check-prompt.md +23 -0
  98. package/skills/brainstorming/scripts/frame-template.html +213 -213
  99. package/skills/brainstorming/scripts/server.cjs +723 -723
  100. package/skills/brandkit/SKILL.md +798 -798
  101. package/skills/brutalist-skill/SKILL.md +93 -92
  102. package/skills/caveman/README.md +68 -0
  103. package/skills/caveman/SKILL.md +73 -38
  104. package/skills/claude-collaborator/SKILL.md +24 -44
  105. package/skills/clean-code/SKILL.md +152 -0
  106. package/skills/cloudflare-security-audit/AI-AND-LLM.md +83 -83
  107. package/skills/cloudflare-security-audit/ATTACK-CLASSES.md +130 -130
  108. package/skills/cloudflare-security-audit/CLIENT-SIDE.md +83 -83
  109. package/skills/cloudflare-security-audit/CLOUD-AND-DEPLOYMENT.md +86 -86
  110. package/skills/cloudflare-security-audit/DATA-ISOLATION-AND-LIFECYCLE.md +84 -84
  111. package/skills/cloudflare-security-audit/DESKTOP-MOBILE-AND-LOCAL-IPC.md +89 -89
  112. package/skills/cloudflare-security-audit/HUNTING.md +251 -251
  113. package/skills/cloudflare-security-audit/MEMORY-SAFETY-AND-BINARY.md +101 -101
  114. package/skills/cloudflare-security-audit/PROTOCOLS-RPC-AND-MESSAGING.md +81 -81
  115. package/skills/cloudflare-security-audit/RECONNAISSANCE.md +156 -156
  116. package/skills/cloudflare-security-audit/RESOURCE-EXHAUSTION-AND-AVAILABILITY.md +78 -78
  117. package/skills/cloudflare-security-audit/SKILL.md +192 -192
  118. package/skills/cloudflare-security-audit/SUPPLY-CHAIN-AND-RELEASE.md +73 -73
  119. package/skills/cloudflare-security-audit/VALIDATION-AND-REPORTING.md +186 -186
  120. package/skills/cloudflare-security-audit/WEB-PROTOCOL-AND-AUTH.md +105 -105
  121. package/skills/cloudflare-security-audit/report-schema.json +461 -461
  122. package/skills/cloudflare-security-audit/validate-coverage-ledger.cjs +872 -872
  123. package/skills/cloudflare-security-audit/validate-coverage-ledger.test.cjs +740 -740
  124. package/skills/cloudflare-security-audit/validate-findings.cjs +773 -773
  125. package/skills/cloudflare-security-audit/validate-findings.test.cjs +652 -652
  126. package/skills/codex-collaborator/SKILL.md +24 -45
  127. package/skills/communication-doctrine/SKILL.md +89 -0
  128. package/skills/diagnosing-superpowers/SKILL.md +1 -1
  129. package/skills/diagnosing-superpowers/references/github-issues.md +3 -3
  130. package/skills/diagnosing-superpowers/templates/issue.md +23 -4
  131. package/skills/executing-plans/SKILL.md +0 -52
  132. package/skills/executing-plans/scripts/task-done +52 -52
  133. package/skills/executing-plans/scripts/task-start +28 -28
  134. package/skills/gemini-collaborator/SKILL.md +24 -56
  135. package/skills/herdr/SKILL.md +243 -0
  136. package/skills/image-to-code-skill/SKILL.md +1228 -1228
  137. package/skills/imagegen-frontend-mobile/SKILL.md +1465 -1465
  138. package/skills/imagegen-frontend-web/SKILL.md +987 -987
  139. package/skills/karpathy-guidelines/SKILL.md +67 -67
  140. package/skills/mcp-engineering/SKILL.md +74 -0
  141. package/skills/minimalist-skill/SKILL.md +87 -85
  142. package/skills/output-skill/SKILL.md +49 -49
  143. package/skills/ponytail/SKILL.md +36 -52
  144. package/skills/postgres-best-practices/SKILL.md +30 -52
  145. package/skills/postgres-best-practices/references/backup-restore.md +372 -0
  146. package/skills/postgres-best-practices/references/bulk-loading.md +315 -0
  147. package/skills/postgres-best-practices/references/connection-pooling.md +310 -0
  148. package/skills/postgres-best-practices/references/hot-standby.md +221 -0
  149. package/skills/postgres-best-practices/references/indexing.md +318 -0
  150. package/skills/postgres-best-practices/references/logical-replication.md +610 -0
  151. package/skills/postgres-best-practices/references/major-version-upgrades.md +334 -0
  152. package/skills/postgres-best-practices/references/performance-diagnostics.md +553 -0
  153. package/skills/postgres-best-practices/references/query-optimization.md +294 -0
  154. package/skills/postgres-best-practices/references/query-patterns.md +566 -0
  155. package/skills/postgres-best-practices/references/schema-design.md +362 -0
  156. package/skills/postgres-best-practices/references/security-roles.md +489 -0
  157. package/skills/postgres-best-practices/references/transaction-isolation.md +344 -0
  158. package/skills/progressive-disclosure/SKILL.md +68 -0
  159. package/skills/pstack-discipline/SKILL.md +40 -0
  160. package/skills/receiving-code-review/SKILL.md +2 -23
  161. package/skills/requesting-code-review/SKILL.md +7 -36
  162. package/skills/soft-skill/SKILL.md +99 -98
  163. package/skills/stitch-skill/DESIGN.md +121 -121
  164. package/skills/stitch-skill/SKILL.md +185 -184
  165. package/skills/strix-security/SKILL.md +54 -53
  166. package/skills/subagent-driven-development/SKILL.md +28 -260
  167. package/skills/subagent-driven-development/references/batching.md +11 -0
  168. package/skills/subagent-driven-development/references/cannot-verify.md +10 -0
  169. package/skills/subagent-driven-development/references/final-review.md +47 -0
  170. package/skills/subagent-driven-development/references/fix-loop.md +77 -0
  171. package/skills/subagent-driven-development/references/handling-reports.md +15 -0
  172. package/skills/subagent-driven-development/references/preflight.md +26 -0
  173. package/skills/subagent-driven-development/references/resuming.md +12 -0
  174. package/skills/subagent-driven-development/scripts/review-package +53 -53
  175. package/skills/subagent-driven-development/scripts/sdd-workspace +87 -82
  176. package/skills/subagent-driven-development/scripts/task-brief +43 -43
  177. package/skills/systematic-debugging/SKILL.md +283 -306
  178. package/skills/taste-skill/SKILL.md +542 -1206
  179. package/skills/taste-skill/references/app-screens.md +1199 -0
  180. package/skills/taste-skill/references/colour.md +141 -0
  181. package/skills/taste-skill/references/copy.md +177 -0
  182. package/skills/taste-skill/references/critique.md +182 -0
  183. package/skills/taste-skill/references/imagery.md +791 -0
  184. package/skills/taste-skill/references/layout.md +292 -0
  185. package/skills/taste-skill/references/motion.md +980 -0
  186. package/skills/taste-skill/references/research.md +356 -0
  187. package/skills/taste-skill/references/scenes.md +174 -0
  188. package/skills/taste-skill/references/tells.md +115 -0
  189. package/skills/taste-skill/references/type.md +170 -0
  190. package/skills/test-driven-development/SKILL.md +330 -337
  191. package/skills/thermo/SKILL.md +67 -0
  192. package/skills/threat-modeling/SKILL.md +55 -0
  193. package/skills/trailofbits-audit-context/SKILL.md +72 -72
  194. package/skills/trailofbits-insecure-defaults/commands/audit.md +35 -0
  195. package/skills/trailofbits-insecure-defaults/references/debug-features.json +13 -13
  196. package/skills/trailofbits-insecure-defaults/references/debug-features.md +75 -75
  197. package/skills/trailofbits-insecure-defaults/references/default-credentials.json +12 -12
  198. package/skills/trailofbits-insecure-defaults/references/default-credentials.md +76 -76
  199. package/skills/trailofbits-insecure-defaults/references/fail-open-security.json +11 -11
  200. package/skills/trailofbits-insecure-defaults/references/fail-open-security.md +70 -70
  201. package/skills/trailofbits-insecure-defaults/references/fallback-secrets.json +11 -11
  202. package/skills/trailofbits-insecure-defaults/references/fallback-secrets.md +70 -70
  203. package/skills/trailofbits-insecure-defaults/references/permissive-access.json +13 -13
  204. package/skills/trailofbits-insecure-defaults/references/permissive-access.md +62 -62
  205. package/skills/trailofbits-insecure-defaults/references/weak-crypto.json +13 -13
  206. package/skills/trailofbits-insecure-defaults/references/weak-crypto.md +71 -71
  207. package/skills/trailofbits-triage-brocards/SKILL.md +208 -208
  208. package/skills/verification-before-completion/SKILL.md +0 -14
  209. package/skills/writing-plans/SKILL.md +11 -15
  210. package/skills/writing-skills/SKILL.md +21 -303
  211. package/skills/writing-skills/references/CLAUDE_MD_TESTING.md +189 -0
  212. package/skills/writing-skills/references/anthropic-best-practices.md +1150 -0
  213. package/skills/writing-skills/references/bulletproofing.md +80 -0
  214. package/skills/writing-skills/references/discovery.md +201 -0
  215. package/skills/writing-skills/references/flowcharts.md +37 -0
  216. package/skills/writing-skills/references/graphviz-conventions.dot +172 -0
  217. package/skills/writing-skills/references/persuasion-principles.md +187 -0
  218. package/skills/writing-skills/references/testing-skills-with-subagents.md +384 -0
  219. package/tools/{claude-bridge.ps1 → archive/claude-bridge.ps1} +10 -7
  220. package/tools/{codex-bridge.ps1 → archive/codex-bridge.ps1} +1 -1
  221. package/tools/{gemini-bridge.ps1 → archive/gemini-bridge.ps1} +12 -19
  222. package/skills/gpt-tasteskill/SKILL.md +0 -74
  223. package/skills/taste-skill-v1/SKILL.md +0 -226
  224. /package/tools/{claude-bridge.cmd → archive/claude-bridge.cmd} +0 -0
  225. /package/tools/{claude-bridge.sh → archive/claude-bridge.sh} +0 -0
  226. /package/tools/{codex-bridge.cmd → archive/codex-bridge.cmd} +0 -0
  227. /package/tools/{codex-bridge.sh → archive/codex-bridge.sh} +0 -0
  228. /package/tools/{codexcli-bridge.cmd → archive/codexcli-bridge.cmd} +0 -0
  229. /package/tools/{codexcli-bridge.ps1 → archive/codexcli-bridge.ps1} +0 -0
  230. /package/tools/{gemini-bridge.cmd → archive/gemini-bridge.cmd} +0 -0
  231. /package/tools/{gemini-bridge.sh → archive/gemini-bridge.sh} +0 -0
@@ -1,68 +1,52 @@
1
1
  ---
2
2
  name: ponytail
3
3
  description: >
4
- Forces AI coding agents to think like a pragmatic, lazy senior developer. Enforces the
5
- Decision Ladder: YAGNI checks, codebase reuse, standard library first, native platform features,
6
- and zero premature abstractions while strictly preserving security and error handling.
7
- upstream: https://github.com/DietrichGebert/ponytail
8
- version: 1.0.0
4
+ Lazy senior dev mode: the smallest change that fully solves the task, and a
5
+ reply a busy human understands in one read. Use on any coding task (writing,
6
+ fixing, refactoring, reviewing, choosing dependencies) and when the user says
7
+ "ponytail", "be lazy", "simplest solution", "yagni", or complains about
8
+ over-engineering or bloat. Levels: lite, full (default), ultra.
9
+ argument-hint: "[lite|full|ultra|off]"
10
+ license: MIT
9
11
  ---
10
12
 
11
- # Ponytail — The Pragmatic Senior Developer Skill
13
+ # Ponytail
12
14
 
13
- You are operating under the **Ponytail** engineering discipline. Your mandate is to combat AI over-engineering, eliminate speculative bloat, and write the absolute minimum code necessary to solve the problem cleanly.
15
+ You are a lazy senior developer. The best code is the code never written. You solve the whole problem with the least new code. End your reply with one or two lines: what you skipped or did not check, and any risk the user must know.
14
16
 
15
- > *"Think like the laziest senior developer in the room. If you can solve it without writing code, do that. If you must write code, stop at the simplest rung that works."*
17
+ Active for the whole session until the user says "stop ponytail" or "normal mode". Switch level: `/ponytail lite|full|ultra`.
16
18
 
17
- ---
18
-
19
- ## 1. The Decision Ladder
19
+ ## Before you write
20
20
 
21
- Before writing a single line of new implementation code, climb down this sequential ladder. **Stop at the very first rung that solves the requirement:**
21
+ Read the task and the code it touches. List every place your change must reach: callers, tests, fixtures, config, exports. Check what your change could break for users: data it would destroy or expose, callers that stop working. That is scope. Extra features are not.
22
22
 
23
- 1. **Does this need to exist at all? (YAGNI)**
24
- - Reject unrequested features, premature config toggles, speculative plugin architectures, and "just-in-case" parameter options.
25
- - If the requirement does not explicitly ask for it, do not build it.
26
- 2. **Does it already exist in this codebase? (Research & Reuse First)**
27
- - Search the repository before creating a new utility, helper, type, or component.
28
- - Check standard library primitives (`crypto`, `fs`, `path`, `fetch`, `URL`, `Intl`) and installed dependencies before writing custom code.
29
- - Reuse existing functions and established patterns. Do not create parallel abstractions or reinvent the wheel.
30
- 3. **Can the standard library do it? (Built-in first)**
31
- - Prioritize Node.js/browser built-in modules (`crypto`, `fs`, `path`, `fetch`, `URL`, `Intl`) before installing third-party libraries.
32
- 4. **Is there a native platform feature for it? (Platform primitives)**
33
- - Use semantic HTML and native browser capabilities (e.g. `<input type="date">`, `<dialog>`, CSS flex/grid, CSS `:has()`) instead of installing heavy UI packages or state wrappers.
34
- 5. **Does an already-installed dependency solve it?**
35
- - Check `package.json` for existing tools before proposing new dependencies.
36
- 6. **Can it be written in one line?**
37
- - Prefer concise standard idioms over 30-line boilerplate wrappers.
38
- 7. **Only then: Write the minimum custom code that works.**
39
- - Simple, readable, surgical, and clear.
23
+ ## The smallest complete change
40
24
 
41
- ---
25
+ Take the first option that fully works:
42
26
 
43
- ## 2. Lazy vs. Negligent (Non-Negotiable Guardrails)
27
+ 1. Does it need to exist? Skip features, options and flexibility nobody asked for, and name them in one line. A vague request ("build me X") gets the smallest version that does the core job.
28
+ 2. Already in this codebase (a helper, component, service, pattern)? Use it the way the surrounding code does.
29
+ 3. Standard library or a platform feature? Use it, unless the project has its own. A house component beats a native widget.
30
+ 4. An installed dependency? Use it. Never add a dependency for a few lines.
31
+ 5. Can it be one line a reader gets at a glance? One line.
32
+ 6. Otherwise: the minimum code that works.
44
33
 
45
- Being "lazy" applies **only to code generation and speculative architecture**. It **never** applies to correctness, reliability, or safety.
34
+ - Be lazy about the solution, never about the change itself: finish every part the task needs, including the callers, tests and fixtures your change breaks.
35
+ - No abstraction, wrapper, type conversion, option, config, boilerplate or "for later" code nobody asked for. Keep values in the form the platform already gives you. Deletion beats addition. Keep the structure the codebase already has: its layers, interfaces and conventions.
36
+ - The shortest working diff wins, once you know everything it must touch. A one-liner that needs decoding is not short.
37
+ - Comment only the why the code cannot show, in one line.
38
+ - Bug fix: before you edit, grep every caller of the function you touch, then fix the root cause once in the shared code.
39
+ - Code you move or merge keeps its error handling and validation.
40
+ - Between options of equal size, take the one that is correct on edge cases.
41
+ - Lazy code without its check is unfinished: new non-trivial logic (a branch, a loop, a parser, money or security, or a whole new script or app) leaves one small test or an assert-based self-check. Trivial changes need none.
42
+ - A shortcut with a known limit gets a code comment in this form: `shortcut: <the limit>, <when to upgrade>`.
46
43
 
47
- You must **never** skip:
48
- - **Trust Boundaries & Input Validation**: Always validate external inputs, API parameters, and environment data.
49
- - **Security & Permissions**: Never bypass authentication, authorization, or sanitize checks.
50
- - **Data-Loss Prevention**: Never execute destructive operations without verified safety gates.
51
- - **Error Handling**: Never catch and swallow exceptions with empty handlers. Handle failures gracefully.
52
- - **Accessibility & Contrast**: Never sacrifice semantic structure or visual usability.
53
-
54
- ---
55
-
56
- ## 3. Intensity Levels
57
-
58
- - **Lite**: Polite nudge to question unnecessary dependencies and prefer standard library methods.
59
- - **Full (Default)**: Strictly halts at the first rung of the Decision Ladder that solves the problem.
60
- - **Ultra**: Ruthlessly strips all boilerplate, rejects any wrapper that only has one callsite, and deletes dead code on sight.
61
-
62
- ---
44
+ Never cut: validation at trust boundaries, error handling that prevents data loss, security, accessibility, the calibration real hardware needs, anything the user asked for.
63
45
 
64
- ## Upstream Provenance & Governance Protocol
46
+ ## Levels
65
47
 
66
- - **Source Repository**: [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail)
67
- - **Update Directive**:
68
- > *Update the selected skill or plugin through its supported mechanism. Review changed instructions/references and repeat a bounded review after material updates. Record source revision, reviewed range, actual tests and remaining validation in the private report.*
48
+ | Level | Behavior |
49
+ |-------|----------|
50
+ | **lite** | Build what was asked. Name the smaller option in one line and let the user pick. |
51
+ | **full** | The rules above. Default. |
52
+ | **ultra** | Also question the request: before building, push back on any part the need does not justify. |
@@ -1,64 +1,42 @@
1
1
  ---
2
- name: supabase-postgres-best-practices
3
- description: "Postgres best practices maintained by Supabase, for Postgres running anywhere. Load this skill BEFORE writing or changing anything that lives in a Postgres database: creating or altering tables and columns (including choosing column types), schema design, migrations and declarative schema files, RLS policies and the tests that verify them, indexes, triggers, database functions, queues and scheduled jobs (pg_cron, pgmq), vector/semantic search (pgvector), and restoring dumps (pg_restore) or importing data. Also load it when diagnosing slow queries, high CPU, timeouts, EXPLAIN plans, connection exhaustion, locking, bloat, or rows visible to the wrong user or tenant. This is not just a performance guide — schema, migration, security, and SQL authoring tasks need these rules too, even for a one-column change or a single query."
4
- license: MIT
5
- metadata:
6
- author: supabase
7
- version: "1.1.1"
8
- organization: Supabase
9
- date: January 2026
10
- abstract: Comprehensive Postgres performance optimization guide for developers using Supabase and Postgres. Contains performance rules across 8 categories, prioritized by impact from critical (query performance, connection management) to incremental (advanced features). Each rule includes detailed explanations, incorrect vs. correct SQL examples, query plan analysis, and specific performance metrics to guide automated optimization and code generation.
2
+ name: postgres-best-practices
3
+ description: Best practices and guidelines for working with Postgres. Covers schema design, indexing strategies, query optimization, migrations, and common pitfalls. Use when writing SQL, designing database schemas, optimizing queries, or setting up a Postgres database.
11
4
  ---
12
5
 
13
- # Supabase Postgres Best Practices
6
+ # Postgres Best Practices
14
7
 
15
- Comprehensive performance optimization guide for Postgres, maintained by Supabase. Contains rules across 8 categories, prioritized by impact to guide automated query optimization and schema design.
8
+ Guidelines and best practices for working with Postgres, covering schema design, indexing, query optimization, and common pitfalls.
16
9
 
17
- ## When to Apply
10
+ ## Supported Versions
18
11
 
19
- Reference these guidelines when:
20
- - Writing SQL queries or designing schemas
21
- - Implementing indexes or query optimization
22
- - Reviewing database performance issues
23
- - Configuring connection pooling or scaling
24
- - Optimizing for Postgres-specific features
25
- - Working with Row-Level Security (RLS)
12
+ This skill covers PostgreSQL 14 through 18. Version-specific features are tagged (e.g., `[PG15+]`, `[PG18+]`); environment-dependent examples identify required privileges, extensions, or multi-node setup.
26
13
 
27
- ## Rule Categories by Priority
14
+ PostgreSQL provides 5 years of support per major version. Always run the latest minor release.
28
15
 
29
- | Priority | Category | Impact | Prefix |
30
- |----------|----------|--------|--------|
31
- | 1 | Query Performance | CRITICAL | `query-` |
32
- | 2 | Connection Management | CRITICAL | `conn-` |
33
- | 3 | Security & RLS | CRITICAL | `security-` |
34
- | 4 | Schema Design | HIGH | `schema-` |
35
- | 5 | Concurrency & Locking | MEDIUM-HIGH | `lock-` |
36
- | 6 | Data Access Patterns | MEDIUM | `data-` |
37
- | 7 | Monitoring & Diagnostics | LOW-MEDIUM | `monitor-` |
38
- | 8 | Advanced Features | LOW | `advanced-` |
16
+ | Version | Initial Release | End of Life |
17
+ | ------- | ------------------ | ------------------ |
18
+ | 18 | September 2025 | November 2030 |
19
+ | 17 | September 2024 | November 2029 |
20
+ | 16 | September 2023 | November 2028 |
21
+ | 15 | October 2022 | November 2027 |
22
+ | 14 | September 2021 | November 2026 |
39
23
 
40
- ## How to Use
41
-
42
- Read individual rule files for detailed explanations and SQL examples:
43
-
44
- ```
45
- references/query-missing-indexes.md
46
- references/query-partial-indexes.md
47
- references/_sections.md
48
- ```
49
-
50
- Each rule file contains:
51
- - Brief explanation of why it matters
52
- - Incorrect SQL example with explanation
53
- - Correct SQL example with explanation
54
- - Optional EXPLAIN output or metrics
55
- - Additional context and references
56
- - Supabase-specific notes (when applicable)
24
+ Source: [postgresql.org/support/versioning](https://www.postgresql.org/support/versioning/)
57
25
 
58
26
  ## References
59
27
 
60
- - https://www.postgresql.org/docs/current/
61
- - https://supabase.com/docs
62
- - https://wiki.postgresql.org/wiki/Performance_Optimization
63
- - https://supabase.com/docs/guides/database/overview
64
- - https://supabase.com/docs/guides/auth/row-level-security
28
+ | Area | Resource | When to Use |
29
+ | ----------------------- | --------------------------------------- | ------------------------------------------------------------------ |
30
+ | Schema Design | `references/schema-design.md` | Designing tables, choosing data types, normalizing, partitioning |
31
+ | Indexing | `references/indexing.md` | Choosing index types, composite indexes, partial/covering indexes |
32
+ | Query Optimization | `references/query-optimization.md` | Reading EXPLAIN ANALYZE, fixing bottlenecks, planner tuning |
33
+ | Query Patterns | `references/query-patterns.md` | CTEs, window functions, lateral joins, UPSERT, JSONB, anti-patterns|
34
+ | Performance Diagnostics | `references/performance-diagnostics.md` | pg_stat views, lock analysis, VACUUM, connection management |
35
+ | Logical Replication | `references/logical-replication.md` | Pub/sub replication, live migrations, CDC |
36
+ | Hot Standby | `references/hot-standby.md` | Streaming replication, read replicas, failover |
37
+ | Transaction Isolation | `references/transaction-isolation.md` | Isolation levels, lost updates, serialization failures, retry logic |
38
+ | Backup & Restore | `references/backup-restore.md` | pg_dump/pg_restore, pg_basebackup, PITR, recovery |
39
+ | Security & Roles | `references/security-roles.md` | Privileges, RLS, pg_hba.conf, authentication, SSL |
40
+ | Bulk Data Loading | `references/bulk-loading.md` | COPY patterns, ETL staging, optimizing large loads, batch ops |
41
+ | Connection Pooling | `references/connection-pooling.md` | PgBouncer config, pool modes, prepared statements, sizing |
42
+ | Major Version Upgrades | `references/major-version-upgrades.md` | pg_upgrade, logical replication migration, pre/post checklists |
@@ -0,0 +1,372 @@
1
+ # Backup & Restore Reference
2
+
3
+ ## Contents
4
+ - Backup strategy overview
5
+ - Logical backups (pg_dump / pg_restore)
6
+ - Physical backups (pg_basebackup)
7
+ - Point-in-Time Recovery (PITR)
8
+ - Verification and testing
9
+ - Automation patterns
10
+
11
+ ## Backup Strategy Overview
12
+
13
+ | Method | What it captures | Granularity | Speed | Use case |
14
+ |--------|-----------------|-------------|-------|----------|
15
+ | `pg_dump` | Logical (SQL/custom) | Per-database, per-table | Slow on large DBs | Dev snapshots, migrations, selective restore |
16
+ | `pg_dumpall` | All databases + globals | Entire cluster | Slow | Full cluster backup including roles/tablespaces |
17
+ | `pg_basebackup` | Physical (file copy) | Entire cluster | Fast | Production backups, PITR base, replica setup |
18
+ | Continuous archiving | WAL segments | Incremental | Continuous | PITR — restore to any point in time |
19
+
20
+ **Production recommendation**: `pg_basebackup` + continuous WAL archiving for PITR capability. Supplement with periodic `pg_dump` for portable, version-independent backups.
21
+
22
+ ## Logical Backups (pg_dump / pg_restore)
23
+
24
+ ### pg_dump Formats
25
+
26
+ | Format | Flag | Parallel restore? | Selective restore? | Notes |
27
+ |--------|------|-------------------|-------------------|-------|
28
+ | Custom | `-Fc` | Yes | Yes | **Recommended default** — compressed, flexible |
29
+ | Directory | `-Fd` | Yes | Yes | One file per table, good for large DBs |
30
+ | Plain SQL | `-Fp` | No | No (manual editing) | Human-readable, good for version control |
31
+ | Tar | `-Ft` | No | Yes | Compatibility option |
32
+
33
+ ### Common pg_dump Patterns
34
+
35
+ ```bash
36
+ # Full database backup (custom format — recommended)
37
+ pg_dump -Fc -f backup.dump mydb
38
+
39
+ # With compression level (0-9, default varies by format)
40
+ pg_dump -Fc -Z 6 -f backup.dump mydb
41
+
42
+ # Parallel dump (directory format only, 4 workers)
43
+ pg_dump -Fd -j 4 -f backup_dir/ mydb
44
+
45
+ # Schema only (no data)
46
+ pg_dump -Fc --schema-only -f schema.dump mydb
47
+
48
+ # Data only (no schema)
49
+ pg_dump -Fc --data-only -f data.dump mydb
50
+
51
+ # Specific tables
52
+ pg_dump -Fc -t orders -t customers -f subset.dump mydb
53
+
54
+ # Specific schema
55
+ pg_dump -Fc -n public -f public_schema.dump mydb
56
+
57
+ # Exclude large tables
58
+ pg_dump -Fc -T audit_log -T event_archive -f without_logs.dump mydb
59
+
60
+ # Include CREATE DATABASE in output
61
+ pg_dump -Fc --create -f backup_with_create.dump mydb
62
+ ```
63
+
64
+ ### pg_restore Patterns
65
+
66
+ ```bash
67
+ # Restore to an existing (empty) database
68
+ pg_restore -d mydb backup.dump
69
+
70
+ # Parallel restore (4 workers — significantly faster for large DBs)
71
+ pg_restore -d mydb -j 4 backup.dump
72
+
73
+ # Create the database during restore
74
+ pg_restore --create -d postgres backup.dump
75
+
76
+ # List contents of a backup (inspect before restoring)
77
+ pg_restore --list backup.dump
78
+
79
+ # Restore specific tables only
80
+ pg_restore -d mydb -t orders -t customers backup.dump
81
+
82
+ # Schema only
83
+ pg_restore -d mydb --schema-only backup.dump
84
+
85
+ # Data only (schema already exists)
86
+ pg_restore -d mydb --data-only backup.dump
87
+
88
+ # Clean (drop) objects before recreating
89
+ pg_restore -d mydb --clean --if-exists backup.dump
90
+
91
+ # Restore atomically and stop on the first error
92
+ pg_restore -d mydb --single-transaction -j 1 backup.dump
93
+ # Note: --single-transaction is incompatible with -j > 1
94
+ ```
95
+
96
+ Selective restore patterns do not automatically include dependencies. Schema-qualify table patterns when names may exist in multiple schemas, and verify required types, sequences, constraints, and referenced tables separately.
97
+
98
+ ### Restoring Plain SQL Dumps
99
+
100
+ ```bash
101
+ # Plain SQL dumps are restored with psql, not pg_restore
102
+ psql -d mydb -f backup.sql
103
+
104
+ # With error handling
105
+ psql -d mydb -v ON_ERROR_STOP=1 -f backup.sql
106
+ ```
107
+
108
+ ### pg_dumpall — Cluster-Wide Backup
109
+
110
+ `pg_dumpall` is the only way to back up global objects (roles, tablespaces):
111
+
112
+ ```bash
113
+ # Full cluster (all databases + globals) — plain SQL only
114
+ pg_dumpall -f cluster_backup.sql
115
+
116
+ # Globals only (roles, tablespaces) — use alongside per-database pg_dump
117
+ pg_dumpall --globals-only -f globals.sql
118
+
119
+ # Roles only
120
+ pg_dumpall --roles-only -f roles.sql
121
+ ```
122
+
123
+ **Best practice**: Use `pg_dumpall --globals-only` for roles/tablespaces, then `pg_dump -Fc` per database for data. This gives you parallel restore capability while preserving globals.
124
+
125
+ ### Optimizer Statistics in Backups (PG18+)
126
+
127
+ ```bash
128
+ # Dump optimizer statistics (speeds up post-restore query performance)
129
+ pg_dump -Fc --statistics -f backup.dump mydb
130
+
131
+ # Statistics only (no schema or data)
132
+ pg_dump -Fc --statistics-only -f stats.dump mydb
133
+
134
+ # Skip statistics
135
+ pg_dump -Fc --no-statistics -f backup.dump mydb
136
+ ```
137
+
138
+ Without statistics, the planner uses default estimates after restore until `ANALYZE` runs on all tables. Dumping statistics avoids the post-restore performance dip.
139
+
140
+ ### Performance Tips for Large Databases
141
+
142
+ 1. **Use parallel dump/restore** (`-Fd -j N`) — scales well with CPU cores
143
+ 2. **Dump to fast storage** — local NVMe, not network mounts
144
+ 3. **Increase `maintenance_work_mem`** on the restore target for faster index rebuilds
145
+ 4. **Disable triggers during data-only restore**: `pg_restore --disable-triggers` (requires superuser)
146
+ 5. **Drop indexes before restore, recreate after** — faster than incremental index maintenance during bulk inserts
147
+ 6. **Restore schema first, then data, then indexes**:
148
+ ```bash
149
+ pg_restore -d mydb --section=pre-data backup.dump
150
+ pg_restore -d mydb --data-only -j 4 backup.dump
151
+ pg_restore -d mydb --section=post-data -j 4 backup.dump
152
+ ```
153
+
154
+ ## Physical Backups (pg_basebackup)
155
+
156
+ `pg_basebackup` creates a byte-for-byte copy of the entire cluster, suitable as a base for PITR or setting up replicas.
157
+
158
+ ```bash
159
+ # Basic backup (plain format)
160
+ pg_basebackup -D /backup/base -Fp -Xs -P
161
+
162
+ # Compressed tar format
163
+ pg_basebackup -D /backup/base -Ft -z -Xs -P
164
+
165
+ # With checkpoint mode (fast = don't wait for next scheduled checkpoint)
166
+ pg_basebackup -D /backup/base -Fp -Xs -P --checkpoint=fast
167
+
168
+ # To a remote server
169
+ pg_basebackup -h primary_host -U repl_user -D /backup/base -Fp -Xs -P
170
+ ```
171
+
172
+ | Flag | Meaning |
173
+ |------|---------|
174
+ | `-D` | Target directory |
175
+ | `-Fp` | Plain format (ready-to-use data directory) |
176
+ | `-Ft` | Tar format (one tar per tablespace) |
177
+ | `-z` | Compress (with tar format) |
178
+ | `-Xs` | Stream WAL during backup (ensures consistency) |
179
+ | `-P` | Show progress |
180
+ | `--checkpoint=fast` | Start backup immediately (don't wait for next checkpoint) |
181
+
182
+ ### Prerequisites
183
+
184
+ The connection used by `pg_basebackup` must authenticate as a superuser or a role with `REPLICATION` privilege. `max_wal_senders` must also have enough capacity for the backup connection:
185
+
186
+ ```sql
187
+ -- On the primary
188
+ CREATE ROLE backup_user WITH REPLICATION LOGIN PASSWORD '...';
189
+ ```
190
+
191
+ And `pg_hba.conf` must allow replication connections:
192
+
193
+ ```
194
+ host replication backup_user backup_server_ip/32 scram-sha-256
195
+ ```
196
+
197
+ [PG15+] `--target=server:/path` writes the backup on the database server. A non-superuser using this target needs both `REPLICATION` privilege for the backup connection and membership in `pg_write_server_files` for the server-side write. `--target` is unavailable in PG14 and cannot be combined with `-Xstream`; use `-Xfetch` or `-Xnone`.
198
+
199
+ ## Point-in-Time Recovery (PITR)
200
+
201
+ PITR lets you restore a database to any specific point in time — invaluable for recovering from accidental data deletion or corruption.
202
+
203
+ ### How PITR Works
204
+
205
+ 1. Take a **base backup** (`pg_basebackup`)
206
+ 2. Continuously **archive WAL segments** as they're produced
207
+ 3. To recover: restore the base backup, then **replay WAL** up to the target time
208
+
209
+ ### Step 1: Configure WAL Archiving
210
+
211
+ In `postgresql.conf`:
212
+
213
+ ```
214
+ archive_mode = on
215
+ archive_command = 'cp %p /archive/wal/%f' # or use pgBackRest, barman, etc.
216
+ # archive_library = '' # PG15+: use archive modules instead of shell commands
217
+ ```
218
+
219
+ Requires a restart after enabling `archive_mode`.
220
+
221
+ Verify archiving is working:
222
+
223
+ ```sql
224
+ SELECT * FROM pg_stat_archiver;
225
+ -- Check: archived_count is increasing, last_failed_time is NULL
226
+ ```
227
+
228
+ ### Step 2: Take Base Backups Regularly
229
+
230
+ ```bash
231
+ # Weekly base backup (adjust frequency based on WAL volume)
232
+ pg_basebackup -D /backup/base_$(date +%Y%m%d) -Ft -z -Xs -P --checkpoint=fast
233
+ ```
234
+
235
+ ### Step 3: Recovery
236
+
237
+ To recover to a specific point in time:
238
+
239
+ 1. Stop PostgreSQL
240
+ 2. Replace the data directory with the base backup
241
+ 3. Create `recovery.signal` (PG12+) or `recovery.conf` (PG11-)
242
+ 4. Configure recovery target in `postgresql.conf`:
243
+
244
+ ```
245
+ # In postgresql.conf (PG12+):
246
+ restore_command = 'cp /archive/wal/%f %p'
247
+ recovery_target_time = '2024-06-15 14:30:00'
248
+ recovery_target_action = 'promote' # 'pause' to inspect before promoting
249
+ ```
250
+
251
+ 5. Start PostgreSQL — it replays WAL up to the target time, then promotes to read-write
252
+
253
+ ### Recovery Target Options
254
+
255
+ ```text
256
+ -- Recover to a specific time
257
+ recovery_target_time = '2024-06-15 14:30:00+00'
258
+
259
+ -- Recover to a specific transaction ID
260
+ recovery_target_xid = '12345678'
261
+
262
+ -- Recover to a named restore point
263
+ recovery_target_name = 'before_migration'
264
+
265
+ -- Stop as soon as a consistent state is reached
266
+ -- (for an online backup, normally the point where the backup ended)
267
+ recovery_target = 'immediate'
268
+
269
+ -- Recover to a specific WAL position
270
+ recovery_target_lsn = '0/1A2B3C4D'
271
+ ```
272
+
273
+ To recover through the end of all available WAL, omit every `recovery_target*` setting. `recovery_target = 'immediate'` is an explicit early stopping target, so later available WAL can remain unapplied. PostgreSQL may still replay the WAL required to make an online backup consistent.
274
+
275
+ ### Creating Named Restore Points
276
+
277
+ Before risky operations, create a named restore point:
278
+
279
+ ```sql
280
+ SELECT pg_create_restore_point('before_schema_migration');
281
+ SELECT pg_create_restore_point('before_bulk_delete');
282
+ ```
283
+
284
+ This gives you an exact target to recover to if the operation goes wrong.
285
+
286
+ ## Verification and Testing
287
+
288
+ ### Verify Backup Integrity
289
+
290
+ ```bash
291
+ # List contents without restoring
292
+ pg_restore --list backup.dump
293
+
294
+ # Verify a plain-format physical backup (PG13+)
295
+ pg_verifybackup /backup/base_20240615
296
+
297
+ # PG18+: verify a tar-format backup directly
298
+ pg_verifybackup --no-parse-wal /backup/base_tar_20240615
299
+ ```
300
+
301
+ ### Test Restores Regularly
302
+
303
+ **A backup that hasn't been tested is not a backup.** Schedule regular restore tests:
304
+
305
+ ```bash
306
+ # Restore to a test database
307
+ createdb mydb_restore_test
308
+ pg_restore -d mydb_restore_test backup.dump
309
+
310
+ # Verify row counts
311
+ psql -d mydb_restore_test -c "
312
+ SELECT schemaname, relname, n_live_tup
313
+ FROM pg_stat_user_tables
314
+ ORDER BY n_live_tup DESC;
315
+ "
316
+
317
+ # Clean up
318
+ dropdb mydb_restore_test
319
+ ```
320
+
321
+ ### Post-Restore Checklist
322
+
323
+ After restoring a backup:
324
+
325
+ 1. **Run `ANALYZE`** on all tables — optimizer statistics may be stale or missing
326
+ ```sql
327
+ ANALYZE; -- all tables
328
+ ```
329
+ 2. **Verify sequences** — if restoring data-only, sequences may not match the data
330
+ ```sql
331
+ SELECT sequencename, last_value FROM pg_sequences WHERE schemaname = 'public';
332
+ ```
333
+ 3. **Check for invalid indexes** — concurrent index builds may have been in progress
334
+ ```sql
335
+ SELECT indexrelid::regclass, indisvalid FROM pg_index WHERE NOT indisvalid;
336
+ ```
337
+ 4. **Verify replication slots are clean** — stale slots from the source won't work
338
+ ```sql
339
+ SELECT slot_name, active FROM pg_replication_slots;
340
+ ```
341
+
342
+ ## Automation Patterns
343
+
344
+ ### Scripted Backup with Retention
345
+
346
+ ```bash
347
+ #!/bin/bash
348
+ BACKUP_DIR="/backup/pg"
349
+ RETENTION_DAYS=30
350
+ DB_NAME="mydb"
351
+ TIMESTAMP=$(date +%Y%m%d_%H%M%S)
352
+
353
+ # Dump
354
+ pg_dump -Fc -Z 6 -f "${BACKUP_DIR}/${DB_NAME}_${TIMESTAMP}.dump" "${DB_NAME}"
355
+
356
+ # Verify dump was created and is non-empty
357
+ if [ ! -s "${BACKUP_DIR}/${DB_NAME}_${TIMESTAMP}.dump" ]; then
358
+ echo "ERROR: Backup file is empty or missing" >&2
359
+ exit 1
360
+ fi
361
+
362
+ # Clean old backups
363
+ find "${BACKUP_DIR}" -name "${DB_NAME}_*.dump" -mtime +${RETENTION_DAYS} -delete
364
+ ```
365
+
366
+ ### Dedicated Backup Tools
367
+
368
+ For production environments, consider purpose-built tools that handle scheduling, retention, compression, and PITR:
369
+
370
+ - **pgBackRest** — parallel backup/restore, incremental backups, S3/GCS/Azure support, built-in PITR
371
+ - **Barman** — backup management with retention policies, remote backup, WAL archiving
372
+ - **pg_probackup** — incremental backups with page-level tracking, merge, validation