freeharness 0.4.1

package/dist/adapters/harness/index.js

@@ -0,0 +1,17 @@
+import { ClaudeCodeAdapter } from "./claude-code.js";
+import { OpenCodeAdapter } from "./opencode.js";
+import { PluginAdapter } from "./plugin.js";
+export function getAdapter(target) {
+    switch (target) {
+        case "claude-code":
+            return new ClaudeCodeAdapter();
+        case "opencode":
+            return new OpenCodeAdapter();
+        case "plugin":
+            return new PluginAdapter();
+        default: {
+            const exhaustive = target;
+            throw new Error(`No adapter for target: ${String(exhaustive)}`);
+        }
+    }
+}

package/dist/adapters/harness/opencode.d.ts

@@ -0,0 +1,7 @@
+import type { Capability } from "@freeharness/core";
+import type { AdapterResult, InstallContext } from "@freeharness/core";
+import type { HarnessPort } from "@freeharness/core";
+export declare class OpenCodeAdapter implements HarnessPort {
+    readonly target: "opencode";
+    apply(cap: Capability, ctx: InstallContext): Promise<AdapterResult>;
+}

package/dist/adapters/harness/opencode.js

@@ -0,0 +1,166 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { copyDir, isJunkEntry, readText, writeText } from "../../infra/fsutil.js";
+import { routingSourcePath } from "../../infra/routing.js";
+import { frontmatterHasKey, rewriteAgentModel, stripAgentKeys } from "@freeharness/core";
+import { initProject } from "@freeharness/sdd/init";
+import { vendoredSddBin } from "../../infra/paths.js";
+import { seedProjectEvidence } from "./claude-code.js";
+/**
+ * Whether any canonical agent (excluding README.md) carries a `memory:` front matter key.
+ * Reads the source tree directly, independent of `dryRun`, so a preview names the same
+ * drop a real run would perform (invariant 2: pass 1 previews pass 2 exactly). Skips the
+ * same entries `copyDir` skips (`isJunkEntry`), and asks `frontmatterHasKey`, the same
+ * reader `stripAgentKeys` strips by, so the note can never name a drop that never happened.
+ * @param agentsSrc The canonical `agents` directory.
+ * @returns True when at least one agent file's front matter sets `memory:`.
+ */
+function anyAgentCarriesMemoryKey(agentsSrc) {
+    if (!fs.existsSync(agentsSrc))
+        return false;
+    const walk = (dir) => {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (isJunkEntry(entry.name))
+                continue;
+            const abs = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (walk(abs))
+                    return true;
+            }
+            else if (entry.name !== "README.md" && frontmatterHasKey(readText(abs), "memory")) {
+                return true;
+            }
+        }
+        return false;
+    };
+    return walk(agentsSrc);
+}
+// OpenCode adapter: emits AGENTS.md + best-effort skill/agent layouts; no session-start hook (OpenCode has no hook contract we emit to).
+export class OpenCodeAdapter {
+    target = "opencode";
+    async apply(cap, ctx) {
+        const res = { capabilityId: cap.id, target: this.target, written: [], actions: [], notes: [] };
+        const C = ctx.canonicalDir;
+        const P = ctx.projectRoot;
+        const dry = ctx.dryRun;
+        // OpenCode global (user) scope is not supported; emitting capabilities are project-only.
+        if (ctx.scope === "user" && ["rules", "skills", "agents", "safety"].includes(cap.id)) {
+            res.notes.push("OpenCode global (user) scope not supported; use --scope project for OpenCode.");
+            return res;
+        }
+        switch (cap.id) {
+            case "rules": {
+                // No SessionStart hook to read the routing file from disk, so AGENTS.md carries the
+                // table itself, appended after the rules with one blank line between them.
+                const rules = readText(path.join(C, "rules", "CLAUDE.md")).replace(/\n+$/, "\n");
+                const routing = readText(routingSourcePath(C));
+                res.written.push(writeText(path.join(P, "AGENTS.md"), `${rules}\n${routing}`, dry));
+                res.notes.push("OpenCode uses AGENTS.md; no session-start pointer hook emitted, so the routing table is appended to AGENTS.md instead of read from a file beside a hook.");
+                seedProjectEvidence(P, dry, res);
+                break;
+            }
+            case "skills": {
+                res.written.push(...copyDir(path.join(C, "skills"), path.join(P, ".opencode", "skills"), dry, {
+                    transform: (c) => stripAgentKeys(c, ["disable-model-invocation", "context", "agent", "model"]),
+                    transformOnly: (n) => n === "SKILL.md",
+                }));
+                res.notes.push("Skills emitted to .opencode/skills (verify against your OpenCode version).");
+                const rfScripts = path.join(P, ".opencode", "skills", "report-formatting", "scripts");
+                res.actions.push({
+                    description: "Install report-formatting .docx deps (docx, image-size)",
+                    command: "npm install --no-audit --no-fund",
+                    cwd: rfScripts,
+                    optional: true,
+                });
+                res.actions.push({
+                    description: "Install report-formatting .pptx deps (python-pptx, lxml, Pillow, defusedxml)",
+                    command: "python3 -m pip install -r pptx/requirements.txt --break-system-packages",
+                    cwd: rfScripts,
+                    optional: true,
+                });
+                break;
+            }
+            case "agents": {
+                const agentsSrc = path.join(C, "agents");
+                const droppedMemoryKey = anyAgentCarriesMemoryKey(agentsSrc);
+                res.written.push(...copyDir(agentsSrc, path.join(P, ".opencode", "agent"), dry, {
+                    skip: (name) => name === "README.md",
+                    transform: (content) => stripAgentKeys(rewriteAgentModel(content, this.target), ["memory"]),
+                }));
+                res.notes.push("Agent model tiers mapped to ${OPENCODE_*_MODEL} placeholders; fill them in.");
+                if (droppedMemoryKey)
+                    res.notes.push("memory: dropped from the agent copy (OpenCode has no such front matter key).");
+                break;
+            }
+            case "safety":
+                res.written.push(writeText(path.join(P, ".freeharness", "safety.md"), readText(path.join(C, "rules", "safety.md")), dry));
+                break;
+            case "sdd": {
+                const src = path.join(C, "openspec");
+                const dest = path.join(os.homedir(), ".local", "share", "openspec", "schemas", "spec-driven");
+                res.actions.push({
+                    description: "Install spec-driven schema override (user-global)",
+                    command: `mkdir -p "${dest}/templates" && cp "${src}/schema.spec-driven.yaml" "${dest}/schema.yaml" && cp -R "${src}/templates/." "${dest}/templates/"`,
+                });
+                // packages/cli/canonical -> ../../sdd = packages/sdd; the workspace root is two
+                // levels above it. Build through the root workspaces (npm -w) so hoisted deps resolve.
+                const sddDir = path.join(C, "..", "..", "sdd");
+                const workspaceRoot = path.join(sddDir, "..", "..");
+                if (fs.existsSync(path.join(sddDir, "package.json"))) {
+                    const sddBin = path.join(sddDir, "dist", "src", "bin", "openspec.js");
+                    res.actions.push({
+                        description: "Expose the vendored `openspec` on PATH via ~/.local/bin (shadows the system openspec; ensure ~/.local/bin is on PATH)",
+                        command: `npm install --no-audit --no-fund -w @freeharness/sdd && npm run build -w @freeharness/sdd && chmod +x "${sddBin}" && mkdir -p "$HOME/.local/bin" && ln -sf "${sddBin}" "$HOME/.local/bin/openspec"`,
+                        cwd: workspaceRoot,
+                        optional: true,
+                    });
+                }
+                else if (vendoredSddBin()) {
+                    // npm/npx install: the sdd package is bundled and already built; link its bin.
+                    const sddBin = vendoredSddBin();
+                    res.actions.push({
+                        description: "Expose the bundled `openspec` on PATH via ~/.local/bin (shadows the system openspec; ensure ~/.local/bin is on PATH)",
+                        command: `chmod +x "${sddBin}" && mkdir -p "$HOME/.local/bin" && ln -sf "${sddBin}" "$HOME/.local/bin/openspec"`,
+                        optional: true,
+                    });
+                }
+                else {
+                    res.notes.push("Vendored @freeharness/sdd not resolvable; expose the vendored openspec bin manually.");
+                }
+                if (ctx.scope !== "project") {
+                    res.notes.push("SDD is project-scoped: run `freeharness bootstrap --target opencode` inside each project.");
+                }
+                else if (dry) {
+                    res.notes.push("Would initialize OpenSpec for OpenCode (/opsx commands + skills + openspec/) via the vendored engine.");
+                }
+                else {
+                    const r = await initProject({ target: "opencode", projectDir: P });
+                    res.written.push(...r.written);
+                    res.notes.push(...r.notes);
+                }
+                break;
+            }
+            case "memory": {
+                // Seam only. The vendored engine is trimmed to the Claude Code hook platform
+                // (memory-slim), and the upstream `npx claude-mem install --ide opencode` bridge
+                // would install a SECOND upstream daemon beside ours (same worker port). Nothing
+                // is installed for OpenCode until FreeHarness ships its own OpenCode plugin wiring.
+                res.notes.push("memory: OpenCode wiring not shipped (seam). The vendored free-mem plugin targets Claude Code; recall from OpenCode is a v4+ item.");
+                break;
+            }
+            case "mcp": {
+                const cfg = JSON.parse(readText(path.join(C, "mcp", "servers.json")));
+                const names = cfg.servers.filter((s) => s.targets.includes("opencode")).map((s) => s.name);
+                res.notes.push(`Configure MCP servers in your OpenCode config: ${names.join(", ") || "(none)"}.`);
+                break;
+            }
+            case "cost":
+                res.notes.push("cost: OpenCode has no Stop/SessionEnd hook contract with a transcript path; usage tracking is Claude Code only for now.");
+                break;
+            default:
+                res.notes.push(`No opencode action for capability '${cap.id}'.`);
+        }
+        return res;
+    }
+}

