@markuplint/create-rule 4.7.22 → 4.18.0

package/ARCHITECTURE.ja.md

@@ -0,0 +1,194 @@
+# @markuplint/create-rule
+
+## 概要
+
+`@markuplint/create-rule` は markuplint ルールのスキャフォルディング CLI です。対話型ウィザードでユーザーからパラメータを収集し、3つのスキャフォルド戦略のいずれかにディスパッチして、ルール開発に必要なボイラープレートファイルを生成します。また、非対話的に使用するためのプログラマティック API（`createRuleHelper()`）も公開しています。
+
+## ディレクトリ構成
+
+```
+src/
+├── cli.ts                        — 対話型 CLI ウィザード（bin のエントリポイント）
+├── types.ts                      — 型定義（Purpose, Params, Result, File）
+├── create-rule-helper.ts         — 目的ベースルーター（戦略にディスパッチ）
+├── create-rule-to-project.ts     — 戦略: 現在のプロジェクトにルールを追加
+├── create-rule-package.ts        — 戦略: スタンドアロン npm パッケージを作成
+├── create-rule-to-core.ts        — 戦略: コアルールに貢献
+├── install-scaffold.ts           — 低レベルスキャフォルドインストーラー
+├── transfer.ts                   — テンプレートの転送、置換、トランスパイル、フォーマット
+├── is-markuplint-repo.ts         — cwd が markuplint モノレポ内かを検出
+├── search-core-repository.ts     — モノレポルートを上方向に検索
+├── read-package-json.ts          — package.json の読み取りとパース
+├── fs-exists.ts                  — ファイル存在チェックユーティリティ
+├── glob.ts                       — Glob ラッパー
+└── create-rule-helper-error.ts   — カスタムエラークラス
+bin/
+└── create-rule.mjs               — Node.js 実行ファイル（cli.ts を呼び出す）
+scaffold/
+├── core/                         — コアルール貢献用テンプレート
+│   ├── index.ts                  — ルール実装テンプレート
+│   ├── index.spec.ts             — テストテンプレート
+│   ├── meta.ts                   — ルールメタデータテンプレート
+│   ├── schema.json               — JSON Schema テンプレート
+│   ├── README.md                 — 英語ドキュメントテンプレート
+│   └── README.ja.md              — 日本語ドキュメントテンプレート
+├── project/                      — プロジェクトローカルプラグイン用テンプレート
+│   ├── index.ts                  — プラグインエントリポイントテンプレート
+│   └── rules/
+│       ├── __ruleName__.ts       — ルール実装テンプレート
+│       └── __ruleName__.spec.ts  — テストテンプレート
+└── package/                      — 公開パッケージ用テンプレート
+    ├── README.md                 — パッケージ README テンプレート
+    ├── tsconfig.json             — TypeScript 設定テンプレート
+    └── src/
+        ├── index.ts              — プラグインエントリポイントテンプレート
+        └── rules/
+            └── __ruleName__.ts   — ルール実装テンプレート
+```
+
+## アーキテクチャ図
+
+```mermaid
+flowchart TD
+    subgraph cli ["CLI レイヤー"]
+        bin["bin/create-rule.mjs"]
+        wizard["cli.ts\n対話型ウィザード"]
+    end
+
+    subgraph router ["ルーター"]
+        helper["create-rule-helper.ts\ncreateRuleHelper()"]
+    end
+
+    subgraph strategies ["スキャフォルド戦略"]
+        project["create-rule-to-project.ts\nプロジェクトに追加"]
+        package["create-rule-package.ts\nパッケージとして公開"]
+        core["create-rule-to-core.ts\nコアに貢献"]
+    end
+
+    subgraph engine ["スキャフォルドエンジン"]
+        install["install-scaffold.ts\ninstallScaffold()"]
+        transfer["transfer.ts\ntransfer()"]
+    end
+
+    subgraph templates ["テンプレート"]
+        tplProject["scaffold/project/"]
+        tplPackage["scaffold/package/"]
+        tplCore["scaffold/core/"]
+    end
+
+    bin --> wizard
+    wizard -->|"params"| helper
+    helper -->|"ADD_TO_PROJECT"| project
+    helper -->|"PUBLISH_AS_PACKAGE"| package
+    helper -->|"CONTRIBUTE_TO_CORE"| core
+    project --> install
+    package --> install
+    core --> install
+    install --> transfer
+    transfer -->|"read"| tplProject
+    transfer -->|"read"| tplPackage
+    transfer -->|"read"| tplCore
+```
+
+## CLI フロー
+
+CLI バイナリ（`bin/create-rule.mjs`）は `cli.ts` の `createRule()` を呼び出し、`@markuplint/cli-utils` を使用して対話型の質問シーケンスを実行します:
+
+1. **目的の選択** — `ADD_TO_PROJECT`、`PUBLISH_AS_PACKAGE`、`CONTRIBUTE_TO_CORE` のいずれか（コアオプションは markuplint モノレポ内でのみ表示）
+2. **プラグイン/ディレクトリ名** — ケバブケースの識別子（コアの場合はスキップ）
+3. **ルール名** — ケバブケースの識別子
+4. **コア固有の質問** — 説明、カテゴリ、重大度（`CONTRIBUTE_TO_CORE` の場合のみ）
+5. **言語** — TypeScript または JavaScript（コアは常に TypeScript）
+6. **テスト生成** — 真偽値（コアは常にテストを含む）
+
+収集されたパラメータは `createRuleHelper()` に渡され、適切な戦略にルーティングされます。
+
+## スキャフォルド戦略
+
+### `createRuleToProject()`
+
+`<cwd>/<pluginName>/` にプラグインディレクトリを作成します。ディレクトリが既に存在する場合は失敗します。`scaffold/project/` テンプレートを使用します。
+
+### `createRulePackage()`
+
+現在の作業ディレクトリにスキャフォルドします。ディレクトリが空である必要があります。`scaffold/package/` テンプレートを使用し、ビルド/テストスクリプトと依存関係の宣言を含む `package.json` を追加で生成します。
+
+### `createRuleToCore()`
+
+markuplint モノレポ内の `packages/@markuplint/rules/src/<ruleName>/` にルールディレクトリを作成します。`searchCoreRepository()` で cwd から上方向にリポジトリルートを検索します。ルールディレクトリが既に存在する場合、またはモノレポルートが見つからない場合は失敗します。TypeScript とテストが常に有効な状態で `scaffold/core/` テンプレートを使用します。
+
+## テンプレートシステム
+
+スキャフォルドエンジンは3つのステージでテンプレートファイルを処理します:
+
+### 1. プレースホルダー置換
+
+テンプレートファイルにはダブルアンダースコアのプレースホルダーが含まれ、ユーザー指定の値に置換されます:
+
+| プレースホルダー  | 置換内容                       | 例                              |
+| ----------------- | ------------------------------ | ------------------------------- |
+| `__pluginName__`  | プラグイン名（そのまま）       | `my-plugin`                     |
+| `__pluginName__c` | プラグイン名（キャメルケース） | `myPlugin`                      |
+| `__ruleName__`    | ルール名（そのまま）           | `no-empty-alt`                  |
+| `__ruleName__c`   | ルール名（キャメルケース）     | `noEmptyAlt`                    |
+| `__description__` | ルールの説明（コアのみ）       | `Disallow empty alt attributes` |
+| `__category__`    | ルールカテゴリ（コアのみ）     | `validation`                    |
+| `__severity__`    | デフォルト重大度（コアのみ）   | `error`                         |
+
+`__<name>__c` サフィックスはキャメルケース変換をトリガーします。ハイフンが除去され、次の文字が大文字化されます（例: `my-rule` → `myRule`）。
+
+`__ruleName__` を含むファイル名も実際のルール名にリネームされます。
+
+### 2. TypeScript から JavaScript へのトランスパイル（オプション）
+
+ユーザーが JavaScript を選択した場合、`.ts` ファイルは TypeScript コンパイラ API（`tsc.transpile()`）を使用して ESNext ターゲットでトランスパイルされます。生成された `.js` ファイルでは、可読性のためにコメントと `export` キーワードの前に空行が挿入されます。
+
+### 3. Prettier フォーマット
+
+すべての出力ファイルは Prettier でフォーマットされます。テンプレート内の `// prettier-ignore` コメントはフォーマット前に自動的に削除されます。
+
+## スキャフォルドテンプレート
+
+### コアテンプレート（`scaffold/core/`）
+
+| テンプレート    | 生成ファイル    | 内容                                                  |
+| --------------- | --------------- | ----------------------------------------------------- |
+| `index.ts`      | `index.ts`      | Element/Attr ウォーカーを使った `createRule()` ルール |
+| `index.spec.ts` | `index.spec.ts` | markuplint の `mlRuleTest()` を使ったテスト           |
+| `meta.ts`       | `meta.ts`       | ルールメタデータ（カテゴリ）                          |
+| `schema.json`   | `schema.json`   | ルール値/オプションの JSON Schema                     |
+| `README.md`     | `README.md`     | 例付き英語ドキュメント                                |
+| `README.ja.md`  | `README.ja.md`  | 例付き日本語ドキュメント                              |
+
+### プロジェクトテンプレート（`scaffold/project/`）
+
+| テンプレート                 | 生成ファイル               | 内容                                        |
+| ---------------------------- | -------------------------- | ------------------------------------------- |
+| `index.ts`                   | `index.ts`                 | `createPlugin()` を使ったプラグインエントリ |
+| `rules/__ruleName__.ts`      | `rules/<ruleName>.ts`      | コメントチェックの例を含むルール            |
+| `rules/__ruleName__.spec.ts` | `rules/<ruleName>.spec.ts` | 期待される違反アサーション付きテスト        |
+
+### パッケージテンプレート（`scaffold/package/`）
+
+| テンプレート                | 生成ファイル              | 内容                                        |
+| --------------------------- | ------------------------- | ------------------------------------------- |
+| `README.md`                 | `README.md`               | インストール/設定付きパッケージドキュメント |
+| `tsconfig.json`             | `tsconfig.json`           | TypeScript 設定                             |
+| `src/index.ts`              | `src/index.ts`            | `createPlugin()` を使ったプラグインエントリ |
+| `src/rules/__ruleName__.ts` | `src/rules/<ruleName>.ts` | コメントチェックの例を含むルール            |
+
+加えて、`installScaffold()` は適切なスクリプトと依存関係を含む `package.json` をプログラム的に（テンプレートからではなく）生成します。
+
+## 主要ソースファイル
+
+| ファイル                        | 役割                                                                          |
+| ------------------------------- | ----------------------------------------------------------------------------- |
+| `bin/create-rule.mjs`           | CLI 実行ファイルエントリポイント                                              |
+| `src/cli.ts`                    | 対話型質問ウィザード                                                          |
+| `src/types.ts`                  | 型定義（`CreateRulePurpose`、`CreateRuleHelperParams`、`File`）               |
+| `src/create-rule-helper.ts`     | スキャフォルド戦略にディスパッチする目的ベースルーター                        |
+| `src/create-rule-to-project.ts` | プロジェクトローカルプラグインのスキャフォルド戦略                            |
+| `src/create-rule-package.ts`    | 公開可能な npm パッケージのスキャフォルド戦略                                 |
+| `src/create-rule-to-core.ts`    | コアルール貢献のスキャフォルド戦略                                            |
+| `src/install-scaffold.ts`       | 低レベルスキャフォルドインストーラー（テンプレートコピー、package.json 生成） |
+| `src/transfer.ts`               | テンプレート処理（置換、トランスパイル、Prettier フォーマット）               |

