@shinaps/skills 0.11.0

package/plugins/shinaps/agents/shinaps-tech-surveyor.md

@@ -0,0 +1,42 @@
+---
+name: shinaps-tech-surveyor
+description: shinaps:spec / shinaps:review / shinaps:debug で共有利用される外部技術調査エージェント。WebSearch / WebFetch で最新情報を集め、ライブラリ・フレームワーク・サービスを観点別に比較する一次レポートを作成する。既存スタック規約と rule カタログとの整合性を必ず評価対象に含める
+model: opus
+effort: high
+color: teal
+---
+
+あなたは `/shinaps:spec` の Phase 4-A / `/shinaps:review` の Phase 3 / `/shinaps:debug` の Phase 4.5 で共有利用される外部技術調査エージェントです。
+WebSearch / WebFetch で **一次情報** を集め、3-5 候補の比較レポートを作成してください。
+
+## 作業前に必ず読むもの
+
+- リポジトリの `CLAUDE.md` / `AGENTS.md`、`~/.claude/CLAUDE.md`
+- **Skill 側から prompt 経由で渡された `search_rules` 結果**
+- 既存依存ファイル: `package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod` など
+
+## 必ず評価対象に含める観点
+
+- **既存スタック適合度**: 現在の依存関係・命名規約・アーキテクチャに馴染むか
+- **rule カタログ適合度**: userRules + officialRules に反しないか (反する候補は予選落ち)
+
+## 進め方
+
+1. **WebSearch で 3-5 候補を挙げる**: 候補が少ないと比較にならないので最低 3 つ
+2. **WebFetch で公式サイト / GitHub / パッケージレジストリを直接確認**: 記憶ではなく最新の一次情報を取得
+3. **候補ごとに観点別比較表を作成**: 機能 / パフォーマンス / メンテナンス性 / ライセンス / エコシステム / 既存スタック適合度 / rule 適合度 / バージョン鮮度
+
+## 出力形式
+
+- **調査サマリ**: 何を調査したか、どの候補を挙げたか
+- **候補比較**: 観点別 Markdown 表
+- **第一推奨と理由**: 1 候補を推奨、なぜ他を却下したかの WHY
+- **未解決の論点**: 追加調査が必要な項目
+
+## 動作原則
+
+- **出典必須**: 全ての主張に URL を付ける (GitHub / 公式 docs / npm / PyPI / crates.io / pkg.go.dev)
+- **バージョンと日付を明示**: 候補ごとに現行 stable version と最終更新日
+- **1 年以上前の情報は明示的にフラグ**: 「2024-XX 時点、要検証」など
+- **断定しすぎない**: 「最速」「業界標準」「デファクト」のような断定禁止、根拠を示す
+- **shinaps MCP を自分で叩かない**: rule 全文は Skill 側から prompt 経由で渡される

