AGENTS.md

1# AGENTS.md
2 
3## Goals
4 
5This 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 
7Work in this repository must prioritize root-cause understanding, correctness, performance, maintainability, portability, security, and consistency with existing project conventions.
8 
9## Requirement Language
10 
11This 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 
20CRITICAL RULES:
21 
221. 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 
252. 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 
283. Do not duplicate code.
29   First check if similar code already exists and reuse it.
30 
31## Mandatory Development Principles
32 
33These principles are mandatory for every task. Code is cheap to add and
34expensive to live with, so a larger diff that removes debt beats a smaller one
35that preserves it.
36 
37**Core (read first; the bullets under each principle are the authority for forks
38and 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 
581. **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   - Re-ground staged designs: a design recorded during planning or an earlier
161     stage MAY have drifted from the code a previous stage produced (a removed
162     structure, an obsoleted mechanism). Before implementing a later stage you
163     MUST re-verify its recorded design against the current code and record the
164     correction in the SOW; never implement against stale assumptions.
165   - Deferral check: before recommending deferral, check the issue, SOW,
166     acceptance criteria, and affected migration scope. Silence or ambiguity MUST
167     NOT be read as permission to defer; if those sources do not clearly place
168     the work outside the approved clean end state, treat it as in-scope and
169     either complete it or pause for a user decision.
170   - Trivial-work exemption: trivial work (per "When A SOW Is Required") has no
171     SOW and is exempt from the record-the-target, disclosure, and
172     reference-search bullets above; the clean-end-state preference still applies.
173     When unsure, treat the work as non-trivial.
174 
1752. **Plan before non-trivial work.**
176   - Plan first: non-trivial work (see "When A SOW Is Required") MUST start with
177     a plan recorded in the SOW before any implementation-file change and before
178     any implementation-equivalent action — migrations, deletions, pushes,
179     non-draft PRs, or external-state mutations via tools. Trivial work is exempt;
180     when unsure, treat the work as non-trivial.
181   - Human-owned goal: the desired end state — the goal, or coherent goal set, the
182     work must reach — MUST be created with or approved by the user. You MUST NOT
183     finalize the goal unilaterally (same user-owned target as Clean end state).
184   - End state first: you MUST establish the desired end state — including its
185     acceptance criteria — before planning the steps; the goal drives the work,
186     not a first diff. If you cannot yet state the end state, keep investigating
187     until you can; do not start work against an unknown target. When the end
188     state is itself a user-owned design decision, record a provisional target
189     plus the open question and resolve it with the user first (Clean end state).
190     Then plan the steps to move from the current state toward that end state.
191   - Decompose into steps: split the work into ordered steps, each with its own
192     clean end state and acceptance criteria, each building on the previous one
193     toward the desired end state. A single coherent step is a valid decomposition
194     when the work is atomic; do not invent artificial sub-steps.
195   - Resolve huge or vague work: if the deliverable is large or vague, keep
196     refining the plan until every step has a clean end state and acceptance
197     criteria. Do not start implementation while steps are still unclear.
198   - Reachability: the plan MUST either reach the desired end state through its
199     steps, or produce evidence that it is not achievable; an unachievable goal
200     is a pause condition for a user decision, not a silent partial result.
201   - Human approval gate: when a goal-approval round is required (see "Approval is
202     for goal-decisions" below), the whole plan — the desired end state and the
203     step breakdown — MUST be explicitly approved by the user before
204     implementation. The assistant proposes and investigates; the user approves.
205     State the goal and step breakdown being accepted, and get confirmation that
206     meets the Approval bar (Clean end state). If the user rejects or edits the
207     plan, revise and re-seek approval; the SOW stays in `planning` until an
208     explicit approval is recorded, then reaches `Status: ready`. This gate is the
209     canonical statement of the approval requirement that the Pre-Implementation
210     Gate and Required First Checks reference.
211   - Approval is for goal-decisions, not work categories:
212     - The goal-approval round fires ONLY when the end state is a genuine
213       user-owned fork — competing designs, a public-contract change, a
214       destructive or irreversible step, or unclear scope.
215     - Other non-trivial work whose end state is already fixed by the triggering
216       request, an existing project skill, or an established repository pattern
217       (for example a clear bug fix, a metadata/docs edit with no contract change,
218       or a collector's skeleton and wiring fixed by its authoring skill — though
219       its Function surface, vnode/host-scope design, and new public config
220       options remain user-owned forks) still needs a recorded plan and the
221       Pre-Implementation Gate, but the triggering request IS the recorded goal
222       approval — no separate round, which also satisfies the resume re-check and
223       the progress rule.
224     - When it is unclear whether a real fork exists, treat it as user-owned and
225       seek approval.
226   - Approval persists; re-check on resume: before continuing an `in-progress` or
227     `paused` SOW you did not personally take through this gate — including
228     takeover or handoff — you MUST confirm the SOW records explicit approval of
229     the current goal and plan. If it does not, or the plan changed materially
230     since approval, treat the SOW as `planning` and re-obtain approval before
231     further implementation.
232 
2333. **Scope discipline at every step.**
234   - Drift check: at each Re-evaluation checkpoint (Clean end state), you MUST
235     also check whether the work has drifted outside the approved scope, not only
236     whether the diff still matches the recorded target.
237   - Independence test: new work is "genuinely independent" only if ALL hold —
238     (a) the approved clean end state is still complete and correct without it,
239     (b) it is not a coupled item or a remaining reference recorded under Clean
240     end state, and (c) it has its own separable acceptance criteria. If any test
241     fails, or you are unsure, treat the work as coupled, not independent, and
242     handle it under Clean end state (do the low-risk part and disclose it; pause
243     only for a genuine fork) — you are not the scope authority.
244   - Disposition of independent work:
245     - Do NOT silently bundle it.
246     - Submit it as a separate PR first and rebase the current branch after it
247       merges, or track it as a GitHub issue per "Followup Discipline."
248     - Do NOT fold it into this SOW's steps — Clean-end-state staged-delivery
249       stages must be a decomposition of one clean end state.
250   - Governed elsewhere: coupled cleanup is in scope (Clean end state), and
251     non-trivial work is delivered in coherent incremental steps (Plan before
252     non-trivial work); this principle does not restate them.
253 
254**Flow diagrams (human reading aid, non-normative):** the bullets above are
255authoritative; the diagrams below summarize the flow for human readers and MUST
256be kept in sync when the principles change.
257 
258<details>
259<summary>Show per-principle flow diagrams</summary>
260 
261How the three principles connect (lifecycle order):
262 
263```mermaid
264flowchart LR
265    A("1. Clean end state<br/>defines the target (what 'done' means)")
266    B("2. Plan before non-trivial work<br/>establish the target + steps; user approves real forks")
267    C("3. Scope discipline<br/>stay on the target while executing each step")
268    A --> B --> C
269    C -->|re-evaluate vs target| A
270```
271 
2721. Clean end state over less churn:
273 
274```mermaid
275flowchart TD
276    A("Approved scope = issue + SOW Purpose/Acceptance + implied surface")
277    B("Define the clean end state, incl. removing what the change makes redundant")
278    C("Record target in SOW: exclusions list + reference search if a path/contract is replaced")
279    D{"Matches recorded target?"}
280    E("Deliver the clean end state")
281    F{"Allowed exception?"}
282    Fx("Only: a) impossible, b) evidenced safety risk, c) out of scope, d) user-accepted partial")
283    G("NOT allowed: risk reduction, smaller diff, or staging")
284    H("Mandatory pause: present evidence, STOP")
285    I{"Explicit approval?"}
286    Ix("Approval bar: a bare 'ok' is not approval")
287    J("Proceed; track remainder per Followup Discipline")
288    K("Re-evaluate vs target: each step, before a PR, before complete")
289    A --> B --> C --> D
290    D -->|yes| E
291    D -->|no| F
292    F -->|no| G --> B
293    F -->|yes| H --> I
294    I -->|no| B
295    I -->|yes| J
296    F -.- Fx
297    I -.- Ix
298    E --> K
299    J --> K
300```
301 
3022. Plan before non-trivial work:
303 
304```mermaid
305flowchart TD
306    A("Task")
307    B{"Trivial?"}
308    C("Exempt: just do it (clean-end-state preference still applies)")
309    D("Establish the desired end state + acceptance criteria FIRST; keep investigating until you can")
310    E("Decompose into ordered steps, each with its own clean end state + criteria; move current toward desired")
311    F{"End state a user-owned fork?"}
312    Fk("Fork = competing designs, public-contract/destructive change, or unclear scope")
313    G("Fixed by request/skill/pattern: the request IS the approval (recorded plan + gate, no separate round)")
314    H("Goal-approval round: explicit user approval of the whole plan (Approval bar)")
315    I("Status: ready, implement")
316    J("Pause for a user decision (not a silent partial)")
317    A --> B
318    B -->|yes| C
319    B -->|no| D
320    D --> E --> F
321    F -->|no| G
322    F -->|yes| H
323    F -.- Fk
324    G --> I
325    H --> I
326    D -->|goal unreachable| J
327```
328 
3293. Scope discipline at every step:
330 
331```mermaid
332flowchart TD
333    A("At each Re-evaluation checkpoint")
334    B{"Drifted outside approved scope?"}
335    C("Continue")
336    D{"Genuinely independent?"}
337    Dx("Independent only if ALL: end state complete without it; not a coupled item/reference; separable acceptance criteria")
338    E("Treat as COUPLED: handle under Clean end state (do the low-risk part + disclose); pause only for a genuine fork")
339    F("Do NOT bundle silently: separate PR + rebase, or track as a GitHub issue; never fold into this SOW's steps")
340    A --> B
341    B -->|no| C
342    B -->|new work| D
343    D -->|no or unsure| E
344    D -->|yes| F
345    D -.- Dx
346```
347 
348</details>
349 
350USER COMMUNICATION:
351 
3521. ALWAYS DO YOUR HOMEWORK BEFORE ASKING QUESTIONS OR REQUESTING USER DECISIONS.
353   PROACTIVELY CHECK ALL RELATED ASPECTS AND ALL POSSIBILITIES SO THAT YOUR QUESTIONS AND REQUESTS ARE WELL INFORMED AND TO THE POINT.
354 
3552. NEVER WRITE WALLS OF TEXT TO THE USER, UNLESS THEY ASKED FOR IT.
356   YOUR COMMUNICATION MUST BE SIMPLE, DIRECT, LEAN, ORDERED BY IMPORTANCE.
357   PROVIDE THE FULL PICTURE AT THE BEGINNING, START FROM THE HIGH LEVEL, AND LET THE USER ASK FOR DETAILS.
358 
3593. NEVER AGREE TO THE USER WHEN THE FACTS CONTRADICT THEIR UNDERSTANDING.
360   YOU MUST ALWAYS PROVIDE CLEAR DESCRIPTIONS OF THE RISKS AND IMPLICATIONS OF THEIR DECISIONS.
361   YOU ARE HELPFUL WHEN YOU ACCURATELY REVEAL THE TRUTH, NOT WHEN YOU AGREE.
362 
363## SOW System
364 
365Project SOW status: initialized
366 
367This project uses a local Statement of Work system.
368 
369SOWs and specs are **local-only working memory, never committed**:
370 
371- SOW working files live under `.agents/sow/q/**` (the queue tree) and MUST NOT
372  be committed to any branch.
373- Specs live under `.agents/sow/specs/**` and are likewise local-only and
374  gitignored. They may be re-introduced to git later, reorganized, as a
375  deliberate decision; until then treat them as local memory.
376- Only the SOW framework files are committed and shared via git:
377  `.agents/sow/SOW.template.md`, `.agents/sow/audit.sh`,
378  `.agents/sow/scan-sensitive.sh`, `.agents/sow/worktree-link.sh`.
379- `.gitignore` enforces this: `/.agents/sow/q` and `/.agents/sow/specs` are
380  ignored; the framework files are tracked normally.
381- Durable knowledge that must survive a SOW belongs in project skills, docs,
382  code, and tests (and, once reorganized, specs) — not in the SOW body.
383- Worktree sharing: SOW working memory is per-developer, not per-worktree. Run
384  `.agents/sow/worktree-link.sh` after creating a git worktree (or after
385  updating an old checkout to this model) to create the queues and symlink
386  `.agents/sow/q`, `.agents/sow/specs`, `.local`, and `.env` to the origin
387  checkout. See "### SOW Locations And Naming".
388 
389The 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 local SOW, project-local specs, and project-local skills.
390 
391### Roles
392 
393- **User responsibilities:** purpose, scope decisions, design forks, risk acceptance, destructive approvals, and final product judgment.
394- **Assistant responsibilities:** investigation, evidence, implementation, tests or equivalent validation, reviews, documentation, memory updates, and concise reporting.
395 
396### Required First Checks
397 
398Before non-trivial work:
399 
4001. Read the active SOWs under `.agents/sow/q/` (the local-only queue tree) if any exist. SOWs are local working memory; discover other in-flight work through open PRs and issues, not through `master`.
4012. Read relevant specs under `.agents/sow/specs/` (local-only memory).
4023. Inspect `.agents/skills/*/SKILL.md` if any exist, and load every runtime project skill whose trigger matches the work.
4034. Inspect legacy runtime skills listed below when the user request matches their frontmatter trigger.
4045. Inspect code, docs, tests, and existing project instructions as ground truth.
4056. 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.
406 
407### Git Worktrees
408 
409Assistants must not create git worktrees on their own. Create a git worktree only when the user explicitly asks for it or approves it.
410 
411After a git worktree is created — or after an old checkout is updated to the
412local-only SOW model — run `.agents/sow/worktree-link.sh`. It builds the SOW
413queues and symlinks `.agents/sow/q`, `.agents/sow/specs`, `.local`, and `.env`
414to the origin checkout, so SOW working memory is shared per-developer rather than
415re-created per worktree. (Exception: a worktree that already has its own real
416`.env` keeps it and is not relinked, so per-worktree secrets are never
417overwritten.) The script is idempotent, never loses data on a name collision,
418re-points a symlink whose origin moved, and refuses to run in a worktree whose
419origin checkout is not yet on this model (it prints how to update the origin
420first).
421 
422### Sensitive Data In Durable Artifacts
423 
424SOWs, 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.
425 
426CRITICAL: 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.
427 
428Write only sanitized evidence:
429 
430- use placeholders such as `[REDACTED_SECRET]`, `[CUSTOMER]`, `[ACCOUNT]`, `[PRIVATE_ENDPOINT]`;
431- use stable aliases such as `customer-a` only when the real mapping is not stored in the repository;
432- cite file paths, line numbers, command names, schema fields, or error classes instead of copying sensitive values;
433- summarize logs and traces; include only minimal redacted snippets.
434 
435If 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.
436 
437### Durable AI-Facing Artifact Formatting
438 
439AI-facing durable artifacts include `AGENTS.md`, SOW specs, runtime project
440skills, public/operator skills, SOW templates, instruction bridge files, and
441other docs primarily written so future AI agents can execute repository rules
442correctly.
443 
444When writing or updating these artifacts:
445 
446- Structure for retrieval and scanning. Use headings, short sections, labeled
447  bullets, and numbered procedures so both humans and AI agents can find the
448  exact rule quickly.
449- Avoid dense multi-rule paragraphs. If a paragraph contains multiple
450  requirements, exceptions, or decision branches, split it into bullets or a
451  table.
452- Use tables only for matrices or comparisons where the cells stay short. Use
453  bullets for rules, workflows, checklists, and exception handling.
454- Put RFC-style requirement words (`MUST`, `MUST NOT`, `SHOULD`, `MAY`) close
455  to the action they govern. Do not hide mandatory behavior in explanatory
456  prose.
457- Prefer labeled bullets for operational guardrails, such as `Target`,
458  `Exception handling`, `Validation`, or `Failure mode`.
459- Keep one durable idea per bullet. If a bullet needs multiple sentences, the
460  first sentence states the rule and later sentences provide evidence,
461  rationale, or examples.
462- For a guardrail with several distinct requirements, use a labeled parent
463  bullet with an indented sub-list — one requirement per sub-bullet — rather than
464  a multi-requirement paragraph; keep a single rule-plus-rationale as one bullet.
465- Preserve precision over brevity. Formatting is for readability, not for
466  weakening contracts or removing necessary evidence.
467- Wrap markdown prose at ~120 columns (SHOULD), not 80. Code blocks, tables, and generated files keep their own
468  formats. Keep reflow-only (whitespace) changes in separate commits from content changes.
469 
470### Open-Source Reference Evidence
471 
472When SOW evidence comes from other open-source repositories, cite the upstream repository and checked commit instead of the workstation absolute path.
473 
474Use:
475 
476```text
477owner/repo @ commit
478relative/path/inside/repo:line
479```
480 
481Resolve `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.
482 
483### Pre-Implementation Gate
484 
485Implementation must not begin until the 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).
486 
487The 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.
488 
489### When A SOW Is Required
490 
491Create or reuse a SOW for non-trivial work:
492 
493- feature work;
494- bug fixes with behavioral impact;
495- refactors;
496- migrations;
497- documentation or content changes with product/business impact;
498- process changes;
499- regressions;
500- spec hygiene;
501- project skill changes;
502- collector changes;
503- packaging, install, or deployment changes;
504- PR review iteration;
505- static analysis triage that changes source, docs, or project policy;
506- any work with unclear risk.
507 
508Trivial work does not need a SOW:
509 
510- typo fixes;
511- formatting-only changes;
512- mechanical rename with no behavior change;
513- simple search/replace with low risk (still grep for the old token to confirm no call sites are missed).
514 
515When unsure, treat the work as non-trivial.
516 
517### SOW Locations And Naming
518 
519- SOW queues (local-only): `.agents/sow/q/` with sub-queues `pending/`,
520  `current/`, `active/`, `done/`. Move a SOW file between these as its state
521  changes; the whole `q/` tree is gitignored.
522- Specs (local-only): `.agents/sow/specs/`
523- Template for new SOWs (committed): `.agents/sow/SOW.template.md`
524- Local audit (committed): `.agents/sow/audit.sh`
525- Worktree/queue setup (committed): `.agents/sow/worktree-link.sh`
526 
527SOW working files and specs are never committed. `.gitignore` ignores
528`/.agents/sow/q` and `/.agents/sow/specs`; only the framework files above are
529tracked. The queue directories are created locally by
530`.agents/sow/worktree-link.sh`, not by committed `.gitkeep` markers, so there is
531no committed SOW layout to preserve.
532 
533Worktree model: SOW working memory is shared per-developer, not per-worktree.
534In a linked worktree, `.agents/sow/worktree-link.sh` symlinks `.agents/sow/q`,
535`.agents/sow/specs`, `.local`, and `.env` to the origin checkout, and migrates
536any pre-existing top-level queue dirs into `q/` without data loss.
537 
538Create new SOW files from `.agents/sow/SOW.template.md`. The template is project-local and may be customized for this repository.
539 
540### Local SOW Parking
541 
542Users may keep private paused, abandoned, or not-yet-public SOW drafts under
543`<repo-root>/.local/sow/`. This directory is gitignored and outside the project
544SOW lifecycle.
545 
546Use `<repo-root>/.local/sow/` when the user wants to preserve work locally
547without creating a public or team-visible GitHub issue yet.
548 
549Local parked SOWs are private memory only:
550 
551- they are not durable project memory;
552- they are not visible to other contributors;
553- they are not acceptable as the only tracking for work that must coordinate a
554  team, block a merge, or survive across machines.
555 
556Deferred work has two valid tracking paths:
557 
558- public or team-visible follow-up: GitHub issue;
559- private or local follow-up: `<repo-root>/.local/sow/`.
560 
561Active implementation work still MUST use the `.agents/sow/q/` queues. SOW
562working files are never committed (the `q/` tree is gitignored), so there is no
563commit-for-handoff and no remove-before-merge step.
564 
565Destructive local deletion guard:
566 
567- Assistants MUST NOT use `rm`, `apply_patch` delete hunks, editor delete
568  operations, or any equivalent filesystem operation to remove a SOW working
569  file from the local checkout unless the user explicitly asks to discard the
570  local SOW.
571- SOW working files are local-only and gitignored, so there is no tracked SOW to
572  untrack and no merge guard to clear.
573- Moving a SOW between `.agents/sow/q/` sub-queues (for example `current/` →
574  `done/`) is normal lifecycle, not deletion.
575 
576Filename:
577 
578```text
579SOW-YYYYMMDD-{slug}.md
580```
581 
582Use the creation date plus a descriptive slug. There is no sequential `NNNN`
583counter because it cannot be allocated safely across parallel branches.
584 
585SOW state lives in the file's `Status:` field:
586 
587- `planning` - analysis or decisions are incomplete; implementation is blocked.
588- `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.
589- `in-progress` - implementation is underway.
590- `paused` - work is intentionally stopped but may resume on the branch.
591- `completed` - work is validated and durable memory has been transferred. The
592  SOW file is local-only and never committed; it MAY be moved to
593  `.agents/sow/q/done/` as local history or deleted locally at the user's
594  request. Never delete it without the user asking.
595 
596### SOW Content Hygiene
597 
598An active SOW is a current-state handoff, not an append-only transcript.
599 
600- When a plan, assumption, or decision is superseded, replace the stale guidance
601  with the current truth. Retain prior history only when it is needed to explain
602  a current constraint, approval, or rejected alternative.
603- Preserve user approvals, durable evidence, and material checkpoints, but
604  consolidate repeated review rounds and remove duplicated analysis.
605- The execution log SHOULD record meaningful state transitions, deviations, and
606  validation results. It SHOULD NOT reproduce the conversation or every review
607  nit.
608- Before completion, prune stale history and verify that another contributor can
609  determine the current target, remaining work, decisions, and evidence without
610  reconstructing chronology.
611 
612### SOW Completion And Merge
613 
614The successful terminal SOW status is `completed`.
615 
616When a SOW's work is ready to merge:
617 
6181. Finish implementation, docs, skills, validation, and follow-up mapping.
6192. Transfer all durable knowledge into project skills, docs, code, and tests
620   (and specs once specs are re-introduced to git). After this step, the SOW
621   body MUST hold nothing durable that is not captured elsewhere.
6223. Update the SOW to `Status: completed`.
623 
624SOW working files are never committed (they live under the gitignored
625`.agents/sow/q/`), so there is no "remove SOW from git before merge" step and no
626CI merge guard to clear. A completed SOW MAY stay in `.agents/sow/q/done/` as
627local history or be deleted locally at the user's discretion — never delete a
628local SOW working file without the user's request (see the deletion guard above).
629 
630### Enforcement
631 
632The SOW system is enforced by local audit tooling and CI:
633 
634- `.agents/sow/audit.sh` is the local consistency audit for SOW rules, the
635  local-only queue/spec layout, framework files, and sensitive-data scanning.
636- `.agents/sow/scan-sensitive.sh` is the shared sensitive-data scanner used by
637  local audit and CI.
638- `.agents/sow/worktree-link.sh` builds the local queues and links a worktree's
639  SOW working memory to its origin checkout.
640- `.github/workflows/sow.yml` rejects pull requests that commit SOW working
641  files or specs — anything under `.agents/sow/q/**`, `.agents/sow/specs/**`, or
642  a stray `.agents/sow/{active,pending,current,done}/SOW-*.md`. These paths are
643  local-only and gitignored; a hit means the file was force-added and MUST be
644  removed before merge.
645- The same workflow scans changed instruction, skill, and framework files for
646  raw sensitive data.
647 
648These checks are guards, not substitutes for the SOW Validation Gate. The
649assistant still owns transferring durable knowledge out of the SOW before
650merge.
651 
652### One SOW At A Time
653 
654Never execute multiple SOWs as one batch.
655 
656If work overlaps:
657 
658- coordinate through the relevant open PRs and issues;
659- merge or consolidate branches before implementation; or
660- split into separate SOWs and complete one before starting the next.
661 
662Progress 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.
663 
664### User Decisions
665 
666When user decisions are needed:
667 
6681. Present concrete evidence with files/lines or source references.
6692. Provide numbered options.
6703. Explain pros, cons, implications, and risks.
6714. Recommend one option with reasoning.
6725. 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.
673 
674### Review Materiality And Stop Condition
675 
676Review findings are leads until they are verified against the shipped code and
677its contracts.
678 
679- A shipping blocker MUST identify a production-reachable trigger, the violated
680  contract or invariant, the concrete consequence, and supporting code or test
681  evidence.
682- Failing required validation or an unmet explicit acceptance criterion is also
683  a shipping blocker, regardless of the reviewer's severity label.
684- An unreachable defensive scenario, optional refactor, style preference, or
685  speculative future risk MUST NOT be promoted to a blocker. Reject it with
686  evidence, or track it separately when it has independent value.
687- Optional test expansion, documentation polish, and maintainability suggestions
688  without a concrete current defect MUST NOT extend the review cycle by
689  themselves.
690- One complete review round is the default. Repeat the same full scope only when
691  a verified shipping blocker required a material change to shipped
692  implementation or behavior, or when the prior review could not assess the
693  complete change.
694- Stop when no verified shipping blocker remains. Reviewer unanimity, exact
695  readiness phrases, and zero optional suggestions are NOT required. Nits alone
696  MUST NOT keep a review cycle open.
697 
698### Followup Discipline
699 
700"Deferred" is not a terminal outcome.
701 
702Before a SOW can close, every valid deferred item must be:
703 
704- implemented in the current SOW; or
705- explicitly rejected as not worth doing, with evidence; or
706- represented by a GitHub issue linked from the current SOW or PR.
707 
708Pre-close, search the SOW for:
709 
710```text
711defer|later|follow-up|future|TODO|pending
712```
713 
714Map every remaining item to implemented, rejected, or tracked.
715 
716### Regressions
717 
718A regression is broken behavior discovered after a SOW's work merged, where the
719original claimed outcome is no longer true.
720 
721Because completed SOWs are not retained on `master`, a regression is handled as
722new work:
723 
7241. Open a new local SOW under `.agents/sow/q/active/`.
7252. In `## Requirements`, link the prior work: `Regresses: PR #NNNNN` and cite
726   any known commit, spec, issue, or test evidence.
7273. Run the normal Pre-Implementation Gate and Validation for the new SOW.
7284. Update the relevant spec, skill, doc, code, or test so durable memory reflects
729   current reality.
730 
731Do not attempt to resurrect or mutate a prior SOW.
732 
733### Validation Gate
734 
735A SOW cannot be completed until Validation records:
736 
737- acceptance criteria evidence;
738- 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;
739- 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;
740- tests or equivalent validation;
741- real-use evidence when a runnable path exists;
742- reviewer findings and how they were handled;
743- same-failure search results;
744- artifact maintenance gate for `AGENTS.md`, runtime project skills, specs, end-user/operator docs, end-user/operator skills, and SOW lifecycle;
745- local-only SOW layout respected: no SOW working file or spec was committed
746  (they stay under the gitignored `.agents/sow/q/` and `.agents/sow/specs/`);
747- spec update or specific reason no spec update was needed;
748- project skill update or specific reason no skill update was needed;
749- end-user/operator docs update or evidence-backed reason none were affected;
750- end-user/operator skill update or evidence-backed reason none were affected by docs/spec changes;
751- lessons extracted or specific reason there were none;
752- workflow-friction triage: each recorded `Workflow Friction & Rule Gaps` note resolved to a rule update (`AGENTS.md`, project skill, spec, or SOW template), an evidence-backed rejection, or a tracked follow-up (or an explicit "none arose");
753- follow-up mapping.
754 
755Generic "N/A" is invalid.
756 
757### Artifact Maintenance Gate
758 
759Every SOW close must explicitly record whether each durable artifact class was updated or why no update was needed:
760 
761- `AGENTS.md` - workflow, responsibility, local framework, project-wide guardrails.
762- Runtime project skills - `.agents/skills/project-*/SKILL.md` for HOW to work here.
763- Specs - `.agents/sow/specs/` for WHAT the project does.
764- End-user/operator docs - README, docs site, runbooks, published guides, help text, or other human-facing documentation.
765- End-user/operator skills - output/reference skills copied or consumed outside normal repo work.
766- SOW lifecycle - local-only SOW under `.agents/sow/q/` (never committed), durable memory transfer, deferred work tracked as GitHub issues, and regressions handled as new linked SOWs.
767 
768This 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.
769 
770### Specs
771 
772Specs are memory of WHAT this project does.
773 
774Specs currently live under `.agents/sow/specs/` as **local-only** memory
775(gitignored, not committed). They are being reorganized and will be
776re-introduced to git later as a deliberate decision; until then they are
777per-developer local memory, shared across worktrees by
778`.agents/sow/worktree-link.sh`. Durable contracts that must be shared with the
779team right now belong in project skills, docs, code, and tests.
780 
781This repository is bootstrapped incrementally. The existing source tree and public documentation remain the primary ground truth. Specs under `.agents/sow/specs/` capture durable project decisions, cross-cutting behavioral rules, and area-specific contracts as they are worked.
782 
783`.agents/sow/specs/` stays flat until scale proves hierarchy is needed. Use
784`<domain>-<topic>.md` names, one durable contract or cross-cutting rule per file,
785and update `.agents/sow/specs/README.md` in the same change. Do not split specs
786by repository path; specs are organized by contract ownership, not source-file
787location.
788 
789Update specs when shipped work changes:
790 
791- product behavior;
792- public contracts;
793- collector behavior;
794- APIs and schemas;
795- data formats;
796- alerting semantics;
797- packaging or deployment behavior;
798- operational guarantees;
799- known edge cases.
800 
801Specs describe current reality, not aspiration. If specs and code disagree, record the discrepancy in the active SOW and resolve or track it.
802 
803### Project Skills
804 
805Project skills are memory of HOW to work here.
806 
807Runtime input project skills should live under `.agents/skills/*/SKILL.md`. Before non-trivial work, inspect those skill descriptions and load every matching runtime skill.
808 
809Output/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.
810 
811### Public skill convention (`docs/netdata-ai/skills/`)
812 
813End-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.
814 
815Public skills are for operators and end-users. They may teach users how to
816query Netdata Cloud, query Agents, inspect metrics/logs/topology/alerts, or run
817safe operational commands. They must not contain developer-contract validation,
818schema migration plans, producer authoring workflows, UI adapter work,
819aggregator implementation notes, SOW handoff instructions, fixture maintenance,
820PR-review tasks, or codebase-internal implementation recipes.
821 
822Developer-facing skills must live under `.agents/skills/`, preferably with a
823`project-` prefix when they are runtime input for repository work. If a workflow
824requires reading source files, updating schemas, validating fixtures, changing
825collectors/producers, or coordinating frontend/backend/aggregator code, it is a
826project developer skill, not a public skill.
827 
828Skill verification harness inputs are not public skill content. Keep seed
829questions, grader rubrics, runner scripts, and transcript-generation prompts
830under `.agents/skill-verification/<skill>/`, not under
831`docs/netdata-ai/skills/<skill>/`.
832 
833Each 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>`.
834 
835Public-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).
836 
837Public-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.
838 
839### How-tos catalog rule
840 
841Each 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.
842 
843The how-to rule does not override audience boundaries. If the analysis produced
844a developer validation recipe, put it in the matching `.agents/skills/` project
845skill and update that skill's index instead of adding it under
846`docs/netdata-ai/skills/`.
847 
848The 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.
849 
850### Project Skills Index
851 
852Runtime input skills:
853 
854- `.agents/skills/project-snmp-profiles-authoring/`
855  Trigger: editing SNMP profile YAMLs, topology SNMP profiles, ddsnmp profile parsing, or SNMP profile-format documentation.
856  Purpose: require MIB `MAX-ACCESS` checks and index-derived extraction for `not-accessible` INDEX objects.
857 
858- `.agents/skills/project-snmp-trap-profiles-authoring/`
859  Trigger: editing SNMP trap profile YAMLs under `src/go/plugin/go.d/config/go.d/snmp.trap-profiles/`, the trap profile-format documentation, the `src/go/cmd/snmptrapprofilegen/` Go helper, or running a regeneration of the OOB trap profile pack.
860  Purpose: enforce the closed 8-category / 8-severity taxonomy, the file-scoped `varbinds:` table pattern, cardinality discipline on `labels:`, and stock/operator separation. Documents the regeneration recipe.
861 
862- `.agents/skills/project-writing-collectors/`
863  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.
864  Status: live. Updates that close gaps or fix outdated pointers must ship in the same PR that exposed the issue.
865 
866- `.agents/skills/project-create-topology/`
867  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.
868  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.
869 
870- `.agents/skills/project-writing-go-modules-framework-v2/`
871  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.
872  Purpose: mirror maintainer-preferred framework V2 patterns from accepted collectors so new or migrated modules blend with repository style.
873 
874- `.agents/skills/integrations-lifecycle/`
875  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.
876  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.
877 
878- `.agents/skills/learn-site-structure/`
879  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.
880  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.
881- `.agents/skills/learn-pr-preview/`
882  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.
883  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.
884- `.agents/skills/query-agent-events/`
885  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.
886  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.
887 
888- `.agents/skills/mirror-netdata-repos/`
889  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.
890  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.
891 
892- `.agents/skills/coverity-audit/`
893  Trigger: Coverity Scan defect triage for this repository.
894  Status: live.
895 
896- `.agents/skills/sonarqube-audit/`
897  Trigger: SonarCloud findings triage for this repository.
898  Status: live.
899 
900- `.agents/skills/graphql-audit/`
901  Trigger: GitHub Code Scanning/CodeQL triage for this repository.
902  Status: live.
903 
904- `.agents/skills/pr-reviews/`
905  Trigger: PR comment and review iteration work for this repository.
906  Status: live.
907 
908- `.agents/skills/codacy-audit/`
909  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.
910  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.
911 
912Public skills (canonical under `docs/netdata-ai/skills/<name>/`; relative symlinks at `.agents/skills/<name>`):
913 
914- `docs/netdata-ai/skills/query-netdata-cloud/`
915  Trigger: querying Netdata Cloud REST API -- metrics, logs (systemd-journal), alerts, generic Function calls on a node.
916  Symlink: `.agents/skills/query-netdata-cloud` -> `../../docs/netdata-ai/skills/query-netdata-cloud`.
917  Status: live. SKILL.md plus per-domain guides (`query-metrics.md`, `query-logs.md`, `query-alerts.md`, `query-functions.md`).
918 
919- `docs/netdata-ai/skills/query-netdata-agents/`
920  Trigger: querying Netdata Agents directly on port 19999, including auto-mint of per-agent bearer tokens from a Cloud token.
921  Symlink: `.agents/skills/query-netdata-agents` -> `../../docs/netdata-ai/skills/query-netdata-agents`.
922  Status: live. SKILL.md plus `scripts/_lib.sh` helpers (`agents_resolve_bearer`, `agents_call_function`, `agents_netdata_prefix`).
923 
924- `docs/netdata-ai/skills/query-snmp-traps/`
925  Trigger: querying SNMP trap logs through Netdata Cloud or directly from a Netdata Agent; use for trap journal entries, severities, categories, senders, deduplication summaries, `TRAP_*` fields, and `TRAP_JSON` varbind searches.
926  Symlink: `.agents/skills/query-snmp-traps` -> `../../docs/netdata-ai/skills/query-snmp-traps`.
927  Status: live. SKILL.md plus `how-tos/INDEX.md` and seeded operator how-tos.
928 
929Output/reference skills:
930 
931- `docs/netdata-ai/skills/`
932  Consumer: downstream assistants and users of Netdata AI skill artifacts.
933  Update when: public/operator AI skill docs, examples, commands, schemas, or workflows change.
934 
935- `src/ai-skills/`
936  Consumer: downstream assistants and users of generated or source AI skill artifacts when this tree is present in the working copy.
937  Update when: generated/source AI skill behavior, tests, examples, commands, schemas, or workflows change.
938 
939### Project-specific commands
940 
941- This bootstrap pass does not define a full-project command matrix for the monolith.
942- Use the narrowest existing command that validates the changed subsystem.
943- Do not claim full-project validation from a narrow subsystem command.
944- 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.
945 
946### Go test style
947 
948- Prefer table-driven tests using `map[string]struct{}` keyed by test-case name
949  when cases share setup and assertion shape.
950- Use separate test functions only when setup or assertions are materially
951  different.
952- Prefer map keys over a `name` field in `[]struct{}` so case names are
953  prominent and order-independent.
954 
955### Project-specific overrides
956 
957All 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.
958 
959## Collector Consistency Requirements
960 
961When working on collectors, runtime behavior, metrics, charts, configuration,
962alerts, taxonomy, and generated documentation MUST stay consistent in one PR.
963The detailed collector consistency checklist and CI enforcement notes live in
964`.agents/skills/integrations-lifecycle/consistency.md`.
965 
966## C code
967- gcc, clang, glibc and muslc
968- libnetdata.h includes everything in libnetdata (just a couple of exceptions) so there is no need to include individual libnetdata headers
969- Functions with 'z' suffix (mallocz, reallocz, callocz, strdupz, etc.) handle allocation failures automatically by calling fatal() to exit Netdata
970- The freez() function accepts NULL pointers without crashing
971- Resuable, generic, module agnostic code, goes to libnetdata
972- Double linked lists are managed with DOUBLE_LINKED_LIST_* macros
973- json-c for json parsing
974- buffer_json_* for manual json generation
975 
976## Naming Conventions
977- "Netdata Agent" (capitalized) when referring to the product
978- "`netdata`" (lowercase, code-formatted) when referring to the process
979- See DICTIONARY.md for precise terminology
980 
981## Local-only working directory
982 
983`/.local/` at the repo root is gitignored and reserved for per-user runtime
984artifacts: audit reports, fetched API data, scratch notes, queue files,
985intermediate triage decisions. Agents writing skill output should default to
986`<repo-root>/.local/audits/<topic>/...` -- where `<topic>` is the skill
987name with any trailing `-audit` suffix removed (so `coverity-audit/`
988writes under `coverity/`, `pr-reviews/` writes under `pr-reviews/`).
989 
990Convention:
991- `/.local/audits/coverity/`  - Coverity raw fetches, per-defect details, triage decisions
992- `/.local/audits/sonarqube/` - Sonar finding queues, FP comment templates
993- `/.local/audits/graphql/`   - GitHub Code Scanning fetches and dismissals
994- `/.local/audits/pr-reviews/`- Per-PR comment / review caches
995 
996Naming: each skill `<topic>-audit/` writes to `.local/audits/<topic>/`
997(the `-audit` suffix is dropped from the directory name so the URL-style
998path stays short). Skills without the `-audit` suffix keep their full
999name (e.g. `pr-reviews/` writes to `.local/audits/pr-reviews/`). When
1000adding a new skill, follow this convention.
1001 
1002Nothing under `/.local/` is committed. Treat the directory as ephemeral
1003between users and machines, not as a shared source of truth.
1004 
1005## Per-user secrets via `.env`
1006 
1007`/.env` at the repo root is gitignored and holds per-user secrets and
1008endpoint configuration consumed by skill scripts: API tokens, session
1009cookies, project keys. Never commit secrets; never hard-code tokens in scripts.
1010 
1011**Setup**: copy `<repo>/.env.template` to `<repo>/.env` and fill in
1012the keys you need.
1013 
1014**Reference**: `<repo>/.agents/ENV.md` is the single canonical guide
1015covering every key -- what it is, where to find the value, sample
1016format, common mistakes, and which skills require it. When a script
1017errors with `<KEY> is empty`, check `.agents/ENV.md` for that key.
1018