heimdall-agent 1.0.0 → 1.2.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 (250) hide show
  1. package/README.md +57 -26
  2. package/README.pt-BR.md +443 -0
  3. package/agents/cloud-engineer.md +77 -0
  4. package/agents/code-sentinel.md +71 -34
  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 +68 -0
  9. package/agents/orchestrator.md +107 -93
  10. package/agents/reviewer.md +102 -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 +31 -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 +762 -573
  22. package/docs/SKILLS.md +393 -275
  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/2026-11-12-compare-report.json +1028 -0
  29. package/docs/runs/skill-audit/2026-11-12-upstream-audit.json +275 -0
  30. package/docs/runs/skill-audit/add_progressive_disclosure.cjs +30 -0
  31. package/docs/runs/skill-audit/check_heimdall_skills.ps1 +9 -0
  32. package/docs/runs/skill-audit/compare_classics.ps1 +26 -0
  33. package/docs/runs/skill-audit/compare_taste.ps1 +12 -0
  34. package/docs/runs/skill-audit/customization-report.json +380 -0
  35. package/docs/runs/skill-audit/diff_pending_skills.cjs +94 -0
  36. package/docs/runs/skill-audit/fetch_and_apply_skill.cjs +58 -0
  37. package/docs/runs/skill-audit/fetch_and_apply_taste_v2.cjs +65 -0
  38. package/docs/runs/skill-audit/inspect_pending_skills.cjs +71 -0
  39. package/docs/runs/skill-audit/inventory.json +308 -0
  40. package/docs/runs/skill-audit/list_local_taste.ps1 +1 -0
  41. package/docs/runs/skill-audit/phase5-update-plan.json +595 -0
  42. package/docs/runs/skill-audit/phase5-update-plan.md +138 -0
  43. package/docs/runs/skill-audit/probe.ps1 +16 -0
  44. package/docs/runs/skill-audit/probe_classics_branches.ps1 +3 -0
  45. package/docs/runs/skill-audit/probe_commits.ps1 +15 -0
  46. package/docs/runs/skill-audit/probe_repos.ps1 +17 -0
  47. package/docs/runs/skill-audit/probe_sentry_sec.ps1 +3 -0
  48. package/docs/runs/skill-audit/probe_sentry_sweep.ps1 +5 -0
  49. package/docs/runs/skill-audit/probe_snyk.ps1 +3 -0
  50. package/docs/runs/skill-audit/probe_snyk_recipes.ps1 +5 -0
  51. package/docs/runs/skill-audit/probe_taste_branches.ps1 +8 -0
  52. package/docs/runs/skill-audit/probe_taste_v19.ps1 +3 -0
  53. package/docs/runs/skill-audit/probe_user_repos.ps1 +19 -0
  54. package/docs/runs/skill-audit/prune_taste_skills.cjs +22 -0
  55. package/docs/runs/skill-audit/run_phase1_2.cjs +142 -0
  56. package/docs/runs/skill-audit/run_phase6_verification.cjs +107 -0
  57. package/docs/runs/skill-audit/show_16_details.ps1 +25 -0
  58. package/docs/runs/skill-audit/show_20_skills.ps1 +28 -0
  59. package/docs/runs/skill-audit/show_classics_diff.cjs +37 -0
  60. package/docs/runs/skill-audit/sync_agent_markdowns.cjs +30 -0
  61. package/docs/runs/skill-audit/taste-skill-upstream.md +542 -0
  62. package/docs/runs/skill-audit/update-manifest.md +88 -0
  63. package/docs/runs/skill-audit/update_config_skills.cjs +52 -0
  64. package/docs/runs/skill-audit/update_registry_phase7.cjs +83 -0
  65. package/docs/runs/skill-audit/upstream-status.json +563 -0
  66. package/docs/runs/skill-audit/verification-results.json +252 -0
  67. package/doctrine/AGENTS.md +42 -77
  68. package/hooks/git/pre-commit +11 -0
  69. package/hooks/heimdall-hook.cjs +81 -2
  70. package/hooks/herdr-agent-state.ps1 +55 -0
  71. package/hooks/hooks.json +0 -11
  72. package/lib/catalog-sync.cjs +167 -0
  73. package/lib/hermes-context.cjs +57 -0
  74. package/lib/model-context.cjs +123 -0
  75. package/lib/path-discovery.cjs +94 -0
  76. package/package.json +7 -3
  77. package/playbooks/01-interactive-grilling-gate.md +23 -6
  78. package/playbooks/02-fast-code-deep-verification.md +3 -2
  79. package/playbooks/03-adversarial-code-review.md +15 -7
  80. package/playbooks/05-canonical-plan-template.md +35 -19
  81. package/playbooks/06-model-registry-matrix.md +24 -13
  82. package/playbooks/07-legacy-code-modernization.md +74 -0
  83. package/playbooks/08-backlog-and-change-request-flow.md +122 -0
  84. package/setup.mjs +592 -172
  85. package/skills/antislop/SKILL.md +76 -56
  86. package/skills/antislop/VERSION +1 -0
  87. package/skills/antislop-copywriting/SKILL.md +407 -372
  88. package/skills/antislop-human/LICENSE-web-quality-skills +21 -0
  89. package/skills/antislop-human/SKILL.md +204 -147
  90. package/skills/antislop-human/contrast-check.py +168 -165
  91. package/skills/antislop-human/contrast-mcp.py +6 -3
  92. package/skills/antislop-human/references/A11Y-PATTERNS.md +249 -0
  93. package/skills/antislop-human/references/WCAG.md +127 -0
  94. package/skills/antislop-ui/LICENSE-web-quality-skills +21 -0
  95. package/skills/antislop-ui/SKILL.md +344 -304
  96. package/skills/antislop-ui/references/CORE-WEB-VITALS.md +181 -0
  97. package/skills/antislop-ui/references/WEB-BASELINE.md +28 -0
  98. package/skills/brainstorming/SKILL.md +296 -265
  99. package/skills/brainstorming/builder-check-prompt.md +23 -0
  100. package/skills/brainstorming/scripts/frame-template.html +213 -213
  101. package/skills/brainstorming/scripts/server.cjs +723 -723
  102. package/skills/brandkit/SKILL.md +798 -798
  103. package/skills/brutalist-skill/SKILL.md +93 -92
  104. package/skills/caveman/README.md +68 -0
  105. package/skills/caveman/SKILL.md +73 -38
  106. package/skills/claude-collaborator/SKILL.md +24 -44
  107. package/skills/clean-code/SKILL.md +152 -0
  108. package/skills/cloudflare-security-audit/AI-AND-LLM.md +83 -83
  109. package/skills/cloudflare-security-audit/ATTACK-CLASSES.md +130 -130
  110. package/skills/cloudflare-security-audit/CLIENT-SIDE.md +83 -83
  111. package/skills/cloudflare-security-audit/CLOUD-AND-DEPLOYMENT.md +86 -86
  112. package/skills/cloudflare-security-audit/DATA-ISOLATION-AND-LIFECYCLE.md +84 -84
  113. package/skills/cloudflare-security-audit/DESKTOP-MOBILE-AND-LOCAL-IPC.md +89 -89
  114. package/skills/cloudflare-security-audit/HUNTING.md +251 -251
  115. package/skills/cloudflare-security-audit/MEMORY-SAFETY-AND-BINARY.md +101 -101
  116. package/skills/cloudflare-security-audit/PROTOCOLS-RPC-AND-MESSAGING.md +81 -81
  117. package/skills/cloudflare-security-audit/RECONNAISSANCE.md +156 -156
  118. package/skills/cloudflare-security-audit/RESOURCE-EXHAUSTION-AND-AVAILABILITY.md +78 -78
  119. package/skills/cloudflare-security-audit/SKILL.md +192 -192
  120. package/skills/cloudflare-security-audit/SUPPLY-CHAIN-AND-RELEASE.md +73 -73
  121. package/skills/cloudflare-security-audit/VALIDATION-AND-REPORTING.md +186 -186
  122. package/skills/cloudflare-security-audit/WEB-PROTOCOL-AND-AUTH.md +105 -105
  123. package/skills/cloudflare-security-audit/report-schema.json +461 -461
  124. package/skills/cloudflare-security-audit/validate-coverage-ledger.cjs +872 -872
  125. package/skills/cloudflare-security-audit/validate-coverage-ledger.test.cjs +740 -740
  126. package/skills/cloudflare-security-audit/validate-findings.cjs +773 -773
  127. package/skills/cloudflare-security-audit/validate-findings.test.cjs +652 -652
  128. package/skills/codebase-design/DEEPENING.md +37 -0
  129. package/skills/codebase-design/DESIGN-IT-TWICE.md +44 -0
  130. package/skills/codebase-design/SKILL.md +114 -0
  131. package/skills/codex-collaborator/SKILL.md +24 -45
  132. package/skills/communication-doctrine/SKILL.md +89 -0
  133. package/skills/diagnosing-superpowers/SKILL.md +1 -1
  134. package/skills/diagnosing-superpowers/references/github-issues.md +3 -3
  135. package/skills/diagnosing-superpowers/templates/issue.md +23 -4
  136. package/skills/domain-modeling/ADR-FORMAT.md +47 -0
  137. package/skills/domain-modeling/GLOSSARY-FORMAT.md +60 -0
  138. package/skills/domain-modeling/SKILL.md +74 -0
  139. package/skills/executing-plans/SKILL.md +6 -56
  140. package/skills/executing-plans/scripts/task-done +52 -52
  141. package/skills/executing-plans/scripts/task-start +28 -28
  142. package/skills/gemini-collaborator/SKILL.md +24 -56
  143. package/skills/grill-me/SKILL.md +65 -0
  144. package/skills/handoff/SKILL.md +64 -0
  145. package/skills/herdr/SKILL.md +243 -0
  146. package/skills/image-to-code-skill/SKILL.md +1228 -1228
  147. package/skills/imagegen-frontend-mobile/SKILL.md +1465 -1465
  148. package/skills/imagegen-frontend-web/SKILL.md +987 -987
  149. package/skills/improve-codebase-architecture/HTML-REPORT.md +123 -0
  150. package/skills/improve-codebase-architecture/SKILL.md +71 -0
  151. package/skills/karpathy-guidelines/SKILL.md +67 -67
  152. package/skills/mcp-engineering/SKILL.md +74 -0
  153. package/skills/minimalist-skill/SKILL.md +87 -85
  154. package/skills/output-skill/SKILL.md +49 -49
  155. package/skills/owasp-security/reference/config-and-supply-chain.md +346 -344
  156. package/skills/owasp-security/reference/languages.md +378 -372
  157. package/skills/owasp-security/reference/owasp-report.md +1144 -1140
  158. package/skills/owasp-security/reference/review-checklist.md +134 -132
  159. package/skills/ponytail/SKILL.md +36 -52
  160. package/skills/postgres-best-practices/SKILL.md +30 -52
  161. package/skills/postgres-best-practices/references/backup-restore.md +372 -0
  162. package/skills/postgres-best-practices/references/bulk-loading.md +315 -0
  163. package/skills/postgres-best-practices/references/connection-pooling.md +310 -0
  164. package/skills/postgres-best-practices/references/hot-standby.md +221 -0
  165. package/skills/postgres-best-practices/references/indexing.md +318 -0
  166. package/skills/postgres-best-practices/references/logical-replication.md +610 -0
  167. package/skills/postgres-best-practices/references/major-version-upgrades.md +334 -0
  168. package/skills/postgres-best-practices/references/performance-diagnostics.md +553 -0
  169. package/skills/postgres-best-practices/references/query-optimization.md +294 -0
  170. package/skills/postgres-best-practices/references/query-patterns.md +566 -0
  171. package/skills/postgres-best-practices/references/schema-design.md +362 -0
  172. package/skills/postgres-best-practices/references/security-roles.md +489 -0
  173. package/skills/postgres-best-practices/references/transaction-isolation.md +344 -0
  174. package/skills/progressive-disclosure/SKILL.md +68 -0
  175. package/skills/pstack-discipline/SKILL.md +40 -0
  176. package/skills/receiving-code-review/SKILL.md +2 -23
  177. package/skills/requesting-code-review/SKILL.md +7 -36
  178. package/skills/soft-skill/SKILL.md +99 -98
  179. package/skills/stitch-skill/DESIGN.md +121 -121
  180. package/skills/stitch-skill/SKILL.md +185 -184
  181. package/skills/strix-security/SKILL.md +54 -53
  182. package/skills/subagent-driven-development/SKILL.md +35 -264
  183. package/skills/subagent-driven-development/references/batching.md +11 -0
  184. package/skills/subagent-driven-development/references/cannot-verify.md +10 -0
  185. package/skills/subagent-driven-development/references/final-review.md +47 -0
  186. package/skills/subagent-driven-development/references/fix-loop.md +77 -0
  187. package/skills/subagent-driven-development/references/handling-reports.md +15 -0
  188. package/skills/subagent-driven-development/references/preflight.md +26 -0
  189. package/skills/subagent-driven-development/references/resuming.md +12 -0
  190. package/skills/subagent-driven-development/scripts/review-package +53 -53
  191. package/skills/subagent-driven-development/scripts/sdd-workspace +87 -82
  192. package/skills/subagent-driven-development/scripts/task-brief +43 -43
  193. package/skills/systematic-debugging/SKILL.md +283 -306
  194. package/skills/taste-skill/SKILL.md +542 -1206
  195. package/skills/taste-skill/references/app-screens.md +1199 -0
  196. package/skills/taste-skill/references/colour.md +141 -0
  197. package/skills/taste-skill/references/copy.md +177 -0
  198. package/skills/taste-skill/references/critique.md +182 -0
  199. package/skills/taste-skill/references/imagery.md +791 -0
  200. package/skills/taste-skill/references/layout.md +292 -0
  201. package/skills/taste-skill/references/motion.md +980 -0
  202. package/skills/taste-skill/references/research.md +356 -0
  203. package/skills/taste-skill/references/scenes.md +174 -0
  204. package/skills/taste-skill/references/tells.md +115 -0
  205. package/skills/taste-skill/references/type.md +170 -0
  206. package/skills/test-driven-development/SKILL.md +330 -337
  207. package/skills/thermo/SKILL.md +67 -0
  208. package/skills/threat-modeling/SKILL.md +55 -0
  209. package/skills/to-spec/SKILL.md +75 -0
  210. package/skills/to-tickets/SKILL.md +105 -0
  211. package/skills/trailofbits-audit-context/SKILL.md +72 -72
  212. package/skills/trailofbits-insecure-defaults/commands/audit.md +35 -0
  213. package/skills/trailofbits-insecure-defaults/references/debug-features.json +13 -13
  214. package/skills/trailofbits-insecure-defaults/references/debug-features.md +75 -75
  215. package/skills/trailofbits-insecure-defaults/references/default-credentials.json +12 -12
  216. package/skills/trailofbits-insecure-defaults/references/default-credentials.md +76 -76
  217. package/skills/trailofbits-insecure-defaults/references/fail-open-security.json +11 -11
  218. package/skills/trailofbits-insecure-defaults/references/fail-open-security.md +70 -70
  219. package/skills/trailofbits-insecure-defaults/references/fallback-secrets.json +11 -11
  220. package/skills/trailofbits-insecure-defaults/references/fallback-secrets.md +70 -70
  221. package/skills/trailofbits-insecure-defaults/references/permissive-access.json +13 -13
  222. package/skills/trailofbits-insecure-defaults/references/permissive-access.md +62 -62
  223. package/skills/trailofbits-insecure-defaults/references/weak-crypto.json +13 -13
  224. package/skills/trailofbits-insecure-defaults/references/weak-crypto.md +71 -71
  225. package/skills/trailofbits-triage-brocards/SKILL.md +208 -208
  226. package/skills/verification-before-completion/SKILL.md +0 -14
  227. package/skills/wayfinder/SKILL.md +128 -0
  228. package/skills/writing-plans/SKILL.md +11 -15
  229. package/skills/writing-skills/SKILL.md +21 -303
  230. package/skills/writing-skills/references/CLAUDE_MD_TESTING.md +189 -0
  231. package/skills/writing-skills/references/anthropic-best-practices.md +1150 -0
  232. package/skills/writing-skills/references/bulletproofing.md +80 -0
  233. package/skills/writing-skills/references/discovery.md +201 -0
  234. package/skills/writing-skills/references/flowcharts.md +37 -0
  235. package/skills/writing-skills/references/graphviz-conventions.dot +172 -0
  236. package/skills/writing-skills/references/persuasion-principles.md +187 -0
  237. package/skills/writing-skills/references/testing-skills-with-subagents.md +384 -0
  238. package/tools/{claude-bridge.ps1 → archive/claude-bridge.ps1} +10 -7
  239. package/tools/{codex-bridge.ps1 → archive/codex-bridge.ps1} +1 -1
  240. package/tools/{gemini-bridge.ps1 → archive/gemini-bridge.ps1} +12 -19
  241. package/skills/gpt-tasteskill/SKILL.md +0 -74
  242. package/skills/taste-skill-v1/SKILL.md +0 -226
  243. /package/tools/{claude-bridge.cmd → archive/claude-bridge.cmd} +0 -0
  244. /package/tools/{claude-bridge.sh → archive/claude-bridge.sh} +0 -0
  245. /package/tools/{codex-bridge.cmd → archive/codex-bridge.cmd} +0 -0
  246. /package/tools/{codex-bridge.sh → archive/codex-bridge.sh} +0 -0
  247. /package/tools/{codexcli-bridge.cmd → archive/codexcli-bridge.cmd} +0 -0
  248. /package/tools/{codexcli-bridge.ps1 → archive/codexcli-bridge.ps1} +0 -0
  249. /package/tools/{gemini-bridge.cmd → archive/gemini-bridge.cmd} +0 -0
  250. /package/tools/{gemini-bridge.sh → archive/gemini-bridge.sh} +0 -0
