skills-win/cubemx-min-prj/SKILL.md

name, description

name	description
cubemx-min-prj	Create a minimal STM32CubeMX reproduction project from scratch, regenerate code, and verify the local build/debug setup. Use when Codex needs to reproduce an STM32 issue in a clean workspace, derive a smallest CubeMX+CMake project from an existing board/project, rebuild `.vscode` STM32 debug files, or document the exact CubeMX CLI and `.ioc` patching steps required to recreate the project.

CubeMX Minimal Project

Create a fresh STM32CubeMX project that reproduces only the hardware and firmware behavior the user needs to debug. Prefer a clean, scriptable reproduction over copying a large existing workspace.

Workflow

1. Inspect the source context.

• Read the target .ioc, build presets, and any .vscode files before creating the reproduction.
• Identify the minimum MCU, clock tree, peripherals, DMA/NVIC settings, and user-code hooks required to reproduce the issue.
• Keep explicit dates and tool versions. For this workspace, the known-good CubeMX version is 6.11.1.

2. Verify local tools.

• Detect the installed STM32CubeMX path and version before touching .ioc metadata.
• Run the local version check command from REPRODUCTION_GUIDE.md first.
• Stop immediately unless the detected version is exactly 6.11.1 or starts with 6.11.1-.
• Confirm CMake, the selected toolchain, and any STM32CubeCLT paths needed for build/debug are present.
• If the installed CubeMX is older than the source .ioc format, stop and report the version mismatch.

3. Create the reproduction workspace.

• Default to a new subdirectory such as reproduction/ under the current workspace.
• Generate the base project from CubeMX CLI/script mode instead of copying generated sources.
• Keep the project minimal: only add the peripherals, pins, and middleware needed to reproduce the issue.

4. Configure CubeMX deterministically.

• Use CubeMX script commands for project creation, pin assignment, peripheral mode selection, and code generation whenever the CLI supports it.
• If CubeMX CLI cannot express required metadata, patch the .ioc directly with exact keys and then regenerate code.
• Treat the .ioc as the source of truth. Do not hand-edit generated C files first and backfill the .ioc later.

5. Patch only the user-owned parts of generated code.

• Restrict manual source changes to /* USER CODE BEGIN */ regions or isolated helper functions added specifically for the reproduction.
• Use this for items like printf retargeting, DMA idle receive callbacks, or small harness logic that CubeMX cannot generate.

6. Rebuild the developer workflow when requested.

• Mirror .vscode/settings.json, tasks.json, launch.json, c_cpp_properties.json, and extensions.json only if the user wants a debug-ready workspace.
• Reuse the existing project's naming and only swap the target ELF/project name where needed.
• Read DEBUG_SETUP.md for the BMSv31-style VS Code template expected in this workspace.

7. Validate before finishing.

• Re-open the .ioc in CubeMX after any direct file patching and confirm the GUI reflects the intended configuration.
• Run cmake --preset Debug and cmake --build --preset Debug unless the user explicitly asks only for scaffolding.
• Confirm the expected ELF exists under build/Debug/.
• Treat the task as incomplete if CubeMX generation or local build verification was skipped without user approval.

Guardrails

• Prefer the smallest reproducible project, not a feature-complete clone.
• Do not proceed with project creation, .ioc edits, or code generation when CubeMX is not 6.11.1 or 6.11.1-*.
• Preserve exact issue-critical details such as clock values, DMA streams, NVIC enables, and peripheral modes.
• Use absolute paths inside one-off local commands only when required by CubeMX or local tooling.
• Keep generated project names, MCU names, and toolchain selections explicit in the final notes.
• If reproducing from a larger project, document what was intentionally omitted.
• If CubeMX silently rewrites required metadata, capture the exact .ioc keys that must be re-applied.

References

• Read REPRODUCTION_GUIDE.md when the task is specifically to recreate the known STM32F407ZGTx/BMSv4 minimal project with CubeMX CLI, .ioc patching, user-code updates, and local build verification.
• Read DEBUG_SETUP.md when the task includes restoring VS Code Cortex-Debug, flash tasks, STM32CubeCLT paths, or extension recommendations.