Add CHANGELOG.md and maintenance agent skill

.github/instructions/changelog_md.instructions.md

@@ -0,0 +1,84 @@
+---
+applyTo: 'CHANGELOG.md'
+description: 'Instructions for maintaining the CHANGELOG.md file that tracks changes between stable releases.'
+---
+
+# Copilot Instructions for `CHANGELOG.md`
+
+## PURPOSE
+
+This file contains instructions for maintaining the repository-root `CHANGELOG.md`. The changelog is the authoritative, human-readable record of all notable changes between stable (non-pre-release, non-RC) tagged releases, following the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
+
+## REQUIREMENTS
+
+### General
+
+- ALWAYS follow the [Keep a Changelog v1.1.0](https://keepachangelog.com/en/1.1.0/) specification.
+- ALWAYS list only **stable** releases (tags matching `vMAJOR.MINOR.PATCH` with no suffix). NEVER list pre-release or release-candidate tags (e.g., `v2.25.0-rc1`, `v2.24.3-rc2`).
+- ALWAYS keep entries in **reverse chronological order** — newest release at the top, oldest at the bottom.
+- ALWAYS include the full date in `YYYY-MM-DD` format after the version heading (e.g., `## [v2.25.0] — 2026-03-27`).
+- ALWAYS include a `[Unreleased]` section at the top for changes on `main` that have not yet been included in a stable release.
+- ALWAYS include reference-style link definitions at the bottom of the file for every version heading and the `[Unreleased]` comparison link.
+- ALWAYS link PR numbers in the format `([#NNN](https://github.com/advanced-security/codeql-development-mcp-server/pull/NNN))`.
+- ALWAYS link contributor handles in the format `[@username](https://github.com/username)`.
+- **ALWAYS run `npm run build-and-test` from the repo root directory and ensure it passes completely before committing any changes.**
+
+### Section Structure
+
+Each release entry MUST use the following section hierarchy. Omit any section that has no entries for that release.
+
+```
+## [vX.Y.Z] — YYYY-MM-DD
+
+### Highlights             ← 2-4 sentence summaries of the most important changes
+### Added                  ← new tools, prompts, resources, queries, VS Code extension features
+### Changed                ← modifications to existing tools, prompts, resources, infrastructure
+### Deprecated             ← features marked for future removal
+### Removed                ← features or tools that were removed
+### Fixed                  ← bug fixes
+### Security               ← vulnerability fixes or hardening
+### Dependencies           ← CodeQL CLI upgrades, npm dependency bumps, action version bumps
+### New Contributors       ← first-time contributors (include only in the release where they first appeared)
+```
+
+Within `Added` and `Changed`, use sub-headings to group entries by area:
+
+```
+#### MCP Server Tools
+#### MCP Server Prompts
+#### MCP Server Resources
+#### CodeQL Query Packs
+#### VS Code Extension
+#### Infrastructure & CI/CD
+```
+
+### Tables for Tools, Prompts, and Resources
+
+- ALWAYS use a two-column markdown table (`| Name | Description |`) when listing new or changed MCP server tools, prompts, or resources.
+- For changed tools, use a two-column table (`| Tool | Change |`) describing what changed.
+
+### Full Changelog Link
+
+- ALWAYS end each release section with a **Full Changelog** comparison link in the format:
+  ```
+  **Full Changelog**: [`vPREV...vCURR`](https://github.com/advanced-security/codeql-development-mcp-server/compare/vPREV...vCURR)
+  ```
+
+### Horizontal Rule
+
+- ALWAYS separate release entries with a `---` horizontal rule.
+
+## PREFERENCES
+
+- PREFER concise, specific descriptions over vague summaries. Name the tool, prompt, or resource affected.
+- PREFER grouping related dependency bumps (e.g., multiple `@vitest/*` packages) into a single bullet.
+- PREFER the `Highlights` section to summarize the 2-4 most impactful changes for a release, with links to relevant PRs.
+- PREFER linking to PRs rather than issues when both exist, since PRs contain the implementation details.
+
+## CONSTRAINTS
+
+- NEVER leave any trailing whitespace on any line.
+- NEVER include placeholder or TODO content — if a release section is not ready, keep changes under `[Unreleased]` until the release is tagged.
+- NEVER duplicate the same change under multiple sections (e.g., do not list the same fix under both `Fixed` and `Changed`).
+- NEVER include internal-only or draft PR references that have not been merged to `main`.
+- NEVER modify historical release entries unless correcting a factual error (wrong PR number, broken link, etc.).

.github/skills/maintain-changelog/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: maintain-changelog
+description: Maintain the CHANGELOG.md file by drafting or updating entries for new stable releases. Use this skill when preparing a release, after merging significant PRs, or when moving changes from Unreleased to a new version section.
+---
+
+# Maintain Changelog
+
+This skill provides a systematic workflow for keeping `CHANGELOG.md` up-to-date as changes land on `main` and when cutting new stable releases.
+
+## When to Use This Skill
+
+- **After merging a PR** that adds, changes, removes, or fixes MCP server tools, prompts, resources, CodeQL query packs, VS Code extension features, or infrastructure.
+- **When preparing a stable release** (tagging `vMAJOR.MINOR.PATCH` without a pre-release suffix).
+- **When reviewing the `[Unreleased]` section** for accuracy before a release candidate or final release.
+
+## Key Concepts
+
+### Release Scope
+
+The changelog tracks changes between **stable releases only** — tags matching `vMAJOR.MINOR.PATCH` with no `-rc*` or other suffix. Pre-release tags are excluded.
+
+### Section Taxonomy
+
+Each release entry follows the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) categories:
+
+| Section              | What goes here                                                        |
+| -------------------- | --------------------------------------------------------------------- |
+| **Highlights**       | 2-4 sentence summaries of the most impactful changes, with PR links   |
+| **Added**            | New tools, prompts, resources, query packs, extension features        |
+| **Changed**          | Modifications to existing tools, prompts, resources, infrastructure   |
+| **Deprecated**       | Features marked for future removal                                    |
+| **Removed**          | Features or tools removed in this release                             |
+| **Fixed**            | Bug fixes                                                             |
+| **Security**         | Vulnerability fixes or hardening changes                              |
+| **Dependencies**     | CodeQL CLI upgrades, npm dependency bumps, action version bumps       |
+| **New Contributors** | First-time contributors (only in the release where they first appear) |
+
+Within `Added` and `Changed`, use sub-headings to group by area: `MCP Server Tools`, `MCP Server Prompts`, `MCP Server Resources`, `CodeQL Query Packs`, `VS Code Extension`, `Infrastructure & CI/CD`.
+
+### Entry Format
+
+- Each bullet links to the PR: `- Description of change. ([#NNN](https://github.com/advanced-security/codeql-development-mcp-server/pull/NNN))`
+- New or changed tools/prompts/resources use a two-column markdown table.
+- Each release ends with: `**Full Changelog**: [\`vPREV...vCURR\`](https://github.com/advanced-security/codeql-development-mcp-server/compare/vPREV...vCURR)`
+
+## Workflow
+
+### Phase 1: Gather Changes
+
+Identify all merged PRs since the last stable release tag.
+
+```sh
+# List PRs merged since the last stable release
+git log --oneline --merges v2.25.0..HEAD
+```
+
+Alternatively, use the GitHub compare view:
+
+```
+https://github.com/advanced-security/codeql-development-mcp-server/compare/vPREV...HEAD
+```
+
+### Phase 2: Classify Each Change
+
+For each merged PR, determine:
+
+1. **Which section** it belongs to (Added, Changed, Fixed, Dependencies, etc.)
+2. **Which sub-area** it affects (MCP Server Tools, VS Code Extension, Infrastructure, etc.)
+3. **Whether it warrants a Highlights mention** (significant user-facing impact)
+
+Use these heuristics:
+
+| PR title pattern                          | Likely section                                   |
+| ----------------------------------------- | ------------------------------------------------ |
+| `Build(deps)` or `Bump`                   | Dependencies                                     |
+| `Fix` or `Fixes`                          | Fixed                                            |
+| `Add` or `New` or `Implement`             | Added                                            |
+| `Update` or `Improve` or `Refactor`       | Changed                                          |
+| `Upgrade CodeQL CLI`                      | Dependencies + possibly Highlights               |
+| `[UPDATE PRIMITIVE]`                      | Changed > MCP Server Tools                       |
+| `Pin actions` or `dependabot`             | Changed > Infrastructure & CI/CD or Dependencies |
+| `Security` or `TOCTOU` or `vulnerability` | Security                                         |
+
+### Phase 3: Draft Entries
+
+1. Open `CHANGELOG.md`.
+2. Add entries under the `[Unreleased]` section, grouped by section and sub-area.
+3. Use concise, specific descriptions. Name the tool, prompt, or resource affected.
+4. Link every entry to its PR number.
+
+### Phase 4: Cut a Release Entry
+
+When a stable release is being tagged:
+
+1. Replace `[Unreleased]` content with a new version heading:
+   ```markdown
+   ## [vX.Y.Z] — YYYY-MM-DD
+   ```
+2. Re-create an empty `[Unreleased]` section above the new entry.
+3. Write a `Highlights` section summarizing the 2-4 most important changes.
+4. Add a `**Full Changelog**` comparison link at the bottom of the entry.
+5. Update the reference-style link definitions at the bottom of the file:
+   - Add `[vX.Y.Z]: https://github.com/advanced-security/codeql-development-mcp-server/releases/tag/vX.Y.Z`
+   - Update `[Unreleased]` to compare against the new tag: `https://github.com/advanced-security/codeql-development-mcp-server/compare/vX.Y.Z...HEAD`
+6. Add a `---` horizontal rule between the new entry and the previous release.
+
+### Phase 5: Validate
+
+1. Verify all PR links resolve correctly.
+2. Verify the `[Unreleased]` comparison link points to `vLATEST...HEAD`.
+3. Verify no duplicate entries exist across sections.
+4. Verify entries are in reverse chronological order.
+5. Run `npm run build-and-test` from the repo root to ensure no regressions.
+
+## Example: Adding an Unreleased Entry
+
+After merging PR #200 that adds a new `foo_bar` tool:
+
+```markdown
+## [Unreleased]
+
+### Added
+
+#### MCP Server Tools
+
+| Tool      | Description               |
+| --------- | ------------------------- |
+| `foo_bar` | Does X for Y, enabling Z. |
+
+- New `foo_bar` tool for doing X. ([#200](https://github.com/advanced-security/codeql-development-mcp-server/pull/200))
+```
+
+## Example: Promoting Unreleased to a New Version
+
+```markdown
+## [Unreleased]
+
+_Changes on `main` since the latest tagged release that have not yet been included in a stable release._
+
+## [v2.26.0] — 2026-04-15
+
+### Highlights
+
+- **New `foo_bar` tool** — ...
+
+### Added
+
+...
+
+**Full Changelog**: [`v2.25.0...v2.26.0`](https://github.com/advanced-security/codeql-development-mcp-server/compare/v2.25.0...v2.26.0)
+
+---
+
+## [v2.25.0] — 2026-03-27
+
+...
+```
+
+## Related Instructions
+
+- [`.github/instructions/changelog_md.instructions.md`](../../instructions/changelog_md.instructions.md) — Formatting rules applied when editing `CHANGELOG.md`.

.github/skills/upgrade-codeql-cli-and-packs/SKILL.md

@@ -289,3 +289,4 @@ See [verify-pack-compatibility.sh](verify-pack-compatibility.sh) for automated c
 
 - [add-mcp-support-for-new-language](../add-mcp-support-for-new-language/SKILL.md) - Adding support for new CodeQL languages
 - [validate-ql-mcp-server-tools-queries](../validate-ql-mcp-server-tools-queries/SKILL.md) - Validating tool query functionality
+- [maintain-changelog](../maintain-changelog/SKILL.md) - Updating `CHANGELOG.md` when preparing a release