What the agent does
The agent clones the repository into its own cloud sandbox and reads where the CLI describes itself today. In a tool like tomnomnom/gron, everything is in main.go: a custom flag.Usage that prints a synopsis (gron [OPTIONS] [FILE|URL|-]), eleven options registered with the standard flag package in short and long pairs (-u/--ungron, -v/--values, -c/--colorize, -m/--monochrome, -s/--stream, -k/--insecure, -x/--proxy, --noproxy, -j/--json, --no-sort, --version), a table of exit codes 0 to 6 from exitOK to exitJSONEncode, and four examples. There is a completions/ directory with Bash and Fish scripts, a README.mkd whose Installation section covers release archives, Homebrew and go install, and an ADVANCED.mkd. Releases run through .github/workflows/release.yml with goreleaser/goreleaser-action@v6 and a .goreleaser.yml that only enables a source archive, so binaries and archives use GoReleaser's defaults. No file ends in .1.
It writes gron.1 by hand in man(7) roff, because a CLI with eleven flags and a standard-library flag set does not need a generator and a dependency to produce one page. The sections follow the usage text: NAME, SYNOPSIS, DESCRIPTION taken from the first line of flag.Usage, OPTIONS with each short and long form and the one-line description the usage prints, EXIT STATUS with the seven codes and their meanings, EXAMPLES with the four from the usage and the ungron alias the README recommends, and SEE ALSO pointing at the README and ADVANCED.mkd. The agent renders it with man -l gron.1 and lints it with mandoc -T lint in the sandbox until both are clean.
A page that drifts from the binary is worse than none, so the agent adds a test in main_test.go: it calls flag.VisitAll on the registered flag set and asserts that every flag name appears in gron.1 as a bold option, and that every option in the page is a registered flag. Adding a flag without touching the page fails go test, which .github/workflows/build.yml already runs on stable and oldstable.
Finally it wires distribution. .goreleaser.yml gets an archives entry that adds gron.1 and the completions/ files beside the binary in every archive, keeping the default name template so existing download links in the README stay valid, and the Installation section gains a line showing where to copy the page (/usr/local/share/man/man1/). It runs goreleaser check and goreleaser release --snapshot --clean in the sandbox to confirm the archives contain the page before opening the pull request.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add a man page to this Go CLI. Read main.go, the flag registrations, the custom usage text, the completions directory, the README installation section and the GoReleaser config first. Write gron.1 by hand in roff with NAME, SYNOPSIS, DESCRIPTION, OPTIONS listing every short and long flag with its description, EXIT STATUS with every exit code, EXAMPLES from the usage text and SEE ALSO. Render it with man and lint it with mandoc until clean. Add a Go test that walks the registered flags with flag.VisitAll and fails if any flag is missing from the page or any option in the page is not a registered flag. Add an archives section to the GoReleaser config that ships the man page and the completion scripts in every release archive without changing archive names, run goreleaser check and a snapshot release to confirm, add an install line to the README, and open a pull request.",
"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
What comes back is a pull request that adds gron.1, changes main_test.go, .goreleaser.yml and README.mkd, and touches no other Go source. The description shows the rendered page as text from man -l, the mandoc -T lint result, and the file listing of one snapshot archive with the page and completions inside.
The run's record keeps the go test run with the new sync test passing on the current flag set and the goreleaser release --snapshot output, so a reviewer can see the archive layout without cutting a release to find out.
Before merging, a reviewer reads the option descriptions for tone, since the page copies the terse usage lines and may deserve a sentence more in places, and decides whether packagers downstream, such as a Homebrew formula or a distribution package, should be told the archive now carries a page they can install.
Run it on every pull request that changes main.go
In the console, an automation in the Project that has the repository, with a github trigger on pull_request.opened, starts one run per pull request with the event after the prompt. The prompt asks the run to finish at once unless the diff registers, renames or removes a flag, and otherwise to update gron.1 to match, re-render and lint it, run go test so the sync test proves the match, and push the change to the pull request branch with a comment saying which options moved.
From your own tooling, a handler that receives GitHub's pull_request webhook sends one POST /o/{org}/sessions with the pull request URL in resources so the run checks out that branch, with a request_id that is a UUID v5 of the pull request id so a redelivery never starts a second run.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
A man page is mostly transcription, and transcription is where a person skims and a flag goes missing. The agent reads the flag registrations rather than the README, so the page matches the binary, and the sync test it adds makes that true for every future flag too. Rendering with man, linting with mandoc and building a snapshot release are all things a laptop can do, but they rarely get done for a documentation change; in the sandbox they run every time and the output stays in the record.
The same request fits any Go CLI in an organisation, whether it uses the standard flag package, pflag or cobra, because the agent reads whatever the repository has and chooses between a hand-written page and a generated one accordingly, each run in its own sandbox with its own pull request.
Frequently asked questions
Why write the page by hand instead of generating it?
For a CLI on the standard flag package with a handful of options, a generator adds a build step and a dependency to produce a page you could read in a minute. The sync test gives the guarantee a generator would, that flags and page agree, without the tooling. A cobra or pflag CLI with subcommands is a different case and the agent generates there.
Will the page ship with releases?
Yes. The archives entry in .goreleaser.yml includes gron.1 and the completion scripts in every archive GoReleaser builds, and the snapshot release in the sandbox shows the resulting file list. Archive names keep GoReleaser's default template so nothing linking to a release asset breaks.
Does Homebrew install it automatically?
Only if the formula is told to. The pull request puts the page in the archive, which is what a formula needs; adding man1.install to the formula is a change in the tap or in homebrew-core, outside this repository, and the description says so.
How does the page stay in sync with new flags?
The test in main_test.go walks every registered flag and checks it against the page in both directions. A pull request that adds --foo without a matching entry fails go test in the existing CI workflow, which runs on every push and pull request.
What about Windows users?
The page is included in the Windows zip too, where it is inert; gron --help keeps printing the same usage text on every platform. Nothing in the binary changes, so there is no runtime cost anywhere.
More Go CLI jobs
The same job on other stacks
More jobs like this: Turn a Linear label into a PR
- Add a Message Shortcut to a Slack Bolt App (Slack Bolt)