@netnodeag/kraftwerk 0.10.2 → 0.12.0

package/README.md

@@ -1,5 +1,26 @@
 # kraftwerk
 
+**Agentic workspace.** Kraftwerk is an open-source agentic workspace for
+teams. It is where people and AI agents get work done together.
+
+**Why it exists.** AI work often lives in individual silos: personal prompts,
+Claude Code sessions, scripts, and one-off automations. Kraftwerk turns that
+into shared, repeatable ways of working across a team or organisation.
+
+**How it works.** Kraftwerk brings together:
+
+- **Agents** — Claude Code, Codex, Pi, and others
+- **Skills** — reusable capabilities and ways of working
+- **Knowledge** — shared organisational and project context
+- **Workflows** — repeatable multi-step processes
+- **Verification** — deterministic gates that check the work
+
+**The shift.** From everyone using AI individually → to the organisation
+working agentically. Kraftwerk is the shared place where that work lives,
+runs, and improves over time.
+
+## Under the hood
+
 Deterministic workflow-as-code over headless agent harnesses, in the spirit of
 [super-simple-software-factory](https://github.com/disler/super-simple-software-factory):
 **code owns the control flow, agents work inside bounded phases.**

package/dist/cli/init.js

@@ -21,6 +21,7 @@ workflows: ${DATA_DIR}/workflows   # where workflows live
 output: ${DATA_DIR}/output         # where run artifacts land (git-ignored)
 knowledge: ${DATA_DIR}/knowledge   # OKF knowledge bundles
 agents: ${DATA_DIR}/agents         # team agent definitions
+skills: ${DATA_DIR}/skills         # workspace skills (shared instruction packages)
 `;
 const WORKFLOW_TEMPLATE = `# yaml-language-server: $schema=${SCHEMA_URL}
 name: hello
@@ -62,6 +63,19 @@ const AGENT_SYSTEM_TEMPLATE = `You are Max, this project's workflow runner. You
 project's kraftwerk workflows, and you consult the knowledge bundles you
 have access to before answering questions they cover.
 `;
+const SKILL_TEMPLATE = `---
+name: daily-summary
+description: Summarize what happened in this workspace today (runs, knowledge updates)
+---
+
+# Daily summary
+
+When invoked, produce a short summary of today's activity in this workspace:
+
+1. List today's workflow runs and their status.
+2. Mention knowledge concepts updated today, if any.
+3. Keep it under 10 lines, plain markdown.
+`;
 const DEMO_BUNDLE = "demo-customer-support";
 const DEMO_CONCEPT = `---
 type: Playbook
@@ -96,6 +110,8 @@ export async function runInit(cwd) {
     // Team agent "max".
     await put(`${DATA_DIR}/agents/max/agent.yml`, AGENT_YML_TEMPLATE);
     await put(`${DATA_DIR}/agents/max/system.md`, AGENT_SYSTEM_TEMPLATE);
+    // Example workspace skill.
+    await put(`${DATA_DIR}/skills/daily-summary/SKILL.md`, SKILL_TEMPLATE);
     // Demo knowledge bundle, through the canonical OKF write path so
     // index.md and log.md come out consistent.
     const knowledgeRoot = path.join(cwd, DATA_DIR, "knowledge");

package/dist/config.d.ts

@@ -16,6 +16,7 @@
  *   output: output             # run-artifact directory, relative to the file
  *   knowledge: knowledge       # OKF knowledge-bundle root, relative to the file
  *   agents: agents             # team agent-definition root, relative to the file
+ *   skills: skills             # workspace skill root, relative to the file
  */
 /** Stable, versionless URL of the workflow JSON schema (editor validation). */
 export declare const SCHEMA_URL = "https://raw.githubusercontent.com/NETNODEAG/kraftwerk/main/kraftwerk/schema/workflow.schema.json";
@@ -37,6 +38,8 @@ export interface ProjectConfig {
     knowledge?: string;
     /** Team agent-definition root relative to the project root. Default: agents */
     agents?: string;
+    /** Workspace skill root relative to the project root. Default: skills */
+    skills?: string;
 }
 export interface Project {
     /** Absolute project root the CLI operates on. */

package/dist/config.js

@@ -19,6 +19,7 @@ import { parse } from "yaml";
  *   output: output             # run-artifact directory, relative to the file
  *   knowledge: knowledge       # OKF knowledge-bundle root, relative to the file
  *   agents: agents             # team agent-definition root, relative to the file
+ *   skills: skills             # workspace skill root, relative to the file
  */
 /** Stable, versionless URL of the workflow JSON schema (editor validation). */
 export const SCHEMA_URL = "https://raw.githubusercontent.com/NETNODEAG/kraftwerk/main/kraftwerk/schema/workflow.schema.json";
@@ -88,10 +89,10 @@ async function loadConfig(configPath) {
     if (raw === null || raw === undefined)
         return {};
     if (typeof raw !== "object" || Array.isArray(raw)) {
-        throw new Error(`${path.basename(configPath)}: expected a mapping (name, icon, port, workflows, output, knowledge, agents)`);
+        throw new Error(`${path.basename(configPath)}: expected a mapping (name, icon, port, workflows, output, knowledge, agents, skills)`);
     }
     const config = raw;
-    const known = ["name", "icon", "port", "workflows", "output", "knowledge", "agents"];
+    const known = ["name", "icon", "port", "workflows", "output", "knowledge", "agents", "skills"];
     for (const key of Object.keys(config)) {
         if (!known.includes(key)) {
             throw new Error(`${path.basename(configPath)}: unknown key "${key}" (allowed: ${known.join(", ")})`);

package/dist/inspector/chat/sessions.js

@@ -25,6 +25,7 @@ async function loadState(id) {
         busy: false,
         pendingPermissions: new Map(),
         writeChain: Promise.resolve(),
+        needsContext: true,
     };
     // Two racing loads: keep whichever registered first.
     return states.get(id) ?? (states.set(id, state), state);
@@ -46,8 +47,8 @@ function emit(state, ev) {
 }
 /* ---------- skills ---------- */
 /**
- * Skills visible to a chat: every discovered skill (project + user
- * .claude/skills), narrowed by the team member's allowlist when the chat
+ * Skills visible to a chat: every discovered skill (workspace skills root
+ * + .claude/skills roots), narrowed by the team member's allowlist when the chat
  * is a team session (absent allowlist = all, empty = none).
  */
 async function availableSkills(scope) {
@@ -211,15 +212,25 @@ async function baseScopeContext(scope, agent) {
     }
     return "";
 }
+/**
+ * Every chat renders in the inspector UI, so agents should know two things:
+ * replies are markdown, and run artifacts are addressable over the
+ * inspector's own file endpoint (relative URLs keep working wherever the
+ * inspector is reachable — localhost, LAN, tunnel).
+ */
+const RENDERING_BLOCK = `## Chat rendering\n` +
+    `Your replies render as markdown in the inspector chat: headings, lists, tables, code blocks, ` +
+    `links and images all work. Files inside a workflow run's output folder are served by the ` +
+    `inspector itself at /api/runs/<run-id>/file?name=<relative-path>&raw=1 — embed an image inline ` +
+    `with ![alt](/api/runs/<run-id>/file?name=picture.png&raw=1), or link any artifact the same way. ` +
+    `Prefer these relative /api/... URLs over file paths when showing results: they render directly ` +
+    `in this chat and keep working wherever the inspector is reachable.`;
 async function scopeContext(scope, agent) {
     const [base, skills] = await Promise.all([
         baseScopeContext(scope, agent),
         availableSkills(scope),
     ]);
-    const block = skillsBlock(skills);
-    if (!block)
-        return base;
-    return base ? `${base}\n\n${block}` : block;
+    return [base, RENDERING_BLOCK, skillsBlock(skills)].filter(Boolean).join("\n\n");
 }
 /* ---------- backend lifecycle ---------- */
 /** Team chats carry the member's model/effort; resolved live so edits apply to new backends. */
@@ -280,6 +291,9 @@ async function ensureBackend(state) {
         agent === "pi"
             ? startPiBackend(cwd, hooks, tuning)
             : await startAcpBackend(agent, cwd, hooks, tuning);
+    // Fresh process = fresh context window: re-send scope context with the
+    // next prompt (matters for chats resumed after an inspector restart).
+    state.needsContext = true;
     return state.backend;
 }
 /* ---------- public API (used by server.ts) ---------- */
@@ -304,6 +318,7 @@ export async function createChat(opts) {
         busy: false,
         pendingPermissions: new Map(),
         writeChain: Promise.resolve(),
+        needsContext: true,
     });
     return meta;
 }
