cpp-code-change - SKILL.md Agent Skill

mustflow_doc: skill.cpp-code-change locale: en canonical: true revision: 1 lifecycle: mustflow-owned authority: procedure name: cpp-code-change description: Apply this skill when C++ source, headers, modules, native build metadata, toolchains, package managers, ABI surfaces, generated bindings, FFI, tests, or benchmarks are created or changed. metadata: mustflow_schema: "1" mustflow_kind: procedure pack_id: mustflow.core skill_id: mustflow.core.cpp-code-change command_intents: - changes_status - changes_diff_summary - lint - build - test_related - test - docs_validate_fast - test_release - mustflow_check

C++ Code Change

Purpose

Preserve C++ target identity, ownership, lifetime, undefined-behavior, build-graph, API, ABI, FFI, generated-binding, modern-language, concurrency, and performance contracts while making a focused change.

A C++ change is successful only when the affected target and consumed surface are understood. Local compile success alone does not prove C++ correctness, compatibility, ABI safety, memory safety, or performance.

Use When

.c, .cc, .cpp, .cxx, .h, .hh, .hpp, .hxx, .ipp, .tpp, .ixx, .cppm, C++ tests, examples, benchmarks, modules, or generated C++ glue change.
C++ build metadata changes, including CMakeLists.txt, CMakePresets.json, toolchain files, meson.build, meson_options.txt, Meson native or cross files, BUILD, BUILD.bazel, .bazelrc, WORKSPACE, MODULE.bazel, Makefile, .mk, Autotools files, conanfile.py, conanfile.txt, conan.lock, Conan profiles, vcpkg.json, vcpkg-configuration.json, triplets, package config files, or pkg-config files.
The task touches C++ standard version, compiler, standard library, ABI mode, platform branches, generated bindings, shared or static library artifacts, exported symbols, public headers, FFI, ownership, raw pointers, references, smart pointers, views, iterators, allocators, exceptions, errors, templates, concepts, coroutines, modules, atomics, locks, sanitizers, fuzzing, or benchmarks.

Do Not Use When

C++ files are read-only context and no C++ source, header, build, package, binding, test, or benchmark surface changes.
The task is only formatting, comments, or documentation and does not affect a public header, exported symbol, generated binding, FFI surface, build graph, or documented C++ contract.
A generated C++ file must be regenerated by a declared project command rather than edited manually.
The change is purely C source with no C++ target, C++ compiler, C++ ABI, C++ build metadata, or C++ consumer boundary involved.

Required Inputs

Changed files and their consumed surface classification: private implementation, private header, public header, module interface, shared library, static library, executable, generated binding input, generated binding output, FFI boundary, test, benchmark, or build metadata.
Owning build target for every changed C++ source, header, module, generated file, and native artifact.
Target-specific compilation identity: C++ standard, compiler family and version, standard library, ABI mode, exception and RTTI mode, build type, platform, architecture, visibility policy, linkage mode, dependency source, and active build front door when available.
Relevant CMake, Meson, Bazel, Make, Autotools, Conan, vcpkg, pkg-config, CI, package, and install/export metadata.
Public headers, exported symbols, public types, public constants, macros, enum values, generated bindings, FFI functions, target-language surfaces, and downstream consumer expectations when any public surface changes.
Ownership, lifetime, allocator, error, exception, callback, thread-safety, synchronization, and performance contracts touched by the change.
Configured verification intents from the repository command contract.

Preconditions

Determine the owning build target before editing. Do not treat repository-wide defaults, editor settings, or the local machine compiler as target authority.
Determine whether the change can affect source API, binary ABI, generated binding API, FFI ABI, behavior, memory safety, thread safety, performance, package consumers, or only private implementation.
Classify compatibility risk by the highest-risk consumed surface touched by the change. Do not downgrade risk because the diff is small, private-looking, or compile-clean.
If C++ standard, compiler, standard library, ABI mode, platform, dependency source, active build front door, or owning target cannot be determined, report the missing boundary and avoid changes that depend on it.
Use only configured command intents for validation. Do not invent native build, test, sanitizer, fuzz, package, or benchmark commands.

Allowed Edits

Keep edits scoped to the affected C++ target, build graph, tests, generated-binding source of truth, and directly synchronized docs or template surfaces.
Prefer RAII, rule of zero, value semantics, explicit ownership transfer, explicit borrowed views, and narrow lifetime contracts over raw ownership or hidden sharing.
Prefer additive API and ABI changes when existing consumers must keep working.
Add focused tests, compile checks, smoke tests, or benchmark guards only when they protect the changed C++ contract and are covered by configured intents.
Do not hand-edit generated output unless the project explicitly treats it as authoritative or the user explicitly requests it with the drift risk understood.
Do not weaken compiler, warning, sanitizer, ABI, package, test, or compatibility checks to make a patch appear complete.

Procedure

