@shinaps/skills 0.30.0 → 0.32.0

package/README.md

@@ -6,12 +6,24 @@ Shinaps AIの利用者向け開発ワークフロー。Claude CodeとCodexには
 
 共通スキルが持つのは判断手順。対象環境・必須検証・公開条件は、対象プロジェクトの `AGENTS.md` / `CLAUDE.md` と参照先、README、CI、既存スクリプトから読み取る。専用設定ファイルは必須にしない。
 
-例外として `linear-execute` の開発進行とチーム設定の変更には、対象リポジトリの `.shinaps/linear.yaml` を必須にする。操作の継続的な許可と終了地点を会話から推測せず、合意した範囲だけを続けて進めるためである。設定は `config_storage: shared` でGit共有、`local` でメインの作業ツリーだけに保存する。既存設定でキーがない場合だけ従来のlocal扱いを維持し、自動追記・許可の再合意は求めない。sharedは現在のcheckout、localはメインの設定と補足を正本とする。共有設定が欠けていても端末別のlocal設定では補わない。[共通設定](plugins/shinaps-claude/references/linear/configuration.md)の読取・保存手順に従う。設定がなくてもIssueの読み取り・整理はできる。設定が必要な実行で共通の読取手順により真に未設定と確認できた場合だけ、同じセッションで `linear-plan` の初期設定ヒアリングへ進み、合意した設定の保存・確認後に元の依頼を再開する。
+例外として `linear-execute` の開発進行とチーム設定の変更には、対象リポジトリの `.shinaps/linear.json` を必須にする。操作の継続的な許可と終了地点を会話から推測せず、合意した範囲だけを続けて進めるためである。設定は `config_storage: shared` でGit共有、`local` でメインの作業ツリーだけに保存する。必須キーの欠落は設定不備として止め、旧設定は明示移行する。sharedは現在のcheckout、localはメインの設定と補足を正本とする。共有設定が欠けていても端末別のlocal設定では補わない。[共通設定](plugins/shinaps-claude/references/linear/configuration.md)の読取・保存手順に従う。設定がなくてもIssueの読み取り・整理はできる。設定が必要な実行で共通の読取手順により真に未設定と確認できた場合だけ、同じセッションで `linear-plan` の初期設定ヒアリングへ進み、合意した設定の保存・確認後に元の依頼を再開する。
 
-sharedで採用する `instructions.md` は共有YAMLの `references.specifications` に明記して開始・再開時に読み、他の必要補足は内容に対応する `references` に記載する。必要補足の欠落・読取不能は依存工程を止め、未採用とは扱わない。設定・採用補足・ignoreの個別例外を一緒に共有するか、共有済み資料への参照に置き換える。端末の絶対パスやsession/thread ID、進捗・QA結果は `.shinaps/work/` に分け、秘密値はどちらにも保存しない。保存方式の合意だけでstage・commit・push・追跡解除を許可しない。
+sharedで採用する `instructions.md` は共有JSONの `references.specifications` に明記して開始・再開時に読み、他の必要補足は内容に対応する `references` に記載する。必要補足の欠落・読取不能は依存工程を止め、未採用とは扱わない。設定・採用補足・ignoreの個別例外を一緒に共有するか、共有済み資料への参照に置き換える。端末の絶対パスやsession/thread ID、進捗・QA結果は `.shinaps/work/` に分け、秘密値はどちらにも保存しない。保存方式の合意だけでstage・commit・push・追跡解除を許可しない。
 
 例えばPCブラウザのみのプロジェクトには対応ブラウザと確認コマンドを書く。iOSプロジェクトにはSimulatorと実機の使い分けを記す。スキルは一律の端末数やOS数を追加しない。既存の情報で決まらず結果を左右する条件だけ確認し、保存を了承された方針をプロジェクト側に残す。
 
