feat(core): generate AI files in create-nx-workspace

astro-docs/src/content/docs/getting-started/ai-setup.mdoc

@@ -6,7 +6,7 @@ sidebar:
   label: AI Integration
 ---
 
-Nx provides deep integration with AI coding assistants through the **Nx Model Context Protocol (MCP) server**, giving your AI assistant comprehensive understanding of your monorepo structure, running processes, and development workflows.
+Nx provides deep integration with AI coding assistants through the **Nx Model Context Protocol (MCP) server**, giving your AI assistant comprehensive understanding of your monorepo structure, running processes, and development workflows. When you create a new Nx workspace, it includes AI agent configuration files (`CLAUDE.md` and `GEMINI.md`) that provide guidelines for working with Nx and the Nx MCP server.
 
 ## Setup and Configuration
 

docs/generated/manifests/menus.json

@@ -5875,6 +5875,14 @@
                         "children": [],
                         "isExternal": false,
                         "disableCollapsible": false
+                      },
+                      {
+                        "id": "set-up-ai-agents",
+                        "path": "/reference/core-api/workspace/generators/set-up-ai-agents",
+                        "name": "set-up-ai-agents",
+                        "children": [],
+                        "isExternal": false,
+                        "disableCollapsible": false
                       }
                     ],
                     "isExternal": false,

docs/generated/manifests/new-nx-api.json

@@ -5881,6 +5881,15 @@
         "originalFilePath": "/packages/workspace/src/generators/infer-targets/schema.json",
         "path": "/reference/core-api/workspace/generators/infer-targets",
         "type": "generator"
