@m-velikov/cpp-quick-start-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Momchil Velikov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# C++ Quick Start MCP Server
+
+[![Discord](https://img.shields.io/badge/Discord-Join%20Us-7289da?logo=discord&logoColor=white)](https://discord.gg/qrhuftYXs4)
+
+This is a **Model Context Protocol (MCP)** server that equips any compatible AI assistant (Antigravity, Cursor, Claude Desktop, etc.) with the ability to expertly scaffold cross-platform C++ projects.
+
+Instead of writing boilerplate from scratch (and hallucinating build system rules), this MCP server acts as an interactive "Knowledge Base". It guides the AI through a structured interview process and then provides it with exact, proven templates for CMake, Conan, vcpkg, GitHub Actions, and standard directory layouts.
+
+## Features
+
+- **The `meta-quickstart` Prompt**: Initiates an interactive interview with the developer to determine the exact C++ stack (Standard, Build System, Package Manager, CI/CD, Coding Style, etc.).
+- **Dynamic Scaffolding Resources**: Provides the AI with deep, instructional markdown resources (`mcp://scaffold/conan`, `mcp://scaffold/github-actions`, etc.) so it knows exactly how to write the requested boilerplate files perfectly.
+- **Agent-Ready Architecture**: When you run the prompt, your C++ project will be automatically configured for modern agentic development. It seeds your project with built-in guidelines and architecture rules so future AI agents know exactly how to collaborate on your codebase safely and predictably.
+
+## Installation
+
+Ensure you have Node.js and `npm` installed.
+
+### Install via NPM (Recommended)
+
+You can install the server directly from the official npm registry:
+
+```bash
+npm install -g @m-velikov/cpp-quick-start-mcp
+```
+
+### Install from Source (Local Development)
+
+If you are cloning this repository to build it locally:
+
+1. Install dependencies:
+   ```bash
+   npm install
+   ```
+2. Build the server:
+   ```bash
+   npm run build
+   ```
+3. Install the package globally from the local directory:
+   ```bash
+   npm install -g .
+   ```
+
+Once installed via either method, the `cpp-quick-start-mcp` command will be available system-wide.
+
+### Starting the Server (Optional)
+
+If you want to run the server standalone over HTTP/SSE instead of standard I/O:
+
+```bash
+# Start with default options (port 3000, host 0.0.0.0)
+cpp-quick-start-mcp --port 3000
+```
+
+_The server binds to all interfaces (`0.0.0.0`) on port `3000` by default._
+
+## Connecting to an AI Agent
+
+This server supports **Dual Transport** (both `stdio` for local clients and `sse` for remote clients).
+
+### 1. Local Connection (stdio) - DEFAULT
+
+For local IDE clients, you can connect directly without running an HTTP server. Since you installed the package globally, you can use the `cpp-quick-start-mcp` command directly.
+
+_(Note: On Windows, use `cpp-quick-start-mcp.cmd` as the command instead of `cpp-quick-start-mcp` in the JSON configurations below)._
+
+#### Antigravity IDE
+
+1. Open the MCP Store by clicking the "..." dropdown at the top of the editor's side panel or agent panel, and select **MCP Servers**.
+2. Click **Manage MCP Servers**, then select **View raw config** to edit your `mcp_config.json` file.
+3. Add the following to your configuration:
+   ```json
+   "mcpServers": {
+     "cpp-quick-start": {
+       "command": "cpp-quick-start-mcp",
+       "args": []
+     }
+   }
+   ```
+   Alternatively, simply ask the Antigravity agent: "Add the cpp-quick-start-mcp server to my configuration".
+
+#### Codex
+
+Codex uses a TOML file for configuration instead of JSON.
+
+1. Open your `~/.codex/config.toml` file (or `.codex/config.toml` in your project folder).
+2. Add the server entry:
+   ```toml
+   [mcp.servers.cpp-quick-start]
+   command = "cpp-quick-start-mcp"
+   args = []
+   ```
+   Alternatively, use the Codex CLI:
+
+```bash
+codex mcp add cpp-quick-start -- cpp-quick-start-mcp
+```
+
+#### Claude Code
+
+1. You can add the MCP server directly via the Claude Code CLI using the following command:
+   ```bash
+   claude mcp add-json cpp-quick-start '{"type":"stdio","command":"cpp-quick-start-mcp","args":[]}'
+   ```
+2. Or you can manually edit your `claude.json` configuration file and add the JSON block shown in the Antigravity section.
+3. Restart Claude Code or verify active servers with `claude mcp list`.
+
+#### GitHub Copilot
+
+1. In Visual Studio Code, open the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`) and type **MCP: Add Server**.
+2. Follow the guided flow, using `cpp-quick-start-mcp` as the command.
+3. Alternatively, manually edit your global `~/.copilot/mcp-config.json` or project-scoped `.mcp/copilot/mcp.json` file and add the JSON configuration block.
+4. Ensure you are in "Agent mode" in your Copilot chat interface to interact with your added MCP tools.
+
+### 2. Remote Connection (SSE)
+
+If you start the server using `--port`, it will automatically switch to HTTP/SSE transport mode. This is extremely useful if you are building a custom MCP client (using the `@modelcontextprotocol/sdk` client library) or deploying the server to the cloud.
+
+_Note: Not all IDEs (like Antigravity or Cursor) currently support configuring remote SSE servers via their `mcp.json` files yet. For those IDEs, you must use the Local Connection (`stdio`) method above._
+
+Example configuration for a custom web client:
+
+```json
+{
+  "mcpServers": {
+    "cpp-quick-start": {
+      "type": "sse",
+      "url": "http://localhost:3000/mcp"
+    }
+  }
+}
+```
+
+## Usage
+
+### New Projects
+
+Once connected, simply open an empty folder in your editor/terminal and tell your AI assistant:
+
+> "Run the **meta-quickstart** prompt to help me start a new C++ project."
+
+The AI will take over, interview you, and generate your custom C++ boilerplate.
+
+### Existing Projects
+
+You can also use this MCP server to configure an existing project for agentic development. Open your existing project folder and tell your AI assistant:
+
+> "Use your scaffolding resources to configure this existing C++ project for agentic development (e.g., adding an AGENTS.md, setting up GitHub Actions, or integrating a package manager)."
+
+The AI will read the exact blueprints from the MCP server and cleanly integrate them into your existing codebase.
+
+## Community
+
+Got questions, ideas, or need help setting up your C++ environment? Come hang out with us on Discord!
+
+[Join the Discord Server](https://discord.gg/YOUR_INVITE_LINK)

package/build/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/build/index.js

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+import { serve } from "@hono/node-server";
+import { Hono } from "hono";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { ListPromptsRequestSchema, GetPromptRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ErrorCode, McpError, } from "@modelcontextprotocol/sdk/types.js";
+import * as fs from "fs/promises";
+import * as path from "path";
+import { fileURLToPath } from "url";
+import crypto from "crypto";
+import { parseArgs } from "node:util";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DATA_DIR = path.join(__dirname, "..", "data");
+const server = new Server({
+    name: "cpp-quick-start-mcp",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        prompts: {},
+        resources: {},
+    },
+});
+// Resources: serve all SKILL.md files inside data/ folders
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    const dirs = await fs.readdir(DATA_DIR);
+    const resources = [];
+    for (const dir of dirs) {
+        if (dir === "meta-quickstart")
+            continue; // Expose meta-quickstart as a Prompt, not a Resource
+        const skillPath = path.join(DATA_DIR, dir, "SKILL.md");
+        try {
+            await fs.access(skillPath);
+            resources.push({
+                uri: `mcp://scaffold/${dir}`,
+                name: `C++ Scaffolding Skill: ${dir}`,
+                mimeType: "text/markdown",
+                description: `Instructions for scaffolding ${dir}`,
+            });
+        }
+        catch (e) {
+            // Ignore directories without SKILL.md
+        }
+    }
+    return { resources };
+});
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const uri = request.params.uri;
+    const match = uri.match(/^mcp:\/\/scaffold\/(.+)$/);
+    if (!match) {
+        throw new McpError(ErrorCode.InvalidRequest, `Invalid URI: ${uri}`);
+    }
+    const skillName = path.basename(match[1]);
+    const skillPath = path.join(DATA_DIR, skillName, "SKILL.md");
+    try {
+        const content = await fs.readFile(skillPath, "utf-8");
+        return {
+            contents: [
+                {
+                    uri,
+                    mimeType: "text/markdown",
+                    text: content,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        throw new McpError(ErrorCode.InvalidRequest, `Resource not found: ${uri}`);
+    }
+});
+// Prompts: expose the meta-quickstart interview
+server.setRequestHandler(ListPromptsRequestSchema, async () => {
+    return {
+        prompts: [
+            {
+                name: "meta-quickstart",
+                description: "Conducts the C++ quick start interview to determine project stack.",
+                arguments: [],
+            },
+        ],
+    };
+});
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    if (request.params.name !== "meta-quickstart") {
+        throw new McpError(ErrorCode.InvalidRequest, `Prompt not found: ${request.params.name}`);
+    }
+    const metaSkillPath = path.join(DATA_DIR, "meta-quickstart", "SKILL.md");
+    try {
+        const content = await fs.readFile(metaSkillPath, "utf-8");
+        return {
+            description: "C++ Meta-Scaffold Interview Workflow",
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: content,
+                    },
+                },
+            ],
+        };
+    }
+    catch (error) {
+        throw new McpError(ErrorCode.InternalError, "Failed to load meta-quickstart instructions");
+    }
+});
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+async function main() {
+    const { values } = parseArgs({
+        args: process.argv.slice(2),
+        options: {
+            port: { type: "string", short: "p" },
+            host: { type: "string", short: "h" },
+            stdio: { type: "boolean" },
+        },
+    });
+    const PORT = values.port
+        ? parseInt(values.port, 10)
+        : process.env.PORT
+            ? parseInt(process.env.PORT, 10)
+            : undefined;
+    // If --stdio is passed (or no port is specified), use stdio.
+    if (values.stdio || !PORT) {
+        console.error("Starting C++ Quick Start MCP Server on stdio...");
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        return;
+    }
+    // Otherwise, use SSE/Hono
+    const transport = new WebStandardStreamableHTTPServerTransport({
+        sessionIdGenerator: () => crypto.randomUUID(),
+    });
+    await server.connect(transport);
+    const app = new Hono();
+    app.all("/mcp", async (c) => {
+        return transport.handleRequest(c.req.raw);
+    });
+    const HOST = values.host ?? process.env.HOST ?? "0.0.0.0";
+    console.log(`Starting C++ Quick Start MCP Server on http://${HOST}:${PORT}/mcp ...`);
+    serve({
+        fetch: app.fetch,
+        port: PORT,
+        hostname: HOST,
+    });
+}
+main().catch(console.error);
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/data/best-practices-bazel/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: best-practices-bazel
+description: Best practices for building C++ projects with Bazel.
+---
+
+# Bazel Best Practices
+
+When building C++ components with Bazel, strictly adhere to the following principles:
+
+## 1. Granular Targets
+
+- Prefer small, granular `cc_library` targets over monolithic ones. This maximizes caching and parallelization.
+- Ensure that every header file is associated with at least one `cc_library` using the `hdrs` attribute.
+
+## 2. Dependency Management
+
+- Declare external dependencies using Bzlmod (`MODULE.bazel`). Avoid the legacy `WORKSPACE` file where possible.
+- Use `bazel dep` commands or manually edit `MODULE.bazel` to specify third-party libraries.
+
+## 3. Visibility
+
+- Restrict visibility using `visibility = ["//visibility:private"]` or specific package lists.
+- Expose targets via `//visibility:public` only when they are intended to be consumed by arbitrary external packages.
+
+## 4. Include Paths
+
+- Use `strip_include_prefix` or `include_prefix` if you need to manipulate header paths.
+- Avoid using `copts = ["-I..."]` for include paths; rely on the native `includes` attribute or proper dependency propagation.

