@ck123pm/harness-kit 0.1.1 → 0.1.3

package/PLAN.md

@@ -1,123 +1,29 @@
-# @ck123pm/harness-kit 设计文档
+# Harness Kit Plan
 
-## 产品定位
+## Current Direction
 
-两段式初始化模型：
+This package now ships the harness capabilities as Claude skills instead of Claude commands.
 
-```
-第一步：CLI 安装能力
-npx @ck123pm/harness-kit install
+Installed artifacts:
 
-第二步：Claude 执行智能初始化
-/harness-init
+- `skills/harness-init/SKILL.md`
+- `skills/harness-update-spec/SKILL.md`
+- `skills/md-to-html-doc.md`
 
-第三步：CLI 或 Claude 执行 comet 初始化
-comet init
-```
+## Intended Workflow
 
-**产品边界：**
-- **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 管理
+1. Run `harness-kit install`.
+2. Open Claude and ask it to use `harness-init` to create `.harness/`.
+3. Later, ask Claude to use `harness-update-spec` to refresh stale specs incrementally.
 
-CLI **不直接生成 `.harness/`** —— 真正的 `.harness/` 内容需要大模型理解项目后生成。
+## CLI Responsibilities
 
-## 目录结构
+- Install packaged skills into Claude config.
+- Check optional external tools such as `comet` and `openspec`.
+- Diagnose environment state.
+- Update or uninstall installed skill artifacts.
 
-```
-@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
-```
+## Notes
 
-## 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` 覆盖
+- `harness-init` and `harness-update-spec` are directory-based skills.
+- The install/update record logic must support hashing whole directories, not only single files.

package/README.md

@@ -1,185 +1,115 @@
 # @ck123pm/harness-kit
 
-CLI for installing and managing Claude Code harness capabilities.
+CLI for installing and managing harness-related Claude skills.
 
-## 安装
+## Install
 
 ```bash
 npx @ck123pm/harness-kit install
 ```
 
-或全局安装后使用：
+Or install globally first:
 
 ```bash
 npm install -g @ck123pm/harness-kit
 harness-kit install
 ```
 
-## 使用流程
+## What Gets Installed
 
-三步初始化模型：
+`harness-kit install` installs these Claude skills:
 
-```
-第一步：CLI 安装能力
-npx @ck123pm/harness-kit install
+- `harness-init`
+- `harness-update-spec`
+- `md-to-html-doc`
 
-第二步：Claude 执行智能初始化
-/harness-init
+It also checks for:
 
-第三步：CLI 或 Claude 执行 comet 初始化
-comet init
-```
+- `@ck123pm/comet`
+- `@fission-ai/openspec`
 
-## CLI 命令
+And writes an install record to `~/.claude/harness-kit.json` or the local `.claude/` scope.
 
-### `harness-kit install`
+## Usage Flow
 
-安装 harness 能力到 Claude 环境：
+1. Install the skills with `harness-kit install`.
+2. Open Claude and ask it to use the `harness-init` skill to initialize the project harness.
+3. After the harness exists, ask Claude to use the `harness-update-spec` skill when specs need to be refreshed.
+4. Use `comet init` or `openspec` commands as needed for the surrounding workflow.
+
+## CLI Commands
+
+### `harness-kit install`
 
-- 复制 `harness-init.md` → `~/.claude/commands/`
-- 复制 `harness-update-spec.md` → `~/.claude/commands/`
-- 复制 `md-to-html-doc.md` → `~/.claude/skills/`
-- 检查/安装 `@ck123pm/comet`
-- 检查/安装 `@fission-ai/openspec`
-- 写入安装记录 `~/.claude/harness-kit.json`
+Install the packaged Claude skills.
 
-**选项：**
+Options:
 
-| 选项 | 说明 |
-|------|------|
-| `--scope <scope>` | `global`（默认）或 `local`（安装到项目 `.claude/`） |
-| `--skip-comet` | 跳过 comet 安装 |
-| `--skip-openspec` | 跳过 openspec 安装 |
-| `--force` | 覆盖已有文件 |
+- `--scope <scope>`: `global` or `local`
+- `--skip-comet`: skip `@ck123pm/comet` install check
+- `--skip-openspec`: skip `@fission-ai/openspec` install check
+- `--force`: overwrite installed files
 
