@gobing-ai/knowledge-kit 0.0.6 → 0.0.8

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

@@ -0,0 +1,101 @@
+"$schema": "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
+kind: state-machine
+name: judge-gated-publish
+description: "Example workflow where an LLM-as-judge agent.run step gates a publish transition"
+initialState: generate
+terminalStates:
+  - done
+  - failed
+failureStates:
+  - failed
+vars:
+  contentFile: ".spur/run/content.json"
+  verdictFile: ".spur/run/verdict.json"
+  rubric: "general"
+  maxRetries: "2"
+  # attempt is mutated by the revise loop; initialize to 0.
+  attempt: "0"
+  spurBin: "spur"
+states:
+  - id: generate
+    description: "Generate content from brief or docs (kk invoke <generator>)"
+    onEnter:
+      - kind: shell
+        options:
+          # 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...'"
+  - 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
+      # 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.
+      - kind: agent.run
+        options:
+          role: reviewer
+          input: |
+            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.
+            Print the verdict path as the last line of stdout.
+          expectFile: ${vars.verdictFile}
+  - id: publish
+    description: "Publish content after clearing judge gate (kk fanout)"
+    onEnter:
+      - kind: shell
+        options:
+          command: "echo 'publishing content...'"
+  - id: done
+    description: "Publish completed successfully"
+  - id: failed
+    description: "Judge rejected content (FAIL) or retries exhausted (NEEDS_REVISION)"
+
+transitions:
+  - from: generate
+    to: judge
+    description: "Content generated -> proceed to evaluation"
+    guard:
+      kind: always
+
+  # PASS -> publish.
+  - from: judge
+    to: publish
+    description: "Judge verdict is PASS (or file absent under --dry-run) -> proceed to publish"
+    guard:
+      kind: shell
+      options:
+        # Fail-closed on an explicit non-PASS verdict; fail-open only when the file is
+        # absent, which happens under --dry-run (actions are skipped, so the judge
+        # never writes its verdict). A real run always has the file.
+        command: 'v="$(jq -r .verdict ${vars.verdictFile} 2>/dev/null)"; test -z "$v" -o "$v" = PASS'
+
+  # NEEDS_REVISION -> back to generate with a bounded retry budget.
+  - from: judge
+    to: generate
+    description: "Judge verdict is NEEDS_REVISION and retry budget remains -> regenerate with feedback"
+    guard:
+      kind: shell
+      options:
+        # Allow the revise loop only while the attempt counter is below maxRetries.
+        # The shell kind cannot mutate vars, so the host (or a sidecar note action) is
+        # responsible for incrementing attempt on each loop in a real run.
+        command: 'v="$(jq -r .verdict ${vars.verdictFile} 2>/dev/null)"; test "$v" = NEEDS_REVISION -a "$attempt" -lt "$maxRetries"'
+
+  # FAIL, or NEEDS_REVISION with no retries left -> failed.
+  - from: judge
+    to: failed
+    description: "Judge verdict is FAIL, or NEEDS_REVISION with retries exhausted -> block publish"
+    guard:
+      kind: shell
+      options:
+        command: 'v="$(jq -r .verdict ${vars.verdictFile} 2>/dev/null)"; test -n "$v" && { test "$v" = FAIL || test "$v" = NEEDS_REVISION -a "$attempt" -ge "$maxRetries"; }'
+
+  - from: publish
+    to: done
+    description: "Publish done"
+    guard:
+      kind: always

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

@@ -0,0 +1,72 @@
+# Linear state-machine workflow template for knowledge-kit plugin platform:
+# ingest -> generate -> publish -> done.
+"$schema": "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
+name: kk-ingest-generate-publish
+kind: state-machine
+description: Chained ingestion, generator, and publish plugins via kk executor run
+initialState: ingest
+terminalStates:
+  - done
+  - failed
+vars:
+  ingestion_plugin: "karakeep-local"
+  generator_plugin: "content-gen"
+  publish_plugin: "surfdash-pub"
+  source: "./source"
+  work_dir: "./work"
+  plugins_path: "./plugins"
+
+states:
+  - id: ingest
+    description: Run ingestion plugin to produce document list (docs.json)
+    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}
+
+  - 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}
+
+  - 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}
+
+  - id: done
+    description: Terminal — all three plugin steps succeeded
+  - id: failed
+    description: Terminal — one of the plugin run steps failed
+
+transitions:
+  - from: ingest
+    to: generate
+    description: Ingest succeeded — proceed to content generation
+    guard:
+      kind: action-ok
+  - from: ingest
+    to: failed
+    description: Ingest failed — terminate workflow
+
+  - from: generate
+    to: publish
+    description: Content generation succeeded — proceed to publish
+    guard:
+      kind: action-ok
+  - from: generate
+    to: failed
+    description: Generator failed — terminate workflow
+
+  - from: publish
+    to: done
+    description: Publish succeeded — workflow complete
+    guard:
+      kind: action-ok
+  - from: publish
+    to: failed
+    description: Publish failed — terminate workflow

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