@@ -0,0 +1,344 @@
1
+ # Transaction Isolation Reference
2
+
3
+ ## Contents
4
+ - Isolation levels overview
5
+ - READ COMMITTED (default)
6
+ - REPEATABLE READ
7
+ - SERIALIZABLE
8
+ - Common pitfalls and surprises
9
+ - Choosing the right level
10
+ - Retry patterns for serialization failures
11
+
12
+ ## Isolation Levels Overview
13
+
14
+ PostgreSQL implements three isolation levels (READ UNCOMMITTED maps to READ COMMITTED):
15
+
16
+ | Level | Dirty reads | Non-repeatable reads | Phantom reads | Serialization anomalies |
17
+ |-------|-------------|---------------------|---------------|------------------------|
18
+ | READ COMMITTED | No | Yes | Yes | Yes |
19
+ | REPEATABLE READ | No | No | No | Yes |
20
+ | SERIALIZABLE | No | No | No | No |
21
+
22
+ ```sql
23
+ -- Check current isolation level
24
+ SHOW transaction_isolation; -- default: 'read committed'
25
+
26
+ -- Set for a single transaction
27
+ BEGIN ISOLATION LEVEL REPEATABLE READ;
28
+ -- ... work ...
29
+ COMMIT;
30
+
31
+ -- Set for the session
32
+ SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL SERIALIZABLE;
33
+
34
+ -- Set per role or database (persistent)
35
+ ALTER ROLE myapp SET default_transaction_isolation = 'repeatable read';
36
+ ALTER DATABASE mydb SET default_transaction_isolation = 'serializable';
37
+ ```
38
+
39
+ ## READ COMMITTED (Default)
40
+
41
+ Each statement within the transaction sees a **fresh snapshot** — it sees all data committed before that statement began, including commits by other transactions that happened after the transaction started.
42
+
43
+ ### Behavior
44
+
45
+ ```sql
46
+ -- Transaction A -- Transaction B
47
+ BEGIN;
48
+ SELECT balance FROM accounts
49
+ WHERE id = 1; -- sees: 1000
50
+ BEGIN;
51
+ UPDATE accounts SET balance = 500
52
+ WHERE id = 1;
53
+ COMMIT;
54
+ SELECT balance FROM accounts
55
+ WHERE id = 1; -- sees: 500 (!)
56
+ -- The second SELECT sees B's commit
57
+ COMMIT;
58
+ ```
59
+
60
+ ### The Lost Update Problem
61
+
62
+ The most common surprise with READ COMMITTED — concurrent updates can silently overwrite each other:
63
+
64
+ ```sql
65
+ -- Transaction A -- Transaction B
66
+ BEGIN; BEGIN;
67
+ SELECT balance FROM accounts
68
+ WHERE id = 1; -- 1000
69
+ SELECT balance FROM accounts
70
+ WHERE id = 1; -- 1000
71
+
72
+ UPDATE accounts
73
+ SET balance = 1000 - 200 -- = 800
74
+ WHERE id = 1;
75
+ -- B blocks here until A commits
76
+ COMMIT;
77
+ UPDATE accounts
78
+ SET balance = 1000 - 300 -- = 700 (!)
79
+ WHERE id = 1;
80
+ COMMIT;
81
+ -- Final balance: 700
82
+ -- Expected (if serial): 500
83
+ -- A's withdrawal was lost!
84
+ ```
85
+
86
+ **Fixes for lost updates in READ COMMITTED:**
87
+
88
+ 1. **Use atomic SQL** — avoid read-then-write patterns:
89
+ ```sql
90
+ UPDATE accounts SET balance = balance - 200 WHERE id = 1;
91
+ ```
92
+ This is safe because the UPDATE re-evaluates `balance` from the latest committed row.
93
+
94
+ 2. **Use SELECT FOR UPDATE** — lock the row before reading:
95
+ ```sql
96
+ BEGIN;
97
+ SELECT balance FROM accounts WHERE id = 1 FOR UPDATE;
98
+ -- Other transactions block here until we commit
99
+ UPDATE accounts SET balance = balance - 200 WHERE id = 1;
100
+ COMMIT;
101
+ ```
102
+
103
+ 3. **Use REPEATABLE READ or SERIALIZABLE** — the second transaction gets a serialization error instead of silently overwriting.
104
+
105
+ ### UPDATE Re-evaluation
106
+
107
+ When an UPDATE in READ COMMITTED encounters a row locked by another transaction, it **waits** for the lock to release, then **re-evaluates** the WHERE clause against the newly committed row. If the row still matches, it proceeds with the update. If not, it skips the row.
108
+
109
+ This means UPDATE with complex WHERE clauses can behave unexpectedly:
110
+
111
+ ```sql
112
+ -- Transaction A -- Transaction B
113
+ BEGIN; BEGIN;
114
+ UPDATE orders
115
+ SET status = 'processing'
116
+ WHERE status = 'pending'
117
+ AND id = 42;
118
+ UPDATE orders
119
+ SET status = 'processing'
120
+ WHERE status = 'pending'
121
+ AND id = 42;
122
+ -- blocks, waiting for A...
123
+ COMMIT;
124
+ -- A committed: row 42 is now 'processing'
125
+ -- Re-evaluates: WHERE status = 'pending' → false
126
+ -- UPDATE 0 (silently skips the row)
127
+ COMMIT;
128
+ ```
129
+
130
+ ## REPEATABLE READ
131
+
132
+ The entire transaction sees a **single snapshot** taken at the start of the first non-transaction-control statement. Subsequent statements see the same data regardless of concurrent commits.
133
+
134
+ ### Behavior
135
+
136
+ ```sql
137
+ -- Transaction A -- Transaction B
138
+ BEGIN ISOLATION LEVEL
139
+ REPEATABLE READ;
140
+ SELECT balance FROM accounts
141
+ WHERE id = 1; -- sees: 1000
142
+ BEGIN;
143
+ UPDATE accounts SET balance = 500
144
+ WHERE id = 1;
145
+ COMMIT;
146
+ SELECT balance FROM accounts
147
+ WHERE id = 1; -- still sees: 1000
148
+ COMMIT;
149
+ ```
150
+
151
+ ### Serialization Errors
152
+
153
+ If a REPEATABLE READ transaction tries to update a row that was modified by a concurrent committed transaction, it fails:
154
+
155
+ ```sql
156
+ -- Transaction A -- Transaction B
157
+ BEGIN ISOLATION LEVEL
158
+ REPEATABLE READ;
159
+ SELECT * FROM accounts
160
+ WHERE id = 1;
161
+ BEGIN;
162
+ UPDATE accounts SET balance = 500
163
+ WHERE id = 1;
164
+ COMMIT;
165
+ UPDATE accounts
166
+ SET balance = balance - 200
167
+ WHERE id = 1;
168
+ -- ERROR: could not serialize access due to concurrent update
169
+ ```
170
+
171
+ This is **safer** than READ COMMITTED's silent re-evaluation — you know the operation failed and can retry.
172
+
173
+ ### What REPEATABLE READ Does NOT Prevent
174
+
175
+ REPEATABLE READ prevents non-repeatable reads and phantoms, but does not prevent all serialization anomalies. Write skew is still possible:
176
+
177
+ ```sql
178
+ -- Constraint: at least one doctor must be on-call
179
+ -- Doctor A and Doctor B are both on-call
180
+
181
+ -- Transaction A (REPEATABLE READ) -- Transaction B (REPEATABLE READ)
182
+ BEGIN; BEGIN;
183
+ SELECT count(*) FROM oncall
184
+ WHERE on_duty = true; -- 2
185
+ SELECT count(*) FROM oncall
186
+ WHERE on_duty = true; -- 2
187
+ UPDATE oncall
188
+ SET on_duty = false
189
+ WHERE doctor = 'A'; -- OK, 1 left
190
+ UPDATE oncall
191
+ SET on_duty = false
192
+ WHERE doctor = 'B'; -- OK, 1 left
193
+ COMMIT; COMMIT;
194
+ -- Both committed! No one is on-call.
195
+ ```
196
+
197
+ Use SERIALIZABLE to prevent write skew.
198
+
199
+ ## SERIALIZABLE
200
+
201
+ The strongest level. Transactions behave **as if they executed one at a time** (serially). PostgreSQL uses Serializable Snapshot Isolation (SSI) — an optimistic approach that detects conflicts during statement execution or at commit rather than acquiring heavy locks upfront.
202
+
203
+ ### Behavior
204
+
205
+ All the anomalies prevented by REPEATABLE READ are prevented, plus serialization anomalies like write skew:
206
+
207
+ ```sql
208
+ -- Same on-call scenario with SERIALIZABLE:
209
+ -- One of the two transactions will get:
210
+ -- ERROR: could not serialize access due to read/write dependencies among transactions
211
+ ```
212
+
213
+ ### Performance Characteristics
214
+
215
+ - Reads are not blocked — SSI tracks read/write dependencies optimistically
216
+ - Slightly higher overhead per transaction (dependency tracking)
217
+ - More serialization failures under contention (requires retry logic)
218
+ - Rarely impacts throughput in practice for OLTP workloads
219
+
220
+ ### When to Use SERIALIZABLE
221
+
222
+ - Financial calculations where correctness is paramount
223
+ - Constraint enforcement that spans multiple rows or tables
224
+ - Any case where "check then act" patterns must be atomic
225
+ - When the alternative is complex application-level locking
226
+
227
+ ## Common Pitfalls and Surprises
228
+
229
+ ### Pitfall: Assuming READ COMMITTED Is "Safe Enough"
230
+
231
+ READ COMMITTED is safe for individual statements but not for multi-statement read-then-write patterns. Any time you SELECT a value and then use it in a subsequent UPDATE/INSERT, you have a potential race condition.
232
+
233
+ ### Pitfall: Not Handling Serialization Failures
234
+
235
+ REPEATABLE READ and SERIALIZABLE can throw:
236
+ ```
237
+ ERROR: could not serialize access due to concurrent update
238
+ SQLSTATE: 40001
239
+ ```
240
+
241
+ **This is expected behavior, not a bug.** Applications must catch and retry.
242
+
243
+ ### Pitfall: Long Transactions in REPEATABLE READ/SERIALIZABLE
244
+
245
+ The snapshot is held for the entire transaction. Long transactions:
246
+ - Prevent VACUUM from cleaning dead rows visible to the snapshot
247
+ - Increase the chance of serialization failures (more time for conflicts)
248
+ - Hold SSI dependency information longer (memory overhead)
249
+
250
+ Keep transactions short regardless of isolation level.
251
+
252
+ ### Pitfall: Mixing Isolation Levels
253
+
254
+ If Transaction A is SERIALIZABLE but Transaction B is READ COMMITTED, you only get SERIALIZABLE guarantees for A's view of the data. B never sees uncommitted intermediate states, but it can observe newer committed states between statements and produce non-serializable outcomes. For full serializable behavior, **all participating transactions** must use SERIALIZABLE.
255
+
256
+ ### Pitfall: DDL and Isolation
257
+
258
+ DDL statements (ALTER TABLE, CREATE INDEX) always acquire strong locks regardless of isolation level. They can block and be blocked by other transactions normally.
259
+
260
+ ## Choosing the Right Level
261
+
262
+ | Scenario | Recommended level | Why |
263
+ |----------|------------------|-----|
264
+ | Simple CRUD, web apps | READ COMMITTED | Default is fine; use atomic SQL for updates |
265
+ | Balance transfers, inventory | READ COMMITTED + `SELECT FOR UPDATE` | Explicit row locking prevents lost updates |
266
+ | Reports reading consistent data | REPEATABLE READ | Snapshot consistency across multiple queries |
267
+ | Multi-row constraints, write skew | SERIALIZABLE | Only level that prevents all anomalies |
268
+ | High-contention counters | READ COMMITTED + atomic UPDATE | `UPDATE x SET n = n + 1` is inherently safe |
269
+
270
+ **Default to READ COMMITTED** and escalate only when you identify a specific anomaly your application cannot tolerate.
271
+
272
+ ## Retry Patterns for Serialization Failures
273
+
274
+ ### Application-Level Retry (Recommended)
275
+
276
+ ```python
277
+ # Python example (psycopg)
278
+ import random
279
+ import time
280
+
281
+ import psycopg
282
+ from psycopg.errors import DeadlockDetected, SerializationFailure
283
+
284
+ MAX_RETRIES = 5
285
+ BASE_DELAY_SECONDS = 0.01
286
+ MAX_DELAY_SECONDS = 0.5
287
+
288
+ for attempt in range(MAX_RETRIES):
289
+ try:
290
+ # This must be a top-level transaction, not a savepoint inside one.
291
+ with conn.transaction():
292
+ conn.execute("SET TRANSACTION ISOLATION LEVEL SERIALIZABLE")
293
+ conn.execute("UPDATE accounts SET balance = balance - 100 WHERE id = 1")
294
+ conn.execute("UPDATE accounts SET balance = balance + 100 WHERE id = 2")
295
+ break # success
296
+ except (SerializationFailure, DeadlockDetected):
297
+ if attempt == MAX_RETRIES - 1:
298
+ raise # give up after max retries
299
+
300
+ # Bounded exponential backoff with jitter reduces repeated collisions.
301
+ delay = min(MAX_DELAY_SECONDS, BASE_DELAY_SECONDS * (2 ** attempt))
302
+ time.sleep(random.uniform(delay / 2, delay))
303
+ ```
304
+
305
+ ### Key Retry Rules
306
+
307
+ 1. **Retry the entire transaction** — not just the failed statement
308
+ 2. **Re-run all reads and decision-making** — transaction inputs may no longer be valid after a conflict
309
+ 3. **Use a bounded retry count** — avoid infinite retry loops
310
+ 4. **Use bounded exponential backoff with jitter** — concurrent retriers should not repeatedly collide; tune the delays for the workload
311
+ 5. **Log retries and exhaustion** — frequent retries indicate contention or transaction-design problems
312
+ 6. **SQLSTATE 40001** is the error code to catch (`serialization_failure`)
313
+ 7. **SQLSTATE 40P01** is deadlock (`deadlock_detected`) — it can be retried, but also fix inconsistent lock ordering where possible
314
+ 8. **Do not publish external side effects before commit** — messages, emails, and API calls can otherwise be duplicated by a retry
315
+
316
+ PostgreSQL requires retrying the complete transaction and warns that multiple attempts may be needed. See [Serialization Failure Handling](https://www.postgresql.org/docs/current/mvcc-serialization-failure-handling.html).
317
+
318
+ ### PL/pgSQL Procedure for the Transaction Body
319
+
320
+ A PL/pgSQL function cannot retry a complete transaction. An `EXCEPTION` block rolls back only its subtransaction; retrying the block remains inside the same top-level transaction and uses the same transaction snapshot at REPEATABLE READ or SERIALIZABLE.
321
+
322
+ A procedure can encapsulate the database work, but the application should still own the complete transaction and retry loop:
323
+
324
+ ```sql
325
+ CREATE OR REPLACE PROCEDURE transfer_funds(
326
+ p_from_id int,
327
+ p_to_id int,
328
+ p_amount numeric
329
+ )
330
+ LANGUAGE plpgsql
331
+ AS $$
332
+ BEGIN
333
+ UPDATE accounts
334
+ SET balance = balance - p_amount
335
+ WHERE id = p_from_id;
336
+
337
+ UPDATE accounts
338
+ SET balance = balance + p_amount
339
+ WHERE id = p_to_id;
340
+ END;
341
+ $$;
342
+ ```
343
+
344
+ Invoke `CALL transfer_funds(...)` inside the application-managed transaction and retry that entire transaction from the application. A serialization failure can occur at commit, so a procedure cannot reliably catch every failure and restart itself.
@@ -0,0 +1,68 @@
1
+ ---
2
+ name: progressive-disclosure
3
+ description: Structuring modular agent skills and toolsets with progressive disclosure to eliminate prompt bloat and avoid multi-agent sprawl
4
+ ---
5
+
6
+ # Progressive Disclosure & Modular Skill Architecture
7
+
8
+ ## Overview
9
+ This skill operationalizes Anthropic's guidance from *"Building agents: When to fold subagents into your main agent loop"* (October 2026) and Google's agentic engineering standards.
10
+
11
+ Defaulting to multi-agent org charts (spawning separate agents for planning, routing, and minor domain steps) introduces severe overhead:
12
+ - **3–10× Token Inflation**: Every nested subagent call duplicates system prompts and model invocations.
13
+ - **Context Degradation (The Telephone Game)**: Nuances are lost across summaries and handoffs.
14
+ - **Subagent Sprawl & The Frankenprompt**: Endless accretion of overlapping prompts that contradict one another.
15
+
16
+ **The Solution**: A **single main agent loop** powered by **Progressive Disclosure**.
17
+
18
+ ---
19
+
20
+ ## 1. The Three Layers of Progressive Disclosure
21
+
22
+ ```mermaid
23
+ flowchart TD
24
+ L1["Layer 1: Discovery Metadata (Always in Prompt)<br>• Skill Name (gerund)<br>• 1-line Description (~20 words)"]
25
+ L2["Layer 2: Procedure on Demand (Loaded when triggered)<br>• SKILL.md detailed instructions<br>• Execution steps & guardrails"]
26
+ L3["Layer 3: Auxiliary References (Loaded only if needed)<br>• templates/, scripts/, examples/<br>• Max 1 level deep"]
27
+
28
+ L1 -->|Triggered by Task| L2
29
+ L2 -->|Deep Domain Work| L3
30
+ ```
31
+
32
+ ### Layer 1: Discovery Metadata (Always Present, Ultra-Light)
33
+ - Only the YAML frontmatter `name` and `description` are loaded into the agent's baseline system prompt.
34
+ - Descriptions must be concise (<25 words) and explicitly state the trigger conditions using active gerunds (e.g., `optimizing-database-queries`, `designing-ui-components`).
35
+ - *Impact*: Cuts initial system prompt token consumption by >80%.
36
+
37
+ ### Layer 2: On-Demand Skill Instructions (`SKILL.md`)
38
+ - The agent reads `SKILL.md` only when the active task matches the skill's description.
39
+ - Detailed step-by-step algorithms, checklists, and edge-case handling reside here.
40
+
41
+ ### Layer 3: Shallow Reference Assets (`references/`, `examples/`)
42
+ - Complex reference tables, boilerplate code, or schemas are kept in separate sibling files within the skill directory.
43
+ - Keep references **exactly one level deep** directly linked from `SKILL.md`. Never build deeply nested documentation trees.
44
+
45
+ ---
46
+
47
+ ## 2. When to Fold vs. When Subagents Earn Their Place
48
+
49
+ Use this decision matrix before spawning a child subagent:
50
+
51
+ | Scenario | Architectural Choice | Reason |
52
+ | :--- | :--- | :--- |
53
+ | **Sequential domain task** (e.g., write migration, update schema, test endpoint) | **Main Agent Loop + Skill** | Single loop retains unbroken reasoning chain; 3–5× cheaper and faster. |
54
+ | **Tool-heavy workflow** (>30 tools available) | **Tool Search / Deferred Loading** | Tool discovery prevents tool hallucination without requiring child agents. |
55
+ | **Stateless Adversarial Review** | **Subagent (Goldfish)** | Invariant requires total blinding from conversational backstory ("Elephant"). |
56
+ | **Parallel Fan-out** (3+ independent test fixes or audit sweeps) | **Parallel Subagents** | Concurrent execution across isolated failure domains. |
57
+ | **Strict Security / Permission Sandbox** | **Subagent** | Subagent runs with restricted credentials or isolated read-only tools. |
58
+
59
+ ---
60
+
61
+ ## 3. Skill Authoring Checklist
62
+
63
+ When writing or refactoring any skill in `skills/`:
64
+ - [ ] **Name**: Gerund format (`writing-plans`, `diagnosing-superpowers`).
65
+ - [ ] **Description**: Concise (<25 words), stating when and why to activate.
66
+ - [ ] **No Monolithic Injections**: Large schemas or long text examples moved to `examples/` or `references/`.
67
+ - [ ] **Direct File Links**: All reference files linked via relative markdown links.
68
+ - [ ] **Clean Exit Criteria**: Explicit conditions defining when the skill procedure is complete.
@@ -0,0 +1,40 @@
1
+ ---
2
+ name: pstack-discipline
3
+ description: >
4
+ Enforce high-rigor engineering discipline from the pstack / poteto framework:
5
+ "Prove It Works", "Fix Root Causes", "Test Behavior, Not Implementation",
6
+ and "Subtract Before You Add" during orchestration and planning.
7
+ ---
8
+
9
+ # PStack Engineering Discipline
10
+
11
+ A distilled set of non-negotiable operational principles originated by Lauren Tan (@poteto) in the `pstack` framework, designed to prevent AI agents from generating unverified, shallow, or symptom-masking code.
12
+
13
+ ---
14
+
15
+ ## The 5 Core Principles
16
+
17
+ ### 1. Prove It Works
18
+ * Never assume, extrapolate, or assert that a system functions without empirical proof.
19
+ * Run terminating, non-interactive verification commands (unit tests, build checks, Playwright assertions) that actively observe behavior.
20
+ * A task is incomplete until the proof is captured.
21
+
22
+ ### 2. Fix Root Causes
23
+ * Never apply defensive guards that merely hide runtime exceptions or symptoms.
24
+ * Trace failures back to the originating boundary or state inconsistency.
25
+ * A patch that masks a crash without resolving why invalid state reached that point is a rejected regression.
26
+
27
+ ### 3. Test Behavior, Not Implementation
28
+ * Tests must exercise the system through its public boundaries exactly as a consumer or user does.
29
+ * Avoid brittle internal mocks and spy assertions that break during internal refactorings.
30
+ * If a test suite would still pass when internal functions return dummy values or no-ops, discard the test suite.
31
+
32
+ ### 4. Subtract Before You Add
33
+ * Before adding new layers, abstractions, or dependencies, evaluate what can be removed or simplified.
34
+ * Reduce reader cognitive load, shrink state scope, and eliminate dead branches first.
35
+ * The cleanest feature is one that reuses existing architecture without expanding complexity.
36
+
37
+ ### 5. Sequence Work into Verifiable Units
38
+ * Break complex tasks into small, self-contained, verifiable increments.
39
+ * Complete and verify unit $N$ before beginning unit $N+1$.
40
+ * Prevent speculative parallel diffs that fail together at integration time.
@@ -24,13 +24,12 @@ WHEN receiving code review feedback:
24
24
  6. IMPLEMENT: One item at a time, test each
25
25
  ```
26
26
 
27
- ## Forbidden Responses (Google EGM "No Glazing" Rule)
27
+ ## Forbidden Responses
28
28
 
29
29
  **NEVER:**
30
30
  - "You're absolutely right!" (explicit instruction-file violation)
31
- - "Great point!" / "Excellent feedback!" (performative flattery)
31
+ - "Great point!" / "Excellent feedback!" (performative)
32
32
  - "Let me implement that now" (before verification)
33
- - Apologies like "I apologize" / "I'm sorry" (substance over politeness)
34
33
 
35
34
  **INSTEAD:**
36
35
  - Restate the technical requirement
@@ -201,26 +200,6 @@ You understand 1,2,3,6. Unclear on 4,5.
201
200
  ✅ "Understand 1,2,3,6. Need clarification on 4 and 5 before implementing."
202
201
  ```
203
202
 
204
- ## The 5-Round Convergence Ledger (Google EGM Protocol)
205
-
206
- For Tier 2 (Architectural & High-Stakes) reviews, maintain the authoritative triage ledger across review rounds:
207
-
208
- ```markdown
209
- | ID | File:Line | Severity (Blocker/Warning/Nit) | Finding & Failure Mode | Verbatim Action / Rebuttal | Status (Open/Resolved/Rebutted) |
210
- ```
211
-
212
- ### Protocol Rules:
213
- 1. **Verbatim Action or Rebuttal Required**:
214
- - For every finding, you must either:
215
- a) Implement a verified code fix and re-run tests.
216
- b) Provide a **verbatim technical rebuttal** citing exact line numbers, architectural contracts, or test outputs that prove the reviewer's assumption does not apply.
217
- - Findings cannot be silently dropped.
218
- 2. **Convergence Loop**:
219
- - Re-request review with the updated git diff and updated ledger.
220
- - The loop continues until the Reviewer reports `"No findings"` AND all previous ledger items are settled (`Resolved` or `Rebutted`).
221
- 3. **Escalation Gate (5-Round Cap)**:
222
- - If findings remain unsettled after 5 rounds, stop and escalate immediately to the human user with the complete ledger. Never commit code with unsettled Blockers.
223
-
224
203
  ## GitHub Thread Replies
