Skip to content

multi: add agent skills for backports, releases and Go bumps - #11580

Open
ziggie1984 wants to merge 10 commits into
lightningnetwork:masterfrom
ziggie1984:repo-agent-skills
Open

ziggie1984 wants to merge 10 commits into
lightningnetwork:masterfrom
ziggie1984:repo-agent-skills

Conversation

@ziggie1984

@ziggie1984 ziggie1984 commented Nov 13, 2026 •

Copy link
Copy Markdown
Collaborator

Change Description

This adds the agent skills we use for lnd's maintenance processes to the repo.
Claude Code and Codex then load the same skills for everyone who works here,
instead of each person keeping a private copy.

  • lnd-backport creates a backport of a merged PR, or repairs a
    backport-action draft that stopped on a BACKPORT-CONFLICT commit. It
    cherry-picks the parent commits one at a time, resolves conflicts against the
    parent commit rather than the incoming hunk (master's btcd v2 imports,
    branch-only context, master-only code inside a conflict hunk), checks that
    the PR's dependencies are on the branch, and runs vet and tests. Its scripts
    compare each backport commit with its parent by git patch-id, and that
    comparison produces a commit-by-commit parity table for the PR description.
    The v0.20/v0.21 backports of sweep: isolate bad inputs on mempool rejection #10842 ([v0.20.x-branch] Backport #10842: sweep: isolate bad inputs on mempool rejection #11578, [v0.21.x-branch] Backport #10842: sweep: isolate bad inputs on mempool rejection #11579) were rebuilt this way.
  • cut-release covers the release flow, from the version bump PR to the
    signed tag via scripts/tag-release.sh, then CI, signing and publishing.
  • bump-golang-version is driven by a new Go tool, scripts/bump-go
    (make bump-go), so no agent edits version strings or types checksums. The script finds every toolchain and
    minimum Go pin using one rule per pin format, rewrites them, and takes the
    docs/INSTALL.md checksums from go.dev's release feed. It then checks that
    all pins agree and that no replaced version is left anywhere. It replaces a
    hand-written file list that had already missed seven go.mod files.

Deterministic steps are Go tools in scripts/, like the release-notes fold
tool, with unit tests and lint coverage. The skills call those tools; they don't
ship scripts of their own beyond thin git/gh helpers.

  • scripts/bump-go checks and bumps every Go version pin (see above).
  • scripts/resolve-v2-imports resolves backport conflicts that only exist
    because master imports the btcd v2 modules. It keeps the release branch's
    imports, adds the new ones, gofmts the file, and refuses any conflict that
    contains code.

Claude Code reads .claude/skills/ and Codex reads .agents/skills/.
.agents/skills is a symlink to .claude/skills, so both tools load the same
files. .claude/skills/README.md lists the skills and explains how to add a new
one. General-purpose skills stay in
lightninglabs/agent-skills.

Steps to Test

  • All three skills pass Codex's quick_validate.py frontmatter check.
  • Running codex exec from the repo root lists lnd-backport, cut-release
    and bump-golang-version.
  • go test ./scripts/bump-go ./scripts/resolve-v2-imports passes, and
    make lint is clean.
  • bump-go was checked against lnd's history and with a forward bump:
    • Recent bumps: replaying every Go bump since 2024 from its parent
      commit reproduces each one since the pins became consistent byte for byte
      (the Go tool gives the same result as the earlier Python prototype on all
      19 bumps):
      df48bd51c6, b1f9ca66d (major 1.26 → 1.27), d67c9edf8 and
      aab1e4661. scripts/bump-go/replay_history.sh runs this as a regression test,
      and it fails when a rule is removed.
    • Older bumps: they don't reproduce exactly because they also fixed
      drifted pins by hand. They also show pins the real PRs missed, which the
      script updates (INSTALL.md and tools/linters/go.mod in 7bc88e8360,
      gen_protos_docker.sh in 1c76c6198c, kvdb/sqldb go.mod in
      19b5a1fb05).
    • Forward bump: bumping the toolchain to 1.27.4 on master changes
      15 files, exactly the diff of build: update toolchain to Go 1.27.4 #11587. All the Docker tags and URLs it points to exist, and the tree
      builds and passes vet and the build/sweep tests with Go 1.27.4.
      make lint passes with the bumped images (0 issues).
    • Release branches: bump-go status passes on master,
      v0.21.x-branch and v0.20.x-branch.
  • On the real sweep: isolate bad inputs on mempool rejection #10842 → v0.21 cherry-pick conflict, resolve-v2-imports
    produces exactly the resolution pushed in [v0.21.x-branch] Backport #10842: sweep: isolate bad inputs on mempool rejection #11579. On a code conflict from the
    same backport, it refuses and leaves the file untouched.
  • I ran parent_commits.sh and parity.sh against the sweep: isolate bad inputs on mempool rejection #10842 backports. They
    reproduced the per-commit SAME/DIFF results and the aggregate diff exactly.

