Add comprehensive .github/copilot-instructions.md for AI-assisted development

[Copilot]

Adds repository-specific instructions to guide GitHub Copilot and AI coding assistants when working with this extension pack codebase.

What's Added

.github/copilot-instructions.md (758 lines) covering:

• Project architecture: Meta-extension pattern bundling 7 Java extensions, React/Redux webview implementation, TypeScript backend structure
• Core patterns: Extension orchestration (check availability before acting), webview message passing with telemetry, JDK detection via jdk-utils
• Developer workflows: npm commands, webpack dual-bundle configuration, debugging setup
• Code conventions: TypeScript style, java.* command namespacing, telemetry best practices (no PII), error handling
• Integration points: Bundled extension APIs, Maven/Gradle project detection, command execution patterns
• Critical gotchas: Extension load order, webview lifecycle (retainContextWhenHidden), cross-platform JDK paths, configuration scope hierarchy, activation event specificity
• Common scenarios: Step-by-step guides for adding commands (package.json → handler → telemetry), creating webviews, integrating external extensions
• Security & performance: HTML sanitization, workspace trust API, lazy loading, debouncing, caching strategies

Key Principles Documented

// Always validate bundled extension availability
import { isExtensionInstalled } from "./utils";

if (!isExtensionInstalled("vscjava.vscode-maven")) {
  await recommendExtension("vscjava.vscode-maven", "Maven extension required...");
  return;
}

// Use jdk-utils for cross-platform JDK detection
import { findRuntimes } from "jdk-utils";
const runtimes = await findRuntimes({ checkJavac: true });

// Message passing with telemetry
import { encodeCommandUriWithTelemetry } from "./utils/webview";
const uri = encodeCommandUriWithTelemetry("java.welcome", "createProject", "maven.archetype.generate");

Emphasizes this extension's UX coordination role rather than core language services, helping maintain clear separation of concerns across the bundled extension ecosystem.

Original prompt

Goal

Add a comprehensive .github/copilot-instructions.md file to guide GitHub Copilot and other AI coding assistants when working with this codebase.

Background

GitHub Copilot coding agent and Copilot Chat can use repository-specific instructions to provide better, more contextual assistance. This file helps AI understand:

• The project's architecture as an Extension Pack coordinator
• TypeScript + React + Redux webview patterns
• Integration patterns with bundled Java extensions
• Development workflow and testing requirements
• Code conventions and best practices

Requirements

Create .github/copilot-instructions.md with the following sections:

1. Project Overview

• Explain this is a meta-extension that bundles 7 Java extensions
• Clarify it provides coordination and UX features, not core language services
• List the bundled extensions

2. Architecture

• Document the src/ directory structure
• Explain key modules: commands, webviews, providers, utils
• Highlight the React/Redux webview architecture

3. Core Principles

• Extension Orchestration: Don't duplicate bundled extension functionality
• Webview Development: Message passing patterns, state management
• First-Time User Experience: Walkthrough API, configuration respect

4. Development Workflow

npm install
npm run compile
npm run watch
npm run build

5. Code Conventions

• TypeScript style (async/await, const over let)
• Naming conventions (java.* namespace)
• Error handling patterns
• Telemetry best practices (no PII)

6. Integration Points

• How to check bundled extension availability
• JDK detection using jdk-utils
• Maven/Gradle project detection
• Command execution patterns

7. Webview Guidelines

• Custom editor patterns (formatter settings)
• Redux state management
• Accessibility requirements
• Message passing protocol

8. Common Scenarios

• Adding a new command (registration in package.json → handler → telemetry)
• Creating a new webview page
• Integrating with external extensions

9. Critical Gotchas

• Extension pack load order
• Webview lifecycle and state persistence
• JDK path handling (cross-platform)
• Configuration scope hierarchy
• Activation event specificity

10. Performance Best Practices

• Lazy loading
• Debouncing UI events
• Caching expensive operations
• Proper disposal

11. Testing Checklist