package/data/best-practices-cmake/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: best-practices-cmake
+description: Best practices for using Modern CMake in C++ projects.
+---
+
+# CMake Best Practices
+
+When working with CMake in this project, adhere to the following modern, target-based CMake practices:
+
+## 1. Target-Based Approach
+
+- **Do not use global state.** Avoid functions like `include_directories()`, `link_directories()`, and `add_definitions()`.
+- Use `target_include_directories()`, `target_link_libraries()`, and `target_compile_definitions()` exclusively.
+- Define visibility explicitly: `PRIVATE`, `PUBLIC`, or `INTERFACE`.
+
+## 2. Setting C++ Standards
+
+Set the C++ standard strictly on a per-target basis using `target_compile_features`. Do not use global state like `CMAKE_CXX_STANDARD` unless absolutely required by a legacy dependency.
+
+```cmake
+target_compile_features(<target_name> PUBLIC cxx_std_20)
+```
+
+## 3. Project Structure
+
+- Split your build files. Avoid large, monolithic top-level `CMakeLists.txt` files.
+- Use `add_subdirectory()` to include sub-components.
+- Keep `CMakeLists.txt` close to the source files they build.
+
+## 4. Testing
+
+- Use `enable_testing()` at the root level.
+- Include testing directories only if tests are enabled (e.g., `if(BUILD_TESTING)`).
+- Register tests using `add_test(NAME <test_name> COMMAND <test_executable>)`.
+
+## 5. CMake Presets
+
+- Use `CMakePresets.json` to standardize configure, build, and test commands across environments.
+- This gives AI agents and developers simple, single-line commands (e.g., `cmake --preset dev`, `cmake --build --preset dev`) and avoids command-line hallucination or environment-specific friction.

