docs(cli): scope Go CLI authority to parity-relevant legacy work - #6153
Merged
Conversation
The legacy shell's port is now ~92% complete (95/103 leaf commands natively ported), but AGENTS.md still reads as porting-era guidance that treats apps/cli-go/ as the unconditional authority for anything touching src/legacy/. That trips up net-new work (bug fixes, refactors, TS-only additions) with an irrelevant parity check. Add ADR 0016 recording the decision and scope AGENTS.md, the porting status tracker, and the ADR index to match: Go CLI is authoritative only for finishing the remaining wrapped ports and for changes that touch an already-ported command's established output/flags/behavior.
Contributor
Supabase CLI previewnpx --yes https://pkg.pr.new/supabase/cli/supabase@8d2d3ac3e77e175e40caaa3f87a77013e76229dfPreview package for commit |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 58b507ac60
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Fixes from PR #6153 review (pullrequestreview-4906607511): - Maintaining a still-wrapped command's own command/flag definition is in scope for Go authority too, not just replacing the wrapper — those definitions gate which invocations reach the Go binary. - Phase 0 wrapping only works for commands the Go CLI already implements; a genuinely TS-only addition has nothing to proxy to and skips Phase 0 entirely. - The parity surface now explicitly includes database and Docker/subprocess side effects and full telemetry semantics (event firing, not just payload shape), matching what SIDE_EFFECTS.md and the Telemetry Parity section already establish. - Stopped overstating CI's testParity/e2e coverage as a blanket safety net for misclassified changes — it's real but deliberately partial (e.g. db pull/lint --local skip testParity today).
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 8d2d3ac3e7
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
avallete
approved these changes
Aug 11, 2026
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
2 participants
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.
What kind of change does this PR introduce?
Docs update (ADR + agent guide).
What is the current behavior?
apps/cli/AGENTS.mdreads, top to bottom, as porting-era guidance: it opens with the Phase 0/1 wrapping workflow and states unconditionally thatapps/cli-go/is "the authoritative source" for anything touchingsrc/legacy/. That was correct while the legacy shell was being built from scratch, but the port is now largely done — 95 of 103 legacy leaf commands (~92%, perapps/cli/docs/go-cli-porting-status.md) are natively ported, with only 8 remaining Phase 0 proxies. Agents (and humans) doing net-new work insrc/legacy/— bug fixes, refactors, TS-only additions, tests — keep following the unconditional framing literally and audit Go source, or judge review feedback against Go parity, for changes that have nothing to do with it.What is the new behavior?
docs/adr/README.md.apps/cli/AGENTS.mdstating current completion and exactly whenapps/cli-go/is required reading: finishing one of the remaining wrapped ports, or changing an already-ported command's established parity surface (command/flag names, stdout/stderr text, exit codes, filesystem/API side effects, telemetry payload shape). Everything else insrc/legacy/is treated like any other TypeScript workspace.apps/cli-go/reference blurb.go-cli-porting-status.md's header to the ADR/AGENTS.md scoping.Companion change (not in this diff, personal Claude Code config): updated the
go-parity-auditorandreview-adjudicatorsubagent definitions to apply the same scoping — parity is the deciding standard only for the two cases above, not for every legacy-shell change.