{
  "markdown": "# OpenMole — AI-driven Refactoring\n\n![OpenMole Logo](docs/images/logo.jpg)\n\n**Version 0.9.0** · CLI: `openmole init` · `openmole update`\n\n> **npm 官方包名 / npm package name:** [`openmole`](https://www.npmjs.com/package/openmole)  \n> 安装：`npm install -g openmole` · CLI 命令已更名 **`openmole`**\n\n[English](#english) · [中文](#中文)\n\n---\n\n<a id=\"english\"></a>\n\n## English\n\n> **npm official package name:** [`openmole`](https://www.npmjs.com/package/openmole) — install with `npm install -g openmole`. The CLI command is **`openmole`**.\n\nOpenMole is a refactoring methodology and agent plugin framework driven by code bad smells. Rules live in phase skills; project artifacts live under `openmole/changes/<change-name>/`.\n\n### Commands & Skills\n\n| Command (IDE slash / protocol) | Skill | Phase |\n|--------------------------------|-------|-------|\n| `/mole-explore` · `mole:explore` | `openmole-explore` | Create/continue change; identify bad smells |\n| `/mole-plan` · `mole:plan` | `openmole-plan` | Task breakdown |\n| `/mole-verify` · `mole:verify` | `openmole-verify` | Verify coverage |\n| `/mole-apply` · `mole:apply` | `openmole-apply` | Execute refactoring |\n| `/mole-archive` · `mole:archive` | `openmole-archive` | Archive change |\n\nMain outputs per phase: `badsmells.md`, `tasks.md`, `analysis.md`, and code changes.\n\n### Workspace\n\n```\nopenmole/\n├── config.yaml              # current_change · installed_ides · init_version · init_at\n└── changes/\n    ├── <change-name>/\n    │   ├── badsmells.md\n    │   ├── tasks.md\n    │   └── analysis.md\n    └── archive/\n```\n\n### Workflow\n\n```\nmole:explore → review badsmells → mole:plan → review tasks → mole:verify → mole:apply → user confirm → mole:archive\n```\n\n### Package layout\n\n```\nopenmole/                         # npm package root\n├── bin/openmole.js               # CLI entry\n├── cli/                     # init · update · IDE adapters\n├── skills/                  # phase skills (openmole-*)\n├── commands/                # IDE commands (mole-*.md)\n├── .cursor-plugin/          # Cursor manifest\n├── .claude-plugin/          # Claude Code manifest\n├── .codex/                  # Codex install guide\n├── gemini-extension.json    # Gemini CLI extension\n├── .opencode/plugins/openmole.js # OpenCode plugin (zero npm deps at runtime)\n└── templates/               # config / gitignore templates\n```\n\n### Tech stack\n\n- **Skills / Commands**: Markdown + YAML frontmatter\n- **Plugin harnesses**: Cursor, OpenCode, Claude Code, Codex, Gemini CLI, Kiro, Qoder, WorkBuddy, Trae\n- **CLI**: Node.js ESM + `@clack/prompts` (CLI only; plugin runtime has no third-party npm deps)\n- **License**: MIT\n\n### Installation\n\n**npm registry (recommended)**\n\n```bash\nnpm install -g openmole\ncd /path/to/your-project\nopenmole init              # welcome screen → interactive IDE selection\n```\n\n**Clone + link (development)**\n\n```bash\ngit clone https://github.com/agiledon/openmole.git\ncd openmole && npm install && npm link\n\ncd /path/to/your-project\nopenmole init\n```\n\n**Install CLI from GitHub**\n\n```bash\nnpm install -g github:agiledon/openmole\ncd /path/to/your-project\nopenmole init\n```\n\n> Package name on npm is **`openmole`** (the `openmole` name is taken). The CLI command is **`openmole`**.\n\nAfter upgrading OpenMole, run `openmole update` in the target project to refresh IDE configs.\n\n#### `openmole init` options\n\n| Flag | Description |\n|------|-------------|\n| `--ides cursor,opencode,...` | Non-interactive IDE list |\n| `--all` | Configure all 9 IDEs |\n| `--none` | Workspace only (`openmole/`) |\n| `--force` | Overwrite existing workspace / IDE config |\n| `--global` | OpenCode user config (`~/.config/opencode/`) |\n| `--dry-run` | Print plan only |\n\n`openmole init` will:\n\n1. Create `openmole/config.yaml`, `openmole/changes/`, `openmole/changes/archive/`\n2. Install skills/commands per selected IDE (see table)\n3. Merge [gitignore snippet](templates/mole-gitignore.snippet) into `.gitignore` (machine-local symlinks)\n\n| IDE | Install model |\n|-----|---------------|\n| **Cursor** | Project `.cursor/skills/` + `.cursor/commands/`; user symlink `~/.cursor/plugins/local/openmole` |\n| **OpenCode** | Project `opencode.json` → `.opencode/plugins/openmole.js` (`--global` → user config) |\n| **Claude Code** | Project `.claude/skills/` + `.claude/commands/`; user symlink `~/.claude/plugins/local/openmole` |\n| **Codex** | Project `.codex/skills/` (skills only, Codex does not expose slash commands) |\n| **Gemini CLI** | Project `.gemini/skills/`, `.gemini/commands/`, `.gemini/extensions/openmole` symlink |\n| **Kiro** | Project `.kiro/skills/`, `.kiro/commands/` |\n| **Qoder** | Project `.qoder/skills/`, `.qoder/commands/` |\n| **WorkBuddy** | Project `.workbuddy/skills/`, `.workbuddy/commands/` |\n| **Trae** | Project `.trae/skills/` (no slash commands; skills auto-discovered) |\n\n**Extend mode**: If `openmole/config.yaml` exists, workspace is preserved; only IDEs missing from `installed_ides` are configured.\n\n#### `openmole update`\n\nRe-install IDE configs listed in `openmole/config.yaml` `installed_ides` (use after upgrading OpenMole):\n\n```bash\nopenmole update\nopenmole update /path/to/project\nopenmole update --dry-run\n```\n\n#### Manual install (fallback)\n\n| IDE | Doc |\n|-----|-----|\n| Cursor | [.cursor/INSTALL.md](.cursor/INSTALL.md) |\n| OpenCode | [.opencode/INSTALL.md](.opencode/INSTALL.md) |\n| Claude Code | [.claude/INSTALL.md](.claude/INSTALL.md) |\n| Codex | [.codex/INSTALL.md](.codex/INSTALL.md) |\n| Gemini CLI | [.gemini/INSTALL.md](.gemini/INSTALL.md) |\n| Kiro | [.kiro/INSTALL.md](.kiro/INSTALL.md) |\n| Qoder | [.qoder/INSTALL.md](.qoder/INSTALL.md) |\n| WorkBuddy | [.workbuddy/INSTALL.md](.workbuddy/INSTALL.md) |\n| Trae | [.trae/INSTALL.md](.trae/INSTALL.md) |\n\n### Development\n\n```bash\nbash scripts/validate-cli.sh      # full CLI + plugin tests + npm pack check\nbash scripts/validate-plugin.sh   # plugin only\nbash scripts/npm-pack-check.sh    # tarball content check\nnpm link && openmole --help\n```\n\n**Maintainers**: publish with `npm publish --access public` (package name `openmole`).\n\n### References\n\n- Plugin architecture inspired by [Superpowers](https://github.com/agiledon/superpowers)\n- [Change workspace design](docs/design/2026-06-05-mole-change-workspace-design.md)\n- [CLI init design](docs/design/2026-06-05-mole-cli-init-design.md)\n- [OpenSpec: mole-cli-init (archived)](openspec/changes/archive/2026-06-05-mole-cli-init/proposal.md)\n\n---\n\n<a id=\"中文\"></a>\n\n## 中文\n\n> **OpenMole 框架在 npm 官方包名为 [`openmole`](https://www.npmjs.com/package/openmole)** — 安装：`npm install -g openmole`。CLI 命令已更名 **`openmole`**。\n\nOpenMole（坏味道驱动重构）是一套面向编码 Agent 的软件重构方法论与 Plugin 框架。规约内嵌于各 phase skill；目标项目工件位于 `openmole/changes/<change-name>/`。\n\n**当前版本**：0.9.0（CLI：`openmole init` · `openmole update`）\n\n### 命令与 Skill\n\n| 命令（IDE slash / 协议） | Skill | 阶段 |\n|--------------------------|-------|------|\n| `/mole-explore` · `mole:explore` | `openmole-explore` | 创建/继续 change，识别坏味道 |\n| `/mole-plan` · `mole:plan` | `openmole-plan` | 任务分解 |\n| `/mole-verify` · `mole:verify` | `openmole-verify` | 覆盖验证 |\n| `/mole-apply` · `mole:apply` | `openmole-apply` | 重构执行 |\n| `/mole-archive` · `mole:archive` | `openmole-archive` | 归档 change |\n\n各阶段主要产出：`badsmells.md`、`tasks.md`、`analysis.md`、代码变更。\n\n### 工作区\n\n```\nopenmole/\n├── config.yaml              # current_change · installed_ides · init_version · init_at\n└── changes/\n    ├── <change-name>/\n    │   ├── badsmells.md\n    │   ├── tasks.md\n    │   └── analysis.md\n    └── archive/\n```\n\n### 工作流\n\n```\nmole:explore → 审阅 badsmells → mole:plan → 审阅 tasks → mole:verify → mole:apply → 用户确认 → mole:archive\n```\n\n### 包结构\n\n```\nopenmole/                         # npm package root\n├── bin/openmole.js               # CLI 入口\n├── cli/                     # init · update · IDE adapters\n├── skills/                  # phase skills（openmole-*）\n├── commands/                # IDE commands（mole-*.md）\n├── .cursor-plugin/          # Cursor manifest\n├── .claude-plugin/          # Claude Code manifest\n├── .codex/                  # Codex install guide\n├── gemini-extension.json    # Gemini CLI extension\n├── .opencode/plugins/openmole.js # OpenCode plugin（零 npm 依赖）\n└── templates/               # config / gitignore 模板\n```\n\n### 技术栈\n\n- **Skill / Command**：Markdown + YAML frontmatter\n- **Plugin harness**：Cursor、OpenCode、Claude Code、Codex、Gemini CLI、Kiro、Qoder、WorkBuddy、Trae\n- **CLI**：Node.js ESM + `@clack/prompts`（仅 CLI；plugin 运行时零第三方依赖）\n- **许可证**：MIT\n\n### 安装\n\n**npm registry（推荐）**\n\n```bash\nnpm install -g openmole\ncd /path/to/your-project\nopenmole init              # welcome 画面 → 交互式选择 IDE\n```\n\n**本仓库开发 / 本地 link**\n\n```bash\ngit clone https://github.com/agiledon/openmole.git\ncd openmole && npm install && npm link\n\ncd /path/to/your-project\nopenmole init\n```\n\n**从 GitHub 安装 CLI**\n\n```bash\nnpm install -g github:agiledon/openmole\ncd /path/to/your-project\nopenmole init\n```\n\n> npm 包名为 **`openmole`**（`openmole` 已被占用）；CLI 命令已更名 **`openmole`**。\n\n升级 OpenMole 后，在目标项目执行 `openmole update` 刷新 IDE 配置。\n\n#### `openmole init` 常用选项\n\n| 选项 | 说明 |\n|------|------|\n| `--ides cursor,opencode,...` | 非交互指定 IDE |\n| `--all` | 配置全部 9 个 IDE |\n| `--none` | 仅创建 `openmole/` 工作区 |\n| `--force` | 覆盖已有 workspace / IDE 配置 |\n| `--global` | OpenCode 写入用户级 `~/.config/opencode/` |\n| `--dry-run` | 只打印计划，不写文件 |\n\n`openmole init` 会：\n\n1. 创建 `openmole/config.yaml`、`openmole/changes/`、`openmole/changes/archive/`\n2. 按所选 IDE 安装 skill/command（见下表）\n3. 合并 [gitignore 片段](templates/mole-gitignore.snippet) 到项目 `.gitignore`（忽略机器相关的 plugin symlink）\n\n| IDE | 安装方式 |\n|-----|----------|\n| **Cursor** | 项目 `.cursor/skills/` + `.cursor/commands/`；用户级 `~/.cursor/plugins/local/openmole` symlink |\n| **OpenCode** | 项目 `opencode.json` 注册 `.opencode/plugins/openmole.js`（`--global` → 用户配置） |\n| **Claude Code** | 项目 `.claude/skills/` + `.claude/commands/`；用户级 `~/.claude/plugins/local/openmole` symlink |\n| **Codex** | 项目 `.codex/skills/`（仅 skill，Codex 无 slash 命令概念） |\n| **Gemini CLI** | 项目 `.gemini/skills/`、`.gemini/commands/`、`.gemini/extensions/openmole` symlink |\n| **Kiro** | 项目 `.kiro/skills/`、`.kiro/commands/` |\n| **Qoder** | 项目 `.qoder/skills/`、`.qoder/commands/` |\n| **WorkBuddy** | 项目 `.workbuddy/skills/`、`.workbuddy/commands/` |\n| **Trae** | 项目 `.trae/skills/`（无 slash 命令；skill 自动发现） |\n\n**Extend 模式**：已存在 `openmole/config.yaml` 时保留 workspace，仅为 `installed_ides` 中缺失的 IDE 追加配置。\n\n#### `openmole update`\n\n在已 init 的项目中，按 `openmole/config.yaml` 的 `installed_ides` 重新安装 IDE 配置（升级 OpenMole 包后使用）：\n\n```bash\nopenmole update              # 当前目录\nopenmole update /path/to/project\nopenmole update --dry-run\n```\n\n#### 手动安装（fallback）\n\n| IDE | 文档 |\n|-----|------|\n| Cursor | [.cursor/INSTALL.md](.cursor/INSTALL.md) |\n| OpenCode | [.opencode/INSTALL.md](.opencode/INSTALL.md) |\n| Claude Code | [.claude/INSTALL.md](.claude/INSTALL.md) |\n| Codex | [.codex/INSTALL.md](.codex/INSTALL.md) |\n| Gemini CLI | [.gemini/INSTALL.md](.gemini/INSTALL.md) |\n| Kiro | [.kiro/INSTALL.md](.kiro/INSTALL.md) |\n| Qoder | [.qoder/INSTALL.md](.qoder/INSTALL.md) |\n| WorkBuddy | [.workbuddy/INSTALL.md](.workbuddy/INSTALL.md) |\n| Trae | [.trae/INSTALL.md](.trae/INSTALL.md) |\n\n### 开发验证\n\n```bash\nbash scripts/validate-cli.sh      # CLI + plugin 全量测试 + npm pack 检查\nbash scripts/validate-plugin.sh   # plugin only\nbash scripts/npm-pack-check.sh    # 发布前 tarball 内容检查\nnpm link && openmole --help\n```\n\n**维护者**：`npm publish --access public` 发布（包名 `openmole`）。\n\n```bash\nbash scripts/npm-pack-check.sh    # 验证 tarball 内容\nnpm pack                          # 本地预览（可选）\n```\n\n### 设计参考\n\n- Plugin 架构参考 [Superpowers](https://github.com/agiledon/superpowers)\n- [Change workspace 设计](docs/design/2026-06-05-mole-change-workspace-design.md)\n- [CLI init 设计](docs/design/2026-06-05-mole-cli-init-design.md)\n- [OpenSpec：mole-cli-init（已归档）](openspec/changes/archive/2026-06-05-mole-cli-init/proposal.md)\n",
  "bytes": 11764,
  "sha": "4447c9dedec31ea4c51ef8161f7a038e3e3c4ddc981fb76b81db75550da05508",
  "repo_slug": "agiledon/openmole",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_agiledon_openmole_d99115e9/readme"
}