Read the repository instructions and configured command intents, then inspect the changed C++ files plus nearby source, headers, tests, build files, package metadata, and CI hints.
Identify the owning target for each changed file. For CMake, inspect target sources, include directories, compile definitions, compile features, options, link libraries, install/export surfaces, and public/private/interface propagation. For Meson, inspect targets, dependencies, include directories, options, cross/native files, and install surfaces. For Bazel, inspect cc_library, cc_binary, cc_test, srcs, hdrs, deps, implementation_deps, defines, local_defines, visibility, toolchains, and select() branches. For Make or Autotools, inspect object rules, included fragments, flags, libraries, generated headers, and install surfaces.
Identify the active build front door. If several active graphs own the same changed file, keep them synchronized or report the unsupported or stale graph explicitly.
Record the target compilation identity: C++ standard, compiler, standard library, ABI mode, platform, architecture, build type, exception and RTTI mode, visibility, linkage, dependency source, and generated-header source when relevant.
Classify risk by highest consumed surface:
- internal_only: private implementation or private helper only.
- source_api: public header, exported type, namespace, macro, enum, overload, template, inline function, default argument, include path, or package consumer compile surface.
- binary_abi: shared library symbol, public object layout, vtable, RTTI, calling convention, visibility, allocator boundary, exception boundary, struct packing, alignment, or ABI flag.
- static_link_contract: static artifact, object compatibility, compile flags, PIC, LTO, link order, duplicate symbol, ODR, or consumer relink surface.
- generated_binding: generator input, generated output, wrapper API, target-language package surface, ownership mapping, nullability, or exception/error mapping.
- ffi_boundary: extern "C", callback, raw buffer, fixed layout, allocator, ownership/free function, error ABI, calling convention, or cross-language thread ownership.
- semantic_compatibility: behavior, ownership, lifetime, error, ordering, threading, range, default, or resource contract changed without a signature change.
- performance_resource: hot path, allocation, lock contention, inlining, template instantiation, serialization, binary size, latency, throughput, or memory footprint.
For ownership and lifetime changes, classify every affected value as owner, borrowed non-null reference, borrowed nullable pointer, view, iterator, handle, shared owner, weak observer, or moved-from value. Check raw pointer ownership, reference escape, lambda capture, async or callback storage, move-after-use, unique_ptr::release, duplicate shared_ptr ownership, custom deleters, container invalidation, member initialization order, and RAII cleanup on failure paths.
For undefined-behavior risk, inspect dangling pointers and references, iterator invalidation, uninitialized memory, out-of-bounds access, signed overflow, bad shifts, strict aliasing, alignment, object lifetime, invalid downcasts, non-virtual base deletion, data races, C string length mistakes, and string_view or span lifetime.
For public headers, review function signatures, overload sets, namespaces, includes, macros, type aliases, enum values, constants, templates, inline functions, public class layout, virtual functions, base classes, alignment, default arguments, exported concepts, deduced return types, modules, and standard-library types exposed as API or ABI.
For shared libraries, review exported symbol names, symbol visibility, version scripts, import/export macros, SONAME or equivalent policy, name mangling, calling convention, public object layout, vtable layout, RTTI, exception behavior, allocator ownership, dependency ABI, and standard-library ABI flags.
For static libraries, review rebuild and relink contracts, public headers, object compatibility, compiler and standard-library assumptions, build flags, PIC, LTO, ODR risk, duplicate symbols, and consumer link behavior. Do not treat static libraries as ABI-free.
For generated bindings, identify the source of truth, generator version when available, generated output, target-language API, smoke tests, and ownership/error/nullability mapping. Reject source/output drift unless the drift is explicitly intended and verified.
For FFI, prefer a stable C ABI unless the project explicitly marks the boundary unstable. Use fixed-size types, explicit layout, explicit ownership and release functions, explicit error reporting, explicit calling convention, null handling, callback lifetime rules, and thread ownership. Do not leak C++ exceptions, STL types, templates, overloaded functions, implicit ownership, or compiler-specific C++ ABI across FFI without an explicit unstable-boundary policy.
For template, concepts, overload, ADL, and SFINAE changes, verify positive and negative compile behavior when configured checks exist. Review which overloads are added, removed, or silently selected differently. Use return-type, constraint, and ADL fixtures when the repository has that pattern.
For error handling, classify failures as programmer bug, recoverable input or environment failure, resource failure, or invariant violation. Preserve the layer's existing channel: exceptions, error codes, project Result, std::expected, assertions, or logging. Do not mix two public failure channels for the same failure without a boundary reason. Treat noexcept as a termination contract, not a performance hint.
For concurrency, list shared mutable state, owner thread, guard mutex, atomic invariant, lifetime rule, lock ordering, callback execution, shutdown path, and join or wait path. Do not introduce unguarded shared mutation, locks held across callbacks or blocking I/O, unexplained memory orders, detached lifetime, or relaxed atomics without proof.
For modern C++ features, reject changes justified only as modern, shorter, or cleaner-looking. A feature is allowed only when it removes a concrete failure mode, narrows state, clarifies lifetime or ownership, improves misuse resistance, or has measured performance value. Check public-surface exposure, compiler support, standard-library support, build-system support, CI support, and fallback or configure-time failure before adopting C++20 or C++23 features.
Treat std::span, std::string_view, ranges views, iterator/sentinel pairs, and coroutine captures as borrowed views. Never store or return them unless owner lifetime is explicit and verified.
For performance work, require baseline, workload, target metric, profile evidence, hypothesis, targeted change, remeasurement, and regression guard when configured verification exists. Do not claim performance from syntax changes, std::move, string_view, ranges, modules, coroutines, or constexpr without evidence or a clear complexity argument.
Choose configured validation by highest-risk surface. All C++ changes need compile-equivalent validation when available. Public headers need downstream-style compile or public-header validation when available. Library artifacts need link validation when available. Shared ABI changes need ABI or exported-symbol validation when available. Generated bindings need regeneration and target-language smoke validation when available. FFI changes need boundary smoke and memory validation when available. Hot-path changes need benchmark validation when available.