Tooling only, no change to lnd itself; no-changelog.

@github-actions github-actions Bot added the ci-hold CI is held; remove this label to run CI label Nov 13, 2026
Add an agent skill that creates a backport of a merged PR onto a
release branch, or repairs a backport-action draft that stopped on a
conflict. It rebuilds the backport with one cherry-pick per parent
commit, resolves conflicts against the parent commit rather than the
incoming hunk, checks that the PR's dependencies are present on the
branch, and runs vet and tests on the touched packages.

The helper scripts list the parent commits, resolve import-only
conflicts caused by master's btcd v2 modules, and compare each
backport commit with its parent by patch-id. That comparison feeds a
commit-by-commit parity table in the PR description, so reviewers can
see every place the backport differs from the parent and why.
Add an agent skill that walks through cutting a release or release
candidate. It asks for the version and the release kind, checks that
the series is still supported, opens the version bump PR, creates the
signed tag with scripts/tag-release.sh, and follows the CI, signing
and publish steps.
Add an agent skill that updates the Go toolchain version and the
minimum Go version across the Makefile, CI workflows, Dockerfiles,
go.mod files and docs/INSTALL.md, using the repo's two-commit
convention.
Claude Code reads skills from .claude/skills and Codex reads them from
.agents/skills. Point .agents/skills at .claude/skills with a symlink so
both tools load the same files, and add a README that lists each skill
and how to add a new one.
Release notes now arrive as fragments in docs/release-notes/unreleased
and are folded into the version-wide document when a release is
prepared. Update cut-release to match. It now does the following:

- folds the fragments in the version bump PR, for release candidates
  and final releases alike, using the fold tool from master, since
  the release branches don't ship the tool
- re-checks unreleased/ on the release branch right before merging
  the bump PR, so a backport that merged in the meantime doesn't
  leave an unfolded fragment behind, as happened with v0.21.7
- runs check-release-notes-consistency.sh release before tagging,
  which tag-release.sh on the release branches doesn't do yet
- ports a patch release's notes to master and deletes the fragments
  it announced
Replace the hand-maintained file list in bump-golang-version with
scripts/bump_go.py. The list had already drifted: it missed seven go.mod
files, the govulncheck workflow and the mobile build docs.

The script finds every toolchain and minimum Go version pin using one
rule per pin format, rather than by matching the version string, since
the two versions can be equal. It rewrites the pins and takes the
docs/INSTALL.md archive checksums from go.dev's release feed instead of
leaving them to be typed in. It then checks the result: all pins of a
kind agree, the checksums match go.dev, and no file still mentions a
replaced version unless it is excluded on purpose. A rule that no
longer matches its file makes the script fail rather than skip it.

Replaying d67c9ed and aab1e46 from their parent commits reproduces
both commits exactly. The skill now drives the script, and its policy
and commit conventions follow recent history.
Replaying every Go bump since 2024 against bump_go.py found two gaps.

The setup-go action names the toolchain's major release ("with Go 1.27
only"), which the script didn't rewrite on the 1.26 -> 1.27 bump. Rules
can now pin the major release only. On a major bump, the leftover scan
also looks for mentions of the old major release.

