!4437odin/claude-code-skills → developc4fbbb9004

Claude Code skills audit + edit hooks

AI-generatedEverything on this page was written by an AI agent from the diff: the summaries, the narration, the diagrams, the flags and the glossary. It can be wrong or incomplete, so check it against the code before you rely on it.

2commits
38files
2.1klines changed
1.8klines to read
8new skills
2edit hooks
0Go / proto lines

Where the diff is

5-minute explainer

What changed

One shape per skill

Short SKILL.md workflow, references/ on demand, 3 evals each.

SKILL.mdreferences/*.mdevals/evals.json

Eight new skills

Query, handlers, memos, mimir, mocknet, upgrades, regtest, simulation.

api-endpointhandler-developmentmemo-parsermimir-parametermocknet-debugprotocol-upgraderegression-testsimulation-test

No version gates

Changes ship ungated; app.ThorchainKeeper is 0.0.0, so its gates never fire.

version.GTE gateedit in placekeeper version 0.0.0state → migration

Stale claims removed

Fake memo prefixes, admin mimir, constants_v3.go, STAGES= dropped.

  • a: · $+ · loan+ not in stringToTxTypeMap
  • no admin mimir tier
  • TEST_SIMULATION_STAGES, not STAGES

pre-edit.sh blocks generated files

Exit 2 refuses edits to *.pb.go, pulsar, openapi/gen, regtest mnt.

Edit/Writepre-edit.shexit 2 → Claude

post-edit.sh formats and lints

goimports, proto/openapi regen, go mod tidy, trunk; failures exit 2.

*.go → goimports*.proto → proto-gengo.mod → tidyother → trunk

Wiring + lint scope

settings.json wires both hooks; trunk ignores markdownlint on skills.

PreToolUse Edit|WritePostToolUse 300 smarkdownlint ignored

Evals

Three prompt + assertion evals per new skill; not run in CI.

promptexpected_outputassertions

Look here first

Each .proto edit regenerates all protos in Dockerproto-gen runs as root via docker, rm -rf api/ and recreates it, and clang-formats every proto; needs buf network access.post-edit.sh:17 ↗verify
8+has() { command -v "$1" >/dev/null; }
9+
10+out=""
11+case "$f" in
12+*.go)
13+ if has goimports; then out=$(goimports -w "$f" 2>&1); fi
14+ ;;
15+*.proto)
16+ if has docker; then
17+ out=$(make proto-format proto-gen 2>&1) && out="" || out="make proto-format proto-gen failed:"$'\n'"$(tail -20 <<<"$out")"
18+ fi
19+ ;;
20+*/openapi/*.yaml | */openapi/*.yml)
21+ if has docker; then
22+ out=$(make openapi 2>&1) && out="" || out="make openapi failed:"$'\n'"$(tail -20 <<<"$out")"
23+ fi
24+ ;;
25+*/go.mod)
26+ out=$( (cd "$(dirname "$f")" && go mod tidy) 2>&1) && out=""
27+ ;;
28+*.gitlab-ci.yml)
29+ if has glab; then out=$(glab ci lint "$f" 2>&1) && out=""; fi
30+ ;;
HALT/PAUSE rule ignores two economic exceptionsIsOperationalMimir returns false for NodePauseChainBlocks and PauseOnSlashThreshold first; the blanket rule misclassifies their vote threshold.SKILL.md:68 ↗verify
59+ the "implicitly-0" comment if it has a nonzero default.
60+2. Add the default to `NewConstantValue()` in constants/constants_v1.go.
61+3. Run `make go-generate` to regenerate constants/constantname_string.go. Commit
62+ the generated file. CI's `generate` job fails on a diff.
63+4. Read it with `k.GetConfigInt64(ctx, constants.YourName)`. Don't read the
64+ constant directly, or the mimir override is ignored.
65+5. Decide the class. If it must react fast (a halt, pause or operational
66+ toggle), either name it so `IsOperationalMimir` matches or add it to the
67+ exact-match list, and add a case to keeper_mimir_test.go. Remember that any key
68+ containing `HALT` or `PAUSE` is operational automatically.
69+6. If a bad value could break consensus or drain funds, add validation in
70+ `MimirHandler.validate` (like the `SLIPMINBPS` and `REVSHARE-` checks), and
71+ clamp at the read site.
72+7. Document it in docs/mimir.md.
73+8. Do not gate on version. Defaults and new behaviour ship ungated.
74+
75+## Add a template key
76+
77+1. Add `MimirTemplate<Name> = "<Prefix>-%s"` to constants/mimir_strings.go, with
78+ a comment saying what fills `%s`.
79+2. Read it with `k.GetMimirWithRef(ctx, constants.MimirTemplate<Name>, chain.String())`.
80+ For assets, pass `asset.MimirString()`.
81+3. Keep the expanded key within `^[a-zA-Z0-9-]+$` and 128 chars.
Block list misses some generated filesconstants/constantname_string.go (stringer), utxo *_gen.go and tron protoc output stay editable; match the 'Code generated' header instead.pre-edit.sh:5 ↗careful
1+#!/usr/bin/env bash
2+# PreToolUse(Edit|Write): refuse edits to generated files. Exit 2 sends stderr back to Claude.
3+f=$(jq -r '.tool_input.file_path // empty')
4+case "$f" in
5+*.pb.go | *.pb.gw.go | *.pulsar.go | */openapi/gen/* | */test/regression/mnt/*)
6+ echo "Blocked: $f is generated. Edit the source (.proto, openapi/openapi.yaml, regression suite) and regenerate." >&2
7+ exit 2
8+ ;;
9+esac
10+exit 0
Uses global trunk, repo ships ./scripts/trunkmake lint calls ./scripts/trunk; without trunk on PATH every non-Go check is skipped silently.post-edit.sh:35 ↗careful
26+ out=$( (cd "$(dirname "$f")" && go mod tidy) 2>&1) && out=""
27+ ;;
28+*.gitlab-ci.yml)
29+ if has glab; then out=$(glab ci lint "$f" 2>&1) && out=""; fi
30+ ;;
31+esac
32+
33+# trunk runs the same formatters and linters as CI (prettier, markdownlint, yamllint, shellcheck, shfmt, ...).
34+# Go is skipped here: golangci-lint per edit is too slow; CI and `make lint` cover it.
35+if [[ $f != *.go ]] && has trunk; then
36+ trunk fmt "$f" >/dev/null 2>&1
37+ chk=$(trunk check --no-fix --no-progress --color=false "$f" 2>&1) || out+=$'\n'"$chk"
38+fi
39+
40+if [ -n "${out//[[:space:]]/}" ]; then
41+ perl -pe 's/\e\[[0-9;]*m//g' <<<"$out" >&2
42+ exit 2
43+fi
44+exit 0
go mod tidy runs on every go.mod editRewrites go.mod/go.sum over the network; no 'has go' guard; fails (exit 2) where private tss-lib is unreachable.post-edit.sh:26 ↗careful
17+ out=$(make proto-format proto-gen 2>&1) && out="" || out="make proto-format proto-gen failed:"$'\n'"$(tail -20 <<<"$out")"
18+ fi
19+ ;;
20+*/openapi/*.yaml | */openapi/*.yml)
21+ if has docker; then
22+ out=$(make openapi 2>&1) && out="" || out="make openapi failed:"$'\n'"$(tail -20 <<<"$out")"
23+ fi
24+ ;;
25+*/go.mod)
26+ out=$( (cd "$(dirname "$f")" && go mod tidy) 2>&1) && out=""
27+ ;;
28+*.gitlab-ci.yml)
29+ if has glab; then out=$(glab ci lint "$f" 2>&1) && out=""; fi
30+ ;;
31+esac
32+
33+# trunk runs the same formatters and linters as CI (prettier, markdownlint, yamllint, shellcheck, shfmt, ...).
34+# Go is skipped here: golangci-lint per edit is too slow; CI and `make lint` cover it.
35+if [[ $f != *.go ]] && has trunk; then
36+ trunk fmt "$f" >/dev/null 2>&1
37+ chk=$(trunk check --no-fix --no-progress --color=false "$f" 2>&1) || out+=$'\n'"$chk"
38+fi
39+
Commands run in CLAUDE_PROJECT_DIR, not file's checkoutIf a worktree nested under the project is edited, make targets run in the main checkout. Unverified how Claude Code sets the variable there.post-edit.sh:7 ↗careful
1+#!/usr/bin/env bash
2+# PostToolUse(Edit|Write): format, regenerate, and lint the edited file.
3+# Problems go to stderr with exit 2 so Claude sees them; missing tools are skipped silently.
4+f=$(jq -r '.tool_input.file_path // empty')
5+[ -n "$f" ] && [ -f "$f" ] || exit 0
6+[[ $f == "$CLAUDE_PROJECT_DIR"/* ]] || exit 0
7+cd "$CLAUDE_PROJECT_DIR" || exit 0
8+has() { command -v "$1" >/dev/null; }
9+
10+out=""
11+case "$f" in
12+*.go)
13+ if has goimports; then out=$(goimports -w "$f" 2>&1); fi
14+ ;;
15+*.proto)
16+ if has docker; then
17+ out=$(make proto-format proto-gen 2>&1) && out="" || out="make proto-format proto-gen failed:"$'\n'"$(tail -20 <<<"$out")"
18+ fi
19+ ;;
20+*/openapi/*.yaml | */openapi/*.yml)
Upgrades-list advice vs in-code commentSkill calls pinning NewUpgrade("<new>") repo practice; app/upgrades.go says add nothing for consensus releases. Both register the name.SKILL.md:32 ↗careful
23+- `grep -rn 'semver.MustParse' x/thorchain --include='*.go' | grep -v _test` returns no feature gates; consensus fixes have shipped ungated since validator-scheduled upgrades replaced in-band version switching.
24+- `app.ThorchainKeeper` is built with a hard-coded `0.0.0` (`x/thorchain/keeper/v1/keeper.go:164`); `GetXManager(_ semver.Version, ...)` factories and `constants.GetConstantValues(_ semver.Version)` ignore their argument. A gate would either never fire or be dead code.
25+- What is still version-aware: `module.go` `BeginBlock` panics with "Unsupported Version: update your binary" when the network's lowest active node version (major/minor) is ahead of `constants.SWVersion`, and validator churn compares node versions (`manager_validator_current.go`). Neither is a feature switch.
26+- If old state must look different under new code, write a store migration. If a parameter should be tunable, use mimir (`mimir-parameter`).
27+
28+## 1. Consensus-breaking release
29+
30+1. Bump the root `version` file (e.g. `3.20.0` -> `3.21.0`). It feeds `constants.Version` / `SWVersion` via Makefile ldflags; there is no `version/version.go`.
31+2. Bump `version:` in `openapi/openapi.yaml` to match (and regenerate `openapi/gen`). `scripts/lint.sh` fails otherwise.
32+3. `app/upgrades.go` `Upgrades`: the upgrade name validators will propose must be registered. Either leave the list empty (then `RegisterUpgradeHandlers` auto-registers `standard.NewUpgrade(app.Version())`) or set it to `standard.NewUpgrade("<new version>")` (repo practice, e.g. `ab9e9b3e6`). **Gotcha:** if the list is non-empty, nothing is auto-appended - a stale `standard.NewUpgrade("<old>")` left from a patch release means no handler for the new name and the chain panics at the upgrade height.
33+4. If state must change, bump `ConsensusVersion()` and add a migration ([section 2](#2-store-migration)).
34+5. Every upgrade handler runs `keeperv1.UpdateActiveValidatorVersions` before `mm.RunMigrations` (`app/upgrades/standard/upgrades.go`). Custom handlers must do the same or the chain cannot resume.
35+6. On-chain flow (for reference): `MsgProposeUpgrade` / `MsgApproveUpgrade` / `MsgRejectUpgrade` (`x/thorchain/handler_upgrade.go`; CLI subcommands `propose-upgrade [name] [height]`, `approve-upgrade [name]`, `reject-upgrade [name]` in `x/thorchain/client/cli/tx.go`). `UpgradeApprovedByMajority` (`keeper/v1/keeper_upgrade.go`) needs 2/3 of active validators; `scheduleUpgradeIfNecessary` then schedules the x/upgrade plan.
36+
37+## 2. Store migration
38+
39+Runs once inside the x/upgrade handler at the upgrade height. Steps (detail and footguns in `references/migrations.md`):
40+
41+1. Bump `func (AppModule) ConsensusVersion()` in `x/thorchain/module.go` (read the current value; do not trust a copied number).
42+2. `cfg.RegisterMigration(types.ModuleName, <N>, m.Migrate<N>to<N+1>)` in `AppModule.RegisterServices` (same file).
43+3. Implement `Migrate<N>to<N+1>` for **every** build tag: either once in untagged `migrations_common.go`, or in each of `migrations.go` (mocknet / default), `migrations_mainnet.go`, `migrations_stagenet.go`, `migrations_chainnet.go`. A missing tag fails only that network's build.
44+4. Start with `m.mgr.LoadManagerIfNecessary(ctx)` - migrations run before `BeginBlock`.
45+5. Mainnet data fixes: wrap in a run/apply pair (`runDonationMigration` / `applyDonationMigration` in `migration_19to20.go`) so drift soft-skips and logs instead of halting the upgrade.
goimports, but make lint enforces gofumptscripts/lint.sh fails on gofumpt -l output that goimports leaves behind.post-edit.sh:13 ↗look
4+f=$(jq -r '.tool_input.file_path // empty')
5+[ -n "$f" ] && [ -f "$f" ] || exit 0
6+[[ $f == "$CLAUDE_PROJECT_DIR"/* ]] || exit 0
7+cd "$CLAUDE_PROJECT_DIR" || exit 0
8+has() { command -v "$1" >/dev/null; }
9+
10+out=""
11+case "$f" in
12+*.go)
13+ if has goimports; then out=$(goimports -w "$f" 2>&1); fi
14+ ;;
15+*.proto)
16+ if has docker; then
17+ out=$(make proto-format proto-gen 2>&1) && out="" || out="make proto-format proto-gen failed:"$'\n'"$(tail -20 <<<"$out")"
18+ fi
19+ ;;
20+*/openapi/*.yaml | */openapi/*.yml)
21+ if has docker; then
22+ out=$(make openapi 2>&1) && out="" || out="make openapi failed:"$'\n'"$(tail -20 <<<"$out")"
23+ fi
24+ ;;
25+*/go.mod)
26+ out=$( (cd "$(dirname "$f")" && go mod tidy) 2>&1) && out=""
markdownlint ignored for all skill docsCommit calls it scoping, but it is an ignore: off for every .claude/skills file, in CI and in the hook.trunk.yaml:50 ↗look
4141 - yamllint
4242 paths:
4343 - test/fixtures/endpoints/auth/accounts/malformed.json
4444 - test/regression/README.md
4545 - test/regression/mnt/exports/**
4646 - test/regression/mnt/blocks/**
4747 - test/regression/suites/**
4848 - test/regression/templates/**
49+- linters:
50+ - markdownlint
51+ paths:
52+ - .claude/skills/**
4953 - linters:
5054 - hadolint
5155 - terrascan
5256 paths:
5357 - ci/Dockerfile.regtest.dockerignore
5458 - ci/Dockerfile.simtest.dockerignore
5559 - linters:
5660 - codespell
5761 paths:
5862 - bifrost/pkg/chainclients/gaia/test-data/*.json
5963 - bifrost/oracle/providers/mock/data/*.json
NewDummyMgr secured/stable managers are not realOnly NewDummyMgrWithKeeper builds real secured-asset and stable-reserve managers; NewDummyMgr leaves securedMgr nil.managers.md:46 ↗look
37+| 4 | `GetXManager(_ semver.Version, ...)` factory next to the others |
38+| 5 | Build it in `recreateManagers` and assign it in the swap block |
39+| 6 | Add to the `Manager` interface only if handlers need it; then `DummyMgr` in `managers_dummy_test.go` needs the method too |
40+| 7 | Hook into `BeginBlock`/`EndBlock` in `module.go` if it has per-block work (mind the order) |
41+| 8 | `manager_x_current_test.go` gocheck suite |
42+
43+Template: `manager_dynamic_fee_current.go` (recent, small, keeper-only, `EndBlock` hook).
44+
45+## Test doubles
46+
47+- `NewDummyMgr()` / `NewDummyMgrWithKeeper(k)` (`managers_dummy_test.go`) return a `*DummyMgr` with dummy gas, event, txout, network, validator, observer, pool, slasher, trade, wasm, switch, adv-swap-queue and scheduled-migration managers (secured-asset and stable-reserve are real, built on the keeper).
48+- `setupManagerForTest(c)` (`handler_test.go`) returns a real `*Mgrs` over a test keeper - use it when the manager interaction itself is under test.
49+- Override one manager in a `DummyMgr` by assigning its field before calling the handler.

Ask an AI about this change

Chat assistantClaude, ChatGPT, … (reads a link)

Coding agentClaude Code, Cursor, … (reads the repo)

The context file is context.md. Use Copy with context for an AI that can't open links; it pastes the whole file in.

Glossary

Claude Code skill
A folder with SKILL.md (frontmatter name + description used for triggering) that Claude loads on demand; references/ hold detail read only when needed.
CLAUDE_PROJECT_DIR
Environment variable Claude Code sets for hooks: the project root. Both hooks are resolved from it, and post-edit.sh cd's into it. post-edit.sh ↗
Evals
evals/evals.json: three realistic prompts per skill, each with an expected answer and assertions an answer must satisfy. Documentation only here; nothing runs them. memo-parser evals ↗
Hook (PreToolUse / PostToolUse)
A command Claude Code runs before or after a tool call. Exit 2 blocks a PreToolUse call; for PostToolUse it feeds stderr back to Claude. settings.json ↗
Mimir
Node-voted runtime overrides of protocol constants. Operational keys need a few matching votes; economic keys need a 2/3 supermajority. docs/mimir.md ↗ keeper_mimir.go ↗
Mocknet
The local Docker Compose network (THORNode, Bifrost, L1 daemons, Midgard) built with the mocknet tag. docker-compose.yml ↗
Store migration
Code run once at the upgrade height (ConsensusVersion bump in module.go) to rewrite stored state into a new shape. module.go ↗
Stringer
Go tool that generates String() methods; constants/constantname_string.go is its output and must be regenerated, not edited. constantname_string.go ↗
trunk
The meta-linter CI uses (prettier, markdownlint, yamllint, shellcheck...). The repo pins it via the ./scripts/trunk launcher and .trunk/trunk.yaml. .trunk/trunk.yaml ↗ scripts/trunk ↗
Version gate
An if on the network version selecting old vs new behaviour. The skills now say not to add them: upgrades are a coordinated restart. keeper.go ↗