What the agent does
The agent reads the lint setup before it changes a line of it. In a CLI laid out like spf13/cobra-cli, .golangci.yml is a v1 file: run.deadline: 5m, linters.disable-all: true and an enable list of deadcode, errcheck, gas, goconst, goimports, golint, govet, ineffassign, interfacer, maligned, megacheck, structcheck, unconvert and varcheck, with two dozen more linters left as comments. go.mod declares the module at go 1.15 with cobra v1.6.1 and viper v1.12.0. The golangci-lint job in .github/workflows/test.yml uses actions/setup-go@v2 with Go 1.17, actions/checkout@v3.1.0 and golangci/golangci-lint-action@v2 with version: latest and args: --verbose, next to a test matrix of Ubuntu and macOS on Go 1.14 through 1.17 and an MSYS2 job on Windows. The Makefile has a lint target that runs golangci-lint run -v and a warning that points at an install script on a host that no longer serves it. The code under lint is main.go, tpl/main.go and the cmd package with root.go, add.go, init.go, project.go, helpers.go, the license files and golden-file tests under cmd/testdata.
Then it maps each v1 setting to its v2 form, because version: latest now installs a v2 binary that refuses a v1 file outright. The file gets version: "2". disable-all: true becomes linters.default: none. goimports moves out of the linter list into formatters.enable, where v2 keeps gofmt, gofumpt, gci and goimports. run.deadline goes, and so does its successor run.timeout, which v2 turns off by default. Six of the enabled linters no longer exist in v2: deadcode, structcheck and varcheck, whose job unused now does; golint, whose rules live on in revive; and interfacer and maligned, which have no successor beyond govet's fieldalignment analyzer. Two more are aliases v2 dropped: gas is gosec and megacheck is staticcheck, which in v2 also absorbs gosimple and stylecheck. The result enables errcheck, goconst, gosec, govet, ineffassign, staticcheck, unconvert and unused, each with a comment naming the v1 entry it replaces, and the commented-out candidates come back as a comment block so nothing the maintainer was considering is lost.
The agent runs golangci-lint migrate first and keeps its output beside the hand-written file. The command backs the original up as .golangci.bck.yml, drops every comment and silently discards unknown fields, which is why its result is a draft and not the pull request: the agent diffs the two, keeps the generated structure where they agree, and explains in the description where they differ. golangci-lint config verify then checks the new file against the v2 schema, and golangci-lint run -v runs the real linters over the module. What gosec, staticcheck and unused report on code that only ever saw the v1 set is fixed in the same pull request when the fix is a one-line mechanical change, such as an unchecked Close or a conversion unconvert flags; anything larger becomes an entry under linters.exclusions.rules with a comment and a line in the description, so the first v2 run is green without hiding findings in silence.
Finally it updates where the linter runs. The lint job moves to golangci/golangci-lint-action@v8, which installs v2 binaries, keeps version: latest, and gets actions/setup-go on go-version: stable, because the v2 binary is built against a Go newer than the 1.17 the job pins today while the test matrix keeps its 1.14 to 1.17 range untouched. The Makefile keeps golangci-lint run -v, which is the same command in v2, and its warning now points at the install script the golangci-lint project publishes. The agent runs make fmt and go test ./... once more so the golden files in cmd/testdata still match, and actionlint over the edited workflow.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Migrate this Cobra CLI from golangci-lint v1 to v2. Read .golangci.yml, go.mod, Makefile and .github/workflows/test.yml first. Install golangci-lint v2 in your sandbox, run golangci-lint migrate and keep its output as a draft, then write .golangci.yml by hand with version \"2\": disable-all becomes linters.default none, goimports moves to formatters.enable, drop run.deadline, replace deadcode, structcheck and varcheck with unused, gas with gosec, megacheck with staticcheck, and say in a comment what happened to golint, interfacer and maligned. Keep the commented-out linters as a comment block. Run golangci-lint config verify and golangci-lint run -v. Fix one-line findings from the new linters in the same change; for anything larger add an exclusion rule with a comment and list it in the pull request. Update the lint job to golangci/golangci-lint-action@v8 with setup-go on stable Go, leave the test matrix as it is, and fix the Makefile's install hint. Run make fmt, go test ./... and actionlint, and open a pull request with a table of every v1 linter and what became of it.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
The pull request changes .golangci.yml, the lint job in .github/workflows/test.yml and the Makefile, plus any Go file a one-line fix touched. Its description carries a table with one row per v1 linter: kept, renamed, merged into another or removed with no successor. Under it are the golangci-lint version and config verify output, the summary line of golangci-lint run -v, and the list of exclusion rules the agent added with the finding each one covers.
The description also pastes the diff between golangci-lint migrate's draft and the committed file, so a reviewer sees what the automatic conversion would have thrown away: the comments, the candidates list and the goimports move.
Before merging, a reviewer decides whether revive should come in to replace golint's naming and comment rules, whether govet's fieldalignment is worth its noise as a stand-in for maligned, whether each exclusion rule should instead become a fix, and whether the test matrix's Go 1.14 to 1.16 entries have outlived the versions the module is built with, which is a separate change the agent leaves alone.
Run it on every Go repository
A team with several Go CLIs on v1 configs sends this body once per repository from its own server, each a POST /o/{org}/sessions with that repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own .golangci.yml: one that enables gofmt moves it to the formatters block, one with issues.exclude-rules gets them under linters.exclusions.rules, and one already on v2 ends with a note saying there is nothing to do.
Once the config is on v2, an automation on the Project with a github trigger on pull_request.opened and the prompt "if this pull request changes .golangci.yml, run golangci-lint config verify and golangci-lint run, and comment with any linter it enables or removes and what that linter reported" starts one run per such pull request. The trigger adds the pull request after the prompt, and only work by an owner, member or collaborator fires it.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A v1 file does not degrade gracefully: the first CI run that picks up a v2 binary through version: latest fails on the config itself, before a single line of Go is read. Fixing that by hand means knowing which of fourteen enabled linters were renamed, which were merged into staticcheck, which unused replaced and which have no successor, and then discovering what the newly enabled linters say about code they have never seen. The agent runs the real v2 binary in its own sandbox and writes the file from that output.
The migrate draft, the config verify result and the full run -v output stay with the run, so a reviewer sees what v2 would report before the lint job does. A team with many Go repositories runs the same request across all of them at once, each in its own sandbox with its own record.
Frequently asked questions
Will the same rules run after the migration?
Most of them, and the description is explicit about the rest. unused covers what deadcode, structcheck and varcheck did, gosec and staticcheck are the linters gas and megacheck always pointed at, and goimports still runs as a formatter. golint is gone unless revive is enabled, and interfacer and maligned have no replacement in v2 beyond govet's fieldalignment, so the pull request names them as dropped rather than pretending to keep them.
Why not just commit what golangci-lint migrate produces?
Because it drops every comment, including the list of linters the maintainer had considered and left off, and it discards fields it does not recognise without saying so. The agent uses the command's output as the first draft, writes the committed file by hand, and shows the diff between the two in the description so nothing disappears unnoticed.
Does the go 1.15 directive in go.mod matter?
The v2 binary reads it to decide which language version to analyse, so the module itself needs no change. What changes is the toolchain the lint job runs on: the 1.17 the job pins today is older than the Go the v2 binary is built with, so the job moves to stable Go while the test matrix keeps its older versions, since compatibility with them is what that matrix exists to prove.
What happens to findings from the newly enabled linters?
A one-line mechanical fix goes in the same pull request, with the linter and rule named in the commit. Anything that needs a design decision becomes an exclusion rule with a comment and a line in the description, so the first v2 run passes and the reviewer still sees every finding that was deferred.