package/ARCHITECTURE.md

@@ -0,0 +1,194 @@
+# @markuplint/create-rule
+
+## Overview
+
+`@markuplint/create-rule` is the scaffolding CLI for markuplint rules. It provides an interactive wizard that collects parameters from the user and dispatches to one of three scaffold strategies, each generating the boilerplate files needed for rule development. The package also exposes a programmatic API (`createRuleHelper()`) for non-interactive use.
+
+## Directory Structure
+
+```
+src/
+├── cli.ts                        — Interactive CLI wizard (entry point for bin)
+├── types.ts                      — Type definitions (Purpose, Params, Result, File)
+├── create-rule-helper.ts         — Purpose-based router (dispatches to strategies)
+├── create-rule-to-project.ts     — Strategy: add rule to current project
+├── create-rule-package.ts        — Strategy: create standalone npm package
+├── create-rule-to-core.ts        — Strategy: contribute to core rules
+├── install-scaffold.ts           — Low-level scaffold installer
+├── transfer.ts                   — Template transfer, replacement, transpile, format
+├── is-markuplint-repo.ts         — Detects if cwd is inside the markuplint monorepo
+├── search-core-repository.ts     — Searches upward for the monorepo root
+├── read-package-json.ts          — Reads and parses package.json
+├── fs-exists.ts                  — File existence check utility
+├── glob.ts                       — Glob wrapper
+└── create-rule-helper-error.ts   — Custom error class
+bin/
+└── create-rule.mjs               — Node.js executable (calls cli.ts)
+scaffold/
+├── core/                         — Templates for core rule contribution
+│   ├── index.ts                  — Rule implementation template
+│   ├── index.spec.ts             — Test template
+│   ├── meta.ts                   — Rule metadata template
+│   ├── schema.json               — JSON Schema template
+│   ├── README.md                 — English docs template
+│   └── README.ja.md              — Japanese docs template
+├── project/                      — Templates for project-local plugin
+│   ├── index.ts                  — Plugin entry point template
+│   └── rules/
+│       ├── __ruleName__.ts       — Rule implementation template
+│       └── __ruleName__.spec.ts  — Test template
+└── package/                      — Templates for publishable package
+    ├── README.md                 — Package README template
+    ├── tsconfig.json             — TypeScript config template
+    └── src/
+        ├── index.ts              — Plugin entry point template
+        └── rules/
+            └── __ruleName__.ts   — Rule implementation template
+```
+
+## Architecture Diagram
+
+```mermaid
+flowchart TD
+    subgraph cli ["CLI Layer"]
+        bin["bin/create-rule.mjs"]
+        wizard["cli.ts\nInteractive wizard"]
+    end
+
+    subgraph router ["Router"]
+        helper["create-rule-helper.ts\ncreateRuleHelper()"]
+    end
+
+    subgraph strategies ["Scaffold Strategies"]
+        project["create-rule-to-project.ts\nAdd to project"]
+        package["create-rule-package.ts\nPublish as package"]
+        core["create-rule-to-core.ts\nContribute to core"]
+    end
+
+    subgraph engine ["Scaffold Engine"]
+        install["install-scaffold.ts\ninstallScaffold()"]
+        transfer["transfer.ts\ntransfer()"]
+    end
+
+    subgraph templates ["Templates"]
+        tplProject["scaffold/project/"]
+        tplPackage["scaffold/package/"]
+        tplCore["scaffold/core/"]
+    end
+
+    bin --> wizard
+    wizard -->|"params"| helper
+    helper -->|"ADD_TO_PROJECT"| project
+    helper -->|"PUBLISH_AS_PACKAGE"| package
+    helper -->|"CONTRIBUTE_TO_CORE"| core
+    project --> install
+    package --> install
+    core --> install
+    install --> transfer
+    transfer -->|"read"| tplProject
+    transfer -->|"read"| tplPackage
+    transfer -->|"read"| tplCore
+```
+
+## CLI Flow
+
+The CLI binary (`bin/create-rule.mjs`) calls `createRule()` from `cli.ts`, which runs an interactive question sequence using `@markuplint/cli-utils`:
+
+1. **Purpose selection** — One of: `ADD_TO_PROJECT`, `PUBLISH_AS_PACKAGE`, `CONTRIBUTE_TO_CORE` (core option only appears inside the markuplint monorepo)
+2. **Plugin/directory name** — Kebab-case identifier (skipped for core)
+3. **Rule name** — Kebab-case identifier
+4. **Core-specific questions** — Description, category, severity (only for `CONTRIBUTE_TO_CORE`)
+5. **Language** — TypeScript or JavaScript (core always uses TypeScript)
+6. **Test generation** — Boolean (core always includes tests)
+
+The collected parameters are passed to `createRuleHelper()`, which routes to the appropriate strategy.
+
+## Scaffold Strategies
+
+### `createRuleToProject()`
+
+Creates a plugin directory at `<cwd>/<pluginName>/`. Fails if the directory already exists. Uses the `scaffold/project/` templates.
+
+### `createRulePackage()`
+
+Scaffolds in the current working directory. Requires the directory to be empty. Uses the `scaffold/package/` templates and generates an additional `package.json` with build/test scripts and dependency declarations.
+
+### `createRuleToCore()`
+
+Creates a rule directory at `packages/@markuplint/rules/src/<ruleName>/` within the markuplint monorepo. Searches upward from the cwd to find the repository root via `searchCoreRepository()`. Fails if the rule directory already exists or if the monorepo root is not found. Uses the `scaffold/core/` templates with TypeScript and tests always enabled.
+
+## Template System
+
+The scaffold engine processes template files through three stages:
+
+### 1. Placeholder Replacement
+
+Template files contain double-underscore placeholders that are replaced with user-provided values:
+
+| Placeholder       | Replaced with                | Example                         |
+| ----------------- | ---------------------------- | ------------------------------- |
+| `__pluginName__`  | Plugin name (as-is)          | `my-plugin`                     |
+| `__pluginName__c` | Plugin name (camelCase)      | `myPlugin`                      |
+| `__ruleName__`    | Rule name (as-is)            | `no-empty-alt`                  |
+| `__ruleName__c`   | Rule name (camelCase)        | `noEmptyAlt`                    |
+| `__description__` | Rule description (core only) | `Disallow empty alt attributes` |
+| `__category__`    | Rule category (core only)    | `validation`                    |
+| `__severity__`    | Default severity (core only) | `error`                         |
+
+The `__<name>__c` suffix triggers camelCase conversion: hyphens are removed and the following letter is uppercased (e.g., `my-rule` becomes `myRule`).
+
+File names containing `__ruleName__` are also renamed to the actual rule name.
+
+### 2. TypeScript-to-JavaScript Transpilation (optional)
+
+When the user selects JavaScript, `.ts` files are transpiled using the TypeScript compiler API (`tsc.transpile()`) targeting ESNext. The resulting `.js` files have blank lines inserted before comments and `export` keywords for readability.
+
+### 3. Prettier Formatting
+
+All output files are formatted with Prettier. Any `// prettier-ignore` comments in templates are automatically stripped before formatting.
+
+## Scaffold Templates
+
+### Core templates (`scaffold/core/`)
+
+| Template        | Generated file  | Content                                             |
+| --------------- | --------------- | --------------------------------------------------- |
+| `index.ts`      | `index.ts`      | Rule using `createRule()` with Element/Attr walkers |
+| `index.spec.ts` | `index.spec.ts` | Test using `mlRuleTest()` from markuplint           |
+| `meta.ts`       | `meta.ts`       | Rule metadata (category)                            |
+| `schema.json`   | `schema.json`   | JSON Schema for rule value/options                  |
+| `README.md`     | `README.md`     | English documentation with examples                 |
+| `README.ja.md`  | `README.ja.md`  | Japanese documentation with examples                |
+
+### Project templates (`scaffold/project/`)
+
+| Template                     | Generated file             | Content                                 |
+| ---------------------------- | -------------------------- | --------------------------------------- |
+| `index.ts`                   | `index.ts`                 | Plugin entry using `createPlugin()`     |
+| `rules/__ruleName__.ts`      | `rules/<ruleName>.ts`      | Rule with comment-checking example      |
+| `rules/__ruleName__.spec.ts` | `rules/<ruleName>.spec.ts` | Test with expected violation assertions |
+
+### Package templates (`scaffold/package/`)
+
+| Template                    | Generated file            | Content                                   |
+| --------------------------- | ------------------------- | ----------------------------------------- |
+| `README.md`                 | `README.md`               | Package documentation with install/config |
+| `tsconfig.json`             | `tsconfig.json`           | TypeScript configuration                  |
+| `src/index.ts`              | `src/index.ts`            | Plugin entry using `createPlugin()`       |
+| `src/rules/__ruleName__.ts` | `src/rules/<ruleName>.ts` | Rule with comment-checking example        |
+
+Additionally, `installScaffold()` generates a `package.json` programmatically (not from a template) with appropriate scripts and dependencies.
+
+## Key Source Files
+
+| File                            | Role                                                                     |
+| ------------------------------- | ------------------------------------------------------------------------ |
+| `bin/create-rule.mjs`           | CLI executable entry point                                               |
+| `src/cli.ts`                    | Interactive question wizard                                              |
+| `src/types.ts`                  | Type definitions (`CreateRulePurpose`, `CreateRuleHelperParams`, `File`) |
+| `src/create-rule-helper.ts`     | Purpose-based router dispatching to scaffold strategies                  |
+| `src/create-rule-to-project.ts` | Scaffold strategy for project-local plugins                              |
+| `src/create-rule-package.ts`    | Scaffold strategy for publishable npm packages                           |
+| `src/create-rule-to-core.ts`    | Scaffold strategy for core rule contributions                            |
+| `src/install-scaffold.ts`       | Low-level scaffold installer (copies templates, generates package.json)  |
+| `src/transfer.ts`               | Template processing (replacement, transpile, Prettier format)            |

