Skip to content

docs(cli): make the TS legacy shell the source of truth in agent instructions - #6281

Merged
avallete merged 3 commits into
developfrom
avallete/repos-agents-instructions-a7425f
Aug 20, 2026
Merged

docs(cli): make the TS legacy shell the source of truth in agent instructions#6281
avallete merged 3 commits into
developfrom
avallete/repos-agents-instructions-a7425f

Conversation

@avallete

@avalleteavallete commented Aug 20, 2026

Copy link
Copy Markdown
Member

Summary

Updates the repo agent instructions (AGENTS.md files and the delegation-surface doc) to reflect where the CLI actually stands after the Go→TS migration:

  • src/legacy/ is the source of truth. The rewritten apps/cli/AGENTS.md replaces the "Go CLI Authority" framing with a "Source of Truth" section: the compatibility standard is the legacy shell's own established behavior (tests, SIDE_EFFECTS.md, shipped output), not comparison against Go. It also explicitly disallows new comments/docs/helper names framed as "Go parity", with old framing cleaned up opportunistically.
  • next/ is frozen and departing. The shell-architecture section now documents that next/ development moves to its own branch and the folder will leave this tree; no new features land there. Porting-era guidance built around it ("Reusing next/ implementations") is removed, and the dual-write file-location rule is noted as leaving with next/.
  • Go is a residual delegation surface, not a reference. "Phase 0: Go Binary Wrapper" becomes "The Go Delegation Surface": the surface only shrinks, never grows, and apps/cli-go/ is authoritative solely for the still-proxied commands' flag definitions until they are removed. docs/go-cli-porting-status.md and apps/cli-e2e/AGENTS.md get matching one-line reframes.
  • Still-live invariants are kept, de-Go'd. The parity checklist becomes "Legacy Shell Invariants" and the telemetry section now treats shared/telemetry/event-catalog.ts as canonical in its own right; all operational rules (telemetry ensuring, stderr error shape, --debug log format, -o vs --output-format, CLI-1546 spinner rule) survive unchanged.
  • docs/go-cli-divergences.md is declared a frozen historical record — new flags/features are just new CLI behavior and no longer tracked as divergences.

Docs-only change; no runtime behavior is affected.

Linked issue

Closes #

  • The linked issue is open and carries the open-for-contribution label (or I'm a Supabase maintainer).

Checklist

  • The PR title follows Conventional Commits (e.g. fix(cli): …).
  • Tests added or updated for the change. (Docs-only — not applicable.)
  • pnpm check:all and pnpm test pass for the workspace(s) I touched. (No code touched; no markdown checks in CI.)

🤖 Generated with Claude Code

@avallete@claude
docs(cli): make the TS legacy shell the source of truth in agent inst…
c86231e
…ructions
The Go->TS port is complete, so the agent instructions no longer treat the
Go CLI as the parity reference: src/legacy/ is the authoritative
implementation, apps/cli-go/ is documented as a residual delegation surface
slated for removal, and new "Go parity" framing in comments/docs is
explicitly disallowed. next/ is marked frozen and departing to its own
branch, with its porting-era guidance (reuse-from-next, phase 0 wrapping,
divergence tracking) removed or reframed around the legacy shell's own
established behavior.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@avallete
avallete requested a review from a team as a code ownerAugust 20, 2026 10:00
chatgpt-codex-connector[bot]
chatgpt-codex-connectorBot reviewed Aug 20, 2026
View reviewed changes

@chatgpt-codex-connectorchatgpt-codex-connectorBot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:c86231e569

ℹ️ 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".

Comment threadapps/cli/AGENTS.md Outdated
@github-actions

github-actionsBot commented Aug 20, 2026•
edited
Loading

Copy link
Copy Markdown
Contributor

Supabase CLI preview

npx --yes https://pkg.pr.new/supabase/cli/supabase@cacbba42a3020ba5bb6635623351571a1817b29d

Preview package for commit cacbba4.

@avallete@claude
docs(cli): require native replacements for retained wrapped commands …
96b99c2
…and fix formatting
Wrapper removal guidance no longer permits deleting user-facing command
trees: the CLI-1964 ruling keeps db branch/db remote/gen keys retained
indefinitely, so shrinking the Go delegation surface means native
replacement, and dropping a public command path stays a product decision.
Also runs oxfmt over the rewritten AGENTS.md to satisfy supabase:fmt:check.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
chatgpt-codex-connector[bot]
chatgpt-codex-connectorBot reviewed Aug 20, 2026
View reviewed changes

@chatgpt-codex-connectorchatgpt-codex-connectorBot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:96b99c28d8

ℹ️ 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".

Comment threadapps/cli/AGENTS.md Outdated
Comment threadapps/cli/AGENTS.md
Comment threadapps/cli/docs/go-cli-porting-status.md
@avallete@claude
docs(cli): reconcile Go-remnant lifecycle guidance across CLI docs
cacbba4
Follow-ups from review: native wrapper replacements must port from the
current in-tree Go source (the shipped implementation) rather than the
pre-trim pin, which already differs (db remote --password precedence);
the divergences ledger's own intro now states it is frozen so it agrees
with AGENTS.md; and binary-distribution.md now separates the two
lifecycles — retained public commands vs Go implementations slated for
native replacement, after which supabase-go stops shipping.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@avallete
avallete added this pull request to the merge queueAug 20, 2026
Merged via the queue into develop with commit 6aa7596Aug 20, 2026
44 checks passed
@avallete
avallete deleted the avallete/repos-agents-instructions-a7425f branch August 20, 2026 13:41
@supabase-cli-releasersupabase-cli-releaserBot mentioned this pull request Aug 25, 2026
Merged
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@chatgpt-codex-connectorchatgpt-codex-connector[bot]chatgpt-codex-connector[bot] left review comments
@jgouxjgouxjgoux approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@avallete@jgoux