@cryptotaxi247 / netdata-1 / commits / a6533938e

init: add SOW (Statement of Work) system (#22363)

Costa Tsaousis committed May 1, 2026 at 16:21 UTC a6533938e1bc9c5d10036662cbb8b07a44bdff0d
8 files changed +861 -1
.agents/sow/SOW.template.md new
+178
@@ -0,0 +1,178 @@
1 +# SOW-NNNN - <Title>
2 +
3 +## Status
4 +
5 +Status: open | in-progress | paused | completed | closed
6 +
7 +Sub-state: <short current truth>
8 +
9 +## Requirements
10 +
11 +### Purpose
12 +
13 +<User-stated purpose. All recommendations must align with this.>
14 +
15 +### User Request
16 +
17 +<Concise quote or faithful summary. Do not lose constraints.>
18 +
19 +### Assistant Understanding
20 +
21 +Facts:
22 +
23 +- <Established from user/project/code/specs.>
24 +
25 +Inferences:
26 +
27 +- <Reasoned but not directly stated.>
28 +
29 +Unknowns:
30 +
31 +- <Only real unknowns that cannot be resolved by investigation.>
32 +
33 +### Acceptance Criteria
34 +
35 +- <Outcome with verification method.>
36 +- <Outcome with verification method.>
37 +
38 +## Analysis
39 +
40 +Sources checked:
41 +
42 +- <file/source>
43 +
44 +Current state:
45 +
46 +- <evidence>
47 +
48 +Risks:
49 +
50 +- <risk and implication>
51 +
52 +## Pre-Implementation Gate
53 +
54 +Status: blocked | ready | needs-user-decision
55 +
56 +Problem / root-cause model:
57 +
58 +- <What is happening, why it is happening, and evidence supporting that model.>
59 +
60 +Evidence reviewed:
61 +
62 +- <Specs, code, docs, tests, logs, traces, prior SOWs, issues, external references.>
63 +
64 +Affected contracts and surfaces:
65 +
66 +- <APIs, schemas, files, commands, UI, docs, specs, skills, tests, integrations, operators, users.>
67 +
68 +Existing patterns to reuse:
69 +
70 +- <Local modules, helpers, conventions, tests, and docs that shape the implementation.>
71 +
72 +Risk and blast radius:
73 +
74 +- <Regression, compatibility, performance, security, data loss, migration, rollout, and operational risks.>
75 +
76 +Implementation plan:
77 +
78 +1. <Ordered chunk with scope, dependencies, and likely files/modules.>
79 +2. <Ordered chunk with scope, dependencies, and likely files/modules.>
80 +
81 +Validation plan:
82 +
83 +- <Tests, fixtures, manual checks, real-use evidence, review passes, same-failure searches.>
84 +
85 +Artifact impact plan:
86 +
87 +- AGENTS.md: <expected update or reason likely unaffected>
88 +- Runtime project skills: <expected update or reason likely unaffected>
89 +- Specs: <expected update or reason likely unaffected>
90 +- End-user/operator docs: <expected update or reason likely unaffected>
91 +- End-user/operator skills: <expected update or reason likely unaffected>
92 +- SOW lifecycle: <split/merge/status/follow-up/regression handling>
93 +
94 +Open decisions:
95 +
96 +- <Resolved decision, or numbered options that block implementation until the user decides.>
97 +
98 +## Implications And Decisions
99 +
100 +<Numbered user decisions, options, selection, and reasoning. User decisions must be recorded before implementation.>
101 +
102 +## Plan
103 +
104 +1. <chunk, scope, risk, dependencies>
105 +2. <chunk, scope, risk, dependencies>
106 +
107 +## Execution Log
108 +
109 +### YYYY-MM-DD
110 +
111 +- <files touched, decisions, deviations, reviewers>
112 +
113 +## Validation
114 +
115 +Acceptance criteria evidence:
116 +
117 +- <evidence>
118 +
119 +Tests or equivalent validation:
120 +
121 +- <command/output summary>
122 +
123 +Real-use evidence:
124 +
125 +- <manual/API/CLI/UI path>
126 +
127 +Reviewer findings:
128 +
129 +- <reviewer and findings>
130 +
131 +Same-failure scan:
132 +
133 +- <search and result>
134 +
135 +Artifact maintenance gate:
136 +
137 +- AGENTS.md: <updated path or evidence-backed reason no update was needed>
138 +- Runtime project skills: <updated .agents/skills/project-*/ path or evidence-backed reason no update was needed>
139 +- Specs: <updated .agents/sow/specs/ path or evidence-backed reason no update was needed>
140 +- End-user/operator docs: <updated docs/runbooks/help paths or evidence-backed reason none were affected>
141 +- End-user/operator skills: <updated output/reference skill paths or evidence-backed reason none were affected>
142 +- SOW lifecycle: <status/directory checked; split/merge/follow-up/regression handling recorded>
143 +
144 +Specs update:
145 +
146 +- <updated spec or specific reason no update was needed>
147 +
148 +Project skills update:
149 +
150 +- <updated runtime project skill or specific reason no update was needed>
151 +
152 +End-user/operator docs update:
153 +
154 +- <updated docs or evidence-backed reason none were affected>
155 +
156 +End-user/operator skills update:
157 +
158 +- <updated output/reference skills affected by docs/spec changes, or evidence-backed reason none were affected>
159 +
160 +Lessons:
161 +
162 +- <lesson or specific reason none>
163 +
164 +Follow-up mapping:
165 +
166 +- <implemented/rejected/tracked>
167 +
168 +## Outcome
169 +
170 +Pending.
171 +
172 +## Lessons Extracted
173 +
174 +Pending.
175 +
176 +## Followup
177 +
178 +None yet.
.agents/sow/audit.sh new
+411
@@ -0,0 +1,411 @@
1 +#!/usr/bin/env bash
2 +# Read-only audit for a project-local SOW setup.
3 +# Reports current state of cwd: is SOW initialized? what's in place? what's missing?
4 +# Never modifies anything.
5 +
6 +set -uo pipefail
7 +
8 +# Color output if stdout is a tty
9 +if [ -t 1 ]; then
10 + RED=$'\033[0;31m'
11 + GREEN=$'\033[0;32m'
12 + YELLOW=$'\033[1;33m'
13 + BLUE=$'\033[0;34m'
14 + GRAY=$'\033[0;90m'
15 + NC=$'\033[0m'
16 +else
17 + RED=""; GREEN=""; YELLOW=""; BLUE=""; GRAY=""; NC=""
18 +fi
19 +
20 +cwd=$(pwd)
21 +echo "${BLUE}=== SOW audit (cwd=$cwd) ===${NC}"
22 +echo
23 +
24 +is_output_reference_skill() {
25 + local name="$1"
26 + [ -f ./AGENTS.md ] && awk -v name="$name" '
27 + BEGIN { in_output = 0; found = 0 }
28 + /^[[:space:]]*Output\/reference skills:[[:space:]]*$/ { in_output = 1; next }
29 + /^[[:space:]]*(Runtime input skills|Legacy runtime skills):[[:space:]]*$/ { if (in_output) in_output = 0 }
30 + /^#{1,6}[[:space:]]/ && $0 !~ /Project Skills/ { if (in_output) in_output = 0 }
31 + in_output && index($0, ".agents/skills/" name "/") { found = 1 }
32 + END { exit found ? 0 : 1 }
33 + ' ./AGENTS.md 2>/dev/null
34 +}
35 +
36 +is_legacy_runtime_skill() {
37 + local name="$1"
38 + [ -f ./AGENTS.md ] && awk -v name="$name" '
39 + BEGIN { in_legacy = 0; found = 0 }
40 + /^[[:space:]]*Legacy runtime skills:[[:space:]]*$/ { in_legacy = 1; next }
41 + /^[[:space:]]*(Runtime input skills|Output\/reference skills):[[:space:]]*$/ { if (in_legacy) in_legacy = 0 }
42 + /^#{1,6}[[:space:]]/ && $0 !~ /Project Skills/ && $0 !~ /Legacy runtime skills/ { if (in_legacy) in_legacy = 0 }
43 + in_legacy && index($0, ".agents/skills/" name "/") { found = 1 }
44 + END { exit found ? 0 : 1 }
45 + ' ./AGENTS.md 2>/dev/null
46 +}
47 +
48 +read_sow_status() {
49 + awk '
50 + function clean(s, a) {
51 + gsub(/^[[:space:]]+|[[:space:]]+$/, "", s)
52 + gsub(/`/, "", s)
53 + gsub(/\*\*/, "", s)
54 + sub(/^Status:[[:space:]]*/, "", s)
55 + sub(/^status:[[:space:]]*/, "", s)
56 + gsub(/^[[:space:]]+|[[:space:]]+$/, "", s)
57 + split(s, a, /[[:space:]|—]+/)
58 + print a[1]
59 + exit
60 + }
61 + /^Status:[[:space:]]*/ { clean($0) }
62 + /^status:[[:space:]]*/ { clean($0) }
63 + /^\*\*Status:\*\*[[:space:]]*/ { clean($0) }
64 + /^## Status[[:space:]]*$/ { in_status = 1; next }
65 + in_status && NF { clean($0) }
66 + ' "$1" 2>/dev/null
67 +}
68 +
69 +# --- Marker check ---
70 +echo "${BLUE}-- initialization marker --${NC}"
71 +if [ -f ./AGENTS.md ]; then
72 + if grep -q "^Project SOW status: initialized$" ./AGENTS.md 2>/dev/null; then
73 + echo " ${GREEN}OK${NC} marker present in ./AGENTS.md"
74 + initialized=true
75 + else
76 + echo " ${YELLOW}--${NC} AGENTS.md exists but marker absent (partial state or not initialized)"
77 + initialized=false
78 + fi
79 +else
80 + echo " ${RED}--${NC} ./AGENTS.md does not exist (create or normalize project instructions first, then SOW init)"
81 + initialized=false
82 +fi
83 +echo
84 +
85 +# --- Canonical AGENTS.md sections ---
86 +echo "${BLUE}-- canonical AGENTS.md sections --${NC}"
87 +required_sections=(
88 + "## Goals"
89 + "## SOW System"
90 + "### Roles"
91 + "### Git Worktrees"
92 + "### Pre-Implementation Gate"
93 + "### Project Skills"
94 + "### Specs"
95 + "### Project-specific overrides"
96 +)
97 +sections_ok=0
98 +sections_missing=0
99 +if [ -f ./AGENTS.md ]; then
100 + for s in "${required_sections[@]}"; do
101 + if grep -qF "$s" ./AGENTS.md 2>/dev/null; then
102 + echo " ${GREEN}OK${NC} $s"
103 + sections_ok=$((sections_ok + 1))
104 + else
105 + echo " ${RED}--${NC} $s (missing)"
106 + sections_missing=$((sections_missing + 1))
107 + fi
108 + done
109 +else
110 + echo " ${GRAY}(AGENTS.md not present; skipping section check)${NC}"
111 +fi
112 +echo
113 +
114 +# --- Cross-tool instruction bridges ---
115 +echo "${BLUE}-- cross-tool instruction bridges --${NC}"
116 +bridge_missing=0
117 +if [ -f ./AGENTS.md ]; then
118 + if [ -L ./CLAUDE.md ] && [ "$(readlink ./CLAUDE.md 2>/dev/null)" = "AGENTS.md" ]; then
119 + echo " ${GREEN}OK${NC} CLAUDE.md -> AGENTS.md"
120 + else
121 + echo " ${RED}--${NC} CLAUDE.md -> AGENTS.md (missing or not a relative symlink)"
122 + bridge_missing=$((bridge_missing + 1))
123 + fi
124 + if [ -L ./GEMINI.md ] && [ "$(readlink ./GEMINI.md 2>/dev/null)" = "AGENTS.md" ]; then
125 + echo " ${GREEN}OK${NC} GEMINI.md -> AGENTS.md"
126 + else
127 + echo " ${RED}--${NC} GEMINI.md -> AGENTS.md (missing or not a relative symlink)"
128 + bridge_missing=$((bridge_missing + 1))
129 + fi
130 + if [ -d ./.agents/skills ]; then
131 + echo " ${GREEN}OK${NC} .agents/skills/"
132 + else
133 + echo " ${RED}--${NC} .agents/skills/ (missing; create even when no project skills exist)"
134 + bridge_missing=$((bridge_missing + 1))
135 + fi
136 + if [ -L ./.claude/skills ] && [ "$(readlink ./.claude/skills 2>/dev/null)" = "../.agents/skills" ]; then
137 + echo " ${GREEN}OK${NC} .claude/skills -> ../.agents/skills"
138 + else
139 + echo " ${RED}--${NC} .claude/skills -> ../.agents/skills (missing or not a relative symlink)"
140 + bridge_missing=$((bridge_missing + 1))
141 + fi
142 +else
143 + echo " ${GRAY}(AGENTS.md not present; skipping bridge check)${NC}"
144 +fi
145 +echo
146 +
147 +# --- .agents/sow/ directories ---
148 +echo "${BLUE}-- SOW directories --${NC}"
149 +sow_dirs=(specs pending current done)
150 +sow_dir_ok=0
151 +sow_dir_missing=0
152 +empty_sow_dir_missing_keep=0
153 +for d in "${sow_dirs[@]}"; do
154 + if [ -d ".agents/sow/$d" ]; then
155 + echo " ${GREEN}OK${NC} .agents/sow/$d/"
156 + sow_dir_ok=$((sow_dir_ok + 1))
157 + has_entries=$(find ".agents/sow/$d" -mindepth 1 -maxdepth 1 2>/dev/null | wc -l | tr -d ' ')
158 + if [ "$has_entries" -eq 0 ] && [ ! -f ".agents/sow/$d/.gitkeep" ] && [ ! -f ".agents/sow/$d/.keep" ]; then
159 + echo " ${YELLOW}*${NC} empty directory has no .gitkeep or .keep placeholder"
160 + empty_sow_dir_missing_keep=$((empty_sow_dir_missing_keep + 1))
161 + fi
162 + else
163 + echo " ${RED}--${NC} .agents/sow/$d/ (missing)"
164 + sow_dir_missing=$((sow_dir_missing + 1))
165 + fi
166 +done
167 +echo
168 +
169 +# --- Project-local framework files ---
170 +echo "${BLUE}-- project-local SOW framework files --${NC}"
171 +framework_missing=0
172 +if [ -f ".agents/sow/SOW.template.md" ]; then
173 + echo " ${GREEN}OK${NC} .agents/sow/SOW.template.md"
174 + if grep -q "^## Pre-Implementation Gate$" ".agents/sow/SOW.template.md" 2>/dev/null; then
175 + echo " ${GREEN}OK${NC} template includes Pre-Implementation Gate"
176 + sow_template_pre_impl_missing=0
177 + else
178 + echo " ${RED}--${NC} template missing ## Pre-Implementation Gate"
179 + sow_template_pre_impl_missing=1
180 + fi
181 +else
182 + echo " ${RED}--${NC} .agents/sow/SOW.template.md (missing)"
183 + framework_missing=$((framework_missing + 1))
184 + sow_template_pre_impl_missing=1
185 +fi
186 +if [ -f ".agents/sow/audit.sh" ]; then
187 + echo " ${GREEN}OK${NC} .agents/sow/audit.sh"
188 +else
189 + echo " ${RED}--${NC} .agents/sow/audit.sh (missing)"
190 + framework_missing=$((framework_missing + 1))
191 +fi
192 +echo
193 +
194 +# --- SOW counts per status ---
195 +echo "${BLUE}-- SOW counts per status --${NC}"
196 +for d in pending current done; do
197 + if [ -d ".agents/sow/$d" ]; then
198 + n=$(find ".agents/sow/$d" -mindepth 1 -maxdepth 1 -name 'SOW-*.md' -type f 2>/dev/null | wc -l | tr -d ' ')
199 + if [ "$n" -gt 0 ]; then
200 + echo " $d: $n"
201 + find ".agents/sow/$d" -mindepth 1 -maxdepth 1 -name 'SOW-*.md' -type f -printf ' %f\n' 2>/dev/null | sort
202 + else
203 + echo " $d: ${GRAY}(empty)${NC}"
204 + fi
205 + fi
206 +done
207 +echo
208 +
209 +# --- SOW status/directory consistency ---
210 +echo "${BLUE}-- SOW status/directory consistency --${NC}"
211 +sow_status_mismatch=0
212 +sow_status_missing=0
213 +sow_status_checked=0
214 +for d in pending current done; do
215 + [ -d ".agents/sow/$d" ] || continue
216 + while IFS= read -r f; do
217 + [ -z "$f" ] && continue
218 + sow_status_checked=$((sow_status_checked + 1))
219 + status=$(read_sow_status "$f")
220 + if [ -z "$status" ]; then
221 + echo " ${RED}--${NC} $f (missing Status: line)"
222 + sow_status_missing=$((sow_status_missing + 1))
223 + continue
224 + fi
225 + ok=false
226 + case "$d:$status" in
227 + pending:open|current:in-progress|current:paused|done:completed|done:closed)
228 + ok=true
229 + ;;
230 + esac
231 + if $ok; then
232 + echo " ${GREEN}OK${NC} $f ($status)"
233 + else
234 + echo " ${RED}--${NC} $f (Status: $status does not match $d/)"
235 + sow_status_mismatch=$((sow_status_mismatch + 1))
236 + fi
237 + done < <(find ".agents/sow/$d" -mindepth 1 -maxdepth 1 -name 'SOW-*.md' -type f 2>/dev/null | sort)
238 +done
239 +if [ "$sow_status_checked" -eq 0 ]; then
240 + echo " ${GRAY}(no SOW files found)${NC}"
241 +fi
242 +echo
243 +
244 +# --- Current SOW pre-implementation gates ---
245 +echo "${BLUE}-- current SOW pre-implementation gates --${NC}"
246 +current_sow_pre_impl_missing=0
247 +current_sow_pre_impl_checked=0
248 +if [ -d ".agents/sow/current" ]; then
249 + while IFS= read -r f; do
250 + [ -z "$f" ] && continue
251 + current_sow_pre_impl_checked=$((current_sow_pre_impl_checked + 1))
252 + if grep -q "^## Pre-Implementation Gate$" "$f" 2>/dev/null; then
253 + echo " ${GREEN}OK${NC} $f"
254 + else
255 + echo " ${RED}--${NC} $f (missing ## Pre-Implementation Gate before implementation continues)"
256 + current_sow_pre_impl_missing=$((current_sow_pre_impl_missing + 1))
257 + fi
258 + done < <(find ".agents/sow/current" -mindepth 1 -maxdepth 1 -name 'SOW-*.md' -type f 2>/dev/null | sort)
259 +fi
260 +if [ "$current_sow_pre_impl_checked" -eq 0 ]; then
261 + echo " ${GRAY}(no current SOW files found)${NC}"
262 +fi
263 +echo
264 +
265 +# --- Project skills ---
266 +echo "${BLUE}-- runtime project skills --${NC}"
267 +project_skills_ok=0
268 +project_skills_total=0
269 +project_output_reference_total=0
270 +if [ -d .agents/skills ]; then
271 + while IFS= read -r d; do
272 + [ -z "$d" ] && continue
273 + name=$(basename "$d")
274 + if is_output_reference_skill "$name"; then
275 + project_output_reference_total=$((project_output_reference_total + 1))
276 + echo " ${GREEN}OK${NC} $name (listed as output/reference; excluded from default runtime guidance)"
277 + continue
278 + fi
279 + project_skills_total=$((project_skills_total + 1))
280 + if [ -f "$d/SKILL.md" ]; then
281 + lines=$(wc -l <"$d/SKILL.md" 2>/dev/null | tr -d ' ')
282 + echo " ${GREEN}OK${NC} $name ($lines lines)"
283 + project_skills_ok=$((project_skills_ok + 1))
284 + else
285 + echo " ${RED}--${NC} $name (no SKILL.md)"
286 + fi
287 + done < <(find .agents/skills -mindepth 1 -maxdepth 1 -type d -name 'project-*' 2>/dev/null | sort)
288 + if [ "$project_skills_total" -eq 0 ] && [ "$project_output_reference_total" -eq 0 ]; then
289 + echo " ${YELLOW}(no .agents/skills/project-*/ found)${NC}"
290 + elif [ "$project_skills_total" -eq 0 ]; then
291 + echo " ${YELLOW}(no runtime input project-* skills found; only output/reference exceptions)${NC}"
292 + fi
293 +else
294 + echo " ${YELLOW}(.agents/skills/ does not exist)${NC}"
295 +fi
296 +echo
297 +
298 +# --- Non-project skill directories ---
299 +echo "${BLUE}-- non-project skill directories --${NC}"
300 +non_project_skills_total=0
301 +non_project_skills_unclassified=0
302 +if [ -d .agents/skills ]; then
303 + while IFS= read -r d; do
304 + [ -z "$d" ] && continue
305 + non_project_skills_total=$((non_project_skills_total + 1))
306 + name=$(basename "$d")
307 + if is_output_reference_skill "$name"; then
308 + echo " ${GREEN}OK${NC} $name (listed as output/reference; not auto-loaded as runtime SOW skill)"
309 + elif is_legacy_runtime_skill "$name"; then
310 + echo " ${GREEN}OK${NC} $name (listed as legacy runtime skill; project-* alignment deferred)"
311 + elif [ -f "$d/SKILL.md" ]; then
312 + echo " ${YELLOW}*${NC} $name (not auto-loaded as runtime SOW skill)"
313 + non_project_skills_unclassified=$((non_project_skills_unclassified + 1))
314 + else
315 + echo " ${RED}--${NC} $name (not project-* and no SKILL.md)"
316 + non_project_skills_unclassified=$((non_project_skills_unclassified + 1))
317 + fi
318 + done < <(find .agents/skills -mindepth 1 -maxdepth 1 -type d ! -name 'project-*' 2>/dev/null | sort)
319 + if [ "$non_project_skills_total" -eq 0 ]; then
320 + echo " ${GREEN}OK${NC} none"
321 + elif [ "$non_project_skills_unclassified" -gt 0 ]; then
322 + echo " ${GRAY}Classify each warning as output/reference, obsolete, or rename/wrap it as project-* if it is runtime input.${NC}"
323 + fi
324 +else
325 + echo " ${GRAY}(.agents/skills/ does not exist)${NC}"
326 +fi
327 +echo
328 +
329 +# --- TODO files at project root ---
330 +echo "${BLUE}-- TODO files at project root --${NC}"
331 +todo_count=0
332 +todo_tracked=false
333 +while IFS= read -r f; do
334 + [ -z "$f" ] && continue
335 + todo_count=$((todo_count + 1))
336 + echo " ${YELLOW}*${NC} $f (not yet migrated)"
337 +done < <(find . -maxdepth 1 -name 'TODO-*.md' -o -maxdepth 1 -name 'TODO.md' 2>/dev/null | sort)
338 +if [ "$todo_count" -gt 0 ]; then
339 + if grep -RiqE "root TODO|TODO file|TODO migration|TODO classification|orphan TODO" .agents/sow/pending .agents/sow/current 2>/dev/null; then
340 + todo_tracked=true
341 + echo " ${GREEN}OK${NC} root TODO classification/migration is tracked by a pending/current SOW"
342 + fi
343 +else
344 + if [ -d .agents/sow/.todo-backup ]; then
345 + bk=$(find .agents/sow/.todo-backup -maxdepth 1 -name 'TODO*.md' 2>/dev/null | wc -l | tr -d ' ')
346 + if [ "$bk" -gt 0 ]; then
347 + echo " ${GREEN}OK${NC} no orphan TODO files (${bk} backed up at .agents/sow/.todo-backup/)"
348 + else
349 + echo " ${GREEN}OK${NC} no TODO files at project root"
350 + fi
351 + else
352 + echo " ${GREEN}OK${NC} no TODO files at project root"
353 + fi
354 +fi
355 +todo_untracked_count=$todo_count
356 +if $todo_tracked; then
357 + todo_untracked_count=0
358 +fi
359 +echo
360 +
361 +# --- Backup of pre-SOW AGENTS.md ---
362 +echo "${BLUE}-- pre-SOW AGENTS.md backup --${NC}"
363 +if [ -f ./AGENTS.md.pre-sow.bak ]; then
364 + echo " ${GREEN}OK${NC} AGENTS.md.pre-sow.bak present (preserves original)"
365 +else
366 + if $initialized; then
367 + echo " ${GRAY}(no backup file; either init was clean or backup name differs)${NC}"
368 + else
369 + echo " ${GRAY}(not yet initialized)${NC}"
370 + fi
371 +fi
372 +echo
373 +
374 +# --- Final verdict ---
375 +echo "${BLUE}-- verdict --${NC}"
376 +skill_classification_warnings=${non_project_skills_unclassified:-0}
377 +
378 +sow_status_errors=$((sow_status_mismatch + sow_status_missing))
379 +pre_impl_errors=$((sow_template_pre_impl_missing + current_sow_pre_impl_missing))
380 +
381 +if $initialized && [ "$sections_missing" -eq 0 ] && [ "$bridge_missing" -eq 0 ] && [ "$sow_dir_missing" -eq 0 ] && [ "$empty_sow_dir_missing_keep" -eq 0 ] && [ "$framework_missing" -eq 0 ] && [ "$sow_status_errors" -eq 0 ] && [ "$pre_impl_errors" -eq 0 ] && [ "$todo_untracked_count" -eq 0 ] && [ "$skill_classification_warnings" -eq 0 ]; then
382 + echo " ${GREEN}=== SOW initialization complete and clean. ===${NC}"
383 + exit 0
384 +elif $initialized && [ "$sections_missing" -eq 0 ] && [ "$bridge_missing" -eq 0 ] && [ "$sow_dir_missing" -eq 0 ] && [ "$empty_sow_dir_missing_keep" -eq 0 ] && [ "$framework_missing" -eq 0 ] && [ "$sow_status_errors" -eq 0 ] && [ "$pre_impl_errors" -eq 0 ] && [ "$todo_untracked_count" -eq 0 ]; then
385 + echo " ${YELLOW}=== SOW initialization structurally complete with skill classification warning(s):${NC}"
386 + echo " ${YELLOW}- ${skill_classification_warnings} non-project skill director(y/ies) need classification in AGENTS.md${NC}"
387 + echo " ${YELLOW}- Runtime input skills should be renamed/wrapped as .agents/skills/project-*/${NC}"
388 + echo " ${YELLOW}- Output/reference skills should be listed separately and kept out of the generic runtime hook${NC}"
389 + exit 0
390 +elif $initialized; then
391 + echo " ${YELLOW}=== SOW marker present but partial state detected:${NC}"
392 + [ "$sections_missing" -gt 0 ] && echo " ${YELLOW}- ${sections_missing} canonical AGENTS.md section(s) missing${NC}"
393 + [ "$bridge_missing" -gt 0 ] && echo " ${YELLOW}- ${bridge_missing} cross-tool instruction bridge(s) missing${NC}"
394 + [ "$sow_dir_missing" -gt 0 ] && echo " ${YELLOW}- ${sow_dir_missing} SOW directory(ies) missing${NC}"
395 + [ "$empty_sow_dir_missing_keep" -gt 0 ] && echo " ${YELLOW}- ${empty_sow_dir_missing_keep} empty SOW directory(ies) missing .gitkeep/.keep${NC}"
396 + [ "$framework_missing" -gt 0 ] && echo " ${YELLOW}- ${framework_missing} project-local framework file(s) missing${NC}"
397 + [ "$sow_status_mismatch" -gt 0 ] && echo " ${YELLOW}- ${sow_status_mismatch} SOW status/directory mismatch(es)${NC}"
398 + [ "$sow_status_missing" -gt 0 ] && echo " ${YELLOW}- ${sow_status_missing} SOW file(s) missing Status line${NC}"
399 + [ "$sow_template_pre_impl_missing" -gt 0 ] && echo " ${YELLOW}- project-local SOW template missing Pre-Implementation Gate${NC}"
400 + [ "$current_sow_pre_impl_missing" -gt 0 ] && echo " ${YELLOW}- ${current_sow_pre_impl_missing} current SOW(s) missing Pre-Implementation Gate${NC}"
401 + [ "$todo_untracked_count" -gt 0 ] && echo " ${YELLOW}- ${todo_untracked_count} untracked orphan TODO file(s) at project root${NC}"
402 + [ "$skill_classification_warnings" -gt 0 ] && echo " ${YELLOW}- ${skill_classification_warnings} non-project skill director(y/ies) need classification${NC}"
403 + echo " ${YELLOW} Repair non-destructively using the project-local AGENTS.md and .agents/sow/SOW.template.md.${NC}"
404 + exit 0
405 +else
406 + echo " ${YELLOW}=== SOW NOT initialized. Install a project-local SOW framework before using SOWs here. ===${NC}"
407 + if [ ! -f ./AGENTS.md ]; then
408 + echo " ${YELLOW} AGENTS.md missing; create or normalize project instructions first.${NC}"
409 + fi
410 + exit 0
411 +fi
.agents/sow/current/.gitkeep
.agents/sow/done/.gitkeep
.agents/sow/pending/.gitkeep
.agents/sow/specs/.gitkeep
.gitignore
+8 -1
@@ -226,4 +226,11 @@ run-ibm.sh
226
227 tmp/
228
229 -build-and-install.sh
229 +build*.sh
230 +install.sh
231 +
232 +.claude/settings.json
233 +.codex
234 +.mcpregistry_github_token
235 +.mcpregistry_registry_token
236 +.playwright-mcp/
AGENTS.md
+264
@@ -9,6 +9,256 @@ THE MOST IMPORTANT RULES ARE:
9 3. Before patching code, we MUST understand the code base and the potential implications of our changes.
10 4. We do not duplicate code. We first check if similar code already exists and to reuse it.
11
12 +## Goals
13 +
14 +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.
15 +
16 +Work in this repository must prioritize root-cause understanding, correctness, performance, maintainability, portability, security, and consistency with existing project conventions. Because the project is too broad for one bootstrap pass, SOW coverage grows incrementally by the area being worked.
17 +
18 +## SOW System
19 +
20 +This project uses a local Statement of Work system.
21 +
22 +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`, project-local SOW files, project-local specs, project-local skills, and the active SOW.
23 +
24 +### Roles
25 +
26 +- **User responsibilities:** purpose, scope decisions, design forks, risk acceptance, destructive approvals, and final product judgment.
27 +- **Assistant responsibilities:** investigation, evidence, implementation, tests or equivalent validation, reviews, documentation, memory updates, and concise reporting.
28 +
29 +### Required First Checks
30 +
31 +Before non-trivial work:
32 +
33 +1. Read pending/current SOWs for overlap, contradictions, and existing decisions.
34 +2. Read relevant specs under `.agents/sow/specs/`.
35 +3. Inspect `.agents/skills/project-*/SKILL.md` if any exist, and load every runtime project skill whose trigger matches the work.
36 +4. Inspect legacy runtime skills listed below when the user request matches their frontmatter trigger.
37 +5. Inspect code, docs, tests, and existing project instructions as ground truth.
38 +6. Ask the user only for irreducible product/design/risk decisions.
39 +
40 +### Git Worktrees
41 +
42 +Assistants must not create git worktrees on their own. Create a git worktree only when the user explicitly asks for it or approves it.
43 +
44 +### Pre-Implementation Gate
45 +
46 +Implementation must not begin until the active SOW contains a concrete `## Pre-Implementation Gate` section. Before moving a SOW from `pending/open` to `current/in-progress`, or before continuing implementation in an existing current SOW that lacks this section, fill the gate.
47 +
48 +The gate must record the problem/root-cause model, evidence reviewed, affected contracts and surfaces, existing patterns to reuse, risk and blast radius, implementation plan, validation plan, artifact impact plan, and open decisions. 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.
49 +
50 +### When A SOW Is Required
51 +
52 +Create or reuse a SOW for non-trivial work:
53 +
54 +- feature work;
55 +- bug fixes with behavioral impact;
56 +- refactors;
57 +- migrations;
58 +- documentation or content changes with product/business impact;
59 +- process changes;
60 +- regressions;
61 +- spec hygiene;
62 +- project skill changes;
63 +- collector changes;
64 +- packaging, install, or deployment changes;
65 +- PR review iteration;
66 +- static analysis triage that changes source, docs, or project policy;
67 +- any work with unclear risk.
68 +
69 +Trivial work does not need a SOW:
70 +
71 +- typo fixes;
72 +- formatting-only changes;
73 +- mechanical rename with no behavior change;
74 +- simple search/replace with low risk.
75 +
76 +When unsure, treat the work as non-trivial.
77 +
78 +### SOW Locations
79 +
80 +- Pending: `.agents/sow/pending/`
81 +- Current: `.agents/sow/current/`
82 +- Done: `.agents/sow/done/`
83 +- Specs: `.agents/sow/specs/`
84 +- Template for new SOWs: `.agents/sow/SOW.template.md`
85 +- Local audit: `.agents/sow/audit.sh`
86 +
87 +Create new SOW files from `.agents/sow/SOW.template.md`. The template is project-local and may be customized for this repository.
88 +
89 +Empty SOW directories must contain `.gitkeep` or `.keep` so the committed repository preserves the full SOW layout after clone/checkout.
90 +
91 +Filename:
92 +
93 +```text
94 +SOW-NNNN-YYYYMMDD-{slug}.md
95 +```
96 +
97 +Status and directory must agree:
98 +
99 +- `open` lives in `pending/`
100 +- `in-progress` lives in `current/`
101 +- `paused` lives in `current/`
102 +- `completed` lives in `done/`
103 +- `closed` lives in `done/`
104 +
105 +### One SOW At A Time
106 +
107 +Never execute multiple SOWs as one batch.
108 +
109 +If work overlaps:
110 +
111 +- merge or consolidate before implementation; or
112 +- split into separate SOWs and complete one before starting the next.
113 +
114 +Progress reports are not stop points. Once a SOW is in progress, continue until it is delivered, failed with evidence, blocked on a real user decision/approval, or superseded by newer user instructions.
115 +
116 +### User Decisions
117 +
118 +When user decisions are needed:
119 +
120 +1. Present concrete evidence with files/lines or source references.
121 +2. Provide numbered options.
122 +3. Explain pros, cons, implications, and risks.
123 +4. Recommend one option with reasoning.
124 +5. Record the user's decision in the SOW before implementation.
125 +
126 +### Followup Discipline
127 +
128 +"Deferred" is not a terminal outcome.
129 +
130 +Before a SOW can close, every valid deferred item must be:
131 +
132 +- implemented in the current SOW; or
133 +- explicitly rejected as not worth doing, with evidence; or
134 +- represented by a real pending/current SOW file.
135 +
136 +Pre-close, search the SOW for:
137 +
138 +```text
139 +defer|later|follow-up|future|TODO|pending
140 +```
141 +
142 +Map every remaining item to implemented, rejected, or tracked.
143 +
144 +### Regressions
145 +
146 +When behavior that a completed SOW claimed working stops working:
147 +
148 +1. Find the original SOW in `done/`.
149 +2. Move it back to `current/`.
150 +3. Mark it `in-progress` with a regression note.
151 +4. Add a `## Regression` section.
152 +5. Fix and validate there.
153 +
154 +Do not create a new SOW for a true regression.
155 +
156 +### Validation Gate
157 +
158 +A SOW cannot be completed until Validation records:
159 +
160 +- acceptance criteria evidence;
161 +- tests or equivalent validation;
162 +- real-use evidence when a runnable path exists;
163 +- reviewer findings and how they were handled;
164 +- same-failure search results;
165 +- artifact maintenance gate for `AGENTS.md`, runtime project skills, specs, end-user/operator docs, end-user/operator skills, and SOW lifecycle;
166 +- SOW status/directory consistency;
167 +- spec update or specific reason no spec update was needed;
168 +- project skill update or specific reason no skill update was needed;
169 +- end-user/operator docs update or evidence-backed reason none were affected;
170 +- end-user/operator skill update or evidence-backed reason none were affected by docs/spec changes;
171 +- lessons extracted or specific reason there were none;
172 +- follow-up mapping.
173 +
174 +Generic "N/A" is invalid.
175 +
176 +### Artifact Maintenance Gate
177 +
178 +Every SOW close must explicitly record whether each durable artifact class was updated or why no update was needed:
179 +
180 +- `AGENTS.md` - workflow, responsibility, local framework, project-wide guardrails.
181 +- Runtime project skills - `.agents/skills/project-*/SKILL.md` for HOW to work here.
182 +- Specs - `.agents/sow/specs/` for WHAT the project does.
183 +- End-user/operator docs - README, docs site, runbooks, published guides, help text, or other human-facing documentation.
184 +- End-user/operator skills - output/reference skills copied or consumed outside normal repo work.
185 +- SOW lifecycle - split, merge, status, directory, deferred work, regression reopening, and follow-up mapping.
186 +
187 +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.
188 +
189 +### Specs
190 +
191 +Specs are memory of WHAT this project does.
192 +
193 +This repository is bootstrapped incrementally. The existing source tree and public documentation remain the primary ground truth. SOW specs under `.agents/sow/specs/` should capture durable project decisions, cross-cutting behavioral rules, and area-specific contracts as they are worked.
194 +
195 +Update specs when shipped work changes:
196 +
197 +- product behavior;
198 +- public contracts;
199 +- collector behavior;
200 +- APIs and schemas;
201 +- data formats;
202 +- alerting semantics;
203 +- packaging or deployment behavior;
204 +- operational guarantees;
205 +- known edge cases.
206 +
207 +Specs describe current reality, not aspiration. If specs and code disagree, record the discrepancy in the active SOW and resolve or track it.
208 +
209 +### Project Skills
210 +
211 +Project skills are memory of HOW to work here.
212 +
213 +Runtime input project skills should live under `.agents/skills/project-*/SKILL.md`. The `project-` prefix is the generic hook meaning "agents working in this repo must consider this skill." Before non-trivial work, inspect those skill descriptions and load every matching runtime skill.
214 +
215 +Do not create generic `project-*` skills only to make the framework look complete. The user requested that project skills for this repository grow incrementally.
216 +
217 +Existing non-`project-*` skills under `.agents/skills/` are preserved as legacy runtime skills. Use them when the request matches their frontmatter trigger. Do not rename them or add wrappers during this bootstrap pass.
218 +
219 +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.
220 +
221 +### Project Skills Index
222 +
223 +Runtime input skills:
224 +
225 +- None yet under `.agents/skills/project-*/`. The user requested incremental creation instead of bootstrap-generated project skills.
226 +
227 +Legacy runtime skills:
228 +
229 +- `.agents/skills/coverity-audit/`
230 + Trigger: Coverity Scan defect triage for this repository.
231 + Status: preserved under legacy name; project-skill alignment is deferred and tracked by `.agents/sow/pending/SOW-0003-20260501-legacy-runtime-skill-alignment.md`.
232 +- `.agents/skills/sonarqube-audit/`
233 + Trigger: SonarCloud findings triage for this repository.
234 + Status: preserved under legacy name; project-skill alignment is deferred and tracked by `.agents/sow/pending/SOW-0003-20260501-legacy-runtime-skill-alignment.md`.
235 +- `.agents/skills/graphql-audit/`
236 + Trigger: GitHub Code Scanning/CodeQL triage for this repository.
237 + Status: preserved under legacy name; project-skill alignment is deferred and tracked by `.agents/sow/pending/SOW-0003-20260501-legacy-runtime-skill-alignment.md`.
238 +- `.agents/skills/pr-reviews/`
239 + Trigger: PR comment and review iteration work for this repository.
240 + Status: preserved under legacy name; project-skill alignment is deferred and tracked by `.agents/sow/pending/SOW-0003-20260501-legacy-runtime-skill-alignment.md`.
241 +
242 +Output/reference skills:
243 +
244 +- `docs/netdata-ai/skills/`
245 + Consumer: downstream assistants and users of Netdata AI skill artifacts.
246 + Update when: public/operator AI skill docs, examples, commands, schemas, or workflows change.
247 +- `src/ai-skills/`
248 + Consumer: downstream assistants and users of generated or source AI skill artifacts when this tree is present in the working copy.
249 + Update when: generated/source AI skill behavior, tests, examples, commands, schemas, or workflows change.
250 +
251 +### Project-specific commands
252 +
253 +- This bootstrap pass does not define a full-project command matrix for the monolith.
254 +- Use the narrowest existing command that validates the changed subsystem.
255 +- Do not claim full-project validation from a narrow subsystem command.
256 +- 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.
257 +
258 +### Project-specific overrides
259 +
260 +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.
261 +
262 ## Collector Consistency Requirements
263
264 When working on collectors (especially Go collectors), ALL of the following files MUST be kept in sync before creating a PR:
@@ -56,6 +306,10 @@ Each skill is self-contained: a `SKILL.md` with frontmatter (`name`,
306 knowledge for tasks that recur across sessions (Coverity triage, SonarCloud
307 triage, GitHub Code Scanning triage, etc.).
308
309 +These existing skills are legacy runtime skills, not SOW-generated `project-*`
310 +skills. They are preserved under their original names during the incremental
311 +SOW bootstrap.
312 +
313 When an agent learns something new while running a skill (a new gotcha, a
314 working API call, a corrected workflow) it MUST update the skill's
315 `SKILL.md` and commit it before proceeding. Knowledge that isn't committed
@@ -67,6 +321,14 @@ Currently available skills:
321 - `.agents/skills/graphql-audit/` - GitHub Code Scanning (CodeQL) triage
322 - `.agents/skills/pr-reviews/` - PR comment / review iteration loop
323
324 +### Preservation Notes
325 +
326 +- The pre-SOW `AGENTS.md` was copied to `AGENTS.md.pre-sow.bak` before this merge.
327 +- Existing top-level rules, collector consistency requirements, C code notes, naming conventions, local-only directory rules, and `.env` secret rules were preserved.
328 +- Existing non-`project-*` operational skills were preserved under their current paths.
329 +- No `project-*` skills were created during bootstrap by user request.
330 +- Existing root `TODO*.md` files were preserved in place and are tracked by a pending SOW for future classification.
331 +
332 ## Local-only working directory
333
334 `/.local/` at the repo root is gitignored and reserved for per-user runtime
@@ -97,3 +359,5 @@ between users and machines, not as a shared source of truth.
359 endpoint configuration consumed by skill scripts: API tokens, session
360 cookies, project keys. Each skill's `SKILL.md` documents the variables it
361 needs. Never commit secrets; never hard-code tokens in scripts.
362 +
363 +Project SOW status: initialized