Add comprehensive AI assistant instructions for HPCC-JS-WASM repository

[Copilot]

Overview

This PR adds comprehensive copilot instructions to help future AI assistants (GitHub Copilot, ChatGPT, Claude, etc.) understand and work effectively with the HPCC-JS-WASM monorepo.

Problem

The HPCC-JS-WASM repository has a complex structure with:

• 8 different WebAssembly packages
• Complex C++ to WASM build pipeline using Emscripten
• Lerna monorepo with interdependent packages
• Multiple testing environments (browser + Node.js)
• Build failures that are expected in fresh clones

Without proper guidance, AI assistants often struggle to:

• Understand the monorepo architecture
• Navigate the complex build system
• Diagnose common build/test failures
• Provide accurate development workflows
• Handle package-specific patterns correctly

Solution

Added comprehensive AI assistant documentation:

📁 Root-level Instructions

• .copilot-summary.md - Navigation guide for all instructions
• .copilot-instructions.md - Repository overview and architecture (6.6KB)
• .copilot-workflow.md - Step-by-step development workflows (6.6KB)
• .copilot-patterns.md - Package usage patterns and quick reference (6.6KB)
• .copilot-troubleshooting.md - Comprehensive debugging guide (8.8KB)

📦 Package-specific Instructions

• packages/graphviz/.copilot-package.md - Graphviz-specific guidance (6.7KB)
• packages/duckdb/.copilot-package.md - DuckDB-specific guidance (10.5KB)

⚙️ IDE Integration

• Updated .vscode/settings.json with AI-friendly configurations
• Updated main README.md to reference copilot instructions

Key Features

🏗️ Architecture Understanding

// All packages follow this loading pattern
import { Graphviz } from "@hpcc-js/wasm-graphviz";
const graphviz = await Graphviz.load();
const svg = graphviz.dot('digraph G { a -> b }');

🔧 Development Workflows

• TypeScript-only changes: npm ci → npm run build-ws → npm run lint
• Full development: npm run install-build-deps → npm run build-cpp → npm run build-ws
• Troubleshooting: Detailed error patterns and solutions

🎯 Package Patterns

Clear guidance for each WASM library:

• Graphviz: Graph visualization with DOT language
• DuckDB: Embedded SQL database for analytics
• Base91: Efficient binary encoding
• Zstd: Fast compression
• Expat: XML parsing
• Llama: AI model inference

🐛 Troubleshooting Coverage

• "Failed to resolve entry for package" → Missing builds
• "Executable doesn't exist" → Playwright setup needed
• WASM loading failures → C++ compilation required
• Memory issues → Environment-specific guidance

Validation

✅ Linting passes: All code style checks pass
✅ Expected behavior: Build failures documented and explained
✅ TypeScript works: Packages can be developed without full WASM builds
✅ Comprehensive coverage: ~38KB of detailed guidance

Benefits for Future AI Sessions

1. Faster onboarding - AI assistants can quickly understand the repository
2. Accurate guidance - Detailed workflows prevent common mistakes
3. Better debugging - Comprehensive troubleshooting for typical issues
4. Package expertise - Specific guidance for each WASM library
5. Build awareness - Clear understanding of what requires full vs. partial builds

Example Usage

When an AI assistant encounters this repository, they can:

# Quick health check
git status && npm ls --depth=0

# Follow TypeScript-only workflow for code changes
npm ci && npm run build-ws && npm run lint

# Use troubleshooting guide for build failures
# Understand that WASM-related failures are expected in fresh clones

This documentation significantly improves the AI assistant experience when working with this complex WebAssembly monorepo.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[GordonSmith]

Move the instructions into .github/instructions folder and use the apply frontmatter to restrict their scope if needed

[Copilot]

Move the instructions into .github/instructions folder and use the apply frontmatter to restrict their scope if needed

Moved all copilot instructions to .github/instructions/ folder as requested. Updated file names and all references in README.md accordingly. (6d09dab)