+## JSON設定の検証
+
+0.32.0から `.shinaps/linear.json`（`config_version: 1`）を使います。旧YAML・scalar review_flow・旧キーの共存は移行未完了として止め、[移行手順](plugins/shinaps-claude/references/linear/configuration.md#旧設定の移行)に従います。コメントの運用条件も補足へ移します。
+
+CLIはpluginに含まれないため、利用中のskillと同じ `@shinaps/skills@0.32.0` を導入し、`shinaps-skills --version` で確認します。`shinaps-skills validate-linear-config <明示ファイル>` は同梱schemaだけで検証し、ネットワーク取得・正本探索・Git操作・入力変更は行いません。`$schema` は固定URLによるエディタ補助で、契約の正本は[同梱schema](plugins/shinaps-claude/references/linear/configuration.schema.json)です。
+
+```sh
+npm install -g @shinaps/skills@0.32.0
+shinaps-skills --version
+shinaps-skills validate-linear-config /absolute/repository/.shinaps/linear.json
+```
+
 ## スキル
 
 | 名前 | 用途 |
@@ -24,7 +36,7 @@ sharedで採用する `instructions.md` は共有YAMLの `references.specificati
 | `refine` | Shinaps AIのruleと実ファイルを照合する |
 | `extract-rules` | PRレビューからruleを抽出する |
 | `simplify` | 目的から見直して不要な構造や手順を削る |
-| `commit` | 進め方（通常・自律）を各単位の実効方針か確認で決め、検証できる単位でコミットする |
+| `commit` | 各単位のreview_flowに従い、autoはAIがレビュー・コミット、manualはAIがstash・stage・提示し、人がレビュー・修正・コミットする |
 | `create-pr` | リポジトリの規約に合わせてPRを作成する |
 | `release` | 公開条件を確定し、対象バージョンの利用可能性を確認する |
 | `linear-plan` | 相談・必要なspec/explore・Issue作成と整理・プロジェクト設定を行い、実装前で止める |
@@ -32,15 +44,15 @@ sharedで採用する `instructions.md` は共有YAMLの `references.specificati
 
 コミット・PR・リリースは、利用者の依頼またはLinear進行で合意済みの継続許可に従う。[共通設定](plugins/shinaps-claude/references/linear/configuration.md)・[担当と工程](plugins/shinaps-claude/references/linear/workflow.md)・[終了と待機](plugins/shinaps-claude/references/linear/execution.md)を参照し、必要な前工程が揃えば再確認せずに進む。単独スキル利用にはLinear進行や新しいゴールを必須にしない。`autonomous-commit-review` の役割は `commit` に統合した。個人用の別AI呼び出し・ブラウザ管理・ゴール管理・動画制作はこのpluginに含めない。
 
-`linear-execute` は初版では利用者本人の環境向けで、進行とAgent QAは会話側が担当する（Claude・Codexの入口ではCodex、Managedの入口では linear-execute を実行する Claude Code または Codex）。運用項目は明示必須で、既存設定の `config_storage`・`path_policy_overrides` 欠落は共通設定の説明に従い、それ以外は未記載を既定値で補わない。実装の担当は作業先の `.shinaps/linear.yaml` の `implementation_skill` で選ぶ。`dev-claude` を選ぶと、ClaudeがAI Terminal Bridge経由の依頼で実装する。`dev-codex` を選ぶと、会話側はゴール・進行・Agent QAを担当し、Issueごとの別Codexタスクが実装・QA指摘の修正・許可されたコミットを行う。タスク作成・連絡には `codex_task` とツールが要求する明示依頼が必要。`dev-managed-cc` を選ぶと、Issueごとの Managed Agents セッションが実装し、進行役が差分を適用してQA・コミットを行う。`managed_session:<USD>` と `dev_delegation` が必要で、Bridge は不要。どの入口でも `implementation_skill` は許可を増やさない。Bridge本体は同梱せず、導入済みのMCPとWebStormプラグインを使う。`SKILL.md` は担当ごとに両版で書き分け、共通の手順と書式は `references/linear/` に置く。`references/linear/` はClaude版を編集元としてCodex版とManaged Agents版へ同じ内容を複製し、テストで一致を確認する。
+`linear-execute` は初版では利用者本人の環境向けで、進行とAgent QAは会話側が担当する（Claude・Codexの入口ではCodex、Managedの入口では linear-execute を実行する Claude Code または Codex）。運用項目は明示必須で、未記載を既定値で補わない。実装の担当は作業先の `.shinaps/linear.json` の `implementation_skill` で選ぶ。`dev-claude` はauto/manualともCodexがローカル `claude -p` を起動し、同じsessionをresumeする。manualのレビューUIは `review_flow.tool` で選ぶ。[CLI手順](plugins/shinaps-claude/references/linear/claude-cli.md)に従い、CLIの既存権限・model・effort・pluginsを保持する。`dev-codex` を選ぶと、会話側はゴール・進行・Agent QAを担当し、Issueごとの別Codexタスクが実装・QA指摘の修正・許可されたコミットを行う。タスク作成・連絡には `codex_task` とツールが要求する明示依頼が必要。`dev-managed-cc` を選ぶと、Issueごとの Managed Agents セッションが実装し、進行役が差分を適用してQAとreview_flowに従ったコミット工程を行う。`managed_session:<USD>` と `dev_delegation` が必要で、Bridge は不要。どの入口でも `implementation_skill` は許可を増やさない。Bridge本体は同梱せず、導入済みのMCPとWebStormプラグインを使う。`SKILL.md` は担当ごとに両版で書き分け、共通の手順と書式は `references/linear/` に置く。`references/linear/` はClaude版を編集元としてCodex版とManaged Agents版へ同じ内容を複製し、テストで一致を確認する。
 
-`path_policy_overrides` で、合意したパスの範囲に限り人レビュー・AIコミット許可・コミットモードを個別に上書きできる。たとえば `paths: ["docs/**", "README.md"]` と `human_code_review: skip` を指定すると、予定コミットの全変更がその範囲に収まる場合だけ人レビューを省く。同じコミットに対象外が混ざれば、そのコミット全体を通常方針とし、改名・移動は旧新両パスを判定する。同じ依頼でも自然な責務分割で独立した範囲内コミットには例外を適用できる。stage・push・公開の許可や必要なQAは変わらない。設定例と競合・照合の手順は[パス別の方針](plugins/shinaps-claude/references/linear/configuration.md#パス別の方針)を参照する。
+`review_flow: { "mode": "auto" }` はAIが自然な単位を決め、独立レビュー・QA後にstage・commitする。`review_flow: { "mode": "manual", "tool": "plasma" }`（toolは `webstorm` も可） はAIが単位を計画し、単位外を安全にstashしてstage・提示し、人がレビュー・修正・commitする。両方のstage権限とautoのAI commit権限は利用者との明示合意に含まれ、未合意ファイルからは得ない。`path_policy_overrides` は `paths` と `review_flow` だけを持つ。全変更が一つのルールで覆われる単位だけ適用し、改名は旧新両パスを判定する。競合時は止める。旧 `human_code_review`・`commit_mode`・permissionsのstage/commit・パス別ai_commitは明示移行が必要。[共通設定](plugins/shinaps-claude/references/linear/configuration.md#パス別の方針)を参照する。
 
-0.29.0では旧 `document_only_changes: ai_commit` を廃止した。利用先では依存工程を止め、具体的なパス例外への移行または例外廃止を合意する。説明だけの変更の許可とは同値でないため自動変換しない。旧 `none` は例外なしとして維持でき、新規設定は `path_policy_overrides: []` にする。
+0.29.0では旧 `document_only_changes: ai_commit` を廃止した。利用先では依存工程を止め、具体的なパス例外への移行または例外廃止を合意する。説明だけの変更の許可とは同値でないため自動変換しない。旧 `none` もJSONへ明示移行し、新規設定は `path_policy_overrides: []` にする。
 
 `permissions` の `development_operations` を明示すると、既存アカウントのログイン・環境準備・依存導入・起動・テスト・QAを継続的に許可できる。コミット・公開・破壊的操作の許可や人レビューは別に扱う。
 
-旧 `linear` の入口は廃止した。相談・Issue整理・設定変更は `linear-plan`、実行は `linear-execute` を使う。YAMLの名前・運用項目は変わらない。実行範囲は毎回の依頼で確定し、バックログではブロッカー到達と報告を終了条件にできる。人レビュー・Human QA待ちは予定工程として待機する。
+旧 `linear` の入口は廃止した。相談・Issue整理・設定変更は `linear-plan`、実行は `linear-execute` を使う。設定は0.32.0からJSONへ移行する。実行範囲は毎回の依頼で確定し、バックログではブロッカー到達と報告を終了条件にできる。人レビュー・Human QA待ちは予定工程として待機する。
 
 ### dev の入口と体制
 
@@ -72,7 +84,7 @@ sharedで採用する `instructions.md` は共有YAMLの `references.specificati
 
 ## Codex
 
-Node.js 22以上と、`plugin marketplace add` / `plugin add` に対応したCodex CLIを使う。Claude Codeのインストールは不要。ただし `linear-execute` の開発進行をClaudeの入口で行う場合は、Claude CodeとAI Terminal Bridgeが必要になる。Managedの入口で進める場合は `ant` CLI が必要になる。
+Node.js 22以上と、`plugin marketplace add` / `plugin add` に対応したCodex CLIを使う。Claude Codeのインストールは不要。ただし `linear-execute` の開発進行をClaudeの入口で行う場合は、両modeともローカルClaude Codeが必要になる。Managedの入口で進める場合は `ant` CLI が必要になる。
 
 導入・更新・削除:
 
@@ -249,7 +261,7 @@ npm pack --dry-run
 
 ### Codexでの人レビュー
 
-人レビューやコミット単位の承認を依頼する際、CodexはPlasmaで対象checkoutと差分を提示します。変更の目的と確認点は会話に示し、利用者の明示的なレビュー完了を待ちます。Plasmaは別途導入するツールで、未導入時も人レビューを省略しません。表示差分とコミット対象の照合、修正後の再確認は[共通手順](plugins/shinaps-codex/references/human-review.md)に従います。人レビューを省略するプロジェクトへ新たなレビュー待ちは追加しません。
+manualでは対象checkoutと単位の差分を提示し、人のレビュー・修正・コミット完了を待ちます。実装runtimeによらず、実効 `review_flow.tool` でPlasmaまたはWebStormを選びます。Plasmaは別途導入するツールで、未導入時も人レビューを省略しません。変更の目的と確認点は会話に示し、人の完了通知後の実コミット照合と修正の検証は[共通手順](plugins/shinaps-codex/references/human-review.md)に従います。autoには人レビュー待ちを追加しません。
 
 ### CIとnpm自動公開
 
@@ -307,7 +319,7 @@ codex mcp login shinaps-ai
 | `shinaps-survey-validator` | tech-surveyor の出典を WebFetch で再確認 |
 | `shinaps-debugger` | 症状から根本原因の仮説立案 (コードトレース + WebSearch + GitHub Issue) |
 | `shinaps-debug-validator` | 仮説の実コード検証 (root-cause / contributing-factor / red-herring / needs-reproduction 分類) |
-| `shinaps-split-reviewer` | `shinaps:commit` の通常モードの分割案を「単位の diff だけで妥当性を判断できるか」で批判 + 修正版最終分割計画 (worktree は read-only) |
+| `shinaps-split-reviewer` | `shinaps:commit` のmanualの分割案を「単位の diff だけで妥当性を判断できるか」で批判 + 修正版最終分割計画 (worktree は read-only) |
 
 Claude版はMarkdown、Codex版はTOMLで役割を定義する。Managed Agents版は dev で使う8役割だけを、Claude版の本文に `ant apply` 用の frontmatter を付けたMarkdownで定義する。
 
@@ -323,7 +335,7 @@ Claude版は全16エージェントが `opus / medium`。Codex版の役割定義
 ```text
 .shinaps/
 ├── .gitignore             # 保存方式に応じた除外・共有対象の例外
-├── linear.yaml            # linear のプロジェクト設定（任意）
+├── linear.json            # linear のプロジェクト設定（任意）
 ├── linear/                # linear の補足（任意）
 └── work/
     ├── {日時}-{作業名}/

package/dist/bin/skills.js

@@ -1,10 +1,23 @@
 #!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { packageRoot } from '../lib/layout.js';
+import { validateLinearConfig } from '../lib/linear-config.js';
 import { run } from '../lib/install.js';
 import { autoUpdate } from '../lib/auto-update.js';
 import { errorMessage } from '../lib/fs.js';
 const [command, ...rest] = process.argv.slice(2);
 try {
-    if (command === 'auto-update')
+    if (command === '--version') {
+        console.log(JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8')).version);
+    }
+    else if (command === 'validate-linear-config') {
+        if (rest.length !== 1)
+            throw new Error('Usage: shinaps-skills validate-linear-config <file>');
+        await validateLinearConfig(rest[0]);
+        console.log('Linear configuration is valid (config_version: 1).');
+    }
+    else if (command === 'auto-update')
         await autoUpdate(rest);
     else
         await run(process.argv.slice(2));

package/dist/lib/install.js

@@ -10,6 +10,7 @@ const actions = ['install', 'update', 'uninstall', 'recover'];
 const isAction = (value) => actions.includes(value);
 const usage = [
     'Usage: shinaps-skills <install|update|uninstall|recover> codex',
+    '       shinaps-skills validate-linear-config <file>',
     '       shinaps-skills auto-update <enable|disable|status|check> codex',
     'Claude Code: /plugin marketplace add sh1n4ps/shinaps-skills',
     '             /plugin install shinaps@shinaps-skills',

package/dist/lib/linear-config.js

@@ -0,0 +1,32 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Ajv } from 'ajv';
+import { packageRoot } from './layout.js';
+/** 明示されたファイルを同梱の契約で検証する。設定の探索・変更や外部取得は行わない。 */
+export async function validateLinearConfig(path) {
+    const input = JSON.parse(await readFile(path, 'utf8'));
+    // 版の不一致は設定修正とskill更新で対処が異なるため、schema検証より先に案内する。
+    if (typeof input === 'object' && input !== null && !Array.isArray(input)) {
+        const version = 'config_version' in input ? input.config_version : undefined;
+        if (version === undefined || (Number.isInteger(version) && Number(version) < 1)) {
+            throw new Error('config_version is missing or old. Migrate with linear-plan to config_version: 1.');
+        }
+        if (Number.isInteger(version) && Number(version) > 1) {
+            throw new Error('Future config_version. Update the skill and matching CLI before continuing.');
+        }
+    }
+    const schema = JSON.parse(await readFile(join(packageRoot, 'plugins/shinaps-claude/references/linear/configuration.schema.json'), 'utf8'));
+    const validator = new Ajv({
+        allErrors: true,
+        coerceTypes: false,
+        useDefaults: false,
+        removeAdditional: false,
+    });
+    const validate = validator.compile(schema);
+    if (!validate(input)) {
+        const errors = validate.errors
+            ?.map((error) => `${error.instancePath || '/'} ${error.message} ${JSON.stringify(error.params)}`)
+            .join('\n');
+        throw new Error(`Invalid Linear configuration. Correct the JSON to match configuration.schema.json:\n${errors}`);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shinaps/skills",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "description": "Install Shinaps AI workflows and custom agents for Codex",
   "type": "module",
   "bin": {
@@ -39,5 +39,8 @@
     "@biomejs/biome": "2.5.15",
     "@types/node": "^26.6.4",
     "typescript": "^7.0.2"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0"
   }
 }

package/plugins/shinaps-claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "shinaps",
   "description": "Shinaps AIの開発ワークフロー。プロジェクトの指示から条件を読み、調査・設計・実装・簡素化・レビュー・コミット・PR・リリースとLinearでの開発進行を支援する。",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "author": {
     "name": "shinaps",
     "email": "ryuta@shinaps.jp"

package/plugins/shinaps-claude/agents/shinaps-split-reviewer.md

@@ -1,13 +1,13 @@
 ---
 name: shinaps-split-reviewer
-description: shinaps:commit の通常モードで、人が単位ごとに承認する前に分割計画を確認するレビューエージェント。メインスレッドが提案したコミット単位の分割を、各単位の diff だけを読んで変更の妥当性を判断できるか (下限) / 一言で説明できる範囲か (上限) / 依存順 / 網羅性の観点で批判的にレビューし、指摘を反映した修正版最終分割計画までを返す。worktree は read-only で扱い、stash / add / checkout / Edit は一切行わない
+description: shinaps:commit のmanualで、人が単位ごとにレビュー・修正・コミットする前に分割計画を確認するレビューエージェント。メインスレッドが提案したコミット単位の分割を、各単位の diff だけを読んで変更の妥当性を判断できるか (下限) / 一言で説明できる範囲か (上限) / 依存順 / 網羅性の観点で批判的にレビューし、指摘を反映した修正版最終分割計画までを返す。worktree は read-only で扱い、stash / add / checkout / Edit は一切行わない
 model: opus
 effort: medium
 color: blue
 ---
 
-あなたは `/shinaps:commit` の通常モードで、人が単位ごとに承認する前に分割計画を確認するレビューエージェントです。
-メインスレッドが提案した **コミット単位の分割計画** を、「この単位の diff だけを渡された人間レビュアーが、変更の妥当性を判断できるか」という視点で **批判的に検証** し、Critical / Warning / Info の指摘を出したうえで、**指摘を反映した修正版最終分割計画 (Part 2)** までを返してください。人が単位ごとに承認する前に区切り方を確かめる立場なので（人の承認は代行しない）、「概ね良い」で済ませずに各単位を実際に読んで判定します。
+あなたは `/shinaps:commit` のmanualで、人が単位ごとにレビュー・修正・コミットする前に分割計画を確認するレビューエージェントです。
+メインスレッドが提案した **コミット単位の分割計画** を、「この単位の diff だけを渡された人間レビュアーが、変更の妥当性を判断できるか」という視点で **批判的に検証** し、Critical / Warning / Info の指摘を出したうえで、**指摘を反映した修正版最終分割計画 (Part 2)** までを返してください。人が単位ごとにレビュー・修正・コミットする前に区切り方を確かめる立場なので（人のレビュー・コミットは代行しない）、「概ね良い」で済ませずに各単位を実際に読んで判定します。
 
 ## 作業前の必須確認
 

package/plugins/shinaps-claude/references/dev/launch.md

@@ -6,6 +6,6 @@
 - 同じ役割の複数担当 は、同じ登録エージェントを別々に起動する。呼び出しごとに別のコンテキストになるので、互いの結果は共有されない。担当番号は起動前に固定し、返された ID と対応づけて保持する。
 - 並行する担当はバックグラウンドで起動し、全担当の完了を待つ。同時に起動できなかった担当は、実行中の担当の完了後に起動する。
 - 同じ担当の継続は、同じ ID へ SendMessage で依頼する。
-- 質問は `AskUserQuestion` で一問ずつ行う。進捗は `TaskCreate`・`TaskUpdate` で管理する。他スキル（`commit`・`create-pr`・`release`）への引き継ぎは `Skill` を使う。現在のセッションで提供されていないツールは仮定しない。
+- 対話セッションの質問は `AskUserQuestion` で一問ずつ行う。CodexからローカルCLIで受けた依頼では質問・障害・再開点を最終resultへ返してターンを終了し（CLI内で `AskUserQuestion` や入力待ちを行わない）、同じsessionのresumeで回答を受ける（[CLI手順](../linear/claude-cli.md)）。Bridge経路は依頼元Codexへ返す。進捗は `TaskCreate`・`TaskUpdate` で管理する。他スキル（`commit`・`create-pr`・`release`）への引き継ぎは `Skill` を使う。現在のセッションで提供されていないツールは仮定しない。
 - `EnterPlanMode` は使わない。bypassPermissions モード（リモート実行など）と両立させるため。
 - 起動できない、または完了しない担当は未完了として記録する。他のモデルや Fable へ切り替えず、メインが代わりに作業して独立確認済みと報告しない。

package/plugins/shinaps-claude/references/dev/workflow.md

@@ -105,7 +105,7 @@ Issue・既存spec・調査記録・関連コード・検証方法を必要な
 
 初期体制と変更理由、実際の担当・確認範囲、計画と実装後のレビュー回数、採否・修正、検証結果、未実施・未照合・未解決事項を報告する。
 
-linear-executeから受けた作業は未コミットの差分と結果を進行役へ返す。devの完了はLocal Agent QAへの引き渡しであり、進行全体の終了ではない。[Linear共通設定](../linear/configuration.md)と[担当と工程](../linear/workflow.md)に従い、QA後のコミット依頼を受ける。
+linear-executeから受けた作業は未コミットの差分と結果を進行役へ返す。devの完了はLocal Agent QAへの引き渡しであり、進行全体の終了ではない。[Linear共通設定](../linear/configuration.md)と[担当と工程](../linear/workflow.md)に従い、QA後のcommit工程の依頼を受け、autoはAIコミット、manualは人への提示準備を行う。Claudeのauto/manual両modeは [Claude CLI](../linear/claude-cli.md) のresultへ報告し、同じsessionのresumeで質問・修正を受ける。manualの提示はprocess終了後に実効 `review_flow.tool` で行う。Codex・Managedはそれぞれの既存返却経路を使う。
 
 単独のdevではコミットが許可されている場合だけ範囲とモードを `commit` へ渡す。許可がなければ未コミットで返し、形式的な許可確認を追加しない。PR・リリースも許可された範囲で各スキルへ渡す。単独devにLinear進行・新しいゴールを必須にしない。
 

package/plugins/shinaps-claude/references/human-review.md

@@ -1,24 +1,32 @@
 # 人レビューの差分提示
 
-人のコードレビューが必要な場合、またはコミット単位の承認を求める場合に使う。人レビューの要否・操作許可・コミットモードは、プロジェクト設定と今回の依頼に従う。この手順はそれらを変更しない。
+manualで人がレビュー・修正・commitする場合に使う。review_flow・操作許可は、プロジェクト設定と今回の依頼に従う。この手順はそれらを変更しない。
+
+実装runtimeによらず、実効 `review_flow.tool` が `plasma` ならPlasma、`webstorm` ならWebStormを使う。UIの指定がない場合は提示前に一問で確認する。設定のmanualでtoolが欠落していれば設定を修正する。CLIのprocess終了を確認してから提示し、人の操作と実装処理を並行しない。
 
 ## 対象の準備
 
 レビュー対象のcheckoutの絶対パス、ブランチ、比較元のcommit、対象ファイルと完全な差分、検証結果を確定する。未追跡ファイルも対象に含める。stageは許可された範囲だけで行い、無関係な差分や既存のステージ境界を変更しない。対象差分と比較元は作業記録へ残し、後で承認対象と照合できるようにする。
 
-## CodexではPlasmaで開く
+## plasmaではPlasmaで開く
 
-人への窓口がCodexの場合は、実装担当がCodexかClaudeかによらず、レビューを依頼する会話でPlasmaを開く。人への窓口がClaudeの場合は既存の差分提示方法を使い、Plasmaのためだけに別のCodexタスクを作らない。
+レビューを依頼する進行役の会話でPlasmaを開く。必要なツールが利用不能なら止め、runtimeから別UIを推測しない。
 
 1. 利用可能なPlasmaの`open_workbench`ツールと現在の入力仕様を確認する。ファイルを開く`route`が使える場合は、対象checkoutの絶対パスとレビュー対象のファイルを指定する。現在の形式は`/open?project=ABSOLUTE_PATH&file=RELATIVE_PATH&line=START&endLine=END`で、各値をURLエンコードする。存在するファイルを使い、適切なファイルがない場合はプロジェクト選択画面から対象checkoutを選ぶ。
 2. ファイルを開くことと差分を表示することを区別する。ファイル用routeに差分モードの未定義パラメーターを足さない。利用可能なUI操作ツールでPlasmaのGit画面を確認し、レビュー対象に合う比較を選ぶ。UI操作が使えない場合は、対象プロジェクト・比較方法・ファイル一覧を示して利用者に選択を依頼する。
 3. 表示中のcheckout・比較元・対象範囲をGitで確定した差分と照合する。ステージ済みの単位なら`git diff --cached`を基準にする。作業ツリー全体や別ブランチの差分を、その単位の差分として提示しない。対象全体を表示できない場合は、未表示の範囲を明示し、完全な差分を確認できる方法を利用者と決める。
-4. 会話に変更の目的、確認してほしい点、検証結果、対象単位を示し、修正指示またはレビュー完了を依頼する。Linear進行ではIssueも示す。Plasma内の注釈は指摘として扱い、画面を開いたことや操作の終了を承認とみなさない。
+4. 会話に変更の目的、確認してほしい点、検証結果、対象単位を示し、レビュー・必要な修正・コミット完了を依頼する。Linear進行ではIssueも示す。Plasma内の注釈は指摘として扱い、画面を開いたことや操作の終了を承認とみなさない。
+
+Plasmaが未導入・起動失敗の場合は、その状態を伝えて止める。別UIを使う場合はtoolの変更を合意してから同じ対象を提示する。無断でインストールや設定変更を行わず、表示できていないレビューを完了扱いにしない。
+
+## webstormではWebStormで開く
+
+`webstorm <checkoutの絶対パス>` で対象を開く。checkout・branch・比較元を確認し、対象単位のstaged差分（`git diff --cached`）を提示する。単にファイルを開いたことを差分表示の完了と扱わない。会話に目的・確認点・検証結果・対象単位を示し、人のレビュー・修正・commit完了を待つ。ツールがない、起動できない、対象差分を確認できない場合は止め、無断fallbackしない。
 
-Plasmaが未導入・起動失敗の場合は、その状態を伝え、Codexの差分表示など利用者が選んだ方法で同じ対象を提示する。無断でインストールや設定変更を行わず、表示できていないレビューを完了扱いにしない。
+## 人のレビュー・コミット完了後の照合
 
-## 承認後の照合
+利用者の明示的なレビュー・修正・コミット完了通知を、対象単位と対応付けて記録する。その後、実コミット一覧・SHA・完全な差分を調べ、許可された目的・範囲と実効review_flowを確認し、影響する挙動を再検証する。Gitにcommitがあるだけでは完了としない。
 
-利用者の明示的なレビュー完了を、対象単位と対応付けて記録する。修正した場合は必要な検証を行い、更新した差分を再提示して再確認を受ける。待機中に対象が変わった場合も、古い承認をそのまま適用しない。
+本人が明示確認した正当な修正は確定単位と全体期待差分に反映する。元の予定差分を保持し、完了通知・修正理由・確定差分・実コミットの対応を記録する。その修正だけを理由に再提示・再承認を要求しない。目的や範囲が不明、対象外変更が混入、適用flowが未解決の場合は人へ確認し、次工程を止める。最終照合は確定済みの期待差分を使い、元の差分との機械的な一致を要求しない。
 
-コミット直前に実際のコミット対象と承認対象の完全な差分を照合する。不一致ならコミットせず、変更後の対象を提示する。Plasmaを開くことはstage・commit・pushの許可を追加しない。具体的なコミット操作は`commit`に従う。
+stashの復元では人の修正を保持し、古い対象パッチで上書きしない。具体的な単位照合・復元は `commit` に従う。表示UIを開くことはstage・commit・pushの許可を追加しない。

package/plugins/shinaps-claude/references/linear/claude-cli.md

@@ -0,0 +1,37 @@
+# ローカルClaude CLIによる実装
+
+`dev-claude` はauto/manualとも、Codexが作業先でローカル `claude -p` を起動する。初回実装前に正確なcheckout・branch・HEAD・既存差分と `claude_cli` の許可（または今回の明示依頼）を確定する。CodexとManagedの既存経路は変更しない。
+
+パス例外はコミット単位のreview_flowを全体置換し、実装sessionを途中で切り替えない。manual単位ではstash・stageまで準備したCLIのprocess終了を確認し、進行役が同じcheckoutを実効 `review_flow.tool`（plasma / webstorm）で提示する。[人レビュー](../human-review.md)に従って人のレビュー・修正・commit完了を受け取り、単位差分・SHAと照合する。その後は変更後のHEADと差分を添えて同じCLI sessionをresumeする。人の操作中にCLIを並行実行しない。UI不足時は止め、別UIやBridgeへ無断で切り替えない。
+
+## 起動と観測
+
+通常の `-p` は既存の設定・skills・plugins・Agentを読み込む。`--bare` やsafe-modeで省かない。model・effort・plugin構成を指定して上書きせず、利用者のCLI設定を保持する。Skill/Agentを技術的に呼べることと、その操作の権限が許可されることは別である。
+
+依頼本文を作業記録のpromptファイルへ保存し、stdinで渡す。本文をshellへ展開しない。以下は絶対パスを今回の記録先に置き換え、コマンドのcwdを確定済みcheckoutへ指定して実行する例。毎回異なる出力名を使い、既存記録を上書きしない。必要なSkill/Agent・Read/Edit・検証コマンド等の `--allowedTools` は依頼の許可と範囲から個別に追加する。たとえばcommit段階の `Bash(git add <対象パス>)` と `Bash(git commit -m <確定メッセージ>)` は実際の引数に限定し、初回実装にはcommit権限を渡さない。広範な既存allow設定がある場合も対象外操作の許可とは扱わない。
+
+```sh
+claude -p --output-format json --permission-mode dontAsk --permission-prompts none < /absolute/work/request.txt > /absolute/work/result.json 2> /absolute/work/stderr.log
+```
+
+途中経過が必要なら `--output-format stream-json --verbose` を使い、JSONLへ保存する。シェル実行ツールのprocess/session ID、開始時刻、cwd、Issue、出力パスを記録する。実行中は同じprocessを短い待機（最大60秒）で観測し、終了コードを取得する。新しいCLIを並行起動せず、進捗を会話へ返す。stream-jsonはイベントを読み、最終resultがない途中出力を完了と扱わない。
+
+jsonの `session_id`、`result`、`is_error`、`permission_denials` を読み、stream-jsonではsession初期化と最終resultを照合する。session_idをIssueとcwdに紐づけてローカル作業記録に保持する。終了コード0だけで成功にせず、エラー・拒否・質問・成果を確認して実差分と検証結果を独立QAする。ID欠落、異常終了、出力欠落なら停止してprocessと記録を調べる。結果不明のまま新規セッションを起動したり同じ依頼を再送したりしない。
+
+## 依頼・質問・修正・コミット
+
+promptにはIssue、`shinaps:dev-claude`、成果物と受入条件、初期体制、exact cwd・branch・HEAD・既存差分、許可・禁止操作、規約と参照先、返却条件を含める。linear-executeを再起動せず、実装後は未コミット差分を返してLocal Agent QAを待つ。spec/explore/review/debugの結果も同じ依頼へ渡す。質問・障害は最終resultに返し、Codexが既存合意で回答できれば回答、目的・権限の判断が必要なら人へ一問ずつ取り次ぐ。CLIからBridge送信や人の対話入力を待たせない。
+
+回答・QA修正・QA後のautoコミット依頼は、元のprocess終了後、記録済みの正確なIDで同じセッションをresumeする。`--continue` で別セッションを推測しない。
+
+```sh
+claude -p --resume '<recorded-session-id>' --output-format json --permission-mode dontAsk --permission-prompts none < /absolute/work/follow-up.txt > /absolute/work/follow-up-result.json 2> /absolute/work/follow-up-stderr.log
+```
+
+resumeにも同じcwdと許可境界を指定し、外部で変化したHEAD・差分を渡す。commit依頼にはLocal Agent QA結果、独立レビュー、単位案と全差分、実効review_flowと合意根拠を含める。完了報告は変更範囲、検証、未解決事項、単位案、commitした場合はSHA・単位照合・残差分・stash復元結果を含める。復帰不能時は理由を報告し、黙って別sessionに作り直さない。
+
+## 操作権限
+
+`review_flow.mode: auto` はClaudeの `--permission-mode auto` を意味しない。非対話起動では `--permission-mode dontAsk` を明示し、既存設定がbypassでも継承しない。model・effort・pluginsは保持し、操作許可は既存の個別allow設定と今回の範囲に限定する。`--permission-prompts none` は対話できないpromptを拒否として返すためであり、許可を付与しない。permission_denialsがあれば操作と必要な権限を報告し、既存の明示許可が対象を満たすか確認する。満たす場合だけ必要なSkill/Agentや対象を限定した `--allowedTools` を明示し、同じsessionへ明示的に再依頼する。新しい権限が必要ならCodexが人へ確認する。`--allowedTools` を使う場合も対象・操作に限定し、無条件の `Bash(*)`、bypassPermissions、dangerously-skip-permissionsを使わない。拒否を隠すsilent retryをしない。会話上の許可はCLIの権限チェックを消さない。
+
+CLI仕様の参照: [headless](https://code.claude.com/docs/en/headless)、[CLI reference](https://code.claude.com/docs/en/cli-reference)。利用版で必要なflagが非対応なら状態を報告して停止し、権限回避へ切り替えない。