docs: 実装済みplanを確定仕様化

docs/specifications/issues-derived-specifications.md

@@ -10,12 +10,14 @@ Skill の挙動仕様は本ディレクトリでは管理しない。Skill に
 
 | 仕様書 | 内容 |
 |---|---|
+| [mcp-redash-multi-environment.md](mcp-redash-multi-environment.md) | Redash MCP の suffix 付きマルチ環境 plugin |
 | [ndf-knowledge-and-kiro.md](ndf-knowledge-and-kiro.md) | NDF 知識構造、Serena 分離、Kiro CLI 対応 |
+| [runtime-plugin-distribution.md](runtime-plugin-distribution.md) | Claude Code / Codex / Kiro 向け runtime 別 plugin 配布 |
 | [runtime-plugin-container-smoke.md](runtime-plugin-container-smoke.md) | runtime 分離 plugin の container smoke test |
 
 ## 対象外
 
-未実装、未完了、または現行リポジトリで確定仕様として扱えない依頼は仕様化しない。例: `issues/i11.md` の Redash MCP プラグイン案は作業中 issue として `issues/` に残すため、完了済み仕様への取り込み対象外とする。
+未実装、未完了、または現行リポジトリで確定仕様として扱えない依頼は仕様化しない。
 
 Skill に関する完了済み issue / plan / report は、該当 Skill の実装と `SKILL.md` に統合済みとして扱い、本ディレクトリには仕様書を置かない。
 

docs/specifications/mcp-redash-multi-environment.md