package/data/best-practices-code-review/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: best-practices-code-review
+description: Best practices for performing automated code reviews in C++.
+---
+
+# Code Review Best Practices
+
+When tasked with reviewing code, the agent MUST follow these guidelines to provide constructive, actionable feedback:
+
+## 1. Style and Formatting
+
+- Verify that the code complies with the project's chosen coding style (e.g., Google, LLVM) and naming conventions.
+- Check if the code passes automated formatters like `clang-format`.
+
+## 2. Modern C++ Usage
+
+- Look for opportunities to use modern C++ features (e.g., `auto`, range-based for loops, `std::unique_ptr`/`std::shared_ptr` over raw pointers).
+- Ensure resource management uses RAII principles.
+
+## 3. Correctness and Safety
+
+- Check for potential memory leaks, dangling references, or uninitialized variables.
+- Verify that error handling is robust (e.g., appropriate use of exceptions or expected types).
+- Look out for thread-safety issues if concurrency is involved.
+
+## 4. Test Coverage
+
+- Ensure that any new functionality is accompanied by corresponding unit tests.
+- Verify that bug fixes include a regression test.
+
+## 5. Feedback Format
+
+- Be specific and constructive. Provide code snippets to demonstrate suggested improvements.
+- Categorize feedback into "Critical/Blocking" and "Nitpicks/Optional".