-**示例：**
+Examples:
 
 ```bash
-# 全局安装（默认）
 harness-kit install
-
-# 安装到项目级 .claude/
 harness-kit install --scope local
-
-# 跳过 comet 和 openspec
 harness-kit install --skip-comet --skip-openspec
 ```
 
 ### `harness-kit doctor`
 
-环境健康检查，打印各项状态：
-
-```
-🔍 harness-kit doctor
-
-  ✓ Claude command harness-init        Found
-  ✓ Claude command harness-update-spec Found
-  ✓ Claude skill md-to-html-doc        Found
-  ✗ comet                               Not found
-  ✗ openspec                            Not found
-  ✓ superpowers                         Built-in
-  ✗ .harness/                           Not found
-  ✗ .comet.yaml                         Not found
-  ✗ openspec/                           Not found
-```
-
-末尾给出修复建议。
+Check whether the required skills and supporting tools are present.
 
 ### `harness-kit update`
 
-升级已安装的 command/skill：
+Update installed skill files from the current package contents.
 
-- 对比已安装文件与包内文件的哈希
-- 有更新时提示确认后覆盖
-- 已是最新时打印 "All files up to date"
+Options:
 
-**选项：**
-
-| 选项 | 说明 |
-|------|------|
-| `--check` | 仅检查不升级 |
-| `--force` | 强制覆盖不提示 |
-
-**示例：**
-
-```bash
-# 检查是否有更新
-harness-kit update --check
-
-# 执行更新
-harness-kit update
-```
+- `--check`: detect updates without applying them
+- `--force`: overwrite without prompting
 
 ### `harness-kit uninstall`
 
-卸载已安装的 command/skill：
+Remove installed skill files and the install record.
 
-```bash
-harness-kit uninstall
-```
+## Installed Skills
 
-删除 `~/.claude/commands/harness-init.md`、`harness-update-spec.md`、`skills/md-to-html-doc.md` 和 `harness-kit.json`。
+### `harness-init`
 
-## Claude Commands
+Initializes the `.harness/` directory from the real codebase and splits project knowledge into the expected harness structure.
 
-安装后在 Claude 中可用的斜杠命令：
+### `harness-update-spec`
 
-| 命令 | 说明 |
-|------|------|
-| `/harness-init` | 智能初始化 `.harness/` 目录，基于项目代码推导生成全部 spec |
-| `/harness-update-spec` | 分析当前项目状态，对比现有 `.harness/` spec，交互式建议更新或新增 |
+Compares the current codebase against the existing `.harness/` specs and proposes or applies incremental updates.
 
-## .harness/ 目录结构
+### `md-to-html-doc`
 
-`/harness-init` 生成的目录：
+Converts Markdown architecture and guide documents into responsive HTML output.
 
-```
+## Expected `.harness/` Structure
+
+```text
 .harness/
-├── README.md                    # 使用说明
+├── README.md
 ├── index/
-│   ├── routing.md               # 任务→上下文路由
-│   ├── priority.md              # 注入优先级 (MUST/SHOULD/HINT)
-│   ├── module-map.md            # 模块→spec 映射
-│   └── project-profile.md       # 项目身份卡片
 ├── rules/
-│   ├── architecture.md          # 架构约束
-│   ├── coding.md                # 编码规范
-│   ├── testing.md               # 测试规则
-│   └── security.md              # 安全约束
 ├── domain/
-│   ├── glossary.md              # 领域术语
-│   ├── business-rules.md        # 业务规则
-│   └── runtime-semantics.md     # 运行时语义
 ├── decisions/
-│   ├── adr/                     # 架构决策记录
-│   └── tradeoffs.md             # 设计权衡
 ├── guides/
-│   ├── backend.md               # 后端执行手册
-│   └── ops.md                   # 运维操作指南
 ├── memory/