@@ -0,0 +1,144 @@
+# Redash MCP マルチ環境 Plugin 仕様
+
+## 概要
+
+`mcp-redash` は、Redash MCP server を Claude Code / Codex / Kiro CLI から利用するための runtime 別 MCP plugin である。
+
+単一環境では plugin 同梱の `redash` MCP server だけを使い、複数環境が必要な project では suffix 付きの `redash-*` MCP server を project `.mcp.json` に追加する。これにより、導入直後の MCP 一覧を最小に保ちながら、必要な Redash 環境だけを明示的に増やせる。
+
+## 対象範囲
+
+対象 runtime と配布先:
+
+| runtime | 配布先 |
+|---|---|
+| Claude Code | `plugins/mcp/claude/mcp-redash` |
+| Codex | `plugins/mcp/codex/mcp-redash` |
+| Kiro CLI | `plugins/mcp/kiro/mcp-redash` |
+
+共通編集元は `plugins/mcp/shared/mcp-redash` とする。runtime 別配布構造は [Runtime Plugin Distribution 仕様](runtime-plugin-distribution.md) に従う。
+
+## 仕様
+
+### Plugin 同梱 MCP
+
+plugin は suffix なしの `redash` MCP server を 1 つだけ同梱する。`redash-dev`、`redash-stg` などの追加環境は plugin 同梱 `.mcp.json` には含めない。
+
+Claude Code / shared / Kiro の `.mcp.json` は `mcpServers.redash` を定義する。Codex の `.mcp.json` は runtime 標準に合わせ、top-level の `redash` entry として定義する。
+
+`redash` は次の環境変数を参照する。
+
+| MCP 名 | URL | API key |
+|---|---|---|
+| `redash` | `REDASH_URL` | `REDASH_API_KEY` |
+
+### 追加 MCP
+
+追加環境は `/redash-add <suffix>` により project `.mcp.json` に追加する。suffix を `dev` とした場合、MCP 名は `redash-dev`、参照環境変数は `REDASH_DEV_URL` と `REDASH_DEV_API_KEY` になる。
+
+suffix と名前の変換:
+
+| suffix 例 | MCP 名 | URL | API key |
+|---|---|---|---|
+| `dev` | `redash-dev` | `REDASH_DEV_URL` | `REDASH_DEV_API_KEY` |
+| `stg` | `redash-stg` | `REDASH_STG_URL` | `REDASH_STG_API_KEY` |
+| `prod2` | `redash-prod2` | `REDASH_PROD2_URL` | `REDASH_PROD2_API_KEY` |
+| `sandbox-1` | `redash-sandbox-1` | `REDASH_SANDBOX_1_URL` | `REDASH_SANDBOX_1_API_KEY` |
+
+suffix は `^[a-z0-9][a-z0-9-]*$` に一致する英小文字、数字、ハイフンで指定する。入力 suffix は script 内で小文字化され、環境変数名ではハイフンをアンダースコアに変換する。`default` と空 suffix は、plugin 同梱の `redash` と衝突するため追加・削除できない。
+
+### Skill
+
+`mcp-redash` は次の user-invocable Skill を提供する。
+
+| Skill | 用途 |
+|---|---|
+| `redash-add` | 指定 suffix の `redash-*` MCP server を project `.mcp.json` に追加する |
+| `redash-remove` | 指定 suffix の `redash-*` MCP server を project `.mcp.json` から削除する |
+| `redash-list` | plugin 同梱 `redash` と project `.mcp.json` 上の `redash-*` を一覧表示する |
+| `redash-status` | 各 Redash MCP が必要とする環境変数名と未設定警告を表示する |
+| `redash-guide` | 利用手順と命名規則を表示する |
+
+各操作 Skill は `scripts/redash-mcp-config.js` を呼び出す。`redash-guide` は利用者向けの説明を持つ。
+
+### 設定操作 script
+
+`scripts/redash-mcp-config.js` は project root の `.mcp.json` を操作する Node.js script である。
+
+project root の解決は、`PROJECT_ROOT`、`WORKSPACE_ROOT`、`GIT_WORK_TREE`、`CLAUDE_PROJECT_DIR`、`CODEX_WORKSPACE_ROOT`、`KIRO_WORKSPACE_ROOT` の環境変数を優先し、未指定の場合は `cwd` から `.git` または最寄りの `.mcp.json` を探索する。
+
+`add` は `.mcp.json` が存在しない場合に新規作成する。Codex runtime では top-level map、その他 runtime では `{ "mcpServers": {} }` を初期形とする。既存 `.mcp.json` に `mcpServers` または `mcp_servers` がある場合はその server map を使い、`mcp_servers` は書き込み時に `mcpServers` へ正規化する。どちらもない object は top-level server map として扱う。
+
+`remove` は対象 entry が存在する場合だけ削除する。存在しない場合は変更なしの成功扱いにする。
+
+`list` は常に `redash (plugin bundled)` を表示し、project `.mcp.json` にある `redash-*` entry を名前順で表示する。
+
+`status` は `redash` と project `.mcp.json` にある `redash-*` entry について、必要な環境変数名と未設定警告を表示する。環境変数の値は表示しない。
+
+### Kiro 同期
+
+Kiro runtime では、`redash-mcp-config.js` が `.mcp.json` の Redash MCP server 定義を `.kiro/agents/default.json` の `mcpServers` に同期する。
+
+同期時は `.kiro/agents/default.json` 上の既存 Redash server entry を削除し、project `.mcp.json` 上の `redash` / `redash-*` entry を反映する。`.kiro/agents/default.json` が存在しない場合は、`name: default` と `resources: ["skill://.kiro/skills/**/SKILL.md"]` を持つ初期 agent 設定を作成する。
+
+## データ・設定
+
+`plugins/mcp/shared/mcp-redash` は次のファイルを持つ。
+
+| ファイル | 内容 |
+|---|---|
+| `.claude-plugin/plugin.json` | Claude Code plugin manifest |
+| `.mcp.json` | plugin 同梱 `redash` MCP server 定義 |
+| `.env.example` | `REDASH_URL` / `REDASH_API_KEY` と suffix 付き環境変数の例 |
+| `README.md` | runtime 別導入方法、使い方、トラブルシューティング |
+| `scripts/redash-mcp-config.js` | project `.mcp.json` の追加・削除・一覧・状態確認 |
+| `skills/*/SKILL.md` | `redash-add` / `redash-remove` / `redash-list` / `redash-status` / `redash-guide` |
+
+runtime 配布物は shared から生成され、Claude Code は `.claude-plugin/plugin.json`、Codex は `.codex-plugin/plugin.json`、Kiro CLI は `install.sh` を導入入口として持つ。
+
+## 外部連携
+
+MCP server の実行コマンドは `npx -y @suthio/redash-mcp` である。接続先 Redash URL と API key は環境変数から渡す。
+
+Redash への接続可否や API 権限は、利用者が設定した `REDASH_*_URL` と `REDASH_*_API_KEY` に依存する。
+
+## エラー処理
+
+- suffix が空または `default` の場合、`add` / `remove` は非 0 で終了する。
+- suffix が `^[a-z0-9][a-z0-9-]*$` に一致しない場合、`add` / `remove` は非 0 で終了する。
+- `.mcp.json` の JSON が壊れている場合、`add` / `remove` は中断し、既存ファイルを上書きしない。
+- `.mcp.json` の server map を解釈できない場合、`add` は非 0 で終了する。
+- 追加対象が既に存在する場合、`add` は変更なしの成功扱いにする。
+- 削除対象が存在しない場合、`remove` は変更なしの成功扱いにする。
+- Kiro 同期時に `.kiro/agents/default.json` の JSON が壊れている場合、処理を中断する。
+
+## セキュリティ
+
+- API key や secret の実値は repository に含めない。
+- `.mcp.json` は `${REDASH_API_KEY}` や `${REDASH_DEV_API_KEY}` などの placeholder だけを保持する。
+- `.env.example` はサンプル値だけを保持する。
+- `redash-status` は必要な環境変数名と未設定警告だけを表示し、環境変数の値は表示しない。
+
+## 運用
+
+単一 Redash 環境だけを使う project では、plugin を導入し、project 環境に `REDASH_URL` と `REDASH_API_KEY` を設定する。
+
+複数 Redash 環境を使う project では、`/redash-add dev` のように suffix を指定して追加し、表示された環境変数名を project `.env` など利用者環境に設定する。設定状況は `/redash-list` と `/redash-status` で確認する。不要になった追加環境は `/redash-remove dev` で project `.mcp.json` から削除する。
+
+## テスト観点
+
+- plugin 導入直後の同梱 MCP が `redash` だけであること。
+- `/redash-add dev` が project `.mcp.json` に `redash-dev` を追加し、`REDASH_DEV_URL` と `REDASH_DEV_API_KEY` を参照すること。
+- 任意 suffix の追加で MCP 名と環境変数名が衝突しないこと。
+- 既存 suffix の再追加が変更なしの成功扱いになること。
+- `/redash-remove dev` が `redash-dev` を削除すること。
+- 存在しない suffix の削除が変更なしの成功扱いになること。
+- `.mcp.json` が壊れている場合に上書きしないこと。
+- `redash-status` が secret 値を出さず、未設定の環境変数名だけを警告すること。
+- `bash scripts/validate-runtime-plugins.sh` が runtime 配布物の同期、manifest、`.mcp.json`、installer、docs link を検証すること。
+
+## 関連リンク
+
+- [Runtime Plugin Distribution 仕様](runtime-plugin-distribution.md)
+- [mcp-redash shared README](../../plugins/mcp/shared/mcp-redash/README.md)
+- [mcp-redash shared config script](../../plugins/mcp/shared/mcp-redash/scripts/redash-mcp-config.js)