@@ -0,0 +1,285 @@
+---
+"$schema": "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
+name: kk-itc
+kind: state-machine
+description: >-
+  IT content authoring pipeline using topic/itc-generating, Spur HITL gates, and optional judging
+initialState: prepare
+terminalStates:
+  - done
+  - failed
+failureStates:
+  - failed
+
+vars:
+  topic: ""
+  input_file: ""
+  work_dir: ""
+  writer: "itc-generating"
+  playbook: "generic"
+  research: "false"
+  judge: "false"
+  outline: ""
+  force: "false"
+  rubric: "tech-accuracy"
+  verdictFile: ".spur/run/${vars.__runId}-itc-verdict.json"
+  agent: ""
+  __runId: "itc"
+  __hitlAnswer: ""
+  __hitlInput: ""
+
+states:
+  - id: prepare
+    description: "mkdir work_dir, 2-outline, 3-draft; validate XOR topic/input_file; write brief.md"
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            set -e;
+            if [ -z "${vars.work_dir}" ]; then
+              echo "missing work_dir" >&2; exit 1;
+            fi;
+            mkdir -p "${vars.work_dir}" "${vars.work_dir}/2-outline" "${vars.work_dir}/3-draft";
+            if [ -n "${vars.topic}" ] && [ -n "${vars.input_file}" ]; then
+              echo "XOR violation: both topic and input_file set" >&2; exit 1;
+            fi;
+            if [ -z "${vars.topic}" ] && [ -z "${vars.input_file}" ]; then
+              echo "XOR violation: neither topic nor input_file set" >&2; exit 1;
+            fi;
+            if [ -f "${vars.work_dir}/brief.md" ] && [ "${vars.force}" != "true" ]; then
+              echo "initialization target already exists at ${vars.work_dir}/brief.md; pass force=true to replace" >&2; exit 1;
+            fi;
+            if [ -n "${vars.topic}" ]; then
+              printf '%s\n' "${vars.topic}" > "${vars.work_dir}/brief.md";
+            else
+              if [ ! -f "${vars.input_file}" ]; then
+                echo "input file not found: ${vars.input_file}" >&2; exit 1;
+              fi;
+              cp "${vars.input_file}" "${vars.work_dir}/brief.md";
+            fi;
+
+  - id: research
+    description: "Conduct preliminary topic research via storm-research (agent.run)"
+    onEnter:
+      - kind: agent.run
+        options:
+          role: scribe
+          agent: ${vars.agent}
+          input: |
+            Load plugins/kk/skills/storm-research/SKILL.md.
+            Run storm-research on the topic or input file specified in the brief at ${vars.work_dir}/brief.md.
+
+  - id: outline-write
+    description: "Generate outline options a, b (and optional c) via writer skill (agent.run)"
+    onEnter:
+      - kind: agent.run
+        options:
+          role: scribe
+          agent: ${vars.agent}
+          input: |
+            Load plugins/kk/skills/${vars.writer}/SKILL.md.
+            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
+      - kind: shell
+        options:
+          command: >-
+            test -f "${vars.work_dir}/2-outline/outline-option-b.md" || { echo "missing required outline-option-b.md" >&2; exit 1; }
+
+  - id: outline-select
+    description: "Operator selects preferred outline option"
+    pause: true
+    onEnter:
+      - kind: hitl.select
+        options:
+          prompt: "Select an approved outline option from ${vars.work_dir}/2-outline/ (outline-option-a.md, outline-option-b.md, or outline-option-c.md):"
+          options:
+            - a
+            - b
+            - c
+          var: __hitlAnswer
+
+  - id: outline-commit
+    description: "Copy selected outline to outline-approved.md"
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            sel="${vars.outline}";
+            if [ -z "$sel" ]; then sel="${vars.__hitlAnswer}"; fi;
+            if [ -z "$sel" ]; then sel="a"; fi;
+            src="${vars.work_dir}/2-outline/outline-option-$sel.md";
+            if [ ! -f "$src" ]; then
+              echo "selected outline file not found: $src" >&2; exit 1;
+            fi;
+            cp "$src" "${vars.work_dir}/2-outline/outline-approved.md";
+
+  - id: draft-write
+    description: "Author full technical draft from approved outline (agent.run)"
+    onEnter:
+      - kind: agent.run
+        options:
+          role: scribe
+          agent: ${vars.agent}
+          input: |
+            Load plugins/kk/skills/${vars.writer}/SKILL.md.
+            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
+
+  - id: draft-review
+    description: "Operator reviews and approves or requests revision on draft-article.md"
+    pause: true
+    onEnter:
+      - kind: hitl.confirm
+        options:
+          prompt: "Review draft at ${vars.work_dir}/3-draft/draft-article.md. Approve?"
+          var: __hitlAnswer
+
+  - id: draft-revise
+    description: "Collect revision feedback from operator (bounded by 3 rounds)"
+    pause: true
+    onEnter:
+      - 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";
+      - kind: hitl.input
+        options:
+          prompt: "Provide specific revision feedback for ${vars.work_dir}/3-draft/draft-article.md:"
+          var: __hitlInput
+
+  - id: judge
+    description: "Evaluate technical draft with content-judge (agent.run)"
+    onEnter:
+      - kind: agent.run
+        options:
+          role: reviewer
+          agent: ${vars.agent}
+          input: |
+            Load plugins/kk/skills/content-judge/SKILL.md and its references/rubrics.md.
+            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.
+            Print the verdict path as the last line of stdout.
+          expectFile: ${vars.verdictFile}
+
+  - id: done
+    description: "Terminal — IT content draft generated and approved successfully"
+  - id: failed
+    description: "Terminal — IT content workflow failed or rejected"
+
+transitions:
+  - from: prepare
+    to: research
+    description: "Research enabled -> proceed to storm-research"
+    guard:
+      kind: shell
+      options:
+        command: 'test "${vars.research}" = "true"'
+
+  - from: prepare
+    to: outline-write
+    description: "Research disabled -> proceed directly to outline generation"
+    guard:
+      kind: shell
+      options:
+        command: 'test "${vars.research}" != "true"'
+
+  - from: research
+    to: outline-write
+    description: "Research completed -> proceed to outline generation"
+    guard:
+      kind: always
+
+  - from: outline-write
+    to: outline-select
+    description: "Outline not pre-selected -> pause for operator selection"
+    guard:
+      kind: shell
+      options:
+        command: 'test -z "${vars.outline}"'
+
+  - from: outline-write
+    to: outline-commit
+    description: "Outline pre-selected -> skip interactive selection"
+    guard:
+      kind: shell
+      options:
+        command: 'test -n "${vars.outline}"'
+
+  - from: outline-select
+    to: outline-commit
+    description: "Outline selected -> commit approved outline"
+    guard:
+      kind: always
+
+  - from: outline-commit
+    to: draft-write
+    description: "Approved outline committed -> write draft"
+    guard:
+      kind: always
+
+  - from: draft-write
+    to: draft-review
+    description: "Draft written -> pause for operator review"
+    guard:
+      kind: always
+
+  - from: draft-review
+    to: judge
+    description: "Draft approved and judge enabled -> evaluate quality"
+    guard:
+      kind: shell
+      options:
+        command: '{ test -z "${vars.__hitlAnswer}" || test "${vars.__hitlAnswer}" = "yes"; } && test "${vars.judge}" = "true"'
+
+  - from: draft-review
+    to: done
+    description: "Draft approved and judge disabled -> complete workflow"
+    guard:
+      kind: shell
+      options:
+        command: '{ test -z "${vars.__hitlAnswer}" || test "${vars.__hitlAnswer}" = "yes"; } && test "${vars.judge}" != "true"'
+
+  - from: draft-review
+    to: draft-revise
+    description: "Draft rejected with revision budget remaining -> collect feedback"
+    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; }'
+
+  - from: draft-review
+    to: failed
+    description: "Draft rejected with revision budget exhausted -> fail"
+    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; }'
+
+  - from: draft-revise
+    to: draft-write
+    description: "Feedback collected -> rewrite draft"
+    guard:
+      kind: always
+
+  - from: judge
+    to: done
+    description: "Judge verdict is PASS (or empty in dry-run) -> complete workflow"
+    guard:
+      kind: shell
+      options:
+        command: 'v="$(jq -r .verdict ${vars.verdictFile} 2>/dev/null)"; test -z "$v" -o "$v" = PASS'
+
+  - from: judge
+    to: failed
+    description: "Judge verdict is not PASS -> fail"
+    guard:
+      kind: shell
+      options:
+        command: 'v="$(jq -r .verdict ${vars.verdictFile} 2>/dev/null)"; test -n "$v" -a "$v" != PASS'