package/CHANGELOG.md

@@ -3,13 +3,23 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [4.7.22](https://github.com/markuplint/markuplint/compare/@markuplint/create-rule@4.7.21...@markuplint/create-rule@4.7.22) (2025-11-05)
+# [4.18.0](https://github.com/markuplint/markuplint/compare/v4.14.1...v4.18.0) (2026-04-22)
+
+**Note:** Version bump only for package @markuplint/create-rule
+
+## [4.8.1](https://github.com/markuplint/markuplint/compare/@markuplint/create-rule@4.8.0...@markuplint/create-rule@4.8.1) (2026-04-21)
 
 **Note:** Version bump only for package @markuplint/create-rule
 
+# [4.8.0](https://github.com/markuplint/markuplint/compare/@markuplint/create-rule@4.7.22...@markuplint/create-rule@4.8.0) (2026-02-10)
 
+### Features
 
+- **create-rule:** add non-interactive CLI mode for AI/automation usage ([33443c6](https://github.com/markuplint/markuplint/commit/33443c63c508023b560f5386580ecdb40bf1fae2))
 
+## [4.7.22](https://github.com/markuplint/markuplint/compare/@markuplint/create-rule@4.7.21...@markuplint/create-rule@4.7.22) (2025-11-05)
+
+**Note:** Version bump only for package @markuplint/create-rule
 
 ## [4.7.21](https://github.com/markuplint/markuplint/compare/@markuplint/create-rule@4.7.20...@markuplint/create-rule@4.7.21) (2025-08-24)
 

package/README.md

@@ -2,8 +2,133 @@
 
 [![npm version](https://badge.fury.io/js/%40markuplint%2Fcreate-rule.svg)](https://www.npmjs.com/package/@markuplint/create-rule)
 
+## Overview
+
+A CLI scaffolding tool for creating new markuplint rules. It provides both an interactive wizard and a non-interactive CLI mode that generates all the boilerplate files needed for rule development, including source files, tests, and configuration.
+
 ## Usage
 
+### Interactive mode
+
+Run without arguments to start the guided wizard:
+
 ```shell
 $ npx @markuplint/create-rule
 ```
+
+### Non-interactive mode
+
+Pass CLI options to create a rule in a single command:
+
+```shell
+# Add a rule to this project
+$ npx @markuplint/create-rule -p project -n my-plugin -r no-empty-alt
+
+# Create a publishable package (JavaScript, no tests)
+$ npx @markuplint/create-rule -p package -n my-plugin -r no-empty-alt -l js --no-test
+
+# Contribute to core
+$ npx @markuplint/create-rule -p core -r no-empty-alt -d "Disallow empty alt" -c a11y -s error
+
+# JSON output (useful for scripting and AI tooling)
+$ npx @markuplint/create-rule -p project -n my-plugin -r no-empty-alt --json
+```
+
+### Options
+
+| Option                 | Short | Description                              | Default                          |
+| ---------------------- | ----- | ---------------------------------------- | -------------------------------- |
+| `--purpose <type>`     | `-p`  | Purpose: `project`, `package`, or `core` | _(required)_                     |
+| `--plugin-name <name>` | `-n`  | Plugin/directory name in kebab-case      | _(required for project/package)_ |
+| `--rule-name <name>`   | `-r`  | Rule name in kebab-case                  | _(required)_                     |
+| `--lang <lang>`        | `-l`  | Language: `ts` or `js`                   | `ts`                             |
+| `--test`               | `-t`  | Generate test files                      | `true`                           |
+| `--no-test`            |       | Skip test file generation                |                                  |
+| `--description <text>` | `-d`  | Rule description                         | _(required for core)_            |
+| `--category <cat>`     | `-c`  | Category (see below)                     | _(required for core)_            |
+| `--severity <level>`   | `-s`  | Severity: `error` or `warning`           | _(required for core)_            |
+| `--json`               |       | Output result as JSON                    | `false`                          |
+| `--help`               | `-h`  | Show help message                        |                                  |
+
+Available categories: `validation`, `a11y`, `naming-convention`, `maintainability`, `style`
+
+> When contributing to core (`--purpose core`), `--lang` is always TypeScript and `--test` is always enabled regardless of the options provided.
+
+## Modes
+
+The CLI supports three scaffolding modes depending on your goal:
+
+| Mode                   | Description                                                   | When to use                                       |
+| ---------------------- | ------------------------------------------------------------- | ------------------------------------------------- |
+| **Add to project**     | Creates a local plugin directory in your project              | Adding a custom rule to an existing project       |
+| **Publish as package** | Scaffolds a standalone npm package with `package.json`        | Distributing a rule as an installable npm package |
+| **Contribute to core** | Adds a rule to `@markuplint/rules` (only inside the monorepo) | Contributing a new built-in rule to markuplint    |
+
+## Interactive Flow
+
+The CLI asks questions in the following order:
+
+1. **Purpose** — Select one of the three modes above
+2. **Directory / plugin name** — The directory name (for project mode) or plugin name (for package mode); skipped for core mode
+3. **Rule name** — The kebab-case name of the rule (e.g., `no-empty-alt`)
+4. **Core-only questions** (contribute to core only):
+   - Description
+   - Category (`validation`, `a11y`, `naming-convention`, `maintainability`, `style`)
+   - Severity (`error` or `warning`)
+5. **Language** — TypeScript or JavaScript (core mode always uses TypeScript)
+6. **Tests** — Whether to generate test files (core mode always includes tests)
+
+## Generated Files
+
+### Add to project
+
+```
+<pluginName>/
+├── index.ts (or .js)               — Plugin entry point
+└── rules/
+    ├── <ruleName>.ts (or .js)      — Rule implementation
+    └── <ruleName>.spec.ts (or .js) — Test file (if selected)
+```
+
+### Publish as package
+
+```
+<cwd>/
+├── package.json                     — Package manifest with scripts
+├── tsconfig.json                    — TypeScript config (if TypeScript)
+├── README.md                        — Package README
+└── src/
+    ├── index.ts (or .js)            — Plugin entry point
+    └── rules/
+        └── <ruleName>.ts (or .js)   — Rule implementation
+```
+
+### Contribute to core
+
+```
+packages/@markuplint/rules/src/<ruleName>/
+├── index.ts                         — Rule implementation
+├── index.spec.ts                    — Test file
+├── meta.ts                          — Rule metadata
+├── schema.json                      — Value/options JSON Schema
+├── README.md                        — English documentation
+└── README.ja.md                     — Japanese documentation
+```
+
+## Programmatic API
+
+The scaffolding logic can be used programmatically:
+
+```typescript
+import { createRuleHelper } from '@markuplint/create-rule';
+
+const result = await createRuleHelper({
+  purpose: 'ADD_TO_PROJECT',
+  pluginName: 'my-plugin',
+  ruleName: 'no-empty-alt',
+  lang: 'TYPESCRIPT',
+  needTest: true,
+});
+```
+
+See [`src/types.ts`](src/types.ts) for the full type definitions of `CreateRuleHelperParams` and `CreateRuleHelperResult`.

package/SKILL.md

@@ -0,0 +1,74 @@
+---
+description: Maintenance tasks for @markuplint/create-rule — CLI scaffolding tool for markuplint rules
+globs:
+  - packages/@markuplint/create-rule/src/**/*.ts
+  - packages/@markuplint/create-rule/scaffold/**/*
+  - packages/@markuplint/create-rule/bin/*.mjs
+alwaysApply: false
+---
+
+# @markuplint/create-rule Maintenance
+
+You are maintaining `@markuplint/create-rule`, the CLI scaffolding tool for creating new markuplint rules.
+
+## Architecture
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the full architecture documentation including the scaffold engine, template system, and strategy patterns.
+
+For detailed maintenance procedures, see [docs/maintenance.md](docs/maintenance.md) ([Japanese](docs/maintenance.ja.md)).
+
+## Key Files
+
+| File                            | Role                                                           |
+| ------------------------------- | -------------------------------------------------------------- |
+| `src/cli.ts`                    | Interactive CLI wizard (question sequence)                     |
+| `src/types.ts`                  | Type definitions (`CreateRulePurpose`, params, result, `File`) |
+| `src/create-rule-helper.ts`     | Purpose-based router dispatching to scaffold strategies        |
+| `src/create-rule-to-project.ts` | Strategy: add rule to current project                          |
+| `src/create-rule-package.ts`    | Strategy: create standalone npm package                        |
+| `src/create-rule-to-core.ts`    | Strategy: contribute to core rules                             |
+| `src/install-scaffold.ts`       | Low-level scaffold installer                                   |
+| `src/transfer.ts`               | Template processing (replacement, transpile, format)           |
+| `scaffold/core/`                | Templates for core rule contributions                          |
+| `scaffold/project/`             | Templates for project-local plugins                            |
+| `scaffold/package/`             | Templates for publishable packages                             |
+
+## Tasks
+
+### update-scaffold-template
+
+Update or modify scaffold template files.
+
+1. Edit the template files in `scaffold/{core,project,package}/`
+2. Maintain placeholder conventions:
+   - `__pluginName__` / `__pluginName__c` (camelCase variant)
+   - `__ruleName__` / `__ruleName__c` (camelCase variant)
+   - `__description__`, `__category__`, `__severity__` (core templates only)
+   - File names with `__ruleName__` are renamed to the actual rule name
+3. Note: `// prettier-ignore` comments are automatically stripped during transfer
+4. If using TypeScript, the template must also produce valid JavaScript when transpiled (for JavaScript mode)
+5. Test: `yarn test --scope @markuplint/create-rule`
+6. Build: `yarn build --scope @markuplint/create-rule`
+
+### add-cli-question
+
+Add or change a question in the interactive CLI wizard.
+
+1. Edit the question sequence in `src/cli.ts`
+2. Add any new types to `src/types.ts` (e.g., new fields on `CreateRuleCreatorParams`)
+3. Pass the new parameter through `createRuleHelper()` in `src/create-rule-helper.ts`
+4. Update the relevant strategy functions to use the new parameter
+5. Test: `yarn test --scope @markuplint/create-rule`
+6. Build: `yarn build --scope @markuplint/create-rule`
+
+### add-scaffold-strategy
+
+Add a new scaffold strategy (a fourth mode).
+
+1. Add a new value to `CreateRulePurpose` in `src/types.ts`
+2. Add the new choice to the selection list in `src/cli.ts`
+3. Create a new strategy file `src/create-rule-<purpose>.ts` following the pattern of existing strategies
+4. Add a new `case` branch in `src/create-rule-helper.ts`
+5. Create template files in `scaffold/<type>/` with appropriate placeholders
+6. Test: `yarn test --scope @markuplint/create-rule`
+7. Build: `yarn build --scope @markuplint/create-rule`