@h2loop/safe-c-coding-plugin 0.3.1 → 0.3.3

package/agents/safe-c-reviewer.md

@@ -2,15 +2,19 @@
 mode: subagent
 displayName: Safe-C Reviewer
 description: >-
-  ALWAYS invoke this subagent once you have written, generated, or modified any C or C++
-  code (.c, .h, .cpp, .hpp), or whenever you want to review existing C/C++ code — do not
-  skip this for one-line changes or code that looks routine. Reviews the code against the
-  safe-c-coding (MISRA C:2012-aligned) guidelines. Given a file, diff, or code range, it
-  scans for undefined behaviour, dynamic allocation, unchecked returns, implicit
-  conversions, missing switch defaults, recursion, and other hazardous constructs, and
-  reports each as "severity — file:line — what's wrong -> safe fix". Use it to audit
-  hand-written or generated C/C++ before it lands, especially for embedded / safety-critical
-  targets.
+  Invoke this subagent for C or C++ code (.c, .h, .cpp, .hpp) only — never for other
+  languages. Frequency depends on task size: for a single small edit (one step, a handful
+  of lines), a self-audit against the safe-c-coding skill's checklist is normally enough
+  and this subagent is optional extra assurance. For a multi-step task with several
+  planned edits and/or files, invoking this subagent is mandatory — but exactly ONCE, as
+  the final step after every planned edit is done, covering the whole changed set. Do not
+  invoke it after each individual step — that is the aggressive, slow pattern to avoid.
+  Reviews the code against the safe-c-coding (MISRA C:2012-aligned) guidelines. Given a
+  file, diff, or code range, it scans for undefined behaviour, dynamic allocation,
+  unchecked returns, implicit conversions, missing switch defaults, recursion, and other
+  hazardous constructs, and reports each as "severity — file:line — what's wrong -> safe
+  fix". Use it to audit hand-written or generated C/C++ before it lands, especially for
+  embedded / safety-critical targets.
 permission:
   # deny-all FIRST, then allow specifics: PermissionNext resolves with findLast
   # (last matching rule wins), so "*": deny MUST precede the allows or it overrides them.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@h2loop/safe-c-coding-plugin",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Safe-C coding plugin for Hydron — MISRA C:2012-aligned defensive C/C++ guidelines as an always-on skill plus a safe-c-reviewer subagent",
   "type": "module",
   "license": "UNLICENSED",

package/plugins/index.ts

@@ -3,10 +3,13 @@ import type { Plugin } from "@kilocode/plugin"
 export const SafeCCodingPlugin: Plugin = async () => ({
   "experimental.chat.system.transform": async (_input, output) => {
     output.system.push(
-      "Before writing, generating, modifying, or reviewing any C or C++ code " +
-        "(.c, .h, .cpp, .hpp), invoke the safe-c-coding skill. After writing or " +
-        "modifying C/C++ code, invoke the safe-c-reviewer subagent. Do this even " +
-        "for a one-line change or code that looks routine.",
+      "Before writing, generating, modifying, or reviewing C or C++ code only " +
+        "(.c, .h, .cpp, .hpp — not other languages), invoke the safe-c-coding skill " +
+        "and follow it so the code is MISRA-aligned on the first pass. For a single " +
+        "small edit, that first pass plus your own re-read is enough — do not also " +
+        "call the safe-c-reviewer subagent. For a multi-step C/C++ task, do not review " +
+        "after each step; add exactly one safe-c-reviewer call as the final step, " +
+        "after all planned edits are done, covering everything changed.",
     )
   },
 })

