feat(core): update formatting of agent rules documentation by Stanzilla · Pull Request #33356 · nrwl/nx

Stanzilla · 2025-11-03T22:22:28Z

Markdown documents should only have one h1 header, it is pretty unlikely that an existing agents config does not already have one, switching to h2 instead should make most linters happy.

In theory you could make this a little smarter by checking beforehand..

I am also considering adding a line akin to

Never use `nx graph` command - This spawns a web server that you don't have access to. 
Use the `nx_visualize_graph` tool or other nx tools instead.

since mine keeps doing that. thoughts?

Current Behavior

The header is inserted as an h1

Expected Behavior

The header is inserted as an h2

Related Issue(s)

Fixes #

netlify · 2025-11-03T22:22:32Z

‼️ Deploy request for nx-docs rejected.

Name	Link
🔨 Latest commit	`118cab2`

vercel · 2025-11-03T22:22:35Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
nx-dev	Ready	Preview	Feb 3, 2026 11:10pm

MaxKless · 2025-11-04T08:42:27Z

I see what you mean... we decided for an h1 originally because then we can make sure that we're not messing with anyone's layout by nesting something where they don't want to.
I wasn't aware of this best practice to only ever use one h1 though, what kind of markdown linter are you using? Does it have that preconfigured?
I'm open to changing this in general though.

Stanzilla · 2025-11-04T08:53:29Z

I see what you mean... we decided for an h1 originally because then we can make sure that we're not messing with anyone's layout by nesting something where they don't want to. I wasn't aware of this best practice to only ever use one h1 though, what kind of markdown linter are you using? Does it have that preconfigured? I'm open to changing this in general though.

I'm on https://github.com/DavidAnson/markdownlint-cli2 (or rather the tooling around it) the rule is https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md025.md

Stanzilla · 2025-11-08T01:54:45Z

there are also spacing issues, currently it has two blank links before and after the snippet, which also triggers linters. so if we want to make it smarter it should

check if it is the only content of the file, if yes, no space before, use an h1 and then 1 or 0 empty lines after
if it is not the only content, use h2 with one space before and one after

Stanzilla · 2025-12-08T22:23:08Z

I now addressed that with an additional commit so it now dynamically adjusts spacing and header

Stanzilla · 2026-01-23T12:42:04Z

@MaxKless what do you think?

MaxKless · 2026-02-03T15:58:08Z

Hey sorry this fell through the cracks - I like the solution more.
The only thing that I'm worried about is if someone adds any content, the next update when using configure-ai-agents will be just a single ## -> # change which is so trivial.

Stanzilla · 2026-02-03T16:05:01Z

Hey sorry this fell through the cracks - I like the solution more. The only thing that I'm worried about is if someone adds any content, the next update when using configure-ai-agents will be just a single ## -> # change which is so trivial.

Hah okay, so how do you want to proceed here?

MaxKless · 2026-02-03T16:25:26Z

I think I'm okay with merging this if we add one more condition: the existing text has to have a # Header statement. This way it wouldn't change with just any addition to AGENTS.md but only if the user actually adds a h1 themselves.

Also, can you switch the implementation to be an object with options instead of adding a new option? I think this will become relevant in the future when we change some things around there in the codebase.

Also rebase pls. Thanks!

Stanzilla · 2026-02-03T16:35:09Z

I think I'm okay with merging this if we add one more condition: the existing text has to have a # Header statement. This way it wouldn't change with just any addition to AGENTS.md but only if the user actually adds a h1 themselves.

Also, can you switch the implementation to be an object with options instead of adding a new option? I think this will become relevant in the future when we change some things around there in the codebase.

Also rebase pls. Thanks!

how does this look?

nx-cloud · 2026-02-03T17:56:44Z

View your CI Pipeline Execution ↗ for commit 928cc76