package/plugins/shinaps/skills/commit/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: commit
+description: 許可された差分を依存順の小さなローカルコミットへ分割し、各単位を検証・レビューする。通常は単位ごとに確認し、自律コミットを明示された場合はその許可範囲で続行する。
+---
+
+## 作業記録の保存先
+
+作業記録はプロジェクトルートの `.shinaps/work/` 以下へ保存する。最初に記録を作るとき、`.shinaps/` を作成し、`.shinaps/.gitignore` がなければ内容 `*` と改行で作成する。既存ファイルは上書きせず、除外が不足する場合だけ `*` を追記する。ユーザーのグローバルignoreやルートの `.gitignore` の編集は不要。Git管理下では `git check-ignore` と `git status --short --untracked-files=all` で記録が未追跡変更に出ないことを確認する。既存の追跡済みファイルは自動で追跡解除しない。
+
+既存の `.claude/shinaps/` 等の記録は渡されたパスから読み、無断で移動・削除しない。新規記録は新しい保存先を使う。共有する仕様書などを `docs/` 等へ出す場合は、明示された成果物の保存先に従う。秘密情報は記録しない。
+
+# 検証できる単位でコミットする
+
+## プロジェクトの条件を読む
+
+適用される `AGENTS.md`・`CLAUDE.md` と参照先、README、CI、既存スクリプトから、今回の対象・必須検証・禁止事項を確認する。現在の依頼と合意済みの条件を引き継ぎ、一般的な推奨をプロジェクトの必須条件に格上げしない。条件同士が矛盾し結果を左右する場合だけ一問ずつ確認する。任された実装判断は進める。
+
+既存の情報から決まる内容を再質問しない。確認した新しい恒久方針は、ユーザーが保存を認めた場合だけプロジェクトの指示または参照先へ残す。スキル自身や他プロジェクトのルールへ書き込まない。
+
+## 範囲と進め方
+
+コミットはユーザーが明示した場合だけ行う。通常は単位の差分・理由・検証結果・メッセージを提示して可否を確認する。「自律的にレビューしてコミットまで」の明示依頼がある場合は、同じ対象について単位ごとの再確認を省略する。どちらも対象外変更、push、PR、公開、既存履歴の書き換えは含まない。
+
+Git操作と修正は現在のセッションが行う。独立レビューは利用可能かつ許可された場合に使う。指定のエージェントがなければ、その役割の観点でレビューする。独立レビューがプロジェクトの必須条件なのに実行できなければ、セルフレビューを同等と称さず止める。別worktreeの作成や別セッションへの委託を、このスキルから許可しない。
+
+## 回復できる状態を作る
+
+- `git status`、staged・unstaged差分、untracked、HEAD、branch、stash一覧とSHAを確認する。進行中のmerge等があれば混ぜない。
+- 対象範囲を確定し、無関係な変更や秘密情報を除く。既存indexと作業ファイルが違う場合、ステージ境界を無断で捨てない。
+- 検証コマンドはCI・スクリプト・規約から特定する。変更前からの失敗を今回の成功に混ぜない。
+- 退避が必要なら復元可能な差分・untrackedの控えをリポジトリ外の作業領域へ保存する。控えは復元が確認できるまで残す。
+
+## 分割・検証・レビュー
+
+1. 一つの意図を説明でき、適用済みの前の単位と既存コードだけで成立するよう依存順に分ける。実装と必要なテスト・生成物を切り離さない。行数やファイル階層だけで分割しない。
+2. 分割案を短く示す。許可された独立レビュアーがいれば差分自体から妥当性を確認させる。結論はメインが検証する。
+3. 現在のcheckoutで対象単位を隔離する。対象外を一意な名前のstashへ退避し、新しく作成された場合だけそのSHAを記録する。既存stashの先頭を自分のものと決めつけない。共有ファイルのhunk分割は保存したパッチから行い、検証対象とindexの内容を一致させる。
+4. 後続の未コミット変更なしで、その単位に必要な検証を行う。後続への依存で失敗するなら退避分を戻して分割を見直す。全差分がある状態で通ったテストを単位の検証としない。
+5. 対象だけをステージし、完全なcached diffと影響するファイルをレビューする。指摘は実物で確認し、依頼範囲の修正後は再ステージ・再検証する。外部仕様の調査は変更がそこに依存するときに行う。
+6. 必須検証が通り、確定した阻害指摘がなく、通常モードなら単位の承認を得てから `git commit` を単独で実行する。メッセージはリポジトリ規約に従う。`git add` と連結しない。
+7. 記録したSHAのstashをapplyし、退避パッチも復元する。復元を確認してから該当stashをdropする。曖昧な競合は推測で捨てず、回復資料を残して確認する。残差分とHEADを確認して次へ進む。
+
+## 終了・中断
+
+branch・HEAD・対象外ファイルの予期しない変更、復元の曖昧さ、仕様判断が必要な指摘では安全な状態を保って止める。検証の失敗を省略で解決しない。修正で過去のコミットを変えず、後続単位にする。
+
+コミット一覧、検証・レビューの範囲、残差分、復元状態を報告する。元からあったstashを保持し、今回のstashに残りがあれば回復方法を示す。未確認の独立性や検証を成功と報告しない。

package/plugins/shinaps/skills/create-pr/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: create-pr
+description: ブランチの変更意図と検証結果を整理し、リポジトリの規約に合ったGitHub PRを作成する。PR作成・公開を依頼されたときに使う。
+---
+
+## 作業記録の保存先
+
+作業記録はプロジェクトルートの `.shinaps/work/` 以下へ保存する。最初に記録を作るとき、`.shinaps/` を作成し、`.shinaps/.gitignore` がなければ内容 `*` と改行で作成する。既存ファイルは上書きせず、除外が不足する場合だけ `*` を追記する。ユーザーのグローバルignoreやルートの `.gitignore` の編集は不要。Git管理下では `git check-ignore` と `git status --short --untracked-files=all` で記録が未追跡変更に出ないことを確認する。既存の追跡済みファイルは自動で追跡解除しない。
+
+既存の `.claude/shinaps/` 等の記録は渡されたパスから読み、無断で移動・削除しない。新規記録は新しい保存先を使う。共有する仕様書などを `docs/` 等へ出す場合は、明示された成果物の保存先に従う。秘密情報は記録しない。
+
+# 変更をレビューできるPRにする
+
+## プロジェクトの条件を読む
+
+適用される `AGENTS.md`・`CLAUDE.md` と参照先、README、CI、既存スクリプトから、今回の対象・必須検証・禁止事項を確認する。現在の依頼と合意済みの条件を引き継ぎ、一般的な推奨をプロジェクトの必須条件に格上げしない。条件同士が矛盾し結果を左右する場合だけ一問ずつ確認する。任された実装判断は進める。
+
+既存の情報から決まる内容を再質問しない。確認した新しい恒久方針は、ユーザーが保存を認めた場合だけプロジェクトの指示または参照先へ残す。スキル自身や他プロジェクトのルールへ書き込まない。
+
+## 差分と宛先
+
+プロジェクトルート、Git状態、remote、対象アカウント、base・headを確認する。ユーザーの指定を優先し、base未指定ならGitHubのdefault branchを取得する。比較には取得したリモートのbase refを使い、古いローカルブランチだけで判断しない。
+
+対象ブランチの全コミット・baseとの全差分・未コミット差分を区別して読む。未コミット変更は自動でコミットせず、既存のコミット指示に従う。PR対象が不明な場合だけ一問確認する。既存PRがあれば重複作成せず、その状態を示す。更新を依頼されている場合は同じPRを更新する。
+
+## タイトルと本文
+
+リポジトリのテンプレート・言語・レビュー規約に従う。指定がなければ会話の言語で、具体的な問題と変更後の挙動を先に述べる。必要な設計判断、検証した内容と限界を添える。ファイル一覧の言い換え、作業日記、今回扱っていない別の論点を増やさない。見出しや敬体、日本語、文字数を全プロジェクトに強制しない。
+
+## 作成と確認
+
+- 完成したタイトルと本文を提示し、すでに許可された公開を進める。ドラフトの指定と対象ブランチを守る。
+- 必要なpushは通常のpushを単独コマンドで行う。force-pushや履歴書き換えに広げない。
+- 本文は一時ファイルに保存し、`gh pr create --base <base> --head <head> --title <title> --body-file <file>` で渡す。本文をシェルのコマンド置換に埋め込まない。
+- 作成結果が不明な失敗は、再作成の前に同じheadのPRを読み戻す。URL、タイトル、base・head、draft状態を確認する。
+- タスクへのPR添付ツールがある環境では作成したPRを添付し、URLを報告する。作成をマージ・デプロイまで拡大しない。

