@gobing-ai/knowledge-kit 0.0.9 → 0.0.11

package/plugins/kk/skills/taste-unslop/references/pattern-guide.md

@@ -0,0 +1,68 @@
+# Pattern guide
+
+Use these patterns during the scan in `SKILL.md`. A matching word or punctuation mark is not enough
+to justify an edit. Change it only when the usage is formulaic, repeated, vague, or wrong for the
+requested voice.
+
+## Content and evidence
+
+1. **Puffery and promotion.** Cut phrases such as "pivotal moment", "testament to", "evolving
+   landscape", "breathtaking", and "groundbreaking" when facts carry the point better.
+2. **Vague authority.** Replace "experts believe" or "reports suggest" with a supplied source. If no
+   source exists, preserve the uncertainty and flag or remove the unsupported claim.
+3. **Context-free name-dropping.** Keep a person, company, or publication only when the text explains
+   what it contributes.
+4. **Decorative participial tails.** Delete or expand "highlighting", "showcasing", "ensuring", and
+   similar endings when they add no supported fact.
+5. **Formulaic concessions.** Replace "despite challenges, it continues to thrive" with the actual
+   limitation and result supplied by the source.
+6. **Generic openings and conclusions.** Cut scene-setting and endings such as "the future looks
+   bright" unless they state a concrete claim, decision, or next action.
+
+## Language
+
+7. **Stock AI diction.** Words such as "delve", "pivotal", "tapestry", "underscore", "vibrant",
+   "intricate", and abstract "landscape" are signals only when generic or clustered. Keep the word
+   when it is the precise one.
+8. **Inflated linking verbs.** Replace "serves as", "stands as", or promotional "boasts" with "is"
+   or "has" when precision survives.
+9. **Stock frames.** Rewrite repeated "not just X but Y", forced groups of three, and false "from X
+   to Y" ranges when a direct statement is clearer.
+10. **Synonym cycling.** Pick the precise noun and repeat it instead of rotating through near-synonyms.
+11. **Vague metaphor and borrowed jargon.** Replace metaphorical "substrate", "vector", "north star",
+    "flywheel", or "scaffolding" with the actual mechanism. Preserve established domain terms such as
+    vector embeddings, API surface, language primitive, and test harness.
+12. **Filler and stacked hedges.** Shorten "in order to", "due to the fact that", and redundant
+    qualifier chains. Preserve qualifiers that encode real uncertainty; never turn "may" into "will".
+13. **Fancy plain words.** Prefer "use", "help", "many", and "if" over "utilize", "facilitate",
+    "numerous", and "in the event that" when meaning is unchanged.
+
+## Structure and style
+
+14. **Mechanical rhythm.** Break repeated sentence openings, equal-length paragraphs, and serial
+    summaries. Do not force variation into text whose form is intentionally regular.
+15. **Punctuation monotony.** Reduce repeated em dashes, colons, or parenthetical asides. Keep
+    punctuation required by grammar, locale, quoted material, or the style guide; no mark is banned.
+16. **Formatting as decoration.** Remove excessive boldface, title-case headings, emoji, and inline
+    labels that merely repeat the sentence. Preserve formatting that improves navigation or meets the
+    publication format.
+17. **Dense syntax.** Split a sentence when its dependencies make the reader backtrack. Keep clauses
+    together when separating them would hide the relationship.
+18. **Unhelpful passive voice.** Name the actor when the actor matters. Keep passive voice when the
+    actor is unknown, obvious, or deliberately de-emphasized.
+19. **Adverbs propping up weak claims.** Use a stronger verb or a supplied measurement. Do not invent a
+    number to replace "significantly" or "quickly".
+20. **Typographic inconsistency.** Follow the source language and house style for quotation marks,
+    dashes, spacing, capitalization, and headings instead of forcing English ASCII conventions.
+
+## Chat and meta language
+
+21. **Stock assistant framing.** Remove empty openings and closings such as "Of course", "Great
+    question", "I hope this helps", and "Let me know if". Keep a direct next step when one exists.
+22. **Sycophancy.** Replace automatic agreement with the answer or evidence.
+23. **Cutoff disclaimers.** State the exact missing evidence or omit the unsupported passage. Never
+    disguise a guess as "details are limited".
+24. **Writing about the writing.** Cut "this article will delve into" and similar road signs when the
+    text can make the point directly.
+25. **Feeling without mechanism.** Replace reusable mood claims such as "SQL you can read" with a
+    source-backed behavior, example, or number. If none exists, cut the claim.