package/skills/safe-c-coding/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: safe-c-coding
-description: ALWAYS invoke this skill before writing, generating, modifying, or reviewing any C or C++ code (.c, .h, .cpp, .hpp) — no exception for one-line changes, snippets, or code that looks routine. Applies especially to embedded, automotive, medical, aerospace, or other safety-critical or resource-constrained targets where reliability, determinism, and freedom from undefined behaviour matter, but the mandatory-invocation rule applies to all C/C++ work.
+description: Invoke this skill ONLY when authoring or reviewing C or C++ source — that is, when you are about to write, generate, or modify the contents of a .c/.h/.cpp/.hpp file, or when explicitly asked to review such source for defects. In those cases invocation is mandatory, with no exception for one-line changes, snippets, or code that looks routine. Do NOT invoke it for activities that merely involve an existing C/C++ project but do not change or review its source: flashing or programming a device, running or launching a binary, debugging a running program (setting breakpoints, inspecting variables, reading a stack trace, diagnosing a crash), building/compiling/linking, running tests, reading or explaining code without editing it, configuring toolchains, or working with logs, build output, or hardware. Reading a C/C++ file for context during such an activity is not authoring and does not trigger the skill. Scope is per file, not per project or per task — do not invoke it for code in other languages (Python, JS/TS, Rust, Go, shell, build/config, etc.), even inside a project that also contains C/C++. It applies especially to embedded, automotive, medical, aerospace, or other safety-critical or resource-constrained targets, but the trigger is always the act of writing or reviewing C/C++ source, never merely being near it.
 ---
 
 # Safe C Coding
@@ -11,6 +11,21 @@ A set of defensive coding guidelines for writing C (and C-style C++) that is rel
 
 **Core principle:** write the safe form by default. Avoid the language's hazardous corners (dynamic memory, undefined behaviour, implicit conversions, unbounded operations) instead of relying on review to catch them later.
 
+## When this skill applies
+
+The trigger is the **act of authoring or reviewing C/C++ source**, not the presence of a C/C++ project. Invoke it when you are about to write, generate, or modify the contents of a `.c/.h/.cpp/.hpp` file, or when explicitly asked to review such source for defects.
+
+Do **not** invoke it for activities that touch a C/C++ project without changing or reviewing its source:
+
+- Flashing, programming, or provisioning a device.
+- Running, launching, or deploying a binary.
+- Debugging a running program — breakpoints, inspecting variables, reading a stack trace, diagnosing a crash.
+- Building, compiling, or linking; running tests.
+- Reading or explaining existing code without editing it.
+- Configuring toolchains, or working with logs, build output, or hardware.
+
+Reading a C/C++ file for context during any of the above is not authoring and does not trigger the skill. If, during such an activity, you decide to *edit* source to fix something, the skill applies from that point.
+
 > **Apply this as you write.** Whenever you write, generate, or modify C or C++ — even a one-line snippet or a quick example — follow these MISRA C:2012-aligned guidelines proactively, without waiting to be asked to review. Produce compliant code the first time; do not emit a hazardous construct now and plan to fix it later. If a guideline genuinely cannot be met, flag it and justify the deviation rather than silently violating it.
 
 ## Non-negotiables
@@ -41,7 +56,7 @@ The full guideline catalogue is in **[guidelines.md](guidelines.md)**.
 
 1. Read guidelines.md in full — before drafting any code, not after.
 2. Choose the safe pattern from the start: static allocation over `malloc`, braced bodies, explicit types, checked return values, a `default` in every `switch`, no recursion, guarded array/pointer access.
-3. Run the **self-audit** below on the code you just wrote, before you save or present it. This step is not optional and not a formality — it is where most violations are actually caught.
+3. Run the **self-audit** below, sized to the task — see that section for which mode applies. This step is not optional and not a formality, but it is not a per-step gate either: a multi-step task gets one audit at the end, not one after every edit.
 4. If a hazardous construct is genuinely unavoidable, don't hide it — call it out and explain why, with a documented justification.
 5. If the project has a MISRA compliance checker (e.g. Cppcheck, Parasoft C/C++test, Helix QAC) and you don't already know how to invoke it for this project, ask the developer for the exact command to run it — then run it against the code you wrote and fix what it reports.
 