Command	Status	Duration	Result
`nx affected --targets=lint,test,test-kt,build,e...`	✅ Succeeded	46m	View ↗
`nx run-many -t check-imports check-lock-files c...`	✅ Succeeded	3m 58s	View ↗
`nx-cloud record -- nx-cloud conformance:check`	✅ Succeeded	8s	View ↗
`nx-cloud record -- nx format:check`	✅ Succeeded	1s	View ↗
`nx-cloud record -- nx sync:check`	✅ Succeeded	<1s	View ↗

☁️ Nx Cloud last updated this comment at 2026-02-10 13:04:35 UTC

nx-cloud

Important

At least one additional CI pipeline execution has run since the conclusion below was written and it may no longer be applicable.

Nx Cloud has identified a possible root cause for your failed CI:

Our PR changes only affect agent rules documentation formatting (h1/h2 headers) in the nx package, while the failing tests are Gradle e2e tests in a completely different project. The failures are caused by an external service outage (foojay toolchain resolver returning 503 errors), not by our code changes. These tests should pass once the external service recovers.

No code changes were suggested for this issue.

You can trigger a rerun by pushing an empty commit:

git commit --allow-empty -m "chore: trigger rerun"
git push

View detailed reasoning on Nx Cloud ↗

_{🎓 Learn more about Self-Healing CI on nx.dev}

netlify · 2026-02-05T19:19:34Z

👷 Deploy request for nx-dev pending review.

Visit the deploys page to approve it

Name	Link
🔨 Latest commit	`928cc76`

Stanzilla · 2026-02-05T19:20:23Z

Addressed the review comments in b3e419b:

The update path now strips the nx block from the file and checks the rest of the document for an h1. This means it correctly determines the header level based on the surrounding content rather than blindly preserving what was there before.
If a user adds their own h1 header after initial setup, the next run will switch the nx block from h1 to h2 automatically.
Added tests covering: h2 idempotency (with external h1), h1-to-h2 switching when user adds their own h1, and run-twice-no-changes for fresh files, files with h1, and files without h1. All 33 tests pass.

MaxKless

LGTM! Thanks for your patience and the fast feedback cycles on reviews/discussions :) appreciate your efforts

MaxKless · 2026-02-09T14:44:45Z

can you push your branch again after a rebase? I think there have been some changes to netflify config which caused this to hang @Stanzilla

Stanzilla · 2026-02-09T15:22:42Z

can you push your branch again after a rebase? I think there have been some changes to netflify config which caused this to hang @Stanzilla

done!

Markdown documents should only have one h1 header, it is pretty unlikely that an existing agents config does not already have one, switching to h2 instead should make most linters happy. In theory you could make this a little smarter by checking beforehand..

- Use h1 header for standalone files, h2 when appending to existing content - Fix spacing: single blank line before/after when appending - Remove leading/trailing whitespace from template - Addresses MD025 (single h1) markdown lint rule # Conflicts: # packages/nx/src/ai/set-up-ai-agents/get-agent-rules.ts

…ng h1 - Refactor getAgentRules and getAgentRulesWrapped to use options objects for better extensibility - Only use h2 header when appending if the existing file already has an h1 header, preventing unnecessary changes for trivial additions - Add test for appending to files without existing h1 header

- When updating existing nx block, check the rest of the document for an h1 instead of blindly preserving the existing header level - Correctly switches h1 to h2 if user adds their own h1 later - Added tests for h2 idempotency, h1-to-h2 switching, and run-twice scenarios

(cherry picked from commit 0b6961b)

github-actions · 2026-02-16T00:16:20Z

This pull request has already been merged/closed. If you experience issues related to these changes, please open a new issue referencing this pull request.

Stanzilla requested a review from a team as a code owner November 3, 2025 22:22

Stanzilla requested a review from AgentEnder November 3, 2025 22:22

vercel Bot deployed to Preview November 3, 2025 22:29 View deployment

Stanzilla force-pushed the patch-1 branch from a2f1a36 to 3cc4688 Compare November 3, 2025 22:33

vercel Bot deployed to Preview November 3, 2025 22:37 View deployment

MaxKless self-assigned this Nov 4, 2025