Review Rejection Criteria

Reject or revise the patch when any of these appear without strong local evidence and risk reporting:

A changed C++ file has no identified owning target, active build front door, or compilation identity.
A public header, exported symbol, generated binding, FFI surface, or library artifact changes without compatibility classification.
API compatibility is claimed without inspecting public headers, generated bindings, or downstream-style consumer compile surface.
ABI compatibility is claimed after exported symbols, object layout, vtable layout, calling convention, visibility, or FFI layout changed without ABI or equivalent binary-compatibility evidence.
A raw pointer, reference, view, iterator, or callback is stored or returned without owner lifetime evidence.
std::string_view, std::span, ranges views, coroutine captures, or iterator pairs outlive their owner or cross mutation/reallocation boundaries without proof.
std::move, unique_ptr::release, shared_ptr, custom deleters, or manual cleanup obscure ownership transfer.
New manual new, delete, malloc, free, close, unlock, or release paths appear where RAII can express the ownership.
A noexcept function calls code that may throw without an intentional termination policy.
Public API exposes C++20 or C++23 features without consumer compiler, standard-library, build-system, and fallback review.
Performance improvement is claimed without baseline, workload, measurement, or complexity evidence.
Sanitizer, ABI, FFI, binding, benchmark, or downstream checks are missing but the output claims those properties were proven.

Postconditions

The owning target, active build graph, and target compilation identity are known or the missing boundary is reported.
The highest compatibility risk is stated: internal-only, source API, binary ABI, static-link contract, generated binding, FFI, semantic compatibility, or performance/resource.
Ownership, lifetime, allocator, error, concurrency, and modern-feature impacts are intentional and evidence-backed.
Public headers, exported symbols, generated bindings, FFI surfaces, build metadata, tests, docs, and template surfaces are synchronized when they are part of the changed contract.
Generated files match their source of truth and generator flow, or drift is reported.
No API, ABI, memory-safety, thread-safety, FFI, binding, or performance compatibility is claimed beyond the validation evidence.

Verification

Use configured oneshot command intents when available:

lint
build
test_related
test
docs_validate_fast
test_release
mustflow_check

Choose validation by highest-risk surface, not by diff size.

Report whether configured validation exists for C++ compile, public-header compile, downstream consumer compile, link, unit, integration, API diff, ABI diff, generated-binding regeneration, target-language smoke, FFI smoke, sanitizer, valgrind or equivalent memory analysis, fuzzing, benchmark, and package-consume scenarios when those surfaces change.

When a required validation intent is unavailable, record the missing intent, why it matters, the weaker validation that was run, and the remaining compatibility risk. Do not invent a command or claim compatibility was proven.

Failure Handling

If the owning target or active build front door is unclear, stop the risky part and inspect build metadata before editing further.
If multiple build graphs own the same changed file and only one can be updated, report the stale graph and compatibility risk.
If public API or ABI policy is absent, classify the risk explicitly instead of assuming semver, SONAME, or package compatibility rules.
If generated bindings drift, restore source/output alignment or report the generator/source-of-truth gap.
If an ownership or lifetime fix creates broad shared ownership, manual cleanup, or hidden view lifetime, revisit the owner boundary before continuing.
If concurrency changes lack a synchronization proof, stop that part and inspect the state owner, guard, lifetime, and shutdown path.
If performance measurements are unavailable, report that performance compatibility was not proven.

Output Format

Boundary checked
Owning target and compilation identity
Highest compatibility risk
Ownership, lifetime, UB, concurrency, modern-feature, or performance impact
Public API, ABI, binding, FFI, or build-graph impact
Files changed
Command intents run
Skipped checks and reasons
Remaining C++ risk