@ck123pm/harness-kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jianshu Liu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PLAN.md

@@ -0,0 +1,123 @@
+# @ck123pm/harness-kit 设计文档
+
+## 产品定位
+
+两段式初始化模型：
+
+```
+第一步：CLI 安装能力
+npx @ck123pm/harness-kit install
+
+第二步：Claude 执行智能初始化
+/harness-init
+
+第三步：CLI 或 Claude 执行 comet 初始化
+comet init
+```
+
+**产品边界：**
+- **harness-kit CLI**：安装 Claude command/skill、检查/安装 comet、环境诊断
+- **harness-init.md**：Claude command，由 Claude 理解项目后智能生成 `.harness/`
+- **md-to-html-doc.md**：Claude skill，Markdown 转响应式 HTML
+- **comet**：后续 OpenSpec + Superpowers workflow 管理
+
+CLI **不直接生成 `.harness/`** —— 真正的 `.harness/` 内容需要大模型理解项目后生成。
+
+## 目录结构
+
+```
+@ck123pm/harness-kit
+├── bin/
+│   └── harness-kit.js          # CLI shebang 入口
+├── src/
+│   ├── cli.js                  # Commander 程序定义
+│   ├── commands/
+│   │   ├── install.js          # install 命令
+│   │   ├── doctor.js           # doctor 命令
+│   │   ├── update.js           # update 命令
+│   │   └── uninstall.js        # uninstall 命令
+│   └── utils/
+│       ├── platform.js         # 平台检测（Windows/Mac/Linux 路径差异）
+│       └── registry.js         # command/skill 安装路径解析
+├── commands/
+│   └── harness-init.md         # Claude command（智能初始化指令）
+├── skills/
+│   └── md-to-html-doc.md       # Claude skill
+├── scripts/
+│   └── init-comet.js           # 独立脚本：执行 comet init
+├── package.json
+└── README.md
+```
+
+## CLI 命令定义
+
+### `harness-kit install`
+
+安装 harness 能力到 Claude 环境：
+
+1. **检测 Claude 配置路径**：解析 `~/.claude/` 或 `CLAUDE_CONFIG_DIR` 环境变量
+2. **安装 harness-init.md 到 commands**：复制 `commands/harness-init.md` → `~/.claude/commands/harness-init.md`
+3. **安装 md-to-html-doc.md 到 skills**：复制 `skills/md-to-html-doc.md` → `~/.claude/skills/md-to-html-doc.md`
+4. **检查/安装 @ck123pm/comet**：检测 `comet` 是否在 PATH，不在则 `npm install -g @ck123pm/comet`
+5. **检查/安装 openspec**：检测 `openspec` 是否在 PATH，不在则 `npm install -g @fission-ai/openspec`
+6. **写入安装记录**：`~/.claude/harness-kit.json`
+7. **提示用户下一步**："Open Claude and run `/harness-init` to initialize your project"
+
+选项：
+- `--scope <scope>`: global (默认) | local（安装到项目 .claude/ 而非全局）
+- `--skip-comet`: 跳过 comet 安装
+- `--skip-openspec`: 跳过 openspec 安装
+- `--force`: 覆盖已有文件
+
+### `harness-kit doctor`
+
+环境健康检查，打印表格，每项绿色 ✓ 或红色 ✗：
+
+- [ ] Claude command harness-init 是否已安装
+- [ ] Claude skill md-to-html-doc 是否已安装
+- [ ] comet 是否可用（版本）
+- [ ] openspec 是否可用（版本）
+- [ ] superpowers 是否可用
+- [ ] 当前目录是否已有 `.harness/`
+- [ ] 当前目录是否已有 `.comet.yaml`
+- [ ] 当前目录是否已有 `openspec/`
+
+末尾给出修复建议。
+
+### `harness-kit update`
+
+升级已安装的 command/skill：
+
+1. 对比已安装文件与包内文件的哈希/大小
+2. 如果有更新：提示用户，确认后覆盖
+3. 如果已是最新：打印 "Up to date"
+4. 可选：`--check` 仅检查不升级
+
+### `harness-kit uninstall`
+
+卸载已安装的 command/skill：
+
+1. 删除 `~/.claude/commands/harness-init.md`
+2. 删除 `~/.claude/skills/md-to-html-doc.md`
+3. 删除 `~/.claude/harness-kit.json`
+4. 打印确认信息
+
+## 依赖配置
+
+- **dependencies**: commander (^14.0.0), chalk (^5.3.0), fs-extra (^11.2.0)
+- **peerDependencies**: @ck123pm/comet (>=0.2.0), @fission-ai/openspec (>=1.0.0)
+- **peerDependenciesMeta**: 两者 optional: true
+- **engines**: node >= 20
+- **publishConfig**: { "access": "public" }
+- **type**: "module"
+
+## 验证方式
+
+1. `npm install` 安装依赖
+2. `node bin/harness-kit.js install` — 安装到全局
+3. `node bin/harness-kit.js doctor` — 验证环境
+4. 打开 Claude，执行 `/harness-init` — 验证 Claude 能识别 command
+5. `node bin/harness-kit.js update` — 验证升级检测
+6. `node bin/harness-kit.js uninstall` — 验证卸载
+7. 测试 `--scope local` 安装到项目 `.claude/`
+8. 测试 `--force` 覆盖

package/README.md

@@ -0,0 +1,2 @@
+# harness-kit
+init harness repo

package/bin/harness-kit.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { program } from '../src/cli.js';
+
+program.parse();

package/commands/harness-init.md