+      },
+      "/reference/core-api/workspace/generators/set-up-ai-agents": {
+        "description": "Sets up the Nx MCP & rule files for common AI Agents",
+        "file": "generated/packages/workspace/generators/set-up-ai-agents.json",
+        "hidden": true,
+        "name": "set-up-ai-agents",
+        "originalFilePath": "/packages/workspace/src/generators/set-up-ai-agents/schema.json",
+        "path": "/reference/core-api/workspace/generators/set-up-ai-agents",
+        "type": "generator"
       }
     },
     "migrations": {

docs/generated/packages/workspace/generators/set-up-ai-agents.json

@@ -0,0 +1,36 @@
+{
+  "name": "set-up-ai-agents",
+  "factory": "./src/generators/set-up-ai-agents/set-up-ai-agents",
+  "schema": {
+    "$schema": "https://json-schema.org/schema",
+    "$id": "SetupAiAgents",
+    "title": "Set Up AI Agents",
+    "description": "Sets up the Nx MCP & rule files for common AI Agents.",
+    "type": "object",
+    "properties": {
+      "directory": {
+        "type": "string",
+        "description": "Directory where the AI agent configuration files will be generated",
+        "default": "."
+      },
+      "writeNxCloudRules": {
+        "type": "boolean",
+        "description": "Whether to write Nx Cloud rules",
+        "default": false
+      },
+      "packageVersion": {
+        "type": "string",
+        "description": "The version of the package to use",
+        "default": "next"
+      }
+    },
+    "required": ["directory"],
+    "presets": []
+  },
+  "description": "Sets up the Nx MCP & rule files for common AI Agents",
+  "hidden": true,
+  "implementation": "/packages/workspace/src/generators/set-up-ai-agents/set-up-ai-agents.ts",
+  "aliases": [],
+  "path": "/packages/workspace/src/generators/set-up-ai-agents/schema.json",
+  "type": "generator"
+}

docs/shared/getting-started/ai-setup.md

@@ -5,7 +5,7 @@ description: Set up Nx MCP server to give AI assistants deep workspace context,
 
 # Integrate Nx with your Coding Assistant
 
-Nx provides deep integration with AI coding assistants through the **Nx Model Context Protocol (MCP) server**, giving your AI assistant comprehensive understanding of your monorepo structure, running processes, and development workflows.
+Nx provides deep integration with AI coding assistants through the **Nx Model Context Protocol (MCP) server**, giving your AI assistant comprehensive understanding of your monorepo structure, running processes, and development workflows. When you create a new Nx workspace, it includes AI agent configuration files (`CLAUDE.md` and `GEMINI.md`) that provide guidelines for working with Nx and the Nx MCP server.
 
 ## Setup and Configuration
 

docs/shared/reference/sitemap.md

@@ -710,6 +710,7 @@
           - [npm-package](/reference/core-api/workspace/generators/npm-package)
           - [ci-workflow](/reference/core-api/workspace/generators/ci-workflow)
           - [infer-targets](/reference/core-api/workspace/generators/infer-targets)
+          - [set-up-ai-agents](/reference/core-api/workspace/generators/set-up-ai-agents)
         - [migrations](/reference/core-api/workspace/migrations)
       - [owners](/reference/core-api/owners)
         - [Overview](/reference/core-api/owners/overview)

packages/create-nx-workspace/src/create-workspace.ts

@@ -1,21 +1,21 @@
-import { CreateWorkspaceOptions } from './create-workspace-options';
-import { output } from './utils/output';
-import {
-  createNxCloudOnboardingUrl,
-  getNxCloudInfo,
-  readNxCloudToken,
-} from './utils/nx/nx-cloud';
-import { createSandbox } from './create-sandbox';
 import { createEmptyWorkspace } from './create-empty-workspace';
 import { createPreset } from './create-preset';
+import { createSandbox } from './create-sandbox';
+import { CreateWorkspaceOptions } from './create-workspace-options';
 import { setupCI } from './utils/ci/setup-ci';
+import { mapErrorToBodyLines } from './utils/error-utils';
 import {
   initializeGitRepo,
   pushToGitHub,
   VcsPushStatus,
 } from './utils/git/git';
+import {
+  createNxCloudOnboardingUrl,
+  getNxCloudInfo,
+  readNxCloudToken,
+} from './utils/nx/nx-cloud';
+import { output } from './utils/output';
 import { getPackageNameFromThirdPartyPreset } from './utils/preset/get-third-party-preset';
-import { mapErrorToBodyLines } from './utils/error-utils';
 import { Preset } from './utils/preset/preset';
 
 export async function createWorkspace<T extends CreateWorkspaceOptions>(

packages/nx/src/utils/package-manager.ts

@@ -416,17 +416,23 @@ export function copyPackageManagerConfigurationFiles(
  * For cases where you'd want to install packages that require an `.npmrc` set up,
  * this function looks up for the nearest `.npmrc` (if exists) and copies it over to the
  * temp directory.
+ *
+ * @param skipCopy - If true, skips copying package manager configuration files to the temporary directory.
+ *                   This is useful when creating a workspace from scratch (e.g., in create-nx-workspace)
+ *                   where no existing configuration files are available to copy.
  */
-export function createTempNpmDirectory() {
+export function createTempNpmDirectory(skipCopy = false) {
   const dir = dirSync().name;
 
   // A package.json is needed for pnpm pack and for .npmrc to resolve
   writeJsonFile(`${dir}/package.json`, {});
-  const isNonJs = !existsSync(join(workspaceRoot, 'package.json'));
-  copyPackageManagerConfigurationFiles(
-    isNonJs ? getNxInstallationPath(workspaceRoot) : workspaceRoot,
-    dir
-  );
+  if (!skipCopy) {
+    const isNonJs = !existsSync(join(workspaceRoot, 'package.json'));
+    copyPackageManagerConfigurationFiles(
+      isNonJs ? getNxInstallationPath(workspaceRoot) : workspaceRoot,
+      dir
+    );
+  }
 
   const cleanup = async () => {
     try {

packages/workspace/generators.json

@@ -59,6 +59,12 @@
       "factory": "./src/generators/infer-targets/infer-targets",
       "schema": "./src/generators/infer-targets/schema.json",
       "description": "Convert Nx projects to use inferred targets."
+    },
+    "set-up-ai-agents": {
+      "factory": "./src/generators/set-up-ai-agents/set-up-ai-agents",
+      "schema": "./src/generators/set-up-ai-agents/schema.json",
+      "description": "Sets up the Nx MCP & rule files for common AI Agents",
+      "hidden": true
     }
   }
 }

packages/workspace/src/generators/new/__snapshots__/generate-workspace-files.spec.ts.snap

@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`@nx/workspace:generateWorkspaceFiles README.md Nx Cloud (github) should be created for AngularMonorepo preset 1`] = `
 "# Proj
@@ -5726,6 +5726,7 @@ These targets are either [inferred automatically](https://nx.dev/concepts/inferr
 While you could add new projects to your workspace manually, you might want to leverage [Nx plugins](https://nx.dev/concepts/nx-plugins?utm_source=nx_project&utm_medium=readme&utm_campaign=nx_projects) and their [code generation](https://nx.dev/features/generate-code?utm_source=nx_project&utm_medium=readme&utm_campaign=nx_projects) feature.
 
 To install a new plugin you can use the \`nx add\` command. Here's an example of adding the React plugin:
+
 \`\`\`sh
 npx nx add @nx/react
 \`\`\`
@@ -5786,6 +5787,7 @@ Learn more:
 - [What are Nx plugins?](https://nx.dev/concepts/nx-plugins?utm_source=nx_project&utm_medium=readme&utm_campaign=nx_projects)
 
 And join the Nx community:
+
 - [Discord](https://go.nx.dev/community)
 - [Follow us on X](https://twitter.com/nxdevtools) or [LinkedIn](https://www.linkedin.com/company/nrwl)
 - [Our Youtube channel](https://www.youtube.com/@nxdevtools)

packages/workspace/src/generators/new/generate-workspace-files.ts

@@ -16,6 +16,7 @@ import { deduceDefaultBase } from '../../utilities/default-base';
 import { nxVersion } from '../../utils/versions';
 import { Preset } from '../utils/presets';
 import type { NormalizedSchema } from './new';
+import { setupAiAgentsGenerator } from '../set-up-ai-agents/set-up-ai-agents';
 
 type PresetInfo = {
   generateAppCmd?: string;
@@ -184,6 +185,12 @@ export async function generateWorkspaceFiles(
 
   await createReadme(tree, options, token);
 
+  await setupAiAgentsGenerator(tree, {
+    directory: options.directory,
+    writeNxCloudRules: options.nxCloud !== 'skip',
+    packageVersion: 'latest',
+  });
+
   const [packageMajor] = packageManagerVersion.split('.');
   if (options.packageManager === 'pnpm' && +packageMajor >= 7) {
     if (gte(packageManagerVersion, '10.6.0')) {

packages/workspace/src/generators/set-up-ai-agents/files/__agent__.md.template

@@ -0,0 +1,18 @@
+# General Guidelines for working with Nx 
+
+- When running tasks (for example build, lint, test, e2e, etc.), always prefer running the task through `nx` (i.e. `nx run`,`nx run-many`, `nx affected`) instead of using the underlying tooling directly
+- You have access to the Nx MCP server and its tools, use them to help the user
+- When answering questions about the repository, use the `nx_workspace` tool first to gain an understanding of the workspace architecture where applicable.
+- When working in individual projects, use the `nx_project_details` mcp tool to analyze and understand the specific project structure and dependencies
+- For questions around nx configuration, best practices or if you're unsure, use the `nx_docs` tool to get relevant, up-to-date docs. Always use this instead of assuming things about nx configuration
+- If the user needs help with an Nx configuration or project graph error, use the `nx_workspace` tool to get any errors
+
+<% if(writeNxCloudRules === true){ %>
+# CI Error Guidelines
+
+If the user wants help with fixing an error in their CI pipeline, use the following flow:
+- Retrieve the list of current CI Pipeline Executions (CIPEs) using the `nx_cloud_cipe_details` tool
+- If there are any errors, use the `nx_cloud_fix_cipe_failure` tool to retrieve the logs for a specific task
+- Use the task logs to see what's wrong and help the user fix their problem. Use the appropriate tools if necessary
+- Make sure that the problem is fixed by running the task that you passed into the `nx_cloud_fix_cipe_failure` tool
+<% } %>

packages/workspace/src/generators/set-up-ai-agents/schema.d.ts

@@ -0,0 +1,8 @@
+export type SetupAiAgentsGeneratorSchema = {
+  directory: string;
+  writeNxCloudRules?: boolean;
+  packageVersion?: string;
+};
+
+export type NormalizedSetupAiAgentsGeneratorSchema =
+  Required<SetupAiAgentsGeneratorSchema>;

packages/workspace/src/generators/set-up-ai-agents/schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "$id": "SetupAiAgents",
+  "title": "Set Up AI Agents",
+  "description": "Sets up the Nx MCP & rule files for common AI Agents.",
+  "type": "object",
+  "properties": {
+    "directory": {
+      "type": "string",
+      "description": "Directory where the AI agent configuration files will be generated",
+      "default": "."
+    },
+    "writeNxCloudRules": {
+      "type": "boolean",
+      "description": "Whether to write Nx Cloud rules",
+      "default": false
+    },
+    "packageVersion": {
+      "type": "string",
+      "description": "The version of the package to use",
+      "default": "next"
+    }
+  },
+  "required": ["directory"]
+}