Version 0.9.0 · CLI: openmole init · openmole update

npm 官方包名 / npm package name: openmole
安装：npm install -g openmole · CLI 命令已更名 openmole

English · 中文

npm official package name: openmole — install with npm install -g openmole. The CLI command is openmole.

OpenMole 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>/.

Main outputs per phase: badsmells.md, tasks.md, analysis.md, and code changes.

openmole/
├── config.yaml              # current_change · installed_ides · init_version · init_at
└── changes/
    ├── <change-name>/
    │   ├── badsmells.md
    │   ├── tasks.md
    │   └── analysis.md
    └── archive/

mole:explore → review badsmells → mole:plan → review tasks → mole:verify → mole:apply → user confirm → mole:archive

openmole/                         # npm package root
├── bin/openmole.js               # CLI entry
├── cli/                     # init · update · IDE adapters
├── skills/                  # phase skills (openmole-*)
├── commands/                # IDE commands (mole-*.md)
├── .cursor-plugin/          # Cursor manifest
├── .claude-plugin/          # Claude Code manifest
├── .codex/                  # Codex install guide
├── gemini-extension.json    # Gemini CLI extension
├── .opencode/plugins/openmole.js # OpenCode plugin (zero npm deps at runtime)
└── templates/               # config / gitignore templates

• Skills / Commands: Markdown + YAML frontmatter
• Plugin harnesses: Cursor, OpenCode, Claude Code, Codex, Gemini CLI, Kiro, Qoder, WorkBuddy, Trae
• CLI: Node.js ESM + @clack/prompts (CLI only; plugin runtime has no third-party npm deps)
• License: MIT

npm registry (recommended)

npm install -g openmole
cd /path/to/your-project
openmole init              # welcome screen → interactive IDE selection

Clone + link (development)

git clone https://github.com/agiledon/openmole.git
cd openmole && npm install && npm link

cd /path/to/your-project
openmole init

Install CLI from GitHub

npm install -g github:agiledon/openmole
cd /path/to/your-project
openmole init

Package name on npm is openmole (the openmole name is taken). The CLI command is openmole.

After upgrading OpenMole, run openmole update in the target project to refresh IDE configs.

openmole init will:

1. Create openmole/config.yaml, openmole/changes/, openmole/changes/archive/
2. Install skills/commands per selected IDE (see table)
3. Merge gitignore snippet into .gitignore (machine-local symlinks)

Extend mode: If openmole/config.yaml exists, workspace is preserved; only IDEs missing from installed_ides are configured.

Re-install IDE configs listed in openmole/config.yaml installed_ides (use after upgrading OpenMole):

openmole update
openmole update /path/to/project
openmole update --dry-run

bash scripts/validate-cli.sh      # full CLI + plugin tests + npm pack check
bash scripts/validate-plugin.sh   # plugin only
bash scripts/npm-pack-check.sh    # tarball content check
npm link && openmole --help

Maintainers: publish with npm publish --access public (package name openmole).

• Plugin architecture inspired by Superpowers
• Change workspace design
• CLI init design
• OpenSpec: mole-cli-init (archived)

OpenMole 框架在 npm 官方包名为 openmole — 安装：npm install -g openmole。CLI 命令已更名 openmole。

OpenMole（坏味道驱动重构）是一套面向编码 Agent 的软件重构方法论与 Plugin 框架。规约内嵌于各 phase skill；目标项目工件位于 openmole/changes/<change-name>/。

当前版本：0.9.0（CLI：openmole init · openmole update）

各阶段主要产出：badsmells.md、tasks.md、analysis.md、代码变更。

openmole/
├── config.yaml              # current_change · installed_ides · init_version · init_at
└── changes/
    ├── <change-name>/
    │   ├── badsmells.md
    │   ├── tasks.md
    │   └── analysis.md
    └── archive/

mole:explore → 审阅 badsmells → mole:plan → 审阅 tasks → mole:verify → mole:apply → 用户确认 → mole:archive

openmole/                         # npm package root
├── bin/openmole.js               # CLI 入口
├── cli/                     # init · update · IDE adapters
├── skills/                  # phase skills（openmole-*）
├── commands/                # IDE commands（mole-*.md）
├── .cursor-plugin/          # Cursor manifest
├── .claude-plugin/          # Claude Code manifest
├── .codex/                  # Codex install guide
├── gemini-extension.json    # Gemini CLI extension
├── .opencode/plugins/openmole.js # OpenCode plugin（零 npm 依赖）
└── templates/               # config / gitignore 模板

• Skill / Command：Markdown + YAML frontmatter
• Plugin harness：Cursor、OpenCode、Claude Code、Codex、Gemini CLI、Kiro、Qoder、WorkBuddy、Trae
• CLI：Node.js ESM + @clack/prompts（仅 CLI；plugin 运行时零第三方依赖）
• 许可证：MIT

npm registry（推荐）

npm install -g openmole
cd /path/to/your-project
openmole init              # welcome 画面 → 交互式选择 IDE

本仓库开发 / 本地 link

git clone https://github.com/agiledon/openmole.git
cd openmole && npm install && npm link

cd /path/to/your-project
openmole init

从 GitHub 安装 CLI

npm install -g github:agiledon/openmole
cd /path/to/your-project
openmole init

npm 包名为 openmole（openmole 已被占用）；CLI 命令已更名 openmole。

升级 OpenMole 后，在目标项目执行 openmole update 刷新 IDE 配置。

openmole init 会：

1. 创建 openmole/config.yaml、openmole/changes/、openmole/changes/archive/
2. 按所选 IDE 安装 skill/command（见下表）
3. 合并 gitignore 片段 到项目 .gitignore（忽略机器相关的 plugin symlink）

Extend 模式：已存在 openmole/config.yaml 时保留 workspace，仅为 installed_ides 中缺失的 IDE 追加配置。

在已 init 的项目中，按 openmole/config.yaml 的 installed_ides 重新安装 IDE 配置（升级 OpenMole 包后使用）：

openmole update              # 当前目录
openmole update /path/to/project
openmole update --dry-run

bash scripts/validate-cli.sh      # CLI + plugin 全量测试 + npm pack 检查
bash scripts/validate-plugin.sh   # plugin only
bash scripts/npm-pack-check.sh    # 发布前 tarball 内容检查
npm link && openmole --help

维护者：npm publish --access public 发布（包名 openmole）。

bash scripts/npm-pack-check.sh    # 验证 tarball 内容
npm pack                          # 本地预览（可选）

• Plugin 架构参考 Superpowers
• Change workspace 设计
• CLI init 设计
• OpenSpec：mole-cli-init（已归档）