@@ -338,7 +353,10 @@ export async function postMessage(id, text) {
     void (async () => {
         try {
             const backend = await ensureBackend(state);
-            const context = isFirst ? await scopeContext(state.meta.scope, state.meta.agent) : "";
+            const context = state.needsContext
+                ? await scopeContext(state.meta.scope, state.meta.agent)
+                : "";
+            state.needsContext = false;
             // "/<skill> args" expands to the skill's instructions for the agent;
             // the thread keeps the short form the user typed.
             const body = await expandSkillInvocation(state.meta.scope, text);

package/dist/inspector/server.js

@@ -9,7 +9,7 @@ import { dockerStatus, triggerRun, stopRun } from "./runner.js";
 import { cancelChat, createChat, deleteChat, getChat, listChats, postMessage, resolvePermission, subscribeChat, } from "./chat/sessions.js";
 import { bundleDetail, conceptDetail, createBundle, knowledgeIndex, putConcept, verifyFromUi, } from "./knowledge.js";
 import { deleteMember, getMember, listMembers, saveMember, teamRoot, } from "./team.js";
-import { listSkills } from "./skills.js";
+import { getSkill, listSkills, skillsRoot } from "./skills.js";
 import { deleteRoutine, routineStatuses, runRoutineNow, saveRoutine, startRoutineScheduler, } from "./routines.js";
 /**
  * The inspector server: a plain node:http server with no dependencies.
@@ -249,9 +249,15 @@ async function handleApi(req, res, url) {
             return json(res, { error: err.message }, 400);
         }
     }
-    // GET /api/skills — discovered skills (project + user .claude/skills)
+    // GET /api/skills — discovered skills (workspace root + .claude/skills + ~/.claude/skills)
     if (seg.length === 2 && seg[1] === "skills" && method === "GET") {
-        return json(res, { skills: await listSkills() });
+        const [root, skills] = await Promise.all([skillsRoot(), listSkills()]);
+        return json(res, { root, skills });
+    }
+    // GET /api/skills/:name — one skill with SKILL.md content + bundled files
+    if (seg.length === 3 && seg[1] === "skills" && method === "GET") {
+        const skill = await getSkill(decodeURIComponent(seg[2]));
+        return skill ? json(res, skill) : json(res, { error: "not found" }, 404);
     }
     // GET/POST /api/team — member list / create a member
     if (seg.length === 2 && seg[1] === "team") {

package/dist/inspector/skills.d.ts

@@ -1,14 +1,17 @@
 /**
  * Skills: reusable instruction packages for chats, discovered from the
  * Claude-style skill layout — one folder per skill holding a SKILL.md with
- * YAML frontmatter (name, description). Two roots are scanned:
+ * YAML frontmatter (name, description). Three roots are scanned:
  *
- *   <projectRoot>/.claude/skills/<name>/SKILL.md   (git-tracked, per project)
- *   ~/.claude/skills/<name>/SKILL.md               (personal, per user)
+ *   <projectRoot>/<skills root>/<name>/SKILL.md    (workspace, git-tracked;
+ *                                                   kraftwerk.yml `skills`, default skills/)
+ *   <projectRoot>/.claude/skills/<name>/SKILL.md   (project .claude, git-tracked)
+ *   ~/.claude/skills/<name>/SKILL.md               (global, this machine only)
  *
- * A project skill shadows a user skill with the same name. Skills are
- * surfaced to every chat as context (and expanded on /<name> invocation),
- * so they work identically on claude, codex, and pi.
+ * Workspace skills are the shared, first-class ones; a workspace skill
+ * shadows a same-named project skill, which shadows a same-named global
+ * skill. Skills are surfaced to every chat as context (and expanded on
+ * /<name> invocation), so they work identically on claude, codex, and pi.
  */
 export interface SkillInfo {
     /** Frontmatter `name`, falling back to the folder name. */
@@ -18,9 +21,20 @@ export interface SkillInfo {
     path: string;
     /** Absolute path to the skill folder (for harnesses that take a dir). */
     dir: string;
-    source: "project" | "user";
+    /** workspace = kraftwerk skills root; project = .claude/skills; user = ~/.claude/skills. */
+    source: "workspace" | "project" | "user";
 }
-/** All discovered skills; a project skill shadows a same-named user skill. */
+export interface SkillDetail extends SkillInfo {
+    /** Full SKILL.md contents. */
+    content: string;
+    /** Non-SKILL.md files bundled in the skill folder (relative paths). */
+    files: string[];
+}
+/** Absolute workspace skills root (kraftwerk.yml `skills`, default skills/). */
+export declare function skillsRoot(): Promise<string>;
+/** All discovered skills; workspace shadows project shadows user (global). */
 export declare function listSkills(): Promise<SkillInfo[]>;
 /** Read a skill's SKILL.md contents (empty string when unreadable). */
 export declare function readSkill(skill: SkillInfo): Promise<string>;
+/** One skill by name (post-shadowing), with SKILL.md content + bundled files. */
+export declare function getSkill(name: string): Promise<SkillDetail | null>;

package/dist/inspector/skills.js

@@ -2,6 +2,7 @@ import { promises as fs } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { parse } from "yaml";
+import { resolveProject } from "../config.js";
 import { getProjectRoot } from "./context.js";
 const NAME_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/i;
 function frontmatter(md) {
@@ -16,6 +17,12 @@ function frontmatter(md) {
         return {};
     }
 }
+/** Absolute workspace skills root (kraftwerk.yml `skills`, default skills/). */
+export async function skillsRoot() {
+    const project = await resolveProject(getProjectRoot()).catch(() => null);
+    const root = project?.root ?? getProjectRoot();
+    return path.resolve(root, project?.config.skills ?? "skills");
+}
 async function scanRoot(root, source) {
     let entries;
     try {
@@ -50,16 +57,45 @@ async function scanRoot(root, source) {
     }));
     return skills.filter(Boolean).sort((a, b) => a.name.localeCompare(b.name));
 }
-/** All discovered skills; a project skill shadows a same-named user skill. */
+/** All discovered skills; workspace shadows project shadows user (global). */
 export async function listSkills() {
-    const [project, user] = await Promise.all([
+    const [workspace, project, user] = await Promise.all([
+        skillsRoot().then((root) => scanRoot(root, "workspace")),
         scanRoot(path.join(getProjectRoot(), ".claude", "skills"), "project"),
         scanRoot(path.join(os.homedir(), ".claude", "skills"), "user"),
     ]);
-    const seen = new Set(project.map((s) => s.name.toLowerCase()));
-    return [...project, ...user.filter((s) => !seen.has(s.name.toLowerCase()))];
+    const out = [...workspace];
+    const seen = new Set(out.map((s) => s.name.toLowerCase()));
+    for (const s of [...project, ...user]) {
+        if (seen.has(s.name.toLowerCase()))
+            continue;
+        seen.add(s.name.toLowerCase());
+        out.push(s);
+    }
+    return out;
 }
 /** Read a skill's SKILL.md contents (empty string when unreadable). */
 export function readSkill(skill) {
     return fs.readFile(skill.path, "utf8").catch(() => "");
 }
+/** One skill by name (post-shadowing), with SKILL.md content + bundled files. */
+export async function getSkill(name) {
+    const skill = (await listSkills()).find((s) => s.name.toLowerCase() === name.toLowerCase());
+    if (!skill)
+        return null;
+    const content = await readSkill(skill);
+    const files = [];
+    const walk = async (dir, rel) => {
+        const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+        for (const e of entries) {
+            if (e.name.startsWith("."))
+                continue;
+            if (e.isDirectory())
+                await walk(path.join(dir, e.name), `${rel}${e.name}/`);
+            else if (`${rel}${e.name}` !== "SKILL.md")
+                files.push(`${rel}${e.name}`);
+        }
+    };
+    await walk(skill.dir, "");
+    return { ...skill, content, files: files.sort() };
+}