Two files, one repository

netdata/netdata ships 1 format across 3 indexed files. The question worth asking is whether the second one says anything the first does not.

A · AGENTS.md · 8376 words B · src/go/AGENTS.md · 1793 words

What each file covers, counted
Dimension	Shared	Only in A	Only in B	Overlap
Sections	1	37	12	2%
Commands	0	1	7	0%
Section tags	6	4	3	46%

What each file covers

Sections

1 shared · 37 only in A · 12 only in B

− AGENTS.md
− Goals
− Requirement Language
− SOW System
− Roles
− Required First Checks
− Git Worktrees
− Sensitive Data In Durable Artifacts
− Durable AI-Facing Artifact Formatting
− Open-Source Reference Evidence
− Pre-Implementation Gate
− When A SOW Is Required
− SOW Locations And Naming
− Local SOW Parking
− SOW Content Hygiene
− SOW Completion And Merge
− Enforcement
− One SOW At A Time
− User Decisions
− Review Materiality And Stop Condition
− Followup Discipline
− Regressions
− Validation Gate
− Artifact Maintenance Gate
− Specs
− Project Skills
− Public skill convention (`docs/netdata-ai/skills/`)
− How-tos catalog rule
− Project Skills Index
− Project-specific commands
− Go test style
− Project-specific overrides
− Collector Consistency Requirements
− C code
− Naming Conventions
− Local-only working directory
− Per-user secrets via `.env`
+ Go Area Instructions
+ Sensitive Data
+ Task Routing
+ New go.d Collector Rules
+ go.d V1-to-V2 Migration Rules
+ Core Framework Change Gate
+ Evidence Before Complexity
+ Hot-Path And Benchmark Discipline
+ Go Formatting
+ Validation For Go Changes
+ Go Review And Reachability
+ Batching And Review
Mandatory Development Principles

Commands

0 shared · 1 only in A · 7 only in B

− git rev-parse --show-toplevel
+ go test -bench
+ git stash
+ go install github.com/segmentio/golines@latest
+ go run ./tools/expandstructs <paths>
+ go/format
+ go vet ./<pkg>/
+ go test -count=1 ./<pkg>/...

Section tags

6 shared · 4 only in A · 3 only in B

− architecture
− testing-strategy
− security
− docs
+ setup
+ database
+ performance
test
lint-format
code-style
git-pr
do-not
agent-behaviour

Line diff

+191 added−982 removed36 unchanged3.5% identical

netdata/netdata · AGENTS.md

@@ −1 @@

1# AGENTS.md

3## Goals

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.

7Work in this repository must prioritize root-cause understanding, correctness, performance, maintainability, portability, security, and consistency with existing project conventions.

9## Requirement Language

11This repository uses RFC-style requirement language:

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.

20CRITICAL RULES:

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.

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?

283. Do not duplicate code.

29 First check if similar code already exists and reuse it.

31## Mandatory Development Principles

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.

37**Core (read first; the bullets under each principle are the authority for forks

38and edge cases):**

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.

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 defines the target (what 'done' means)")

266 B("2. Plan before non-trivial work establish the target + steps; user approves real forks")

