ENG-9646: Reflex Init --agents

[amsraman]

All Submissions:

• Have you followed the guidelines stated in CONTRIBUTING.md file?
• Have you checked to ensure there aren't any other open Pull Requests for the desired changed?

Type of change

Please delete options that are not relevant.

• New feature (non-breaking change which adds functionality)
• This change requires a documentation update

New Feature Submission:

• Does your submission pass the tests?
• Have you linted your code locally prior to submission?

After these steps, you're ready to open a pull request.

a. Give a descriptive title to your PR.

b. Describe your changes.

c. Put `closes #XXXX` in your comment to auto-close the issue that your PR fixes (if such).

[linear-code]

ENG-9646

[greptile-apps]

Greptile Summary

This PR introduces reflex init --agents (enabled by default), which fetches a canonical AGENTS.md from the reflex-dev/agent-skills repo and writes a Reflex-managed, marker-delimited section into the project root — preserving user content outside the markers on subsequent re-runs. A CLAUDE.md bridge importing @AGENTS.md is also created or updated for Claude Code users.

• AgentsMd constants are added to reflex_base.constants, _plan_agents_md selects which files to write based on the state of AGENTS.md/CLAUDE.md (missing, symlinked, or already importing), and _apply_agents_md_action handles new/refresh/malformed-marker cases.
• The --agents/--no-agents click flag (default True) is wired into reflex init and delegates to initialize_agents_md; a failed fetch warns and exits gracefully so init still succeeds offline.
• Docs are updated to describe the new auto-generation flow, and nine unit tests cover the full decision matrix including symlinks, malformed markers, and fetch failures.

Confidence Score: 5/5

Safe to merge after the open review threads (exception scope and branch URL) are addressed; the new code path degrades gracefully on failure and does not touch core init logic.

The feature is well-encapsulated, opt-out is supported via --no-agents, and a network failure is non-blocking. The one new finding (substring check for the CLAUDE.md bridge) is a low-probability edge case with no data-loss risk. The two previously flagged issues remain open but are tracked in earlier threads.

reflex/utils/frontend_skeleton.py for the @AGENTS.md bridge-detection heuristic; packages/reflex-base/src/reflex_base/constants/config.py for the feature-branch URL in CANONICAL_URL.

Important Files Changed

Filename	Overview
reflex/utils/frontend_skeleton.py	Adds initialize_agents_md with marker-preserving file management logic; the @AGENTS.md substring check for detecting an existing bridge import could match prose/comments in CLAUDE.md
packages/reflex-base/src/reflex_base/constants/config.py	Adds AgentsMd constants; CANONICAL_URL points to a feature branch (aditya/agentsmd) rather than main, already discussed in prior review thread
reflex/reflex.py	Adds --agents/--no-agents flag (default on) to init, correctly wired through to _init and initialize_agents_md
tests/units/utils/test_utils.py	Comprehensive unit tests covering create, refresh, malformed-marker repair, symlink, bridge, and dual-file cases; the fetch-failure test asserts console.warn is called, but httpx.ConnectError is not a subclass of httpx.HTTPError so the exception propagates unhandled (discussed in prior review thread)
packages/reflex-base/src/reflex_base/constants/init.py	Exports new AgentsMd constant class; no issues
docs/ai_builder/integrations/agents_md.md	Updated installation docs to describe the new automatic reflex init behavior and marker-preservation semantics
docs/getting_started/installation.md	Adds an AI-agent-targeted alert block with starter rules and a reference to reflex init auto-generating AGENTS.md

_{Reviews (8): Last reviewed commit: "Fix broken docs link and outdated AGENTS..." | Re-trigger Greptile}

[codspeed-hq]

Merging this PR will not alter performance

✅ 26 untouched benchmarks
⏩ 8 skipped benchmarks¹

---

_{Comparing aditya/init-agentsmd (d6ab0e2) with main (7b3a5c1)²}

Footnotes

1. 8 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

2. No successful run was found on main (beccb0d) during the generation of this report, so 7b3a5c1 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[adhami3310]

@greptile