@@ -0,0 +1,115 @@
+---
+name: harness-init
+description: Initialize .harness/ AI Engineering Harness directory structure, inject actual project code knowledge
+---
+
+# Harness Init
+
+Based on the latest code on the current branch, initialize the corresponding files according to the directory structure below.
+
+**Core Principles (strictly follow):**
+1. **Don't record what code can derive**: Information the AI can derive directly from source code (class names, method signatures, simple logic) should not be recorded
+2. **Split high-cost derivation info by type**: Project identity goes to `index/project-profile.md`, data flow/message flow and external system runtime semantics (DB/QMQ/RPC/translation service/lock/CAT/Shark) go to `guides/backend.md`, high-risk chains go to `rules/architecture.md`
+3. **Undervable content goes to decisions**: Design decisions, historical reasons, trade-offs (why use magic numbers, why dual type system) go into `decisions/`
+4. **Human-readable content in human-docs/**: onboarding, architecture intro, operation manuals — generate md first, convert to HTML, then delete the md
+5. **Don't hardcode non-existent content**: Must derive from real project code, don't fabricate
+
+**Target Directory Structure:**
+
+```
+.harness/
+│
+├── README.md
+│   # Harness usage: principles, lifecycle, injection strategy
+│
+├── index/
+│   ├── routing.md
+│   │   # Task/phase/module → which context to inject (most important, decides context routing)
+│   ├── priority.md
+│   │   # Injection priority and intensity: MUST / SHOULD / HINT
+│   ├── module-map.md
+│   │   # Module → rules/domain/guides/memory mapping
+│   └── project-profile.md
+│       # Project identity card: app id, purpose, tech stack, runtime, key entry points, constants
+│
+├── rules/
+│   ├── architecture.md
+│   │   # Architecture constraints: dependency direction, module boundaries, Ownership, high-risk chains, prohibited cross-domain behavior
+│   ├── coding.md
+│   │   # Coding standards: naming, annotations, serialization, distributed locks
+│   ├── testing.md
+│   │   # Test rules: framework, file matching, strategy, fast test commands
+│   └── security.md
+│       # Security constraints: data security, SQL security, concurrency security, external call security
+│
+├── domain/
+│   ├── glossary.md
+│   │   # Domain terminology: core concepts, POI types, category IDs
+│   ├── business-rules.md
+│   │   # Long-term business rules
+│   └── runtime-semantics.md
+│       # Business semantics, state transitions, magic values, runtime rules
+│
+├── decisions/
+│   ├── adr/
+│   │   # Architecture Decision Records
+│   └── tradeoffs.md
+│       # Design tradeoffs: why designed this way, why not change casually
+│
+├── guides/
+│   ├── backend.md
+│   │   # AI execution manual: external system runtime semantics, message flow, new Service/Consumer/Producer, distributed locks, transactions
+│   └── ops.md
+│       # Operations manual: startup modes, logs, builds, config, monitoring, troubleshooting
+│
+├── memory/
+│   ├── pitfalls.md
+│   │   # Historical pitfall experiences
+│   ├── regressions.md
+│   │   # Historical regression issues
+│   ├── patterns.md
+│   │   # Reusable engineering patterns
+│   └── lessons.md
+│       # Long-term experience summary
+│
+└── human-docs/
+    ├── onboarding.html
+    │   # Newcomer onboarding (for humans, not injected to AI)
+    ├── architecture-intro.html
+    │   # Architecture intro for humans (not injected to AI)
+    └── operation-manual.html
+        # Operation manual for humans (not injected to AI)
+```
+
+**Content Split Rules:**
+
+| Information Type | Location | Reason |
+|---|---|---|
+| Project identity (app id, tech stack, module structure, key constants) | `index/project-profile.md` | High-frequency access, quick project overview |
+| Data flow/message flow (QMQ Topic, consumption chains) | `guides/backend.md` | Reference when developing new features |
+| External system runtime semantics (DB/QMQ/RPC/translation/lock/CAT/Shark) | `guides/backend.md` | Integration knowledge needed for coding |
+| ops (startup, logs, build, config, monitoring, troubleshooting) | `guides/ops.md` | Operations and publishing |
+| High-risk chains | `rules/architecture.md` | Part of architecture constraints |
+| Module boundaries/Ownership/prohibited cross-domain | `rules/architecture.md` | Part of architecture constraints |
+| Design decisions/tradeoffs | `decisions/` | Understanding "why designed this way" |
+
+**Exploration Strategy:**
+
+1. Read project metadata: package.json/pom.xml (module structure, dependencies, versions), README.md, AGENTS.md
+2. Identify tech stack: framework versions, RPC mode, database, message queue, cache
+3. Map module boundaries: each module's responsibilities, dependency directions, prohibited behaviors
+4. Deep dive into key code:
+   - Service entry points
+   - Entity definitions
+   - Consumer/Producer (message flow, Topic, serialization mode)
+   - Enums and state machines
+   - Config files (databases, external services, feature flags)
+   - Test structure
+5. Check git history: recent commits, fix records, regressions
+
+**Execution Steps:**
+
+1. Thoroughly explore the project's real structure (at least 3 rounds: tech stack → modules → data flow/message flow). If codegraph MCP is available, prefer using it.
+2. Create all `.harness/` directories and files based on actual code content, split info by content rules
+3. For `human-docs/`, write `.md` first, then call `md-to-html-doc` skill to convert to `.html`, then delete `.md`
+4. After completion, verify directory structure is complete

package/commands/harness-update-spec.md

@@ -0,0 +1,122 @@
+---
+name: harness-update-spec
+description: Analyze current project state and derive whether .harness/ specs need updating, provide interactive suggestions
+---
+
+# Harness Update Spec
+
+基于当前项目最新代码状态，分析 `.harness/` 目录中的 spec 是否需要更新或新增。
+
+**核心原则（严格遵守）**：
+1. **对比驱动**：以 `.harness/` 现有内容为基准，对比当前代码真实状态
+2. **增量更新**：只关注"什么变了"和"什么缺失了"，不重新生成全部内容
+3. **交互式建议**：列出变更候选项，用户确认后逐个执行
+4. **不记录可推导信息**：AI 能从源码直接推导的信息不写入 spec
+
+## 分析流程
+
+### 第一步：扫描现有 .harness/ 内容
+
+读取当前 `.harness/` 目录下的所有文件，建立内容索引：
+- 每个文件的主题、关键声明、版本号（如有）
+- 识别出哪些 spec 存在、哪些缺失
+
+### 第二步：探索项目当前状态
+
+至少 3 轮深入探索（如果存在 codegraph 则优先使用 codegraph MCP）：
+
+1. **技术栈变更**：package.json/pom.xml 的依赖新增/删除/升级
+2. **模块边界变更**：新增/删除/重构的模块、服务入口、实体
+3. **数据流/消息流变更**：新的 Consumer/Producer、RPC 调用、Topic
+4. **高风险链路变更**：新的分布式锁、事务、外部集成
+5. **Git 近期变更**：最近 commit message 中暗示的架构调整
+
+### 第三步：推导差异矩阵
+
+| 变更类型 | 影响 spec | 推导信号 |
+|---|---|---|
+| 新依赖 | `index/project-profile.md` | package.json/pom.xml 新增重要依赖 |
+| 新模块 | `index/module-map.md` | 新目录/新 Maven module |
+| 新服务入口 | `guides/backend.md` | 新 Consumer/Producer/Service |
+| 新 RPC/DB/QMQ 集成 | `guides/backend.md` | 新配置、新 Topic、新 Entity |
+| 新枚举/状态 | `domain/runtime-semantics.md` | 新增枚举类、状态定义 |
+| 架构变更 | `rules/architecture.md` | 模块间依赖方向变化 |
+| 新设计决策 | `decisions/tradeoffs.md` | commit message 中的权衡记录 |
+| 新项目身份 | `index/project-profile.md` | 应用号、环境、关键常量变更 |
+| 新业务术语 | `domain/glossary.md` | 新增领域概念 |
+| 新项目业务规则 | `domain/business-rules.md` | 新的长期业务逻辑 |
+| 新踩坑经验 | `memory/pitfalls.md` | 近期修复的问题 |
+| 新回归问题 | `memory/regressions.md` | 回归修复记录 |
+| 新模式 | `memory/patterns.md` | 可复用的新代码模式 |
+
+### 第四步：交互式建议
+
+以表格形式列出所有候选更新项：
+
+```
+🔍 harness-update-spec 分析报告
+
+发现的变更（5 项）：
+
+  #   类型      影响 spec                          信号
+  ─── ───────── ────────────────────────────────── ──────────────────────
+  1   新增      guides/backend.md                  新增 QMQ Topic: order.create
+  2   变更      index/project-profile.md           新增依赖: @elastic/elasticsearch v8.x
+  3   缺失      domain/runtime-semantics.md        存在 OrderState 枚举但未记录
+  4   变更      rules/architecture.md              module-a 开始依赖 module-c
+  5   新增      memory/pitfalls.md                 修复了分布式锁超时问题 (#1234)
+
+缺失的 spec（2 项）：
+  ~ decisions/tradeoffs.md  不存在，可能有新设计决策
+  ~ memory/patterns.md      不存在，可能有新模式
+
+请选择要执行的操作：
+  A. 全部更新
+  B. 交互式选择（逐项确认）
+  C. 取消
+
+输入 [A/B/C]:
+```
+
+### 第五步：执行更新
+
+根据用户选择执行：
+
+**A. 全部更新**：
+- 逐个生成/更新对应 spec 文件
+- 遵循内容拆分规则
+- 完成后用 `find .harness -type f | sort` 验证
+
+**B. 交互式选择**：
+- 逐项列出变更
+- 每次询问用户是否更新该项
+- 用户确认后执行该项更新
+
+**C. 取消**：
+- 打印摘要后退出
+
+### 第六步：human-docs 处理
+
+如果新增了 human-docs/ 下的内容：
+1. 先写 `.md` 文件
+2. 调用 `md-to-html-doc` skill 转 `.html`
+3. 删除 `.md` 原文件
+
+## 内容拆分规则（复用 harness-init）
+
+| 信息类型 | 存放位置 |
+|---|---|
+| 项目身份（应用号、技术栈、模块结构、关键常量） | `index/project-profile.md` |
+| 数据流/消息流（QMQ Topic、消费链路） | `guides/backend.md` |
+| 外部系统运行语义（DB/QMQ/RPC/翻译服务/锁/CAT/Shark） | `guides/backend.md` |
+| 高风险链路 | `rules/architecture.md` |
+| 模块边界/Ownership/禁止跨域行为 | `rules/architecture.md` |
+| 设计决策/权衡 | `decisions/` |
+| 历史踩坑/回归/模式 | `memory/` |
+
+## 更新时的注意事项
+
+- **不要覆盖已有的正确内容**：只新增和变更部分
+- **保留历史记录**：如果是 ADR 或 memory 类 spec，追加而非覆盖
+- **验证一致性**：更新后检查 `.harness/` 内部引用是否一致
+- **如果 .harness/ 不存在**：提示用户先运行 `/harness-init`

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@ck123pm/harness-kit",
+  "version": "0.1.0",
+  "description": "CLI for installing and managing Claude Code harness capabilities",
+  "type": "module",
+  "bin": {
+    "harness-kit": "bin/harness-kit.js"
+  },
+  "scripts": {
+    "start": "node bin/harness-kit.js"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^14.0.0",
+    "fs-extra": "^11.2.0"
+  },
+  "peerDependencies": {
+    "@ck123pm/comet": ">=0.2.0",
+    "@fission-ai/openspec": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@ck123pm/comet": {
+      "optional": true
+    },
+    "@fission-ai/openspec": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/init-comet.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/**
+ * Standalone script to run comet init.
+ * Checks for comet binary, installs if missing, then runs comet init.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const exec = promisify(execFile);
+
+async function detectComet() {
+  try {
+    const { stdout } = await exec('comet', ['--version']);
+    return { available: true, version: stdout.trim() };
+  } catch {
+    return { available: false, version: null };
+  }
+}
+
+async function main() {
+  console.log('Checking for comet...');
+
+  const comet = await detectComet();
+
+  if (!comet.available) {
+    console.log('comet not found, installing @ck123pm/comet...');
+    try {
+      await exec('npm', ['install', '-g', '@ck123pm/comet'], { stdio: 'inherit' });
+    } catch (err) {
+      console.error('Failed to install comet:', err.message);
+      console.error('Try: npm install -g @ck123pm/comet');
+      process.exit(1);
+    }
+  } else {
+    console.log(`comet ${comet.version} found`);
+  }
+
+  console.log('Running comet init...');
+  try {
+    await exec('comet', ['init'], { stdio: 'inherit' });
+    console.log('comet init complete');
+  } catch (err) {
+    console.error('Failed to run comet init:', err.message);
+    process.exit(1);
+  }
+}
+
+main();

package/skills/md-to-html-doc.md

@@ -0,0 +1,196 @@
+---
+name: md-to-html-doc
+description: Convert Markdown architecture docs into modern, responsive single-page HTML with sidebar nav, flowcharts, and state-machine diagrams
+---
+
+# Markdown to Modern HTML Doc
+
+Convert Markdown architecture documents into modern, responsive single-page HTML.
+
+## Flow
+
+1. **Read source Markdown** and understand its structure (heading hierarchy, code blocks, lists, tables)
+2. **Generate complete HTML** file, output to the same path with `.html` extension
+3. **Open in browser** to verify the result
+
+## Core Design Principles
+
+### 1. Charts must use HTML/CSS, no fixed-position SVG
+
+SVG with `x,y` coordinate positioning is an anti-pattern — labels overlap, content gets cut off, text blurs when scaled.
+
+**Correct approach**: use flexbox/grid layout so the browser auto-calculates node positions. Arrows use CSS pseudo-elements or tiny SVG connectors (only branch lines need SVG because they're not purely linear layouts).
+
+```
+✅ Flow nodes → div.flow-node + flexbox vertical layout
+✅ Branch lines → small SVG connector (connection line only, no text)
+✅ State machine → flex horizontal 3-column, arrows via CSS ::after
+❌ Large SVG viewBox + manual x,y coordinates
+❌ <text> tag with fixed x,y
+```
+
+### 2. SVG must be `width="100%"` + adaptive viewBox
+
+If SVG is needed, never write `width="880"` — use `width="100%"` with `viewBox` for browser auto-scaling based on container width.
+
+### 3. Labels along paths (SVG scenario)
+
+When multiple lines converge in SVG, labels at different `x,y` overlap. Use `<textPath>` for text along arrow paths, but HTML/CSS is still cleaner — labels in flex containers naturally avoid overlap.
+
+## HTML Structure Template
+
+```html
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Document Title</title>
+  <style>
+    /* CSS variables + global styles + component styles */
+  </style>
+</head>
+<body>
+
+<!-- Fixed sidebar -->
+<aside class="sidebar">
+  <div class="sidebar-logo">
+    <h1>Document Title</h1>
+    <span>Subtitle / English</span>
+  </div>
+  <nav>
+    <!-- Each h2/h3 gets a link, depth-2 for h3 -->
+    <a href="#section-id">Title</a>
+    <a href="#subsection-id" class="depth-2">Subtitle</a>
+  </nav>
+</aside>
+
+<!-- Main content -->
+<main class="main">
+  <section id="section-id">
+    <h2>Title</h2>
+    <!-- cards, tables, code blocks, charts -->
+  </section>
+</main>
+
+<!-- Back to top -->
+<button class="back-to-top" id="backToTop">↑</button>
+
+<script>
+  // Scroll listener + back-to-top visibility + nav highlight
+</script>
+
+</body>
+</html>
+```
+
+## CSS System
+
+### Design Variables
+
+```css
+:root {
+  --sidebar-w: 280px;
+  --content-max: 960px;
+  --bg: #f8f9fb;
+  --surface: #ffffff;
+  --text: #1e293b;
+  --text-secondary: #64748b;
+  --primary: #4f46e5;
+  --primary-light: #e0e7ff;
+  --primary-dark: #3730a3;
+  --border: #e2e8f0;
+  --code-bg: #1e293b;
+  --code-text: #e2e8f0;
+  --success: #10b981;
+  --warning: #f59e0b;
+  --danger: #ef4444;
+  --shadow-sm: 0 1px 3px rgba(0,0,0,.06);
+  --shadow-md: 0 4px 16px rgba(0,0,0,.08);
+  --radius: 12px;
+  --radius-sm: 8px;
+}
+```
+
+### Flowchart Components (HTML + CSS)
+
+```css
+/* Vertical flowchart */
+.flow-chart { display: flex; flex-direction: column; align-items: center; gap: 0; padding: 16px 0; }
+.flow-node { padding: 10px 20px; border-radius: 10px; font-size: 13.5px; font-weight: 600; text-align: center; line-height: 1.5; max-width: 360px; width: max-content; }
+.flow-node.entry   { background: #4f46e5; color: white; border-radius: 20px; }
+.flow-node.primary { background: #e0e7ff; color: #3730a3; border: 1.5px solid #4f46e5; }
+.flow-node.decision{ background: #fef3c7; color: #92400e; border: 1.5px solid #f59e0b; }
+.flow-node.success { background: #d1fae5; color: #166534; border: 1.5px solid #10b981; }
+.flow-node.danger  { background: #fee2e2; color: #991b1b; border: 1.5px solid #ef4444; }
+.flow-node.warning { background: #fef3c7; color: #92400e; border: 1.5px solid #f59e0b; }
+.flow-node.blue    { background: #dbeafe; color: #1e40af; border: 1.5px solid #3b82f6; }
+.flow-node.dark    { background: #4f46e5; color: white; }
+.flow-node.gray    { background: #f1f5f9; color: #475569; border: 1.5px solid #64748b; }
+.flow-arrow-down { width: 2px; height: 20px; background: #94a3b8; position: relative; }
+.flow-arrow-down::after { content: ''; position: absolute; bottom: 0; left: 50%; transform: translateX(-50%); border-left: 5px solid transparent; border-right: 5px solid transparent; border-top: 6px solid #94a3b8; }
+.flow-connector { display: flex; justify-content: center; margin: 0; }
+.flow-connector svg { display: block; width: 240px; height: 30px; }
+.flow-connector line, .flow-connector path { stroke: #94a3b8; stroke-width: 2; fill: none; }
+.flow-branch { display: flex; gap: 32px; align-items: flex-start; margin: 0; }
+.state-machine { display: flex; flex-direction: column; align-items: center; padding: 16px 0; }
+.sm-transitions { display: flex; gap: 32px; flex-wrap: wrap; justify-content: center; }
+.sm-transition { display: flex; flex-direction: column; align-items: center; min-width: 160px; }
+```
+
+### Other Components
+
+- **Card** `.card` — white background + rounded corners + hover shadow
+- **Overview grid** `.overview-grid` — `grid-template-columns: repeat(auto-fit, minmax(220px, 1fr))`
+- **Steps list** `.steps` — counter-reset + circular numbering
+- **Good/bad examples** `.example.good` / `.example.bad` — green/red background
+- **Design decision cards** `.decision` — with background/decision/reason metadata
+- **Callout** `.callout.info/warning/danger/success` — left border color strip
+
+## Chart Conversion Rules
+
+| Markdown content | HTML conversion |
+|---|---|
+| Vertical flowchart/pseudocode | flexbox vertical `.flow-chart` + `.flow-node` + `.flow-arrow-down` |
+| Branch/decision | `.flow-connector` (small SVG) + `.flow-branch` (two-column flex) |
+| Parallel paths | `.flow-paths` (horizontal flex) + each path vertical inside |
+| State machine | `.state-machine` — top center node + `.sm-transitions` horizontal |
+| Tables | `<div class="table-wrapper"><table>...</table></div>` |
+| Code blocks | `<pre><code>...</code></pre>` |
+
+## Sidebar Navigation (left, fixed)
+
+**Every HTML document must have.** Fixed position on left, right content scrolls freely.
+
+```css
+.sidebar { position: fixed; top: 0; left: 0; width: var(--sidebar-w); height: 100vh; background: var(--surface); border-right: 1px solid var(--border); overflow-y: auto; padding: 32px 0 24px; z-index: 100; box-shadow: var(--shadow-sm); }
+.main { margin-left: var(--sidebar-w); padding: 40px 48px 120px; }
+```
+
+- Each `<h2>` generates `<a href="#id">Title</a>`
+- Each `<h3>` generates `<a href="#id" class="depth-2">Subtitle</a>`
+- JS listens to scroll, auto-highlights current section link (`.active` class)
+- Responsive: `@media (max-width: 900px)` hide sidebar, main full-width
+
+## Back-to-Top Button (bottom-right, fixed)
+
+**Every HTML document must have.** Fixed at bottom-right, fades in after scrolling past 400px.
+
+```css
+.back-to-top { position: fixed; bottom: 32px; right: 32px; width: 44px; height: 44px; border-radius: 50%; background: var(--primary); color: white; border: none; cursor: pointer; box-shadow: var(--shadow-md); display: flex; align-items: center; justify-content: center; opacity: 0; transform: translateY(16px); transition: all .25s ease; z-index: 200; }
+.back-to-top.visible { opacity: 1; transform: translateY(0); }
+```
+
+```js
+const backToTop = document.getElementById('backToTop');
+window.addEventListener('scroll', () => { backToTop.classList.toggle('visible', window.scrollY > 400); });
+backToTop.addEventListener('click', () => { window.scrollTo({ top: 0, behavior: 'smooth' }); });
+```
+
+## Notes
+
+- **Never use fixed pixel width** — all `width` uses relative units or `max-content`
+- **SVG only for connection lines** — nodes and text are HTML elements
+- **Branch connectors use small SVG** — because fork shapes aren't purely vertical, CSS pseudo-elements are too complex
+- **Responsive** — `@media (max-width: 900px)` hide sidebar, main full-width
+- **lang="zh-CN"** — Chinese font stack includes `'Noto Sans SC'`

package/src/cli.js

@@ -0,0 +1,58 @@
+import { Command } from 'commander';
+import fs from 'fs-extra';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkg = await fs.readJson(path.join(__dirname, '..', 'package.json'));
+
+const program = new Command();
+
+program
+  .name('harness-kit')
+  .description('CLI for installing and managing Claude Code harness capabilities')
+  .version(pkg.version);
+
+program
+  .command('install')
+  .description('Install harness-init command and md-to-html-doc skill to Claude')
+  .option('--scope <scope>', 'Installation scope: global or local', 'global')
+  .option('--skip-comet', 'Skip @ck123pm/comet installation')
+  .option('--skip-openspec', 'Skip @fission-ai/openspec installation')
+  .option('--force', 'Overwrite existing files')
+  .action(async (options) => {
+    if (!['global', 'local'].includes(options.scope)) {
+      console.error('Error: --scope must be "global" or "local"');
+      process.exit(1);
+    }
+    const { default: action } = await import('./commands/install.js');
+    await action(options);
+  });
+
+program
+  .command('doctor')
+  .description('Check health of harness environment')
+  .action(async () => {
+    const { default: action } = await import('./commands/doctor.js');
+    await action();
+  });
+
+program
+  .command('update')
+  .description('Update installed command/skill files')
+  .option('--check', 'Check for updates without installing')
+  .option('--force', 'Force overwrite without prompting')
+  .action(async (options) => {
+    const { default: action } = await import('./commands/update.js');
+    await action(options);
+  });
+
+program
+  .command('uninstall')
+  .description('Remove installed command/skill files')
+  .action(async () => {
+    const { default: action } = await import('./commands/uninstall.js');
+    await action();
+  });
+
+export { program };

package/src/commands/doctor.js

@@ -0,0 +1,162 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import chalk from 'chalk';
+import {
+  resolveTargetPath,
+  detectGlobalCommand,
+  getRecordPath,
+} from '../utils/registry.js';
+
+export default async function doctorAction() {
+  console.log(chalk.bold('\n🔍 harness-kit doctor\n'));
+
+  const checks = [];
+
+  // Check 1: Claude command harness-init (check both scopes)
+  let cmdPath = null;
+  const globalCmd = resolveTargetPath('commands/harness-init.md', 'global');
+  const localCmd = resolveTargetPath('commands/harness-init.md', 'local');
+  if (await fs.pathExists(globalCmd)) {
+    cmdPath = globalCmd;
+  } else if (await fs.pathExists(localCmd)) {
+    cmdPath = localCmd;
+  }
+  checks.push({
+    label: 'Claude command harness-init',
+    status: cmdPath ? 'ok' : 'fail',
+    detail: cmdPath ? `Found at ${cmdPath}` : 'Not installed',
+    fix: 'Run: harness-kit install',
+  });
+
+  // Check 2: Claude skill md-to-html-doc (check both scopes)
+  let skillPath = null;
+  const globalSkill = resolveTargetPath('skills/md-to-html-doc.md', 'global');
+  const localSkill = resolveTargetPath('skills/md-to-html-doc.md', 'local');
+  if (await fs.pathExists(globalSkill)) {
+    skillPath = globalSkill;
+  } else if (await fs.pathExists(localSkill)) {
+    skillPath = localSkill;
+  }
+  checks.push({
+    label: 'Claude skill md-to-html-doc',
+    status: skillPath ? 'ok' : 'fail',
+    detail: skillPath ? `Found at ${skillPath}` : 'Not installed',
+    fix: 'Run: harness-kit install',
+  });
+
+  // Check 3: Claude command harness-update-spec (check both scopes)
+  let updateSpecPath = null;
+  const globalUpdateSpec = resolveTargetPath('commands/harness-update-spec.md', 'global');
+  const localUpdateSpec = resolveTargetPath('commands/harness-update-spec.md', 'local');
+  if (await fs.pathExists(globalUpdateSpec)) {
+    updateSpecPath = globalUpdateSpec;
+  } else if (await fs.pathExists(localUpdateSpec)) {
+    updateSpecPath = localUpdateSpec;
+  }
+  checks.push({
+    label: 'Claude command harness-update-spec',
+    status: updateSpecPath ? 'ok' : 'fail',
+    detail: updateSpecPath ? `Found at ${updateSpecPath}` : 'Not installed',
+    fix: 'Run: harness-kit install',
+  });
+
+  // Check 4: harness-kit install record (check both scopes)
+  let recordPath = null;
+  const gr = await getRecordPath('global');
+  const lr = await getRecordPath('local');
+  if (await fs.pathExists(gr)) {
+    recordPath = gr;
+  } else if (await fs.pathExists(lr)) {
+    recordPath = lr;
+  }
+  checks.push({
+    label: 'harness-kit install record',
+    status: recordPath ? 'ok' : 'fail',
+    detail: recordPath ? `Found at ${recordPath}` : 'Not installed',
+    fix: 'Run: harness-kit install',
+  });
+
+  // Check 4: comet
+  const comet = await detectGlobalCommand('comet');
+  checks.push({
+    label: 'comet',
+    status: comet.available ? 'ok' : 'fail',
+    detail: comet.available ? `v${comet.version}` : 'Not found',
+    fix: 'Run: npm install -g @ck123pm/comet',
+  });
+
+  // Check 5: openspec
+  const openspec = await detectGlobalCommand('openspec');
+  checks.push({
+    label: 'openspec',
+    status: openspec.available ? 'ok' : 'fail',
+    detail: openspec.available ? `v${openspec.version}` : 'Not found',
+    fix: 'Run: npm install -g @fission-ai/openspec',
+  });
+
+  // Check 6: superpowers (built-in to Claude Code)
+  checks.push({
+    label: 'superpowers',
+    status: 'ok',
+    detail: 'Built-in to Claude Code',
+    fix: null,
+  });
+
+  // Check 7: .harness/
+  const harnessDir = path.join(process.cwd(), '.harness');
+  const harnessExists = await fs.pathExists(harnessDir);
+  checks.push({
+    label: '.harness/',
+    status: harnessExists ? 'ok' : 'fail',
+    detail: harnessExists ? 'Project initialized' : 'Not found',
+    fix: 'Run: /harness-init in Claude',
+  });
+
+  // Check 8: .comet.yaml
+  const cometYaml = path.join(process.cwd(), '.comet.yaml');
+  const cometYamlExists = await fs.pathExists(cometYaml);
+  checks.push({
+    label: '.comet.yaml',
+    status: cometYamlExists ? 'ok' : 'fail',
+    detail: cometYamlExists ? 'Found' : 'Not found',
+    fix: 'Run: /harness-init in Claude or comet init',
+  });
+
+  // Check 8: openspec/
+  const openspecDir = path.join(process.cwd(), 'openspec');
+  const openspecDirExists = await fs.pathExists(openspecDir);
+  checks.push({
+    label: 'openspec/',
+    status: openspecDirExists ? 'ok' : 'fail',
+    detail: openspecDirExists ? 'Found' : 'Not found',
+    fix: 'Run: openspec init',
+  });
+
+  // Print table
+  const maxLabel = Math.max(...checks.map(c => c.label.length));
+  const maxDetail = Math.max(...checks.map(c => c.detail.length));
+
+  console.log(chalk.bold(`  ${'Check'.padEnd(maxLabel + 2)} ${'Status'.padEnd(8)} ${'Details'}`));
+  console.log(chalk.gray('  ' + '─'.repeat(maxLabel + 2 + 8 + maxDetail + 4)));
+
+  for (const check of checks) {
+    const status = check.status === 'ok'
+      ? chalk.green('✓')
+      : chalk.red('✗');
+    const label = check.label.padEnd(maxLabel + 2);
+    const detail = check.detail;
+    console.log(`  ${status} ${label} ${detail}`);
+  }
+
+  // Repair suggestions
+  const failures = checks.filter(c => c.status === 'fail' && c.fix);
+  if (failures.length > 0) {
+    console.log(chalk.bold.yellow('\nRepair suggestions:'));
+    failures.forEach((f, i) => {
+      console.log(chalk.yellow(`  ${i + 1}. ${f.fix}`));
+    });
+  } else {
+    console.log(chalk.bold.green('\n✅ All checks passed!\n'));
+  }
+  console.log();
+}

package/src/commands/install.js

@@ -0,0 +1,117 @@
+import chalk from 'chalk';
+import {
+  resolveClaudeConfigDir,
+  ensureClaudeDirs,
+} from '../utils/platform.js';
+import {
+  FILE_MAPPINGS,
+  copyFileRecord,
+  detectGlobalCommand,
+  installGlobalPackage,
+  writeRecord,
+  getPackageVersion,
+} from '../utils/registry.js';
+
+export default async function installAction(options) {
+  const { scope = 'global', skipComet = false, skipOpenspec = false, force = false } = options;
+
+  console.log(chalk.bold('\n🔧 harness-kit install\n'));
+
+  // Step 1: Resolve and ensure dirs
+  const claudeDir = resolveClaudeConfigDir({ scope });
+  console.log(chalk.cyan(`  Scope: ${scope}`));
+  console.log(chalk.cyan(`  Config: ${claudeDir}\n`));
+
+  await ensureClaudeDirs(claudeDir);
+
+  // Step 2: Copy files
+  console.log(chalk.bold('Installing commands and skills:'));
+  const fileResults = [];
+
+  for (const mapping of FILE_MAPPINGS) {
+    const result = await copyFileRecord(mapping.source, mapping.target, { force, scope });
+    fileResults.push({ ...result, source: mapping.source });
+
+    if (result.didUpdate) {
+      console.log(chalk.green(`  ✓ ${mapping.target}`));
+    } else {
+      console.log(chalk.yellow(`  ~ ${mapping.target} (already up to date)`));
+    }
+  }
+
+  // Step 3: Check/install comet
+  let cometResult;
+  if (!skipComet) {
+    console.log(chalk.bold('\nChecking comet:'));
+    cometResult = await detectGlobalCommand('comet');
+    if (cometResult.available) {
+      console.log(chalk.green(`  ✓ comet ${cometResult.version}`));
+    } else {
+      console.log(chalk.yellow('  ! comet not found, installing @ck123pm/comet...'));
+      try {
+        await installGlobalPackage('@ck123pm/comet');
+        const afterInstall = await detectGlobalCommand('comet');
+        cometResult = afterInstall;
+        if (afterInstall.available) {
+          console.log(chalk.green(`  ✓ comet ${afterInstall.version} (installed)`));
+        } else {
+          console.log(chalk.red('  ✗ Failed to install comet'));
+        }
+      } catch (err) {
+        console.log(chalk.red(`  ✗ Failed to install comet: ${err.message}`));
+        console.log(chalk.yellow('  Try: npm install -g @ck123pm/comet'));
+      }
+    }
+  }
+
+  // Step 4: Check/install openspec
+  let openspecResult;
+  if (!skipOpenspec) {
+    console.log(chalk.bold('\nChecking openspec:'));
+    openspecResult = await detectGlobalCommand('openspec');
+    if (openspecResult.available) {
+      console.log(chalk.green(`  ✓ openspec ${openspecResult.version}`));
+    } else {
+      console.log(chalk.yellow('  ! openspec not found, installing @fission-ai/openspec...'));
+      try {
+        await installGlobalPackage('@fission-ai/openspec');
+        const afterInstall = await detectGlobalCommand('openspec');
+        openspecResult = afterInstall;
+        if (afterInstall.available) {
+          console.log(chalk.green(`  ✓ openspec ${afterInstall.version} (installed)`));
+        } else {
+          console.log(chalk.red('  ✗ Failed to install openspec'));
+        }
+      } catch (err) {
+        console.log(chalk.red(`  ✗ Failed to install openspec: ${err.message}`));
+        console.log(chalk.yellow('  Try: npm install -g @fission-ai/openspec'));
+      }
+    }
+  }
+
+  // Step 5: Write install record
+  const version = await getPackageVersion();
+  const record = {
+    version,
+    installedAt: new Date().toISOString(),
+    scope,
+    files: fileResults.map(r => ({
+      source: r.source,
+      target: r.target,
+      hash: r.hash,
+      size: r.size,
+    })),
+    options: {
+      comet: !skipComet,
+      openspec: !skipOpenspec,
+    },
+  };
+
+  await writeRecord(record, scope);
+  console.log(chalk.green(`\n  ✓ Install record written to ${claudeDir}/harness-kit.json`));
+
+  // Step 6: Summary
+  console.log(chalk.bold.green('\n✅ Installation complete!\n'));
+  console.log('Next step:');
+  console.log(chalk.cyan('  Open Claude and run /harness-init to initialize your project\n'));
+}

package/src/commands/uninstall.js

@@ -0,0 +1,52 @@
+import chalk from 'chalk';
+import fs from 'fs-extra';
+import {
+  FILE_MAPPINGS,
+  resolveTargetPath,
+  getRecordPath,
+  readRecord,
+} from '../utils/registry.js';
+
+export default async function uninstallAction() {
+  console.log(chalk.bold('\n🗑️  harness-kit uninstall\n'));
+
+  const scope = 'global';
+  let removedCount = 0;
+
+  // Step 1: Read install record for tracked files
+  const record = await readRecord(scope);
+
+  if (record && record.files) {
+    for (const fileEntry of record.files) {
+      if (await fs.pathExists(fileEntry.target)) {
+        await fs.remove(fileEntry.target);
+        console.log(chalk.green(`  ✓ Removed ${fileEntry.target}`));
+        removedCount++;
+      } else {
+        console.log(chalk.yellow(`  ~ Already gone: ${fileEntry.target}`));
+      }
+    }
+  } else {
+    // No record, use known paths
+    console.log(chalk.yellow('  No install record found, removing known files...'));
+    for (const mapping of FILE_MAPPINGS) {
+      const targetPath = resolveTargetPath(mapping.target, scope);
+      if (await fs.pathExists(targetPath)) {
+        await fs.remove(targetPath);
+        console.log(chalk.green(`  ✓ Removed ${targetPath}`));
+        removedCount++;
+      }
+    }
+  }
+
+  // Step 2: Delete harness-kit.json
+  const recordPath = getRecordPath(scope);
+  if (await fs.pathExists(recordPath)) {
+    await fs.remove(recordPath);
+    console.log(chalk.green(`  ✓ Removed ${recordPath}`));
+    removedCount++;
+  }
+
+  // Step 3: Summary
+  console.log(chalk.bold.green(`\n✅ Uninstalled. Removed ${removedCount} file(s).\n`));
+}

package/src/commands/update.js

@@ -0,0 +1,112 @@
+import chalk from 'chalk';
+import {
+  FILE_MAPPINGS,
+  resolveSourcePath,
+  resolveTargetPath,
+  hashFile,
+  readRecord,
+  writeRecord,
+} from '../utils/registry.js';
+
+export default async function updateAction(options) {
+  const { check = false, force = false } = options;
+
+  console.log(chalk.bold('\n🔄 harness-kit update\n'));
+
+  // Step 1: Read install record
+  const record = await readRecord('global');
+  if (!record) {
+    console.log(chalk.red('  ✗ Not installed. Run: harness-kit install'));
+    return;
+  }
+
+  console.log(chalk.cyan(`  Installed version: ${record.version}`));
+  console.log(chalk.cyan(`  Installed at: ${record.installedAt}\n`));
+
+  // Step 2: Compare hashes
+  const updates = [];
+  let allUpToDate = true;
+
+  for (const fileEntry of record.files) {
+    const srcPath = resolveSourcePath(fileEntry.source);
+    const tgtPath = fileEntry.target;
+
+    let sourceHash;
+    try {
+      sourceHash = await hashFile(srcPath);
+    } catch {
+      console.log(chalk.yellow(`  ⚠ Source file not found: ${fileEntry.source}`));
+      continue;
+    }
+
+    const installedHash = fileEntry.hash;
+    const isDifferent = sourceHash !== installedHash;
+
+    if (isDifferent) {
+      allUpToDate = false;
+      updates.push({
+        source: fileEntry.source,
+        target: tgtPath,
+        installedHash,
+        sourceHash,
+      });
+    }
+  }
+
+  if (allUpToDate) {
+    console.log(chalk.green('  ✅ All files up to date.'));
+    console.log();
+    return;
+  }
+
+  // Step 3: Show differences
+  console.log(chalk.bold.yellow(`  ${updates.length} file(s) have updates available:\n`));
+
+  for (const update of updates) {
+    console.log(chalk.yellow(`  ~ ${update.source}`));
+    console.log(chalk.gray(`    installed: ${update.installedHash} → package: ${update.sourceHash}`));
+  }
+
+  if (check) {
+    console.log(chalk.cyan('\n  Use harness-kit update (without --check) to apply updates.'));
+    console.log();
+    return;
+  }
+
+  // Step 4: Apply updates (unless force, prompt first)
+  if (!force) {
+    console.log();
+    const readline = await import('node:readline');
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise(resolve => {
+      rl.question(chalk.bold('  Apply updates? [y/N] '), resolve);
+    });
+    rl.close();
+
+    if (!answer.toLowerCase().startsWith('y')) {
+      console.log(chalk.yellow('  Update cancelled.'));
+      console.log();
+      return;
+    }
+  }
+
+  // Step 5: Copy updated files
+  console.log();
+  for (const update of updates) {
+    const fs = await import('fs-extra');
+    await fs.copy(resolveSourcePath(update.source), update.target, { overwrite: true });
+    const newHash = await hashFile(update.target);
+
+    // Update record
+    const recordEntry = record.files.find(f => f.source === update.source);
+    if (recordEntry) {
+      recordEntry.hash = newHash;
+    }
+
+    console.log(chalk.green(`  ✓ Updated ${update.source}`));
+  }
+
+  await writeRecord(record, 'global');
+  console.log(chalk.green('\n  ✓ Install record updated'));
+  console.log(chalk.bold.green('\n✅ Update complete!\n'));
+}

package/src/utils/platform.js

@@ -0,0 +1,39 @@
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'fs-extra';
+
+/**
+ * Resolve the Claude config directory.
+ * Priority: CLAUDE_CONFIG_DIR env var > ~/.claude
+ * For --scope local, uses cwd/.claude instead.
+ */
+export function resolveClaudeConfigDir({ scope = 'global' } = {}) {
+  if (scope === 'local') {
+    return path.join(process.cwd(), '.claude');
+  }
+  if (process.env.CLAUDE_CONFIG_DIR) {
+    return process.env.CLAUDE_CONFIG_DIR;
+  }
+  return path.join(os.homedir(), '.claude');
+}
+
+/**
+ * Ensure directories exist for command/skill installation.
+ */
+export async function ensureClaudeDirs(claudeDir) {
+  await fs.ensureDir(path.join(claudeDir, 'commands'));
+  await fs.ensureDir(path.join(claudeDir, 'skills'));
+}
+
+/**
+ * Detect platform info for display purposes.
+ */
+export function getPlatformInfo() {
+  return {
+    os: process.platform,
+    arch: process.arch,
+    homeDir: os.homedir(),
+    claudeDir: resolveClaudeConfigDir(),
+    isWindows: process.platform === 'win32',
+  };
+}

package/src/utils/registry.js

@@ -0,0 +1,113 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { resolveClaudeConfigDir, ensureClaudeDirs } from './platform.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+export const PACKAGE_ROOT = path.resolve(__dirname, '..', '..');
+
+export const FILE_MAPPINGS = [
+  {
+    source: 'commands/harness-init.md',
+    target: 'commands/harness-init.md',
+  },
+  {
+    source: 'commands/harness-update-spec.md',
+    target: 'commands/harness-update-spec.md',
+  },
+  {
+    source: 'skills/md-to-html-doc.md',
+    target: 'skills/md-to-html-doc.md',
+  },
+];
+
+export function resolveSourcePath(relativePath) {
+  return path.join(PACKAGE_ROOT, relativePath);
+}
+
+export function resolveTargetPath(relativeTarget, scope = 'global') {
+  const claudeDir = resolveClaudeConfigDir({ scope });
+  return path.join(claudeDir, relativeTarget);
+}
+
+export async function hashFile(filePath) {
+  const content = await fs.readFile(filePath);
+  return createHash('sha256').update(content).digest('hex').slice(0, 12);
+}
+
+export function getRecordPath(scope = 'global') {
+  const claudeDir = resolveClaudeConfigDir({ scope });
+  return path.join(claudeDir, 'harness-kit.json');
+}
+
+export async function readRecord(scope = 'global') {
+  const recordPath = getRecordPath(scope);
+  if (await fs.pathExists(recordPath)) {
+    return await fs.readJson(recordPath);
+  }
+  return null;
+}
+
+export async function writeRecord(record, scope = 'global') {
+  const recordPath = getRecordPath(scope);
+  await fs.ensureDir(path.dirname(recordPath));
+  await fs.writeJson(recordPath, record, { spaces: 2 });
+}
+
+export async function copyFileRecord(sourceRel, targetRel, { force = false, scope = 'global' } = {}) {
+  const src = resolveSourcePath(sourceRel);
+  const tgt = resolveTargetPath(targetRel, scope);
+
+  if (!force && await fs.pathExists(tgt)) {
+    const existingHash = await hashFile(tgt);
+    const sourceHash = await hashFile(src);
+    if (existingHash === sourceHash) {
+      return { target: tgt, didUpdate: false, reason: 'already-up-to-date' };
+    }
+  }
+
+  const claudeDir = resolveClaudeConfigDir({ scope });
+  await ensureClaudeDirs(claudeDir);
+  await fs.copy(src, tgt, { overwrite: true });
+  const hash = await hashFile(tgt);
+  const stat = await fs.stat(tgt);
+
+  return {
+    target: tgt,
+    didUpdate: true,
+    hash,
+    size: stat.size,
+  };
+}
+
+export async function detectGlobalCommand(binName) {
+  const { execFile } = await import('node:child_process');
+  const { promisify } = await import('node:util');
+  const exec = promisify(execFile);
+
+  try {
+    const { stdout } = await exec(binName, ['--version']);
+    return { available: true, version: stdout.trim() };
+  } catch {
+    return { available: false, version: null };
+  }
+}
+
+export async function installGlobalPackage(packageName) {
+  const { execFile } = await import('node:child_process');
+  const { promisify } = await import('node:util');
+  const exec = promisify(execFile);
+
+  await exec('npm', ['install', '-g', packageName], { stdio: 'inherit' });
+}
+
+export async function getPackageVersion() {
+  const pkgPath = path.join(PACKAGE_ROOT, 'package.json');
+  if (await fs.pathExists(pkgPath)) {
+    const pkg = await fs.readJson(pkgPath);
+    return pkg.version;
+  }
+  return 'unknown';
+}