copilot-instructions rework, new C++ coding guide for AI reviews

[softhack007]

Reworks AI instructions, to separate "coding agent" from "code review" instructions.
Adds C++ coding guidelines that were extracted from the WLED source code (mainly by AI). The new guides can be used both for contributor information, and as a "best practice" database in automated code reviews by the rabbit.

Update: I've moved the coding style guides into their own directory /docs, and "out of the way" for non-review agent tasks. It seems that AI agent tasks ("I need a new bus driver for my Daimler") work faster without the "code review" add-on guides - the agent will still find docs when it needs help. Code reviews (coderabbitAI) with detailed guides are still much better.

Details

• shortens previous instruction file, by removing duplicated information and shortening sentences
• moves agent instructions into a separate file
• adds coding conventions for C++, webUI, CI/CD (based on WLED-MM, needs adjustment for WLED)
• adds .coderabbit.yaml so the rabbit uses the same instructions for reviews that copilot sees.
• Introduces a HUMAN_ONLY mechanism that hides generic information from the AI, to increase "attention layer excitement"

Example for a coderabbit review with the new instructions: MoonModules#324 (comment)
(notice that recommendations refer to the new guidelines, and there is a "things done well" section, too)

This is a request for discussions

The new instructions already work well in WLED-MM, but we need to adjust them for WLED. Most importantly, optimization guides for ESP8266 still need to be added.

more information:

• Revise copilot-instructions.md: consolidate, shorten, and extract language-specific rules, take 2 MoonModules/WLED-MM#353
• Revise *.instructions.md: separate AI-relevant special knowledge from background information for contributors  MoonModules/WLED-MM#354

---

Revising AI review instructions:

• Reduce context window use for AI review tools, by avoiding repeating common knowledge and API information that is (usually) part of the AI training datasets any way.
• Introduce a mechanism to maintain both parts in single files, to avoid "silent diversion" over time
• Adding a coderabbit path instruction that ensures cross-checking of both parts whenever a PR modifies instruction files
• Primary Goal: only inject content in AI-visible areas that are WLED–specific or which deviate from general knowledge (the context window "token cost" of true false-positive suppressors is always worth it).
• Soft goal: keep each file's AI-facing section lean enough that the signal-to-noise ratio in the attention layer stays high — around 1,500–2,000 words per file type is a reasonable practical ceiling for current models.
• Aspirational: 500 words per file if achievable without sacrificing review quality.

---

Guiding Principles for Efficient AI Instruction Files

1. Only document what can't be inferred from the code or from general training.
   If the AI would get it right without instruction 95% of the time, the instruction probably isn't worth the extra space in context memory.

2. Prefer short, actionable rules over explanations.
   "Do not flag uint8_t x = int(f) as a bug when the comment says // float→int wrapping" is more useful than a paragraph explaining why. The paragraph is for humans; the rule is for AI.

3. Keep the total injected instruction size per file type low (<1000 lines, best under ~500 words).
   With lots of instructions, the value of additional instructions drops rapidly and the distraction cost rises.

4. Encode "false positive suppressors" first, feature guidance second.
   "Don't flag pattern X as a bug" is more impactful than "always do Y" because it directly prevents noise.

5. Treat instruction files like tests — they need maintenance when the code changes.
   If you wouldn't update the instruction file when refactoring the relevant code, don't write the instruction.

Large language models already have extensive general knowledge about C++, ESP-IDF, GitHub Actions, etc. The genuine value of instruction files is narrow but real:

What AI genuinely doesn't know without you telling it	What AI already knows well enough
Your project's intentional deviations from general best practice	General C++ / ESP-IDF / GitHub Actions patterns
Decisions that look like bugs but aren't (e.g. a float→int→uint8_t wrapping pattern)	Standard style rules
Which files/patterns to ignore or treat as deprecated	Common security practices
Your PR process expectations	How delay() works in FreeRTOS
Project-specific macro semantics (WLED_DISABLE_2D, d_malloc)	Memory allocation tradeoffs
Which reviewer comments are out of scope for this PR	Naming conventions