package/plugins/kk/workflows/judge-gated-publish-example.yaml

@@ -25,22 +25,21 @@ states:
           # Seed the verdict so the judge gate guards can be evaluated in --dry-run
           # (dry-run skips actions but still evaluates shell guards). A real run's
           # judge step overwrites this file before the gate is read.
-          command: "echo '{\"verdict\":\"PASS\",\"score\":0.0}' > ${vars.verdictFile} && echo 'generating content...'"
+          command: 'echo ''{"verdict":"PASS","score":0.0}'' > ${vars.verdictFile} && echo ''generating content...'''
   - id: judge
     description: "Evaluate generated content via the judge skill (agent.run)"
     onEnter:
-      # `agent.run` is registered by the kk workflow host: it spawns an agent that loads the
-      # content-judge skill, evaluates the content against ${vars.rubric}, and writes the verdict
+      # `agent.run` is registered by the kk workflow host: it spawns an agent that invokes the
+      # kk:content-judge skill, evaluates the content against ${vars.rubric}, and writes the verdict
       # JSON to ${vars.verdictFile}. Under `spur workflow run` (dry-run), this action is
-      # skipped — the seeded verdict above keeps the gate evaluable. See
-      # plugins/kk/skills/content-judge/SKILL.md and references/workflow-integration.md.
+      # skipped — the seeded verdict above keeps the gate evaluable.
       - kind: agent.run
         options:
           role: reviewer
           input: |
+            Invoke the kk:content-judge skill.
             Evaluate the content at ${vars.contentFile} against the ${vars.rubric} rubric.
-            Load plugins/kk/skills/content-judge/SKILL.md and its references/rubrics.md.
-            Write the verdict JSON to ${vars.verdictFile} per the contract in SKILL.md.
+            Write the verdict JSON to ${vars.verdictFile} per the skill's verdict contract.
             Print the verdict path as the last line of stdout.
           expectFile: ${vars.verdictFile}
   - id: publish

package/plugins/kk/workflows/kk-daily-ai-voice.yaml

@@ -83,6 +83,14 @@ states:
             if [ -n "${vars.plugins_path}" ]; then set -- --plugins-path "${vars.plugins_path}"; fi;
             VOICE_GEN_MP3="${vars.transcode_mp3}" kk executor run voice-gen --in "${vars.work_dir}/3-audio/docs.json" --out "${vars.work_dir}/3-audio/content.json" "$@"
 
+  - id: quality-control
+    description: "Verify audio quality, speech rate, and silence/repetition QC metrics"
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            bun -e 'const content = JSON.parse(await Bun.file(process.argv[1]).text()); const qc = content.metadata?.qc; console.log("=== Voice Quality Control Report ==="); console.log("Overall Score: " + (qc ? qc.overallScore : 100) + "/100 | Passed: " + (qc ? qc.passed : true)); if (qc && qc.criticalIssues && qc.criticalIssues.length) { console.warn("QC Issues:\n" + qc.criticalIssues.map(function(i) { return "  - " + i; }).join("\n")); } else { console.log("All audio segments passed quality control checks cleanly."); }' "${vars.work_dir}/3-audio/content.json"
+
   - id: done
     description: "Terminal — Daily AI news voice broadcast generated successfully"
   - id: failed
@@ -138,7 +146,13 @@ transitions:
       kind: always
 
   - from: generate
+    to: quality-control
+    description: "Audio generated -> run quality control validation"
+    guard:
+      kind: always
+
+  - from: quality-control
     to: done
-    description: "Audio generated successfully -> complete"
+    description: "Quality control checks complete -> done"
     guard:
       kind: always

package/plugins/kk/workflows/kk-ingest-generate-publish.yaml

@@ -14,7 +14,7 @@ vars:
   publish_plugin: "surfdash-pub"
   source: "./source"
   work_dir: "./work"