Stanzilla force-pushed the patch-1 branch from 3cc4688 to eb537ed Compare December 8, 2025 21:12

vercel Bot deployed to Preview December 8, 2025 21:19 View deployment

Stanzilla force-pushed the patch-1 branch from eb537ed to dc7f291 Compare January 11, 2026 16:03

vercel Bot deployed to Preview January 11, 2026 16:08 View deployment

Stanzilla force-pushed the patch-1 branch from dc7f291 to 207ea08 Compare February 3, 2026 16:28

vercel Bot deployed to Preview February 3, 2026 16:42 View deployment

Stanzilla changed the title ~~Update formatting of agent rules documentation~~ feat(core): update formatting of agent rules documentation Feb 3, 2026

Stanzilla force-pushed the patch-1 branch from b4eead6 to 9732d8e Compare February 3, 2026 23:04

vercel Bot deployed to Preview February 3, 2026 23:10 View deployment

MaxKless requested changes Feb 5, 2026

View reviewed changes

Comment thread packages/nx/src/ai/set-up-ai-agents/set-up-ai-agents.ts Outdated

Comment thread packages/nx/src/ai/set-up-ai-agents/set-up-ai-agents.ts

nx-cloud Bot reviewed Feb 5, 2026

View reviewed changes

Stanzilla force-pushed the patch-1 branch from b3e419b to 3131b70 Compare February 5, 2026 20:39

MaxKless approved these changes Feb 6, 2026

View reviewed changes

Stanzilla force-pushed the patch-1 branch from 3131b70 to 118cab2 Compare February 9, 2026 15:22

Stanzilla added 4 commits February 9, 2026 23:10

Stanzilla force-pushed the patch-1 branch from 118cab2 to 928cc76 Compare February 9, 2026 22:10

MaxKless merged commit 0b6961b into nrwl:master Feb 10, 2026
15 of 16 checks passed

FrozenPandaz pushed a commit that referenced this pull request Feb 13, 2026

feat(core): update formatting of agent rules documentation (#33356)

7d5b859

(cherry picked from commit 0b6961b)

github-actions Bot locked as resolved and limited conversation to collaborators Feb 16, 2026

Stanzilla deleted the patch-1 branch February 16, 2026 00:25

Conversation

Stanzilla commented Nov 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Current Behavior

Expected Behavior

Related Issue(s)

Uh oh!

netlify Bot commented Nov 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

‼️ Deploy request for nx-docs rejected.

Uh oh!

vercel Bot commented Nov 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

MaxKless commented Nov 4, 2025

Uh oh!

Stanzilla commented Nov 4, 2025

Uh oh!

Stanzilla commented Nov 8, 2025

Uh oh!

Stanzilla commented Dec 8, 2025

Uh oh!

Stanzilla commented Jan 23, 2026

Uh oh!

MaxKless commented Feb 3, 2026

Uh oh!

Stanzilla commented Feb 3, 2026

Uh oh!

MaxKless commented Feb 3, 2026

Uh oh!

Stanzilla commented Feb 3, 2026

Uh oh!

nx-cloud Bot commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nx-cloud Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Nx Cloud has identified a possible root cause for your failed CI:

Uh oh!

netlify Bot commented Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

👷 Deploy request for nx-dev pending review.

Uh oh!

Stanzilla commented Feb 5, 2026

Uh oh!

MaxKless left a comment

Choose a reason for hiding this comment

Uh oh!

MaxKless commented Feb 9, 2026

Uh oh!

Stanzilla commented Feb 9, 2026

Uh oh!

Uh oh!

github-actions Bot commented Feb 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Stanzilla commented Nov 3, 2025 •

edited

Loading

netlify Bot commented Nov 3, 2025 •

edited

Loading

vercel Bot commented Nov 3, 2025 •

edited

Loading

nx-cloud Bot commented Feb 3, 2026 •

edited

Loading

nx-cloud Bot left a comment •

edited

Loading

netlify Bot commented Feb 5, 2026 •

edited

Loading