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 covering C++ and Web UI conventions, build & test workflows (including agent-mode build/test guidance), CI/CD/workflow standards, PR expectations, troubleshooting, and recovery steps.
• Chores
  • Added a repository-level review/config that scopes guidance by area, protects generated outputs from manual edits/commits, and includes alignment/drift checks between AI-facing rules and human-only reference guidance.

[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: 7e14196e-78d5-4205-8f55-a6bfe450dd0e

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

Added a repository-level CodeRabbit configuration plus six new or updated documentation files covering path-scoped review instructions, C++ and Web UI coding standards, CI/CD workflow conventions, an agent-mode build/test runbook, and updated Copilot guidance referencing the new docs.

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 for .github/*.instructions.md.
Agent build & test runbook \.github/agent-build.instructions.md	New agent-mode build/test instructions: required build order (web UI before firmware), minimum timeouts for npm/PlatformIO, required validation steps (npm test, pio run -e esp32dev), manual testing, troubleshooting, and CI validation notes.
CI/CD guidance \.github/cicd.instructions.md	New GitHub Actions conventions: YAML style, required name: fields, trigger and job-wiring guidance (needs/outputs), runner/tool pinning, caching, artifact rules, 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 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, roles of key files, reuse of common.js, build integration via tools/cdata.js, npm run build workflow, and rule to avoid editing generated wled00/html_*.h/js_*.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, add usermod guidelines, expanded project overview, and links to the new instruction files; removed the prior “Working Effectively” structure.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested reviewers

• Aircoookie
• netmindz
• willmmiles
• DedeHai

🚥 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 accurately summarizes the main changes: restructuring copilot-instructions and introducing a new C++ coding guide for AI code reviews, which are the primary objectives of the PR.
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.}