* Prepare for archiving of copilot-sdk-java repo in favor of java directory in copilot-sdk
* Update README
* Update with latest `java` from `copilot-sdk`.
### 16:37 Prompt
I have added `copilot-sdk-00` to this VS Code workspace. The `copilot-sdk-00/java` directory **is** the Copilot SDK for which this `copilot-sdk-java.instructions.md` is the instructions.
Do a deep read of the source code in `copilot-sdk-00/java`.
Do a deep read of the existing `copilot-sdk-java.instructions.md`.
Suggest any updates based on what should be changed in `copilot-sdk-java.instructions.md`, based on your findings.
### 16:51 Response
Now I have a comprehensive picture. Let me summarize the findings and suggest updates:
---
Based on my deep read of the Java SDK source code and the current copilot-sdk-java.instructions.md, here are the updates I'd suggest:
## Issues Found
### 1. Incorrect: `session.setModel()` documentation is slightly wrong
The instructions show `session.setModel(modelId)` — this is actually correct (it exists on CopilotSession), but the full signatures should be documented:
- `setModel(String model)`
- `setModel(String model, String reasoningEffort)`
- `setModel(String model, String reasoningEffort, ModelCapabilitiesOverride modelCapabilities)` *(since 1.3.0)*
### 2. Incorrect: `PreToolUseHookOutput` API
The instructions show:
```java
var decision = new PreToolUseHookOutput().setKind("allow");
```
But actually `PreToolUseHookOutput` is a **record** with static factory methods:
- `PreToolUseHookOutput.allow()`
- `PreToolUseHookOutput.deny()`
- `PreToolUseHookOutput.deny(String reason)`
- `PreToolUseHookOutput.ask()`
### 3. Missing: `CopilotClientOptions` fields not documented
These are in the source but not in the instructions:
- `setRemote(boolean)` — Mission Control integration
- `setTelemetry(TelemetryConfig)` — OpenTelemetry export *(since 1.2.0)*
- `setSessionIdleTimeoutSeconds(int)` — Idle timeout *(since 1.3.0)*
- `setExecutor(Executor)` — Custom thread pool
- `setTcpConnectionToken(String)` — TCP security token
### 4. Missing: `ToolDefinition.createSkipPermission()`
A third factory method exists *(since 1.2.0)* that skips the CLI permission request entirely. The instructions only mention `create()` and `createOverride()`.
### 5. Missing: Session listing with filters
The instructions show `client.listSessions()` but don't mention the overload with `SessionListFilter` that can filter by `cwd`, `gitRoot`, `repository`, and `branch`.
### 6. Missing: `session.log()` with URL
The instructions show `log(message, level, ephemeral)` but there's also a 4-param overload:
```java
session.log(String message, String level, Boolean ephemeral, String url)
```
### 7. Missing: MCP Server Configuration
The instructions mention `setMcpServers()` in the SessionConfig options list but don't show how to configure them. There are two types:
- `McpStdioServerConfig` — Local/stdio-based servers
- `McpHttpServerConfig` — HTTP/SSE remote servers
### 8. Missing: Cloud Sessions / Remote features
The `setRemote(boolean)` option on client options and per-session GitHub token support for cloud/content-exclusion scenarios.
### 9. Missing: `ModelCapabilitiesOverride`
Vision/image support can be controlled via model capabilities override, but this isn't documented.
### 10. Missing: `EventErrorPolicy` enum values
The instructions mention `EventErrorPolicy.SUPPRESS_AND_LOG_ERRORS` but don't list the other value: `PROPAGATE_AND_LOG_ERRORS` (which is the default).
### 11. Missing: `onLifecycle()` typed overload
There's also `onLifecycle(String eventType, SessionLifecycleHandler handler)` for filtering specific lifecycle events.
### 12. Minor: `send()` return type
`session.send()` returns `CompletableFuture<String>` (the message ID), which is worth mentioning since it can be used for correlation.
---
## Recommended Priority
**High priority** (incorrect info):
- Fix#2 (`PreToolUseHookOutput` API)
**Medium priority** (missing important features):
- Add #4 (`createSkipPermission`)
- Add #7 (MCP server configuration examples)
- Add #3 (missing client options)
- Add #5 (session list filters)
**Low priority** (nice-to-have completeness):
- Expand #1 (setModel overloads)
- Add #6 (log with URL)
- Add #9-12 (minor additions)
Would you like me to apply any or all of these updates to the file?
### 16:52 Prompt
Yes. Apply all of these.
### 16:54 Response
Created 12 todos
Now I have the full file. Let me apply all the changes:
Starting: *Fix PreToolUseHookOutput API (incorrect)* (1/12)
Replacing 84 lines with 199 lines in [](file:///e%3A/workareas/awesome-copilot-00/instructions/copilot-sdk-java.instructions.md)
```
```
Completed: *Fix PreToolUseHookOutput API (incorrect)* (1/12)
All 12 updates have been applied to copilot-sdk-java.instructions.md:
1. **Fixed** `PreToolUseHookOutput` — now uses correct static factory methods (`allow()`, `deny()`, `ask()`) instead of the incorrect `new PreToolUseHookOutput().setKind("allow")`
2. **Added** `ToolDefinition.createSkipPermission()` section (since 1.2.0)
3. **Added** 5 missing `CopilotClientOptions` fields: `remote`, `telemetry`, `sessionIdleTimeoutSeconds`, `executor`, `tcpConnectionToken`
4. **Added** `SessionListFilter` with `setRepository()`, `setBranch()`, `setCwd()`, `setGitRoot()`
5. **Expanded** `setModel()` to show all 3 overloads (model, reasoning effort, capabilities)
6. **Added** `log(message, level, ephemeral, url)` overload
7. **Added** full MCP server configuration section with `McpStdioServerConfig` and `McpHttpServerConfig` examples
8. **Added** `EventErrorPolicy` enum values with explanations
9. **Added** `onLifecycle(String eventType, handler)` filtered overload
10. **Added** note that `send()` returns `CompletableFuture<String>` (message ID for correlation)
11. **Added** `ModelCapabilitiesOverride` section with vision/limits configuration (since 1.3.0)
12. **Added** `remote` option for Mission Control / cloud session integration
13. **Bonus:** Expanded `SessionHooks` example to include all 5 hook types (`onPreToolUse`, `onPostToolUse`, `onUserPromptSubmitted`, `onSessionStart`, `onSessionEnd`)
Made changes.
### 16:54 Prompt
In the "## Core Principles" section. Add a bullet point that describes how `Optional` is used in the API.
### 16:58 Response
Searched for text `Optional` (`copilot-sdk-00` · `java/src/main/java/com/github/copilot/sdk/json/*.java`), 10 results
Searched for text `Optional` (`copilot-sdk-00` · `java/src/main/java/com/github/copilot/sdk/json/InfiniteSessionConfig.java`), 13 results
Replacing 7 lines with 8 lines in [](file:///e%3A/workareas/awesome-copilot-00/instructions/copilot-sdk-java.instructions.md)
```
```
Added the bullet point describing how `Optional<T>`, `OptionalInt`, and `OptionalDouble` are used on config class getters to distinguish "not set" from explicit values, while setters accept raw types and return `this` for fluent chaining.
Made changes.
### 16:58 Prompt
Consider this code from the Java README.
```java
public class CopilotSDK {
public static void main(String[] args) throws Exception {
var lastMessage = new String[]{null};
// Create and start client
try (var client = new CopilotClient()) { // JDK 25+: comment out this line
// JDK 25+: uncomment the following 3 lines for virtual thread support
// var options = new CopilotClientOptions()
// .setExecutor(Executors.newVirtualThreadPerTaskExecutor());
// try (var client = new CopilotClient(options)) {
client.start().get();
// Create a session
var session = client.createSession(
new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL).setModel("claude-sonnet-4.5")).get();
// Handle assistant message events
session.on(AssistantMessageEvent.class, msg -> {
lastMessage[0] = msg.getData().content();
System.out.println(lastMessage[0]);
});
// Handle session usage info events
session.on(SessionUsageInfoEvent.class, usage -> {
var data = usage.getData();
System.out.println("\n--- Usage Metrics ---");
System.out.println("Current tokens: " + data.currentTokens().intValue());
System.out.println("Token limit: " + data.tokenLimit().intValue());
System.out.println("Messages count: " + data.messagesLength().intValue());
});
// Send a message
var completable = session.sendAndWait(new MessageOptions().setPrompt("What is 2+2?"));
// and wait for completion
completable.get();
}
boolean success = lastMessage[0] != null && lastMessage[0].contains("4");
System.exit(success ? 0 : -1);
}
}
```
I want to get across the very important JDK 25 comment. What's the best place to encode that knowledge in the instructions?
* Apply review suggestions
* feat: add Azure resource naming conventions based on Microsoft CAF
* Potential fix for pull request finding
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
* docs: update Azure naming conventions with additional resource type patterns and constraints
Co-authored-by: Copilot <copilot@github.com>
* docs: add CAF acronym to ignore-words-list in codespell configuration
* Potential fix for pull request finding
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
* Potential fix for pull request finding
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---------
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <copilot@github.com>
* feat: add hooks authoring instruction
Add hooks.instructions.md with portable guidance for writing GitHub Copilot hooks:
- Folder structure, config schema, and all field documentation
- Script contract: stdin JSON, exit codes, stdout/stderr channels
- Payload schemas for all common events (sessionStart, sessionEnd, userPromptSubmitted, preToolUse, postToolUse, errorOccurred, agentStop)
- Per-event deny mechanisms (structured JSON for preToolUse, non-zero exit for others)
- Matcher support for host-level tool filtering
- Three impactful examples: commit gate, auto-format, dangerous command blocker
- Bash and PowerShell templates
- Cross-platform guidance (Python through both entries)
- Anti-patterns, design rules, and portability notes (GitHub Copilot vs Claude Code)
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fix: address PR review comments
- Document both toolArgs (JSON string) and tool_input/toolInput (object) variants with defensive parsing
- Update sessionStart stdout to reflect additionalContext injection support
- Document preToolUse stdout output fields: modifiedArgs/updatedInput, additionalContext
- Add matcher field note about local verification
- Remove undocumented notification event from event table
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fix: address round 2 review comments
- Defensive toolArgs parsing in all 3 example scripts (handle toolArgs string, tool_input, toolInput)
- PowerShell type check: test -is [string] before ConvertFrom-Json, init to null
- commit-gate.sh: add package.json existence guard before jq
- block-dangerous.sh: truncate command in deny reason and stderr to avoid leaking secrets
- Consistent defensive parsing helper across all Bash examples
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fix: handle toolArgs as string or object in jq, fix short_cmd scoping
- All 3 Bash example jq blocks now check toolArgs type before fromjson
- short_cmd defined before the deny/log branch to avoid set -u error
- Consistent defensive pattern across commit-gate, format-on-save, block-dangerous
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fix: remove accidentally committed agency.toml
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fix: expand Portability Note into CLI vs VS Code vs Cloud Agent section
Address Aaron's review: replace the thin portability bullet points with
a concrete comparison table covering what is the same (config schema,
event name casing, fields) and what differs (hook loading, shell
environment, tool argument field names). Add a 'How to write portable
hooks' checklist. Separate Claude Code into its own subsection.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fix: simplify to toolArgs-only parsing, clean portability section
- toolArgs is the documented contract — remove tool_input/toolInput defensive
fallbacks from all examples and the Script Contract template
- Simplify portability section: same config everywhere, one-line note about
cloud agent requiring default branch
- All 3 example scripts now use simple toolArgs pipe parsing
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* feat: add azure-functions-csharp.instructions.md
Added guidelines and best practices for building Azure Functions in C# using the isolated worker model.
* feat: add azure-durable-functions-csharp.instructions.md
Added guidelines and best practices for building Azure Durable Functions in C# using the isolated worker model.
* docs: add config & testing sections to durable functions instructions
Added detailed configuration and testing guidelines for Azure Durable Functions in C#.
* Fix capitalization in applyTo path for local.settings.json
Changed Local.settings.json to local.settings.json in the applyTo directive to match the actual filename used in Azure Functions projects.
* update through npm build
* feat(instructions): update security, a11y, and performance to 2025-2026 standards
Security: OWASP 2025 (55 anti-patterns, AI/LLM section, 6 frameworks)
Accessibility: WCAG 2.2 AA (38 anti-patterns, legal context EAA/ADA, 4 frameworks)
Performance: CWV (50 anti-patterns, Next.js 16, Angular 20, modern APIs)
* fix(instructions): use globalThis.scheduler to prevent ReferenceError
Access scheduler via globalThis to safely handle environments where
the Scheduling API is not declared as a global variable.
* fix(instructions): correct regex patterns and harden SSRF example
- AU1: anchor jwt.verify lookahead inside parentheses
- AU2: anchor jwt.sign lookahead, add expiresIn alternative
- AU7: fix greedy .* before negative lookahead in OAuth state check
- I5: resolve all DNS records, add TOCTOU production note
- K2: add closing delimiters and multi-digit support to tabindex regex
* fix(instructions): enhance SSRF IP validation with IPv4-mapped IPv6
Normalize IPv4-mapped IPv6 addresses (::ffff:127.0.0.1) before
checking private ranges, preventing bypass via mapped addresses.
* fix(instructions): add noscript fallback for deferred CSS pattern
Without JS, the media="print" + onload pattern leaves the stylesheet
inactive. The noscript tag loads it normally when JS is disabled.
* fix(instructions): add execFileSync to I3 command injection detection
The BAD example uses execFileSync but the regex only matched exec,
execSync, and execFile — missing the sync variant.
* fix(instructions): cover full IPv6 link-local range in SSRF check
fe80::/10 spans fe80-febf (fe8*, fe9*, fea*, feb*). Previous regex
only matched fe80::. Also use normalized variable for consistency.
* fix(instructions): adjust SSRF wording and downgrade reduced-motion severity
- SSRF: replace "full DNS/IP validation" with accurate wording that
acknowledges TOCTOU limitation
- V5: downgrade prefers-reduced-motion from IMPORTANT to SUGGESTION,
remove 2.2.2 (A) reference since it's an AAA enhancement
* fix(instructions): rename AU4 heading to include SHA-256
The heading said "Weak Password Hash (MD5/SHA1)" but the detection
regex and BAD example both use SHA-256. Renamed to "Fast Hash for
Passwords" which better describes the actual anti-pattern.
* fix(instructions): clarify WCAG 2.2 SC 4.1.1 status as obsolete
SC 4.1.1 Parsing is still present in the WCAG 2.2 spec but marked
as obsolete (always satisfied). Changed wording from "removed" to
"obsolete" for accuracy.
* fix(instructions): rename I1 example vars to avoid TS redeclaration
Copy-pasting the I1 SQL injection example as a single block failed with a
TypeScript redeclaration error because both BAD and GOOD snippets used
`const result`. Rename to `unsafeResult`/`safeResult` so the block remains
copy-pasteable into a single scope.
* fix(instructions): migrate I3 example to async execFile with bounds
The I3 command injection example used `execFileSync` in both BAD and GOOD
paths, which (a) redeclared `const output` in the same block and (b) blocks
the Node event loop in server handlers, amplifying DoS impact.
Switch the GOOD/BEST paths to a promisified `execFile` call with explicit
`timeout` and `maxBuffer` bounds, and rename variables to
`unsafeOutput`/`safeOutput` so the snippet stays copy-pasteable. Add a
trailing note recommending async child_process APIs for server code.
* fix(instructions): align AU6 heading with session fixation example
The AU6 heading claimed "Session Not Invalidated on Password Change" but
the mitigation example showed `req.session.regenerate`, which is the
canonical defense against session fixation on login rather than bulk
invalidation after a credential change.
Rename the anti-pattern to "Missing Session Regeneration on Login (Session
Fixation)" so it matches the example, and add a trailing note pointing to
the complementary practice of invalidating other active sessions for the
user on password change (e.g., via a `tokenVersion` counter).
* fix(instructions): make L1 critical CSS pattern CSP-compatible
The L1 "GOOD" snippet relied on an inline `onload="this.media='all'"`
handler on a `<link>` tag. Under a strict CSP that disallows
`'unsafe-inline'` / `script-src-attr 'unsafe-inline'`, inline event
handlers are blocked, so the stylesheet would never activate and users
would hit a styling regression.
Replace the pattern with build-time critical CSS extraction
(Critters/Beasties/Next.js `optimizeCss`) plus a normal
`<link rel="preload" as="style">` and standard `<link rel="stylesheet">`.
Add a trailing note explaining why the older inline-onload trick breaks
under strict CSP and how to defer non-critical CSS with an external
script when deferral is truly needed.
* Add draw-io diagram generator skill for awesome github copilot
* Add comprehensive shape libraries and style reference documentation for draw.io
- Introduced a new markdown file for draw.io shape libraries detailing various built-in shapes, their style keys, and usage.
- Added a complete style reference for `<mxCell>` elements, including universal style keys, shape-specific keys, edge styles, and color palettes.
- Included examples for common styles and shapes to aid users in creating diagrams effectively.
* Add draw-io diagram validation and shape addition scripts
* Add new diagram templates for flowchart, sequence, and UML class diagrams
- Created a flowchart template with a structured layout including start, steps, decision points, and end.
- Added a sequence diagram template illustrating interactions between a client, API server, and database with activation boxes and message arrows.
- Introduced a UML class diagram template featuring an interface, classes, attributes, methods, and relationships, including composition and realization.
* Add draw-io diagram generator skill to README with detailed usage instructions and bundled assets
* Add draw.io instructions with workflow, XML structure rules, style conventions, and validation checklist
* Add draw.io diagram standards to README instructions for enhanced diagram creation and editing
* Moving diagram templates to assets/ to follow agentskills structure
- Moved flowchart template with start, steps, decision points, and end nodes.
- Moved sequence diagram template illustrating interactions between a client, API server, and database.
- Moved UML class diagram template featuring an interface, classes, attributes, methods, and relationships.
* Clarify installation instructions for draw.io VS Code extension in SKILL.md
* Cleaned up some tool names
* Removing some instructionsThese instructions are no longer useful as the knowledge the add is already well handled by frontier models, so the instructions potentially provide conflicting or incorrect information to the agent while it undertakes a task
* Improved the skill to be more explicit on how to use playwright
* Removing a skill that is of low value
The information captured in this skill is mostly just what is found in the links that are at the top of the references, and thus the model will already have that knowledge available to it, meaning that the skill will potentially provide conflicting guidance to the agent as it works
* Updating readmes
Add tools for maximizing GitHub Copilot effectiveness through better
context management:
- Instructions: Guidelines for structuring code so Copilot understands it
- Agent: Context Architect - plans multi-file changes by mapping dependencies
- Prompts:
- context-map: Map all affected files before changes
- what-context-needed: Ask Copilot what files it needs
- refactor-plan: Create phased refactor plans with rollback steps
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Updated the instructionsUsage template in constants.mjs to clarify that task-specific instruction files should be created in the .github/instructions/ folder with the pattern *.instructions.md (e.g., .github/instructions/my-csharp-rules.instructions.md), instead of the confusing original wording that mentioned both .github/.instructions.md files and .github/instructions folder.
Co-authored-by: aaronpowell <434140+aaronpowell@users.noreply.github.com>
Ed Burns
Alvin Ashcraft
Petr Stupka
Gordon Lam
Sertxito
Mario Codes
Philippe D
Anmol Behl
Gonzalo Fleming
John Haugabook
Satya K
Daniel Scott-Raynsford
Marcel Deutzer
Aaron Powell
Niels Laute
icsaba
Bruno Borges
copilot-swe-agent[bot]
Roberto Perez
David Raygoza
Imran Siddique
Héctor Benedicte
Lance
4regab
vfaraji89
Michael Fairchild
garrettsiegel
Benji Shohet
Emerson Delatorre
Matt Soucoup