ci: add copilot-instructions.md for AI coding agents

[BrendanWalsh]

What changes were proposed in this pull request?

Adds .github/copilot-instructions.md — a structured guide that helps AI coding agents (GitHub Copilot, Codex, Claude, Gemini) understand SynapseML's architecture and conventions.

Why this matters

SynapseML has several non-obvious patterns that AI agents consistently get wrong without explicit guidance:

• Code generation pipeline: Python wrappers are auto-generated from Scala via the Wrappable trait. Agents try to edit generated files.
• Scala-first architecture: Business logic goes in Scala, not Python. Agents default to editing Python.
• Trait mixin pattern: Parameters are defined in traits, composed into transformer classes.
• Required traits: Wrappable (for Python codegen), SynapseMLLogging (for telemetry), companion objects (for serialization).
• Pinned tooling: black==22.3.0, scalastyle with specific rules, conventional commit PR titles.

What's covered (245 lines)

Section	Content
Architecture	Module map, directory layout, inter-module dependencies
Code Generation Pipeline	How Wrappable → makePyFile() → _ClassName.py works, what to edit vs not
Scala Patterns	Complete transformer example, parameter traits, logging, cognitive module differences
Build System	sbt commands, Python style (black 22.3.0), scalastyle rules
Testing	ScalaTest patterns, TestBase trait, SparkSession setup, Python test paths
CI/CD	ADO vs GitHub Actions roles, PR title conventions
Common Mistakes	8 specific pitfalls with explanations

Research basis

Modeled after best practices from:

• PyTorch copilot-instructions.md
• HuggingFace Transformers copilot-instructions.md
• GitHub Blog: 5 tips for better custom instructions
• OpenAI AGENTS.md best practices
• Anthropic Claude Code best practices

Key principle: focus on traps and non-obvious patterns that agents get wrong, not generic project descriptions.

How was this patch tested?

Documentation-only change. The file is read automatically by GitHub Copilot when working on PRs and issues in this repository.

Does this PR introduce any user-facing change?

No — improves AI-assisted development experience for contributors.

[github-actions]

Hey @BrendanWalsh 👋!
Thank you so much for contributing to our repository 🙌.
Someone from SynapseML Team will be reviewing this pull request soon.

We use semantic commit messages to streamline the release process.
Before your pull request can be merged, you should make sure your first commit and PR title start with a semantic prefix.
This helps us to create release messages and credit you for your hard work!

Examples of commit messages with semantic prefixes:

• fix: Fix LightGBM crashes with empty partitions
• feat: Make HTTP on Spark back-offs configurable
• docs: Update Spark Serving usage
• build: Add codecov support
• perf: improve LightGBM memory usage
• refactor: make python code generation rely on classes
• style: Remove nulls from CNTKModel
• test: Add test coverage for CNTKModel

To test your commit locally, please follow our guild on building from source.
Check out the developer guide for additional guidance on testing your change.

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None