-  plugins_path: "./plugins"
+  plugins_path: "" # empty -> ADR-012 default discovery (package-shipped built-ins); set for checkout dev
 
 states:
   - id: ingest
@@ -22,21 +22,30 @@ states:
     onEnter:
       - kind: shell
         options:
-          command: kk executor run ${vars.ingestion_plugin} --in ${vars.source} --out ${vars.work_dir}/docs.json --plugins-path ${vars.plugins_path}
+          command: >-
+            set --;
+            if [ -n "${vars.plugins_path}" ]; then set -- --plugins-path "${vars.plugins_path}"; fi;
+            kk executor run ${vars.ingestion_plugin} --in ${vars.source} --out ${vars.work_dir}/docs.json "$@"
 
   - id: generate
     description: Run content generator plugin to produce markdown content (content.json)
     onEnter:
       - kind: shell
         options:
-          command: kk executor run ${vars.generator_plugin} --in ${vars.work_dir}/docs.json --out ${vars.work_dir}/content.json --plugins-path ${vars.plugins_path}
+          command: >-
+            set --;
+            if [ -n "${vars.plugins_path}" ]; then set -- --plugins-path "${vars.plugins_path}"; fi;
+            kk executor run ${vars.generator_plugin} --in ${vars.work_dir}/docs.json --out ${vars.work_dir}/content.json "$@"
 
   - id: publish
     description: Run publish plugin to deploy content and receive result (result.json)
     onEnter:
       - kind: shell
         options:
-          command: kk executor run ${vars.publish_plugin} --in ${vars.work_dir}/content.json --out ${vars.work_dir}/result.json --plugins-path ${vars.plugins_path}
+          command: >-
+            set --;
+            if [ -n "${vars.plugins_path}" ]; then set -- --plugins-path "${vars.plugins_path}"; fi;
+            kk executor run ${vars.publish_plugin} --in ${vars.work_dir}/content.json --out ${vars.work_dir}/result.json "$@"
 
   - id: done
     description: Terminal — all three plugin steps succeeded

package/plugins/kk/workflows/kk-itc.yaml

@@ -22,9 +22,8 @@ vars:
   outline: ""
   force: "false"
   rubric: "tech-accuracy"
-  verdictFile: ".spur/run/${vars.__runId}-itc-verdict.json"
+  verdictFile: "" # empty -> ${vars.work_dir}/.itc-verdict.json (set by prepare)
   agent: ""
-  __runId: "itc"
   __hitlAnswer: ""
   __hitlInput: ""
 
@@ -40,6 +39,7 @@ states:
               echo "missing work_dir" >&2; exit 1;
             fi;
             mkdir -p "${vars.work_dir}" "${vars.work_dir}/2-outline" "${vars.work_dir}/3-draft";
+            echo 0 > "${vars.work_dir}/.revise-count";
             if [ -n "${vars.topic}" ] && [ -n "${vars.input_file}" ]; then
               echo "XOR violation: both topic and input_file set" >&2; exit 1;
             fi;
@@ -66,7 +66,7 @@ states:
           role: scribe
           agent: ${vars.agent}
           input: |
-            Load plugins/kk/skills/storm-research/SKILL.md.
+            Invoke the kk:storm-research skill.
             Run storm-research on the topic or input file specified in the brief at ${vars.work_dir}/brief.md.
 
   - id: outline-write
@@ -77,7 +77,7 @@ states:
           role: scribe
           agent: ${vars.agent}
           input: |
-            Load plugins/kk/skills/${vars.writer}/SKILL.md.
+            Invoke the kk:${vars.writer} skill.
             Generate outline options (outline-option-a.md, outline-option-b.md, and optionally outline-option-c.md) in ${vars.work_dir}/2-outline/ from the brief at ${vars.work_dir}/brief.md using playbook ${vars.playbook}.
             Do not wait for operator selection; write the option files.
           expectFile: ${vars.work_dir}/2-outline/outline-option-a.md
@@ -122,7 +122,7 @@ states:
           role: scribe
           agent: ${vars.agent}
           input: |