225
204
 
226
205
  When replying to inline review comments on GitHub, reply in the comment thread (`gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`), not as a top-level PR comment.
@@ -7,7 +7,7 @@ description: Use when completing tasks, implementing major features, or before m
7
7
 
8
8
  Dispatch a code reviewer subagent to catch issues before they cascade. The reviewer gets precisely crafted context for evaluation — never your session's history.
9
9
 
10
- **Core principle:** Review early, review often. Enforce the **Google Elephant-Goldfish Model (EGM)**: the reviewer operates as an isolated, stateless **Goldfish** that evaluates raw code artifacts without being polluted by author debates or conversational rationalizations.
10
+ **Core principle:** Review early, review often.
11
11
 
12
12
  ## When to Request Review
13
13
 
@@ -21,46 +21,17 @@ Dispatch a code reviewer subagent to catch issues before they cascade. The revie
21
21
  - Before refactoring (baseline check)
22
22
  - After fixing complex bug
23
23
 
24
- ## Two-Tier Review Trigger
24
+ ## How to Request
25
25
 
26
- - **Tier 1 (Bounded & Routine Tasks)**: Single-pass adversarial critique targeting edge cases, type safety, missing tests, and anti-slop hygiene.
27
- - **Tier 2 (Architectural & High-Stakes Tasks)**: Mandatory **5-round convergence loop** with a structured findings ledger.
28
-
29
- ## Adaptive Execution Ladder (Cross-Model Bridge vs. Same-Model Fallback)
30
-
31
- When dispatching the Goldfish reviewer:
32
- 1. **Check for Multi-Model Bridges**:
33
- Inspect if shared bridges exist in `C:\Apps\tools\` or PATH:
34
- - For Claude sessions: check for `gemini-bridge.ps1` or `codex-bridge.ps1`.
35
- - For Gemini sessions: check for `claude-bridge.ps1` or `codex-bridge.ps1`.
36
- - For Codex sessions: check for `claude-bridge.ps1` or `gemini-bridge.ps1`.
37
- 2. **If Bridge & API Credentials Present**:
38
- Execute the cross-model validator:
39
- ```powershell
40
- powershell -File C:/Apps/tools/gemini-bridge.ps1 review -Model "Gemini 3.8 Flash" -Effort "high"
41
- ```
42
- 3. **If Bridges Absent (Graceful Fallback)**:
43
- Spawn a fresh child subagent on the **same model / native harness** (e.g., `invoke_subagent` in Antigravity, Agent tool in Claude Code) with zero parent conversation context. The stateless Goldfish discipline is strictly preserved.
44
-
45
- ## How to Request (The Blinded Packet Builder)
46
-
47
- **1. Get git SHAs and Diff:**
26
+ **1. Get git SHAs:**
48
27
  ```bash