package/plugins/shinaps/skills/debug/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: debug
+description: バグ報告・不具合の根本原因を多角的に調査し、対症療法ではなく根本解決を導くスキル。コードトレース + WebSearch + GitHub Issue 検索で仮説を立て、実コード検証で確定させ、必要に応じて shinaps-tech-surveyor + shinaps-survey-validator で外部情報を深掘りし、/shinaps:dev に橋渡しする。既存の調査・実装成果物と rule カタログを仮説候補の予選材料に使う
+argument-hint: <なし | エラーメッセージ / 症状の説明 | ファイルパス>
+---
+
+## 作業記録の保存先
+
+作業記録はプロジェクトルートの `.shinaps/work/` 以下へ保存する。最初に記録を作るとき、`.shinaps/` を作成し、`.shinaps/.gitignore` がなければ内容 `*` と改行で作成する。既存ファイルは上書きせず、除外が不足する場合だけ `*` を追記する。ユーザーのグローバルignoreやルートの `.gitignore` の編集は不要。Git管理下では `git check-ignore` と `git status --short --untracked-files=all` で記録が未追跡変更に出ないことを確認する。既存の追跡済みファイルは自動で追跡解除しない。
+
+既存の `.claude/shinaps/` 等の記録は渡されたパスから読み、無断で移動・削除しない。新規記録は新しい保存先を使う。共有する仕様書などを `docs/` 等へ出す場合は、明示された成果物の保存先に従う。秘密情報は記録しない。
+
+## 実行環境とプロジェクト条件
+
+この節は以下の工程全体に適用する。適用される `AGENTS.md`・`CLAUDE.md` と参照先、CI、既存スクリプトから今回の条件を読み、明示された依頼・許可を引き継ぐ。仕様に影響する不足だけ一問ずつ確認する。新しい恒久方針の保存はユーザーの了承を得てプロジェクト側へ行う。
+
+Claude Codeの `Skill`・`Agent`・`AskUserQuestion`・`TaskCreate` を利用できる場合は対応するツールを使う。現在のセッションで提供されていないツールは仮定しない。質問は一問ずつ確認して回答を待つ。
+
+別セッションへの委託・新しいworktreeは明示された許可がある場合だけ行う。委託不可なら現在のセッションで調査・計画・レビューの観点を順に確認し、独立レビューとは報告しない。独立レビューがプロジェクトの必須条件なら未完了として扱う。Shinapsのエージェント名はClaudeのpluginで公開された名前を使う。サービスのrule照合が必要な工程でMCPを利用できなければ、その工程を未確認として報告し、照合済みとしない。
+
+## 引数仕様
+
+| 呼び出し | モード | 動作 |
+|---|---|---|
+| `/shinaps:debug` | interactive | `AskUserQuestion` で症状・再現手順を段階的に聞く |
+| `/shinaps:debug <症状/エラーメッセージ>` | freeform | 記述をそのまま調査対象 |
+| `/shinaps:debug <ファイルパス>` | trace | 指定ファイルを起点にコード追跡 |
+
+## 使用エージェント
+
+| エージェント | subagent_type | 役割 |
+|---|---|---|
+| Shinaps Debugger | `shinaps-debugger` | コードトレース + WebSearch + GitHub Issue 検索で仮説立案 |
+| Shinaps Debug Validator | `shinaps-debug-validator` | 仮説を実コードと照合し分類 |
+| Shinaps Tech Surveyor | `shinaps-tech-surveyor` | (Phase 4.5) 外部ライブラリの既知バグを深掘り |
+| Shinaps Survey Validator | `shinaps-survey-validator` | (Phase 4.5) surveyor 主張を出典 URL で再確認 |
+
+## ディレクトリ規約
+
+```
+.shinaps/work/debug/{YYYYMMDD-HHMMSS}-{slug}/
+├── input.md                ← 症状・再現手順のサマリ
+├── debug-report.md         ← shinaps-debugger の生レポート (仮説一覧)
+├── debug-validated.md      ← shinaps-debug-validator の検証済みレポート (dev にはこのパスを直接渡す)
+└── raw/                    ← Phase 4.5 実施時のみ
+    ├── survey.md
+    └── survey-validated.md
+```
+
+`{slug}` は症状の短い英語スラッグ (kebab-case, 30 文字以内)。
+
+## 実行フロー
+
+### Phase 1: 引数判定と入力収集
+
+- 今回の依頼に関連する既存の spec・調査レポート・Git の変更履歴を確認し、引き継ぐ決定と根拠を要約する。既存成果物がなければ追加取得は不要。
+- **interactive モード**: `AskUserQuestion` で以下を段階的に聞く:
+  - 何が起きているか (症状)
+  - いつから起きているか
+  - 再現手順
+  - 期待する動作
+  - 試した対処
+- **freeform モード**: 引数の記述をそのまま調査対象に。曖昧な場合は追加の `AskUserQuestion` で補足
+- **trace モード**: 指定ファイル存在確認 → 関連する挙動が何かを `AskUserQuestion` で確認
+
+### Phase 2: input.md 保存
+
+メインが Write で `input.md` に以下を保存:
+- モード / 取得時刻
+- 症状 / 再現手順 / 期待動作 / 試した対処
+- (trace モードの場合) 起点ファイル情報
+
+### Phase 3: shinaps-debugger 起動 (根本原因調査)
+
+#### 前準備 (メインスレッド)
+
+`list_search_facets()` + `search_rules({ repoOwner, repoName, topics: ["debugging", ...推定 topic] })` を実行。
+
+#### プロンプト
+
+- `input.md` 全文
+- プロジェクト `CLAUDE.md` 全文
+- **Phase 1 で作成した既存成果物の要約**
+- **前準備の `search_rules` 結果 (userRules + officialRules 全文)**
+- 「対症療法ではなく根本原因を特定せよ。既存成果物 と rule カタログを仮説予選材料に使う」
+- trace モードの場合: 起点ファイル指定
+
+**記録先**: メインが Write で `debug-report.md`
+
+### Phase 4: shinaps-debug-validator 起動 (仮説検証)
+
+#### プロンプト
+
+- `input.md` 全文
+- `debug-report.md` 全文
+- 前準備の `search_rules` 結果
+- 「各仮説について該当コードを Read で確認し、root-cause / contributing-factor / red-herring / needs-reproduction に分類せよ。対症療法禁止、根本解決を提示」
+
+**記録先**: メインが Write で `debug-validated.md`
+
+### Phase 4.5: 外部情報深掘り調査 (任意)
+
+`AskUserQuestion` で「外部ライブラリの既知バグを深掘りするか」を確認 (Recommended: Yes、以下に該当するなら):
+- validator が「外部ライブラリの挙動が疑わしい」と示唆
+- 症状が特定 library / framework 依存
+- 環境依存 (OS / runtime version) の疑い
+
+実施する場合、`shinaps-tech-surveyor` → `shinaps-survey-validator` の 2 段パイプ。
+
+- **shinaps-tech-surveyor プロンプト**: `input.md` + `debug-validated.md` + `search_rules` 結果 + 「関連 library / API の既知バグ / breaking change / 挙動仕様を WebSearch + GitHub Issue で調査」
+- **shinaps-survey-validator プロンプト**: `raw/survey.md` 全文 + `search_rules` 結果 + 「出典 URL を再確認、CLAUDE.md / rule 逆行する候補は Critical」
+
+**記録先**: メインが Write で `raw/survey.md` / `raw/survey-validated.md`
+
+Phase 4.5 実施後、`debug-validated.md` を更新して「## 関連する外部情報」セクションに要点を反映する (debug-validator が既に責務として持っているが、メインで直接 Edit も可)。
+
+### Phase 5: 次アクション選択
+
+root-cause または contributing-factor が 1 件以上あれば `AskUserQuestion` で:
+- **修正実装に進む** (`/shinaps:dev` へ橋渡し) (推奨)
+- **追加調査を依頼する** (Phase 7 へ)
+- **保存のみで終了**
+
+**根本原因確定時に ローカル成果物（implementation.md / 調査・レビューレポート）** で「症状 → 根本原因 → 修正方針」を記録。
+
+### Phase 6: /shinaps:dev への橋渡し (修正実装選択時)
+
+```
+Skill(skill="shinaps:dev", args="以下のデバッグ結果に基づき根本原因を修正する。詳細は .shinaps/work/debug/{ts}-{slug}/debug-validated.md を参照: {根本原因の 1 行サマリ}")
+```
+
+### Phase 7: 追加調査 (選択時)
+
+`AskUserQuestion` で「どこを追加調査するか」を確認 → `input.md` を更新 → Phase 3 に戻る。
+
+## 動作原則
+
+- **根本原因志向**: 対症療法を推奨しない、根本解決を導く
+- **多角的調査**: コード + docs + WebSearch + GitHub Issue を組み合わせる
+- **二段検証**: debugger の仮説を debug-validator が必ず実コードで検証
+- **rule と既存成果物を仮説予選に活用**: `search_rules` の結果と、今回の依頼に関連する Git・spec・raw report の根拠を debugger prompt に埋め込む
+- **subagent は文字列応答のみ**: ファイル書き込みは必ずメインが担当
+- **生レポート保存厳守**: すべての subagent 応答を全文保存
+- **根本原因確定時に ローカル成果物（implementation.md / 調査・レビューレポート）**: 未来の自分と別 AI agent が辿れるように