INSTALL.md checksums were matched by line format, and that format
changed in 7fcbbd4. The script now identifies each SHA256 by its
value on go.dev and swaps in the hash of the same archive for the new
version. status rejects any hash that isn't an archive of the minimum.

Pins are now rewritten only where they hold the anchor version:
Makefile GO_VERSION for the toolchain, the root go.mod for the
minimum. --allow-inconsistent bumps a tree whose pins drifted and
reports the pins it leaves alone.

Add replay_history.sh, which replays past bumps from their parent
commits and requires a byte-identical result. It reproduces df48bd5,
b1f9ca6, d67c9ed and aab1e46, and it fails when the major-only
rule is removed. Older bumps don't replay exactly because they also
fixed hand-made drift, and the replay showed pins those PRs had missed.
Add a Go tool that checks and bumps the Go versions lnd pins: the build
toolchain (Makefile GO_VERSION, CI workflows, Docker images, linter
config and build docs) and the minimum version (every go.mod and
docs/INSTALL.md).

Each pin format has its own rule. Pins are matched by context rather
than by the version string, since the toolchain and the minimum can be
equal. status checks that every pin agrees with its anchor (Makefile
GO_VERSION or the root go.mod), and that each INSTALL.md hash is the
go.dev checksum of a minimum-version archive. set rewrites the pins
that hold the anchor version and swaps the checksums by value for the
same archives of the new version. It then repeats the checks and fails
if the replaced version is still mentioned anywhere. A rule whose file
exists but no longer matches fails the check, so a format change can't
make a pin silently go stale.

make bump-go runs status. Passing toolchain= and/or min= runs set
instead.

replay_history.sh replays past bumps from their parent commits and
requires a byte-identical result. It reproduces every bump since the
pins became consistent: df48bd5, b1f9ca6, d67c9ed and
aab1e46.
Backports from master conflict on import blocks because master uses
the btcd v2 modules (btcutil/v2, chainhash/v2, wire/v2, ...) while the
release branches import v1. Add a tool that resolves those conflicts.
It keeps the release branch's imports, adds the incoming imports that
aren't btcd v2 paths, and gofmts the file. It refuses any conflict
that contains a non-import line, so code conflicts are still resolved
by hand.
Replace the Python scripts in the skills with the Go tools in
scripts/bump-go and scripts/resolve-v2-imports, and document how to
build them from master for use on release branches.
@github-actions github-actions Bot added the severity-medium Focused review required label Nov 16, 2026
@github-actions

Copy link
Copy Markdown

🟡 PR Severity: MEDIUM

file classification + line-count bump | 13 files | 2328 lines changed (1858 excluding tests)

🟢 Low (11 files)
  • .agents/skills - repo config/skills pointer, non-code
  • .claude/skills/README.md - documentation
  • .claude/skills/bump-golang-version/SKILL.md - documentation
  • .claude/skills/cut-release/SKILL.md - documentation
  • .claude/skills/lnd-backport/SKILL.md - documentation
  • .claude/skills/lnd-backport/scripts/parent_commits.sh - helper script
  • .claude/skills/lnd-backport/scripts/parity.sh - helper script
  • Makefile - build tooling
  • scripts/bump-go/main.go - standalone dev tooling script
  • scripts/bump-go/replay_history.sh - helper script
  • scripts/resolve-v2-imports/main.go - standalone dev tooling script
🧪 Test files (excluded from count, 2 files)
  • scripts/bump-go/main_test.go
  • scripts/resolve-v2-imports/main_test.go

Analysis

Every changed file falls under scripts/*, .claude/skills/*, or Makefile — all LOW severity categories (tooling/docs, no production Lightning code touched). However, non-test lines changed total 1858 (2328 total minus 470 in *_test.go files), which exceeds the 500-line threshold for a severity bump. Per the rules, this bumps the PR one level up from LOW to MEDIUM. No critical or high-risk packages (lnwallet, htlcswitch, contractcourt, etc.) are touched.


To override, add a severity-override-{critical,high,medium,low} label.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci-hold CI is held; remove this label to run CI no-changelog no-itest severity-medium Focused review required

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant