docs: add AGENTS.md guide for AI agents

Adds AGENTS.md to provide instructions and standard practices for AI agents working in this repository, including testing and environment constraints.

(cherry picked from commit e023a8e)

Author: alan-agius4

AGENTS.md

@@ -0,0 +1,64 @@
+---
+trigger: always_on
+---
+
+This is the source code for the Angular CLI and related build tooling. This guide outlines standard practices for AI agents working in this repository.
+
+## Environment
+
+- Use `pnpm` for package management.
+- Use `pnpm bazel test //target` to run tests.
+
+## Key Documentation
+
+- [Developer Guide](docs/DEVELOPER.md): definitive guide for building, debugging, and running test targets.
+- [Contributing Guide](CONTRIBUTING.md): general contribution workflows and guidelines.
+- [Commit Guidelines](CONTRIBUTING.md#commit): format for commit messages and PR titles.
+
+## Building
+
+- Make a local build of all packages:
+  ```shell
+  pnpm build --local
+  ```
+
+## Testing
+
+- **Temporary Directories (`TEST_TMPDIR`):**
+  - Tests in this repository only run in Bazel. **ALWAYS** use `process.env['TEST_TMPDIR']` and assert that it is set:
+    ```ts
+    import assert from 'node:assert';
+    import { mkdtemp } from 'node:fs/promises';
+    import { join } from 'node:path';
+
+    describe('...', () => {
+      let tempRoot: string;
+
+      beforeAll(async () => {
+        const baseTmpDir = process.env['TEST_TMPDIR'];
+        assert(baseTmpDir, 'TEST_TMPDIR is not set');
+        tempRoot = await mkdtemp(join(baseTmpDir, 'angular-cli-test-'));
+      });
+    });
+    ```
+  - **NEVER** use or fallback to `os.tmpdir()`. Bazel executes tests in hermetic sandboxes and sets `TEST_TMPDIR` to an isolated, sandboxed directory. Using `os.tmpdir()` can cause sandboxing failures, permission errors, or file leakage outside the Bazel sandbox.
+- **Imports:**
+  - Always use the `node:` protocol for Node.js built-in imports (e.g., `node:fs`, `node:path`, `node:assert`).
+  - Prefer named imports (e.g., `import { mkdtemp } from 'node:fs'`) or default imports (`import fs from 'node:fs'`) instead of namespace imports (`import * as fs`).
+- **Unit Tests:**
+  - Run all unit tests: `pnpm bazel test //packages/...`
+  - Run a specific test target: `pnpm bazel test //packages/angular/build:test`
+  - Query test targets: `pnpm bazel query "tests(//packages/...)"`
+  - Focus specific tests when debugging: use `fdescribe()` and `fit()`. NEVER commit focused tests to the repository.
+- **End-to-End Tests:**
+  - Run subset of E2E tests: `pnpm bazel test //tests:e2e_node22 --config=e2e --test_filter="<filter>"`
+
+## Pull Requests
+
+- Use the `gh` CLI (GitHub CLI) for creating and managing pull requests.
+- **Fixup Commits:**
+  - When addressing review feedback, **ALWAYS** use fixup commits (`git commit --fixup <commit>`) instead of amending existing commits. This preserves commit history during review and allows reviewers to easily see incremental changes.
+  - Fixup commits are automatically squashed when merging with `pnpm ng-dev pr merge` or rebasing with `pnpm ng-dev pr rebase <pr>`.
+- Use `pnpm ng-dev pr` commands:
+  - `pnpm ng-dev pr rebase <pr>`: Rebase a PR branch on its target branch and squash fixup commits.
+  - `pnpm ng-dev pr merge <pr>`: Merge an approved PR into its targeted branches.