package/dist/adapters/harness/plugin.d.ts

@@ -0,0 +1,22 @@
+import type { AdapterResult, Capability, HarnessPort, InstallContext } from "@freeharness/core";
+/** Plugin directory name inside the project root. */
+export declare const PLUGIN_DIR_NAME = "freeharness-plugin";
+/** Marketplace name (the `@marketplace` suffix in `claude plugin install freeharness@...`). */
+export declare const MARKETPLACE_NAME = "freeharness-local";
+/**
+ * Emits the FreeHarness content as a Claude Code plugin directory under
+ * `<projectRoot>/freeharness-plugin/` with a sibling local marketplace manifest.
+ */
+export declare class PluginAdapter implements HarnessPort {
+    readonly target: "plugin";
+    private scaffolded;
+    apply(cap: Capability, ctx: InstallContext): Promise<AdapterResult>;
+    /**
+     * Writes the plugin manifest, README, and the local marketplace manifest.
+     * @param projectRoot Directory that receives `.claude-plugin/marketplace.json`.
+     * @param root The plugin directory.
+     * @param dry When true nothing is written.
+     * @returns Paths written (or planned).
+     */
+    private scaffold;
+}

package/dist/adapters/harness/plugin.js

@@ -0,0 +1,257 @@
+// Plugin adapter: arranges the canonical content into the official Claude Code plugin
+// layout (format taken from the claude-code fork's plugins/: .claude-plugin/plugin.json,
+// agents/, skills/, hooks/hooks.json, .mcp.json, README.md) plus a local marketplace
+// manifest so the emitted directory installs with `claude plugin marketplace add <dir>`.
+// Project scope only: a plugin is a directory, not an install into ~/.claude.
+import fs from "node:fs";
+import path from "node:path";
+import { rewriteAgentModel } from "@freeharness/core";
+import { copyDir, copyExecutable, readText, writeText } from "../../infra/fsutil.js";
+import { cliVersion } from "../../infra/paths.js";
+import { ROUTING_FILE, routingSourcePath } from "../../infra/routing.js";
+import { CONFIG_GUARD_FLAGS, CONTEXT_MONITOR_FLAGS, OUTPUT_PRUNER_FLAGS, REPEAT_TOOL_FLAGS, SESSION_END_TIMEOUT_S, SESSION_START_MATCHER } from "./claude-code.js";
+/** Plugin directory name inside the project root. */
+export const PLUGIN_DIR_NAME = "freeharness-plugin";
+/** Marketplace name (the `@marketplace` suffix in `claude plugin install freeharness@...`). */
+export const MARKETPLACE_NAME = "freeharness-local";
+/**
+ * Additively merges a hook entry into the plugin's hooks.json (dedupe by command; the file is
+ * created with the official `description` + `hooks` shape).
+ * @param file Absolute path of hooks/hooks.json.
+ * @param event Hook event name (SessionStart, PreToolUse, ...).
+ * @param entry Entry to add.
+ * @param dryRun When true nothing is written.
+ * @returns Whether the entry was added (false when already present).
+ */
+function mergePluginHook(file, event, entry, dryRun) {
+    let doc = {
+        description: "FreeHarness hooks: SessionStart pointer (+ post-compaction re-orientation), PreCompact checkpoint, memory guard, config guard, repeat-tool reminder, security guidance (advisory), cost tracker, output pruner, context monitor, auto-memory (flag-gated). Additive; only the memory guard and the config guard deny.",
+        hooks: {},
+    };
+    if (fs.existsSync(file))
+        doc = JSON.parse(fs.readFileSync(file, "utf8"));
+    doc.hooks ??= {};
+    doc.hooks[event] ??= [];
+    const cmd = entry.hooks[0].command;
+    const exists = doc.hooks[event].some((e) => e.hooks.some((h) => h.command === cmd));
+    if (!exists)
+        doc.hooks[event].push(entry);
+    if (!dryRun && !exists)
+        writeText(file, JSON.stringify(doc, null, 2) + "\n", false);
+    return !exists;
+}
+/**
+ * Emits the FreeHarness content as a Claude Code plugin directory under
+ * `<projectRoot>/freeharness-plugin/` with a sibling local marketplace manifest.
+ */
+export class PluginAdapter {
+    target = "plugin";
+    scaffolded = false;
+    async apply(cap, ctx) {
+        const res = { capabilityId: cap.id, target: this.target, written: [], actions: [], notes: [] };
+        if (ctx.scope !== "project") {
+            res.notes.push("plugin target is project-scoped: it writes a plugin directory, not ~/.claude. Use --scope project --project <dir>.");
+            return res;
+        }
+        const C = ctx.canonicalDir;
+        const dry = ctx.dryRun;
+        const root = path.join(ctx.projectRoot, PLUGIN_DIR_NAME);
+        const hooksDir = path.join(root, "hooks");
+        const hooksFile = path.join(hooksDir, "hooks.json");
+        const hookCmd = (script, runner = "node", flags = "") => `${runner} "\${CLAUDE_PLUGIN_ROOT}/hooks/${script}"${flags ? ` ${flags}` : ""}`;
+        /** Copies a canonical hook script and registers it under each event (dedupe by command). */
+        const emitHook = (script, flags, events) => {
+            res.written.push(writeText(path.join(hooksDir, script), readText(path.join(C, "hooks", script)), dry));
+            for (const e of events) {
+                const entry = { ...(e.matcher ? { matcher: e.matcher } : {}), hooks: [{ type: "command", command: hookCmd(script, "node", flags), ...(e.event === "SessionEnd" ? { timeout: SESSION_END_TIMEOUT_S } : {}) }] };
+                mergePluginHook(hooksFile, e.event, entry, dry);
+            }
+        };
+        if (!this.scaffolded) {
+            this.scaffolded = true;
+            res.written.push(...this.scaffold(ctx.projectRoot, root, dry));
+        }
+        switch (cap.id) {
+            case "rules": {
+                // CLAUDE.md is not a plugin component: the behavior rules stay a per-user install.
+                res.notes.push("rules: CLAUDE.md cannot ship inside a plugin; install the behavior rules with `freeharness init --scope user --only rules` (the plugin carries the SessionStart pointer + memory guard only).");
+                res.written.push(copyExecutable(path.join(C, "hooks", "freeharness-session-start"), path.join(hooksDir, "freeharness-session-start"), dry));
+                const ss = { matcher: SESSION_START_MATCHER, hooks: [{ type: "command", command: hookCmd("freeharness-session-start", "bash"), async: false }] };
+                mergePluginHook(hooksFile, "SessionStart", ss, dry);
+                // Same file name and same directory as the claude-code target: the hook script reads
+                // it from its own directory regardless of which target installed it.
+                res.written.push(writeText(path.join(hooksDir, ROUTING_FILE), readText(routingSourcePath(C)), dry));
+                res.written.push(writeText(path.join(hooksDir, "freeharness-memory-guard.mjs"), readText(path.join(C, "hooks", "freeharness-memory-guard.mjs")), dry));
+                const mg = { matcher: "Write|Edit|MultiEdit", hooks: [{ type: "command", command: hookCmd("freeharness-memory-guard.mjs") }] };
+                mergePluginHook(hooksFile, "PreToolUse", mg, dry);
+                emitHook("freeharness-config-guard.mjs", CONFIG_GUARD_FLAGS, [{ event: "PreToolUse", matcher: "Edit|Write|MultiEdit|Bash" }]);
+                emitHook("freeharness-repeat-tool.mjs", REPEAT_TOOL_FLAGS, [{ event: "PreToolUse" }, { event: "UserPromptSubmit" }]);
+                emitHook("freeharness-precompact.mjs", "", [{ event: "PreCompact" }]);
+                res.written.push(hooksFile);
+                break;
+            }
+            case "skills":
+                res.written.push(...copyDir(path.join(C, "skills"), path.join(root, "skills"), dry, {
+                    transform: (c) => rewriteAgentModel(c, this.target),
+                    transformOnly: (n) => n === "SKILL.md",
+                }));
+                res.notes.push("skills: report-formatting runtime deps (docx/python-pptx) are installed by the user after the plugin loads (see the plugin README).");
+                break;
+            case "agents":
+                res.written.push(...copyDir(path.join(C, "agents"), path.join(root, "agents"), dry, {
+                    skip: (n) => n === "README.md",
+                    transform: (c) => rewriteAgentModel(c, this.target),
+                }));
+                break;
+            case "safety": {
+                res.notes.push("safety: rules/safety.md is a rules file (not a plugin component); only the advisory security-guidance hook ships in the plugin.");
+                res.written.push(writeText(path.join(hooksDir, "freeharness-security-guidance.mjs"), readText(path.join(C, "hooks", "freeharness-security-guidance.mjs")), dry));
+                const sg = { matcher: "Write|Edit|MultiEdit", hooks: [{ type: "command", command: hookCmd("freeharness-security-guidance.mjs") }] };
+                mergePluginHook(hooksFile, "PreToolUse", sg, dry);
+                res.written.push(hooksFile);
+                break;
+            }
+            case "mcp": {
+                const cfg = JSON.parse(readText(path.join(C, "mcp", "servers.json")));
+                const mcpServers = {};
+                for (const s of cfg.servers) {
+                    if (!s.targets.includes("claude-code"))
+                        continue;
+                    mcpServers[s.name] = { command: s.command, args: s.args };
+                }
+                res.written.push(writeText(path.join(root, ".mcp.json"), JSON.stringify({ mcpServers }, null, 2) + "\n", dry));
+                break;
+            }
+            case "cost": {
+                res.written.push(writeText(path.join(hooksDir, "freeharness-cost-tracker.mjs"), readText(path.join(C, "hooks", "freeharness-cost-tracker.mjs")), dry));
+                res.written.push(writeText(path.join(hooksDir, "cost-prices.json"), readText(path.join(C, "hooks", "cost-prices.json")), dry));
+                mergePluginHook(hooksFile, "Stop", { hooks: [{ type: "command", command: hookCmd("freeharness-cost-tracker.mjs") }] }, dry);
+                // A plugin hook's timeout never raises Claude Code's shared 1.5 s SessionEnd budget
+                // (only settings-file timeouts do); the user sets CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS
+                // for long transcripts. The timeout still bounds this hook inside the budget.
+                mergePluginHook(hooksFile, "SessionEnd", { hooks: [{ type: "command", command: hookCmd("freeharness-cost-tracker.mjs"), timeout: SESSION_END_TIMEOUT_S }] }, dry);
+                // SubagentStop mirrors SessionEnd (same command, same timeout): the cost tracker reads
+                // the subagent's own transcript, which a long dispatch pushes past the default budget.
+                mergePluginHook(hooksFile, "SubagentStop", { hooks: [{ type: "command", command: hookCmd("freeharness-cost-tracker.mjs"), timeout: SESSION_END_TIMEOUT_S }] }, dry);
+                res.notes.push("cost: SessionEnd hooks run under Claude Code's shared 1.5 s budget, which a plugin timeout does not raise; set CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=10000 for long transcripts.");
+                emitHook("freeharness-output-pruner.mjs", OUTPUT_PRUNER_FLAGS, [{ event: "PostToolUse", matcher: "Bash" }]);
+                emitHook("freeharness-context-monitor.mjs", CONTEXT_MONITOR_FLAGS, [{ event: "Stop" }]);
+                res.written.push(hooksFile);
+                res.notes.push("cost: the hook prices with hooks/cost-prices.json next to it (placeholders; edit, or point FREEHARNESS_COST_PRICES at your table).");
+                res.notes.push("cost: a plugin cannot set settings keys; add promptCacheTtl / subagentPromptCacheTtl = 1h to ~/.claude/settings.json by hand or with `freeharness init --scope user --only cost`.");
+                break;
+            }
+            case "sdd":
+                res.notes.push("sdd: not a plugin component (OpenSpec is a per-project init through the vendored engine): run `freeharness bootstrap` inside each project.");
+                emitHook("freeharness-converge.mjs", "", [{ event: "Stop" }]);
+                res.notes.push("sdd: the converge Stop hook ships (a no-op until <project>/.freeharness/converge.json exists).");
+                res.written.push(hooksFile);
+                break;
+            case "memory":
+                res.notes.push("memory: not a plugin component (free-mem is its own plugin, built and registered by `freeharness init --scope user --only memory`).");
+                emitHook("freeharness-auto-memory.mjs", "", [{ event: "SessionEnd" }]);
+                res.notes.push("memory: the auto-memory tier-0 hook ships (SessionEnd; a no-op until FREEHARNESS_AUTO_MEMORY=on).");
+                res.written.push(hooksFile);
+                break;
+            default:
+                res.notes.push(`No plugin action for capability '${cap.id}'.`);
+        }
+        return res;
+    }
+    /**
+     * Writes the plugin manifest, README, and the local marketplace manifest.
+     * @param projectRoot Directory that receives `.claude-plugin/marketplace.json`.
+     * @param root The plugin directory.
+     * @param dry When true nothing is written.
+     * @returns Paths written (or planned).
+     */
+    scaffold(projectRoot, root, dry) {
+        const version = cliVersion();
+        const manifest = {
+            name: "freeharness",
+            version,
+            description: "FreeHarness for Claude Code: execution/verification skills (TDD, subagent-driven development, debugging, code/PR review, git workflow, report-formatting), reviewer/design/exploration agents, and the SessionStart, memory-guard, config-guard, repeat-tool, security-guidance, cost-tracker, output-pruner and context-monitor hooks.",
+            author: { name: "André Negrelli" },
+            homepage: "https://github.com/anegrelli/FreeHarness",
+            repository: "https://github.com/anegrelli/FreeHarness",
+            license: "MIT",
+            keywords: ["claude-code", "agentic", "spec-driven", "openspec", "skills", "agents", "hooks", "harness"],
+        };
+        const marketplace = {
+            $schema: "https://json.schemastore.org/claude-code-marketplace.json",
+            name: MARKETPLACE_NAME,
+            version,
+            description: "Local marketplace for the FreeHarness plugin emitted by `freeharness init --target plugin`.",
+            owner: { name: "André Negrelli" },
+            plugins: [
+                {
+                    name: "freeharness",
+                    description: manifest.description,
+                    version,
+                    author: manifest.author,
+                    source: `./${PLUGIN_DIR_NAME}`,
+                    category: "productivity",
+                },
+            ],
+        };
+        return [
+            writeText(path.join(root, ".claude-plugin", "plugin.json"), JSON.stringify(manifest, null, 2) + "\n", dry),
+            writeText(path.join(root, "README.md"), pluginReadme(version, projectRoot), dry),
+            writeText(path.join(projectRoot, ".claude-plugin", "marketplace.json"), JSON.stringify(marketplace, null, 2) + "\n", dry),
+        ];
+    }
+}
+/**
+ * Builds the plugin README (install mechanism per the official plugins README: marketplace
+ * add + install, or `--plugin-dir` for local development).
+ * @param version Plugin version.
+ * @param marketplaceDir Directory holding `.claude-plugin/marketplace.json`.
+ * @returns Markdown text.
+ */
+function pluginReadme(version, marketplaceDir) {
+    return `# FreeHarness plugin (v${version})
+
+Generated by \`freeharness init --target plugin\`. Official Claude Code plugin layout:
+
+\`\`\`
+${PLUGIN_DIR_NAME}/
+├── .claude-plugin/plugin.json   # manifest
+├── agents/                      # reviewer, design, and planning agents (model tiers resolved)
+├── skills/                      # execution/verification skills
+├── hooks/hooks.json             # SessionStart pointer, memory/config guards, repeat-tool, security guidance, cost tracker, output pruner, context monitor
+├── hooks/*.mjs, freeharness-session-start
+├── .mcp.json                    # MCP servers (context7)
+└── README.md
+\`\`\`
+
+## Install
+
+Claude Code installs plugins from a marketplace. This directory's parent is a local marketplace
+(\`.claude-plugin/marketplace.json\`, name \`${MARKETPLACE_NAME}\`):
+
+\`\`\`
+claude plugin marketplace add ${marketplaceDir}
+claude plugin install freeharness@${MARKETPLACE_NAME}
+\`\`\`
+
+Inside a session the same steps are \`/plugin marketplace add <path>\` and
+\`/plugin install freeharness@${MARKETPLACE_NAME}\`. For local development, load the directory
+directly without a marketplace: \`claude --plugin-dir ${path.join(marketplaceDir, PLUGIN_DIR_NAME)}\`.
+Publishing: push the marketplace directory to a git repo and add it with
+\`claude plugin marketplace add <owner>/<repo>\`.
+
+Verify with \`claude plugin list\` (or \`/plugin\`): the \`freeharness\` plugin should be listed, with
+its agents, skills, and hooks.
+
+## What is not in the plugin
+
+- Behavior rules (\`CLAUDE.md\`) and \`safety.md\`: not plugin components. Install them per user with
+  \`freeharness init --scope user --only rules,safety\`.
+- SDD (OpenSpec \`/opsx\`): per-project init, \`freeharness bootstrap\` inside the project.
+- Memory (free-mem): its own plugin, \`freeharness init --scope user --only memory\`.
+- Report-formatting runtime deps: after install run \`npm install\` in
+  \`skills/report-formatting/scripts\` and \`python3 -m pip install -r skills/report-formatting/scripts/pptx/requirements.txt --break-system-packages\`.
+
+Hook commands use \`\${CLAUDE_PLUGIN_ROOT}\` so the plugin works from any install location.
+`;
+}