-│   ├── pitfalls.md              # 踩坑经验
-│   ├── regressions.md           # 回归问题
-│   ├── patterns.md              # 可复用模式
-│   └── lessons.md               # 经验总结
 └── human-docs/
-    ├── onboarding.html          # 新人手册
-    ├── architecture-intro.html  # 架构介绍
-    └── operation-manual.html    # 操作手册
 ```
 
-## Claude Skill
-
-| Skill | 说明 |
-|-------|------|
-| `md-to-html-doc` | Markdown 转响应式 HTML（含侧边栏导航、flexbox 流程图） |
-
-## 环境要求
+## Requirements
 
 - Node.js >= 20
 - Claude Code CLI
-- `@ck123pm/comet`（可选）
-- `@fission-ai/openspec`（可选）
+- `@ck123pm/comet` optional
+- `@fission-ai/openspec` optional
 
 ## License
 
-MIT
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ck123pm/harness-kit",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "CLI for installing and managing Claude Code harness capabilities",
   "type": "module",
   "bin": {

package/skills/harness-init/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: harness-init
+description: Initialize a project's .harness/ directory by deriving high-value project knowledge from the real codebase, splitting content into the expected index/rules/domain/decisions/guides/memory/human-docs structure, and avoiding facts that can be re-derived from source.
+---
+
+# Harness Init
+
+Use this skill when the user wants to initialize a project's `.harness/` directory from the current codebase state.
+
+## Core Principles
+
+1. Do not record what the AI can cheaply derive from source code.
+2. Split expensive-to-derive knowledge by type and place it in the right file.
+3. Put design decisions, historical reasons, and tradeoffs into `decisions/`.
+4. Put human-oriented docs in `human-docs/` as Markdown first, convert them to HTML with `md-to-html-doc`, then remove the Markdown source if the workflow requires generated HTML only.
+5. Never fabricate content that is not supported by the actual repository state.
+
+## Target Directory Structure
+
+Create this structure under `.harness/`:
+
+```text
+.harness/
+├── README.md
+├── index/
+│   ├── routing.md
+│   ├── priority.md
+│   ├── module-map.md
+│   └── project-profile.md
+├── rules/
+│   ├── architecture.md
+│   ├── coding.md
+│   ├── testing.md
+│   └── security.md
+├── domain/
+│   ├── glossary.md
+│   ├── business-rules.md
+│   └── runtime-semantics.md
+├── decisions/
+│   ├── adr/
+│   └── tradeoffs.md
+├── guides/
+│   ├── backend.md
+│   └── ops.md
+├── memory/
+│   ├── pitfalls.md
+│   ├── regressions.md
+│   ├── patterns.md
+│   └── lessons.md
+└── human-docs/
+    ├── onboarding.html
+    ├── architecture-intro.html
+    └── operation-manual.html
+```
+
+## Content Routing
+
+| Information type | Destination |
+| --- | --- |
+| Project identity, tech stack, module structure, key constants | `index/project-profile.md` |
+| Task-to-context routing | `index/routing.md` |
+| Injection priority and intensity | `index/priority.md` |
+| Module-to-spec mapping | `index/module-map.md` |
+| Architecture constraints, module boundaries, ownership, high-risk chains | `rules/architecture.md` |
+| Coding standards, serialization, locking, conventions | `rules/coding.md` |
+| Test framework, file layout, strategy, fast commands | `rules/testing.md` |
+| Security constraints | `rules/security.md` |
+| Domain terminology | `domain/glossary.md` |
+| Stable business rules | `domain/business-rules.md` |
+| Runtime semantics, state transitions, magic values | `domain/runtime-semantics.md` |
+| External-system runtime semantics, message flow, integration behavior | `guides/backend.md` |
+| Build, startup, logs, config, monitoring, troubleshooting | `guides/ops.md` |
+| ADRs and tradeoffs | `decisions/` |
+| Historical pitfalls, regressions, reusable patterns, lessons | `memory/` |
+
+## Exploration Strategy
+
+Before writing files, inspect the repository in at least three passes:
+
+1. Project metadata and top-level docs: `package.json`, `pom.xml`, `README`, `AGENTS.md`, workspace config.
+2. Module boundaries and entry points: application bootstraps, services, APIs, entities, consumers, producers, config, tests.
+3. Runtime and history signals: external integrations, state machines, queues, locks, transactions, recent commits, regressions.
+
+Prefer CodeGraph when it is available. Use local search only when you need literal text or filesystem details.
+
+## Language
+
+Before generating any content, determine the output language:
+
+1. Read the project's `CLAUDE.md` (or `.claude/CLAUDE.md`) if it exists. If it declares a language preference (e.g. `language: zh-CN`, "使用中文", "write in English"), follow that.
+2. If no language preference is found, match the language of the current conversation.
+3. All generated files in `.harness/` must use the same language consistently.
+
+## Execution
+
+1. Explore the repository thoroughly and base all outputs on the current branch state.
+2. Create the full `.harness/` tree, even if some files are initially brief.
+3. Keep generated content concise and high-signal.
+4. If `human-docs/` content is needed, write Markdown first, then use `md-to-html-doc` to produce HTML.
+5. Verify the final `.harness/` tree is complete.

package/skills/harness-update-spec/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: harness-update-spec
+description: Analyze an existing project's .harness/ specs against the current codebase, identify incremental updates or missing specs, and propose focused changes without regenerating everything from scratch.
+---
+
+# Harness Update Spec
+
+Use this skill when the user wants to inspect whether an existing `.harness/` directory is stale and update it incrementally.
+
+## Core Principles
+
+1. Use the current `.harness/` content as the baseline and compare it with the real codebase state.
+2. Focus on incremental changes: what changed, what is missing, and what should be amended.
+3. Prefer interactive confirmation when the user wants review-first behavior; otherwise execute the requested updates directly.
+4. Do not add facts that can be cheaply re-derived from source code.
+5. Preserve historical records in `decisions/` and `memory/` by appending when appropriate instead of overwriting blindly.
+
+## Analysis Flow
+
+### 1. Scan existing `.harness/`
+
+Read the current `.harness/` files and build a quick index of:
+
+- Which spec files already exist.
+- What each file currently covers.
+- Which expected files are missing.
+
+If `.harness/` does not exist, stop and tell the user to initialize it with the `harness-init` skill first.
+
+### 2. Re-scan the project
+
+Inspect the live repository in at least three passes:
+
+1. Tech stack changes: dependency additions, removals, or upgrades.
+2. Module boundary changes: new or removed modules, services, entry points, entities.
+3. Runtime flow changes: new consumers, producers, RPC edges, topics, configs, transactions, locks, external integrations.
+4. High-risk chain changes: new distributed behavior, critical state transitions, external dependencies.
+5. Recent git history: commits that imply architectural or behavior changes.
+
+Prefer CodeGraph when it is available.
+
+### 3. Derive a diff matrix
+
+Map detected changes to spec targets:
+
+| Change type | Likely spec target |
+| --- | --- |
+| Dependency or runtime identity changes | `index/project-profile.md` |
+| Module structure changes | `index/module-map.md` |
+| New services, consumers, producers, RPC or message flows | `guides/backend.md` |
+| New runtime semantics or state machines | `domain/runtime-semantics.md` |
+| Architecture boundary changes | `rules/architecture.md` |
+| New design tradeoffs or ADR-worthy decisions | `decisions/tradeoffs.md` or `decisions/adr/` |
+| New domain terms or business rules | `domain/glossary.md`, `domain/business-rules.md` |
+| New pitfalls, regressions, or reusable patterns | `memory/` |
+
+### 4. Report proposed updates
+
+When the user asks for analysis first, present a compact report that includes:
+
+- Newly detected changes.
+- Missing spec files.
+- Which `.harness/` files should be updated and why.
+
+If the user asks you to proceed, apply only the selected or clearly necessary updates.
+
+### 5. Apply updates
+
+When updating:
+
+1. Do not rewrite correct existing content without reason.
+2. Append to history-oriented files when that better preserves context.
+3. Keep internal references inside `.harness/` consistent after edits.
+4. Re-run a quick file list check to ensure the directory remains coherent.
+
+## Content Routing
+
+Reuse the same content-routing rules as `harness-init`:
+
+- Project identity goes to `index/project-profile.md`.
+- Data flow and external runtime semantics go to `guides/backend.md`.
+- High-risk chains and boundaries go to `rules/architecture.md`.
+- Decisions and tradeoffs go to `decisions/`.
+- Historical pitfalls, regressions, and patterns go to `memory/`.
+
+## Language
+
+Before generating or updating any content, determine the output language using the same rules as `harness-init`:
+
+1. Read the project's `CLAUDE.md` (or `.claude/CLAUDE.md`) if it exists. If it declares a language preference, follow that.
+2. If no preference is found, match the language of the current conversation.
+3. All generated files in `.harness/` must use the same language consistently and match the language of existing `.harness/` files.
+
+## Human Docs
+
+If you add or refresh `human-docs/` content, write Markdown first and then use `md-to-html-doc` to produce the HTML artifacts expected by the harness.

package/src/cli.js

@@ -15,7 +15,7 @@ program
 
 program
   .command('install')
-  .description('Install harness-init command and md-to-html-doc skill to Claude')
+  .description('Install harness skills into 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')
@@ -39,7 +39,7 @@ program
 
 program
   .command('update')
-  .description('Update installed command/skill files')
+  .description('Update installed skill files')
   .option('--check', 'Check for updates without installing')
   .option('--force', 'Force overwrite without prompting')
   .action(async (options) => {
@@ -49,7 +49,7 @@ program
 
 program
   .command('uninstall')
-  .description('Remove installed command/skill files')
+  .description('Remove installed skill files')
   .action(async () => {
     const { default: action } = await import('./commands/uninstall.js');
     await action();

package/src/commands/doctor.js

@@ -12,19 +12,19 @@ export default async function doctorAction() {
 
   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;
+  // Check 1: Claude skill harness-init (check both scopes)
+  let initSkillPath = null;
+  const globalInitSkill = resolveTargetPath('skills/harness-init/SKILL.md', 'global');
+  const localInitSkill = resolveTargetPath('skills/harness-init/SKILL.md', 'local');
+  if (await fs.pathExists(globalInitSkill)) {
+    initSkillPath = globalInitSkill;
+  } else if (await fs.pathExists(localInitSkill)) {
+    initSkillPath = localInitSkill;
   }
   checks.push({
-    label: 'Claude command harness-init',
-    status: cmdPath ? 'ok' : 'fail',
-    detail: cmdPath ? `Found at ${cmdPath}` : 'Not installed',
+    label: 'Claude skill harness-init',
+    status: initSkillPath ? 'ok' : 'fail',
+    detail: initSkillPath ? `Found at ${initSkillPath}` : 'Not installed',
     fix: 'Run: harness-kit install',
   });
 
@@ -44,19 +44,19 @@ export default async function doctorAction() {
     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;
+  // Check 3: Claude skill harness-update-spec (check both scopes)
+  let updateSpecSkillPath = null;
+  const globalUpdateSpecSkill = resolveTargetPath('skills/harness-update-spec/SKILL.md', 'global');
+  const localUpdateSpecSkill = resolveTargetPath('skills/harness-update-spec/SKILL.md', 'local');
+  if (await fs.pathExists(globalUpdateSpecSkill)) {
+    updateSpecSkillPath = globalUpdateSpecSkill;
+  } else if (await fs.pathExists(localUpdateSpecSkill)) {
+    updateSpecSkillPath = localUpdateSpecSkill;
   }
   checks.push({
-    label: 'Claude command harness-update-spec',
-    status: updateSpecPath ? 'ok' : 'fail',
-    detail: updateSpecPath ? `Found at ${updateSpecPath}` : 'Not installed',
+    label: 'Claude skill harness-update-spec',
+    status: updateSpecSkillPath ? 'ok' : 'fail',
+    detail: updateSpecSkillPath ? `Found at ${updateSpecSkillPath}` : 'Not installed',
     fix: 'Run: harness-kit install',
   });
 
@@ -109,7 +109,7 @@ export default async function doctorAction() {
     label: '.harness/',
     status: harnessExists ? 'ok' : 'fail',
     detail: harnessExists ? 'Project initialized' : 'Not found',
-    fix: 'Run: /harness-init in Claude',
+    fix: 'Ask Claude to use the harness-init skill',
   });
 
   // Check 8: .comet.yaml
@@ -119,7 +119,7 @@ export default async function doctorAction() {
     label: '.comet.yaml',
     status: cometYamlExists ? 'ok' : 'fail',
     detail: cometYamlExists ? 'Found' : 'Not found',
-    fix: 'Run: /harness-init in Claude or comet init',
+    fix: 'Ask Claude to use the harness-init skill or run comet init',
   });
 
   // Check 8: openspec/

package/src/commands/install.js

@@ -25,7 +25,7 @@ export default async function installAction(options) {
   await ensureClaudeDirs(claudeDir);
 
   // Step 2: Copy files
-  console.log(chalk.bold('Installing commands and skills:'));
+  console.log(chalk.bold('Installing skills:'));
   const fileResults = [];
 
   for (const mapping of FILE_MAPPINGS) {
@@ -113,5 +113,5 @@ export default async function installAction(options) {
   // 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'));
+  console.log(chalk.cyan('  Open Claude and ask it to use the harness-init skill to initialize your project\n'));
 }

package/src/utils/registry.js

@@ -10,12 +10,12 @@ export const PACKAGE_ROOT = path.resolve(__dirname, '..', '..');
 
 export const FILE_MAPPINGS = [
   {
-    source: 'commands/harness-init.md',
-    target: 'commands/harness-init.md',
+    source: 'skills/harness-init',
+    target: 'skills/harness-init',
   },
   {
-    source: 'commands/harness-update-spec.md',
-    target: 'commands/harness-update-spec.md',
+    source: 'skills/harness-update-spec',
+    target: 'skills/harness-update-spec',
   },
   {
     source: 'skills/md-to-html-doc.md',
@@ -33,10 +33,54 @@ export function resolveTargetPath(relativeTarget, scope = 'global') {
 }
 
 export async function hashFile(filePath) {
+  const stat = await fs.stat(filePath);
+
+  if (stat.isDirectory()) {
+    const hash = createHash('sha256');
+    await hashDirectoryInto(hash, filePath, filePath);
+    return hash.digest('hex').slice(0, 12);
+  }
+
   const content = await fs.readFile(filePath);
   return createHash('sha256').update(content).digest('hex').slice(0, 12);
 }
 
+async function hashDirectoryInto(hash, rootDir, currentDir) {
+  const entries = await fs.readdir(currentDir);
+  entries.sort();
+
+  for (const entry of entries) {
+    const fullPath = path.join(currentDir, entry);
+    const stat = await fs.stat(fullPath);
+    const relativePath = path.relative(rootDir, fullPath).replaceAll('\\', '/');
+
+    hash.update(relativePath);
+    hash.update(stat.isDirectory() ? 'dir' : 'file');
+
+    if (stat.isDirectory()) {
+      await hashDirectoryInto(hash, rootDir, fullPath);
+      continue;
+    }
+
+    const content = await fs.readFile(fullPath);
+    hash.update(content);
+  }
+}
+
+async function getPathSize(targetPath) {
+  const stat = await fs.stat(targetPath);
+  if (stat.isFile()) {
+    return stat.size;
+  }
+
+  let total = 0;
+  const entries = await fs.readdir(targetPath);
+  for (const entry of entries) {
+    total += await getPathSize(path.join(targetPath, entry));
+  }
+  return total;
+}
+
 export function getRecordPath(scope = 'global') {
   const claudeDir = resolveClaudeConfigDir({ scope });
   return path.join(claudeDir, 'harness-kit.json');
@@ -72,13 +116,12 @@ export async function copyFileRecord(sourceRel, targetRel, { force = false, scop
   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,
+    size: await getPathSize(tgt),
   };
 }
 

package/commands/harness-init.md

@@ -1,115 +0,0 @@
----
-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

@@ -1,122 +0,0 @@
----
-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`