docs/specifications/runtime-plugin-container-smoke.md

@@ -203,4 +203,4 @@ authenticated workflow は `ANTHROPIC_API_KEY`、`OPENAI_API_KEY`、BigQuery 関
 - [runtime plugin validation](../../scripts/validate-runtime-plugins.sh)
 - [Runtime plugin smoke workflow](../../.github/workflows/runtime-plugin-smoke.yml)
 - [Runtime plugin authenticated smoke workflow](../../.github/workflows/runtime-plugin-authenticated-smoke.yml)
-- [runtime 分離仕様](ndf-knowledge-and-kiro.md)
+- [Runtime Plugin Distribution 仕様](runtime-plugin-distribution.md)

docs/specifications/runtime-plugin-distribution.md

@@ -0,0 +1,155 @@
+# Runtime Plugin Distribution 仕様
+
+## 概要
+
+AI Plugins marketplace は、Claude Code / Codex / Kiro CLI 向けに runtime 別の plugin 配布物を提供する。
+
+NDF plugin は runtime ごとの manifest、hook、agent、installer 差分を持つため、共通編集元と配布先を分離する。MCP plugin も runtime ごとに Claude Code / Codex / Kiro CLI 用の配布ディレクトリを持ち、同じ plugin 名で導入できる構成にする。
+
+## 対象範囲
+
+対象 runtime:
+
+| runtime | marketplace / 導入方式 | NDF 配布物 | MCP 配布物 |
+|---|---|---|---|
+| Claude Code | `.claude-plugin/marketplace.json` | `plugins/ndf-claude` | `plugins/mcp/claude/*` |
+| Codex | `.agents/plugins/marketplace.json` | `plugins/ndf-codex` | `plugins/mcp/codex/*` |
+| Kiro CLI | installer | `plugins/ndf-kiro` | `plugins/mcp/kiro/*` |
+
+共通編集元:
+
+| 種別 | パス | 用途 |
+|---|---|---|
+| NDF shared | `plugins/ndf-shared` | runtime 配布物へ同期する Skill / scripts / manifest の編集元 |
+| MCP shared | `plugins/mcp/shared/*` | runtime 別 MCP plugin 生成元 |
+
+## NDF Plugin 配布仕様
+
+NDF plugin の plugin name は全 runtime で `ndf` を維持する。旧 `plugins/ndf` 配布物は廃止し、runtime 別ディレクトリを配布単位とする。
+
+| runtime | manifest / installer | 主な内容 |
+|---|---|---|
+| Claude Code | `plugins/ndf-claude/.claude-plugin/plugin.json` | Claude Code agents、hooks、skills、scripts |
+| Codex | `plugins/ndf-codex/.codex-plugin/plugin.json` | Codex 用 skills、hooks、scripts |
+| Kiro CLI | `plugins/ndf-kiro/install.sh` | `.kiro/agents/default.json`、`.kiro/skills/` symlink、prompts、任意 hook |
+
+`plugins/ndf-shared/manifests/{claude,codex,kiro}-skills.txt` は runtime ごとの配布 Skill 一覧を定義する。`scripts/build-runtime-plugins.sh` はこの manifest を読み、`plugins/ndf-shared/skills` から各 runtime の `skills/` へ同期する。
+
+Codex / Kiro では一部 Skill 内の `${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}` 参照を runtime 用に書き換える。
+
+| runtime | 書き換え |
+|---|---|
+| Codex | `${CODEX_PLUGIN_ROOT}` を含む fallback と `skills/` 配下 script path に変換 |
+| Kiro CLI | `plugins/ndf-kiro` を既定 root とする参照に変換 |
+
+scripts は `plugins/ndf-shared/scripts` から `plugins/ndf-{runtime}/scripts` へ同期する。
+
+## MCP Plugin 配布仕様
+
+MCP plugin は `plugins/mcp/shared/<plugin-name>` を編集元とし、runtime 別に以下へ配布する。
+
+| runtime | 配布先 | 導入方式 |
+|---|---|---|
+| Claude Code | `plugins/mcp/claude/<plugin-name>` | Claude marketplace |
+| Codex | `plugins/mcp/codex/<plugin-name>` | Codex marketplace |
+| Kiro CLI | `plugins/mcp/kiro/<plugin-name>` | `install.sh` |
+
+各 runtime で plugin name は同一にする。例: `mcp-bigquery`、`mcp-redash`、`mcp-serena`。
+
+Claude 用配布物は `.claude-plugin/plugin.json` と `.mcp.json` を持つ。Codex 用配布物は `.codex-plugin/plugin.json` と `.mcp.json` を持つ。Kiro 用配布物は `.mcp.json` と `install.sh` を持つ。
+
+Kiro MCP installer は対象 project の `.mcp.json` へ MCP server 設定を merge する。hooks や skills を持つ MCP plugin では、必要に応じて `.kiro/agents/default.json` や `.kiro/skills/` も更新する。
+
+## Marketplace
+
+Claude Code marketplace は `.claude-plugin/marketplace.json` で管理する。各 entry の `source` は Claude 用配布ディレクトリを指す。
+
+Codex marketplace は `.agents/plugins/marketplace.json` で管理する。各 entry の `source.path` は Codex 用配布ディレクトリを指す。
+
+Kiro CLI は repository root の marketplace manifest ではなく、`plugins/ndf-kiro/install.sh` と `plugins/mcp/kiro/*/install.sh` を導入入口とする。
+
+## Build / Validation
+
+runtime 配布物の同期は `scripts/build-runtime-plugins.sh` で行う。
+
+```bash
+bash scripts/build-runtime-plugins.sh
+bash scripts/build-runtime-plugins.sh --check
+```
+
+`--check` は生成先と shared source の差分を比較し、drift がある場合に非 0 で終了する。
+
+総合検証は `scripts/validate-runtime-plugins.sh` で行う。
+
+```bash
+bash scripts/validate-runtime-plugins.sh
+```
+
+検証内容:
+
+| 領域 | 確認内容 |
+|---|---|
+| 生成物 | `build-runtime-plugins.sh --check` |
+| JSON | marketplace、plugin manifest、`.mcp.json` の parse |
+| marketplace | Claude / Codex source path と runtime manifest の存在 |
+| Skill manifest | shared skill と runtime skill の存在 |
+| MCP runtime | shared MCP plugin に対応する claude / codex / kiro 配布先の存在 |
+| Claude Code | `claude plugin validate` が使える環境では NDF と marketplace を検証 |
+| Kiro CLI | NDF installer と MCP installer の `--dry-run` |
+| docs | `scripts/check-markdown-links.py` による local link 検証 |
+
+## CI
+
+`.github/workflows/runtime-plugin-validate.yml` は runtime 配布物の build check、manifest validation、Markdown link check を実行する。
+
+`.github/workflows/runtime-plugin-smoke.yml` は runtime ごとの非認証 container smoke test を実行する。
+
+`.github/workflows/runtime-plugin-authenticated-smoke.yml` は protected environment から secret を受け取り、手動で認証付き smoke test を実行する。
+
+container smoke test の詳細は [Runtime Plugin Container Smoke Test 仕様](runtime-plugin-container-smoke.md) を参照する。
+
+## セキュリティ
+
+- 認証情報、API token、secret、private key は repository に含めない。
+- `.mcp.json` と README では `${ENV_NAME}` placeholder を使い、secret 実値を書かない。
+- runtime smoke test は host の credential directory を mount しない。
+- Kiro installer と MCP installer は project 配下の設定ファイルだけを更新する。
+- Codex / Claude / Kiro の hook script は runtime 別配布物に分離し、payload 差異を混同しない。
+
+## 運用
+
+NDF Skill を変更する場合:
+
+1. `plugins/ndf-shared/skills/<skill>/` を編集する。
+2. 必要なら `plugins/ndf-shared/manifests/*-skills.txt` を更新する。
+3. `bash scripts/build-runtime-plugins.sh` を実行する。
+4. `bash scripts/validate-runtime-plugins.sh` を実行する。
+
+MCP plugin を変更する場合:
+
+1. `plugins/mcp/shared/<plugin-name>/` を編集する。
+2. `bash scripts/build-runtime-plugins.sh` を実行して runtime 配布先へ反映する。
+3. `bash scripts/validate-runtime-plugins.sh` を実行する。
+
+runtime 配布先を直接編集した場合、`build-runtime-plugins.sh --check` で shared source との drift として検出される。例外的な runtime 固有ファイルは build script の生成ルールに含める。
+
+## テスト観点
+
+| 観点 | 確認方法 |
+|---|---|
+| shared source と runtime 配布物の同期 | `bash scripts/build-runtime-plugins.sh --check` |
+| marketplace / manifest / MCP config | `bash scripts/validate-runtime-plugins.sh` |
+| Claude Code install smoke | `bash scripts/runtime-smoke-test.sh --runtime claude` |
+| Codex install smoke | `bash scripts/runtime-smoke-test.sh --runtime codex` |
+| Kiro CLI install smoke | `bash scripts/runtime-smoke-test.sh --runtime kiro` |
+| 旧パス残存 | docs / scripts / plugin 配布物に旧 `plugins/ndf` や `plugins/mcp-*` 配置を案内する参照が残っていないこと |
+
+## 関連リンク
+
+- [Runtime Plugin Container Smoke Test 仕様](runtime-plugin-container-smoke.md)
+- [NDF 知識構造・Kiro CLI 仕様](ndf-knowledge-and-kiro.md)
+- [NDF Plugin リファレンス](../ndf-plugin-reference.md)
+- [NDF Claude README](../../plugins/ndf-claude/README.md)
+- [NDF Codex README](../../plugins/ndf-codex/README.md)
+- [NDF Kiro README](../../plugins/ndf-kiro/README.md)
+- [NDF shared README](../../plugins/ndf-shared/README.md)