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.

• 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 contributor docs: C++ and Web UI coding/build conventions, CI/CD/workflow standards, agent-mode build & test procedures, contributor setup, PR expectations, troubleshooting, and recovery steps.
• Chores
  • Added a repository-level review/configuration that scopes review guidance per area and includes alignment checks comparing AI-facing rules to human-only reference guidance.

[coderabbitai]

Important

Review skipped

This PR was authored by the user configured for CodeRabbit reviews. CodeRabbit does not review PRs authored by this user. It's recommended to use a dedicated user account to post CodeRabbit review feedback.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 2e5625d9-cae1-4af9-ac71-d402c232e33b

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

Walkthrough

Added a repository-level CodeRabbit configuration and five new or updated documentation files providing path-scoped review instructions, C++ and Web UI coding standards, CI/CD workflow conventions, and agent-mode build/test procedures; Copilot instructions were revised to reference these new guides.

Changes

Cohort / File(s)	Summary
CodeRabbit config \.coderabbit\.yaml	New repo-level CodeRabbit config with path-scoped reviews.path_instructions for C/C++ sources, web UI assets, generated headers, usermods, GitHub workflows, and drift-detection rules targeting .github/*.instructions.md.
Agent build & test \.github/agent-build.instructions.md	New agent-mode build/test runbook: mandated build order, minimum timeouts for npm/PlatformIO, required firmware build/test steps, manual web UI testing, troubleshooting, recovery steps, and CI validation checklist.
CI/CD guidance \.github/cicd.instructions.md	New GitHub Actions conventions: YAML style, name: fields, trigger guidance, job wiring (needs/outputs), runner/tool/version pinning, caching, artifact naming, least-privilege permissions, action pinning, secret handling, and safe run: usage.
C++ conventions \.github/cpp.instructions.md	New C/C++/Arduino coding standards for **/*.{cpp,h,hpp,ino}: formatting, naming, header guards, AI-generated code markers, prohibition of C++ exceptions, PSRAM-aware allocation, hot-path optimization patterns, synchronization and UB guidance.
Web UI conventions \.github/web.instructions.md	New Web UI style/build guidance for wled00/data/**: tab indentation, JS/HTML/CSS conventions, file role descriptions, build integration via tools/cdata.js, npm run build workflow, and rule to not edit generated wled00/html_*.h.
Copilot instructions (updated) \.github/copilot-instructions.md	Reworked setup/build flow: require npm ci; npm run build before PlatformIO, mandate pio run -e esp32dev firmware build, add usermod guidelines, project overview, and links to the new instruction files.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested reviewers

• Aircoookie
• willmmiles
• netmindz
• lost-hope

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly relates to the main changes: reworking copilot-instructions and adding a new C++ coding guide for AI reviews, which are core objectives.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

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

---

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