@@ -53,16 +68,16 @@ The code already in the file, the neighbouring functions, and the project's hous
 - Do **not** inherit its *hazardous constructs*. "The function next to mine does it this way" is not a justification, and a static-analysis tool will not accept it — each construct is judged on its own.
 - You will often be told not to modify existing code. That constrains what you may change; it does not license writing new non-compliant code that imitates it. Write the compliant form in the code you own, and note the divergence in one line if it looks inconsistent.
 
-### Self-audit (run on your own diff, before saving)
+### Self-audit — one pass, sized to the task
 
-Do this as a **separate pass with fresh eyes**, not as a mental note while writing — the audit only catches anything if it actually re-reads the code. Two acceptable forms, in order of preference:
+Do this as a **separate pass with fresh eyes**, not as a mental note while writing — the audit only catches anything if it actually re-reads the code. Pick the mode by the shape of the task, not by habit: auditing after every single step of a multi-step task is the slow, aggressive pattern this section replaces.
 
-- Delegate the code you just wrote to the **safe-c-reviewer** subagent (bundled with this skill) and fix every Critical and Standard finding it reports.
-- If no subagent is available, re-read the edited region with the read tool — reading it back is part of the step — and work through the checklist below line by line.
+- **Single small change** (one edit step, a handful of lines, one function): no subagent call. Re-read the edited region with the read tool — reading it back is part of the step — and work through the checklist below line by line yourself, before you save.
+- **Multi-step task** (several planned edits and/or files touching C/C++): don't audit after each step. Write every step compliant the first time using the guidelines above, then add exactly **one** extra step at the end of the task, after all planned edits are done, that delegates the full set of changed C/C++ files or diff to the **safe-c-reviewer** subagent and fixes every Critical and Standard finding it reports. That final review is the task's last step, not a gate between steps — do not call the subagent again until the whole task's edits are complete.
 
-Either way the pass is required before you save the file or report the work as done. A summary that says the code is compliant without a re-read behind it is not an audit.
+Either way the pass is required once before you save the file(s) or report the work as done — never zero times, and never once per edit. A summary that says the code is compliant without a re-read or reviewer pass behind it is not an audit.
 
-Walk the lines you wrote — not the whole file — and answer each question explicitly, by re-reading the code rather than from memory of what you intended.
+Walk the lines that changed since the task started (or, if delegating, since the last review) — not the whole file — and answer each question explicitly, by re-reading the code rather than from memory of what you intended.
 
 1. **Every array subscript and pointer dereference**: list them. For each, name the enclosing `if` or loop condition that proves the index is in range and the pointer is non-NULL *on that path*. If the only thing between the access and undefined behaviour is an assertion macro, a comment, a caller's promise, or a convention copied from nearby code, then it is unguarded — add a real guard.
 2. **Every name you did not define in this file**: list the macros, struct/union members, types, enum constants, globals, and functions your new code references. For each, name the header or context file whose declaration you actually read. Any name you produced from memory, from the shape of a sibling name, or because it seemed like it ought to exist is unverified — go and find its declaration, and correct the spelling to match. This is a five-second check that prevents code that cannot compile.
@@ -72,7 +87,7 @@ Walk the lines you wrote — not the whole file — and answer each question exp
 6. **Every branch construct**: braced bodies, a `default` in every `switch`, a terminating `else` where the chain must be exhaustive.
 7. **Anything on the banned-facility list** (dynamic memory, recursion, VLAs, `exit`/`abort`/`longjmp`, unbounded string functions): replaced by its substitute, or deviated from with a written justification.
 
-State the result of the audit before you finish: for every Critical or Standard finding raised — by the reviewer subagent or by your own re-read — name the finding and the specific edit that resolved it. "Audit passed" or "no issues found" with no re-read behind it is not an audit; a finding with no matching fix next to it is not an audit either.
+State the result of the audit before you finish the task: for every Critical or Standard finding raised — by the reviewer subagent or by your own re-read — name the finding and the specific edit that resolved it. "Audit passed" or "no issues found" with no re-read behind it is not an audit; a finding with no matching fix next to it is not an audit either.
 
 ## Preferred patterns