@gobing-ai/knowledge-kit 0.0.6 → 0.0.8

package/plugins/kk/commands/workflow-run.md

@@ -0,0 +1,202 @@
+---
+name: workflow-run
+description: >-
+  Run STORM daily research or IT content authoring end to end. Installs the workflow
+  YAML on first run (two-root copy rule), creates the config with defaults if missing,
+  computes the workspace, and shells spur workflow run against the installed workflow.
+argument-hint: "[name] <topic|--in file> [--dir <path>] [--playbook generic|english|wechat] [--research] [--judge] [--outline <a|b|c>] [--writer itc-generating|topic] [--duration <min>] [--language <code>] [--script-approved] [--fixture] [--force]"
+---
+
+Thin runner around the **storm-research**, **itc-generating** / **topic**, and **kk-solo-podcast**
+capabilities. Read `plugins/kk/skills/storm-research/SKILL.md` or
+`plugins/kk/skills/itc-generating/SKILL.md` for craft; solo-podcast craft is inlined in the
+workflow `agent.run` prompt (no fat skill). This command owns the run procedure: config create,
+YAML install (two-root copy rule) into `$HOME/.config/kk/workflows`, workspace computation, and
+the `spur workflow run` of that **runtime** dest. Design-time SSOT remains
+`plugins/kk/workflows/` in the package/repo. No new `kk` CLI noun (ADR-011) — everything here
+is shell + the workflow.
+
+**Args:** `$ARGUMENTS`
+
+## 1. Parse `$ARGUMENTS`
+
+Parse per the frozen rule:
+
+- First token is the workflow **name** when it matches `^[a-z0-9][a-z0-9-]*$` and is not `--in`;
+  otherwise `name=kk-storm-research` and that token is the topic. Supported profile names:
+  `kk-storm-research` (default), `kk-itc`, `kk-solo-podcast`. Any other name after successful copy → exit 1 listing
+  `kk-storm-research`, `kk-itc`, `kk-solo-podcast`.
+- `--in <file>` → file mode. `--force` → overwrite an existing dest YAML / existing `brief.md`.
+- Profile `kk-storm-research`: `--fixture` → force `fixture: "true"`.
+- Profile `kk-itc`: `--dir <path>` (default `./<kebab>`), `--playbook generic|english|wechat` (default `generic`),
+  `--research` (`true`|`false`, default `false`), `--judge` (`true`|`false`, default `false`),
+  `--outline <a|b|c>` (default empty), `--writer itc-generating|topic` (default `itc-generating`).
+  `--fixture` passed with `kk-itc` or `kk-solo-podcast` → exit 1 (`fixture is storm-only`).
+- Profile `kk-solo-podcast`: `--dir <path>` (default `$works_dir/<kebab>`), `--outline <a|b|c>`
+  (default empty), `--duration <min>` (default `8`), `--language <code>` (default `en`),
+  `--script-approved` (sets `script_approved=true`; default off). `--fixture` is storm-only.
+- **XOR:** exactly one of `<topic>` / `--in <file>`. Both set or both empty → exit 1, stderr
+  states the XOR rule, no writes.
+
+Resolve these before step 2: `NAME`, `TOPIC`, `INPUT_FILE` (empty in sentence mode), `FIXTURE`
+(`true`|`false`), `FORCE` (`true`|`false`), `DIR`, `PLAYBOOK`, `RESEARCH`, `JUDGE`, `OUTLINE`,
+`WRITER`, `DURATION` (`8`), `LANGUAGE` (`en`), `SCRIPT_APPROVED` (`true`|`false`),
+`VOICE_PROFILE` (from `VOICEBOX_DEFAULT_PROFILE`, default empty).
+
+## 2. Resolve the config
+
+`config_path="${KK_CONFIG:-$HOME/.config/kk/config.yaml}"`.
+
+- **Missing file → create-on-first-run** with compiled defaults (never overwrite an existing
+  file — no merge, no rewrite):
+
+```bash
+install -d "$(dirname "$config_path")"
+cat > "$config_path" <<'EOF'
+works_dir: "$HOME/.config/kk/works"
+workflows_dir: "$HOME/.config/kk/workflows"
+defaults:
+  maxResults: 8
+  fixture: false
+EOF
+```
+
+- **Unreadable / unparseable / invalid types** (e.g. `maxResults: "eight"`) → exit 1, stderr
+  names the key and expected vs actual type; touch nothing.
+- Read the four values with precedence **command flag > env > file > compiled default**:
+
+| Value | Env override | Compiled default |
+| --- | --- | --- |
+| `works_dir` | `KK_WORKS_DIR` | `$HOME/.config/kk/works` |
+| `workflows_dir` | `KK_WORKFLOWS_DIR` | `$HOME/.config/kk/workflows` |
+| `defaults.maxResults` | — | `8` |
+| `defaults.fixture` | — | `false` |
+
+`--fixture` sets `fixture=true` regardless of the file. `FIRECRAWL_API_KEY` is **never** read
+from config — env-only.
+
+## 3. Install the workflow YAML
+
+`dest="$workflows_dir/$NAME.yaml"`. Copy from the **first hit** of, in order:
+
+1. `$KK_WORKFLOWS_SOURCE/$NAME.yaml`
+2. `plugins/kk/workflows/$NAME.yaml`
+
+- `dest` missing → copy from the first hit. Source missing from both roots → exit 1, stderr
+  lists the roots searched: `no source workflow for $NAME (searched KK_WORKFLOWS_SOURCE, plugins/kk/workflows)`.
+- `dest` exists + `--force` → overwrite from source.
+- `dest` exists + identical bytes → no-op.
+- `dest` exists + different bytes → **warn and leave** (run proceeds with the user's copy).
+
+```bash
+src=""
+for d in "$KK_WORKFLOWS_SOURCE" "plugins/kk/workflows"; do
+  [ -n "$d" ] && [ -f "$d/$NAME.yaml" ] && { src="$d/$NAME.yaml"; break; }
+done
+[ -z "$src" ] && { echo "no source workflow for $NAME (searched KK_WORKFLOWS_SOURCE, plugins/kk/workflows)" >&2; exit 1; }
+if [ ! -f "$dest" ] || [ "$FORCE" = true ]; then
+  install -d "$(dirname "$dest")" && cp "$src" "$dest"
+elif ! cmp -s "$src" "$dest"; then
+  echo "warning: $dest differs from install source; leaving user copy (pass --force to replace)" >&2
+fi
+# Runtime dest is $workflows_dir (default ~/.config/kk/workflows). Copy YAML sidecars
+# that the machine shells (kk-solo-podcast: validate-voicescript.ts).
+if [ "$NAME" = "kk-solo-podcast" ] && [ -n "$src" ]; then
+  side="validate-voicescript.ts"
+  sdir=$(dirname "$src")
+  ddir=$(dirname "$dest")
+  if [ -f "$sdir/$side" ]; then
+    if [ ! -f "$ddir/$side" ] || [ "$FORCE" = true ]; then
+      cp "$sdir/$side" "$ddir/$side"
+    elif ! cmp -s "$sdir/$side" "$ddir/$side"; then
+      echo "warning: $ddir/$side differs from install source; leaving user copy (pass --force to replace)" >&2
+    fi
+  fi
+fi
+```
+
+## 4. Compute workspace
+
+### Profile `kk-storm-research` (0056 `topicId`)
+
+`raw` = `TOPIC` (sentence mode) or the first ATX H1 (`/^#\s+(.+)$/m`) else basename without
+extension (`--in` mode). Then:
+
+```bash
+normalized=$(printf '%s' "$raw" | tr '[:upper:]' '[:lower:]' | tr -s '[:space:]' ' ' | sed 's/^[[:space:]]*//; s/[[:space:]]*$//')
+slug=$(printf '%s' "$normalized" | tr -cs 'a-z0-9' '-' | sed 's/^-*//; s/-*$//' | cut -c1-48 | sed 's/-*$//')
+[ -z "$slug" ] && slug="topic"
+hash=$(printf '%s' "$normalized" | shasum -a 256 | cut -c1-8)
+topic_id="${slug}-${hash}"
+work_dir="$works_dir/$topic_id"
+```
+
+- `raw` derives empty (no H1 and empty basename) → exit 1 with the derived value.
+- Same `raw` → same workspace; **last write wins**; never fail on an existing works dir.
+
+```bash
+mkdir -p "$work_dir"
+```
+
+### Profile `kk-itc` (authoring workspace)
+
+`raw` = `TOPIC` or file-mode first ATX H1 else basename without extension.
+`kebab` = lower-case, `[^a-z0-9]+` → `-`, trimmed dashes (no length cap, no sha256 hash).
+`work_dir="${DIR:-./$kebab}"`. Empty derived `kebab` → exit 1.
+
+### Profile `kk-solo-podcast`
+
+`raw` = `TOPIC` or file-mode first ATX H1 else basename without extension.
+`kebab` = lower-case, `[^a-z0-9]+` → `-`, trimmed dashes (no length cap, no sha256 hash).
+`work_dir="${DIR:-$works_dir/$kebab}"`. Empty derived `kebab` → exit 1.
+
+## 5. Run the workflow
+
+All values are strings.
+
+### Profile `kk-storm-research`
+
+Bind vars: `maxResults` and `fixture` from step 2; `plugins_path` defaults to `./plugins`
+in a checkout, else installed package `plugins/` or `KK_PLUGIN_PATH`; `render_script` is
+`plugins/kk/scripts/render-md.ts`.
+
+```bash
+spur workflow run "$dest" --vars \
+  "{\"topic\":\"$TOPIC\",\"input_file\":\"$INPUT_FILE\",\"maxResults\":\"$maxResults\",\"fixture\":\"$FIXTURE\",\"work_dir\":\"$work_dir\",\"plugins_path\":\"$plugins_path\",\"render_script\":\"$render_script\"}"
+```
+
+### Profile `kk-itc`
+
+Bind vars: `topic`, `input_file`, `work_dir`, `writer`, `playbook`, `research`, `judge`, `outline`,
+`force`, `rubric` (`tech-accuracy`), `verdictFile` (`.spur/run/${vars.__runId}-itc-verdict.json`), `agent`.
+
+```bash
+spur workflow run "$dest" --vars \
+  "{\"topic\":\"$TOPIC\",\"input_file\":\"$INPUT_FILE\",\"work_dir\":\"$work_dir\",\"writer\":\"$WRITER\",\"playbook\":\"$PLAYBOOK\",\"research\":\"$RESEARCH\",\"judge\":\"$JUDGE\",\"outline\":\"$OUTLINE\",\"force\":\"$FORCE\",\"rubric\":\"tech-accuracy\",\"verdictFile\":\".spur/run/\${vars.__runId}-itc-verdict.json\",\"agent\":\"$AGENT\"}"
+```
+
+### Profile `kk-solo-podcast`
+
+Bind vars: `topic`, `input_file`, `work_dir`, `outline`, `script_approved`, `force`,
+`target_duration_min`, `language`, `voice_profile` (from `VOICEBOX_DEFAULT_PROFILE` or empty),
+`validate_script` (`$workflows_dir/validate-voicescript.ts`), `plugins_path` (empty → ADR-012
+default discovery), `agent`. **Always** `spur workflow run "$dest"` — `$dest` is
+`$workflows_dir/kk-solo-podcast.yaml`, never the design-time `plugins/kk/workflows/` path.
+
+```bash
+spur workflow run "$dest" --vars \
+  "{\"topic\":\"$TOPIC\",\"input_file\":\"$INPUT_FILE\",\"work_dir\":\"$work_dir\",\"outline\":\"$OUTLINE\",\"script_approved\":\"$SCRIPT_APPROVED\",\"force\":\"$FORCE\",\"target_duration_min\":\"$DURATION\",\"language\":\"$LANGUAGE\",\"voice_profile\":\"$VOICE_PROFILE\",\"validate_script\":\"$workflows_dir/validate-voicescript.ts\",\"plugins_path\":\"\",\"agent\":\"$AGENT\"}"
+```
+
+## 6. Report
+
+- **`kk-storm-research`**: print resolved `work_dir`, then `$work_dir/content.md` (report sidecar)
+  and `$work_dir/content.json` (machine contract). Skim `content.md` citations against `docs.json`
+  ids before presenting.
+- **`kk-itc`**: print resolved `work_dir`, then `$work_dir/brief.md`, `$work_dir/2-outline/outline-approved.md`,
+  and `$work_dir/3-draft/draft-article.md`. If `judge=true`, also print the verdict path.
+- **`kk-solo-podcast`**: print resolved `work_dir`, then `$work_dir/3-script/voicescript.yaml`,
+  `$work_dir/4-audio/content.json`, and `$work_dir/4-audio/content.wav`.
+
+If the run ended `failed`, show the failing state (`spur workflow trace <run-id> --json`) and the
+fail-loud recovery line.

package/plugins/kk/config.example.yaml

@@ -0,0 +1,34 @@
+works_dir: "~/.config/kk/works"
+workflows_dir: "~/.config/kk/workflows"
+defaults:
+  maxResults: 8
+  fixture: false
+
+# Plugin credentials — paste values between the quotes.
+# Path: plugins/<collection>/<name>/env — each entry is injected into that plugin's
+# process environment at exec time. A real environment variable always wins
+# over a value here (flag > env > config > compiled default).
+plugins:
+  ingestions:
+    web-search:
+      env:
+        FIRECRAWL_API_KEY: ""   # firecrawl.dev — required for live research
+  generations:
+    voice-gen:
+      env:
+        VOICEBOX_URL: "http://127.0.0.1:17493"     # local Voicebox REST origin
+        VOICEBOX_DEFAULT_PROFILE: "Robin"          # GET /profiles name or id — required for plain-text Docs
+        VOICEBOX_TIMEOUT_MS: "600000"              # per-generation poll budget (ms)
+        VOICEBOX_POLL_MS: "1000"                   # GET /history/{id} interval
+        VOICEBOX_MAX_CHUNK_CHARS: "800"            # Voicebox auto-chunk size (100–5000)
+        VOICEBOX_CROSSFADE_MS: "50"                # Voicebox chunk crossfade (0–500)
+  publishings:
+    qiita-pub:
+      env:
+        QIITA_TOKEN: ""         # Qiita API v2 token (read_qiita/write_qiita) — required
+    zenn-pub:
+      env:
+        ZENN_REPO: ""           # GitHub repo for Zenn CLI deploy — used by zenn-pub
+    surfdash-pub:
+      env:
+        POSTSURFING_BIN: ""    # optional — delete if unused; defaults to `postsurfing` on PATH

package/plugins/kk/scripts/render-md.ts

@@ -0,0 +1,150 @@
+/**
+ * Shipped no-checkout runner for the Content→markdown research-report helper.
+ * 0059's `render` state shells: `bun <this script> --in <content.json> --out <content.md>`.
+ *
+ * Self-contained by design: end users install the published `kk` package and cannot
+ * resolve `@gobing-ai/kk-core` (private). The render logic below is a COPY of
+ * `packages/kk-core/src/render-md.ts`; keep them byte-identical for the same Content.
+ *
+ * NODE-BUILTIN-ONLY — no workspace or `@gobing-ai/*` imports, and therefore raw
+ * `console.error` rather than the ts-utils output seam. This script ships to arbitrary
+ * user projects and is shelled as `bun <this script>`; an `@gobing-ai/*` import resolves
+ * there only because bun auto-installs it from the network, so it fails under
+ * `bun --no-install`, offline, or in an air-gapped environment. Enforced by
+ * `shipped-script-isolation` in `.spur/rules/boundary/`.
+ *
+ * SYNC: packages/kk-core/src/render-md.ts (renderContentMarkdown + helpers)
+ */
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { parseArgs } from 'node:util';
+
+interface Ref {
+    url?: string;
+    title?: string;
+    cite?: string;
+}
+
+interface ContentInput {
+    body: string;
+    title?: string;
+    outline?: string;
+    references?: Ref[];
+}
+
+/** Mirror of `ContentSchema` structural requirements for the fields this render touches. */
+function parseContent(raw: string): ContentInput {
+    const value: unknown = JSON.parse(raw);
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('content must be an object');
+    }
+    const c = value as Record<string, unknown>;
+    if (typeof c.body !== 'string') {
+        throw new Error('body is required and must be a string');
+    }
+    const out: ContentInput = { body: c.body };
+    if (c.title !== undefined) {
+        if (typeof c.title !== 'string') {
+            throw new Error('title must be a string');
+        }
+        out.title = c.title;
+    }
+    if (c.outline !== undefined) {
+        if (typeof c.outline !== 'string') {
+            throw new Error('outline must be a string');
+        }
+        out.outline = c.outline;
+    }
+    if (c.references !== undefined) {
+        if (!Array.isArray(c.references)) {
+            throw new Error('references must be an array');
+        }
+        out.references = c.references.map((r, i) => {
+            if (r === null || typeof r !== 'object' || Array.isArray(r)) {
+                throw new Error(`references[${i}] must be an object`);
+            }
+            const rr = r as Record<string, unknown>;
+            for (const key of ['url', 'title', 'cite'] as const) {
+                if (rr[key] !== undefined && typeof rr[key] !== 'string') {
+                    throw new Error(`references[${i}].${key} must be a string`);
+                }
+            }
+            return { url: rr.url, title: rr.title, cite: rr.cite } as Ref;
+        });
+    }
+    return out;
+}
+
+export function renderContentMarkdown(content: ContentInput): string {
+    const heading = content.title?.trim() || 'Untitled';
+    const startsWithHeading = content.body.startsWith(`# ${heading}`);
+    const lead = startsWithHeading ? '' : `# ${heading}\n\n`;
+    const refsBlock = renderReferences(content.references);
+    return `${lead}${content.body}${refsBlock}\n`;
+}
+
+function renderReferences(references: ContentInput['references']): string {
+    if (!references || references.length === 0) {
+        return '';
+    }
+    const lines: string[] = [];
+    for (const ref of references) {
+        const label = renderReferenceLabel(ref);
+        if (label === '') {
+            continue;
+        }
+        lines.push(`- ${label}`);
+    }
+    if (lines.length === 0) {
+        return '';
+    }
+    return `\n\n## References\n\n${lines.join('\n')}`;
+}
+
+function renderReferenceLabel(ref: Ref): string {
+    const { url, title, cite } = ref;
+    const titleT = title?.trim() ?? '';
+    const urlT = url?.trim() ?? '';
+    const citeT = cite?.trim() ?? '';
+    let label: string;
+    if (titleT !== '' && urlT !== '') {
+        label = `[${titleT}](${urlT})`;
+    } else if (titleT !== '') {
+        label = titleT;
+    } else if (urlT !== '') {
+        label = urlT;
+    } else if (citeT !== '') {
+        label = `\`${citeT}\``;
+    } else {
+        return '';
+    }
+    if (citeT !== '' && label !== `\`${citeT}\``) {
+        label = `${label} (${citeT})`;
+    }
+    return label;
+}
+
+async function main(): Promise<number> {
+    const { values } = parseArgs({
+        options: {
+            in: { type: 'string' },
+            out: { type: 'string' },
+        },
+    });
+    if (!values.in || !values.out) {
+        console.error('Error: Missing required arguments --in and --out');
+        return 1;
+    }
+    try {
+        const content = parseContent(await readFile(values.in, 'utf-8'));
+        await writeFile(values.out, renderContentMarkdown(content), 'utf-8');
+        return 0;
+    } catch (err: unknown) {
+        console.error(`render-md failed: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+}
+
+if (import.meta.main) {
+    process.exitCode = await main();
+}

package/plugins/kk/skills/{kk-judge → content-judge}/SKILL.md

@@ -1,17 +1,17 @@
 ---
-name: kk-judge
-description: This skill should be used when an LLM evaluation gate is needed in a knowledge-kit pipeline — "judge this content", "evaluate against rubric", "quality gate before publish", "check technical accuracy", "review brand tone", "compliance check", or when a spur workflow step of type `agent.run` targets the kk-judge skill to emit a PASS/FAIL/NEEDS_REVISION verdict. Centralizes evaluation rubrics, prompt templates, and structured verdict emission for generated Content.
+name: content-judge
+description: This skill should be used when an LLM evaluation gate is needed in a knowledge-kit pipeline — "judge this content", "evaluate against rubric", "quality gate before publish", "check technical accuracy", "review brand tone", "compliance check", or when a spur workflow step of type `agent.run` targets the content-judge skill to emit a PASS/FAIL/NEEDS_REVISION verdict. Centralizes evaluation rubrics, prompt templates, and structured verdict emission for generated Content.
 version: 0.1.0
 ---
 
-# kk-judge — LLM-as-judge evaluation skill
+# content-judge — LLM-as-judge evaluation skill
 
 ## Purpose
 
 Evaluate generated `Content` against a rubric and emit a structured **verdict** that a spur
 workflow gate can consume. This is the fat skill — the single source of truth for evaluation
-logic, prompt templates, and verdict formatting. Thin wrappers (tech-accuracy, brand-tone,
-compliance) delegate here with a pre-selected rubric.
+logic, prompt templates, and verdict formatting. The `agent.run` prompt (or `--judge` flag on
+`itc-generating`) selects the rubric; there are no persona subagents.
 
 LLM-as-judge is **not** a knowledge-kit plugin kind (ADR-007 amdt 2026-08-07). It runs as an
 `agent.run` step in a spur workflow; the verdict is a skill output, not a plugin-kind contract.
@@ -20,7 +20,7 @@ LLM-as-judge is **not** a knowledge-kit plugin kind (ADR-007 amdt 2026-08-07). I
 
 - A spur workflow needs a quality gate between `generate` and `publish`.
 - A user asks to "judge", "evaluate", "quality-check", or "gate" generated content.
-- A thin wrapper (tech-accuracy / brand-tone / compliance) delegates evaluation.
+- A workflow or skill names a rubric (`tech-accuracy` / `brand-tone` / `compliance` / `general`).
 
 ## Verdict output contract
 
@@ -61,8 +61,8 @@ Every evaluation writes a JSON verdict file. The default path is
 
 1. **Read the Content** from the path given in the evaluation request (the `content.json` written
    by the preceding `kk executor run <generator>` step).
-2. **Select the rubric** — either named in the request (`tech-accuracy`, `brand-tone`,
-   `compliance`, `general`) or loaded by a thin wrapper. Default: `general`.
+2. **Select the rubric** — named in the request (`tech-accuracy`, `brand-tone`,
+   `compliance`, `general`). Default: `general`.
 3. **Evaluate each criterion** in the rubric. For each, produce a `pass` / `fail` / `warn` status
    backed by a specific, quotable evidence reference (quote, section, claim).
 4. **Score** — weighted aggregate per the rubric's scoring rules. `score` is 0.0–1.0.
@@ -107,7 +107,7 @@ Content to evaluate: {{content_path}}
 Rubric: {{rubric}}              # general | tech-accuracy | brand-tone | compliance
 Output verdict to: {{verdict_path}}
 
-Load the rubric definition from plugins/kk/skills/kk-judge/references/rubrics.md (section: {{rubric}}).
+Load the rubric definition from plugins/kk/skills/content-judge/references/rubrics.md (section: {{rubric}}).
 Evaluate the content against every criterion in that rubric.
 For each criterion, quote the specific passage and assign pass | fail | warn.
 Decide the verdict: any must-pass fail → FAIL; else score < threshold → NEEDS_REVISION; else PASS.
@@ -119,13 +119,12 @@ Print the verdict path to stdout as the last line.
 
 See `references/workflow-integration.md` for the `agent.run` step shape and the shell/`jq` guard
 that reads the verdict. The example workflow is at
-`.spur/workflows/judge-gated-publish-example.yaml`.
+`plugins/kk/workflows/judge-gated-publish-example.yaml`.
 
-## Thin wrappers
+## Rubric selection
 
-The wrappers in `plugins/kk/agents/` (tech-accuracy, brand-tone, compliance) are thin: they fix
-the `rubric` field and forward to this skill. They do not duplicate evaluation logic. To create a
-new persona, add a wrapper that sets the rubric and reuses this skill's procedure verbatim.
+The `agent.run` prompt (or the calling skill) sets `{{rubric}}`. To add a persona, add a rubric
+section in `references/rubrics.md` and name it from the prompt — do not add a subagent wrapper.
 
 ## Additional resources
 

package/plugins/kk/skills/{kk-judge → content-judge}/references/rubrics.md

@@ -1,6 +1,6 @@
-# Rubrics — kk-judge evaluation criteria
+# Rubrics — judge evaluation criteria
 
-Loaded by the kk-judge skill at evaluation time. Each rubric defines criteria, weights,
+Loaded by the judge skill at evaluation time. Each rubric defines criteria, weights,
 must-pass flags, and the score thresholds that map to verdicts.
 
 ## Scoring model

package/plugins/kk/skills/{kk-judge → content-judge}/references/workflow-integration.md

@@ -1,4 +1,4 @@
-# Workflow integration — kk-judge in a spur workflow
+# Workflow integration — content-judge in a spur workflow
 
 Spur's workflow engine executes one node at a time (`type: parallel` is an inert schema field —
 see `docs/03_ARCHITECTURE.md`). The judge step is therefore a single `agent.run` node followed
@@ -7,16 +7,18 @@ by a `shell` node that guards the transition to `publish`.
 ## Step shape
 
 ```yaml
-- name: judge
-  type: agent.run
-  run: |
-    Evaluate the generated content against the {{rubric}} rubric.
-    Content: {{content_path}}
-    Write the verdict to {{verdict_path}}.
-  skill: kk-judge
+- kind: agent.run
+  options:
+    role: reviewer
+    input: |
+      Evaluate the generated content against the {{rubric}} rubric.
+      Content: {{content_path}}
+      Write the verdict to {{verdict_path}}.
+      Load plugins/kk/skills/content-judge/SKILL.md.
+    expectFile: "{{verdict_path}}"
 ```
 
-- `agent.run` spawns an agent that loads the `kk-judge` skill, performs the evaluation, and writes
+- `agent.run` spawns an agent that loads the `content-judge` skill, performs the evaluation, and writes
   the verdict JSON to `{{verdict_path}}` (typically `.spur/run/verdict-judge.json`).
 - The verdict file is the only durable artifact. The agent's prose output is not the contract.
 
@@ -28,22 +30,22 @@ The guard runs as a `shell` step after `judge`. It reads the verdict and gates t
 #!/usr/bin/env sh
 verdict_path="{{verdict_path}}"
 if [ ! -f "$verdict_path" ]; then
-  echo "kk-judge: verdict file not found at $verdict_path"
+  echo "judge: verdict file not found at $verdict_path"
   exit 1
 fi
 verdict=$(jq -r '.verdict' "$verdict_path")
 case "$verdict" in
   PASS)
-    echo "kk-judge: PASS"
+    echo "judge: PASS"
     exit 0
     ;;
   FAIL|NEEDS_REVISION)
-    echo "kk-judge: $verdict — see $verdict_path for findings"
+    echo "judge: $verdict — see $verdict_path for findings"
     jq -r '.findings[]? | select(.status=="fail") | "  FAIL: \(.criterion): \(.detail)"' "$verdict_path"
     exit 1
     ;;
   *)
-    echo "kk-judge: unrecognized verdict '$verdict' in $verdict_path"
+    echo "judge: unrecognized verdict '$verdict' in $verdict_path"
     exit 1
     ;;
 esac
@@ -60,7 +62,7 @@ esac
 
 For a bounded regenerate-retry loop, wire the workflow so that a `NEEDS_REVISION` verdict routes
 back to the `generate` step with the verdict's `feedback` as additional input. Cap retries (the
-example workflow uses 2). This is workflow-level orchestration — `kk-judge` itself is stateless
+example workflow uses 2). This is workflow-level orchestration — `content-judge` itself is stateless
 and re-runnable.
 
 ```
@@ -73,5 +75,5 @@ generate ──▶ judge ──PASS──▶ publish
 
 ## Workflow YAML location
 
-The runnable example lives at `.spur/workflows/judge-gated-publish-example.yaml`. It demonstrates
+The runnable example lives at `plugins/kk/workflows/judge-gated-publish-example.yaml`. It demonstrates
 `generate → judge → guard → publish` with a 2-retry NEEDS_REVISION loop.