Repository navigation
docs: AGENTS.md in STE-style English; drop CLAUDE.md/GEMINI.md symlinks - #49
Merged
Merged
Conversation
Why: Amy: "remove the GEMINI.md and CLAUDE.md and move BOTS.md to AGENTS.md now that claude code and everyone else has settled on AGENTS.md." Approach: git mv keeps history; drop both symlinks. Claude Code reads AGENTS.md only when no CLAUDE.md exists, so removing the symlink is what turns it on. 0.6.0 is unreleased, so its CHANGELOG entries are rewritten rather than adding a rename note. Learned: Claude Code's AGENTS.md fallback (2.1.277, 2026-09) is reportedly not on Bedrock/Vertex/Foundry yet; Gemini CLI still defaults to GEMINI.md and needs context.fileName set. README says so. Next: contributors on those setups need the setting (Gemini) or a local CLAUDE.md with `@AGENTS.md` (Claude Code on Bedrock/Vertex). 🤖 Claude <claude@anthropic.com> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
🤖 Claude <claude@anthropic.com> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Amy: "49 doesn't need to mention gemini-cli which is being discontinued. agy reads AGENTS.md." 🤖 Claude <claude@anthropic.com> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
tobert
changed the title
Why: Amy: "make our AGENTS.md be more STE-ish, and also have a section to guide to STE-ish in documentation, and terse alignment to STE in comments, commits, and PR descriptions." Modeled on ~/src/kaish/AGENTS.md. Approach: STE rules (one topic per sentence, 20/25-word limits, imperative, active voice, one term per concept, specific values) and one rule set for each kind of text. Terms table has only otel-cli terms; OTel and W3C terms keep their spec meaning (Amy). Removed the marketing text, the per-model "style is welcome" section (it contradicts one shared style), the git and gh command tables, and the stale Go 1.21 and 0.5.0 facts. Added the behavior that scripts depend on, the CI gates, and known test hazards. "Open issues early" becomes "ask a maintainer first". CHANGELOG: "LLM agent" -> "agent" (Amy). Learned: the squash setting is COMMIT_MESSAGES; the PR body becomes the squash message only because the maintainer pastes it at merge. Next: merge after #48. The gates and the stable-Go hazard describe #48. 🤖 Claude <claude@anthropic.com> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Amy: "let's drop the list of models in the attribution section" 🤖 Claude <claude@anthropic.com> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Amy: "can we simple say 'The style is inspired by Simplified Technical English.'" 🤖 Claude <claude@anthropic.com> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Owner
Author
|
kaibo review (cast Accuracy:
Added from the gaps it found: Style: fixed two figures of speech, a 21-word instruction, a repeated sentence, and a duplicate Not applied: naming a Go version in "latest stable Go" (it is a policy, not a value), and README's "CLI argument" column against "flag" here (README is out of scope). 🤖 Generated with Claude Code |
…zards Why: Amy asked for a kaibo deepseek review of AGENTS.md. Approach: verified each finding against the code before applying it. - exec: a nonzero child exit code has priority over --fail (otelcli/config.go:381-390). Stated in the behavior list and Terms. - Hazards: Expect.ExitCode is set by 9 fixtures and never compared (checkProcess, main_test.go:201); PATH in a fixture stops the run; -short skips IsLongTest; Diag.ExecExitCode must be set before SoftFail. - Testing: name `otel-cli status` as the debugging tool. - Env var rule matches the code: one-invocation flags like --start have none. - STE fixes: two figures of speech, a 21-word instruction, a repeated sentence, a duplicate Next: field in the handoff block. - Copyright line matches LICENSE (Equinix Metal 2020, A. Tobey 2025). Learned: the --fail exit-1 contract has no test; the fixtures that set ExitCode: 1 look like assertions but check nothing. Next: Amy's call on a test-gap fix. 🔍 Reviewed-by: DeepSeek (kaibo, deepseek cast) 🤖 Claude <claude@anthropic.com> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
🤖 Claude <claude@anthropic.com> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Amy: "drop line 334 in pr49" 🤖 Claude <claude@anthropic.com> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
tobert
added a commit
that referenced
this pull request
Oct 24, 2026
…nd a ctrl-c panic (#50) The functional test harness never compared `Expect.ExitCode`. Nine fixtures set it, and none was tested. With the check on, three fixtures showed a real bug: `otel-cli exec` exits 255 when its child is killed by a signal. **Behavior change for review:** `exec` now exits 128 + signal for a signaled child, which is the shell convention: 130 for Ctrl-C, 137 for `--command-timeout` (SIGKILL). Before, it exited 255. Scripts can see this change. The alternative is to keep 255 and pin it in the fixtures. What changed: - `main_test.go`: `checkProcess` compares the exit code when the process exited on its own. A killed process reports -1, so it is skipped. - `data_for_test.go`: the #360 fixture uses `ExitCode: 42` in place of a `CheckFunc`; "protocol: bad config" with `--fail` expects 1. The three signal fixtures expect 130 and 137. Their old values (2 and 0) were never checked. - `otelcli/exec.go`: `128 + status.Signal()` when `ProcessState.Sys()` is a `syscall.WaitStatus` and `Signaled()`. - `otelcli/exec.go`: `signal.Stop(signals)` before `close(signals)`. Before, a Ctrl-C during the span export panicked with "send on closed channel" (exit 2). Now SIGINT has its default action. The new fixture "exec ctrl-c during export does not panic" was red before the fix. - CHANGELOG: two lines under 0.6.0 Fixed. Commits are test-first: each fix follows a failing fixture. Verification: ``` go vet ./... && go build && go test ./... # green GOOS=windows|darwin|freebsd go build -o /dev/null . # ok ./otel-cli exec --command-timeout 50ms -- sleep 1; echo $? # 137 ./otel-cli exec -- sh -c 'exit 3'; echo $? # 3 ``` Found by the kaibo review of AGENTS.md on #49. After this merges, the AGENTS.md hazard "the harness ignores `Expect.ExitCode`" is no longer true; #49 drops it. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Renames BOTS.md to AGENTS.md, removes the per-model symlinks, and rewrites the file in a style inspired by Simplified Technical English (STE). Merge after #48: the Gates and Hazards sections describe #48 (govulncheck, latest stable Go).
What changed:
git mv BOTS.md AGENTS.md; removed theCLAUDE.mdandGEMINI.mdsymlinks.--fail,--verbose), CI gates, and test hazards (SoftFailexits,PATHin fixtures,-short, base-10 parsing, requiredbuildcheck).Tool compatibility: Claude Code (2.1.277+) reads AGENTS.md only when there is no CLAUDE.md. Codex, agy and most other agents read AGENTS.md natively.
Verification: a script split the prose into sentences; none is over 25 words. No code changes.
🤖 Generated with Claude Code