@okf-harness/agent-pack 0.1.0

package/README.md

@@ -0,0 +1,14 @@
+# @okf-harness/agent-pack
+
+Adapter renderer package for OKF Harness agent guidance. It renders shared Claude Code and Codex instructions from one source so workspace setup stays consistent across supported agents.
+
+OKF Harness is an independent open-source project built on [Andrej Karpathy's LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern and Google's [Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) / [OKF specification](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md).
+
+Most users should install the CLI instead:
+
+```bash
+npm install -g @okf-harness/cli
+okfh doctor --json
+```
+
+For project overview, workflows, and security notes, see the [main repository README](https://github.com/pumblus/okf-harness#readme).

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+declare const packageInfo: {
+    readonly name: "@okf-harness/agent-pack";
+    readonly role: "agent-pack";
+};
+type PackageInfo = typeof packageInfo;
+type AgentAdapter = "claude" | "codex";
+type AgentInstallTarget = AgentAdapter | "all";
+type RenderedAgentFile = {
+    path: string;
+    contents: string;
+};
+type RenderAgentAdapterOptions = {
+    adapter: AgentAdapter;
+    version?: string;
+};
+type RenderedAgentAdapter = {
+    adapter: AgentAdapter;
+    files: RenderedAgentFile[];
+};
+type ManagedBlockAction = "created" | "inserted" | "replaced" | "unchanged";
+type ManagedBlockResult = {
+    path: string;
+    action: ManagedBlockAction;
+};
+type AgentInstallConflict = {
+    path: string;
+    reason: string;
+};
+type InstallAgentAdaptersOptions = {
+    workspaceRoot: string;
+    adapter: AgentInstallTarget;
+    dryRun?: boolean;
+    force?: boolean;
+};
+type InstallAgentAdaptersResult = {
+    adapter: AgentInstallTarget;
+    dryRun: boolean;
+    writtenFiles: string[];
+    plannedFiles: string[];
+    replacedFiles: string[];
+    skippedFiles: string[];
+    conflicts: AgentInstallConflict[];
+    managedBlocks: ManagedBlockResult[];
+};
+declare function renderAgentAdapter(options: RenderAgentAdapterOptions): RenderedAgentAdapter;
+declare function installAgentAdapters(options: InstallAgentAdaptersOptions): Promise<InstallAgentAdaptersResult>;
+
+export { type AgentAdapter, type AgentInstallConflict, type AgentInstallTarget, type InstallAgentAdaptersOptions, type InstallAgentAdaptersResult, type ManagedBlockAction, type ManagedBlockResult, type PackageInfo, type RenderAgentAdapterOptions, type RenderedAgentAdapter, type RenderedAgentFile, installAgentAdapters, packageInfo, renderAgentAdapter };

package/dist/index.js

@@ -0,0 +1,455 @@
+// src/index.ts
+import { mkdir, readFile, writeFile } from "fs/promises";
+import path from "path";
+var packageInfo = {
+  name: "@okf-harness/agent-pack",
+  role: "agent-pack"
+};
+var defaultVersion = "0.1";
+var managedBlockStart = "<!-- OKF Harness: start -->";
+var managedBlockEnd = "<!-- OKF Harness: end -->";
+var skillTemplates = [
+  {
+    name: "okf-harness-init",
+    title: "OKF Harness Init",
+    description: "Initialize and organize an OKF Harness workspace on macOS, including folders, git, OKF bundle files, and Claude/Codex adapters. Use when the user asks to set up, create, initialize, organize, or install OKF Harness support. Do not use for ingesting an already-added source.",
+    summary: "Use this skill to create a workspace or repair Claude/Codex adapter support.",
+    requiredBehavior: [
+      "Locate or choose the workspace path with the user.",
+      "Use the local shell to run `okfh init <workspace> --name <name> --agents all --json` for first-time setup.",
+      "Use `okfh agent install all --workspace <workspace> --json` to repair adapter files in an existing workspace.",
+      "If the CLI or local shell is unavailable, run `okfh doctor --json` when possible; otherwise stop and tell the user to install OKF Harness instead of hand-writing the workspace structure.",
+      "After initialization, run `okfh status --workspace <workspace> --json` and report the workspace path, lint status, warnings, and next step."
+    ],
+    hardRules: [
+      "Do not create a parallel workspace skeleton by hand.",
+      "Do not overwrite a non-empty directory unless `okfh` returns an explicit safe plan.",
+      "Do not add plugin, hook, Pi, OpenCode, or Obsidian setup.",
+      "Use the same local shell `okfh --json` workflow in Desktop App and TUI sessions.",
+      "Run `git diff` before final response when file changes were made."
+    ],
+    reference: {
+      path: "workflow.md",
+      title: "Init Workflow",
+      body: `# Init Workflow
+
+## First-time setup
+
+Run:
+
+\`\`\`bash
+okfh init <workspace> --name <name> --agents all --json
+\`\`\`
+
+Use \`--agents claude\`, \`--agents codex\`, or \`--agents none\` only when the user explicitly asks for that narrower target.
+
+## Repair adapter support
+
+Run:
+
+\`\`\`bash
+okfh agent install all --workspace <workspace> --json
+\`\`\`
+
+If the command returns conflicts, explain the conflicting paths and ask before using \`--force\`.
+`
+    }
+  },
+  {
+    name: "okf-harness-ingest",
+    title: "OKF Harness Ingest",
+    description: "Add source material and compile it into an OKF-compatible LLM Wiki by creating reference pages, updating topic/entity/project pages, citations, index, and log. Use when the user asks to add, ingest, absorb, summarize into the wiki, or organize a new source. Do not use for general question answering without new sources.",
+    summary: "Use this skill to register source material and compile it into the local OKF wiki.",
+    requiredBehavior: [
+      "Locate the workspace by finding `okfh.config.yaml`.",
+      "Use the local shell to run `okfh --json` commands.",
+      "If the source is not registered, run `okfh source add <path-or-url> --workspace <workspace> --json`.",
+      "Run `okfh ingest plan <source-id-or-path> --workspace <workspace> --json` before editing wiki files.",
+      "Treat candidate concepts as metadata hints only; read the full source before semantic analysis.",
+      "After ingest work changes wiki files, run `okfh lint --workspace <workspace> --json`.",
+      "Show the user changed files, lint status, and unresolved questions."
+    ],
+    hardRules: [
+      "Never edit `raw/sources/`.",
+      "Never invent source IDs, citations, dates, or claims.",
+      "Do not hand-roll a source manifest, search index, graph, or raw source management.",
+      "If more than 20 wiki files seem affected, stop after an ingest plan and ask the user to narrow scope.",
+      "Run `git diff` before final response when file changes were made."
+    ],
+    reference: {
+      path: "ingest-contract.md",
+      title: "Ingest Contract",
+      body: `# Ingest Contract
+
+## Supported now
+
+Run:
+
+\`\`\`bash
+okfh source add <path-or-url> --workspace <workspace> --json
+okfh ingest plan <source-id-or-path> --workspace <workspace> --json
+\`\`\`
+
+The ingest plan is metadata-level guidance. It returns a recommended reference path, candidate concepts, and an Agent checklist; it does not read source bodies, summarize content, extract claims, or synthesize wiki pages.
+
+## Wiki update contract
+
+- Create or update one \`wiki/references/<slug>.md\` page per source.
+- Update only affected \`wiki/topics/\`, \`wiki/entities/\`, \`wiki/projects/\`, \`wiki/decisions/\`, or \`wiki/questions/\` pages.
+- Preserve uncertainty and contradictions.
+- Add or update \`# Citations\` sections.
+- Update \`wiki/index.md\` and relevant subdirectory indexes.
+- Append \`wiki/log.md\`.
+`
+    }
+  },
+  {
+    name: "okf-harness-query",
+    title: "OKF Harness Query",
+    description: "Answer questions using the local OKF Harness wiki by searching concepts, reading full pages, following citations, and citing concept paths. Use when the user asks what their knowledge base says, asks a research question, or requests synthesis from existing wiki knowledge. Do not use to ingest new source material.",
+    summary: "Use this skill to answer from existing OKF wiki knowledge.",
+    requiredBehavior: [
+      "Locate the workspace by finding `okfh.config.yaml`.",
+      "Run `okfh status --json` and confirm `data.capabilities.search`, `read`, and `graph` are available while `queryCommand` is not available.",
+      "Run `okfh read index --json` first to inspect the wiki map.",
+      "Run `okfh search <question> --json` to get candidate concept cards.",
+      "Run `okfh read <concept-id-or-path> --json` for relevant candidates before synthesizing.",
+      "Follow useful reference citations with `okfh read <reference-concept-id-or-path> --json` when factual precision matters.",
+      "If a read is truncated, continue with `--section`, `--section-id`, `--offset/--limit`, or `--full` before relying on omitted content.",
+      "Answer directly first, then list supporting concept paths and available source IDs.",
+      "If hits are weak, citations are missing, or only wiki synthesis was read, state the evidence limit plainly."
+    ],
+    hardRules: [
+      "Do not ingest new source material from this skill.",
+      "Do not invent citations or claim the wiki says something without reading it.",
+      "Do not run or hallucinate an `okfh query` command.",
+      "Do not build an ad hoc search index or search `raw/sources/` for normal query answers.",
+      "Do not edit `raw/sources/`."
+    ],
+    reference: {
+      path: "answer-contract.md",
+      title: "Answer Contract",
+      body: `# Answer Contract
+
+## Query workflow
+
+Use the CLI as the deterministic retrieval layer:
+
+\`\`\`bash
+okfh status --json
+okfh read index --json
+okfh search "<question>" --json
+okfh read <concept-id-or-path> --json
+\`\`\`
+
+There is no \`okfh query\` command in the current CLI. Compose answers from search candidate cards plus bounded reads.
+
+## Answer shape
+
+Answer with:
+
+- Direct answer.
+- Evidence from concept paths and available source IDs.
+- A note when evidence came only from wiki synthesis rather than raw source bodies.
+- Open questions or contradictions.
+- Insufficient-evidence statement when search hits are weak or citations are missing.
+- Suggested follow-up only when it naturally follows from the wiki evidence.
+`
+    }
+  },
+  {
+    name: "okf-harness-maintain",
+    title: "OKF Harness Maintain",
+    description: "Maintain an OKF Harness wiki by running lint, repairing broken links or missing metadata, updating index/log files, checking source hashes, and generating graph reports. Use when the user asks to check, clean up, repair, validate, lint, or visualize the knowledge base. Do not use for first-time initialization.",
+    summary: "Use this skill to lint and repair an existing OKF Harness workspace.",
+    requiredBehavior: [
+      "Locate the workspace by finding `okfh.config.yaml`.",
+      "Run `okfh lint --json` before deciding what to change.",
+      "Use small patches for wiki repairs.",
+      "Run `okfh lint --json` again after wiki edits.",
+      "Run `okfh graph --json` only when the user asks for a graph, visualization, or graph report.",
+      "Report lint status, changed files, graph report paths when generated, and any remaining manual fixes.",
+      "If the user did not ask for a graph, mention graph generation only as an optional follow-up."
+    ],
+    hardRules: [
+      "Never edit `raw/sources/`.",
+      "Do not silently rewrite large wiki sections.",
+      "Do not hand-roll graph reports or source hash checks.",
+      "Run `git diff` before final response when file changes were made."
+    ],
+    reference: {
+      path: "lint-contract.md",
+      title: "Lint Contract",
+      body: `# Lint Contract
+
+## Supported now
+
+Run:
+
+\`\`\`bash
+okfh lint --json
+\`\`\`
+
+Fix only issues that can be resolved from current wiki context without inventing missing source facts.
+
+## Graph reports
+
+Source hash checks are supported by \`okfh lint\`. Graph generation is supported by:
+
+\`\`\`bash
+okfh graph --json
+\`\`\`
+
+Run graph only when the user asks to visualize or generate a graph report. Maintain workflows should not generate graph reports automatically.
+`
+    }
+  }
+];
+function renderAgentAdapter(options) {
+  const version = options.version ?? defaultVersion;
+  return {
+    adapter: options.adapter,
+    files: [renderRootGuidance(options.adapter), ...renderSkillFiles(options.adapter, version)]
+  };
+}
+async function installAgentAdapters(options) {
+  const workspaceRoot = path.resolve(options.workspaceRoot);
+  const dryRun = options.dryRun === true;
+  const force = options.force === true;
+  const plan = createInstallResult(options.adapter, dryRun);
+  await planAgentAdapterWrites(workspaceRoot, options.adapter, {
+    dryRun: true,
+    force,
+    result: plan
+  });
+  if (dryRun || plan.conflicts.length > 0) {
+    return plan;
+  }
+  const result = createInstallResult(options.adapter, false);
+  await planAgentAdapterWrites(workspaceRoot, options.adapter, { dryRun: false, force, result });
+  return result;
+}
+function createInstallResult(adapter, dryRun) {
+  return {
+    adapter,
+    dryRun,
+    writtenFiles: [],
+    plannedFiles: [],
+    replacedFiles: [],
+    skippedFiles: [],
+    conflicts: [],
+    managedBlocks: []
+  };
+}
+async function planAgentAdapterWrites(workspaceRoot, adapterTarget, context) {
+  for (const adapter of adaptersForTarget(adapterTarget)) {
+    for (const file of renderAgentAdapter({ adapter }).files) {
+      if (isRootGuidancePath(file.path)) {
+        await planRootGuidanceWrite(workspaceRoot, file, context);
+      } else {
+        await planManagedFileWrite(workspaceRoot, file, context);
+      }
+    }
+  }
+}
+function renderRootGuidance(adapter) {
+  const rootPath = adapter === "claude" ? "CLAUDE.md" : "AGENTS.md";
+  const routePrefix = adapter === "claude" ? "/" : "$";
+  const routeLabel = adapter === "claude" ? "Use the project skills for user-facing workflows:" : "Use repo skills for workflows:";
+  return {
+    path: rootPath,
+    contents: `# OKF Harness workspace
+
+${managedBlockStart}
+This repository is an OKF Harness workspace.
+
+${routeLabel}
+
+- \`${routePrefix}okf-harness-init\` for first-time setup and adapter repair.
+- \`${routePrefix}okf-harness-ingest\` for adding or compiling sources.
+- \`${routePrefix}okf-harness-query\` for answering from the wiki.
+- \`${routePrefix}okf-harness-maintain\` for lint, repair, and graph reports.
+
+Rules:
+
+- \`raw/sources/\` is immutable. Never edit source files.
+- \`wiki/\` is the OKF bundle and may be edited by the agent.
+- Use \`okfh --json\` through the local shell for deterministic harness operations.
+- Desktop App and TUI sessions use the same local shell command workflow.
+- If \`okfh\` or shell access fails, run \`okfh doctor --json\` when possible and report the failed checks.
+- Run \`okfh lint --workspace <workspace> --json\` after modifying wiki files.
+- Run \`git diff\` before final response after any file changes.
+${managedBlockEnd}
+`
+  };
+}
+function adaptersForTarget(target) {
+  return target === "all" ? ["claude", "codex"] : [target];
+}
+function isRootGuidancePath(filePath) {
+  return filePath === "AGENTS.md" || filePath === "CLAUDE.md";
+}
+async function planRootGuidanceWrite(workspaceRoot, file, context) {
+  const absolutePath = path.join(workspaceRoot, file.path);
+  const existing = await readOptionalTextFile(absolutePath);
+  const nextContents = mergeRootGuidance(existing, file.contents);
+  if (nextContents.conflict !== void 0) {
+    context.result.conflicts.push({
+      path: file.path,
+      reason: nextContents.conflict
+    });
+    return;
+  }
+  context.result.managedBlocks.push({ path: file.path, action: nextContents.action });
+  if (existing === nextContents.contents) {
+    context.result.skippedFiles.push(file.path);
+    return;
+  }
+  context.result.plannedFiles.push(file.path);
+  if (context.dryRun) {
+    return;
+  }
+  await writeRenderedFile(absolutePath, nextContents.contents);
+  if (existing === void 0) {
+    context.result.writtenFiles.push(file.path);
+  } else {
+    context.result.replacedFiles.push(file.path);
+  }
+}
+async function planManagedFileWrite(workspaceRoot, file, context) {
+  const absolutePath = path.join(workspaceRoot, file.path);
+  const existing = await readOptionalTextFile(absolutePath);
+  if (existing === file.contents) {
+    context.result.skippedFiles.push(file.path);
+    return;
+  }
+  if (existing !== void 0 && !isHarnessManagedSkill(existing) && !isBaseWorkspacePlaceholder(existing) && !context.force) {
+    context.result.conflicts.push({
+      path: file.path,
+      reason: "Existing file is not marked as OKF Harness managed. Re-run with --force to replace it."
+    });
+    return;
+  }
+  context.result.plannedFiles.push(file.path);
+  if (context.dryRun) {
+    return;
+  }
+  await writeRenderedFile(absolutePath, file.contents);
+  if (existing === void 0) {
+    context.result.writtenFiles.push(file.path);
+  } else {
+    context.result.replacedFiles.push(file.path);
+  }
+}
+function mergeRootGuidance(existing, renderedRoot) {
+  const renderedBlock = extractManagedBlock(renderedRoot);
+  if (existing === void 0 || isBaseWorkspacePlaceholder(existing)) {
+    return { contents: renderedRoot, action: existing === void 0 ? "created" : "replaced" };
+  }
+  const existingStart = existing.indexOf(managedBlockStart);
+  const existingEnd = existing.indexOf(managedBlockEnd);
+  if (existingStart !== -1 || existingEnd !== -1) {
+    if (existingStart === -1 || existingEnd === -1 || existingEnd <= existingStart) {
+      return {
+        contents: existing,
+        action: "unchanged",
+        conflict: "Existing root guidance contains a malformed OKF Harness managed block. Fix the markers before reinstalling."
+      };
+    }
+  }
+  if (existingStart !== -1 && existingEnd !== -1 && existingEnd > existingStart) {
+    const afterEnd = existingEnd + managedBlockEnd.length;
+    const contents = `${existing.slice(0, existingStart)}${renderedBlock}${existing.slice(afterEnd)}`;
+    return {
+      contents,
+      action: contents === existing ? "unchanged" : "replaced"
+    };
+  }
+  const separator = existing.endsWith("\n\n") ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+  return { contents: `${existing}${separator}${renderedBlock}
+`, action: "inserted" };
+}
+function extractManagedBlock(contents) {
+  const start = contents.indexOf(managedBlockStart);
+  const end = contents.indexOf(managedBlockEnd);
+  if (start === -1 || end === -1 || end <= start) {
+    throw new Error("Rendered root guidance is missing the OKF Harness managed block.");
+  }
+  return contents.slice(start, end + managedBlockEnd.length);
+}
+function isHarnessManagedSkill(contents) {
+  return contents.includes("okf-harness-managed: true");
+}
+function isBaseWorkspacePlaceholder(contents) {
+  return contents.trim() === "@AGENTS.md" || contents.includes("Placeholder. Install agent guidance with okfh init or okfh agent.");
+}
+async function readOptionalTextFile(filePath) {
+  try {
+    return await readFile(filePath, "utf8");
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") {
+      return void 0;
+    }
+    throw error;
+  }
+}
+async function writeRenderedFile(filePath, contents) {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, contents, "utf8");
+}
+function isNodeError(error) {
+  return typeof error === "object" && error !== null && "code" in error;
+}
+function renderSkillFiles(adapter, version) {
+  const skillRoot = adapter === "claude" ? ".claude/skills" : ".agents/skills";
+  return skillTemplates.flatMap((skill) => [
+    {
+      path: `${skillRoot}/${skill.name}/SKILL.md`,
+      contents: renderSkill(skill, version)
+    },
+    {
+      path: `${skillRoot}/${skill.name}/references/${skill.reference.path}`,
+      contents: skill.reference.body
+    }
+  ]);
+}
+function renderSkill(skill, version) {
+  return `---
+name: ${skill.name}
+description: ${skill.description}
+license: Apache-2.0
+compatibility: Designed for Claude Code and Codex on macOS. Requires the okfh CLI and local shell command access.
+metadata:
+  okf-harness-version: "${version}"
+  okf-harness-managed: true
+---
+
+# ${skill.title}
+
+${skill.summary}
+
+## Required Behavior
+
+${numberedList(skill.requiredBehavior)}
+
+## Hard Rules
+
+${bulletList(skill.hardRules)}
+
+See [the ${referenceLabel(skill.reference.title)}](references/${skill.reference.path}) for details.
+`;
+}
+function numberedList(items) {
+  return items.map((item, index) => `${index + 1}. ${item}`).join("\n");
+}
+function bulletList(items) {
+  return items.map((item) => `- ${item}`).join("\n");
+}
+function referenceLabel(title) {
+  return title.toLowerCase();
+}
+export {
+  installAgentAdapters,
+  packageInfo,
+  renderAgentAdapter
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@okf-harness/agent-pack",
+  "version": "0.1.0",
+  "description": "Claude and Codex adapter renderers and shared skill templates.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "author": "Eric Zhou",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "homepage": "https://github.com/pumblus/okf-harness#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pumblus/okf-harness.git",
+    "directory": "packages/agent-pack"
+  },
+  "bugs": {
+    "url": "https://github.com/pumblus/okf-harness/issues"
+  },
+  "keywords": [
+    "okf",
+    "llm-wiki",
+    "agent-skills",
+    "claude-code",
+    "codex",
+    "agent-guidance"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "prepublishOnly": "pnpm run build"
+  }
+}