@gobing-ai/knowledge-kit 0.0.7 → 0.0.9

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

@@ -1,18 +1,20 @@
 ---
 name: workflow-run
 description: >-
-  Run STORM daily research end to end — a topic sentence XOR a markdown file becomes a
-  grounded content.md report. Installs the workflow YAML on first run (0056 copy rule),
-  creates the config with defaults if missing, computes the topic workspace, and shells
-  spur workflow run against the installed workflow.
-argument-hint: "[name] <topic|--in file> [--fixture] [--force]"
+  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 wrapper around the **storm-research** skill. Read
-`plugins/kk/skills/storm-research/SKILL.md` first — it is the craft SSOT (query framing,
-evidence verification, better-report practices, fail-loud rows). This command owns the run
-procedure: config create, YAML install, topic-id computation, and the `spur workflow run`.
-No new `kk` CLI noun (ADR-011) — everything here is shell + the workflow.
+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`
 
@@ -21,14 +23,25 @@ No new `kk` CLI noun (ADR-011) — everything here is shell + the workflow.
 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.
-- `--in <file>` → file mode. `--fixture` → force `fixture: "true"`. `--force` → overwrite an
-  existing dest YAML.
+  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`), `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
 
@@ -68,28 +81,43 @@ from config — env-only.
 
 1. `$KK_WORKFLOWS_SOURCE/$NAME.yaml`
 2. `plugins/kk/workflows/$NAME.yaml`
-3. `.spur/workflows/$NAME.yaml`
 
-- `dest` missing → copy from the first hit. Source missing from all three → exit 1, stderr
-  lists the roots searched.
+- `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" ".spur/workflows"; do
+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, .spur/workflows)" >&2; exit 1; }
+[ -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 the topic workspace (0056 `topicId`)
+## 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:
@@ -110,21 +138,65 @@ work_dir="$works_dir/$topic_id"
 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. Bind the vars first: `maxResults` and `fixture` from step 2;
-`plugins_path` defaults to `./plugins` in a checkout, else the installed package `plugins/`
-path or `KK_PLUGIN_PATH`; `render_script` stays `plugins/kk/scripts/render-md.ts`.
+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
 
-Print the resolved `work_dir`, then the two artifacts to hand the operator:
-`$work_dir/content.md` (report sidecar) and `$work_dir/content.json` (machine contract).
-Per the skill's better-report practice (d), skim `content.md` citations against `docs.json`
-ids before presenting. If the run ended `failed`, show the failing state
-(`spur workflow trace <run-id> --json`) and the skill's fail-loud recovery row.
+- **`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

@@ -6,6 +6,13 @@
  * 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)
  */
 
@@ -72,10 +79,8 @@ 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 outlineBlock =
-        content.outline && content.outline.trim().length > 0 ? `\n\n## Outline\n\n${content.outline.trim()}` : '';
     const refsBlock = renderReferences(content.references);
-    return `${lead}${content.body}${outlineBlock}${refsBlock}\n`;
+    return `${lead}${content.body}${refsBlock}\n`;
 }
 
 function renderReferences(references: ContentInput['references']): string {

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

@@ -1,17 +1,17 @@
 ---
-name: 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 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
 ---
 
-# 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/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/{judge → content-judge}/references/workflow-integration.md

@@ -1,4 +1,4 @@
-# Workflow integration — 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: 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 `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.
 
@@ -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 — `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.

package/plugins/kk/skills/itc-generating/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: itc-generating
+description: >-
+  Use the itc-generating skill to produce an approved IT technical draft from a
+  topic or Markdown brief, applying the distilled generic IT-writing method and
+  an optional platform playbook — "write an article about X applying the IT
+  writing method", "generate an IT technical draft on X", "create a technical
+  article for WeChat/English platforms". Orchestrates topic (outline + draft),
+  optional storm-research, and optional content-judge without enlarging those skills.
+---
+
+# itc-generating — IT technical draft generation (method + orchestration)
+
+## Purpose
+
+Turn a topic or Markdown brief into an **approved IT technical draft** by applying the distilled
+IT-writing craft and orchestrating the existing `kk` skills — `topic` (outline + draft), optional
+`storm-research` (evidence), optional `content-judge` (technical-accuracy gate). One fat skill with one
+operation, `create`, whose default is the distilled generic-craft method; it delegates outline
+selection and draft review to `topic` and writes the **same topic artifact paths**. This skill owns
+*which* method and *when* to research/judge — it never reimplements topic-core, research, or
+evaluation (D6).
+
+## When to use
+
+- A user asks to write an IT technical article from a topic or brief and wants the distilled
+  IT-writing method applied ("write an IT article about X", "produce a technical draft on X").
+- A user wants a specific platform playbook applied to the draft (`--playbook english` / `wechat`).
+- A user wants the same topic artifact contract but with the writing method and optional
+  research/judging orchestrated around it.
+
+Do **not** use this skill for: a single topic-core step without the method (call `topic` directly);
+research alone (call `storm-research`); evaluating content alone (call `content-judge`); publishing,
+platform adaptation, or image generation (all out of scope); anything requiring a runtime plugin
+(`kk executor run`, `plugin.json`, `GeneratorInput → Content`).
+
+## Invocation contract
+
+`$ARGUMENTS` (or the Skill call args) parse as:
+
+```
+[create] <topic-or-brief> [--dir <target>] [--brief <path>]
+         [--playbook generic|english|wechat]
+         [--research] [--judge]
+         [--outline <a|b|c>] [--revise <feedback>] [--force]
+```
+
+| Token | Meaning | Default |
+| --- | --- | --- |
+| `create` | the only operation; may be omitted | `create` |
+| `<topic-or-brief>` | quoted topic phrase, or `--brief <path>` naming a Markdown brief file | required — empty fails loud |
+| `--dir <target>` | workspace directory | `./<kebab-case(topic)>` (same default as `topic`) |
+| `--playbook <p>` | which reference to load as the writing method | `generic` |
+| `--research` | if the workspace has no evidence, run `storm-research` first | off |
+| `--judge` | after an approved draft, run `content-judge` with the `tech-accuracy` rubric | off |
+| `--outline <a\|b\|c>` | explicit outline selection (passed through to `topic`) | operator selects at the gate |
+| `--revise <feedback>` | revision feedback for the draft review gate (passed through to `topic`) | none (approve path) |
+| `--force` | explicit operator approval to replace an existing artifact (passed through to `topic`) | off — never overwrite without it |
+
+Flags may appear in any order; the first bare positional token is the topic phrase. An unknown
+operation (anything other than `create`) fails loud and lists `create` as the only valid operation.
+
+## References (loaded on demand, R2)
+
+| File | When to load |
+| --- | --- |
+| `references/generic-craft.md` | **always** on every `create` run — the five IT-writing disciplines |
+| `references/platform-english.md` | `--playbook english` — X / Medium / Substack playbook |
+| `references/platform-wechat.md` | `--playbook wechat` — WeChat Official Account playbook |
+| `references/skill-authoring.md` | when reviewing or editing this skill — why it stays lean |
+
+The four STORM studies remain in the works dirs (`~/.config/kk/works/`) as provenance; the skill
+body and references do **not** vendor the full reports (D4).
+
+## Artifact contract (reuses topic, D5)
+
+All paths are relative to the workspace `--dir`. This skill does **not** invent a parallel
+workspace — it delegates to `topic`, which writes exactly these paths:
+
+| Artifact | Path | Written by |
+| --- | --- | --- |
+| Brief | `brief.md` | `topic` `init` |
+| Outline options | `2-outline/outline-option-{a,b,c}.md` | `topic` `outline` |
+| Approved outline | `2-outline/outline-approved.md` | `topic` `outline` (after selection gate) |
+| Draft | `3-draft/draft-article.md` | `topic` `draft` (from approved outline, review gate) |
+
+## create sequence
+
+1. **Input check** (fail loud, R5): empty topic and no `--brief` → stop with recovery. A `--brief`
+   path that does not exist → stop with recovery.
+2. **Target check** (fail loud, R5): if `--dir` exists with a `brief.md` and no `--force` → stop
+   with recovery ("initialization target already exists at `<dir>`; pass `--force` after explicit
+   operator confirmation to replace, or choose a new `--dir`"). Never overwrite without `--force`.
+3. **Load the method** — read `references/generic-craft.md` (always) plus the selected playbook if
+   `--playbook` is not `generic` (R2). If `--research` and the workspace has no reusable evidence,
+   invoke `storm-research` on the topic (XOR: a topic phrase or `--in <file>`); re-run research
+   only when the query or sources must change — reuse existing `docs.json` otherwise.
+4. **Delegate to `topic`** — run `topic create` against `--dir` with the same artifact contract and
+   gates: outline options → explicit selection gate (`--outline <a|b|c>` or interactive) → approved
+   outline → draft → review gate (approve or bounded `--revise`). This skill never reimplements
+   those gates (R1, R3).
+5. **Apply the method while drafting** — using the loaded references, apply the five disciplines
+   (one goal per document, value proposition as scope firewall, explicit prerequisites and POLA,
+   show-don't-tell with diagrams/examples, accessibility) plus the platform playbook's constraints
+   (e.g. WeChat mobile formatting or English-platform framing). The draft is written by `topic`
+   from the approved outline; the method shapes it.
+6. **Optional judge gate** — if `--judge` and `3-draft/draft-article.md` is approved, invoke
+   `content-judge` with the `tech-accuracy` rubric. A non-`PASS` verdict is reported to the operator; it
+   does **not** auto-publish and does not auto-revise past `topic`'s 3-round bound.
+7. **Print** the final artifact paths and stop.
+
+## Fail-loud table (R5)
+
+| Condition | Behavior | Recovery instruction |
+| --- | --- | --- |
+| Empty topic and no `--brief` | Stop; no files created | Provide a topic phrase or `--brief <path>` |
+| `--brief` path does not exist | Stop; no files created | Check the path; supply a real Markdown brief |
+| `--research` with neither topic nor `--in` | Stop; nothing written | Pass exactly one of the topic / `--in <file>` to `storm-research` |
+| Missing prerequisite artifact (e.g. outline before draft) | Stop; nothing written | The recovery comes from `topic` — run the prerequisite step first (see `topic` fail-loud table) |
+| Existing initialization target without `--force` | Stop; no overwrite | Confirm with the operator and pass `--force`, or choose a new `--dir` |
+| Unknown operation | Stop; nothing written | Use `create` (the only operation) or call `topic` / `storm-research` / `content-judge` directly |
+
+Every stop names the exact missing or existing path and the exact next command. Never silently
+skip, never auto-replace, never delete.
+
+## Invariants
+
+- `create` is the **only** operation. Research, illustration, adaptation, and publish operations
+  are **not** added to `topic` — this skill delegates to `storm-research` / `content-judge` (R3).
+- Reuse `topic` artifact paths; never invent a parallel workspace (D5).
+- `topic` / `storm-research` / `content-judge` contracts are unchanged (D6) — this skill only orchestrates.
+- No `plugins/kk/commands/itc*.md`, no `kk` CLI noun/verb, no generator `plugin.json` (R4).
+- Never overwrite an existing artifact without `--force`; bound draft revision at `topic`'s 3
+  rounds.
+- No live publish, no external side effects beyond the delegated research call, no image generation.
+
+## Prompt template (Skill() / agent.run)
+
+```
+Skill(skill="itc-generating",
+  args="<topic-or-brief> [--dir <target>] [--brief <path>] [--playbook generic|english|wechat] [--research] [--judge] [--outline <a|b|c>] [--revise <feedback>] [--force]")
+```
+
+When invoked, follow the `create` sequence above. Load the references the flags select, delegate
+outline selection and draft review to `topic`, and pause for the operator at `topic`'s gates. On
+any stop, output the fail-loud recovery line. The artifact paths under the workspace `--dir` are
+the handoff.

package/plugins/kk/skills/itc-generating/references/generic-craft.md

@@ -0,0 +1,80 @@
+# Generic IT-writing craft — five disciplines
+
+Distilled from the STORM study "How to Write the Best Generic IT Technical Documentation"
+(works dir `how-to-write-the-best-generic-it-technical-docum-0a71c5a7`, provenance only — this
+reference replaces vendoring the full report). Load this reference on every `create` run; apply
+all five disciplines while authoring the draft.
+
+## 1. Structure and scope (the document architect)
+
+- Pick the document types you actually need — and **stop**. There is no universal list; add a
+  document only when no existing one's goal absorbs the content.
+- **One document, one goal**, enforced at review: reread after writing and remove or move
+  anything that does not serve that goal. Write everything first, then cut.
+- **Write the Value Proposition (VP) first**: a one-page list of what the doc will do for its
+  reader (save time, reduce errors, cut training…). It says nothing about format or fonts. Use it
+  as a scope-creep firewall — keep content that supports a VP item, remove the rest.
+- **Plan before writing**: research first (history → latest literature → what existing docs
+  already cover), then a documentation plan (scope, objectives, estimates, workflows, resources).
+  Do not over-invest in placement up front — move a document after it exists.
+- **One goal per section** too: link out to other documents for prerequisites and detail instead
+  of inlining everything.
+
+## 2. Write for the reader (the reader advocate)
+
+- **Profile the readership** enough to structure and customize for them. Do not assume background,
+  environment, context, or that they have read your other docs — link prerequisites instead of
+  inlining them.
+- **Show, don't tell**: lead with diagrams (process flows, C4 views), then explain in prose.
+  Text-based diagrams (Mermaid, PlantUML) stay easy to update. Use at least one concrete example
+  early — a simple example beats an abstract description.
+- **Principle of Least Astonishment (POLA)**: cover the gotchas and non-typical usage up front —
+  undocumented prerequisites, surprising defaults, implicit ordering. Name assumptions, defaults,
+  and prerequisites explicitly.
+- **Long-form craft**: a succinct, jargon-free title; structure against the five Ws + H; write the
+  introduction last, once the content has settled.
+- **Accessibility and inclusive writing** are concrete requirements: follow accessibility
+  guidelines for structure/language; use inclusive example names and bias-free language.
+
+## 3. Make it a team discipline (the engineering manager)
+
+- **Budget for docs time**: measure how long SME review of writer output takes and factor it into
+  each release. Good docs are written once, read hundreds of times.
+- **Close the specialized-skill gap**: technical writing is its own discipline (audience
+  understanding + logical presentation); bring in a technical writer or build review processes
+  that treat writing with the same rigor as code.
+- **Embed docs in the engineering workflow**: docs reviews inside normal PR review, preview builds
+  on each check-in, docs as part of shipping every release — not a post-release afterthought.
+- **Docs are coordination infrastructure** at team scale: they improve knowledge retention and
+  underpin quality, consistency, and compliance.
+- **Build documentation mindshare**: state the problem, start in engineering, gather input
+  broadly, build a taxonomy, make contribution easy, meet regularly.
+
+## 4. Keep it fresh (the maintenance owner)
+
+- **Docs go stale by default**; the countermeasure is procedural — assess doc impact of changes
+  each sprint and allocate update time in the release.
+- **Make updates cheap**: prefer simple human-readable formats (Markdown — diffable in Git) and
+  text-based diagrams so edits stay cheap.
+- **Institutionalize the lifecycle**: plan → write → review → publish, with research up front and
+  maintenance at the end; take occasional content inventories and use reader feedback to fill gaps.
+
+## 5. Tooling and publishing (the pipeline engineer)
+
+- **Match tools to doc types and languages**; when in doubt, defer to Markdown and tooling with
+  simple human-readable formats. A convenient editor matters — you won't write docs you hate
+  editing.
+- **Bake publishing into CI/CD**: build docs from sources and publish on every release; generate
+  docs from code artifacts where possible (OpenAPI is the canonical example).
+- **Plan reuse**: write content once and reuse it (CCMS for cross-product scale); audit for
+  overlap before duplication spreads.
+- **Adopt (or author) style guides**: shared style guides keep output consistent — don't write
+  them from scratch (Write the Docs maintains a living one). During review, get the right experts
+  on the right documents and use preview runs to catch errors before publication.
+
+## Applying this in `create`
+
+While drafting `3-draft/draft-article.md` (after `topic`'s outline gate), apply: one goal per
+document enforced at the draft-review gate; the Value Proposition as a scope firewall; explicit
+prerequisites and POLA; show-don't-tell with diagrams/examples; and accessibility. The `--judge`
+gate then verifies technical accuracy against the rubric.