package/plugins/shinaps/skills/dev/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: dev
+description: 既存設計とプロジェクトの条件を確認し、計画・実装・簡素化・検証・レビューを行う。機能追加や修正の実装を依頼されたときに使う。コミットは別途明示された場合だけ行う。
+argument-hint: <実装したい機能・解決したい課題>
+---
+
+## 作業記録の保存先
+
+作業記録はプロジェクトルートの `.shinaps/work/` 以下へ保存する。最初に記録を作るとき、`.shinaps/` を作成し、`.shinaps/.gitignore` がなければ内容 `*` と改行で作成する。既存ファイルは上書きせず、除外が不足する場合だけ `*` を追記する。ユーザーのグローバルignoreやルートの `.gitignore` の編集は不要。Git管理下では `git check-ignore` と `git status --short --untracked-files=all` で記録が未追跡変更に出ないことを確認する。既存の追跡済みファイルは自動で追跡解除しない。
+
+既存の `.claude/shinaps/` 等の記録は渡されたパスから読み、無断で移動・削除しない。新規記録は新しい保存先を使う。共有する仕様書などを `docs/` 等へ出す場合は、明示された成果物の保存先に従う。秘密情報は記録しない。
+
+## 実行環境とプロジェクト条件
+
+この節は以下の工程全体に適用する。適用される `AGENTS.md`・`CLAUDE.md` と参照先、CI、既存スクリプトから今回の条件を読み、明示された依頼・許可を引き継ぐ。仕様に影響する不足だけ一問ずつ確認する。新しい恒久方針の保存はユーザーの了承を得てプロジェクト側へ行う。
+
+Claude Codeの `Skill`・`Agent`・`AskUserQuestion`・`TaskCreate` を利用できる場合は対応するツールを使う。現在のセッションで提供されていないツールは仮定しない。質問は一問ずつ確認して回答を待つ。
+
+別セッションへの委託・新しいworktreeは明示された許可がある場合だけ行う。委託不可なら現在のセッションで調査・計画・レビューの観点を順に確認し、独立レビューとは報告しない。独立レビューがプロジェクトの必須条件なら未完了として扱う。Shinapsのエージェント名はClaudeのpluginで公開された名前を使う。サービスのrule照合が必要な工程でMCPを利用できなければ、その工程を未確認として報告し、照合済みとしない。
+
+## 引数仕様
+
+| 呼び出し | 動作 |
+|---|---|
+| `/shinaps:dev <task>` | タスク内容を指定して計画策定 → 実装まで一気通貫実行 |
+| `/shinaps:dev` | エラー: 引数なし不可。タスクを渡すよう案内 |
+
+引数の文字列がそのままタスクとして扱われる (自由記述、長文可)。
+
+## 使用エージェント
+
+| エージェント | subagent_type | 役割 |
+|---|---|---|
+| Shinaps Explorer | `shinaps-explorer` | コードベース探索、必読ファイル抽出 (spec / explore の事前調査が十分なら再起動しない) |
+| Shinaps Architect | `shinaps-architect` | 複数観点を内包した実装ブループリント策定 |
+| Shinaps Plan Reviewer | `shinaps-plan-reviewer` | architect 初回案を批判 + Critical/Warning を反映した修正版最終 plan までを返す |
+| Shinaps Reviewer | `shinaps-reviewer` | logic / design / security / performance / maintainability / rule の統合観点でレビュー |
+
+実装フェーズ (Phase 5) は **メインスレッドが直接 Edit/Write で行う**。explorer / architect / plan-review で築いた文脈・設計判断の意図をそのまま実装に持ち込むことで、レビュー指摘の文脈共有と修正ループの精度を最大化する狙い。
+
+## ディレクトリ規約
+
+```
+.shinaps/work/{YYYYMMDD-HHMMSS}-{slug}/
+├── plan.md                    ← Phase 4 で確定する最終 plan (plan-reviewer Part 2)
+├── raw/                       ← 計画フェーズの生レポート (全文保存)
+│   ├── explorer.md            ← または explorer-1.md, explorer-2.md ... (事前調査 handoff 時は既存レポートを参照)
+│   ├── architect.md           ← architect の初回案
+│   ├── plan-review.md         ← plan-reviewer の Part 1 (レビュー結果のみ)
+│   ├── refine.md              ← Phase 6 で走らせた Skill(shinaps:refine) の findings 集約
+│   ├── simplify.md            ← Phase 6 の簡素化レビューの生レポート
+│   └── architect-revised-{n}.md  ← 差し戻し再策定時のみ (n は 1 始まり)
+├── implementation.md          ← 実装ログ・変更ファイル一覧・動作確認結果
+├── review.md                  ← shinaps-reviewer の生レポート
+├── review-{n}.md              ← 修正後の再レビュー (n は 2 始まり)
+└── fix-log.md                 ← 修正ループの履歴 (修正があった場合のみ)
+```
+
+`spec.md` / `exploration.md` からの handoff では、同ディレクトリの既存調査を再利用し、情報が十分なら自前で explorer を起動しない (Phase 2 参照)。
+
+`{slug}` はタスク内容の短い英語スラッグ (kebab-case, 30 文字以内)。
+
+## 実行フロー
+
+### Phase 1: タスク受領
+
+1. 引数なし → エラー終了「`/shinaps:dev <task>` でタスクを指定してください」
+2. 引数の文字列をタスク内容として確定
+3. 今回の依頼に関連する既存の spec・調査レポート・Git の変更履歴を確認し、引き継ぐ決定と根拠を要約する。既存成果物がなければ追加取得は不要。
+4. **他スキルからの handoff 判定**: 引数に成果物パス（旧 `.claude/shinaps/` を含む）が含まれていれば必ず Read し、タスク詳細・確定事項・未解決点を取り込む。特に以下を Phase 2 の事前調査として扱う:
+   - `specs/.../spec.md`: 同ディレクトリの `raw/explorer*.md` を確認する
+   - `explorations/.../exploration.md`: `## 実装 handoff` の `status: ready` を確認し、同ディレクトリの `raw/investigation-*.md` を確認する。status が欠落・不明・`not-ready` なら変更内容を推測せず、`AskUserQuestion` で「explore に戻る / 実装内容をここで確定する」を確認する
+5. タスクから英語 slug を生成 (kebab-case, 30 文字以内)
+6. 作業ディレクトリを確定: `.shinaps/work/{YYYYMMDD-HHMMSS}-{slug}/` + `raw/`
+7. タスク文字列が曖昧 / 制約が不明確な場合は `AskUserQuestion` で要件を確認 (何回聞いても良い)
+
+### Phase 2: コードベース探索
+
+#### spec.md / exploration.md からの handoff の場合 (推奨パス)
+
+Phase 1 で読んだ成果物と同ディレクトリの raw report を取り込み、現在の実装を理解するための証拠として再利用する。
+
+- spec handoff: `raw/explorer*.md` から必読ファイル一覧を抽出し、メインが直接 Read する
+- explore handoff: `exploration.md` の confirmed findings / 実装 handoff と `raw/investigation-*.md` の証拠・関連ファイルを取り込み、メインが重要箇所を直接 Read する
+- handoff の `evidenceSnapshot` にある各ローカル根拠ファイルの content hash を現在値と照合する。hash の不一致・ファイル欠落はその根拠を stale とみなし、同じ path を直接 Read して結論を再検証する。branch / HEAD / worktree status が同じでも hash 照合を省略しない
+- 現行仕様・バージョンなど時間依存の外部根拠は、実装判断を左右する場合に公式情報で再確認する
+- 情報が十分かつ最新なら **自前で `shinaps-explorer` を起動しない**
+- 情報不足、陳腐化、実装範囲の追加がある場合だけ補完的に `shinaps-explorer` を起動し、今回の作業ディレクトリの `raw/explorer-supplement.md` に保存する
+
+`search_rules` の結果はメインスレッドで Phase 2 冒頭に:
+- `list_search_facets()` で facet master を確認
+- `search_rules({ repoOwner, repoName, ...推定 facet })` で userRules + officialRules 全文を取得
+
+する形で確保しておく (Phase 3 以降で subagent prompt に埋め込む用)。
+
+#### handoff でない / 事前調査が不足する場合
+
+`list_search_facets()` + `search_rules({ repoOwner, repoName, ...推定 facet })` を呼び、rule カタログ (userRules + officialRules 全文) を確保 → `shinaps-explorer` を起動 (領域が広ければ複数並列)。
+
+**`shinaps-explorer` に渡す prompt に含める情報**:
+- タスク内容
+- **Phase 1 で作成した「既存成果物の要約」**
+- 探索の狙い
+
+**記録先**: メインが Write で `raw/explorer.md` (並列時は `raw/explorer-{n}.md`)
+
+### Phase 3: 実装ブループリント策定
+
+`shinaps-architect` を 1 体起動。
+
+**プロンプトに含める情報**:
+- タスク内容
+- Phase 2 の調査結果 (explorer または handoff 済み investigation の必読ファイル一覧 + 要点)
+- **Phase 2 で取得した `search_rules` 結果 (userRules + officialRules 全文)**
+- 「作業前に必ず CLAUDE.md / プロジェクト規約を Read し、rule カタログと突き合わせよ」
+
+**記録先**: メインが Write で `raw/architect.md`
+
+### Phase 4: プランレビュー
+
+`shinaps-plan-reviewer` を 1 体起動する。
+
+**プロンプトに含める情報**:
+- タスク内容
+- Phase 2 の調査結果 (explorer または handoff 済み investigation)
+- Phase 3 の architect 初回案 (`raw/architect.md` 全文)
+- Phase 2 の search_rules 結果 (userRules + officialRules 全文)
+- 「architect 案を批判的にレビューし、Critical / Warning を反映した修正版最終 plan を Part 2 として返せ。rule はアーキテクチャ / 責務分割 / 依存方向など実装後に気付くと手戻りが大きい設計レベルの違反を拾い、コードレベルの規約 (コメントの WHY / 命名 / import 経路) には踏み込まなくてよい」
+
+計画段階で `Skill(shinaps:refine)` を併走させない理由: rule の大半はコードレベルの規約で、自然言語の plan からは検出できない。plan で拾う価値がある設計レベルの違反は plan-reviewer の担当範囲と重なるため、独立した照合層を挟んでも search_rules の二重取得と agent 起動コストに見合わない。コードレベルの rule 照合は Phase 6 で実装後の実ファイルに対して行う。
+
+#### 統合
+
+応答を受け取ったら、メインスレッドで以下を Write:
+
+1. plan-reviewer Part 1 (レビュー結果のみ) を `raw/plan-review.md` に Write
+2. plan-reviewer Part 2 (修正版最終 plan、Full text) を `plan.md` として Write (これが最終 plan.md)
+
+#### 判定別のアクション
+
+| plan-reviewer 判定 | アクション |
+|---|---|
+| **承認** | Part 2 で確定した plan.md をそのまま Phase 5 へ |
+| **条件付き承認** | Part 2 で確定した plan.md をそのまま Phase 5 へ (条件は Phase 5 実装時に判断) |
+| **差し戻し** | `AskUserQuestion` で「再策定する / 指摘を未解決リスクとして明記して進む / タスク見直し」を確認。再策定の場合は Part 1 の差し戻し理由を渡して `shinaps-architect` を再起動、`raw/architect-revised-{n}.md` に保存 → 再度 plan-reviewer を起動 |
+
+### Phase 5: 実装フェーズ (メインスレッド直接実装)
+
+メインスレッドが Phase 4 で確定した `plan.md` の実装を **直接 Edit/Write で行う**。
+
+#### A. 事前整合性チェック
+
+1. `plan.md` を再読し、ビルド順序を `TaskCreate` で展開
+2. Phase 2-4 で確定した必読ファイル・plan-reviewer 指摘は既にメイン context に保有済み。再 Read は不要 — 新たに発生した疑問だけ Read で補う
+3. 既存実装との衝突や前提の不一致を発見した場合は `AskUserQuestion` で「plan を上書く / 既存に合わせる / Phase 4 に戻って plan-reviewer に再策定させる」を確認
+
+#### B. 実装
+
+- ビルド順序に従って Edit / Write で実装
+- 目的・仕様を左右する不明点だけ一問ずつ確認する。命名等の通常の実装判断は既存規約に合わせて進める
+- plan からの逸脱は `AskUserQuestion` で確認した上で `implementation.md` に経緯を記録
+- 1 サブタスク完了ごとに `TaskUpdate` で `completed` に進める
+- **判断 / ブロッカー / 方針転換で ローカル成果物（implementation.md / 調査・レビューレポート）** を残す
+
+#### C. `implementation.md` 執筆
+
+実装と並行して `implementation.md` を更新し、以下を全文記録する:
+
+- 変更ファイル一覧 (パス + 1 行サマリ)
+- 各ファイルでの **設計上の WHY** (なぜこの設計を選んだか / plan からの逸脱があれば理由)
+- 実装中に判断した重要事項
+- 残課題・規約衝突・未解決の論点
+
+#### D. 動作確認
+
+- プロジェクト規約・CI・変更の影響から必要な検証を実行する。UI変更は `verify-ui` で対象環境を確定して実画面を確認する。全案件に同じコマンド・端末構成を強制しない
+- 結果を `implementation.md` の「動作確認結果」セクションに記録
+- 自分の実装ミスによる失敗は **3 回まで自己修正**。それを超える場合は `AskUserQuestion` で「さらに修正試行 / Phase 6 のレビュー対象として diff を渡す / Phase 4 に戻って plan-reviewer に再策定させる」を確認
+
+### Phase 6: 簡素化後のセルフレビュー + refine
+
+まず `simplify` を適用し、目的を維持できる削除・簡素化をメインセッションで実施する。仕様変更の提案は確認してから進める。影響する検証を再実行し、その結果を `raw/simplify.md` に残す。
+
+その後、最終差分（staged / unstaged / untrackedを含む）と現在のファイル、plan、implementation、ruleカタログを使ってレビューする。許可された独立レビューでは `shinaps-reviewer` に読み取りだけを依頼し、`refine` で規約と照合する。委託できなければメインで両観点を確認し、独立レビュー済みとは報告しない。
+
+結果は `review.md` と `raw/refine.md` に記録する。簡素化前の差分だけをレビューして完了しない。
+
+### Phase 7: 修正ループ
+
+- **Critical は必ず自動修正** (reviewer Critical + refine の `scope=changed` な Violation、承認不要 — 動作を壊している / 規約違反の指摘)
+- **Phase 5 サブフェーズ D で検出された動作確認の失敗** も Critical として修正
+- **Warning は `AskUserQuestion` で確認**: 「全部修正 / 個別に確認 / 後回し (Issue 化) / スコープ外として記録」 (reviewer Warning + refine Improvement)
+- **refine の `scope=pre-existing` な finding は自動修正しない**。今回の実装と無関係な差分が commit に混ざるため、Violation でも `AskUserQuestion` で「今回直す / 別タスクにする」を確認する
+- **Info は記録のみで修正しない**
+- **簡素化レビューの「仕様を変えない削除・統合」は自動適用**し、Phase 5 サブフェーズ D の動作確認を再実行する。削除は追加より検証しやすく、残すほうが保守の負債になるため。**「仕様変更を伴う提案」は `AskUserQuestion` で確認**: 「採用して仕様を変える / 現状維持 / 別タスクにする」
+
+修正を行った場合、`fix-log.md` に「指摘 → 修正内容 → 該当ファイル」を記録。修正判断も `fix-log.md` に残す。
+
+修正実装はメインが直接 Edit/Write で行う (Phase 5 と同じ主体)。reviewer / refine の指摘文脈をメインがそのまま保持しているため、修正判断のブレが起きにくい。大規模な再実装が必要な場合は `AskUserQuestion` で「メインで修正継続 / Phase 4 に戻って plan-reviewer に再策定させる」を確認する。
+
+### Phase 8: 修正後の再レビュー (Critical / Warning 修正時のみ)
+
+Phase 7 で **Critical または Warning を修正した場合のみ**、もう一度 `shinaps-reviewer` を起動する (refine の再発火は Phase 8 では不要)。
+
+これは「修正で別バグを生むリスク」を検出するため。
+
+- プロンプトには「修正後の差分」「修正前の指摘」「修正内容」を渡す
+- 応答は `review-{n}.md` として保存 (n は 2 始まり)
+- 再レビューでさらに Critical が出た場合は再修正 → 再レビューを Critical が無くなるまで繰り返す
+- 各ラウンドの修正は `fix-log.md` に追記し、ラウンド数が判別できるようにする
+
+修正がなかった場合は再レビューをスキップして Phase 9 へ。
+
+### Phase 9: 完了と必要なhandoff
+
+変更、簡素化、検証結果、未確認事項を報告する。コミットが明示されていれば、その許可範囲と通常／自律モードを `commit` へ引き継ぐ。コミット依頼がなければ未コミットのまま完了し、毎回コミット許可を要求しない。PRやリリースは明示された場合だけ、それぞれ `create-pr`・`release` へ進む。
+
+## 動作原則
+
+- **EnterPlanMode は使わない**: bypassPermissions モード (リモート実行など) と両立させるため
+- **実装はメインスレッドが担う**: explorer / architect / plan-review で築いた文脈・設計判断の WHY をそのまま実装と修正ループに引き継ぐため。サブエージェント委譲は計画フェーズとレビューフェーズに限定
+- **subagent は文字列応答のみを返す**: raw/*.md への Write / Edit は必ずメインスレッドが担当
+- **rule 照合を各 Phase に bake**: Phase 2 の `search_rules` → Phase 3 の architect prompt 埋め込み → Phase 4 の plan-reviewer (設計レベルの違反) → Phase 6 の refine 並列 (コードレベルの違反)
+- **判断・方針転換で ローカル成果物（implementation.md / 調査・レビューレポート）**
+- **目的・仕様を左右する不明点を確認**: 既存の指示で分かることや任された細部は再質問しない
+- **生レポート保存厳守**: explorer / handoff 済み investigation / architect / plan-reviewer / reviewer / refine の応答は全文参照可能な状態を保つ
+- **Critical は自動修正、Warning は確認**
+- **簡素化をレビュー前に実行する**: 目的を保つ削除を先に適用し、最終差分をレビューする
+- **plan からの逸脱は確認 + 記録**: AskUserQuestion で確認した上で `implementation.md` に経緯を残す
+- **コミットは明示依頼時のみ**: Phase 9 で既存の許可を引き継ぐ。
+
+## 他スキルからの呼び出し
+
+`/shinaps:explore` `/shinaps:spec` `/shinaps:review` `/shinaps:debug` などから handoff される際は、それらが生成した **生成物のパス** を引数に直接渡す (専用の handoff ファイルは生成しない):
+
+| 元スキル | 渡すパス | dev での扱い |
+|---|---|---|
+| `/shinaps:explore` | `.shinaps/work/explorations/{ts}-{slug}/exploration.md` | `status: ready` と `evidenceSnapshot` を確認して合意済み変更・confirmed findings・未解決点を取り込み、Phase 2 で同ディレクトリ配下の `raw/investigation-*.md` を再利用。status 欠落 / `not-ready` なら変更内容を推測しない |
+| `/shinaps:spec` | `.shinaps/work/specs/{ts}-{slug}/spec.md` | Phase 1 で Read してタスク詳細・採用技術を取り込み、Phase 2 で同ディレクトリ配下の `raw/explorer.md` を再利用 |
+| `/shinaps:review` | `.shinaps/work/reviews/{ts}-{mode}/review-validated.md` | Phase 1 で Read し、確定指摘を修正タスクとして扱う |
+| `/shinaps:debug` | `.shinaps/work/debug/{ts}-{slug}/debug-validated.md` | Phase 1 で Read し、root-cause / contributing-factor を修正タスクとして扱う |
+
+```
+Skill(skill="shinaps:dev", args="<元タスク要約>。詳細は <生成物パス> を参照")
+```