• Extension activates without errors
• Commands work
• Webviews render correctly
• Works with missing bundled extensions

12. Security Considerations

• No arbitrary code execution
• HTML sanitization in webviews
• Path validation
• Workspace trust API

Style Guidelines

• Use clear, actionable language
• Include code examples for patterns
• Use emoji sparingly for visual hierarchy (🎯 🚀 ✅ 📝)
• Emphasize this extension is about developer experience and onboarding
• Use markdown code blocks with language hints

Success Criteria

• File is comprehensive but scannable
• Provides actionable guidance for both Copilot and human developers
• Covers extension-pack-specific patterns (not generic VS Code extension advice)
• Includes practical code examples
• Helps maintain consistency in contributions

Implementation Notes

• Place file at .github/copilot-instructions.md (standard location)
• Use markdown formatting
• Keep sections concise but informative
• Focus on what makes THIS project unique (extension pack orchestration, webview architecture, Java tooling integration)

This pull request was created as a result of the following prompt from Copilot chat.

Goal

Add a comprehensive .github/copilot-instructions.md file to guide GitHub Copilot and other AI coding assistants when working with this codebase.

Background

GitHub Copilot coding agent and Copilot Chat can use repository-specific instructions to provide better, more contextual assistance. This file helps AI understand:

• The project's architecture as an Extension Pack coordinator
• TypeScript + React + Redux webview patterns
• Integration patterns with bundled Java extensions
• Development workflow and testing requirements
• Code conventions and best practices

Requirements

Create .github/copilot-instructions.md with the following sections:

1. Project Overview

• Explain this is a meta-extension that bundles 7 Java extensions
• Clarify it provides coordination and UX features, not core language services
• List the bundled extensions

2. Architecture

• Document the src/ directory structure
• Explain key modules: commands, webviews, providers, utils
• Highlight the React/Redux webview architecture

3. Core Principles

• Extension Orchestration: Don't duplicate bundled extension functionality
• Webview Development: Message passing patterns, state management
• First-Time User Experience: Walkthrough API, configuration respect

4. Development Workflow

npm install
npm run compile
npm run watch
npm run build

5. Code Conventions

• TypeScript style (async/await, const over let)
• Naming conventions (java.* namespace)
• Error handling patterns
• Telemetry best practices (no PII)

6. Integration Points

• How to check bundled extension availability
• JDK detection using jdk-utils
• Maven/Gradle project detection
• Command execution patterns

7. Webview Guidelines

• Custom editor patterns (formatter settings)
• Redux state management
• Accessibility requirements
• Message passing protocol

8. Common Scenarios

• Adding a new command (registration in package.json → handler → telemetry)
• Creating a new webview page
• Integrating with external extensions

9. Critical Gotchas

• Extension pack load order
• Webview lifecycle and state persistence
• JDK path handling (cross-platform)
• Configuration scope hierarchy
• Activation event specificity

10. Performance Best Practices

• Lazy loading
• Debouncing UI events
• Caching expensive operations
• Proper disposal

11. Testing Checklist

• Extension activates without errors
• Commands work
• Webviews render correctly
• Works with missing bundled extensions

12. Security Considerations

• No arbitrary code execution
• HTML sanitization in webviews
• Path validation
• Workspace trust API

Style Guidelines

• Use clear, actionable language
• Include code examples for patterns
• Use emoji sparingly for visual hierarchy (🎯 🚀 ✅ 📝)
• Emphasize this extension is about developer experience and onboarding
• Use markdown code blocks with language hints

Success Criteria

• File is comprehensive but scannable
• Provides actionable guidance for both Copilot and human developers
• Covers extension-pack-specific patterns (not generic VS Code extension advice)
• Includes practical code examples
• Helps maintain consistency in contributions

Implementation Notes

• Place file at .github/copilot-instructions.md (standard location)
• Use markdown formatting
• Keep sections concise but informative
• Focus on what makes THIS project unique (extension pack orchestration, webview architecture, Java tooling integration)

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.