#!/usr/bin/env bun /** * Generate the canonical sayknow-cli host plugin bundles under `plugins/`. * * Single source of truth: the coordinator contract tool names plus the * coding-agent package version. Host bundles (Claude Code + Codex) and the * shared MCP wiring are rendered deterministically so a drift check can fail * CI when the committed files diverge from this renderer. * * Usage: * bun scripts/generate-skc-plugins.ts # write files * bun scripts/generate-skc-plugins.ts --check # compare complete file set + bytes, exit 1 on drift */ import * as fs from "node:fs"; import * as path from "node:path"; import * as os from "node:os"; import { COORDINATOR_MCP_TOOL_NAMES } from "../packages/coding-agent/src/coordinator/contract"; const repoRoot = path.join(import.meta.dir, ".."); const pluginsDir = path.join(repoRoot, "plugins"); const DELEGATE_TOOLS = COORDINATOR_MCP_TOOL_NAMES.filter(name => name.startsWith("skc_delegate_")); const PLUGIN_NAME = "sayknow-cli"; const NAMESPACE_LABEL = "sayknow-cli-plugin"; interface DelegateMeta { tool: string; workflow: "plan" | "execute" | "team"; skill: "ralplan" | "ultragoal" | "team"; summary: string; } const DELEGATE_META: DelegateMeta[] = [ { tool: "skc_delegate_plan", workflow: "plan", skill: "ralplan", summary: "Delegate consensus planning to SKC (runs /skill:ralplan to a pending-approval plan).", }, { tool: "skc_delegate_execute", workflow: "execute", skill: "ultragoal", summary: "Delegate execution to SKC (runs /skill:ultragoal to completion with verification).", }, { tool: "skc_delegate_team", workflow: "team", skill: "team", summary: "Delegate parallel team execution to SKC (runs /skill:team with internal tmux workers).", }, ]; function readPackageVersion(): string { const pkgPath = path.join(repoRoot, "packages", "coding-agent", "package.json"); const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8")) as { version?: string }; if (!pkg.version) throw new Error("coding-agent package.json is missing a version"); return pkg.version; } function json(value: unknown): string { return `${JSON.stringify(value, null, 2)}\n`; } function coordinatorServer(projectDirToken: string): Record { return { "skc-coordinator": { command: "skc", args: ["mcp-serve", "coordinator"], env: { SKC_COORDINATOR_MCP_WORKDIR_ROOTS: projectDirToken, SKC_COORDINATOR_MCP_REPO: NAMESPACE_LABEL, SKC_COORDINATOR_MCP_SESSION_COMMAND: "skc --worktree", }, }, }; } // Claude Code expects an `mcpServers` wrapper in .mcp.json. function claudeMcpServers(projectDirToken: string): Record { // Fail-closed: workdir allowlist scoped to the host project; mutations omitted. return { mcpServers: coordinatorServer(projectDirToken) }; } // Codex accepts a direct server map or an `mcp_servers` wrapper. Verified on // Codex CLI 0.139.0, the direct map registers the server (an `mcp_servers` // wrapper did not), so emit the direct, docs-blessed map. function codexMcpServers(projectDirToken: string): Record { return coordinatorServer(projectDirToken); } function commandDoc(meta: DelegateMeta): string { return `--- name: ${meta.workflow} description: ${meta.summary} --- Call the \`${meta.tool}\` coordinator MCP tool to delegate this work to sayknow-cli. - Pass the current project directory as \`cwd\`. - Pass the user's request as \`task\`. - Only set \`allow_mutation: true\` after the user explicitly approves changes AND the coordinator server was started with the \`sessions\` mutation class enabled. Delegation is read-only until both conditions hold. SKC starts a session and runs \`/skill:${meta.skill}\` to completion, returning a durable \`turn_id\`, status, and artifact references. Poll with \`skc_coordinator_await_turn\` or \`skc_coordinator_watch_events\`. `; } function skillDoc(): string { const rows = DELEGATE_META.map( meta => `| \`${meta.tool}\` | ${meta.workflow} | /skill:${meta.skill} | ${meta.summary} |`, ).join("\n"); return `--- name: skc-delegation description: Delegate planning, execution, and team workflows to sayknow-cli via the coordinator MCP server. --- # SKC delegation This plugin exposes sayknow-cli's coordinator MCP server so a host agent can delegate whole workflows to SKC and receive durable turn status plus artifacts. ## Tools | Tool | Workflow | SKC skill | Purpose | | --- | --- | --- | --- | ${rows} ## Fail-closed safety The bundled MCP config sets \`SKC_COORDINATOR_MCP_WORKDIR_ROOTS\` to the host project directory and does **not** set \`SKC_COORDINATOR_MCP_MUTATIONS\`. Delegation is read-only until the user explicitly enables a mutation class and passes \`allow_mutation: true\` per call. \`SKC_COORDINATOR_MCP_REPO\` is a namespace label only, never a filesystem path. ## Polling Each delegate returns a \`turn_id\`. Poll \`skc_coordinator_await_turn\` (bounded) or \`skc_coordinator_watch_events\` for the \`delegation.started\` event and the terminal turn state. Turn state is the source of truth, not terminal scrollback. `; } function readmeDoc(): string { return `# sayknow-cli plugin (generated) These files are generated by \`scripts/generate-skc-plugins.ts\` from the coordinator contract and the coding-agent package version. Do not edit them by hand; run \`bun run generate-plugins\` and commit the result. CI runs \`bun run check:plugins\` to fail on drift. - \`.claude-plugin/plugin.json\` — Claude Code manifest. - \`.codex-plugin/plugin.json\` — Codex manifest. - \`.mcp.json\` — Claude coordinator MCP wiring (\${CLAUDE_PROJECT_DIR}). - \`.codex.mcp.json\` — Codex coordinator MCP wiring (host-neutral; \`skc setup codex\` rewrites concrete roots). - \`commands/\`, \`skills/\` — host-facing delegate command + skill docs. Install: \`codex plugin marketplace add ./plugins\` (Codex) or \`/plugin marketplace add ./plugins\` (Claude Code), then install the \`sayknow-cli\` plugin. `; } export function renderPluginFiles(): Map { const version = readPackageVersion(); const files = new Map(); const dir = PLUGIN_NAME; // the plugin folder lives under plugins// // Codex repo marketplace (verified shape: source object + policy + category). // `codex plugin marketplace add ./plugins` reads this and loads ./sayknow-cli. files.set( path.join(".agents", "plugins", "marketplace.json"), json({ name: `${PLUGIN_NAME}-local`, interface: { displayName: "Sayknow-CLI" }, plugins: [ { name: PLUGIN_NAME, source: { source: "local", path: `./${dir}` }, policy: { installation: "AVAILABLE", authentication: "ON_INSTALL" }, category: "Productivity", }, ], }), ); // Claude Code marketplace (legacy-compatible; Codex can also read this). files.set( path.join(".claude-plugin", "marketplace.json"), json({ name: PLUGIN_NAME, owner: { name: "Sayknow-CLI" }, metadata: { description: "SKC delegation plugin", version }, plugins: [ { name: PLUGIN_NAME, source: `./${dir}`, description: "Delegate SKC planning/execution/team workflows via coordinator MCP.", version, author: { name: "Sayknow-CLI" }, keywords: ["skc", "delegation", "mcp", "planning", "agents"], }, ], }), ); // Plugin folder: Claude manifest files.set( path.join(dir, ".claude-plugin", "plugin.json"), json({ name: PLUGIN_NAME, description: "Delegate planning, execution, and team workflows to SKC through the coordinator MCP server.", version, commands: "./commands", skills: "./skills", mcpServers: "./.mcp.json", }), ); // Plugin folder: Codex manifest (only plugin.json lives under .codex-plugin; // skills/.mcp.json live at the plugin root per Codex plugin anatomy). files.set( path.join(dir, ".codex-plugin", "plugin.json"), json({ name: PLUGIN_NAME, version, description: "Delegate Codex tasks to SKC workflows through coordinator MCP.", skills: "./skills/", mcpServers: "./.codex.mcp.json", }), ); // Per-host MCP wiring. Claude uses its ${CLAUDE_PROJECT_DIR} token; Codex gets a // host-neutral file that `skc setup codex` rewrites with a concrete workdir root. files.set(path.join(dir, ".mcp.json"), json(claudeMcpServers("${CLAUDE_PROJECT_DIR}"))); files.set(path.join(dir, ".codex.mcp.json"), json(codexMcpServers("${PWD}"))); for (const meta of DELEGATE_META) { files.set(path.join(dir, "commands", `delegate_${meta.workflow}.md`), commandDoc(meta)); } files.set(path.join(dir, "skills", "skc-delegation", "SKILL.md"), skillDoc()); files.set(path.join(dir, "README.md"), readmeDoc()); return files; } function writeFiles(files: Map): void { // Clean-generate: remove any stale generated files before writing. fs.rmSync(pluginsDir, { recursive: true, force: true }); for (const [rel, content] of files) { const target = path.join(pluginsDir, rel); fs.mkdirSync(path.dirname(target), { recursive: true }); fs.writeFileSync(target, content); } process.stdout.write(`Generated ${files.size} plugin file(s) under plugins/\n`); } function listPluginFiles(dir: string, rel = ""): string[] { if (!fs.existsSync(dir)) return []; const files: string[] = []; for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { const entryRel = path.join(rel, entry.name); const entryPath = path.join(dir, entry.name); if (entry.isDirectory()) { files.push(...listPluginFiles(entryPath, entryRel)); } else { // Treat symlinks and special entries as files: no unrendered entry may be installable. files.push(entryRel); } } return files; } export function findUnexpectedPluginFiles(files: ReadonlyMap, root = pluginsDir): string[] { const expected = new Set(files.keys()); return listPluginFiles(root).filter(rel => !expected.has(rel)).sort(); } function checkFiles(files: Map, root = pluginsDir, report = true): number { const problems: string[] = []; for (const [rel, content] of files) { const target = path.join(root, rel); let actual: string | null = null; try { actual = fs.readFileSync(target, "utf8"); } catch { actual = null; } if (actual === null) { problems.push(`missing: plugins/${rel}`); } else if (actual !== content) { problems.push(`drift: plugins/${rel}`); } } for (const rel of findUnexpectedPluginFiles(files, root)) { problems.push(`unexpected: plugins/${rel}`); } if (problems.length > 0) { if (report) { for (const problem of problems) process.stderr.write(`${problem}\n`); process.stderr.write(`Plugin bundle drift detected. Run \`bun run generate-plugins\`.\n`); } return 1; } process.stdout.write(`Plugin bundle is in sync (${files.size} file(s)).\n`); return 0; } function runSelfTest(): void { const files = renderPluginFiles(); const root = fs.mkdtempSync(path.join(os.tmpdir(), "skc-plugin-self-test-")); try { for (const [rel, content] of files) { const target = path.join(root, rel); fs.mkdirSync(path.dirname(target), { recursive: true }); fs.writeFileSync(target, content); } for (const rel of [ path.join(PLUGIN_NAME, "commands", "stale.md"), path.join(PLUGIN_NAME, "skills", "stale", "SKILL.md"), ]) { const target = path.join(root, rel); fs.mkdirSync(path.dirname(target), { recursive: true }); fs.writeFileSync(target, "stale\n"); } const unexpected = findUnexpectedPluginFiles(files, root); if ( checkFiles(files, root, false) !== 1 || !unexpected.includes(path.join(PLUGIN_NAME, "commands", "stale.md")) || !unexpected.includes(path.join(PLUGIN_NAME, "skills", "stale", "SKILL.md")) ) { throw new Error("plugin file-set check did not reject stale command and skill files"); } process.stdout.write("Plugin file-set self-test passed.\n"); } finally { fs.rmSync(root, { recursive: true, force: true }); } } export { DELEGATE_TOOLS }; if (import.meta.main) { if (DELEGATE_TOOLS.length !== 3) { process.stderr.write(`Expected 3 delegate tools in the coordinator contract, found ${DELEGATE_TOOLS.length}.\n`); process.exit(1); } if (process.argv.includes("--self-test")) { runSelfTest(); } else if (process.argv.includes("--check")) { process.exit(checkFiles(renderPluginFiles())); } else { writeFiles(renderPluginFiles()); } }