49
28
  BASE_SHA=$(git rev-parse HEAD~1) # or: git merge-base origin/main HEAD
50
29
  HEAD_SHA=$(git rev-parse HEAD)
51
- git diff $BASE_SHA..$HEAD_SHA
52
30
  ```
53
31
 
54
- **2. Assemble the Blinded Packet:**
55
- - Strip conversational history, justifications, and author debates.
56
- - Hand the reviewer ONLY:
57
- - `{DESCRIPTION}`: Brief, objective summary of the change.
58
- - `{PLAN_OR_REQUIREMENTS}`: Explicit acceptance criteria.
59
- - `{DIFF}`: Raw git diff and touched source files.
60
-
61
- **3. Dispatch code reviewer subagent:**
32
+ **2. Dispatch code reviewer subagent:**
62
33
 
63
- Dispatch a `general-purpose` or `reviewer` subagent, filling the template at [code-reviewer.md](code-reviewer.md).
34
+ Dispatch a `general-purpose` subagent, filling the template at [code-reviewer.md](code-reviewer.md)
64
35
 
65
36
  **Placeholders:**
66
37
  - `{DESCRIPTION}` - Brief summary of what you built
@@ -68,7 +39,7 @@ Dispatch a `general-purpose` or `reviewer` subagent, filling the template at [co
68
39
  - `{BASE_SHA}` - Starting commit
69
40
  - `{HEAD_SHA}` - Ending commit
70
41
 
71
- **4. Act on feedback:**
42
+ **3. Act on feedback:**
72
43
  - Fix Critical issues immediately
73
44
  - Fix Important issues before proceeding
74
45
  - Note Minor issues for later
@@ -81,7 +52,7 @@ Dispatch a `general-purpose` or `reviewer` subagent, filling the template at [co
81
52
 
82
53
  You: Let me request code review before proceeding.
83
54
 
84
- BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
55
+ BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | cut -d' ' -f1)
85
56
  HEAD_SHA=$(git rev-parse HEAD)
86
57
 
87
58
  [Dispatch code reviewer subagent]