package/data/best-practices-conan/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: best-practices-conan
+description: Best practices for using Conan 2.x for dependency management.
+---
+
+# Conan Best Practices
+
+Follow these best practices when managing C++ dependencies via Conan:
+
+## 1. Declarative Requirements
+
+- Use a `conanfile.py` exclusively to declare requirements, even for simple consuming projects. Do not use `conanfile.txt` as it limits flexibility in Conan 2.x.
+- Specify versions clearly (e.g., `requires = "zlib/1.3.1"`).
+
+## 2. Options and Settings
+
+- Define options and settings explicitly in your profiles, rather than passing them continuously on the command line.
+- Always provide a `build_type` (e.g., Debug or Release) to ensure ABI compatibility.
+
+## 3. Generators
+
+- Use the modern `CMakeDeps` and `CMakeToolchain` generators to integrate with CMake seamlessly.
+- Avoid legacy generators like `cmake` or `cmake_multi`.
+- Let `CMakeToolchain` generate the `conan_toolchain.cmake` file, and pass it to CMake configure: `-DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake`.
+
+## 4. Reproducible Builds
+
+- Generate and commit a `conan.lock` lockfile for stable and reproducible builds across developer machines and CI.

package/data/best-practices-cpp/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: best-practices-cpp
+description: General C++ programming best practices based on the C++ Core Guidelines.
+---
+
+# C++ Best Practices (Core Guidelines)
+
+When writing or modifying C++ code in this project, strictly adhere to the philosophies outlined in the official [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md).
+
+## 1. Resource Management (RAII)
+
+- Avoid naked `new` and `delete`. Use `std::make_unique` and `std::make_shared` for dynamic allocation.
+- Use smart pointers (`std::unique_ptr`, `std::shared_ptr`) or containers (like `std::vector`) to manage ownership.
+- Never pass a smart pointer unless the function needs to manipulate the ownership itself. Pass by reference (`T&`) or `const` reference (`const T&`) otherwise.
+
+## 2. Interfaces
+
+- Make interfaces explicit. Do not hide dependencies or rely on global state.
+- Consistently use `const`. If a function does not modify an argument, pass it as `const T&`. If a member function does not modify state, mark it `const`.
+- Use `std::optional` or `std::expected` for functions that might fail to return a value, rather than out-parameters or ambiguous return codes.
+
+## 3. Modern Language Features
+
+- Use `auto` to avoid redundant type names, but keep types explicit when it improves readability.
+- Prefer range-based `for` loops over index-based loops.
+- Prefer using `constexpr` and `consteval` for values and functions that can be evaluated at compile time.
+- Prefer `<ranges>` and range-based algorithms (like `std::ranges::find_if`) over `<algorithm>` and iterator-based algorithms where possible, and prefer both over writing raw loops.
+- Use `std::span` when passing read-only views of contiguous memory instead of passing raw pointers/sizes or `const std::vector&`.
+
+## 4. Safety and Error Handling
+
+- Use exceptions for error handling unless the project is explicitly compiled without them.
+- Throw by value, catch by reference.
+- Apply `noexcept` consistently for functions that are guaranteed not to throw exceptions (especially move constructors and destructors).
+- Use `[[nodiscard]]` on functions where ignoring the return value is likely a bug (e.g., error codes).
+- Avoid C-style raw arrays; use `std::array` or `std::vector`. When creating `std::array`s, prefer `std::to_array` to deduce the array length automatically instead of hardcoding it (e.g., `auto arr = std::to_array({1, 2, 3});`).
+
+These guidelines ensure the code remains safe, performant, and maintainable across the entire project.

