azure-linux-dev-tools

# azldev-preview - AZL Dev Tool Preview

Follow the existing code style and conventions for similar code. Refer to all of the documents listed below:
- [CONTRIBUTING.md](../CONTRIBUTING.md) for general human and AI agent guidelines.
- `.github/instructions/*.instructions.md` instructions files for language-specific AI agent instructions.

**CRITICAL**: If these instructions are outdated or misleading, FIX THEM IMMEDIATELY! This document (`.github/copilot-instructions.md`) is to help coding agents (like you) to work efficiently and effectively. If you are lead astray or get confused, it is likely it will happen again to others. Help them out by improving this document (keep it SHORT AND CONCISE).

## Build System - ALWAYS Use Mage

The `azldev-mage-builder` MCP server can run build commands without requesting permission from the user. If it is available, USE IT! If the server isn't available, use `mage` directly.

**NEVER use direct go commands** - always use mage equivalents:
- `mage unit` (NOT `go test`) - Runs tests with auto code generation + MCP integration
- `mage build` (NOT `go build`) - Builds with proper pipeline
- `mage fix all` (NOT `golangci-lint run --fix`) - Auto-fixes formatting and simple linting issues
- `mage check all` (NOT `golangci-lint run`) - Runs all quality checks
- `mage scenario`  (NOT manual test commands) - Runs end-to-end tests (SLOW)
- `mage e2e` - Runs the heavier `//go:build e2e` tests against real upstream repos (NOT run by `mage scenario`/`mage all`; intended for CI only)
- `mage mutation ./internal/<pkg>` - Mutation testing (gremlins) to audit unit-test *quality* (does a test actually catch a bug?), not just coverage. Available as the `mage_mutation` MCP tool. Slower than unit tests; scope to a package for quick feedback (`./` runs the whole repo in a few min). Console shows only survivors/uncovered; full JSON report at `out/mutation-report.json`. On-demand audit tool, NOT part of `mage all`/CI. See `testing.instructions.md`.

- `run-azldev-from-out-bin` MCP server **IF** available (NOT `go run ./cmd/azldev` or `./azldev`)

**ALWAYS start with `mage fix all`** when fixing linter issues - it automatically handles most formatting and simple fixes. Only manually fix the remaining issues that the auto-fixer cannot handle (both check and fix may take > 30 seconds the first time they run).

Run `mage all` to verify Go changes and scenario tests. Run `mage check all` as well when
changing Python or to include the optional Python lint and type checks.

Project structure: `cmd/` (entry points), `internal/` (business logic), `magefiles/` (build config).

Documentation structure: `docs/user/reference/cli/` (auto-generated CLI docs, regenerated by `mage docs`), `docs/user/reference/config/` (hand-written TOML config reference), `docs/user/how-to/` (workflow guides), `docs/user/explanation/` (conceptual docs).

**Agent skills track tool behavior.** `internal/app/azldev/agentskill/` emits the AI-agent skills and instruction files that describe azldev's CLI, config, and workflows. After a behavioral change (command syntax, flags, config schema, overlay types, workflows), check whether these need updating — see [instructions/agent-skills.instructions.md](instructions/agent-skills.instructions.md).

The TOML config files in `defaultconfigs/` are loaded via `internal/projectconfig/`.

**IMPORTANT**: Code generation runs automatically with build/test commands. `mage generate` (runs `go generate` for each package in parallel) is a prerequisite for building and runs automatically with `mage build` and `mage unit`. `mage docs` rebuilds the binary and updates the JSON schema (`schemas/azldev.schema.json`) and CLI docs (`docs/user/reference/cli/`). Run `mage docs` explicitly after changing config structs or Cobra command descriptions so that checked-in generated files stay current (checked by PR gates).

**CRITICAL**: Run `mage scenarioUpdate` when test expectations change (updates snapshots).

Follow conventional commit format for all changes AND PR titles. A github action will fail the PR if the title does not adhere to the format.