267 C("3. Scope discipline 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

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

netdata/netdata · src/go/AGENTS.md

@@ +1 @@

1# Go Area Instructions

3This file routes Go-specific work under `src/go/`. Repository-wide rules in

4the repo-root `AGENTS.md` still apply. More specific `AGENTS.md` files under

5subdirectories override this file for that subtree. Paths below are

6repo-relative unless stated otherwise.

8## Sensitive Data

10The repo-root `AGENTS.md` sensitive-data policy applies in full to all durable

11Go artifacts, including code comments, docs, specs, skills, and SOWs.

13## Mandatory Development Principles

15The repo-root clean-end-state and scope-discipline principles are mandatory and

16apply in full. For Go work, enforce them explicitly when changing collectors,

17framework code, runtime behavior, `metrix`, chart templates, Functions,

18topology, tests, specs, or skills.

20- You MUST prefer the clean framework or collector shape over preserving a

21 smaller diff.

22- You MUST re-check scope after each coherent batch. If a separate framework fix,

23 collector cleanup, or docs rewrite becomes necessary, split it into its own

24 step or submit it independently before continuing.

25- You SHOULD use RFC-style requirement language (`MUST`, `SHOULD`, `MAY`) in

26 Go-area specs, skills, and instructions when documenting enforceable rules.

28## Task Routing

30| Work area | Start here | Notes |

31|---|---|---|

32| New go.d collector | `src/go/plugin/go.d/docs/how-to-write-a-collector.md` | New go.d collectors use framework V2. |

33| Migrating go.d V1 collector to V2 | `src/go/plugin/go.d/docs/migrate-v1-to-v2.md` | Preserve public contracts unless a breaking change is explicitly approved. |

34| go.d V2 implementation details | `.agents/skills/project-writing-go-modules-framework-v2/SKILL.md`, `src/go/pkg/metrix/README.md`, `src/go/plugin/framework/charttpl/README.md`, `src/go/plugin/framework/chartengine/README.md` | Use the skill for maintainer style and the READMEs for framework API contracts. Editing `metrix` or framework packages is framework-gated work. |

35| go.d helper packages | `src/go/plugin/go.d/docs/helper-packages.md` | Check existing HTTP, config-option, matcher, logger, socket, command, SQL, ping, log-file, and cloud-auth helpers before adding custom plumbing. |

36| Collector design across plugins | `.agents/skills/project-writing-collectors/SKILL.md` | Use for NIDL, cardinality, obsoletion, missing data, logging, and config discipline. |

37| Integration metadata, taxonomy, generated docs | `.agents/skills/integrations-lifecycle/SKILL.md`, `.agents/skills/integrations-lifecycle/consistency.md` | Source artifacts and generated artifacts MUST stay synchronized. |

38| IBM.d work | `src/go/plugin/ibm.d/AGENTS.md` | IBM.d has a generator-driven workflow; go.d V2 layout rules MUST NOT be applied there. |

39| Function handlers | `src/go/plugin/framework/functions/README.md`, `src/go/tools/functions-validation/README.md` | Collector Functions SHOULD be isolated behind narrow dependencies. |

40| Topology payloads | `.agents/skills/project-create-topology/SKILL.md`, `.agents/skills/project-create-topology/topology-function-schema.md`, `src/go/pkg/topology/v1` | New topology producers MUST use the production `netdata.topology.v1` schema. |

41| Host scopes / vnodes | `.agents/skills/project-writing-go-modules-framework-v2/go-v2-host-scope.md`, `src/go/plugin/go.d/collector/azure_monitor/` | Use host scopes when one job emits metrics for resources that SHOULD appear as separate Netdata nodes. |

42| Matchers/selectors | `src/go/pkg/matcher/README.md` | Prefer existing matcher APIs over custom selector grammars. |

43| Core framework changes | `src/go/plugin/framework/docs/changing-framework-code.md` and `Core Framework Change Gate` below | The applicable approval tier MUST be satisfied before implementation. |

45## New go.d Collector Rules

47- New go.d collectors MUST implement `collectorapi.CollectorV2` from

48 `src/go/plugin/framework/collectorapi/collector.go` and register via

49 `CreateV2`. This includes writing metrics through `metrix.CollectorStore` and

50 providing `ChartTemplateYAML()`.

51- New go.d collector guidance MUST NOT teach or copy the V1

52 `Collect() map[string]int64` pattern for new

53 collectors.

54- Collector runtime, metric, chart, config, alert, taxonomy, and documentation

55 changes MUST follow the repository collector consistency policy. The detailed

56 checklist lives in `.agents/skills/integrations-lifecycle/consistency.md`.

57- Public config options SHOULD be added only when they represent a real

58 operator decision. Implementation tuning such as page sizes, scan windows,

59 retry limits, and cadence SHOULD use internal constants unless user control is

60 clearly justified.

61- New collectors MUST NOT inherit unsupported config knobs from adjacent

62 collectors or generic templates.

63- Collector-local globals, singletons, adapters, caches, or glue layers that

64 substitute for missing shared framework/helper capabilities are

65 framework-scope work and MUST follow

66 `src/go/plugin/framework/docs/changing-framework-code.md` before

67 implementation.

68- If the collector exposes Functions, put Function code in a dedicated

69 `<name>func/` package behind a narrow `Deps` interface declared in that

70 package. The Function package MUST NOT import the collector package or hold

71 `*Collector`.

72- If the collector emits topology, it MUST use `netdata.topology.v1`, the Go

73 producer model in `src/go/pkg/topology/v1`, and validate payloads against

74 `src/plugins.d/FUNCTION_TOPOLOGY_SCHEMA.json`. New producers MUST NOT use

75 legacy topology payloads.

76- If one job emits metrics for multiple remote resources that SHOULD appear as

77 separate Netdata nodes, it MUST use V2 host scopes/vnodes.

79## go.d V1-to-V2 Migration Rules

81- V1-to-V2 migrations MUST start with

82 `src/go/plugin/go.d/docs/migrate-v1-to-v2.md`.

83- Migrations MUST preserve chart IDs, contexts, dimensions, config keys,

84 defaults, health lookups, metadata, taxonomy, stock config, and service

85 discovery behavior unless the user explicitly approves a breaking change.

86- Compatibility migration SHOULD be separate from enrichment such as new labels,

87 host scopes, topology, Functions, or config expansion.

88- Completed migrations MUST NOT keep a runtime V1-to-V2 bridge. Temporary V1

89 logic can be used during development for parity checks, but it MUST be

90 removed from the final migrated collector.

92## Core Framework Change Gate

94Changes to shared Go framework code (`metrix`, `chartengine`, `charttpl`, the job

95runtime, `collectorapi`) are high-blast-radius: this code runs in EVERY collector,

96most of it on the per-cycle hot path. Before changing these areas, read

97`src/go/plugin/framework/docs/changing-framework-code.md` — the canonical owner of

98the framework-change scope list, required design note, validation expectations, and

99artifact checks. Implementation MUST NOT begin until that guide's applicable

100approval tier is satisfied.

101

102- Clean extension over glue: prefer a clean framework extension over

103 collector-local globals, singletons, adapters, or private-package coupling when

104 the problem is general.

105- Behavior preservation: when a framework change also touches shipped collectors,

106 preserve their observable behavior (chart IDs, contexts, dimensions, config keys,

107 defaults) and validate representative consumers, not only the framework package

108 (see "Validation For Go Changes").

109- metrix contract: `metrix` keeps one descriptor per metric NAME, resolved

110 atomically at commit and bounded — a name idle past `expireAfterSuccessCycles +

111 descriptorGraceCycles` is evicted, and re-registers cleanly afterward. A consumer

112 that caches per-name state across cycles MUST couple its lifetime to the optional

113 `metrix.DescriptorRetention` accessor. See `src/go/pkg/metrix/README.md`

114 ("Descriptor Lifecycle and Retention").

115

116## Evidence Before Complexity

117

118Readability and maintainability are the default for Go control-plane and

119framework code. Complexity needs evidence; a plausible future problem is not a

120requirement.

121

122- Code MUST NOT introduce population, byte, concurrency, queue, retry, or

123 backpressure limits, nor add accounting, scheduling, pooling, caching, custom

124 data structures, or lifecycle machinery, unless the design follows from a

125 concrete correctness, liveness, protocol, compatibility, or security contract,

126 a documented scale requirement, or a measured production workload.

127- The justification MUST identify the input or producer, the failure being

128 prevented, the expected scale, and why simpler slices, maps, channels, or

129 direct ownership are insufficient. A round number, hypothetical abuse case,

130 or benchmark in isolation is not evidence of a product requirement.

131- Protocol- and security-derived bounds MUST remain tied to their source with a

132 concise rationale and boundary tests. Do not generalize one per-item bound

133 into an aggregate process policy without separate evidence.

134- When a limit has no valid requirement, remove the policy and its coupled

135 machinery. Raising it to an effectively unreachable value is not the clean

136 end state.

137- Do not add allocation- or latency-oriented complexity until the path is shown

138 to be hot by its production frequency, a profile, or representative benchmark.

139 Once a path is established as hot, follow "Hot-Path And Benchmark Discipline."

140

141## Hot-Path And Benchmark Discipline

142

143metrix commit/collect, per-sample/per-write, and per-cycle code are hot paths that

144run for every collector on every cycle.

145

146- Before/after REQUIRED: a hot-path change MUST include before/after

147 `go test -bench` numbers (use `git stash` for the "before" baseline), not just

148 "tests pass".

149- Allocation count is the gate: assert allocs stay within the intended envelope

150 (e.g. a sparse commit stays ~O(touched), never O(retained)). `ns/op` is a

151 dev-machine trend indicator, NOT a CI gate — label it as such inline, and never

152 record a personal name in the file.

153- State the complexity envelope explicitly (e.g. "commit is O(live-series +

154 touched + distinct-names)") and prove the change did not introduce an

155 O(samples)/O(retained)/O(n^2) regression.

156- Keep bench comments in sync with the code they measure, in the same change, with

157 self-contained wording (no round/session references).

158

159## Go Formatting

160

161`gofmt` and `goimports` are the baseline. This repository additionally

162RECOMMENDS (not CI-enforced) a fuller formatting pipeline that keeps line

163wrapping tight and keyed struct literals readable:

164

1651. `golines -m 120 -t 4 -w <paths>` — join over-wrapped signatures/calls and

166 split lines past ~120 columns. SKIP this step if `golines` is not installed

167 (`go install github.com/segmentio/golines@latest`).

1682. `go run ./tools/expandstructs <paths>` — put each keyed struct-literal field

169 on its own line. Formats source in-process with `go/format`.

1703. `goimports -w <paths>` — order imports.

171

172Conventions this encodes:

173

174- Keep a signature / call / return / composite literal on ONE line when it fits

175 within ~120 columns; wrap only when it does not.

176- Keyed struct literals of a named type go ONE field per line.

177

178`gofmt`/`goimports` cannot express these two rules, so they are not CI-enforced;

179re-run the pipeline if code drifts. See `tools/expandstructs/README.md`.

180

181## Validation For Go Changes

182

183Run the narrowest command that actually exercises the change; do not claim

184full-project validation from a narrow one.

185

186- Always: formatted per "Go Formatting" above (at minimum `gofmt` clean) and

187 `go vet ./<pkg>/` clean.

188- Unit: `go test -count=1 ./<pkg>/...` for every package you touched.

189- Concurrency: add `-race` for concurrency-sensitive packages (`metrix`, the job

190 runtime, `plugin/agent/jobmgr`).

191- Shared framework code: ALSO build and test representative consumers (a couple of

192 real collectors) plus `-race ./plugin/agent/jobmgr/`, so a framework change is

193 proven against real users, not just its own package.

194- Reproduce a reviewer-reported bug as a FAILING test first, then fix to green

195 (repo-wide working-style rule).

196- Prefer `testify/require` for test prerequisites and `testify/assert` for

197 comparisons when applicable. Use `t.Fatal` or `t.Fatalf` directly when it

198 represents genuine test control flow or has no clearer assertion equivalent.

199

200## Go Review And Reachability

201

202- Start review at the declared interface and the shipped production adapter.

203 Inspect implementation internals behind that boundary only when the contract

204 leaves relevant behavior unspecified or concrete evidence points across it.

205 Do not make a caller responsible for arbitrary private behavior of every

206 implementation.

207- Before deleting Go code as unused, check all relevant reference forms:

208 selector reads and writes, struct literals, constructor arguments, method

209 values, interface satisfaction, reflection, build-tagged and platform files,

210 generated code, and test-only injection. A call-site-only search is not proof

211 of unreachability.

212

213## Batching And Review

214

215- Changes SHOULD stay atomic. If a collector or framework task grows, split it

216 into coherent batches before review becomes difficult.

217- At every batch boundary, you MUST re-evaluate clean end state and scope. If

218 the branch now contains independent work, pause and submit that work

219 separately or defer it before continuing.

220- Changes MUST NOT mix framework changes, collector migrations, and

221 integration-doc regeneration unless they are required for one coherent

222 behavior change.

223- Multi-round review: checkpoint-commit each validated change before its review and

224 squash at PR time; if findings keep clustering in one subsystem (~2-3 rounds),

225 stop patching and fix the class (repo-wide review rules).

226- For Go test style, follow the repo-root `AGENTS.md` "Go test style" section.

227

@@ −1 +1 @@

1−# AGENTS.md

1+# Go Area Instructions

3−## Goals

3+This file routes Go-specific work under `src/go/`. Repository-wide rules in

4+the repo-root `AGENTS.md` still apply. More specific `AGENTS.md` files under

5+subdirectories override this file for that subtree. Paths below are

6+repo-relative unless stated otherwise.

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.

8+## Sensitive Data

7−Work in this repository must prioritize root-cause understanding, correctness, performance, maintainability, portability, security, and consistency with existing project conventions.

10+The repo-root `AGENTS.md` sensitive-data policy applies in full to all durable

11+Go artifacts, including code comments, docs, specs, skills, and SOWs.

812

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−

3113 ## Mandatory Development Principles

3214

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.

15+The repo-root clean-end-state and scope-discipline principles are mandatory and

16+apply in full. For Go work, enforce them explicitly when changing collectors,

17+framework code, runtime behavior, `metrix`, chart templates, Functions,

18+topology, tests, specs, or skills.

3619

37−**Core (read first; the bullets under each principle are the authority for forks

38−and edge cases):**

20+- You MUST prefer the clean framework or collector shape over preserving a

21+ smaller diff.

22+- You MUST re-check scope after each coherent batch. If a separate framework fix,

23+ collector cleanup, or docs rewrite becomes necessary, split it into its own

24+ step or submit it independently before continuing.

25+- You SHOULD use RFC-style requirement language (`MUST`, `SHOULD`, `MAY`) in

26+ Go-area specs, skills, and instructions when documenting enforceable rules.

3927

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.

28+## Task Routing

5729

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.

30+| Work area | Start here | Notes |

31+|---|---|---|

32+| New go.d collector | `src/go/plugin/go.d/docs/how-to-write-a-collector.md` | New go.d collectors use framework V2. |

33+| Migrating go.d V1 collector to V2 | `src/go/plugin/go.d/docs/migrate-v1-to-v2.md` | Preserve public contracts unless a breaking change is explicitly approved. |

34+| go.d V2 implementation details | `.agents/skills/project-writing-go-modules-framework-v2/SKILL.md`, `src/go/pkg/metrix/README.md`, `src/go/plugin/framework/charttpl/README.md`, `src/go/plugin/framework/chartengine/README.md` | Use the skill for maintainer style and the READMEs for framework API contracts. Editing `metrix` or framework packages is framework-gated work. |

35+| go.d helper packages | `src/go/plugin/go.d/docs/helper-packages.md` | Check existing HTTP, config-option, matcher, logger, socket, command, SQL, ping, log-file, and cloud-auth helpers before adding custom plumbing. |

36+| Collector design across plugins | `.agents/skills/project-writing-collectors/SKILL.md` | Use for NIDL, cardinality, obsoletion, missing data, logging, and config discipline. |

37+| Integration metadata, taxonomy, generated docs | `.agents/skills/integrations-lifecycle/SKILL.md`, `.agents/skills/integrations-lifecycle/consistency.md` | Source artifacts and generated artifacts MUST stay synchronized. |

38+| IBM.d work | `src/go/plugin/ibm.d/AGENTS.md` | IBM.d has a generator-driven workflow; go.d V2 layout rules MUST NOT be applied there. |

39+| Function handlers | `src/go/plugin/framework/functions/README.md`, `src/go/tools/functions-validation/README.md` | Collector Functions SHOULD be isolated behind narrow dependencies. |

40+| Topology payloads | `.agents/skills/project-create-topology/SKILL.md`, `.agents/skills/project-create-topology/topology-function-schema.md`, `src/go/pkg/topology/v1` | New topology producers MUST use the production `netdata.topology.v1` schema. |

41+| Host scopes / vnodes | `.agents/skills/project-writing-go-modules-framework-v2/go-v2-host-scope.md`, `src/go/plugin/go.d/collector/azure_monitor/` | Use host scopes when one job emits metrics for resources that SHOULD appear as separate Netdata nodes. |

42+| Matchers/selectors | `src/go/pkg/matcher/README.md` | Prefer existing matcher APIs over custom selector grammars. |

43+| Core framework changes | `src/go/plugin/framework/docs/changing-framework-code.md` and `Core Framework Change Gate` below | The applicable approval tier MUST be satisfied before implementation. |

12944

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.

45+## New go.d Collector Rules

17446

175−2. **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.

47+- New go.d collectors MUST implement `collectorapi.CollectorV2` from

48+ `src/go/plugin/framework/collectorapi/collector.go` and register via

49+ `CreateV2`. This includes writing metrics through `metrix.CollectorStore` and

50+ providing `ChartTemplateYAML()`.

51+- New go.d collector guidance MUST NOT teach or copy the V1

52+ `Collect() map[string]int64` pattern for new

53+ collectors.

54+- Collector runtime, metric, chart, config, alert, taxonomy, and documentation

55+ changes MUST follow the repository collector consistency policy. The detailed

56+ checklist lives in `.agents/skills/integrations-lifecycle/consistency.md`.

57+- Public config options SHOULD be added only when they represent a real

58+ operator decision. Implementation tuning such as page sizes, scan windows,

59+ retry limits, and cadence SHOULD use internal constants unless user control is

60+ clearly justified.

61+- New collectors MUST NOT inherit unsupported config knobs from adjacent

62+ collectors or generic templates.

63+- Collector-local globals, singletons, adapters, caches, or glue layers that

64+ substitute for missing shared framework/helper capabilities are

65+ framework-scope work and MUST follow

66+ `src/go/plugin/framework/docs/changing-framework-code.md` before

67+ implementation.

68+- If the collector exposes Functions, put Function code in a dedicated

69+ `<name>func/` package behind a narrow `Deps` interface declared in that

70+ package. The Function package MUST NOT import the collector package or hold

71+ `*Collector`.

72+- If the collector emits topology, it MUST use `netdata.topology.v1`, the Go

73+ producer model in `src/go/pkg/topology/v1`, and validate payloads against

74+ `src/plugins.d/FUNCTION_TOPOLOGY_SCHEMA.json`. New producers MUST NOT use

75+ legacy topology payloads.

76+- If one job emits metrics for multiple remote resources that SHOULD appear as

77+ separate Netdata nodes, it MUST use V2 host scopes/vnodes.

23278

233−3. **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.

79+## go.d V1-to-V2 Migration Rules

25380

254−**Flow diagrams (human reading aid, non-normative):** the bullets above are

255−authoritative; the diagrams below summarize the flow for human readers and MUST

256−be kept in sync when the principles change.

81+- V1-to-V2 migrations MUST start with

82+ `src/go/plugin/go.d/docs/migrate-v1-to-v2.md`.

83+- Migrations MUST preserve chart IDs, contexts, dimensions, config keys,

84+ defaults, health lookups, metadata, taxonomy, stock config, and service

85+ discovery behavior unless the user explicitly approves a breaking change.

86+- Compatibility migration SHOULD be separate from enrichment such as new labels,

87+ host scopes, topology, Functions, or config expansion.

88+- Completed migrations MUST NOT keep a runtime V1-to-V2 bridge. Temporary V1

89+ logic can be used during development for parity checks, but it MUST be

90+ removed from the final migrated collector.

25791

258−<details>

259−<summary>Show per-principle flow diagrams</summary>

92+## Core Framework Change Gate

26093

261−How the three principles connect (lifecycle order):

94+Changes to shared Go framework code (`metrix`, `chartengine`, `charttpl`, the job

95+runtime, `collectorapi`) are high-blast-radius: this code runs in EVERY collector,

96+most of it on the per-cycle hot path. Before changing these areas, read

97+`src/go/plugin/framework/docs/changing-framework-code.md` — the canonical owner of

98+the framework-change scope list, required design note, validation expectations, and

99+artifact checks. Implementation MUST NOT begin until that guide's applicable

100+approval tier is satisfied.

262101

263−```mermaid

264−flowchart LR

265− A("1. Clean end state defines the target (what 'done' means)")

266− B("2. Plan before non-trivial work establish the target + steps; user approves real forks")

267− C("3. Scope discipline stay on the target while executing each step")

268− A --> B --> C

269− C -->|re-evaluate vs target| A

270−```

102+- Clean extension over glue: prefer a clean framework extension over

103+ collector-local globals, singletons, adapters, or private-package coupling when

104+ the problem is general.

105+- Behavior preservation: when a framework change also touches shipped collectors,

106+ preserve their observable behavior (chart IDs, contexts, dimensions, config keys,

107+ defaults) and validate representative consumers, not only the framework package

108+ (see "Validation For Go Changes").

109+- metrix contract: `metrix` keeps one descriptor per metric NAME, resolved

110+ atomically at commit and bounded — a name idle past `expireAfterSuccessCycles +

111+ descriptorGraceCycles` is evicted, and re-registers cleanly afterward. A consumer

112+ that caches per-name state across cycles MUST couple its lifetime to the optional

113+ `metrix.DescriptorRetention` accessor. See `src/go/pkg/metrix/README.md`

114+ ("Descriptor Lifecycle and Retention").

271115

272−1. Clean end state over less churn:

116+## Evidence Before Complexity

273117

274−```mermaid

275−flowchart 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−```

118+Readability and maintainability are the default for Go control-plane and

119+framework code. Complexity needs evidence; a plausible future problem is not a

120+requirement.

301121

302−2. Plan before non-trivial work:

122+- Code MUST NOT introduce population, byte, concurrency, queue, retry, or

123+ backpressure limits, nor add accounting, scheduling, pooling, caching, custom

124+ data structures, or lifecycle machinery, unless the design follows from a

125+ concrete correctness, liveness, protocol, compatibility, or security contract,

126+ a documented scale requirement, or a measured production workload.

127+- The justification MUST identify the input or producer, the failure being

128+ prevented, the expected scale, and why simpler slices, maps, channels, or

129+ direct ownership are insufficient. A round number, hypothetical abuse case,

130+ or benchmark in isolation is not evidence of a product requirement.

131+- Protocol- and security-derived bounds MUST remain tied to their source with a

132+ concise rationale and boundary tests. Do not generalize one per-item bound

133+ into an aggregate process policy without separate evidence.

134+- When a limit has no valid requirement, remove the policy and its coupled

135+ machinery. Raising it to an effectively unreachable value is not the clean

136+ end state.

137+- Do not add allocation- or latency-oriented complexity until the path is shown

138+ to be hot by its production frequency, a profile, or representative benchmark.

139+ Once a path is established as hot, follow "Hot-Path And Benchmark Discipline."

303140

304−```mermaid

305−flowchart 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−```

141+## Hot-Path And Benchmark Discipline

328142

329−3. Scope discipline at every step:

143+metrix commit/collect, per-sample/per-write, and per-cycle code are hot paths that

144+run for every collector on every cycle.

330145

331−```mermaid

332−flowchart 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−```

146+- Before/after REQUIRED: a hot-path change MUST include before/after

147+ `go test -bench` numbers (use `git stash` for the "before" baseline), not just

148+ "tests pass".

149+- Allocation count is the gate: assert allocs stay within the intended envelope

150+ (e.g. a sparse commit stays ~O(touched), never O(retained)). `ns/op` is a

151+ dev-machine trend indicator, NOT a CI gate — label it as such inline, and never

152+ record a personal name in the file.

153+- State the complexity envelope explicitly (e.g. "commit is O(live-series +

154+ touched + distinct-names)") and prove the change did not introduce an

155+ O(samples)/O(retained)/O(n^2) regression.

156+- Keep bench comments in sync with the code they measure, in the same change, with

157+ self-contained wording (no round/session references).

347158

348−</details>

159+## Go Formatting

349160

350−USER COMMUNICATION:

161+`gofmt` and `goimports` are the baseline. This repository additionally

162+RECOMMENDS (not CI-enforced) a fuller formatting pipeline that keeps line

163+wrapping tight and keyed struct literals readable:

351164

352−1. 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.

165+1. `golines -m 120 -t 4 -w <paths>` — join over-wrapped signatures/calls and

166+ split lines past ~120 columns. SKIP this step if `golines` is not installed

167+ (`go install github.com/segmentio/golines@latest`).

168+2. `go run ./tools/expandstructs <paths>` — put each keyed struct-literal field

169+ on its own line. Formats source in-process with `go/format`.

170+3. `goimports -w <paths>` — order imports.

354171

355−2. 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.

172+Conventions this encodes:

358173

359−3. 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.

174+- Keep a signature / call / return / composite literal on ONE line when it fits

175+ within ~120 columns; wrap only when it does not.

176+- Keyed struct literals of a named type go ONE field per line.

362177

363−## SOW System

178+`gofmt`/`goimports` cannot express these two rules, so they are not CI-enforced;

179+re-run the pipeline if code drifts. See `tools/expandstructs/README.md`.

364180

365−Project SOW status: initialized

181+## Validation For Go Changes

366182

367−This project uses a local Statement of Work system.

183+Run the narrowest command that actually exercises the change; do not claim

184+full-project validation from a narrow one.

368185

369−SOWs and specs are **local-only working memory, never committed**:

186+- Always: formatted per "Go Formatting" above (at minimum `gofmt` clean) and

187+ `go vet ./<pkg>/` clean.

188+- Unit: `go test -count=1 ./<pkg>/...` for every package you touched.

189+- Concurrency: add `-race` for concurrency-sensitive packages (`metrix`, the job

190+ runtime, `plugin/agent/jobmgr`).

191+- Shared framework code: ALSO build and test representative consumers (a couple of

192+ real collectors) plus `-race ./plugin/agent/jobmgr/`, so a framework change is

193+ proven against real users, not just its own package.

194+- Reproduce a reviewer-reported bug as a FAILING test first, then fix to green

195+ (repo-wide working-style rule).

196+- Prefer `testify/require` for test prerequisites and `testify/assert` for

197+ comparisons when applicable. Use `t.Fatal` or `t.Fatalf` directly when it

198+ represents genuine test control flow or has no clearer assertion equivalent.

370199

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".

200+## Go Review And Reachability

388201

389−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 local SOW, project-local specs, and project-local skills.

202+- Start review at the declared interface and the shipped production adapter.

203+ Inspect implementation internals behind that boundary only when the contract

204+ leaves relevant behavior unspecified or concrete evidence points across it.

205+ Do not make a caller responsible for arbitrary private behavior of every

206+ implementation.

207+- Before deleting Go code as unused, check all relevant reference forms:

208+ selector reads and writes, struct literals, constructor arguments, method

209+ values, interface satisfaction, reflection, build-tagged and platform files,

210+ generated code, and test-only injection. A call-site-only search is not proof

211+ of unreachability.

390212

391−### Roles

213+## Batching And Review

392214

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−

398−Before non-trivial work:

399−

400−1. 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`.

401−2. Read relevant specs under `.agents/sow/specs/` (local-only memory).

402−3. Inspect `.agents/skills/*/SKILL.md` if any exist, and load every runtime project skill whose trigger matches the work.

403−4. Inspect legacy runtime skills listed below when the user request matches their frontmatter trigger.

404−5. Inspect code, docs, tests, and existing project instructions as ground truth.

405−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.

406−

407−### Git Worktrees

408−

409−Assistants must not create git worktrees on their own. Create a git worktree only when the user explicitly asks for it or approves it.

410−

411−After a git worktree is created — or after an old checkout is updated to the

412−local-only SOW model — run `.agents/sow/worktree-link.sh`. It builds the SOW

413−queues and symlinks `.agents/sow/q`, `.agents/sow/specs`, `.local`, and `.env`

414−to the origin checkout, so SOW working memory is shared per-developer rather than

415−re-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

417−overwritten.) The script is idempotent, never loses data on a name collision,

418−re-points a symlink whose origin moved, and refuses to run in a worktree whose

419−origin checkout is not yet on this model (it prints how to update the origin

420−first).

421−

422−### Sensitive Data In Durable Artifacts

423−

424−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.

425−

426−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.

427−

428−Write 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−

435−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.

436−

437−### Durable AI-Facing Artifact Formatting

438−

439−AI-facing durable artifacts include `AGENTS.md`, SOW specs, runtime project

440−skills, public/operator skills, SOW templates, instruction bridge files, and

441−other docs primarily written so future AI agents can execute repository rules

442−correctly.

443−

444−When 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−

472−When SOW evidence comes from other open-source repositories, cite the upstream repository and checked commit instead of the workstation absolute path.

473−

474−Use:

475−

476−```text

477−owner/repo @ commit

478−relative/path/inside/repo:line

479−```

480−

481−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.

482−

483−### Pre-Implementation Gate

484−

485−Implementation 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−

487−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.

488−

489−### When A SOW Is Required

490−

491−Create 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−

508−Trivial 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−

515−When 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−

527−SOW working files and specs are never committed. `.gitignore` ignores

528−`/.agents/sow/q` and `/.agents/sow/specs`; only the framework files above are

529−tracked. The queue directories are created locally by

530−`.agents/sow/worktree-link.sh`, not by committed `.gitkeep` markers, so there is

531−no committed SOW layout to preserve.

532−

533−Worktree model: SOW working memory is shared per-developer, not per-worktree.

534−In 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

536−any pre-existing top-level queue dirs into `q/` without data loss.

537−

538−Create 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−

542−Users 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

544−SOW lifecycle.

545−

546−Use `<repo-root>/.local/sow/` when the user wants to preserve work locally

547−without creating a public or team-visible GitHub issue yet.

548−

549−Local 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−

556−Deferred 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−

561−Active implementation work still MUST use the `.agents/sow/q/` queues. SOW

562−working files are never committed (the `q/` tree is gitignored), so there is no

563−commit-for-handoff and no remove-before-merge step.

564−

565−Destructive 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−

576−Filename:

577−

578−```text

579−SOW-YYYYMMDD-{slug}.md

580−```

581−

582−Use the creation date plus a descriptive slug. There is no sequential `NNNN`

583−counter because it cannot be allocated safely across parallel branches.

584−

585−SOW 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−

598−An 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−

614−The successful terminal SOW status is `completed`.

615−

616−When a SOW's work is ready to merge:

617−

618−1. Finish implementation, docs, skills, validation, and follow-up mapping.

619−2. 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.

622−3. Update the SOW to `Status: completed`.

623−

624−SOW 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

626−CI merge guard to clear. A completed SOW MAY stay in `.agents/sow/q/done/` as

627−local history or be deleted locally at the user's discretion — never delete a

628−local SOW working file without the user's request (see the deletion guard above).

629−

630−### Enforcement

631−

632−The 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−

648−These checks are guards, not substitutes for the SOW Validation Gate. The

649−assistant still owns transferring durable knowledge out of the SOW before

650−merge.

651−

652−### One SOW At A Time

653−

654−Never execute multiple SOWs as one batch.

655−

656−If 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−

662−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.

663−

664−### User Decisions

665−

666−When user decisions are needed:

667−

668−1. Present concrete evidence with files/lines or source references.

669−2. Provide numbered options.

670−3. Explain pros, cons, implications, and risks.

671−4. Recommend one option with reasoning.

672−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.

673−

674−### Review Materiality And Stop Condition

675−

676−Review findings are leads until they are verified against the shipped code and

677−its 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−

702−Before 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−

708−Pre-close, search the SOW for:

709−

710−```text

712−```

713−

714−Map every remaining item to implemented, rejected, or tracked.

715−

716−### Regressions

717−

718−A regression is broken behavior discovered after a SOW's work merged, where the

719−original claimed outcome is no longer true.

720−

721−Because completed SOWs are not retained on `master`, a regression is handled as

722−new work:

723−

724−1. Open a new local SOW under `.agents/sow/q/active/`.

725−2. In `## Requirements`, link the prior work: `Regresses: PR #NNNNN` and cite

726− any known commit, spec, issue, or test evidence.

727−3. Run the normal Pre-Implementation Gate and Validation for the new SOW.

728−4. Update the relevant spec, skill, doc, code, or test so durable memory reflects

729− current reality.

730−

731−Do not attempt to resurrect or mutate a prior SOW.

732−

733−### Validation Gate

734−

735−A 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−

755−Generic "N/A" is invalid.

756−

757−### Artifact Maintenance Gate

758−

759−Every 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−

768−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.

769−

770−### Specs

771−

772−Specs are memory of WHAT this project does.

773−

774−Specs currently live under `.agents/sow/specs/` as **local-only** memory

775−(gitignored, not committed). They are being reorganized and will be

776−re-introduced to git later as a deliberate decision; until then they are

777−per-developer local memory, shared across worktrees by

778−`.agents/sow/worktree-link.sh`. Durable contracts that must be shared with the

779−team right now belong in project skills, docs, code, and tests.

780−

781−This 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,

785−and update `.agents/sow/specs/README.md` in the same change. Do not split specs

786−by repository path; specs are organized by contract ownership, not source-file

787−location.

788−

789−Update 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−

801−Specs 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−

805−Project skills are memory of HOW to work here.

806−

807−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.

808−

809−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.

810−

811−### Public skill convention (`docs/netdata-ai/skills/`)

812−

813−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.

814−

815−Public skills are for operators and end-users. They may teach users how to

816−query Netdata Cloud, query Agents, inspect metrics/logs/topology/alerts, or run

817−safe operational commands. They must not contain developer-contract validation,

818−schema migration plans, producer authoring workflows, UI adapter work,

819−aggregator implementation notes, SOW handoff instructions, fixture maintenance,

820−PR-review tasks, or codebase-internal implementation recipes.

821−

822−Developer-facing skills must live under `.agents/skills/`, preferably with a

823−`project-` prefix when they are runtime input for repository work. If a workflow

824−requires reading source files, updating schemas, validating fixtures, changing

825−collectors/producers, or coordinating frontend/backend/aggregator code, it is a

826−project developer skill, not a public skill.

827−

828−Skill verification harness inputs are not public skill content. Keep seed

829−questions, grader rubrics, runner scripts, and transcript-generation prompts

830−under `.agents/skill-verification/<skill>/`, not under

831−`docs/netdata-ai/skills/<skill>/`.

832−

833−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>`.

834−

835−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).

836−

837−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.

838−

839−### How-tos catalog rule

840−

841−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.

842−

843−The how-to rule does not override audience boundaries. If the analysis produced

844−a developer validation recipe, put it in the matching `.agents/skills/` project

845−skill and update that skill's index instead of adding it under

846−`docs/netdata-ai/skills/`.

847−

848−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.

849−

850−### Project Skills Index

851−

852−Runtime 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−

912−Public 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−

929−Output/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−

957−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.

958−

959−## Collector Consistency Requirements

960−

961−When working on collectors, runtime behavior, metrics, charts, configuration,

962−alerts, taxonomy, and generated documentation MUST stay consistent in one PR.

963−The 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

984−artifacts: audit reports, fetched API data, scratch notes, queue files,

985−intermediate triage decisions. Agents writing skill output should default to

986−`<repo-root>/.local/audits/<topic>/...` -- where `<topic>` is the skill

987−name with any trailing `-audit` suffix removed (so `coverity-audit/`

988−writes under `coverity/`, `pr-reviews/` writes under `pr-reviews/`).

989−

990−Convention:

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−

996−Naming: each skill `<topic>-audit/` writes to `.local/audits/<topic>/`

997−(the `-audit` suffix is dropped from the directory name so the URL-style

998−path stays short). Skills without the `-audit` suffix keep their full

999−name (e.g. `pr-reviews/` writes to `.local/audits/pr-reviews/`). When

1000−adding a new skill, follow this convention.

1001−

1002−Nothing under `/.local/` is committed. Treat the directory as ephemeral

1003−between 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

1008−endpoint configuration consumed by skill scripts: API tokens, session

1009−cookies, project keys. Never commit secrets; never hard-code tokens in scripts.

1010−

1011−**Setup**: copy `<repo>/.env.template` to `<repo>/.env` and fill in

1012−the keys you need.

1013−

1014−**Reference**: `<repo>/.agents/ENV.md` is the single canonical guide

1015−covering every key -- what it is, where to find the value, sample

1016−format, common mistakes, and which skills require it. When a script

1017−errors with `<KEY> is empty`, check `.agents/ENV.md` for that key.

215+- Changes SHOULD stay atomic. If a collector or framework task grows, split it

216+ into coherent batches before review becomes difficult.

217+- At every batch boundary, you MUST re-evaluate clean end state and scope. If

218+ the branch now contains independent work, pause and submit that work

219+ separately or defer it before continuing.

220+- Changes MUST NOT mix framework changes, collector migrations, and

221+ integration-doc regeneration unless they are required for one coherent

222+ behavior change.

223+- Multi-round review: checkpoint-commit each validated change before its review and

224+ squash at PR time; if findings keep clustering in one subsystem (~2-3 rounds),

225+ stop patching and fix the class (repo-wide review rules).

226+- For Go test style, follow the repo-root `AGENTS.md` "Go test style" section.

1018227