package/data/best-practices-gtest/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: best-practices-gtest
+description: Best practices for writing C++ tests with Google Test.
+---
+
+# Google Test (GTest) Best Practices
+
+Follow these guidelines when writing unit and integration tests using GTest:
+
+## 1. Test Organization
+
+- Mirror the source directory structure in the `tests/` directory.
+- Use `TEST(TestSuiteName, TestName)` for simple standalone tests.
+- Use `TEST_F(TestFixtureName, TestName)` when multiple tests share the same setup and teardown logic via a fixture class.
+
+## 2. Assertions
+
+- Prefer `EXPECT_*` over `ASSERT_*` when you want the test to continue running after a failure.
+- Use `ASSERT_*` only when a failure means subsequent code in the test will crash or behave completely unpredictably.
+- Provide descriptive failure messages by streaming into the macro: `EXPECT_EQ(a, b) << "Values should match because...";`
+
+## 3. Naming Conventions
+
+- Test suite names should describe the component being tested (e.g., `StringUtilsTest`).
+- Test names should describe the specific scenario or behavior being verified (e.g., `HandlesEmptyStrings`).
+
+## 4. Mocking
+
+- Use gMock (`MOCK_METHOD`) to mock interfaces when testing components in isolation.
+- Verify expectations explicitly using `EXPECT_CALL` before invoking the code under test.

