@gobing-ai/knowledge-kit 0.0.9 → 0.0.10

package/plugins/kk/skills/audio-authoring/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: audio-authoring
+description: >-
+  Use the audio-authoring skill to author spoken-audio scripts from a brief —
+  "create an audio script", "write a podcast script", "generate a briefing",
+  "outline options for audio", "author a VoiceScript", "revise the script".
+  Runs briefing → outline → script with explicit operator gates; solo mode
+  ships first, dialogue/interview/narration are named extension points.
+---
+
+# audio-authoring — spoken-audio authoring (create | briefing | outline | script)
+
+## Purpose
+
+Turn a Markdown brief into an **approved VoiceScript** for spoken audio in a small
+file-backed workspace. One fat skill with four operations — `create`, `briefing`,
+`outline`, `script` — sharing one artifact contract, one VoiceScript contract, one
+spoken-budget rule, resume behavior, and recovery guidance. This is the authoring
+layer extracted from `kk-solo-podcast`; synthesis (TTS) and deterministic formats
+are deliberately **out of scope**.
+
+## When to use
+
+- A user asks to author spoken-audio content from a brief or topic ("create a podcast
+  script about X", "write the briefing for a 10-minute episode").
+- A workflow `agent.run` step needs one authoring stage independently (briefing only,
+  outline options only, script from an approved outline).
+- An operator resumes a half-finished audio workspace and expects existing approved
+  artifacts to be reused, not overwritten.
+
+Do **not** use this skill for: deterministic broadcast-news scripting (that is the
+`kk:dailynews-gen` generator plugin), text-to-speech synthesis itself (that is
+`kk:voice-gen` — this skill's output is its input), or multi-speaker authoring
+beyond the extension-point notes below.
+
+## Invocation contract
+
+`$ARGUMENTS` (or the Skill call args) parse as:
+
+```
+[operation] [--mode solo] --dir <work_dir> [--duration <min>] [--language <code>] [--profile <voice>] [--outline a|b|c] [--revise <feedback>] [--force]
+```
+
+| Token | Meaning | Default |
+| --- | --- | --- |
+| `operation` | `create` (default) \| `briefing` \| `outline` \| `script` | `create` |
+| `--mode <name>` | authoring mode | `solo` (only implemented mode; others fail loud) |
+| `--dir <work_dir>` | workspace directory | required — an empty dir fails loud |
+| `--duration <min>` | target spoken duration in minutes | `8` |
+| `--language <code>` | spoken language code (enum below) | `en` |
+| `--profile <voice>` | voice profile for the wrap step — **not** written into the VoiceScript | none |
+| `--outline <a\|b\|c>` | explicit outline selection | operator must select when options are shown |
+| `--revise <feedback>` | revision feedback for the script review gate | none (approve path) |
+| `--force` | explicit operator approval to replace an existing artifact | off — never overwrite without it |
+
+Operations are case-insensitive. An unknown operation fails loud and lists the four
+valid operations. Flags may appear in any order (topic convention).
+
+## Artifact contract
+
+All paths are relative to the workspace `--dir`. Every operation uses these exact
+paths — the contract is the same whether the operation runs inside `create` or
+directly.
+
+| Artifact | Path | Written by |
+| --- | --- | --- |
+| Brief (input) | `brief.md` | supplied before invocation — topic phrase or Markdown brief |
+| Briefing | `1-briefing/briefing.md` | `briefing` — thesis, takeaways, audience, duration, tone |
+| Outline options | `2-outline/outline-option-a.md`, `outline-option-b.md`, `outline-option-c.md` | `outline` — always two or three (a and b required; c optional) |
+| Approved outline | `2-outline/outline-approved.md` | `outline` — after explicit operator selection |
+| VoiceScript | `3-script/voicescript.yaml` | `script` — from the approved outline only |
+
+Each operation creates the directory it writes into (`1-briefing/`, `2-outline/`,
+`3-script/`) when absent. No other files are created — no metadata, no JSON
+manifests, no templates, no placeholders.
+
+## Modes
+
+- **solo** (default; only implemented mode) — one voice, no `speakers` map, no
+  per-segment `profile` (the `--profile` value lands in the Doc[] wrap performed by
+  the workflow, never in the VoiceScript).
+- **dialogue** (extension point) — two or more named speakers via the `speakers` map
+  and per-segment `speaker`; turns alternate, distinct voices.
+- **interview** (extension point) — host + guest via `speakers`; host drives
+  questions, guest answers at length.
+- **narration** (extension point) — single voice over long-form material; like solo
+  but paces for continuous narration rather than episode structure.
+
+Requesting an unimplemented mode fails loud naming the mode and stating that only
+`solo` is implemented. No multi-speaker authoring guidance beyond these notes.
+
+## Operations
+
+### create (default)
+
+Sequence: `briefing` → `outline` (selection gate) → `script` (review gate), resuming
+from any existing approved artifact:
+
+1. **Resolve the brief** — require `brief.md` under `--dir`; run the `briefing`
+   semantics.
+2. **Outline** — if `2-outline/outline-approved.md` is missing, run the `outline`
+   semantics (write options, selection gate). If it exists, reuse it — do not
+   regenerate.
+3. **Script** — if `3-script/voicescript.yaml` is missing, run the `script` semantics
+   (write + review gate). If it exists and is approved, report it as final — do not
+   rewrite.
+4. **Report** the final artifact paths and stop. Never re-run a completed step; never
+   overwrite an existing approved artifact without `--force`.
+
+### briefing
+
+1. **Prerequisite** (fail loud): `brief.md` missing → stop with recovery ("supply a
+   brief at `<dir>/brief.md` first"). `1-briefing/briefing.md` exists without
+   `--force` → stop before replacing.
+2. **Read** `brief.md` and write `1-briefing/briefing.md`: core thesis, key listener
+   takeaways, audience profile, target spoken duration (`--duration` minutes), tone,
+   and what material from the brief to emphasize or cut.
+
+### outline
+
+1. **Prerequisite** (fail loud): `1-briefing/briefing.md` missing → stop with
+   recovery ("run `briefing` or `create` first").
+2. **Resume**: `2-outline/outline-approved.md` exists → reuse it; without `--force`,
+   stop before replacing.
+3. **Write options** — read the briefing and write two or three genuinely distinct
+   outline options to `2-outline/outline-option-{a,b,c}.md` (a and b required; c
+   optional). Each option targets the total spoken duration from `--duration`.
+4. **Selection gate**: present the options with their paths and **wait for explicit
+   operator selection** — `--outline <a|b|c>` or an interactive answer. Do not
+   proceed without it. Copy the selected option **verbatim** to
+   `2-outline/outline-approved.md`.
+
+### script
+
+1. **Prerequisite** (fail loud): `2-outline/outline-approved.md` missing → stop with
+   recovery ("run `outline` or `create` first — never script before outline
+   approval").
+2. **Resume**: `3-script/voicescript.yaml` exists → without `--force` or `--revise`,
+   stop before replacing ("script exists at `<path>`; to revise pass `--revise
+   <feedback>`, to replace pass `--force`").
+3. **Write** `3-script/voicescript.yaml` from the approved outline only, obeying the
+   VoiceScript contract and the spoken-budget rule below. Solo mode shape: one
+   speaker, **no** `speakers` map, per-segment `profile` omitted. Emit only valid
+   YAML — no markdown fences, no repo or docs paths in the file body.
+4. **Review gate**: present the script; offer **approve** or **revision**. Bounded
+   revision: at most **3 revision rounds**; each round takes `--revise <feedback>`,
+   rewrites the script from the approved outline plus the feedback, and re-presents
+   it. After 3 rounds, stop and require an explicit operator decision — never loop
+   past the bound.
+5. **Executable check**: when the `validate-voicescript.ts` checker is discoverable
+   (`KK_WORKFLOWS_DIR` or `$HOME/.config/kk/workflows/`), run it against the written
+   file; it is the sole executable authority — the embedded contract below is the
+   authoring-time distillation of it.
+
+## VoiceScript contract
+
+The authoring template lives at **`templates/voicescript.solo.yaml`** (relative to
+this skill file) — read it first when authoring `3-script/voicescript.yaml`; it is a
+valid-YAML skeleton with per-field constraint comments. The executable authority is
+`plugins/kk/workflows/validate-voicescript.ts` (canonical source
+`plugins/generations/voice-gen/src/voicescript.ts`); the template is its
+authoring-time distillation. No other fields are valid authoring targets — do not
+invent fields (no `default_profile`, no required `title`).
+
+Field summary (the template carries the same information as inline comments):
+
+| Field | Where | Constraint |
+| --- | --- | --- |
+| `language` | root | 23-language enum (see template) |
+| `default_engine` | root | engine enum (7 engines, see template) |
+| `speakers` | root | multi-speaker modes only; each entry requires `profile`; omit in solo |
+| `segments` | root | required, non-empty |
+| `text` | segment | required, 1..50000 chars |
+| `instruct` | speaker/segment | <= 500 chars |
+| `gap_ms` | segment | >= 0 |
+| `max_chunk_chars` | segment | 100..5000 |
+| `crossfade_ms` | segment | 0..500 |
+| `speaker` | segment | must name a key of the `speakers` map |
+
+## Spoken-budget rule
+
+Target spoken volume derives from `--duration` and `--language`: for `zh`, `ja`, or
+`ko`, target **characters = duration × 220**; for every other language, target
+**words = duration × 150**. Land within **±20%** of the target. Apply the rule when
+outlining (each option) and when scripting (total across segments).

package/plugins/kk/skills/audio-authoring/templates/voicescript.solo.yaml

@@ -0,0 +1,25 @@
+# Solo-podcast VoiceScript starter template.
+# Fill the placeholders; delete comments before authoring is considered final.
+# Executable contract: validate-voicescript.ts (canonical: voice-gen/src/voicescript.ts).
+# No other fields are valid — do not invent fields (no `default_profile`, no `title`).
+
+language: en # zh|en|ja|ko|de|fr|ru|pt|es|it|he|ar|da|el|fi|hi|ms|nl|no|pl|sv|sw|tr
+# default_engine: qwen  # optional; qwen|qwen_custom_voice|luxtts|chatterbox|chatterbox_turbo|tada|kokoro
+
+# Multi-speaker modes only (dialogue/interview) — omit entirely in solo mode:
+# speakers:
+#   <name>:
+#     profile: <voice-profile>   # required per speaker
+#     engine: qwen               # optional
+#     language: en               # optional
+#     instruct: warm             # optional, <= 500 chars
+
+segments: # required, non-empty
+  - text: "Replace with the spoken sentence." # required, 1..50000 characters
+    gap_ms: 400 # optional, >= 0 — silence before next clip
+    # instruct: "warm"                          # optional, <= 500 characters
+    # engine: qwen                              # optional, per-segment override
+    # language: en                              # optional, per-segment override
+    # max_chunk_chars: 800                      # optional, 100..5000
+    # crossfade_ms: 50                          # optional, 0..500
+    # speaker: <name>                           # multi-speaker only; must key the speakers map

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'