use AGENTS.md for agent to work on the emitter, add SKILL for "validate-dev-build"

.github/skills/validate-dev-build/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: validate-dev-build
+description: Build the emitter with dev dependencies, and validate end-to-end tests
+argument-hint: [test-case]
+---
+
+## Update Node.js dependencies to dev
+
+Read "typespec-extension/package.json", if it does not depends on a dev version of `@typespec/compiler` (e.g. `X-dev.Y`), run following command on repository root:
+```
+npx -y @azure-tools/typespec-bump-deps typespec-extension/package.json typespec-tests/package.json --add-npm-overrides
+```
+
+Under "typespec-extension" folder, run `npm install --force` to install the dev dependencies.
+
+## Prepare end-to-end test environment
+
+Under "typespec-tests" folder, run `Setup.ps1`.
+
+## Generate end-to-end test code
+
+Under "typespec-tests" folder.
+
+`[test-case]` usually in the form of an URL, e.g. "https://github.com/Azure/typespec-azure/tree/main/packages/azure-http-specs/specs/azure/client-generator-core/override"
+
+Map this URL to the location of the test case in "node_modules".
+E.g. above would map to "node_modules/@azure-tools/azure-http-specs/specs/azure/client-generator-core/override/client.tsp"
+
+URL "https://github.com/microsoft/typespec/tree/main/packages/http-specs/specs/encode/array" would map to "node_modules/@typespec/http-specs/specs/encode/array/main.tsp"
+
+- Use "client.tsp" when available. Otherwise, use "main.tsp".
+- Escape the `@`, if it is necessary to do so in terminal.
+
+Run
+```
+tsp compile --config . [location-of-test-case]
+```
+to generate Java code.

AGENTS.md

@@ -0,0 +1,58 @@
+# Development
+
+The emitter is the [TypeSpec](https://typespec.io/) library for emitting Java client from the TypeSpec REST protocol binding.
+
+See [Emitter](https://typespec.io/docs/extending-typespec/emitters-basics/) for the basics on the TypeSpec emitter library.
+
+See [Developer Guide for TypeSpec Emitter](docs/developer/typespec/readme.md) for basics on this repository.
+
+Guideline:
+
+- Most of the development work should happen in "core/packages/http-client-java" folder.
+- Before starting the development in "core" folder, always checkout latest code from main branch, and create a dev branch upon it.
+- When checking in code in "core" folder, do not check-in the files in "core.patch".
+- When preparing the PR, create 2 PRs, one for the code changes in submodule ("typespec" repository, if there is change), one for the code changes in this repository (which would include the update on "core" submodule).
+
+## TypeScript Part for the Emitter
+
+TypeScript code for the Emitter is in "core/packages/http-client-java/emitter" folder. Follow the package.json for the build and unit test.
+
+The code there, in runtime, produces a "code-model.yaml" file, and passes it to Java Part to generate Java client.
+
+## Java Part for the Emitter
+
+Java code for the Emitter is in "core/packages/http-client-java/generator/http-client-generator" (which depends on "http-client-generator-core" and "http-client-generator-mgmt" module). Follow the pom.xml for the build and unit test.
+
+The code there, in runtime, consumes the "code-model.yaml" file produced by the TypeSpec Part, and generate the Java client.
+
+# Update and Release
+
+## Update Node.js Package for Latest Dependencies
+
+Instructions:
+- Always use absolute path when change directory.
+
+Steps:
+
+1. In "core" folder, run `git pull upstream main` to fetch latest commit from upstream or origin.
+2. Go back to project root. Commit the change in "core" folder.
+3. Run `ncu -u` on "package.json" in both "package.json" from "typespec-extension" and "typespec-tests" folder.
+4. Update package versions in `peerDependencies` (keep the semver range) in "package.json" from "typespec-extension" folder, according to the corresponding package versions in `devDependencies`.
+5. Update package versions in `override` (keep the semver range) in "package.json" from "typespec-tests" folder, according to the corresponding package versions in "package.json" from "typespec-extension" folder.
+6. Save the files, and run `npm install` in "typespec-extension" folder, so that "package-lock.json" would be updated.
+7. Commit the changes in "typespec-extension" and "typespec-tests" folders.
+8. Run `pwsh SyncTests.ps1` in "typespec-tests" folder.
+9. Commit the changes in "typespec-tests" folder, include new files.
+
+## Prepare for Minor/Patch Release
+
+Steps:
+
+1. Bump minor/patch version of `@typespec/typespec-java` in both "package.json" from "typespec-extension" and "typespec-tests" folder.
+2. Save the file, and run `npm install` in "typespec-extension" folder, so that "package-lock.json" would be updated.
+3. Add a new item in release history in "typespec-extension/changelog.md". The version would be the minor/patch version. The date would be today.
+
+The [publish to NPM pipeline](https://dev.azure.com/azure-sdk/internal/_build?definitionId=5618) needs to be triggered, after the PR is merged.
+
+After release, the [sync SDK pipeline](https://dev.azure.com/azure-sdk/internal/_build?definitionId=6270) needs to be triggered, to sync the released typespec-java into the SDK repository.
+This pipeline also regenerates all SDK based on TypeSpec.

docs/developer/typespec/readme.md

@@ -8,6 +8,8 @@ As [NPM package](https://www.npmjs.com/package/@azure-tools/typespec-java), it i
 
 At present, almost all the code of the emitter is in [microsoft/typespec repository](https://github.com/microsoft/typespec/tree/main/packages/http-client-java).
 
+This repository is checked out at `core` folder as submodule.
+
 ### Build
 
 NPM package is in `typespec-extension` folder.

readme.md

@@ -15,7 +15,7 @@ npm install -g autorest
 ```
 
 # Usage
-To use the latest released preview(https://github.com/Azure/autorest.java/releases), run
+To use the latest released preview (https://github.com/Azure/autorest.java/releases), run
 ```bash
 autorest --java
     --use:@autorest/java@4.x.x
@@ -45,7 +45,7 @@ autorest --java
 
 Java files will be generated under `where/to/generate/java/files/src/main/java/specified/java/package`.
 
-To debug, add `--java.debugger` to the argument list. The JVM will suspend at the beginning of the execution. Then attach a remote debugger in your IDE to `localhost:5005`. **Make sure you detach the debugger before killing the AutoRest process. Otherwise it will fail to shutdown the JVM and leave it orphaned. (which can be killed in the Task Manager)**
+To debug, add `--java.debugger` to the argument list. The JVM will suspend at the beginning of the execution. Then attach a remote debugger in your IDE to `localhost:5005`. **Make sure you detach the debugger before killing the AutoRest process. Otherwise it will fail to shut down the JVM and leave it orphaned. (which can be killed in the Task Manager)**
 
 # Recommended Settings