@cryptotaxi247 / netdata-1
Code Commits Issues Pulls Sessions CI/CD
master
master
md 908 lines 52.3 KB
Rendered Raw
1 # AGENTS.md
2
3 ## Goals
4
5 This repository is the Netdata Agent codebase. It is a large, multi-language, multi-platform monolith that serves production monitoring, troubleshooting, data collection, alerting, storage, streaming, cloud integration, packaging, and documentation workflows.
6
7 Work in this repository must prioritize root-cause understanding, correctness, performance, maintainability, portability, security, and consistency with existing project conventions.
8
9 ## Requirement Language
10
11 This repository uses RFC-style requirement language:
12
13 - **MUST** / **REQUIRED**: mandatory. Work that violates it is not acceptable
14 unless the user explicitly changes the requirement.
15 - **MUST NOT**: prohibited.
16 - **SHOULD** / **RECOMMENDED**: expected default. Deviate only with evidence
17 and explain the trade-off.
18 - **MAY** / **OPTIONAL**: allowed, not required.
19
20 CRITICAL RULES:
21
22 1. You MUST ALWAYS find the root cause of a problem, before offering/giving a solution.
23 Patching without understanding the problem IS NOT ALLOWED.
24
25 2. Before patching code, you MUST understand the codebase and the potential implications of the changes.
26 What else is affected? What else is using this part of the code?
27
28 3. Do not duplicate code.
29 First check if similar code already exists and reuse it.
30
31 ## Mandatory Development Principles
32
33 These principles are mandatory for every task. Code is cheap to add and
34 expensive to live with, so a larger diff that removes debt beats a smaller one
35 that preserves it.
36
37 **Core (read first; the bullets under each principle are the authority for forks
38 and edge cases):**
39
40 - Deliver the **clean end state** of the approved scope, not the smallest diff —
41 including removing what the change makes redundant; refactor low-risk mess in
42 code you touch.
43 - **Record that target in the SOW first** (what you remove; any coupled item you
44 exclude, with its reason). When you replace a path or contract, record a
45 reference search proving the list is complete.
46 - **You are not the scope authority.** Coupled cleanup is in scope: do the
47 low-risk part and disclose it; never silently drop it or relabel it
48 "independent."
49 - Falling short of the recorded target — or any user-owned **fork** (competing
50 designs, a public-contract or destructive change, unclear scope) — triggers a
51 **Mandatory pause**: stop, state the trade-off, get explicit approval.
52 - **Plan before non-trivial work:** establish the user-approved end state plus
53 acceptance criteria, then ordered steps; re-evaluate against the target at each
54 step, before any PR, and before completion.
55 - **Default on doubt:** if unsure whether something is in scope, trivial, or a
56 user-owned fork, treat it as in-scope / non-trivial / user-owned and ask.
57
58 1. **Clean end state over less churn.**
59 - Binding rule (read first): you MUST recommend and deliver the clean end
60 state — the structure the codebase SHOULD have once the approved scope is
61 fully delivered, including removing the code, config, docs, and tests the
62 change makes redundant — not the smallest diff. You MUST NOT relabel the
63 smallest working diff as "the clean end state."
64 - Record the target: before generating options, record that clean end state in
65 the SOW. The recorded target is the clean end state of this SOW's approved
66 scope; for staged work, each stage's SOW records that stage's target and the
67 stages together MUST reach the full target. Any option that does not match
68 the recorded target is a non-clean state and triggers the Mandatory pause.
69 - Open design decision: when the clean end state is itself an open design
70 decision that is the user's to make, do not invent a fixed target; record a
71 provisional target plus the open design question and resolve it with the
72 user first.
73 - Approved scope: "the approved scope" is the union of (a) the issue or user
74 request, (b) the SOW Purpose and Acceptance Criteria, and (c) the
75 migration/contract surface they imply. If it is unclear whether work is in
76 scope, treat it as in-scope and raise it with the user; never silently
77 exclude it.
78 - You are not the scope authority:
79 - A "coupled item" is code, config, docs, or tests the current change makes
80 redundant or leaves inconsistent (for example a replaced path, its
81 callers, or its tests).
82 - You MUST NOT reclassify in-scope or coupled work as "independent" or "out
83 of scope" to avoid doing it, and you MUST NOT silently drop coupled work.
84 - When you only suspect something is coupled and including it is low-risk and
85 confined to what you are changing, include it and disclose it rather than
86 stopping to ask.
87 - Pause for the user only when including it would expand the blast radius,
88 change a user-visible contract, or the boundary is itself a genuine scope
89 fork.
90 - This overrides any reading of "Scope discipline" that would defer coupled
91 cleanup.
92 - Disclose exclusions: in the recorded target you MUST list (i) what you will
93 remove as redundant, and (ii) any coupled item you are treating as NOT part
94 of this clean end state, each with its reason and the scope source it rests
95 on. Excluding an in-scope or coupled item without recording it there is
96 silent scope-narrowing and is prohibited, so a reviewer or the next agent can
97 check your exclusions against those sources.
98 - Touch-the-mess-you-touch: when your change modifies code that already
99 contains adjacent duplication, dead code, or a clear pre-existing defect, you
100 SHOULD clean that adjacent mess as part of this work rather than build on top
101 of it, provided the cleanup is low-risk and confined to the code you are
102 already modifying. Cleanup that would reach into unrelated code is
103 independent work (Scope discipline) — track it, do not silently bundle it. If you
104 choose NOT to clean adjacent mess you touched, record why under the
105 disclosure list (ii).
106 - Reference search (when replacing a path or altering a contract):
107 - You MUST run and record in the SOW a reference search for remaining
108 references to the replaced path or contract.
109 - Search construction sites and prefixes too, not only literal final names —
110 identifiers here are often built dynamically (for example via
111 `fmt.Sprintf`).
112 - Every surviving reference MUST appear in (i) or (ii) with its scope source,
113 or the target is incomplete; an item you did not search for counts as
114 silent scope-narrowing.
115 - A repository-wide search cannot prove safety for consumers outside this
116 repo (Netdata Cloud, exporters, streaming, ML, the docs pipeline); treat
117 renaming a shipped public contract as a user-owned breaking decision (an
118 Allowed-exceptions pause), not something the search clears.
119 - Allowed exceptions (pause conditions, not auto-routes): recommend a
120 non-clean route ONLY for one of:
121 - (a) technically impossible — impossible to implement correctly at all, NOT
122 impossible within a preferred diff size;
123 - (b) a concrete, evidenced safety risk — a named hazard such as data loss
124 or a security/production-stability regression, NOT "a larger diff is
125 riskier";
126 - (c) confirmed by the user as outside the approved scope; or
127 - (d) accepted by the user, through the Mandatory pause, as an in-scope
128 partial to ship now.
129
130 For (a)/(b) you MUST cite specific evidence (file/line, failure class, or
131 test) and route through the Mandatory pause — you do not self-certify
132 "unsafe." For (d) track the remainder per "Followup Discipline" with why
133 deferral is acceptable and when it lands; repeatedly shipping partials is
134 debt accumulation, not delivery. Risk reduction, review convenience, smaller
135 diff, and issue staging are NEVER valid and MUST NOT be relabeled "unsafe"
136 or "independent."
137 - Mandatory pause: if the delivered state will fall short of its recorded
138 target for any reason other than approved staged delivery, you MUST present
139 the evidence, STOP, and obtain explicit user approval (see Approval bar)
140 before proceeding, before requesting non-draft review, and before marking
141 the work complete.
142 - Approval bar (used by every gate): approval means the user explicitly
143 accepts a trade-off, goal, or plan that you stated in your own words (what
144 stays redundant or partial, and why). A bare "ok" or "sounds good" to a
145 one-sided pitch is not approval.
146 - Re-evaluation: at the completion of each planned step, before opening or
147 updating a PR, and before marking a SOW completed (the Re-evaluation
148 checkpoints), you MUST re-evaluate already-written changes against the
149 recorded target; you SHOULD also re-evaluate whenever you pause to report
150 progress. Do not keep a compromise only because it already exists in the
151 branch.
152 - Staged delivery: allowed ONLY when every stage is an in-scope decomposition
153 of one approved clean end state and the stages together reach it. The user
154 approval recorded for the staged plan covers the intermediate states, so an
155 approved stage does not re-trigger the Mandatory pause; every later stage
156 MUST be tracked per "Followup Discipline" (implemented here, rejected with
157 evidence, or a linked GitHub issue) before an earlier stage merges. A
158 self-certified "a later stage will finish it" with no tracked item is not
159 acceptable.
160 - Deferral check: before recommending deferral, check the issue, SOW,
161 acceptance criteria, and affected migration scope. Silence or ambiguity MUST
162 NOT be read as permission to defer; if those sources do not clearly place
163 the work outside the approved clean end state, treat it as in-scope and
164 either complete it or pause for a user decision.
165 - Trivial-work exemption: trivial work (per "When A SOW Is Required") has no
166 SOW and is exempt from the record-the-target, disclosure, and
167 reference-search bullets above; the clean-end-state preference still applies.
168 When unsure, treat the work as non-trivial.
169
170 2. **Plan before non-trivial work.**
171 - Plan first: non-trivial work (see "When A SOW Is Required") MUST start with
172 a plan recorded in the SOW before any implementation-file change and before
173 any implementation-equivalent action — migrations, deletions, pushes,
174 non-draft PRs, or external-state mutations via tools. Trivial work is exempt;
175 when unsure, treat the work as non-trivial.
176 - Human-owned goal: the desired end state — the goal, or coherent goal set, the
177 work must reach — MUST be created with or approved by the user. You MUST NOT
178 finalize the goal unilaterally (same user-owned target as Clean end state).
179 - End state first: you MUST establish the desired end state — including its
180 acceptance criteria — before planning the steps; the goal drives the work,
181 not a first diff. If you cannot yet state the end state, keep investigating
182 until you can; do not start work against an unknown target. When the end
183 state is itself a user-owned design decision, record a provisional target
184 plus the open question and resolve it with the user first (Clean end state).
185 Then plan the steps to move from the current state toward that end state.
186 - Decompose into steps: split the work into ordered steps, each with its own
187 clean end state and acceptance criteria, each building on the previous one
188 toward the desired end state. A single coherent step is a valid decomposition
189 when the work is atomic; do not invent artificial sub-steps.
190 - Resolve huge or vague work: if the deliverable is large or vague, keep
191 refining the plan until every step has a clean end state and acceptance
192 criteria. Do not start implementation while steps are still unclear.
193 - Reachability: the plan MUST either reach the desired end state through its
194 steps, or produce evidence that it is not achievable; an unachievable goal
195 is a pause condition for a user decision, not a silent partial result.
196 - Human approval gate: when a goal-approval round is required (see "Approval is
197 for goal-decisions" below), the whole plan — the desired end state and the
198 step breakdown — MUST be explicitly approved by the user before
199 implementation. The assistant proposes and investigates; the user approves.
200 State the goal and step breakdown being accepted, and get confirmation that
201 meets the Approval bar (Clean end state). If the user rejects or edits the
202 plan, revise and re-seek approval; the SOW stays in `planning` until an
203 explicit approval is recorded, then reaches `Status: ready`. This gate is the
204 canonical statement of the approval requirement that the Pre-Implementation
205 Gate and Required First Checks reference.
206 - Approval is for goal-decisions, not work categories:
207 - The goal-approval round fires ONLY when the end state is a genuine
208 user-owned fork — competing designs, a public-contract change, a
209 destructive or irreversible step, or unclear scope.
210 - Other non-trivial work whose end state is already fixed by the triggering
211 request, an existing project skill, or an established repository pattern
212 (for example a clear bug fix, a metadata/docs edit with no contract change,
213 or a collector's skeleton and wiring fixed by its authoring skill — though
214 its Function surface, vnode/host-scope design, and new public config
215 options remain user-owned forks) still needs a recorded plan and the
216 Pre-Implementation Gate, but the triggering request IS the recorded goal
217 approval — no separate round, which also satisfies the resume re-check and
218 the progress rule.
219 - When it is unclear whether a real fork exists, treat it as user-owned and
220 seek approval.
221 - Approval persists; re-check on resume: before continuing an `in-progress` or
222 `paused` SOW you did not personally take through this gate — including
223 takeover or handoff — you MUST confirm the SOW records explicit approval of
224 the current goal and plan. If it does not, or the plan changed materially
225 since approval, treat the SOW as `planning` and re-obtain approval before
226 further implementation.
227
228 3. **Scope discipline at every step.**
229 - Drift check: at each Re-evaluation checkpoint (Clean end state), you MUST
230 also check whether the work has drifted outside the approved scope, not only
231 whether the diff still matches the recorded target.
232 - Independence test: new work is "genuinely independent" only if ALL hold —
233 (a) the approved clean end state is still complete and correct without it,
234 (b) it is not a coupled item or a remaining reference recorded under Clean
235 end state, and (c) it has its own separable acceptance criteria. If any test
236 fails, or you are unsure, treat the work as coupled, not independent, and
237 handle it under Clean end state (do the low-risk part and disclose it; pause
238 only for a genuine fork) — you are not the scope authority.
239 - Disposition of independent work:
240 - Do NOT silently bundle it.
241 - Submit it as a separate PR first and rebase the current branch after it
242 merges, or track it as a GitHub issue per "Followup Discipline."
243 - Do NOT fold it into this SOW's steps — Clean-end-state staged-delivery
244 stages must be a decomposition of one clean end state.
245 - Governed elsewhere: coupled cleanup is in scope (Clean end state), and
246 non-trivial work is delivered in coherent incremental steps (Plan before
247 non-trivial work); this principle does not restate them.
248
249 **Flow diagrams (human reading aid, non-normative):** the bullets above are
250 authoritative; the diagrams below summarize the flow for human readers and MUST
251 be kept in sync when the principles change.
252
253 <details>
254 <summary>Show per-principle flow diagrams</summary>
255
256 How the three principles connect (lifecycle order):
257
258 ```mermaid
259 flowchart LR
260 A("1. Clean end state<br/>defines the target (what 'done' means)")
261 B("2. Plan before non-trivial work<br/>establish the target + steps; user approves real forks")
262 C("3. Scope discipline<br/>stay on the target while executing each step")
263 A --> B --> C
264 C -->|re-evaluate vs target| A
265 ```
266
267 1. Clean end state over less churn:
268
269 ```mermaid
270 flowchart TD
271 A("Approved scope = issue + SOW Purpose/Acceptance + implied surface")
272 B("Define the clean end state, incl. removing what the change makes redundant")
273 C("Record target in SOW: exclusions list + reference search if a path/contract is replaced")
274 D{"Matches recorded target?"}
275 E("Deliver the clean end state")
276 F{"Allowed exception?"}
277 Fx("Only: a) impossible, b) evidenced safety risk, c) out of scope, d) user-accepted partial")
278 G("NOT allowed: risk reduction, smaller diff, or staging")
279 H("Mandatory pause: present evidence, STOP")
280 I{"Explicit approval?"}
281 Ix("Approval bar: a bare 'ok' is not approval")
282 J("Proceed; track remainder per Followup Discipline")
283 K("Re-evaluate vs target: each step, before a PR, before complete")
284 A --> B --> C --> D
285 D -->|yes| E
286 D -->|no| F
287 F -->|no| G --> B
288 F -->|yes| H --> I
289 I -->|no| B
290 I -->|yes| J
291 F -.- Fx
292 I -.- Ix
293 E --> K
294 J --> K
295 ```
296
297 2. Plan before non-trivial work:
298
299 ```mermaid
300 flowchart TD
301 A("Task")
302 B{"Trivial?"}
303 C("Exempt: just do it (clean-end-state preference still applies)")
304 D("Establish the desired end state + acceptance criteria FIRST; keep investigating until you can")
305 E("Decompose into ordered steps, each with its own clean end state + criteria; move current toward desired")
306 F{"End state a user-owned fork?"}
307 Fk("Fork = competing designs, public-contract/destructive change, or unclear scope")
308 G("Fixed by request/skill/pattern: the request IS the approval (recorded plan + gate, no separate round)")
309 H("Goal-approval round: explicit user approval of the whole plan (Approval bar)")
310 I("Status: ready, implement")
311 J("Pause for a user decision (not a silent partial)")
312 A --> B
313 B -->|yes| C
314 B -->|no| D
315 D --> E --> F
316 F -->|no| G
317 F -->|yes| H
318 F -.- Fk
319 G --> I
320 H --> I
321 D -->|goal unreachable| J
322 ```
323
324 3. Scope discipline at every step:
325
326 ```mermaid
327 flowchart TD
328 A("At each Re-evaluation checkpoint")
329 B{"Drifted outside approved scope?"}
330 C("Continue")
331 D{"Genuinely independent?"}
332 Dx("Independent only if ALL: end state complete without it; not a coupled item/reference; separable acceptance criteria")
333 E("Treat as COUPLED: handle under Clean end state (do the low-risk part + disclose); pause only for a genuine fork")
334 F("Do NOT bundle silently: separate PR + rebase, or track as a GitHub issue; never fold into this SOW's steps")
335 A --> B
336 B -->|no| C
337 B -->|new work| D
338 D -->|no or unsure| E
339 D -->|yes| F
340 D -.- Dx
341 ```
342
343 </details>
344
345 USER COMMUNICATION:
346
347 1. ALWAYS DO YOUR HOMEWORK BEFORE ASKING QUESTIONS OR REQUESTING USER DECISIONS.
348 PROACTIVELY CHECK ALL RELATED ASPECTS AND ALL POSSIBILITIES SO THAT YOUR QUESTIONS AND REQUESTS ARE WELL INFORMED AND TO THE POINT.
349
350 2. NEVER WRITE WALLS OF TEXT TO THE USER, UNLESS THEY ASKED FOR IT.
351 YOUR COMMUNICATION MUST BE SIMPLE, DIRECT, LEAN, ORDERED BY IMPORTANCE.
352 PROVIDE THE FULL PICTURE AT THE BEGINNING, START FROM THE HIGH LEVEL, AND LET THE USER ASK FOR DETAILS.
353
354 3. NEVER AGREE TO THE USER WHEN THE FACTS CONTRADICT THEIR UNDERSTANDING.
355 YOU MUST ALWAYS PROVIDE CLEAR DESCRIPTIONS OF THE RISKS AND IMPLICATIONS OF THEIR DECISIONS.
356 YOU ARE HELPFUL WHEN YOU ACCURATELY REVEAL THE TRUTH, NOT WHEN YOU AGREE.
357
358 ## SOW System
359
360 Project SOW status: initialized
361
362 This project uses a local Statement of Work system.
363
364 SOWs are branch-local working memory, not product artifacts. During active work,
365 including draft PR and ready-for-review takeover work, a SOW may live on the
366 feature branch so it preserves the root-cause model, decisions, evidence, and
367 validation for PR takeover. Commit the active SOW on the feature branch when
368 takeover or handoff is expected. When no takeover is expected, keeping the
369 active SOW local and uncommitted is acceptable, but the SOW still MUST be used
370 as working memory. Before merge, complete the SOW, transfer durable knowledge,
371 and delete the active SOW file. `master` and the final merge head MUST contain
372 no SOW working files; durable memory belongs in `.agents/sow/specs/`, project
373 skills, docs, code, and tests.
374
375 The SOW system is self-contained in this repository. Normal SOW work must not depend on `~/.agents`, `~/.AGENTS.md`, global skills, global templates, or global scripts. Use this `AGENTS.md`, the branch-local SOW, project-local specs, and project-local skills.
376
377 ### Roles
378
379 - **User responsibilities:** purpose, scope decisions, design forks, risk acceptance, destructive approvals, and final product judgment.
380 - **Assistant responsibilities:** investigation, evidence, implementation, tests or equivalent validation, reviews, documentation, memory updates, and concise reporting.
381
382 ### Required First Checks
383
384 Before non-trivial work:
385
386 1. Read the current branch's SOW under `.agents/sow/active/` if one exists. Since SOWs are branch-local, discover other in-flight work through open PRs and issues, not through `master`.
387 2. Read relevant specs under `.agents/sow/specs/`.
388 3. Inspect `.agents/skills/*/SKILL.md` if any exist, and load every runtime project skill whose trigger matches the work.
389 4. Inspect legacy runtime skills listed below when the user request matches their frontmatter trigger.
390 5. Inspect code, docs, tests, and existing project instructions as ground truth.
391 6. Ask the user only for irreducible product/design/risk decisions. For non-trivial work, the goal and plan are user-owned decisions gated by the "Plan before non-trivial work" Human approval gate.
392
393 ### Git Worktrees
394
395 Assistants must not create git worktrees on their own. Create a git worktree only when the user explicitly asks for it or approves it.
396
397 ### Sensitive Data In Durable Artifacts
398
399 SOWs, specs, documentation, project skills, agent instructions, and code comments are commit-ready artifacts. Treat them as public unless a repository-specific policy explicitly says otherwise.
400
401 CRITICAL: Never write raw sensitive data to durable artifacts. This includes passwords, API keys, bearer tokens, SNMP communities, private keys, connection strings with embedded credentials, session cookies, community member names, customer names, customer identifiers, personal data, non-private IP addresses that can identify customers, private endpoints, account IDs, and proprietary incident details.
402
403 Write only sanitized evidence:
404
405 - use placeholders such as `[REDACTED_SECRET]`, `[CUSTOMER]`, `[ACCOUNT]`, `[PRIVATE_ENDPOINT]`;
406 - use stable aliases such as `customer-a` only when the real mapping is not stored in the repository;
407 - cite file paths, line numbers, command names, schema fields, or error classes instead of copying sensitive values;
408 - summarize logs and traces; include only minimal redacted snippets.
409
410 If sensitive data is required to continue, stop and ask the user for a secure handling path. If sensitive data is found in a durable artifact, sanitize it before any commit. If sensitive data was already committed, tell the user and do not rewrite history without explicit approval.
411
412 ### Durable AI-Facing Artifact Formatting
413
414 AI-facing durable artifacts include `AGENTS.md`, SOW specs, runtime project
415 skills, public/operator skills, SOW templates, instruction bridge files, and
416 other docs primarily written so future AI agents can execute repository rules
417 correctly.
418
419 When writing or updating these artifacts:
420
421 - Structure for retrieval and scanning. Use headings, short sections, labeled
422 bullets, and numbered procedures so both humans and AI agents can find the
423 exact rule quickly.
424 - Avoid dense multi-rule paragraphs. If a paragraph contains multiple
425 requirements, exceptions, or decision branches, split it into bullets or a
426 table.
427 - Use tables only for matrices or comparisons where the cells stay short. Use
428 bullets for rules, workflows, checklists, and exception handling.
429 - Put RFC-style requirement words (`MUST`, `MUST NOT`, `SHOULD`, `MAY`) close
430 to the action they govern. Do not hide mandatory behavior in explanatory
431 prose.
432 - Prefer labeled bullets for operational guardrails, such as `Target`,
433 `Exception handling`, `Validation`, or `Failure mode`.
434 - Keep one durable idea per bullet. If a bullet needs multiple sentences, the
435 first sentence states the rule and later sentences provide evidence,
436 rationale, or examples.
437 - For a guardrail with several distinct requirements, use a labeled parent
438 bullet with an indented sub-list — one requirement per sub-bullet — rather than
439 a multi-requirement paragraph; keep a single rule-plus-rationale as one bullet.
440 - Preserve precision over brevity. Formatting is for readability, not for
441 weakening contracts or removing necessary evidence.
442
443 ### Open-Source Reference Evidence
444
445 When SOW evidence comes from other open-source repositories, cite the upstream repository and checked commit instead of the workstation absolute path.
446
447 Use:
448
449 ```text
450 owner/repo @ commit
451 relative/path/inside/repo:line
452 ```
453
454 Resolve `owner/repo` from the repository remote, record the checked commit, and keep paths relative to the upstream repository root. Never write absolute paths into SOW evidence.
455
456 ### Pre-Implementation Gate
457
458 Implementation must not begin until the branch-local SOW contains a concrete `## Pre-Implementation Gate` section with `Status: ready` or `Status: in-progress`. Before changing implementation files, or before continuing implementation in an existing SOW that lacks this section, fill the gate. Reaching `Status: ready` additionally requires the "Plan before non-trivial work" Human approval gate (explicit user approval of the goal and plan).
459
460 The gate must record the problem/root-cause model, evidence reviewed, affected contracts and surfaces, the clean-end-state target (its removed-redundant and excluded-coupled items, and the reference search where a path or contract is replaced), existing patterns to reuse, risk and blast radius, sensitive data handling plan, implementation plan, validation plan, artifact impact plan, and open decisions. The sensitive data plan must cover SOWs, specs, documentation, project skills, agent instructions, and code comments. Generic placeholders such as `TBD`, `N/A`, or "to be checked later" are invalid unless the SOW explains why the item truly does not apply. If the gate exposes an unknown that cannot be resolved by investigation, stop and ask the user before implementation.
461
462 ### When A SOW Is Required
463
464 Create or reuse a SOW for non-trivial work:
465
466 - feature work;
467 - bug fixes with behavioral impact;
468 - refactors;
469 - migrations;
470 - documentation or content changes with product/business impact;
471 - process changes;
472 - regressions;
473 - spec hygiene;
474 - project skill changes;
475 - collector changes;
476 - packaging, install, or deployment changes;
477 - PR review iteration;
478 - static analysis triage that changes source, docs, or project policy;
479 - any work with unclear risk.
480
481 Trivial work does not need a SOW:
482
483 - typo fixes;
484 - formatting-only changes;
485 - mechanical rename with no behavior change;
486 - simple search/replace with low risk (still grep for the old token to confirm no call sites are missed).
487
488 When unsure, treat the work as non-trivial.
489
490 ### SOW Locations And Naming
491
492 - Active branch-local SOWs: `.agents/sow/active/`
493 - Specs: `.agents/sow/specs/`
494 - Template for new SOWs: `.agents/sow/SOW.template.md`
495 - Local audit: `.agents/sow/audit.sh`
496
497 There is no `done/` directory and no committed pending queue. On `master`,
498 `.agents/sow/active/` is empty except for `.gitkeep`; real SOW files exist only
499 on feature branches. Feature branches and PRs may commit active SOW files when
500 takeover or handoff is expected, but active SOW files are deleted before merge.
501
502 Create new SOW files from `.agents/sow/SOW.template.md`. The template is project-local and may be customized for this repository.
503
504 Empty SOW directories must contain `.gitkeep` or `.keep` so the committed repository preserves the full SOW layout after clone/checkout.
505
506 ### Local SOW Parking
507
508 Users may keep private paused, abandoned, or not-yet-public SOW drafts under
509 `<repo-root>/.local/sow/`. This directory is gitignored and outside the project
510 SOW lifecycle.
511
512 Use `<repo-root>/.local/sow/` when the user wants to preserve work locally
513 without creating a public or team-visible GitHub issue yet.
514
515 Local parked SOWs are private memory only:
516
517 - they are not durable project memory;
518 - they are not visible to other contributors;
519 - they are not acceptable as the only tracking for work that must coordinate a
520 team, block a merge, or survive across machines.
521
522 Deferred work has two valid tracking paths:
523
524 - public or team-visible follow-up: GitHub issue;
525 - private or local follow-up: `<repo-root>/.local/sow/`.
526
527 Active implementation work still MUST use `.agents/sow/active/`. Active SOW
528 files MAY be committed for takeover or handoff and still MUST be deleted before
529 merge.
530
531 Filename:
532
533 ```text
534 SOW-YYYYMMDD-{slug}.md
535 ```
536
537 Use the creation date plus a descriptive slug. There is no sequential `NNNN`
538 counter because it cannot be allocated safely across parallel branches.
539
540 SOW state lives in the file's `Status:` field:
541
542 - `planning` - analysis or decisions are incomplete; implementation is blocked.
543 - `ready` - the Pre-Implementation Gate is complete and, where the goal-approval round ("Plan before non-trivial work") applies, the user has approved the goal and plan; implementation can start.
544 - `in-progress` - implementation is underway.
545 - `paused` - work is intentionally stopped but may resume on the branch.
546 - `completed` - work is validated and durable memory has been transferred; this is a transient state before deleting the SOW file.
547
548 ### SOW Completion And Merge
549
550 The successful terminal SOW status is `completed`.
551
552 When a SOW's work is ready to merge:
553
554 1. Finish implementation, docs, specs, skills, validation, and follow-up mapping.
555 2. Transfer all durable knowledge into `.agents/sow/specs/`, project skills, docs, code, and tests. After this step, the SOW body MUST hold nothing durable that is not captured elsewhere.
556 3. Update the SOW to `Status: completed`.
557 4. Delete the SOW working file before merge.
558
559 Draft and ready-for-review PRs MAY temporarily contain
560 `.agents/sow/active/SOW-*.md` files when takeover or handoff is expected. The
561 SOW CI job still rejects committed active SOW files; that red check is an
562 intentional merge guard, not a sign that handoff or takeover is forbidden. The
563 branch HEAD that merges MUST contain no `.agents/sow/active/SOW-*.md` file.
564
565 ### Enforcement
566
567 The SOW system is enforced by local audit tooling and CI:
568
569 - `.agents/sow/audit.sh` is the local consistency audit for SOW rules, specs,
570 references, and sensitive-data scanning.
571 - `.agents/sow/scan-sensitive.sh` is the shared sensitive-data scanner used by
572 local audit and CI.
573 - `.github/workflows/sow.yml` rejects pull requests that contain branch-local
574 SOW working files under `.agents/sow/active/SOW-*.md` or legacy SOW working
575 files under `.agents/sow/{pending,current,done}/SOW-*.md`. This failure is
576 expected when an active SOW is intentionally committed for takeover or
577 handoff; it MUST be cleared before merge.
578 - The same workflow scans changed SOW, spec, instruction, and cross-tool
579 bridge files for raw sensitive data.
580
581 These checks are guards, not substitutes for the SOW Validation Gate. The
582 assistant still owns transferring durable knowledge out of the SOW before
583 merge.
584
585 ### One SOW At A Time
586
587 Never execute multiple SOWs as one batch.
588
589 If work overlaps:
590
591 - coordinate through the relevant open PRs and issues;
592 - merge or consolidate branches before implementation; or
593 - split into separate SOWs and complete one before starting the next.
594
595 Progress reports are not stop points (re-evaluating against the target per the Clean-end-state rule is not itself a stop point). Once a SOW is in progress and its goal/plan approval is recorded ("Plan before non-trivial work"), continue until it is delivered, failed with evidence, blocked on a real user decision/approval, or superseded by newer user instructions.
596
597 ### User Decisions
598
599 When user decisions are needed:
600
601 1. Present concrete evidence with files/lines or source references.
602 2. Provide numbered options.
603 3. Explain pros, cons, implications, and risks.
604 4. Recommend one option with reasoning.
605 5. Record the user's decision in the SOW before implementation. For the goal/plan approval round, the bar is the "Plan before non-trivial work" Human approval gate.
606
607 ### Followup Discipline
608
609 "Deferred" is not a terminal outcome.
610
611 Before a SOW can close, every valid deferred item must be:
612
613 - implemented in the current SOW; or
614 - explicitly rejected as not worth doing, with evidence; or
615 - represented by a GitHub issue linked from the current SOW or PR.
616
617 Pre-close, search the SOW for:
618
619 ```text
620 defer|later|follow-up|future|TODO|pending
621 ```
622
623 Map every remaining item to implemented, rejected, or tracked.
624
625 ### Regressions
626
627 A regression is broken behavior discovered after a SOW's work merged, where the
628 original claimed outcome is no longer true.
629
630 Because completed SOWs are not retained on `master`, a regression is handled as
631 new work:
632
633 1. Open a new branch-local SOW under `.agents/sow/active/`.
634 2. In `## Requirements`, link the prior work: `Regresses: PR #NNNNN` and cite
635 any known commit, spec, issue, or test evidence.
636 3. Run the normal Pre-Implementation Gate and Validation for the new SOW.
637 4. Update the relevant spec, skill, doc, code, or test so durable memory reflects
638 current reality.
639
640 Do not attempt to resurrect or mutate a prior SOW.
641
642 ### Validation Gate
643
644 A SOW cannot be completed until Validation records:
645
646 - acceptance criteria evidence;
647 - clean-end-state evidence: the delivered state matches the clean end state recorded in the SOW, including its recorded list of removed-redundant and excluded coupled items (and, where a path or contract was replaced, the recorded reference search), or an explicit user approval for a non-clean state is recorded and linked;
648 - deferred clean-end-state remainder: any clean-end-state work deferred under an approved partial (exception (d)) or otherwise tracked rather than done is listed with why deferral was acceptable and when (or under what condition) it lands;
649 - tests or equivalent validation;
650 - real-use evidence when a runnable path exists;
651 - reviewer findings and how they were handled;
652 - same-failure search results;
653 - artifact maintenance gate for `AGENTS.md`, runtime project skills, specs, end-user/operator docs, end-user/operator skills, and SOW lifecycle;
654 - SOW working file removed before merge;
655 - spec update or specific reason no spec update was needed;
656 - project skill update or specific reason no skill update was needed;
657 - end-user/operator docs update or evidence-backed reason none were affected;
658 - end-user/operator skill update or evidence-backed reason none were affected by docs/spec changes;
659 - lessons extracted or specific reason there were none;
660 - follow-up mapping.
661
662 Generic "N/A" is invalid.
663
664 ### Artifact Maintenance Gate
665
666 Every SOW close must explicitly record whether each durable artifact class was updated or why no update was needed:
667
668 - `AGENTS.md` - workflow, responsibility, local framework, project-wide guardrails.
669 - Runtime project skills - `.agents/skills/project-*/SKILL.md` for HOW to work here.
670 - Specs - `.agents/sow/specs/` for WHAT the project does.
671 - End-user/operator docs - README, docs site, runbooks, published guides, help text, or other human-facing documentation.
672 - End-user/operator skills - output/reference skills copied or consumed outside normal repo work.
673 - SOW lifecycle - branch-local active SOW, durable memory transfer, SOW deletion before merge, deferred work tracked as GitHub issues, and regressions handled as new linked SOWs.
674
675 This is an assistant responsibility. If a SOW changes behavior, docs, specs, commands, schemas, defaults, workflows, examples, or operating procedure, the assistant must update every affected artifact in the same SOW, or record the evidence-backed reason an artifact is unaffected.
676
677 ### Specs
678
679 Specs are memory of WHAT this project does.
680
681 This repository is bootstrapped incrementally. The existing source tree and public documentation remain the primary ground truth. SOW specs under `.agents/sow/specs/` should capture durable project decisions, cross-cutting behavioral rules, and area-specific contracts as they are worked.
682
683 `.agents/sow/specs/` stays flat until scale proves hierarchy is needed. Use
684 `<domain>-<topic>.md` names, one durable contract or cross-cutting rule per file,
685 and update `.agents/sow/specs/README.md` in the same change. Do not split specs
686 by repository path; specs are organized by contract ownership, not source-file
687 location.
688
689 Update specs when shipped work changes:
690
691 - product behavior;
692 - public contracts;
693 - collector behavior;
694 - APIs and schemas;
695 - data formats;
696 - alerting semantics;
697 - packaging or deployment behavior;
698 - operational guarantees;
699 - known edge cases.
700
701 Specs describe current reality, not aspiration. If specs and code disagree, record the discrepancy in the active SOW and resolve or track it.
702
703 ### Project Skills
704
705 Project skills are memory of HOW to work here.
706
707 Runtime input project skills should live under `.agents/skills/*/SKILL.md`. Before non-trivial work, inspect those skill descriptions and load every matching runtime skill.
708
709 Output/reference skills may also exist under product documentation or generated skill directories. Do not rename, shorten, or change their descriptions only to satisfy runtime discovery. Update them when their related public/operator workflow changes.
710
711 ### Public skill convention (`docs/netdata-ai/skills/`)
712
713 End-user-facing AI skills under `docs/netdata-ai/skills/` follow the directory shape `docs/netdata-ai/skills/<skill-name>/SKILL.md`, with optional supporting docs (`<topic>.md`) and an optional `scripts/` subdirectory for helper code. SKILL.md frontmatter has `name` and `description`; the description is the trigger-matching text and must enumerate the phrases users will actually type.
714
715 Public skills are for operators and end-users. They may teach users how to
716 query Netdata Cloud, query Agents, inspect metrics/logs/topology/alerts, or run
717 safe operational commands. They must not contain developer-contract validation,
718 schema migration plans, producer authoring workflows, UI adapter work,
719 aggregator implementation notes, SOW handoff instructions, fixture maintenance,
720 PR-review tasks, or codebase-internal implementation recipes.
721
722 Developer-facing skills must live under `.agents/skills/`, preferably with a
723 `project-` prefix when they are runtime input for repository work. If a workflow
724 requires reading source files, updating schemas, validating fixtures, changing
725 collectors/producers, or coordinating frontend/backend/aggregator code, it is a
726 project developer skill, not a public skill.
727
728 Skill verification harness inputs are not public skill content. Keep seed
729 questions, grader rubrics, runner scripts, and transcript-generation prompts
730 under `.agents/skill-verification/<skill>/`, not under
731 `docs/netdata-ai/skills/<skill>/`.
732
733 Each public skill is reachable from `.agents/skills/<skill-name>` via a relative symlink (`.agents/skills/<name>` → `../../docs/netdata-ai/skills/<name>`) so local AI assistants reading from `.agents/skills/` see the same skill as end-users. Create the symlink with `ln -srfn`. Verify with `readlink -f .agents/skills/<name>`.
734
735 Public-skill scripts must follow the same `_lib.sh` shape as existing skills (`set -euo pipefail`, ANSI colors with real ESC bytes via `$'\033[...]'`, `<prefix>_repo_root` via `git rev-parse --show-toplevel`, `<prefix>_load_env` that sources `<repo>/.env` with `: "${VAR:?}"` validation, `<prefix>_audit_dir` that creates `<repo>/.local/audits/<topic>/`, masked-token `<prefix>_run`/`<prefix>_run_read` wrappers).
736
737 Public-skill scripts that touch credentials (cloud tokens, per-agent bearers, claim ids, session cookies) MUST be **token-safe** -- helpers that handle credential bytes are named with a leading underscore (`_skill_*`, internal-only) and return them via bash namerefs into the caller's local variables, NEVER to stdout. Public wrappers (no leading underscore) read credentials from `.env` internally and emit ONLY the response body. Each token-handling lib must ship a `<prefix>_selftest_no_token_leak` function that drives every public wrapper with a sentinel token and asserts the sentinel never appears on captured stdout.
738
739 ### How-tos catalog rule
740
741 Each public skill ships a `how-tos/` subdirectory with `INDEX.md`. The catalog is **live**: every time an AI assistant is asked a concrete operator/end-user question that requires analysis (multiple wrapper calls, jq pipelines, or cross-referencing more than one per-domain guide) and the answer isn't already documented under `how-tos/`, the assistant MUST author a new how-to and add it to `INDEX.md` BEFORE completing the task. This rule is repeated in each skill's `SKILL.md` so future assistants honor it. Skipping it means the next assistant repeats the same analysis from scratch -- an explicit framework violation.
742
743 The how-to rule does not override audience boundaries. If the analysis produced
744 a developer validation recipe, put it in the matching `.agents/skills/` project
745 skill and update that skill's index instead of adding it under
746 `docs/netdata-ai/skills/`.
747
748 The existing private skills (`coverity-audit`, `sonarqube-audit`, `graphql-audit`, `pr-reviews`) keep their `.agents/skills/<name>/` location -- they are intentionally private and have no `docs/netdata-ai/skills/` counterpart.
749
750 ### Project Skills Index
751
752 Runtime input skills:
753
754 - `.agents/skills/project-snmp-profiles-authoring/`
755 Trigger: editing SNMP profile YAMLs, topology SNMP profiles, ddsnmp profile parsing, or SNMP profile-format documentation.
756 Purpose: require MIB `MAX-ACCESS` checks and index-derived extraction for `not-accessible` INDEX objects.
757
758 - `.agents/skills/project-writing-collectors/`
759 Trigger: authoring or modifying any Netdata data-collection plugin or module (Go go.d / ibm.d, Rust crates, internal C plugins, external plugins via PLUGINSD). Read before adding a new collector, modifying an existing one, working on NetFlow/sFlow/IPFIX, OTEL ingestion, topology, SNMP profiles, or interactive Functions.
760 Status: live. Updates that close gaps or fix outdated pointers must ship in the same PR that exposed the issue.
761
762 - `.agents/skills/project-create-topology/`
763 Trigger: creating or updating Netdata topology producers, topology Function payloads, topology schema fixtures, graph presentation, correlation rules, direction semantics, topology drilldowns, telemetry overlays, or Cloud topology aggregation fixtures.
764 Status: live. Developer-facing topology authoring workflow. End-user/operator-facing AI skills belong under `docs/netdata-ai/skills/`; this project skill is the runtime guidance for repository work.
765
766 - `.agents/skills/project-writing-go-modules-framework-v2/`
767 Trigger: creating or migrating a Go go.d collector to framework V2; touching `CollectorV2`, `metrix.CollectorStore`, `ChartTemplateYAML` / `charts.yaml`, `charttpl`, `chartengine`, V2 host scopes, or V2 collector tests.
768 Purpose: mirror maintainer-preferred framework V2 patterns from accepted collectors so new or migrated modules blend with repository style.
769
770 - `.agents/skills/integrations-lifecycle/`
771 Trigger: editing any `metadata.yaml` or collector `taxonomy.yaml`; modifying `integrations/` generators, schemas, taxonomy registries, or templates; debugging generated gitignored integration outputs (`integrations.js`, `integrations.json`, `integrations/taxonomy.json`); working with committed per-integration `.md` files / `COLLECTORS.md` / `SECRETS.md` / `SERVICE-DISCOVERY.md`; ibm.d module generation (`contexts.yaml` -> `metadata.yaml`); CI workflows `generate-integrations.yml` and `check-markdown.yml`; the collector-consistency rule.
772 Status: live. SKILL.md plus per-domain guides (`pipeline.md`, `schema-reference.md`, `per-type-matrix.md`, `artifacts-and-banners.md`, `ibm-d.md`, `consistency.md`, `in-app-contract.md`, `gotchas.md`) and `recipes/`, `how-tos/` directories.
773
774 - `.agents/skills/learn-site-structure/`
775 Trigger: adding/moving/renaming/deleting any docs page that should appear on `learn.netdata.cloud`; editing `<repo>/docs/.map/map.yaml`; investigating why a Learn page looks the way it does; reading the live `ingest/ingest.py` orchestrator or the legacy `ingest.js` / `ingest.md` (which are stale); MDX escape rules; redirects; the Netlify deploy contract.
776 Status: live. SKILL.md plus per-domain guides (`mapping.md`, `pipeline.md`, `sidebars.md`, `mdx-rules.md`, `redirects.md`, `pitfalls-and-gotchas.md`, `authoring-boundary.md`) and `recipes/`, `how-tos/` directories.
777 - `.agents/skills/learn-pr-preview/`
778 Trigger: only when the user explicitly asks to build, run, preview, inspect, or validate `learn.netdata.cloud` locally using the contents of a PR or documentation branch before merge.
779 Status: live. SKILL.md with an isolated preview workflow that copies PR source content, runs Learn ingest with `--local-repo`, builds Docusaurus with the Netlify-pinned runtime, and inspects representative pages without dirtying the real Learn checkout.
780 - `.agents/skills/query-agent-events/`
781 Trigger: investigating crashes, panics, or fatals across the Netdata fleet; downloading events from the agent-events ingestion namespace; analyzing AE_* fields and their enums; understanding the 23h client-side dedup or the after-the-fact event timing; using the systemd-journal Function multi-value `selections` filter for index-friendly queries.
782 Status: live. SKILL.md plus per-domain guides (`AE_FIELDS.md`, `transports.md`, `update-cadence.md`, `query-discipline.md`, `finding-crashes.md`, `finding-fatals.md`), scripts (`scripts/_lib.sh`, `get-events.sh`, `analyze-events.sh`, `redact-events.sh`) and `recipes/`, `how-tos/` directories. Bug-investigation tool, NOT a generic logs query skill -- consumes `query-netdata-{cloud,agents}` for transport.
783
784 - `.agents/skills/mirror-netdata-repos/`
785 Trigger: setting up or updating a local mirror of Netdata-org source repositories at `${NETDATA_REPOS_DIR}` for cross-repo grep / code review without GitHub API calls; running the vendored sync script; questions about the reset-to-default-branch safety mechanism or the `--repo NAME` scoping flag.
786 Status: live. SKILL.md (single-file overview) plus the vendored `scripts/sync-netdata-repos.sh` (env-driven, sanitized, `--repo` scoping, `gh` optional for Phase 2) and `how-tos/` catalog. Independent from any other repo mirrors this workstation may have.
787
788 - `.agents/skills/coverity-audit/`
789 Trigger: Coverity Scan defect triage for this repository.
790 Status: live.
791
792 - `.agents/skills/sonarqube-audit/`
793 Trigger: SonarCloud findings triage for this repository.
794 Status: live.
795
796 - `.agents/skills/graphql-audit/`
797 Trigger: GitHub Code Scanning/CodeQL triage for this repository.
798 Status: live.
799
800 - `.agents/skills/pr-reviews/`
801 Trigger: PR comment and review iteration work for this repository.
802 Status: live.
803
804 - `.agents/skills/codacy-audit/`
805 Trigger: Codacy Cloud workflow for this repository -- pre-push local analysis (`codacy-analysis-cli` via docker or local binary) and read-only PR-issue fetching via the v3 API.
806 Status: live. SKILL.md plus `scripts/_lib.sh` (token-safe wrappers + sentinel no-leak self-test), `scripts/analyze-local.sh`, `scripts/pr-issues.sh`, and a live `how-tos/INDEX.md` catalog. Read-only by design; write actions require a GitHub issue or branch-local SOW.
807
808 Public skills (canonical under `docs/netdata-ai/skills/<name>/`; relative symlinks at `.agents/skills/<name>`):
809
810 - `docs/netdata-ai/skills/query-netdata-cloud/`
811 Trigger: querying Netdata Cloud REST API -- metrics, logs (systemd-journal), alerts, generic Function calls on a node.
812 Symlink: `.agents/skills/query-netdata-cloud` -> `../../docs/netdata-ai/skills/query-netdata-cloud`.
813 Status: live. SKILL.md plus per-domain guides (`query-metrics.md`, `query-logs.md`, `query-alerts.md`, `query-functions.md`).
814
815 - `docs/netdata-ai/skills/query-netdata-agents/`
816 Trigger: querying Netdata Agents directly on port 19999, including auto-mint of per-agent bearer tokens from a Cloud token.
817 Symlink: `.agents/skills/query-netdata-agents` -> `../../docs/netdata-ai/skills/query-netdata-agents`.
818 Status: live. SKILL.md plus `scripts/_lib.sh` helpers (`agents_resolve_bearer`, `agents_call_function`, `agents_netdata_prefix`).
819
820 Output/reference skills:
821
822 - `docs/netdata-ai/skills/`
823 Consumer: downstream assistants and users of Netdata AI skill artifacts.
824 Update when: public/operator AI skill docs, examples, commands, schemas, or workflows change.
825
826 - `src/ai-skills/`
827 Consumer: downstream assistants and users of generated or source AI skill artifacts when this tree is present in the working copy.
828 Update when: generated/source AI skill behavior, tests, examples, commands, schemas, or workflows change.
829
830 ### Project-specific commands
831
832 - This bootstrap pass does not define a full-project command matrix for the monolith.
833 - Use the narrowest existing command that validates the changed subsystem.
834 - Do not claim full-project validation from a narrow subsystem command.
835 - Existing local helper scripts such as `install.sh` may exist in this working copy; inspect before use and do not assume they are tracked project interfaces.
836
837 ### Go test style
838
839 - Prefer table-driven tests using `map[string]struct{}` keyed by test-case name
840 when cases share setup and assertion shape.
841 - Use separate test functions only when setup or assertions are materially
842 different.
843 - Prefer map keys over a `name` field in `[]struct{}` so case names are
844 prominent and order-independent.
845
846 ### Project-specific overrides
847
848 All existing project-specific instructions in this file remain active. The SOW framework adds durable work tracking; it does not weaken the root-cause, collector consistency, C code, naming, local-output, or secret-handling rules below.
849
850 ## Collector Consistency Requirements
851
852 When working on collectors, runtime behavior, metrics, charts, configuration,
853 alerts, taxonomy, and generated documentation MUST stay consistent in one PR.
854 The detailed collector consistency checklist and CI enforcement notes live in
855 `.agents/skills/integrations-lifecycle/consistency.md`.
856
857 ## C code
858 - gcc, clang, glibc and muslc
859 - libnetdata.h includes everything in libnetdata (just a couple of exceptions) so there is no need to include individual libnetdata headers
860 - Functions with 'z' suffix (mallocz, reallocz, callocz, strdupz, etc.) handle allocation failures automatically by calling fatal() to exit Netdata
861 - The freez() function accepts NULL pointers without crashing
862 - Resuable, generic, module agnostic code, goes to libnetdata
863 - Double linked lists are managed with DOUBLE_LINKED_LIST_* macros
864 - json-c for json parsing
865 - buffer_json_* for manual json generation
866
867 ## Naming Conventions
868 - "Netdata Agent" (capitalized) when referring to the product
869 - "`netdata`" (lowercase, code-formatted) when referring to the process
870 - See DICTIONARY.md for precise terminology
871
872 ## Local-only working directory
873
874 `/.local/` at the repo root is gitignored and reserved for per-user runtime
875 artifacts: audit reports, fetched API data, scratch notes, queue files,
876 intermediate triage decisions. Agents writing skill output should default to
877 `<repo-root>/.local/audits/<topic>/...` -- where `<topic>` is the skill
878 name with any trailing `-audit` suffix removed (so `coverity-audit/`
879 writes under `coverity/`, `pr-reviews/` writes under `pr-reviews/`).
880
881 Convention:
882 - `/.local/audits/coverity/` - Coverity raw fetches, per-defect details, triage decisions
883 - `/.local/audits/sonarqube/` - Sonar finding queues, FP comment templates
884 - `/.local/audits/graphql/` - GitHub Code Scanning fetches and dismissals
885 - `/.local/audits/pr-reviews/`- Per-PR comment / review caches
886
887 Naming: each skill `<topic>-audit/` writes to `.local/audits/<topic>/`
888 (the `-audit` suffix is dropped from the directory name so the URL-style
889 path stays short). Skills without the `-audit` suffix keep their full
890 name (e.g. `pr-reviews/` writes to `.local/audits/pr-reviews/`). When
891 adding a new skill, follow this convention.
892
893 Nothing under `/.local/` is committed. Treat the directory as ephemeral
894 between users and machines, not as a shared source of truth.
895
896 ## Per-user secrets via `.env`
897
898 `/.env` at the repo root is gitignored and holds per-user secrets and
899 endpoint configuration consumed by skill scripts: API tokens, session
900 cookies, project keys. Never commit secrets; never hard-code tokens in scripts.
901
902 **Setup**: copy `<repo>/.env.template` to `<repo>/.env` and fill in
903 the keys you need.
904
905 **Reference**: `<repo>/.agents/ENV.md` is the single canonical guide
906 covering every key -- what it is, where to find the value, sample
907 format, common mistakes, and which skills require it. When a script
908 errors with `<KEY> is empty`, check `.agents/ENV.md` for that key.