-            Load plugins/kk/skills/${vars.writer}/SKILL.md.
+            Invoke the kk:${vars.writer} skill.
             Author the technical draft at ${vars.work_dir}/3-draft/draft-article.md based on approved outline ${vars.work_dir}/2-outline/outline-approved.md and brief ${vars.work_dir}/brief.md using playbook ${vars.playbook}.
             Revision feedback: ${vars.__hitlInput}
           expectFile: ${vars.work_dir}/3-draft/draft-article.md
@@ -143,12 +143,8 @@ states:
       - kind: shell
         options:
           command: >-
-            mkdir -p .spur/run;
-            run_id="${vars.__runId}";
-            if [ -z "$run_id" ]; then run_id="itc"; fi;
-            count_file=".spur/run/$run_id-itc-revise-count";
-            curr=$(cat "$count_file" 2>/dev/null || echo 0);
-            echo $((curr + 1)) > "$count_file";
+            n=$(cat "${vars.work_dir}/.revise-count" 2>/dev/null || echo 0);
+            echo $((n + 1)) > "${vars.work_dir}/.revise-count";
       - kind: hitl.input
         options:
           prompt: "Provide specific revision feedback for ${vars.work_dir}/3-draft/draft-article.md:"
@@ -162,11 +158,11 @@ states:
           role: reviewer
           agent: ${vars.agent}
           input: |
-            Load plugins/kk/skills/content-judge/SKILL.md and its references/rubrics.md.
+            Invoke the kk:content-judge skill.
             Evaluate the draft at ${vars.work_dir}/3-draft/draft-article.md against the ${vars.rubric} rubric.
-            Write the verdict JSON to ${vars.verdictFile} per the contract in SKILL.md.
+            Write the verdict JSON to ${vars.work_dir}/.itc-verdict.json per the skill's verdict contract.
             Print the verdict path as the last line of stdout.
-          expectFile: ${vars.verdictFile}
+          expectFile: ${vars.work_dir}/.itc-verdict.json
 
   - id: done
     description: "Terminal — IT content draft generated and approved successfully"
@@ -252,7 +248,7 @@ transitions:
     guard:
       kind: shell
       options:
-        command: 'test "${vars.__hitlAnswer}" = "no" && { run_id="${vars.__runId}"; if [ -z "$run_id" ]; then run_id="itc"; fi; test "$(cat .spur/run/$run_id-itc-revise-count 2>/dev/null || echo 0)" -lt 3; }'
+        command: 'test "${vars.__hitlAnswer}" = "no" && test "$(cat "${vars.work_dir}/.revise-count" 2>/dev/null || echo 0)" -lt 3'
 
   - from: draft-review
     to: failed
@@ -260,7 +256,7 @@ transitions:
     guard:
       kind: shell
       options:
-        command: 'test "${vars.__hitlAnswer}" = "no" && { run_id="${vars.__runId}"; if [ -z "$run_id" ]; then run_id="itc"; fi; test "$(cat .spur/run/$run_id-itc-revise-count 2>/dev/null || echo 0)" -ge 3; }'
+        command: 'test "${vars.__hitlAnswer}" = "no" && test "$(cat "${vars.work_dir}/.revise-count" 2>/dev/null || echo 0)" -ge 3'
 
   - from: draft-revise
     to: draft-write
@@ -274,7 +270,7 @@ transitions:
     guard:
       kind: shell
       options:
-        command: 'v="$(jq -r .verdict ${vars.verdictFile} 2>/dev/null)"; test -z "$v" -o "$v" = PASS'
+        command: 'v="$(jq -r .verdict ${vars.work_dir}/.itc-verdict.json 2>/dev/null)"; test -z "$v" -o "$v" = PASS'
 
   - from: judge
     to: failed
@@ -282,4 +278,4 @@ transitions:
     guard:
       kind: shell
       options:
-        command: 'v="$(jq -r .verdict ${vars.verdictFile} 2>/dev/null)"; test -n "$v" -a "$v" != PASS'
+        command: 'v="$(jq -r .verdict ${vars.work_dir}/.itc-verdict.json 2>/dev/null)"; test -n "$v" -a "$v" != PASS'