# https://github.com/m-velikov/cpp-quick-start-mcp Project Manual

Generated at: 2026-06-22 04:58:01 UTC

## Table of Contents

- [Project Overview & MCP Architecture](#page-overview)
- [Installation & Client Configuration](#page-installation)
- [Scaffolding Skills Knowledge Base](#page-knowledge)
- [Interview Workflow & Usage Patterns](#page-workflow)

<a id='page-overview'></a>

## Project Overview & MCP Architecture

### Related Pages

Related topics: [Installation & Client Configuration](#page-installation), [Scaffolding Skills Knowledge Base](#page-knowledge), [Interview Workflow & Usage Patterns](#page-workflow)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/README.md)
- [package.json](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/package.json)
- [data/meta-quickstart/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/meta-quickstart/SKILL.md)
- [data/scaffold-agents/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-agents/SKILL.md)
- [data/scaffold-workspace-skills/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-workspace-skills/SKILL.md)
- [data/scaffold-cmake/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-cmake/SKILL.md)
- [data/scaffold-make/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-make/SKILL.md)
- [data/scaffold-pitchfork-layout/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-pitchfork-layout/SKILL.md)
</details>

# Project Overview & MCP Architecture

## Purpose and Scope

`@m-velikov/cpp-quick-start-mcp` is a Model Context Protocol (MCP) server whose purpose is to scaffold modern C++ projects and configure them for agentic AI development. It exposes structured knowledge — build files, layout conventions, CI pipelines, static-analysis configs, and agent-guideline templates — that an AI agent client can fetch on demand and assemble into a working C++ repository. Source: [README.md:1-30]()

The package is distributed on the NPM registry under the name `@m-velikov/cpp-quick-start-mcp` and registers a global CLI named `cpp-quick-start-mcp`. Source: [package.json:1-11]() and [package.json:23-30]() (`"bin": { "cpp-quick-start-mcp": "build/index.js" }`). It is written in TypeScript, built to `build/index.js`, requires Node.js `>=18.3.0`, and uses ES modules (`"type": "module"`). Source: [package.json:25-29]().

As of release **v0.7.0** ([Changelog](https://github.com/m-velikov/cpp-quick-start-mcp/compare/v0.6.0...v0.7.0)), the published bundle ships the compiled server plus the entire `data/` directory of scaffolding resources, declared in [package.json:18-21]() (`"files": ["build", "data"]`).

## MCP Architecture

The server follows the standard MCP pattern with three primitives exposed to clients: **tools**, **resources**, and **prompts**.

- **Resources** are URI-addressed content blocks the agent reads through MCP `read-resource`. The canonical scheme used throughout the project is `mcp://scaffold/<topic>` (e.g. `mcp://scaffold/cmake`, `mcp://scaffold/conan`, `mcp://scaffold/github-actions`). Source: [README.md:18-22]() and [data/meta-quickstart/SKILL.md]().
- **Tools** include at least `list-resources`, which returns the complete URI catalogue so the agent can decide what to load. Source: [data/meta-quickstart/SKILL.md]().
- **Prompts** provide entry-point workflows. The flagship prompt is `go`, a Level-2 meta-skill that orchestrates scaffolding rather than writing C++ directly. Source: [data/meta-quickstart/SKILL.md:6-10]().

Two transports are supported. The default uses **standard I/O** for MCP clients that launch the server as a subprocess. Optionally, the server can run over **HTTP/SSE** via `cpp-quick-start-mcp --port 3000`, binding `0.0.0.0:3000`. Source: [README.md:48-55]().

```mermaid
flowchart LR
    A[AI Agent Client] -- MCP protocol --> B[cpp-quick-start-mcp server]
    B -- tools/list, resources/read --> A
    B -- data/*.md --> C[(data/ scaffolding skills)]
    B -- generated skills/, AGENTS.md --> D[(User Project)]
```

## Resource & Skill Catalogue

Every shipped resource is a Markdown skill under `data/scaffold-<component>/SKILL.md`, each starting with YAML frontmatter containing a kebab-case `name` and a single-line `description` ending in `Use when …`. Source: [data/scaffold-cmake/SKILL.md:1-3]() and [data/scaffold-workspace-skills/SKILL.md:9-14]().

| Category | Representative skills | Source |
|----------|----------------------|--------|
| Build systems | CMake, Make, Meson, Bazel | [scaffold-cmake/SKILL.md](), [scaffold-make/SKILL.md](), [scaffold-meson/SKILL.md](), [scaffold-bazel/SKILL.md]() |
| Layout | Pitchfork Layout | [scaffold-pitchfork-layout/SKILL.md]() |
| Testing | Doctest integration | [scaffold-doctest/SKILL.md]() |
| Static analysis | clang-tidy, cppcheck | [scaffold-clang-tidy/SKILL.md](), [scaffold-cppcheck/SKILL.md]() |
| CI/CD | GitHub Actions, GitLab CI | [scaffold-github-actions/SKILL.md](), [scaffold-gitlab-ci/SKILL.md]() |
| Base configs | `.gitignore`, `.gitattributes`, `.clangd`, `CMakePresets.json` | [scaffold-base-configs/SKILL.md](), [scaffold-cmake-presets/SKILL.md]() |
| Agent onboarding | `AGENTS.md`, workspace-skill template | [scaffold-agents/SKILL.md](), [scaffold-workspace-skills/SKILL.md]() |

The `meta-quickstart` skill (`go` prompt) does not scaffold C++ itself — it drives the interview and then dispatches to the per-component skills above. Source: [data/meta-quickstart/SKILL.md:6-12]().

## Meta-Scaffold Workflow

The `go` prompt implements a two-mode workflow. Source: [data/meta-quickstart/SKILL.md:13-26]().

1. **Pre-flight scan** — list the working directory to detect an existing project (`CMakeLists.txt`, `Makefile`, `src/`, etc.).
2. **Mode A: New Project** — run a 12-category interactive interview (build system, package manager, C++ standard, layout, testing framework, CI provider, formatter, static analysis, target platforms, namespace, license, etc.).
3. **Mode B: Existing Project** — read existing build files to infer conventions, then ask whether to **add components** or **modernize** the codebase for agentic development. Source: [data/meta-quickstart/SKILL.md]() (Mode B section).
4. **Resource discovery** — call `list-resources` to enumerate every available `mcp://scaffold/*` URI and proactively suggest the relevant ones.
5. **Skill emission** — write permanent workspace skills into the user's project at `skills/<skill-name>/SKILL.md`, each with the frontmatter and required sections (`## Commands`, `## Expected Output`) mandated by [scaffold-workspace-skills/SKILL.md:9-26]().
6. **`AGENTS.md` generation** — emit a top-level agent-guidelines file whose "Workspace Skills" index row-matches every skill actually present in `skills/`. Source: [scaffold-agents/SKILL.md:9-30]().

The end result is a C++ repository seeded with executable, copy-pasteable CLI commands for configuring, building, testing, and reviewing the project — so any future agent can collaborate safely without improvising.

## See Also

- Latest release notes: [v0.7.0 changelog](https://github.com/m-velikov/cpp-quick-start-mcp/compare/v0.6.0...v0.7.0)
- Pitchfork Layout Specification — referenced by [data/scaffold-pitchfork-layout/SKILL.md]()
- CMake Presets v3 — referenced by [data/scaffold-cmake-presets/SKILL.md]()

---

<a id='page-installation'></a>

## Installation & Client Configuration

### Related Pages

Related topics: [Project Overview & MCP Architecture](#page-overview), [Interview Workflow & Usage Patterns](#page-workflow)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/README.md)
- [data/meta-quickstart/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/meta-quickstart/SKILL.md)
- [data/scaffold-agents/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-agents/SKILL.md)
- [data/scaffold-base-configs/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-base-configs/SKILL.md)
- [data/scaffold-cmake/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-cmake/SKILL.md)
- [data/scaffold-workspace-skills/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-workspace-skills/SKILL.md)
- [data/scaffold-pitchfork-layout/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-pitchfork-layout/SKILL.md)
</details>

# Installation & Client Configuration

## Overview

`cpp-quick-start-mcp` is a Model Context Protocol (MCP) server that bootstraps modern C++ projects through a guided interview with an AI agent. It exposes a curated library of `mcp://scaffold/*` resources and a `quickstart` prompt, letting any MCP-compatible client generate build files, manifests, agent guidelines, and directory structures consistent with current C++ best practices. Source: [README.md:1-40]()

This page focuses on getting the server installed, started, and wired into an MCP client, then summarizes what the client can expect to discover on the other end.

## Installation

The server is distributed as a Node.js package and can be installed globally in two ways. Source: [README.md:50-75]()

### Install from NPM (Recommended)

```bash
npm install -g @m-velikov/cpp-quick-start-mcp
```

This registers the `cpp-quick-start-mcp` binary on `PATH`, which is the command every MCP client will eventually invoke. Source: [README.md:55-60]()

### Install from Source (Local Development)

When cloning the repository for hacking on the server itself:

```bash
npm install
npm run build
npm install -g .
```

The first two commands resolve the project's own development dependencies and compile the TypeScript output; the third installs the locally built package globally so the `cpp-quick-start-mcp` command is available system-wide. Source: [README.md:63-73]()

## Server Startup Options

By default the server speaks MCP over standard I/O, which is the transport expected by most agent runtimes (Claude Desktop, IDE plugins, etc.). It can also be run standalone over HTTP/SSE. Source: [README.md:80-90]()

```bash
# Start with default options (port 3000, host 0.0.0.0)
cpp-quick-start-mcp --port 3000
```

When launched this way the server binds to all interfaces (`0.0.0.0`) on port `3000`, making it reachable from other machines on the network. The README explicitly notes that this HTTP/SSE mode is optional — for most agent workflows the stdio transport is sufficient. Source: [README.md:85-90]()

| Startup Mode | Transport | Use Case |
|---|---|---|
| `cpp-quick-start-mcp` (default) | stdio | Local MCP clients and IDE agents |
| `cpp-quick-start-mcp --port 3000` | HTTP/SSE | Network-accessible or shared dev environments |

## Client Configuration

Once installed, the server must be registered with an MCP-compatible client. The client is responsible for spawning the `cpp-quick-start-mcp` process (stdio mode) or pointing at the HTTP/SSE endpoint (network mode) defined above.

The server's onboarding flow is driven by the `quickstart` prompt, which performs a **Mode A** interview for new projects or a **Mode B** audit for existing repositories, then reads additional `mcp://scaffold/*` resources to fill in the chosen stack. Source: [data/meta-quickstart/SKILL.md:1-40]()

Typical configuration for a stdio-based MCP client (pseudo-config):

```json
{
  "mcpServers": {
    "cpp-quick-start": {
      "command": "cpp-quick-start-mcp",
      "args": [],
      "transport": "stdio"
    }
  }
}
```

For network mode, replace `command` with a `url` pointing at `http://<host>:3000`. Source: [README.md:85-90]()

## What the Client Discovers

After connecting, the client can enumerate the server's resources to understand the scaffolding surface area. The bundled resources cover every decision point the agent needs:

- **Build systems**: CMake, Make, Meson, Bazel — each skill enforces non-recursive architectures and target-based modularity. Source: [data/scaffold-cmake/SKILL.md:1-25](), [data/scaffold-make/SKILL.md:1-15]()
- **Package managers & packaging**: Conan, vcpkg — generating manifest files with locked baselines. Source: [data/scaffold-vcpkg/SKILL.md:1-25]()
- **Directory layouts**: Pitchfork Layout — the recommended structure for both single and multi-target projects. Source: [data/scaffold-pitchfork-layout/SKILL.md:1-40]()
- **CMake Presets**: `CMakePresets.json` generation to standardize `cmake --preset dev` workflows. Source: [data/scaffold-cmake-presets/SKILL.md:1-25]()
- **Testing frameworks**: Doctest boilerplate and integration recipes. Source: [data/scaffold-doctest/SKILL.md:1-25]()
- **Static analysis**: `.clang-tidy` and `cppcheck` configuration wired into both build targets and (optionally) pre-commit hooks. Source: [data/scaffold-clang-tidy/SKILL.md:1-25](), [data/scaffold-cppcheck/SKILL.md:1-25]()
- **Base repository files**: `.gitignore`, `.gitattributes`, and `.clangd` so Git, cross-platform line endings, and IDEs all behave correctly out of the box. Source: [data/scaffold-base-configs/SKILL.md:1-40]()
- **Agent topology**: An `AGENTS.md` index table that points future agents at the project's own workspace skills. Source: [data/scaffold-agents/SKILL.md:1-30]()

The permanent skills written into the user's project under `skills/<name>/SKILL.md` follow a strict structure — YAML frontmatter, kebab-case names, copy-pasteable commands, and ordered `## Commands` / `## Expected Output` sections — so downstream agents can rely on a predictable shape regardless of which skill they load. Source: [data/scaffold-workspace-skills/SKILL.md:1-25]()

## Common Failure Modes

1. **Command not found after install**: The global `node_modules` bin directory is not on `PATH`. Re-run with `npm install -g` or use `npx @m-velikov/cpp-quick-start-mcp` instead.
2. **Server starts but client sees no resources**: Some MCP clients cache the resource list at connect time. Restart the client (or reconnect the server) after upgrading — the v0.7.0 release added resources that older sessions may not surface.
3. **Mode B detects the wrong conventions**: When invoked against an existing project, the agent scans build files for hints. Make sure the project's primary build file (e.g. `CMakeLists.txt`, `Makefile`) is committed and not generated. Source: [data/meta-quickstart/SKILL.md:15-35]()

## See Also

- [Quickstart Interview Flow & Modes](quickstart-interview-flow.md)
- [Scaffolding Resources Reference](scaffolding-resources.md)
- [Workspace Skills Format](workspace-skills-format.md)

---

<a id='page-knowledge'></a>

## Scaffolding Skills Knowledge Base

### Related Pages

Related topics: [Project Overview & MCP Architecture](#page-overview), [Interview Workflow & Usage Patterns](#page-workflow)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/README.md)
- [data/meta-quickstart/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/meta-quickstart/SKILL.md)
- [data/scaffold-workspace-skills/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-workspace-skills/SKILL.md)
- [data/scaffold-cmake/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-cmake/SKILL.md)
- [data/scaffold-cmake-presets/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-cmake-presets/SKILL.md)
- [data/scaffold-bazel/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-bazel/SKILL.md)
- [data/scaffold-meson/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-meson/SKILL.md)
- [data/scaffold-make/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-make/SKILL.md)
- [data/scaffold-vcpkg/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-vcpkg/SKILL.md)
- [data/scaffold-doctest/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-doctest/SKILL.md)
- [data/scaffold-clang-tidy/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-clang-tidy/SKILL.md)
- [data/scaffold-cppcheck/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-cppcheck/SKILL.md)
- [data/scaffold-base-configs/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-base-configs/SKILL.md)
- [data/scaffold-pitchfork-layout/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-pitchfork-layout/SKILL.md)
- [data/scaffold-gitlab-ci/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-gitlab-ci/SKILL.md)
- [data/scaffold-agents/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-agents/SKILL.md)
</details>

# Scaffolding Skills Knowledge Base

The Scaffolding Skills Knowledge Base is the structured collection of Markdown-based instructional resources shipped under `data/scaffold-*` within the `cpp-quick-start-mcp` MCP server. It powers a "dynamic scaffolding" workflow in which an AI agent can read targeted skill files via the `mcp://scaffold/*` resource URIs and emit correct, opinionated boilerplate for a wide range of C++ toolchains. As described in [README.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/README.md), the knowledge base exists so the model "knows exactly how to write the requested boilerplate files perfectly" and seeds a project with "built-in guidelines and architecture rules" for safe agentic collaboration.

## Purpose and Scope

The knowledge base is **not** a static C++ tutorial. It is a curated set of executable instructions, each scoped to a single tool, layout, or workflow. Every skill file uses YAML frontmatter with `name` and a one-line `description` ending in `Use when ...` so an agent can decide whether to load it without reading the body.

Skills fall into three operational layers:

- **Meta-skill** — `data/meta-quickstart/SKILL.md` ("go") is a Level 2 meta-skill whose job is to interview the user, then synthesize a tailored scaffolding plan. It explicitly states it is a "Level 2 'Meta-Skill'. Its purpose is not to write C++ code directly, but to generate the _actual_ scaffolding skills (e.g., `scaffold-project`, `build-project`) tailored to the user's specific tooling choices." ([meta-quickstart/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/meta-quickstart/SKILL.md))
- **Per-tool scaffolding skills** — one skill per tool: `scaffold-cmake`, `scaffold-bazel`, `scaffold-meson`, `scaffold-make`, `scaffold-vcpkg`, `scaffold-doctest`, `scaffold-clang-tidy`, `scaffold-cppcheck`, `scaffold-cmake-presets`, `scaffold-base-configs`, `scaffold-pitchfork-layout`, `scaffold-gitlab-ci`, etc.
- **Project-emitted skills** — `scaffold-workspace-skills` defines the structure for the *permanent* task skills (e.g. `configure-project`, `build-project`, `test-project`) that get written into the user's `skills/` directory after scaffolding.

## Coverage of the C++ Stack

The knowledge base spans the major axes of a modern C++ project:

| Concern | Representative skills |
| --- | --- |
| Build systems | `scaffold-cmake`, `scaffold-bazel`, `scaffold-meson`, `scaffold-make` |
| Dependency / packaging | `scaffold-vcpkg` |
| Testing | `scaffold-doctest` (and additional testing skills under the same convention) |
| Static analysis / quality | `scaffold-clang-tidy`, `scaffold-cppcheck` |
| Build orchestration | `scaffold-cmake-presets` |
| Repo hygiene | `scaffold-base-configs`, `scaffold-pitchfork-layout` |
| CI | `scaffold-gitlab-ci` |
| Agent coordination | `scaffold-agents` |

Each skill encodes non-negotiable conventions. For example, `scaffold-cmake` mandates `cmake_minimum_required(VERSION 3.20)`, target-based Modern CMake, `cxx_std_20` via `target_compile_features`, and a critical modularity rule: "Do NOT create a single monolithic top-level `CMakeLists.txt` … you MUST split the build files per artifact." ([scaffold-cmake/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-cmake/SKILL.md)). `scaffold-make` enforces a non-recursive Makefile design, warning that "GNU Make does not support `**` globbing, so it would silently expand to nothing" if `$(wildcard ...)` is used naively ([scaffold-make/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-make/SKILL.md)). `scaffold-bazel` declares a root `MODULE.bazel` for Bzlmod and uses per-target `BUILD` files ([scaffold-bazel/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-bazel/SKILL.md)), while `scaffold-meson` follows the same modularity rule for Meson ([scaffold-meson/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-meson/SKILL.md)).

Quality, layout, and CI skills add their own firm rules. `scaffold-clang-tidy` requires the agent to ask the user about naming conventions before emitting `CheckOptions` for `readability-identifier-naming.*` ([scaffold-clang-tidy/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-clang-tidy/SKILL.md)). `scaffold-cppcheck` provides a `run-cppcheck` `add_custom_target` template wired into CMake with a curated `--suppress` list ([scaffold-cppcheck/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-cppcheck/SKILL.md)). `scaffold-pitchfork-layout` requires a target-namespaced `include/<target_name>/` subdirectory, explicitly forbidding flat headers ([scaffold-pitchfork-layout/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-pitchfork-layout/SKILL.md)). `scaffold-cmake-presets` standardizes configuration via a hidden base preset plus `dev`/`release` user-facing presets ([scaffold-cmake-presets/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-cmake-presets/SKILL.md)). `scaffold-base-configs` ships the canonical `.gitignore`, `.gitattributes`, and `.clangd` every project should have ([scaffold-base-configs/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-base-configs/SKILL.md)), and `scaffold-gitlab-ci` provides a two-stage (`build`, `test`) pipeline with ccache and per-package-manager caching ([scaffold-gitlab-ci/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-gitlab-ci/SKILL.md)).

## Skill Structure and Composition

Workspace-emitted skills are governed by `scaffold-workspace-skills`, which makes the format uniform. Every such skill must live at `skills/<skill-name>/SKILL.md` with kebab-case names, the same YAML frontmatter, copy-pasteable commands in fenced blocks (no unresolved placeholders), and, for task skills, a fixed `## Commands` / `## Expected Output` section order ([scaffold-workspace-skills/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-workspace-skills/SKILL.md)). `scaffold-agents` builds on this by populating an `AGENTS.md` index table whose rows are generated from the `description` of every skill actually present in `skills/`, ensuring future agents always read the relevant skill before acting ([scaffold-agents/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-agents/SKILL.md)).

The meta-skill orchestrates composition. `meta-quickstart` instructs the agent to first scan the working directory to decide between **Mode A: New Project Interview** and **Mode B: Add Components**, ask all 12 stack categories in batched multiple-choice questions, then call `list-resources` to discover every `mcp://scaffold/*` URI, perform a gap analysis, and "proactively suggest relevant ones to the user" — e.g. `scaffold-clang-tidy`, `scaffold-cppcheck`, `scaffold-code-hygiene`, `scaffold-github-actions` — before writing a single file ([meta-quickstart/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/meta-quickstart/SKILL.md)). This means the knowledge base is not consumed linearly; it is queried on demand and stitched together per project, which is why the v0.7.0 release emphasizes "Dynamic Scaffolding Resources" and an "Agent-Ready Architecture" in [README.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/README.md).

## See Also

- [cpp-quick-start-mcp overview and installation](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/README.md)
- Release notes: [v0.7.0 changelog](https://github.com/m-velikov/cpp-quick-start-mcp/compare/v0.6.0...v0.7.0)

---

<a id='page-workflow'></a>

## Interview Workflow & Usage Patterns

### Related Pages

Related topics: [Project Overview & MCP Architecture](#page-overview), [Scaffolding Skills Knowledge Base](#page-knowledge), [Installation & Client Configuration](#page-installation)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [data/meta-quickstart/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/meta-quickstart/SKILL.md)
- [data/scaffold-workspace-skills/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-workspace-skills/SKILL.md)
- [data/scaffold-cmake/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-cmake/SKILL.md)
- [data/scaffold-cmake-presets/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-cmake-presets/SKILL.md)
- [data/scaffold-agents/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/scaffold-agents/SKILL.md)
- [data/best-practices-meson/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/best-practices-meson/SKILL.md)
- [README.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/README.md)
</details>

# Interview Workflow & Usage Patterns

## Overview

`cpp-quick-start-mcp` is an MCP (Model Context Protocol) server that drives AI agents through a deterministic, interview-based workflow for creating and modernizing C++ projects. The centerpiece of this workflow is the Level 2 **meta-skill** `data/meta-quickstart/SKILL.md`, which delegates work to a library of single-purpose scaffolding skills (e.g., `scaffold-cmake`, `scaffold-meson`, `scaffold-pitchfork-layout`, `scaffold-doctest`). The result is an agentic stack that exposes curated `mcp://scaffold/*` resources and writes a project-specific `AGENTS.md` plus a `skills/` directory of permanent workspace skills ([README.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/README.md)).

The current latest release is **v0.7.0**, which incrementally refines this interview workflow; users upgrading from v0.6.0 should see no breaking changes to the MCP interface but should consult the [release comparison](https://github.com/m-velikov/cpp-quick-start-mcp/compare/v0.6.0...v0.7.0) for additions to the question set or new skill resources.

## Pre-flight Scan and Mode Selection

The interview always begins with a **pre-flight project scan**: the agent lists the working directory and looks for markers such as `CMakeLists.txt`, `Makefile`, or `src/`. Based on this scan, `data/meta-quickstart/SKILL.md` branches into one of two top-level modes:

- **Mode A — New Project Interview**: the directory is essentially empty.
- **Mode B — Add Components or Modernize**: an existing project is detected. The agent scans the build files and a few sources to infer conventions, then asks the user which path to take.

```mermaid
flowchart TD
    A[Pre-flight Scan] --> B{Empty dir?}
    B -- yes --> C[Mode A: 12-category interview]
    B -- no --> D[Mode B: Convention Scan]
    D --> E{User path?}
    E -- Path 1 --> F[Add Components]
    E -- Path 2 --> G[Modernize & Augment]
    C --> H[Step 2: Resource Discovery]
    F --> H
    G --> H
    H --> I[Generate scaffolding + workspace skills]
```

## Mode A: New Project Interview

When the directory is empty, the meta-skill requires the agent to ask the user about **12 mandatory categories** (build system, C++ standard, package manager, testing framework, formatter, linter, static analyzer, CI provider, pre-commit hooks, target platforms, project layout, license). Per `data/meta-quickstart/SKILL.md`, the agent must:

1. Use an **interactive multiple-choice question tool** (e.g., `ask_question`) with a free-form text input option, since users may have write-in answers.
2. Split questions across as many consecutive batches as the tool allows; **none of the 12 categories may be skipped, inferred, or dropped**, even if the tool only fits four questions per call.
3. After the interview, automatically load and apply the matching `scaffold-*` skill for each chosen component. For example, selecting **CMake** activates `data/scaffold-cmake/SKILL.md`, which mandates a target-based `CMakeLists.txt` per artifact with `cmake_minimum_required(VERSION 3.20)` (or higher) and `target_compile_features(... PUBLIC cxx_std_20)` enforced on the target rather than via `CMAKE_CXX_STANDARD`. Picking **CMake** also triggers `data/scaffold-cmake-presets/SKILL.md`, which requires a `CMakePresets.json` (version 3+) with a hidden base preset and user-facing `dev` / `release` presets inheriting from it.

## Mode B: Adding Components to or Modernizing an Existing Project

When a project already exists, the agent must NOT redo the full Mode A interview. Instead, per `data/meta-quickstart/SKILL.md`:

- The agent **auto-detects** the build system, package manager, directory layout, naming conventions, and formatting style from existing files.
- It asks the user to pick **Path 1 (Add Components)** or **Path 2 (Modernize & Augment)**.
- **Path 1** triggers a focused component interview: new libraries/executables, target platforms, and a layout-conformity check (e.g., proposing a migration to Pitchfork if the additions would violate the inferred layout).
- **Path 2** triggers a missing-tooling interview (`.clang-format`, pre-commit hooks, `.clang-tidy`, `cppcheck`, testing, CI/CD, `.gitignore`), a build-system evaluation that *avoids* migrations to a different family (e.g., Make → CMake is disallowed, but legacy CMake → target-based CMake is encouraged), an explicit Pitchfork-layout question, and a target-platforms question.

## Step 2: Resource Discovery and Proactive Suggestion

After either Mode concludes, the meta-skill requires the agent to call `list-resources` against the MCP server, fetch every relevant `mcp://scaffold/*` URI via `read-resource`, and include the full text of any matching best-practices resource into the generated workspace skills. This is what produces the project-specific `skills/best-practices-<component>/SKILL.md` files; for example, a Meson-based project receives `data/best-practices-meson/SKILL.md` content in full, covering structured `meson.build` files, dialect selection via `default_options: ['cpp_std=c++20']`, `dependency()` lookup, and the `meson test -C build` invocation ([data/best-practices-meson/SKILL.md](https://github.com/m-velikov/cpp-quick-start-mcp/blob/main/data/best-practices-meson/SKILL.md)).

The meta-skill also mandates specific workspace skills be created (always in full, never summarized):

- `skills/configure-project/SKILL.md` — exact dependency-fetch and configure commands.
- `skills/build-project/SKILL.md` — exact build commands.
- Component best-practices skills (e.g., `best-practices-cmake`).
- `skills/best-practices-refactoring/SKILL.md` — refactoring rules including the namespace/file-name consistency rule.
- `skills/best-practices-code-review/SKILL.md` — code-review rules.

## Workspace Skill Structure and `AGENTS.md`

Every skill written into the user's `skills/` directory must follow the contract in `data/scaffold-workspace-skills/SKILL.md`: kebab-case directory names matching the `name` field, a YAML frontmatter with `name` and a one-line `description` ending in `Use when ...`, copy-pasteable commands in fenced code blocks with no placeholders, and (for task skills) a `## Commands` section followed by `## Expected Output`.

The generated `AGENTS.md` (per `data/scaffold-agents/SKILL.md`) is the agent's entry point and must contain a **Workspace Skills** index table whose rows reflect only the skills actually present in `skills/`. Agents are instructed to scan this table first and load the relevant `SKILL.md` in full before configuring, building, testing, refactoring, or reviewing the project.

## Common Failure Modes

- **Skipping interview categories**: a known anti-pattern. The meta-skill explicitly forbids inferring or dropping any of the 12 categories.
- **Using recursive Makefiles**: `data/scaffold-make/SKILL.md` requires a non-recursive `Makefile` design because GNU Make does not support `**` globbing and recursive `$(MAKE)` calls hurt dependency tracking.
- **Replacing the build system family in Mode B**: never migrate Make → CMake or vice versa; only modernize within the existing family.
- **Summarizing MCP resources**: the meta-skill requires `read-resource` contents to be included in full in the generated workspace skills, not paraphrased.
- **Omitting `AGENTS.md` or `CMakePresets.json`**: when CMake is chosen, both files are mandatory outputs of the interview workflow.

## See Also

- [Scaffolding Skills](scaffolding-skills.md) — catalog of every `scaffold-*` resource.
- [Workspace Skills Format](workspace-skills.md) — detailed format spec for the generated `skills/` directory.
- [Best Practices Library](best-practices.md) — full list of `best-practices-*` resources embedded into projects.

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: m-velikov/cpp-quick-start-mcp

Summary: Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

## 1. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://github.com/m-velikov/cpp-quick-start-mcp

## 2. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/m-velikov/cpp-quick-start-mcp

## 3. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/m-velikov/cpp-quick-start-mcp

## 4. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/m-velikov/cpp-quick-start-mcp

## 5. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/m-velikov/cpp-quick-start-mcp

## 6. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/m-velikov/cpp-quick-start-mcp

## 7. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/m-velikov/cpp-quick-start-mcp

<!-- canonical_name: m-velikov/cpp-quick-start-mcp; human_manual_source: deepwiki_human_wiki -->