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.
- package/README.md +57 -26
- package/README.pt-BR.md +443 -0
- package/agents/cloud-engineer.md +77 -0
- package/agents/code-sentinel.md +71 -34
- package/agents/database-architect.md +31 -25
- package/agents/frontend-designer.md +30 -28
- package/agents/mobile-designer.md +25 -24
- package/agents/modernizer.md +68 -0
- package/agents/orchestrator.md +107 -93
- package/agents/reviewer.md +102 -71
- package/agents/security-auditor.md +27 -27
- package/agents/tester.md +97 -90
- package/commands/grill-me.md +20 -4
- package/commands/orchestrate.md +16 -0
- package/commands/orchestrator.md +16 -0
- package/commands/plan.md +17 -1
- package/config/agents.json +31 -3
- package/config/mcp.json +72 -0
- package/config/models.json +26 -16
- package/config/profiles.json +2 -4
- package/config/skills.json +762 -573
- package/docs/SKILLS.md +393 -275
- package/docs/designs/old/2026-10-31 plan-lifecycle-backlog-and-clean-code-skill.md +87 -0
- package/docs/designs/old/2026-11-02 skill-upstream-audit-and-update.md +105 -0
- package/docs/designs/old/2026-11-05 communication-doctrine-bluf-ste.md +94 -0
- package/docs/designs/old/2026-11-06-cloud-engineer-and-resilience-synthesis.md +67 -0
- package/docs/designs/old/2026-11-06-herdr-native-agent-orchestration.md +45 -0
- package/docs/runs/skill-audit/2026-11-12-compare-report.json +1028 -0
- package/docs/runs/skill-audit/2026-11-12-upstream-audit.json +275 -0
- package/docs/runs/skill-audit/add_progressive_disclosure.cjs +30 -0
- package/docs/runs/skill-audit/check_heimdall_skills.ps1 +9 -0
- package/docs/runs/skill-audit/compare_classics.ps1 +26 -0
- package/docs/runs/skill-audit/compare_taste.ps1 +12 -0
- package/docs/runs/skill-audit/customization-report.json +380 -0
- package/docs/runs/skill-audit/diff_pending_skills.cjs +94 -0
- package/docs/runs/skill-audit/fetch_and_apply_skill.cjs +58 -0
- package/docs/runs/skill-audit/fetch_and_apply_taste_v2.cjs +65 -0
- package/docs/runs/skill-audit/inspect_pending_skills.cjs +71 -0
- package/docs/runs/skill-audit/inventory.json +308 -0
- package/docs/runs/skill-audit/list_local_taste.ps1 +1 -0
- package/docs/runs/skill-audit/phase5-update-plan.json +595 -0
- package/docs/runs/skill-audit/phase5-update-plan.md +138 -0
- package/docs/runs/skill-audit/probe.ps1 +16 -0
- package/docs/runs/skill-audit/probe_classics_branches.ps1 +3 -0
- package/docs/runs/skill-audit/probe_commits.ps1 +15 -0
- package/docs/runs/skill-audit/probe_repos.ps1 +17 -0
- package/docs/runs/skill-audit/probe_sentry_sec.ps1 +3 -0
- package/docs/runs/skill-audit/probe_sentry_sweep.ps1 +5 -0
- package/docs/runs/skill-audit/probe_snyk.ps1 +3 -0
- package/docs/runs/skill-audit/probe_snyk_recipes.ps1 +5 -0
- package/docs/runs/skill-audit/probe_taste_branches.ps1 +8 -0
- package/docs/runs/skill-audit/probe_taste_v19.ps1 +3 -0
- package/docs/runs/skill-audit/probe_user_repos.ps1 +19 -0
- package/docs/runs/skill-audit/prune_taste_skills.cjs +22 -0
- package/docs/runs/skill-audit/run_phase1_2.cjs +142 -0
- package/docs/runs/skill-audit/run_phase6_verification.cjs +107 -0
- package/docs/runs/skill-audit/show_16_details.ps1 +25 -0
- package/docs/runs/skill-audit/show_20_skills.ps1 +28 -0
- package/docs/runs/skill-audit/show_classics_diff.cjs +37 -0
- package/docs/runs/skill-audit/sync_agent_markdowns.cjs +30 -0
- package/docs/runs/skill-audit/taste-skill-upstream.md +542 -0
- package/docs/runs/skill-audit/update-manifest.md +88 -0
- package/docs/runs/skill-audit/update_config_skills.cjs +52 -0
- package/docs/runs/skill-audit/update_registry_phase7.cjs +83 -0
- package/docs/runs/skill-audit/upstream-status.json +563 -0
- package/docs/runs/skill-audit/verification-results.json +252 -0
- package/doctrine/AGENTS.md +42 -77
- package/hooks/git/pre-commit +11 -0
- package/hooks/heimdall-hook.cjs +81 -2
- package/hooks/herdr-agent-state.ps1 +55 -0
- package/hooks/hooks.json +0 -11
- package/lib/catalog-sync.cjs +167 -0
- package/lib/hermes-context.cjs +57 -0
- package/lib/model-context.cjs +123 -0
- package/lib/path-discovery.cjs +94 -0
- package/package.json +7 -3
- package/playbooks/01-interactive-grilling-gate.md +23 -6
- package/playbooks/02-fast-code-deep-verification.md +3 -2
- package/playbooks/03-adversarial-code-review.md +15 -7
- package/playbooks/05-canonical-plan-template.md +35 -19
- package/playbooks/06-model-registry-matrix.md +24 -13
- package/playbooks/07-legacy-code-modernization.md +74 -0
- package/playbooks/08-backlog-and-change-request-flow.md +122 -0
- package/setup.mjs +592 -172
- package/skills/antislop/SKILL.md +76 -56
- package/skills/antislop/VERSION +1 -0
- package/skills/antislop-copywriting/SKILL.md +407 -372
- package/skills/antislop-human/LICENSE-web-quality-skills +21 -0
- package/skills/antislop-human/SKILL.md +204 -147
- package/skills/antislop-human/contrast-check.py +168 -165
- package/skills/antislop-human/contrast-mcp.py +6 -3
- package/skills/antislop-human/references/A11Y-PATTERNS.md +249 -0
- package/skills/antislop-human/references/WCAG.md +127 -0
- package/skills/antislop-ui/LICENSE-web-quality-skills +21 -0
- package/skills/antislop-ui/SKILL.md +344 -304
- package/skills/antislop-ui/references/CORE-WEB-VITALS.md +181 -0
- package/skills/antislop-ui/references/WEB-BASELINE.md +28 -0
- package/skills/brainstorming/SKILL.md +296 -265
- package/skills/brainstorming/builder-check-prompt.md +23 -0
- package/skills/brainstorming/scripts/frame-template.html +213 -213
- package/skills/brainstorming/scripts/server.cjs +723 -723
- package/skills/brandkit/SKILL.md +798 -798
- package/skills/brutalist-skill/SKILL.md +93 -92
- package/skills/caveman/README.md +68 -0
- package/skills/caveman/SKILL.md +73 -38
- package/skills/claude-collaborator/SKILL.md +24 -44
- package/skills/clean-code/SKILL.md +152 -0
- package/skills/cloudflare-security-audit/AI-AND-LLM.md +83 -83
- package/skills/cloudflare-security-audit/ATTACK-CLASSES.md +130 -130
- package/skills/cloudflare-security-audit/CLIENT-SIDE.md +83 -83
- package/skills/cloudflare-security-audit/CLOUD-AND-DEPLOYMENT.md +86 -86
- package/skills/cloudflare-security-audit/DATA-ISOLATION-AND-LIFECYCLE.md +84 -84
- package/skills/cloudflare-security-audit/DESKTOP-MOBILE-AND-LOCAL-IPC.md +89 -89
- package/skills/cloudflare-security-audit/HUNTING.md +251 -251
- package/skills/cloudflare-security-audit/MEMORY-SAFETY-AND-BINARY.md +101 -101
- package/skills/cloudflare-security-audit/PROTOCOLS-RPC-AND-MESSAGING.md +81 -81
- package/skills/cloudflare-security-audit/RECONNAISSANCE.md +156 -156
- package/skills/cloudflare-security-audit/RESOURCE-EXHAUSTION-AND-AVAILABILITY.md +78 -78
- package/skills/cloudflare-security-audit/SKILL.md +192 -192
- package/skills/cloudflare-security-audit/SUPPLY-CHAIN-AND-RELEASE.md +73 -73
- package/skills/cloudflare-security-audit/VALIDATION-AND-REPORTING.md +186 -186
- package/skills/cloudflare-security-audit/WEB-PROTOCOL-AND-AUTH.md +105 -105
- package/skills/cloudflare-security-audit/report-schema.json +461 -461
- package/skills/cloudflare-security-audit/validate-coverage-ledger.cjs +872 -872
- package/skills/cloudflare-security-audit/validate-coverage-ledger.test.cjs +740 -740
- package/skills/cloudflare-security-audit/validate-findings.cjs +773 -773
- package/skills/cloudflare-security-audit/validate-findings.test.cjs +652 -652
- package/skills/codebase-design/DEEPENING.md +37 -0
- package/skills/codebase-design/DESIGN-IT-TWICE.md +44 -0
- package/skills/codebase-design/SKILL.md +114 -0
- package/skills/codex-collaborator/SKILL.md +24 -45
- package/skills/communication-doctrine/SKILL.md +89 -0
- package/skills/diagnosing-superpowers/SKILL.md +1 -1
- package/skills/diagnosing-superpowers/references/github-issues.md +3 -3
- package/skills/diagnosing-superpowers/templates/issue.md +23 -4
- package/skills/domain-modeling/ADR-FORMAT.md +47 -0
- package/skills/domain-modeling/GLOSSARY-FORMAT.md +60 -0
- package/skills/domain-modeling/SKILL.md +74 -0
- package/skills/executing-plans/SKILL.md +6 -56
- package/skills/executing-plans/scripts/task-done +52 -52
- package/skills/executing-plans/scripts/task-start +28 -28
- package/skills/gemini-collaborator/SKILL.md +24 -56
- package/skills/grill-me/SKILL.md +65 -0
- package/skills/handoff/SKILL.md +64 -0
- package/skills/herdr/SKILL.md +243 -0
- package/skills/image-to-code-skill/SKILL.md +1228 -1228
- package/skills/imagegen-frontend-mobile/SKILL.md +1465 -1465
- package/skills/imagegen-frontend-web/SKILL.md +987 -987
- package/skills/improve-codebase-architecture/HTML-REPORT.md +123 -0
- package/skills/improve-codebase-architecture/SKILL.md +71 -0
- package/skills/karpathy-guidelines/SKILL.md +67 -67
- package/skills/mcp-engineering/SKILL.md +74 -0
- package/skills/minimalist-skill/SKILL.md +87 -85
- package/skills/output-skill/SKILL.md +49 -49
- package/skills/owasp-security/reference/config-and-supply-chain.md +346 -344
- package/skills/owasp-security/reference/languages.md +378 -372
- package/skills/owasp-security/reference/owasp-report.md +1144 -1140
- package/skills/owasp-security/reference/review-checklist.md +134 -132
- package/skills/ponytail/SKILL.md +36 -52
- package/skills/postgres-best-practices/SKILL.md +30 -52
- package/skills/postgres-best-practices/references/backup-restore.md +372 -0
- package/skills/postgres-best-practices/references/bulk-loading.md +315 -0
- package/skills/postgres-best-practices/references/connection-pooling.md +310 -0
- package/skills/postgres-best-practices/references/hot-standby.md +221 -0
- package/skills/postgres-best-practices/references/indexing.md +318 -0
- package/skills/postgres-best-practices/references/logical-replication.md +610 -0
- package/skills/postgres-best-practices/references/major-version-upgrades.md +334 -0
- package/skills/postgres-best-practices/references/performance-diagnostics.md +553 -0
- package/skills/postgres-best-practices/references/query-optimization.md +294 -0
- package/skills/postgres-best-practices/references/query-patterns.md +566 -0
- package/skills/postgres-best-practices/references/schema-design.md +362 -0
- package/skills/postgres-best-practices/references/security-roles.md +489 -0
- package/skills/postgres-best-practices/references/transaction-isolation.md +344 -0
- package/skills/progressive-disclosure/SKILL.md +68 -0
- package/skills/pstack-discipline/SKILL.md +40 -0
- package/skills/receiving-code-review/SKILL.md +2 -23
- package/skills/requesting-code-review/SKILL.md +7 -36
- package/skills/soft-skill/SKILL.md +99 -98
- package/skills/stitch-skill/DESIGN.md +121 -121
- package/skills/stitch-skill/SKILL.md +185 -184
- package/skills/strix-security/SKILL.md +54 -53
- package/skills/subagent-driven-development/SKILL.md +35 -264
- package/skills/subagent-driven-development/references/batching.md +11 -0
- package/skills/subagent-driven-development/references/cannot-verify.md +10 -0
- package/skills/subagent-driven-development/references/final-review.md +47 -0
- package/skills/subagent-driven-development/references/fix-loop.md +77 -0
- package/skills/subagent-driven-development/references/handling-reports.md +15 -0
- package/skills/subagent-driven-development/references/preflight.md +26 -0
- package/skills/subagent-driven-development/references/resuming.md +12 -0
- package/skills/subagent-driven-development/scripts/review-package +53 -53
- package/skills/subagent-driven-development/scripts/sdd-workspace +87 -82
- package/skills/subagent-driven-development/scripts/task-brief +43 -43
- package/skills/systematic-debugging/SKILL.md +283 -306
- package/skills/taste-skill/SKILL.md +542 -1206
- package/skills/taste-skill/references/app-screens.md +1199 -0
- package/skills/taste-skill/references/colour.md +141 -0
- package/skills/taste-skill/references/copy.md +177 -0
- package/skills/taste-skill/references/critique.md +182 -0
- package/skills/taste-skill/references/imagery.md +791 -0
- package/skills/taste-skill/references/layout.md +292 -0
- package/skills/taste-skill/references/motion.md +980 -0
- package/skills/taste-skill/references/research.md +356 -0
- package/skills/taste-skill/references/scenes.md +174 -0
- package/skills/taste-skill/references/tells.md +115 -0
- package/skills/taste-skill/references/type.md +170 -0
- package/skills/test-driven-development/SKILL.md +330 -337
- package/skills/thermo/SKILL.md +67 -0
- package/skills/threat-modeling/SKILL.md +55 -0
- package/skills/to-spec/SKILL.md +75 -0
- package/skills/to-tickets/SKILL.md +105 -0
- package/skills/trailofbits-audit-context/SKILL.md +72 -72
- package/skills/trailofbits-insecure-defaults/commands/audit.md +35 -0
- package/skills/trailofbits-insecure-defaults/references/debug-features.json +13 -13
- package/skills/trailofbits-insecure-defaults/references/debug-features.md +75 -75
- package/skills/trailofbits-insecure-defaults/references/default-credentials.json +12 -12
- package/skills/trailofbits-insecure-defaults/references/default-credentials.md +76 -76
- package/skills/trailofbits-insecure-defaults/references/fail-open-security.json +11 -11
- package/skills/trailofbits-insecure-defaults/references/fail-open-security.md +70 -70
- package/skills/trailofbits-insecure-defaults/references/fallback-secrets.json +11 -11
- package/skills/trailofbits-insecure-defaults/references/fallback-secrets.md +70 -70
- package/skills/trailofbits-insecure-defaults/references/permissive-access.json +13 -13
- package/skills/trailofbits-insecure-defaults/references/permissive-access.md +62 -62
- package/skills/trailofbits-insecure-defaults/references/weak-crypto.json +13 -13
- package/skills/trailofbits-insecure-defaults/references/weak-crypto.md +71 -71
- package/skills/trailofbits-triage-brocards/SKILL.md +208 -208
- package/skills/verification-before-completion/SKILL.md +0 -14
- package/skills/wayfinder/SKILL.md +128 -0
- package/skills/writing-plans/SKILL.md +11 -15
- package/skills/writing-skills/SKILL.md +21 -303
- package/skills/writing-skills/references/CLAUDE_MD_TESTING.md +189 -0
- package/skills/writing-skills/references/anthropic-best-practices.md +1150 -0
- package/skills/writing-skills/references/bulletproofing.md +80 -0
- package/skills/writing-skills/references/discovery.md +201 -0
- package/skills/writing-skills/references/flowcharts.md +37 -0
- package/skills/writing-skills/references/graphviz-conventions.dot +172 -0
- package/skills/writing-skills/references/persuasion-principles.md +187 -0
- package/skills/writing-skills/references/testing-skills-with-subagents.md +384 -0
- package/tools/{claude-bridge.ps1 → archive/claude-bridge.ps1} +10 -7
- package/tools/{codex-bridge.ps1 → archive/codex-bridge.ps1} +1 -1
- package/tools/{gemini-bridge.ps1 → archive/gemini-bridge.ps1} +12 -19
- package/skills/gpt-tasteskill/SKILL.md +0 -74
- package/skills/taste-skill-v1/SKILL.md +0 -226
- /package/tools/{claude-bridge.cmd → archive/claude-bridge.cmd} +0 -0
- /package/tools/{claude-bridge.sh → archive/claude-bridge.sh} +0 -0
- /package/tools/{codex-bridge.cmd → archive/codex-bridge.cmd} +0 -0
- /package/tools/{codex-bridge.sh → archive/codex-bridge.sh} +0 -0
- /package/tools/{codexcli-bridge.cmd → archive/codexcli-bridge.cmd} +0 -0
- /package/tools/{codexcli-bridge.ps1 → archive/codexcli-bridge.ps1} +0 -0
- /package/tools/{gemini-bridge.cmd → archive/gemini-bridge.cmd} +0 -0
- /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
|
|
27
|
+
## Forbidden Responses
|
|
28
28
|
|
|
29
29
|
**NEVER:**
|
|
30
30
|
- "You're absolutely right!" (explicit instruction-file violation)
|
|
31
|
-
- "Great point!" / "Excellent feedback!" (performative
|
|
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.
|
|
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
|
-
##
|
|
24
|
+
## How to Request
|
|
25
25
|
|
|
26
|
-
|
|
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.
|
|
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`
|
|
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
|
-
**
|
|
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 |
|
|
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]
|