package/data/best-practices-meson/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: best-practices-meson
+description: Best practices for building C++ projects with Meson.
+---
+
+# Meson Best Practices
+
+When using Meson for your build system, follow these practices:
+
+## 1. Structured Build Files
+
+- Use `meson.build` at the root and include subdirectories using `subdir('dirname')`.
+- Keep the root `meson.build` clean, primarily defining the project, global compiler arguments, and including subdirectories.
+
+## 2. Compiler Flags
+
+- Set C++ dialects (e.g., C++20) using `default_options: ['cpp_std=c++20']` within the `project()` definition.
+- Use `add_project_arguments()` to specify project-wide compiler warnings. Avoid hardcoding specific GCC or Clang flags without checking compiler IDs, e.g.:
+
+```meson
+cpp = meson.get_compiler('cpp')
+if cpp.get_id() == 'gcc' or cpp.get_id() == 'clang'
+  add_project_arguments('-Wextra', '-Werror', language : 'cpp')
+endif
+```
+
+## 3. Dependencies
+
+- Use `dependency('libname')` to find system libraries via pkg-config or CMake.
+- Use Meson's WrapDB for third-party dependencies by placing `.wrap` files in the `subprojects/` directory. Use `fallback` in `dependency()` to gracefully use a wrap if the system package is not found.
+
+## 4. Testing
+
+- Register tests using the `test('test_name', executable_target)` command.

package/data/best-practices-refactoring/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: best-practices-refactoring
+description: Best practices for safely refactoring C++ code.
+---
+
+# Refactoring Best Practices
+
+When an agent is tasked with refactoring code in this project, it MUST adhere to the following protocol:
+
+## 1. Prerequisites
+
+- **Ensure a Clean State**: Before making any changes, compile the project and run the entire test suite. Do not begin refactoring if tests are currently failing.
+
+## 2. Atomic Commits
+
+- Perform refactoring in small, atomic, and verifiable steps.
+- Avoid changing functionality and refactoring structure at the same time.
+
+## 3. Directory and Layout Compliance
+
+- When moving files, strictly adhere to the project's directory layout (e.g., Pitchfork layout).
+- Move header files to the appropriate `include/` directory and source files to `src/`.
+
+## 4. Verification
+
+- After moving files or renaming symbols, update all relevant `#include` paths.
+- Re-run the build and the test suite after _each_ atomic step to catch regressions immediately.
+- Use `clang-tidy` or similar linters to ensure the new structure doesn't introduce code quality issues.

package/data/best-practices-vcpkg/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: best-practices-vcpkg
+description: Best practices for using vcpkg for dependency management.
+---
+
+# vcpkg Best Practices
+
+When integrating vcpkg for dependency management, follow these best practices:
+
+## 1. Use Manifest Mode
+
+- Always use `vcpkg.json` (Manifest mode) instead of classic mode to declare dependencies. This ensures that dependencies are version-controlled alongside your code.
+- Avoid running `vcpkg install` manually. Let CMake drive the installation during the configure step via the toolchain file.
+
+## 2. Toolchain Integration
+
+- Ensure CMake uses the vcpkg toolchain file by passing `-DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]/scripts/buildsystems/vcpkg.cmake`.
+- For multi-platform setups, consider wrapping the toolchain configuration in an IDE preset (e.g., `CMakePresets.json`).
+
+## 3. Searching and Adding Dependencies
+
+- Ensure that you read the port usage notes after installation (vcpkg prints these out). They often contain the exact `find_package` and `target_link_libraries` commands needed.
+- Always use `find_package(<package> CONFIG REQUIRED)` if supported by the package.
+
+## 4. Reproducibility
+
+- Create a `vcpkg-configuration.json` to pin baseline versions. This ensures that all developers and CI runners are using the exact same versions of the dependencies.