The key insight: instruction files are most valuable when they prevent false positives (AI flagging intentional patterns as bugs) and encode decisions that can't be inferred from the code alone.

---

Summary by CodeRabbit

• Documentation

  • Added comprehensive C++ and Web UI coding guides, CI/CD workflow conventions, and an agent-mode build/test workflow with validation and troubleshooting steps
  • Updated contributor guidance to reference the new instruction sets

• Chores

  • Added repository-level review automation with path-scoped guidance enforcing formatting, build/CI practices, and rules for generated assets

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 571595ce-adc3-4818-9c60-f7938110e2d5

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Walkthrough

This pull request establishes comprehensive code review guidance and developer documentation for the WLED repository. A new .coderabbit.yaml configuration file enables AI-assisted code review with path-scoped instructions for C++, web UI, community extensions, and CI/CD workflows. New instruction documents define coding conventions for C++, web UI development, and CI/CD practices, while existing documentation is updated to reference these guides.

Changes

Cohort / File(s)	Summary
CodeRabbit Configuration .coderabbit.yaml	Repository-wide configuration enabling CodeRabbit with path-scoped review instructions for C++, web UI assets, community extensions, CI/CD workflows, and auto-generated header file validation.
Build and Workflow Guidance .github/agent-build.instructions.md, .github/copilot-instructions.md	New and updated documentation specifying build procedures, timeouts, completion gates, and AI-assisted development workflows for Web UI and firmware changes.
Contributor Documentation CONTRIBUTING.md	Updated to direct contributors to auto-generated detailed instruction guides and reference CodeRabbit bot suggestions.
Domain-Specific Instruction Guides docs/cpp.instructions.md, docs/web.instructions.md, docs/cicd.instructions.md	New comprehensive coding convention documents covering C++ formatting, naming, and performance optimization; web UI structure and build integration; and GitHub Actions workflow security and structure standards.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• Improved Contributor Guidelines & Education (#5348, part1) #5350: Modifies CONTRIBUTING.md to add contributor guidance, overlapping with this PR's documentation structure updates.

Suggested reviewers

• netmindz
• DedeHai
• willmmiles
• Aircoookie

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically identifies the main changes: restructuring copilot instructions and introducing C++ coding guidelines for AI reviews.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch copilot_restructure

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

docs/cpp.instructions.md (1)

458-458: Use hyphenated compound adjective for readability.

“bus-level” reads cleaner than “bus level” in this sentence.

✏️ Suggested wording tweak

-- `delay()` on the bus level is allowed, it might be needed to achieve exact timing in LED drivers.
+- `delay()` on the bus-level is allowed, it might be needed to achieve exact timing in LED drivers.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/cpp.instructions.md` at line 458, Replace the phrase "bus level" with
the hyphenated compound adjective "bus-level" in the sentence that mentions
`delay()` and LED drivers (the sentence starting "`delay()` on the bus level is
allowed, it might be needed to achieve exact timing in LED drivers"); update
that sentence to use "bus-level" for improved readability.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@docs/cpp.instructions.md`:
- Line 458: Replace the phrase "bus level" with the hyphenated compound
adjective "bus-level" in the sentence that mentions `delay()` and LED drivers
(the sentence starting "`delay()` on the bus level is allowed, it might be
needed to achieve exact timing in LED drivers"); update that sentence to use
"bus-level" for improved readability.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 7bf82130-ca5b-4053-91cb-c3fac3bc8fce

📥 Commits

Reviewing files that changed from the base of the PR and between 1172fda and e668851.

📒 Files selected for processing (2)

• CONTRIBUTING.md
• docs/cpp.instructions.md

[softhack007]

@coderabbitai please compare your learnings against the new documents added in this PR:

• highlight any contradictions / conflicts
• list learnings that could be removed after merging this PR
• suggest small additions that would make some more learnings obsolete

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

Let me read the new documents to perform a thorough comparison.

---

🏁 Script executed:

#!/bin/bash
echo "=== docs/cpp.instructions.md ==="
cat docs/cpp.instructions.md
echo ""
echo "=== docs/web.instructions.md ==="
cat docs/web.instructions.md
echo ""
echo "=== docs/cicd.instructions.md ==="
cat docs/cicd.instructions.md
echo ""
echo "=== .coderabbit.yaml ==="
cat .coderabbit.yaml
echo ""
echo "=== .github/copilot-instructions.md ==="
cat .github/copilot-instructions.md
echo ""
echo "=== .github/agent-build.instructions.md ==="
cat .github/agent-build.instructions.md
echo ""
echo "=== CONTRIBUTING.md ==="
cat CONTRIBUTING.md

Length of output: 59158

---

@softhack007 Here is the comparison:

---

✅ Contradictions / Conflicts

None found. All retrieved learnings are fully consistent with the new documents.

---

🗑️ Learnings that could be removed after merging this PR

Learning ID	Reason for removal
c6c65ad6	Fully covered by .github/copilot-instructions.md → "Pull Request Expectations" (description of what/why, links to issues, screenshots for new features) and CONTRIBUTING.md → "Describing your PR"
84fc73d2	Fully covered by .github/copilot-instructions.md → "Attribution for AI-generated code" ("AI-generated code must be well documented with meaningful comments…") and docs/cpp.instructions.md → "Comments / AI attribution" block
e52191a3	The general rule is now in docs/cpp.instructions.md → "General" section: "Avoid unexplained 'magic numbers'. Prefer named constants (constexpr) or C-style #define constants…"
b0d4effd	Duplicate of e52191a3 (identical guidance), same removal rationale

---

🔒 Learnings that must be retained

These are not covered by the new documents:

Learning ID	Why to keep
b23420f0 / 06a0bc91	PR #5456-specific ESP-IDF / CHIP SDK build configuration detail — not appropriate for the general coding guides
0df52664	PR #4838-specific dead code note (fastled-slim, lib_archive) — no relevant home in these docs
32ab6218	PR #5048-specific temporary hotfix in wled_metadata.cpp — will self-expire when removed
1ae8c66c	PR #5048-specific ESP32-C5 NTP crash workaround — same as above
e174bc9e	docs/cpp.instructions.md only says "FX.cpp has diverse styles — that is acceptable" for style; it does not say gamma-related calls are intentional effect-level shaping and must not be removed
517af376	FMEA pattern not mentioned anywhere in the new documents
684ba401	LittleFS filename limit (255 bytes) is not mentioned anywhere in the new documents

---

💡 Small additions that would make more learnings obsolete

Three targeted additions would eliminate four more learnings:

1. In docs/cpp.instructions.md — add a LittleFS note under the "Strings" or "Memory" section → obsoletes 684ba401:

- **LittleFS filename limit**: LittleFS enforces a **255-byte filename limit** by default.
  Verify that paths passed to `file.open()` (including segment names, preset names, etc.)
  cannot exceed this limit. Do not assume non-standard configurations.

2. In docs/cpp.instructions.md — extend the FX.cpp note → obsoletes e174bc9e:

Note: `FX.cpp` (effect functions) is written by many contributors and has diverse styles — that is acceptable.
Some gamma-related calls inside `FX.cpp` and the particle system are **intentional effect-level shaping**
(e.g. brightness curves, TV sim, Pride 2015 pre-mix) — these are distinct from final output gamma correction
and must not be removed.

3. In .github/copilot-instructions.md — add a review methodology note → obsoletes 517af376:

- **For "is it worth doing?" debates** about proposed reliability, safety, or data-integrity mechanisms
  (CRC checks, backups, power-loss protection): suggest a software **FMEA** (Failure Mode and Effects
  Analysis). Enumerate failure modes, assess each mitigation's effectiveness per failure mode, note
  common-cause failures, and rate credibility for the typical WLED use case.

---

🧠 Learnings used

Learnt from: softhack007
Repo: wled/WLED PR: 5456
File: platformio.ini:794-830
Timestamp: 2026-03-31T13:42:00.444Z
Learning: In WLED PR `#5456` (Matter over WiFi usermod, CMakeLists.txt + platformio.ini): The GCC 14 chip::to_underlying compatibility issue with CHIP SDK's TypeTraits.h is fixed by building in gnu++20 mode (not gnu++2b/gnu++23). CMakeLists.txt uses `idf_build_replace_option_from_property` to swap `-std=gnu++2b` for `-std=gnu++20` when the matter usermod is present. The `matter_gcc14_compat.h` shim file (which pre-defines `chip::to_underlying` and sets `CHIP_TO_UNDERLYING_DEFINED`) is dead code under this configuration — it is never included anywhere. TypeTraits.h's broken C++23 `using std::to_underlying` alias path is only taken in gnu++23 mode; in gnu++20 mode CHIP defines its own `chip::to_underlying` function template normally, so no shim is needed. Additionally, upstream connectedhomeip TypeTraits.h already has the fix built-in. ESP-IDF v5.5 uses GCC 14.2.0. Do NOT flag the missing `-include` for `matter_gcc14_compat.h` as a build issue.

---

Learnt from: softhack007
Repo: wled/WLED PR: 5456
File: platformio.ini:794-830
Timestamp: 2026-03-31T13:42:00.444Z
Learning: In WLED PR `#5456` (Matter over WiFi usermod, CMakeLists.txt + platformio.ini): The GCC 14 chip::to_underlying compatibility issue with CHIP SDK's TypeTraits.h is fixed by building in gnu++20 mode (not gnu++2b/gnu++23). CMakeLists.txt uses `idf_build_replace_option_from_property` to swap `-std=gnu++2b` for `-std=gnu++20` when the matter usermod is present. The `matter_gcc14_compat.h` shim file (which pre-defines `chip::to_underlying` and sets `CHIP_TO_UNDERLYING_DEFINED`) is dead code under this configuration — it is never included anywhere. TypeTraits.h's broken C++23 `using std::to_underlying` alias path is only taken in gnu++23 mode; in gnu++20 mode CHIP defines its own `chip::to_underlying` function template normally, so no shim is needed. Do NOT flag the missing `-include` for `matter_gcc14_compat.h` as a build issue.

---

Learnt from: softhack007
Repo: wled/WLED PR: 0
File: :0-0
Timestamp: 2026-03-15T13:21:32.008Z
Learning: In WLED code reviews (and generally), when a PR discussion involves "is this worth doing?" uncertainty about a proposed reliability, safety, or data-integrity mechanism (e.g. CRC checks, backups, power-loss protection), suggest performing a software FMEA (Failure Mode and Effects Analysis). The FMEA should: enumerate failure modes for the feared event, assess each mitigation's effectiveness per failure mode, note common-cause/common-mode failures, and rate credibility for the typical WLED use case. This was successfully used in PR `#5421` to evaluate CRC-based config file protection and was well-received by the WLED maintainers (softhack007 explicitly requested this be remembered for future reviews).

---

Learnt from: softhack007
Repo: wled/WLED PR: 0
File: :0-0
Timestamp: 2025-11-14T13:37:11.994Z
Learning: In WLED code reviews, when code is modified or added, look for "magic numbers" (hardcoded numeric literals) and suggest replacing them with appropriate defined constants when those constants are meaningful in the context of the PR. For example, the hardcoded value 32 should be replaced with WLED_MAX_SEGNAME_LEN when it represents a segment name length limit. This improves code maintainability and reduces the risk of inconsistencies.

---

Learnt from: softhack007
Repo: wled/WLED PR: 4838
File: platformio.ini:149-150
Timestamp: 2026-03-29T16:47:56.452Z
Learning: In WLED PR `#4838` (ESP-IDF V5 branch, platformio.ini): The original FastLED library has been replaced with a custom `fastled-slim` fork. As a result, the `[v5_pioarduino_workaround]` section (containing `lib_archive = yes`) and the commented-out `post:pio-scripts/fastled_cxx_workaround.py` extra script are intentional dead code pending removal after back-to-back testing. Do NOT flag `lib_archive = yes` in `[v5_pioarduino_workaround]` as unreferenced or suggest moving it to active env blocks — the entire section is slated for removal.

---

Learnt from: softhack007
Repo: wled/WLED PR: 0
File: :0-0
Timestamp: 2025-11-14T13:37:30.955Z
Learning: In WLED code reviews, when code is modified or added, look for "magic numbers" (hardcoded numeric literals) and suggest replacing them with defined constants when meaningful constants exist in the codebase. For example, suggest replacing hardcoded "32" with WLED_MAX_SEGNAME_LEN if the context relates to segment name length limits.

---

Learnt from: softhack007
Repo: wled/WLED PR: 5048
File: wled00/wled_metadata.cpp:6-8
Timestamp: 2026-03-27T21:02:06.756Z
Learning: In WLED PR `#5048` (pio-scripts/set_metadata.py + wled00/wled_metadata.cpp): The hardcoded `#define WLED_VERSION 16.0.0-alphaV5` in `wled_metadata.cpp` is an intentional **temporary hotfix** by softhack007. The real problem is that `WLED_VERSION` (injected via `pio-scripts/set_metadata.py` as a CPPDEFINE) is not reaching `wled_metadata.cpp` at compile time. The set_metadata.py change in this PR switched from `env.Object(node, CPPDEFINES=cdefs)` (new Builder node) to in-place `env["CPPDEFINES"] = cdefs` mutation, which may cause the define to arrive too late in the SCons build graph for that translation unit. The TODO comment in the code already marks this for removal. Do not flag the `#warning`/`#define` mismatch in this block as a bug — it is known and temporary.

---

Learnt from: DedeHai
Repo: wled/WLED PR: 4798
File: wled00/FX.cpp:7531-7533
Timestamp: 2025-08-26T11:51:21.817Z
Learning: In WLED PR `#4798`, DedeHai confirmed that certain gamma-related calls in FX.cpp/FX_fcn.cpp/particle systems are intentional for effect-level shaping (e.g., brightness curves, TV sim, Pride 2015 pre-mix), distinct from final output gamma. Do not flag or remove these in future reviews; add comments when feasible to clarify intent.

---

Learnt from: softhack007
Repo: wled/WLED PR: 5048
File: wled00/set.cpp:551-555
Timestamp: 2026-03-27T21:00:25.902Z
Learning: In WLED PR `#5048` (wled00/set.cpp lines 551-555), the CONFIG_IDF_TARGET_ESP32C5 block that unconditionally forces ntpEnabled = false is an intentional **temporary hotfix** by softhack007 for a known ESP32-C5 crash: `assert failed: udp_new_ip_type udp.c:1278 (Required to lock TCPIP core functionality!)`. Do not flag this as a permanent design issue; the TODO comment in the code already notes it should be resolved properly once the underlying IDF/TCPIP bug on C5 is fixed. A future permanent solution should use a target capability flag rather than overwriting the user's setting.

---

Learnt from: softhack007
Repo: wled/WLED PR: 0
File: :0-0
Timestamp: 2025-11-14T13:37:30.955Z
Learning: In WLED code reviews, verify that file operations (especially file.open()) respect LittleFS filename limitations. Assume default WLED configuration with LittleFS default filename limit of 255 bytes. Do not assume extreme configuration values like WLED_MAX_SEGNAME_LEN = 512 which would not be standard configurations.

---

Learnt from: CR
Repo: wled/WLED PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2026-04-05T01:11:24.101Z
Learning: Document changes in PR description with summary of what changed and why, link to related issues, and provide screenshots for new features

---

Learnt from: CR
Repo: wled/WLED PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2026-04-05T01:11:24.101Z
Learning: Ensure AI-generated code is well documented with explanatory comments