@shinaps/skills 0.18.3 → 0.19.0

package/README.md

@@ -6,6 +6,8 @@ Shinaps AIの利用者向け開発ワークフロー。Claude CodeとCodexそれ
 
 共通スキルが持つのは判断手順。対象環境・必須検証・公開条件は、対象プロジェクトの `AGENTS.md` / `CLAUDE.md` と参照先、README、CI、既存スクリプトから読み取る。専用設定ファイルは必須にしない。
 
+例外として `linear` の開発進行とチーム設定の変更には、対象リポジトリの `.shinaps/linear.yaml` を必須にする。操作の継続的な許可と終了地点を会話から推測せず、合意した範囲だけを続けて進めるためである。設定はGit対象外の個人用ローカルファイルで、`.shinaps/.gitignore` の除外に含まれる。設定がなくてもIssueの読み取り・整理はできる。
+
 例えばPCブラウザのみのプロジェクトには対応ブラウザと確認コマンドを書く。iOSプロジェクトにはSimulatorと実機の使い分けを記す。スキルは一律の端末数やOS数を追加しない。既存の情報で決まらず結果を左右する条件だけ確認し、保存を了承された方針をプロジェクト側に残す。
 
 ## スキル
@@ -20,12 +22,15 @@ Shinaps AIの利用者向け開発ワークフロー。Claude CodeとCodexそれ
 | `refine` | Shinaps AIのruleと実ファイルを照合する |
 | `extract-rules` | PRレビューからruleを抽出する |
 | `simplify` | 目的から見直して不要な構造や手順を削る |
-| `commit` | 開始時に通常（推奨）・自律を確認し、検証できる単位へ分けてコミットする |
+| `commit` | 進め方（通常・自律）を `.shinaps/linear.yaml` の `commit_mode` か開始時の確認で決め、検証できる単位へ分けてコミットする |
 | `create-pr` | リポジトリの規約に合わせてPRを作成する |
 | `release` | 公開条件を確定し、対象バージョンの利用可能性を確認する |
+| `linear` | LinearのIssue整理から、Codexの進行・Bridge経由のClaudeの実装・QA・Cycle報告までを進める |
 
 Claude版の `dev` は実装後にレビュー・規約照合・簡素化の提案を並行して集め、全結果を専任verifierが検証し、同じ architect が採否を統合して実装担当へ修正を依頼する。実装後のレビューは最大2ラウンドで終了する。コミット・PR・リリースは依頼された場合だけ進む。`autonomous-commit-review` の役割は `commit` に統合した。個人用の別AI呼び出し・ブラウザ管理・ゴール管理・動画制作はこのpluginに含めない。
 
+`linear` は初版では利用者本人の環境向けで、Codexが進行とAgent QA、ClaudeがAI Terminal Bridge経由の依頼で実装を担当する。Bridge本体は同梱せず、導入済みのMCPとWebStormプラグインを使う。`SKILL.md` は担当ごとに両版で書き分け、共通の手順と書式は `references/` に置く。`references/` はClaude版を編集元としてCodex版へ同じ内容を複製し、テストで一致を確認する。
+
 ## Claude Code
 
 ```text
@@ -37,7 +42,7 @@ Claude版の `dev` は実装後にレビュー・規約照合・簡素化の提
 
 ## Codex
 
-Node.js 22以上と、`plugin marketplace add` / `plugin add` に対応したCodex CLIを使う。Claude Codeのインストールは不要。
+Node.js 22以上と、`plugin marketplace add` / `plugin add` に対応したCodex CLIを使う。Claude Codeのインストールは不要。ただし `linear` の開発進行には、Claude CodeとAI Terminal Bridgeが必要になる。
 
 導入・更新・削除:
 
@@ -139,7 +144,7 @@ codex mcp add shinaps-ai --url https://app.shinaps.ai/mcp
 codex mcp login shinaps-ai
 ```
 
-未登録の利用者は[Shinaps AI](https://app.shinaps.ai)でアカウントを作成する。未認証でもスキルの導入は完了できる。MCPが使えないときに照合済みと報告しない。`simplify`・`commit`・`create-pr`・`release` の基本手順はMCP接続を必須としない。
+未登録の利用者は[Shinaps AI](https://app.shinaps.ai)でアカウントを作成する。未認証でもスキルの導入は完了できる。MCPが使えないときに照合済みと報告しない。`simplify`・`commit`・`create-pr`・`release`・`linear` の基本手順はMCP接続を必須としない。
 
 ## Subagents (Claude: 16 / Codex: 13)
 
@@ -220,6 +225,8 @@ flowchart TD
 ```text
 .shinaps/
 ├── .gitignore             # *
+├── linear.yaml            # linear のプロジェクト設定（任意）
+├── linear/                # linear の補足（任意）
 └── work/
     ├── {日時}-{作業名}/
     ├── explorations/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shinaps/skills",
-  "version": "0.18.3",
+  "version": "0.19.0",
   "description": "Install Shinaps AI workflows and custom agents for Codex",
   "type": "module",
   "bin": {

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

@@ -1,7 +1,7 @@
 {
   "name": "shinaps",
-  "description": "Shinaps AIの開発ワークフロー。プロジェクトの指示から条件を読み、調査・設計・実装・簡素化・レビュー・コミット・PR・リリースを支援する11スキル。",
-  "version": "0.18.3",
+  "description": "Shinaps AIの開発ワークフロー。プロジェクトの指示から条件を読み、調査・設計・実装・簡素化・レビュー・コミット・PR・リリースとLinearでの開発進行を支援する12スキル。",
+  "version": "0.19.0",
   "author": {
     "name": "shinaps",
     "email": "ryuta@shinaps.jp"
@@ -17,6 +17,7 @@
     "planning",
     "code-review",
     "investigation",
-    "agents"
+    "agents",
+    "linear"
   ]
 }

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

@@ -25,6 +25,17 @@ color: red
 - **maintainability**: 命名・重複・複雑度・型・可読性
 - **rule**: rule カタログとの適合性 (rule 違反は必ず Critical タグを付ける)
 
+## 可読性のレビュー
+
+対象言語の基礎を知るジュニアが初めて読んでも、処理の目的・流れ・判断理由を追えるかを基準にする。レビュアー自身が解読できることを、読みやすさの根拠にしない。
+
+- 読み手が推測する意味、同時に覚える状態、理解のために往復する箇所を減らせるか確認する。命名・構造・抽象化・説明が理解に寄与しているかを、利用側も含めて判断する。
+- 短さ、分割数、特定の構文を目標にしない。意図を隠す圧縮も、処理のまとまりを失う細分化も避け、プロジェクトの慣用表現と規約を尊重する。
+- 正しさ・型の保証・既存の性能を維持する。可読性のために計算量・I/O・並列性・メモリ使用を悪化させない。性能上必要な複雑さは、その理由と使い方を理解しやすくする。影響が不明なら、同等と断言せず必要な検証を示す。
+- 指摘は、具体的に読み手が立ち止まる箇所、理解に必要な余分な推論、その負担を減らす修正案を示す。バグがなくても根拠のある保守上の負担は指摘できる。ほぼ同等の表現や好みだけの差は修正要求にしない。
+
+背景にある考え方は『リーダブルコード』の理解に要する時間と、『A Philosophy of Software Design』の複雑さ・認知負荷の削減。書籍の個別手法を一律の規約として適用しない。
+
 ## Confidence 閾値: 80
 
 **重要な指摘だけに絞る**。confidence 80 未満は報告しない (質より量を優先しない)。

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

@@ -1,6 +1,6 @@
 ---
 name: commit
-description: 許可された差分を依存順の小さなローカルコミットへ分割し、各単位を検証・レビューする。開始時に通常（推奨）・自律の進め方をユーザーに確認し、選択された範囲で実行する。
+description: 許可された差分を依存順の小さなローカルコミットへ分割し、各単位を検証・レビューする。進め方（通常・自律）はプロジェクト設定のcommit_modeか開始時の確認で決め、選択された範囲で実行する。
 ---
 
 ## 作業記録の保存先
@@ -19,12 +19,14 @@ description: 許可された差分を依存順の小さなローカルコミッ
 
 ## 範囲と進め方
 
-コミットはユーザーが明示した場合だけ行う。開始時に、今回の対象についてユーザー自身が進め方を選択済みか確認する。未選択なら、利用可能な入力ツール（なければ文章）で「今回のコミットはどちらで進めますか？」と一問だけ聞く。
+コミットは、ユーザーが明示した場合と、linear の開発進行でCodexからLocal Agent QAの合格後に対象を指定して依頼され、作業先リポジトリの `.shinaps/linear.yaml` の `permissions` に `commit` と `stage` がある場合だけ行う（条件の詳細はlinearの `references/configuration.md` の「許可」）。開始時に、今回の対象についてユーザー自身が進め方を選択済みか確認する。未選択なら、プロジェクトの `.shinaps/linear.yaml`（Git対象外のため、worktreeで実行する場合はメインの作業ツリー、`git worktree list` の先頭にある）に `commit_mode` が `normal` または `autonomous` で書かれていれば、それをこのプロジェクトでユーザーが合意済みの選択として使う。設定がない、または値がこの2つ以外なら、利用可能な入力ツール（なければ文章）で「今回のコミットはどちらで進めますか？」と一問だけ聞く。
 
 - **通常（推奨）**: 単位ごとに差分・理由・検証結果・メッセージを提示し、承認を得てからコミットする。
 - **自律**: 許可された対象を単位ごとに検証・レビューし、個別の承認を求めずコミットする。
 
-回答を受け取るまで作業を進めない。未回答や推奨選択肢の初期選択を承認と扱わない。「コミットして」「進めて」などの一般的な依頼や、エージェント自身の計画から自律モードを推測しない。今回の対象についてユーザーが通常・自律を明示済みならその選択を引き継ぎ、同じ確認を繰り返さない。過去の別対象での自律選択は引き継がない。
+質問した場合は、回答を受け取るまで作業を進めない。未回答や推奨選択肢の初期選択を承認と扱わない。「コミットして」「進めて」などの一般的な依頼や、エージェント自身の計画から自律モードを推測しない。今回の対象についてユーザーが通常・自律を明示済みならその選択を引き継ぎ、同じ確認を繰り返さない。過去の別対象での自律選択は引き継がない。例外は `commit_mode` として明示的に保存されたプロジェクト設定だけで、同じプロジェクトでの依頼の選択として使う。その場の明示的な指定は設定に優先する。
+
+`commit_mode` は進め方の既定値であり、コミットの許可ではない。設定があるだけでコミット・pushを始めず、人のレビュー済みと推測しない。`normal` は上記の通常モード（単位ごとに承認を得る）で、人が自分でgit操作をする工程を指すものではない。
 
 どちらも対象外変更、push、PR、公開、既存履歴の書き換えは含まない。
 

package/plugins/shinaps-claude/skills/linear/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: linear
+description: Codexが進行するLinearの開発で、AI Terminal Bridge経由の実装・修正依頼を受けて実行し、結果、許可されたコミット、人のレビュー・コミット完了をCodexへ報告する。利用者から明示的に依頼されたIssue整理も行う。
+---
+
+# Linearの開発でClaudeが行うこと
+
+初版では、Codexが進行・Agent QA・人への窓口を担当する。ClaudeはAI Terminal Bridge（以下Bridge）経由の依頼で、技術調査と実装・修正を担当する。担当を入れ替えない。
+
+## 再確認せず進める条件
+
+Codexから許可範囲と受入条件を伴う実装・修正の依頼をBridgeで受けたClaudeは、人へ着手を再確認せず、指定されたスキルで実行する。質問・相談・障害・完了はCodexへ返す。
+
+人のレビュー・コミット完了の報告をBridgeで受けたCodexは、報告の対象とGitの状態を照合し、一致すれば既存の許可の範囲で人へ再確認せず次の工程へ進む。
+
+条件の一覧と報告の項目は `references/workflow.md` にある。
+
+## 読む資料
+
+依頼を受けたら、[references/workflow.md](references/workflow.md) の「担当と窓口」「再確認せず進める条件」「Bridgeでの依頼と報告」を読む。依頼に添えられたプロジェクトの補足と参照先も読む。
+
+他の資料は次の場合だけ読む: 依頼で指示された場合、Issue整理を依頼された場合（[references/issue.md](references/issue.md)）、設定を読む必要がある場合（[references/configuration.md](references/configuration.md) の「設定の読み方」）。
+
+## 依頼を受けて実行する
+
+- 依頼の範囲・受入条件・Gitの作業ディレクトリ・ブランチ・既存差分・許可範囲を確認する。
+- 実装・修正には `shinaps:dev` を使う。`shinaps:dev` は内部で簡素化・規約照合・レビューを行うので、これらを別に起動しない。`shinaps:dev` を使えない場合は、独自の手順で代わりに実装せずCodexへ報告する。
+- `shinaps:dev` の委託（サブエージェントや別のCLI）は、依頼の許可範囲に `dev_delegation` が書かれている場合だけ使う。許可範囲に `dev_delegation` がない依頼では委託しない。worktreeの作成は含まない。
+- `shinaps:dev` が利用者に確認する場面（計画の判断、不明点、承認）では、人ではなくCodexへ相談する。Codexが既存の合意で答えた内容を人へ再確認しない。仕様・受入条件・許可範囲の変更が必要な場合は、Codexが人に確認する。
+- QAで見つかった不具合の修正依頼も同じ扱いにし、人の着手許可を改めて取らない。
+- 同じ作業ツリーをCodexや人と同時に編集しない。人や他のAIの変更を保持する。
+- 利用者本人がその場で明示的に依頼した場合と、作業先リポジトリの設定の `permissions` に `commit` と `stage` があり、CodexがLocal Agent QAの合格後にコミットを依頼した場合だけ、Claudeはコミットする。後者では、Claude自身が設定（[references/configuration.md](references/configuration.md) の「設定の読み方」）で、この2つの許可を確認する。実装完了の直後に先行してコミットしない。それ以外のCodexの依頼はコミットの許可にならない。コミットは `shinaps:commit` で行い、進め方は `commit_mode` か開始時の確認で決める。確認と承認の扱いは、[references/workflow.md](references/workflow.md) の「Bridgeでの依頼と報告」に従う。
+
+## 結果と人の対応を報告する
+
+- 完了の報告と、人のレビュー・コミット完了の報告に含める項目は、[references/workflow.md](references/workflow.md) の「Bridgeでの依頼と報告」に従う。
+- 人へ着手の確認やコミットの依頼をしない。人がClaudeへ直接伝えた指示や結果は保持し、Codexへ報告する。Gitにコミットがあるだけで、人のレビュー済みと報告しない。設定で人のレビューを省略した場合は、省略と報告する。
+
+## Codexの依頼なしで起動された場合
+
+- 利用者から明示的にIssueの整理を依頼された場合は、[references/issue.md](references/issue.md) に従って整理する。Issueの更新は、依頼で指定された範囲だけにする（設定の有無にかかわらない）。
+- 開発進行（実装からQAを経て終了地点までの進行）を依頼された場合、Claudeは進行役を兼ねない。作業先リポジトリの設定で `bridge_request` が許可され、BridgeでCodexのセッションを特定できる場合は、[references/workflow.md](references/workflow.md) の「開発進行の引き渡し」の項目を添えてCodexへ引き渡す。設定は [references/configuration.md](references/configuration.md) の「設定の読み方」に従って読む。許可や相手のセッションがない場合は、必要な準備（設定、Codexセッションの起動、Bridgeの導入）を利用者へ案内する。

package/plugins/shinaps-claude/skills/linear/references/configuration.md

@@ -0,0 +1,152 @@
+# プロジェクト設定
+
+設定は、運用上の決定と既存資料への参照を持つ。手順の全文は書かない。秘密値を保存しない。設定はAIが読む文書であり、専用のプログラムで検査しない。
+
+## 配置
+
+```text
+.shinaps/
+  .gitignore            # *
+  linear.yaml           # 対象・工程・許可・終了地点・参照先・報告
+  linear/
+    instructions.md     # プロジェクト固有の指示（任意）
+    references/         # 必要な場合だけ分ける詳細資料（任意）
+```
+
+- 設定を置いたリポジトリが対象のリポジトリになる。複数のリポジトリが、それぞれの設定で同じworkspace・team・projectを指してよい。設定はメインの作業ツリーに置く。
+- 保存の前に `.shinaps/.gitignore` を確認する。なければ内容 `*` と改行で作成する。既存なら内容を保持し、不足するときだけ `*` を追記する。`git check-ignore .shinaps/linear.yaml` でGitの対象外であることを確認する。追跡済みのファイルは追跡を解除せず、保存の前に扱いを利用者と決める。
+- 必須でない空ファイルを作らない。補足にSKILL.mdや独立した呼び出し名を置かない。READMEなどが正本の内容はリンクで参照し、コピーしない。
+
+## 設定の読み方
+
+- 実行開始時と再開時に、作業先リポジトリの `.shinaps/linear.yaml` と、あれば `.shinaps/linear/instructions.md` を読む。`.shinaps/linear/references/` は、担当する工程に必要なものだけ読む。
+- 設定はGitの対象外なのでworktreeには存在しない。作業がworktreeで行われる場合も、メインの作業ツリー（`git worktree list` の先頭）から読む。
+- 補足ファイルは追加の条件と手順を表す。設定の決定（対象・許可・終了地点・工程の対応）と、人の完了・QAの証拠の要件は変えない。補足と設定が矛盾したら、設定に従って止め、どちらを直すか確認する。
+- 不足や矛盾があれば、影響する工程の開始前に止めて一問ずつ確認する。影響しない工程は続ける。許可の追加やステータスの新設を推測で補わない。
+- 終了地点は操作の許可を兼ねない。設定は、利用中のツールの権限や利用者の明示的な停止・撤回を上書きしない。
+
+## 項目
+
+| キー | 内容 | 未記載のとき |
+| --- | --- | --- |
+| `target.workspace` | Linearのworkspace | 開発進行を始めない |
+| `target.team` | チームのキー（例 `SHINAPS`） | 開発進行を始めない |
+| `target.project` | 使うprojectのURL。projectを使わない運用では `null` | 未決として扱い、project未使用とは推測しない。projectに依存する操作の前で止める |
+| `team_settings` | `existing_only`（既存の定義に合わせ、変更しない）または `manage_on_setup`（初期設定・設定変更のときだけ変更案を示し、合意後に整備できる） | `existing_only` |
+| `statuses` | 工程キーと待ち状態の `human_input` から、実在するステータス名への対応。複数のキーに同じステータスを指定できる | そのキーの状態更新の前で止める |
+| `stop_after` | 終了地点（下の「終了地点」） | 開発進行を始めない |
+| `permissions` | 継続的に許可した操作の一覧（下の「許可」） | 何も許可していない |
+| `references` | `specifications`・`validation`・`environments`・`deployment`・`publication` ごとに、既存資料のパスまたはURLの一覧 | 各リポジトリのAGENTS.md・README・CIから読む |
+| `cycle_report` | Cycle報告の設定（下の「Cycle報告」） | Cycle報告を書き込まない |
+| `commit_mode` | `shinaps:commit` でコミットするときの進め方。`normal`（単位ごとに承認を得る）または `autonomous`（個別の承認なしで単位ごとに検証してコミットする） | `shinaps:commit` が開始時に一問確認する。値が2つ以外のときも同じ |
+| `human_code_review` | 人のコードレビューの要否。`required`（人がレビューする）または `skip`（人のレビューを行わない） | `required`。値が2つ以外のときも同じ |
+
+- `commit_mode` は進め方の既定値であり、コミットの許可ではない。コミットは利用者の明示的な依頼、または `permissions` の `commit`（条件は下の「許可」）があるときだけ行う。`commit_mode` があるだけではコミット・pushを始めず、人のレビュー済みと推測しない。その場の明示的な指定は設定に優先する。`normal` は人が自分でgit操作をする工程（`code_review`）とは別のもの。
+- `human_code_review: skip` は人のレビューの工程だけを省く。`shinaps:dev` 内のレビュー、Agent QA、必要なHuman QAは省かない。省略は、人のレビュー済みとして記録しない。`human_code_review`・`commit`・`stage`・`commit_mode` は互いに独立しており、一つから他を推測しない。
+- 工程キーは [workflow.md](workflow.md) の工程表と同じ。`statuses` の値はチームに実在する正確な名前にする。操作時はLinearから取得した状態のIDを使う。対応が曖昧・欠落・実物と不一致なら、その対応に依存する更新を止める。ステータスを自動で新設しない。
+- `team_settings: manage_on_setup` の場合も、通常実行ではチーム設定を変更しない。
+
+## 終了地点
+
+初期設定ではこの一覧を示して選んでもらう。
+
+| `stop_after` | 止まる地点 |
+| --- | --- |
+| `pre_push_qa` | `code_review` の工程を終えた後、push前の最終Agent QAが合格し、記録した時点 |
+| `pr_created` | 必須の検証と許可されたpush・PR作成を終え、IssueとPRの相互リンクを確認した時点。Staging QAが未実施なら残項目として記録する |
+| `issue_done` | Issueの必須受入条件をすべて満たし、Doneにした時点 |
+
+- 終了地点の工程がそのIssueにない場合（Git変更がない作業など）の扱いは、[workflow.md](workflow.md) の「工程とステータス」に従う。
+- 終了地点は到達点だけを決める。途中の操作は `permissions` が決める。許可のない操作（例 `merge`）がある場合は、その操作の前で許可を確認する。これは許可待ちであり、終了地点への到達ではない。Cycle全体を任された場合も、許可待ちのIssueは終了地点に達したものとして扱わない。
+
+## 許可
+
+| 値 | 許可する操作 |
+| --- | --- |
+| `issue_update` | 対象のteam・projectの中で、利用者が任せたIssue・Cycleの範囲に対する運用上の更新（本文・コメント・状態・依存・Linearへの添付、整理で必要になったIssueの作成・分割）。チーム設定の変更、未合意の範囲・期限の変更、Cycle外への進行、Issueの削除、外部への送信を含めない |
+| `bridge_request` | BridgeによるCodexからClaudeへの実装・修正の依頼と、ClaudeからCodexへの開発進行の引き渡し |
+| `stage` | レビュー・コミットの対象差分だけをステージする |
+| `commit` | 対象Issueの差分を、Local Agent QAの合格と `human_code_review` に従った工程の後に、`shinaps:commit` でローカルにコミットする。AIのコミットには `stage` の許可も併せて必要。push・PR・履歴の書き換え、人のレビューの省略を含めない |
+| `push` | 対象Issueの作業ブランチの通常のpush |
+| `pr_create` | 対象IssueのPRの作成と更新 |
+| `merge` | 必要なQA・承認が揃った対象PRのマージと、元のブランチへ戻る操作 |
+| `deploy:<環境>` | 指定した環境への配備・配布（例 `deploy:staging`） |
+| `publish:<操作>` | 一般公開やストアへの提出など、指定した公開操作（例 `publish:app_store_submit`） |
+| `dev_delegation` | Claudeが `shinaps:dev` の中で委託（サブエージェント・別のCLI）を使う。worktreeの作成は含まない |
+| `evidence:<保存先>` | Linear以外の指定した保存先へQA素材を保存する（LinearのIssueへの添付は `issue_update` に含む） |
+
+- 開発進行には `issue_update` と `bridge_request` が必要である。初期設定では、この2つと `stage`・`dev_delegation` を開発進行の標準の組として提案する。設定があるだけでは、どの許可も得ない。必要な許可がない設定では開発進行を始めず、不足している許可を示す。
+- 一つの操作が別の操作を伴う場合は、伴う操作の許可も必要とする（マージで本番へ自動配備される場合は `merge` と `deploy:production`）。
+- 次の操作は一覧に含めず、常にその場で確認する: force-push、履歴の書き換え、ブランチの削除、チーム設定の変更。
+- 設定の許可は、今回の依頼で任されたIssue・Cycleの範囲を広げない。
+
+## Cycle報告
+
+| サブキー | 内容 |
+| --- | --- |
+| `qa_scope` | 全体QAの対象となる環境・端末の一覧 |
+| `destination` | 報告本文の保存先（例 `linear_cycle_document`） |
+| `index` | 索引のURL、または `null` |
+| `audience` | 読み手 |
+| `format` | 既存の書式や直近の報告への参照（任意） |
+
+書き込むのは `destination` と `index` だけ。記載のない報告先や送信先には、補足ファイルに書かれていても書き込まない。
+
+## 設定例
+
+shinaps-skills側の例。shinaps-aiも、自分のリポジトリの設定で同じprojectを指す。
+
+```yaml
+# 設定を置いたこのリポジトリを作業先とするIssueに適用する。
+target:
+  workspace: shinaps
+  team: SHINAPS
+  project: https://linear.app/shinaps/project/shinaps-ai-76ed13db8314 # projectを使わない場合は null
+team_settings: existing_only
+# ステータス名は形式の例。初期設定でチームの実際の一覧と照合して決める。
+statuses:
+  todo: Todo
+  refinement: In Progress
+  ready: Todo
+  coding: In Progress
+  local_agent_qa: In Progress
+  code_review: In Review
+  post_commit: In Review
+  human_input: In Progress
+  done: Done
+stop_after: pre_push_qa
+permissions:
+  - issue_update
+  - bridge_request
+  - stage
+  - dev_delegation
+references:
+  validation:
+    - README.md#開発と配布
+    - package.json
+  publication:
+    - README.md#CIとnpm自動公開
+```
+
+この例は `stop_after: pre_push_qa` なので、`post_commit` より後の工程の対応を書いていない。
+
+## 初期設定
+
+Codexが行う。
+
+1. アカウント、workspace、team、projectと、チームのステータス一覧・既存の運用をLinearから読む。
+2. 作業先リポジトリのAGENTS.md・CLAUDE.md・README・CI・検証や配備のスクリプトを読み、`references` の候補を決める。
+3. 設定案を一つ作る。チーム設定を管理できる場合だけ、FamilyStayを基にした工程の分離（[workflow.md](workflow.md) の工程表に対応するステータス）を変更案として示す。利用者のプロジェクトらしいという推測で `manage_on_setup` にしない。
+4. 既存の情報で決まらない運用上の決定（`stop_after`、`permissions`（`commit` を含む）、`human_code_review`、`team_settings`、Cycle報告、`commit_mode`）だけを一問ずつ確認する。終了地点は上の一覧から選んでもらう。
+5. 合意した内容を保存し、読み直して確認する。
+6. Linearのチーム設定の変更は、ローカル設定の保存とは別に扱う。対象チームと変更差分（追加・改名するステータスと順序）を示し、合意を得てから反映して読み戻す。反映後に `statuses` を実物に合わせて確定する。
+
+## 設定変更
+
+初期設定と同じ手順で、既存の設定との差分を示して合意を得る。許可の追加を推測で補わない。
+
+## 補足ファイルに書くもの
+
+`instructions.md` には、QA固有の注意（端末・ブラウザ・テストアカウントの取得方法への参照）、版の照合に使うコマンド、報告の文体・見せ方、関係者への依頼方法、環境の現状を書く。共通の手順は複製しない。
+
+CodexはClaudeへの依頼に、関係する部分と参照先を添える。

package/plugins/shinaps-claude/skills/linear/references/cycle-report.md

@@ -0,0 +1,53 @@
+# Cycle完了QAと成果報告
+
+Codexが実行する。Cycle全体を任され、報告まで許可されている場合は、報告用Issue以外の対象Issue（文書・運用のIssueを含む）がすべてDoneであることを確認して続ける。Issue単位の依頼では自動で開始せず、全件完了を案内する。報告だけを明示的に依頼された場合も開始できる。設定の `cycle_report` がなければ書き込まず、必要な設定を案内する。
+
+対象のCycle IDとIssue一覧を記録する。日付の到来・自動繰り越し・Cycleの移動・取消を、全件完了の根拠にしない。取消・持ち越し・対象外への変更は、成果と区別して記録する。履歴を取得できない場合は不明と書く。
+
+## 手順
+
+| 順序 | 行動と完了条件 |
+| --- | --- |
+| 対象を確定 | 既存の報告用Issueと報告書を再利用し、Cycleと対象Issueの受入条件・結果を整理する |
+| 全体QA | 設定の `qa_scope` の環境・端末で対象版を確認し、Cycleの変更を合わせた主要導線を検証する。再利用できる検証証拠は活用し、不足する結合・画面操作を補う |
+| 素材を記録 | 対象画面・端末のスクショ、動きの説明に必要な短い動画を保存し、対象版・環境と対応づける。秘密値や実利用者の情報を含めない |
+| 報告を作成 | 利用者・運営にとって何ができるようになったか、確認結果、制限、次のCycleの実際の計画、必要な人の対応を説明する |
+| 保存と確認 | 設定された保存先へ書き込み、本文・画像・リンクの表示を確認する。索引が指定されていればリンクを更新して読み戻す |
+
+全体QAの記録には [qa.md](qa.md) のQAコメントの書式を使い、報告用Issueへ記録する。
+
+## 報告の書き方
+
+- 詳細な検証証拠は報告用Issueへ集め、成果報告には読み手に必要な要約・代表画像・詳細へのリンクを置く。仕様決定・実装済み・公開済みを混同しない。
+- 次のCycleの内容は、実際の登録Issue・依存・状態を確認して書く。未登録の予定を確定事項として書かない。
+- 報告本文へテスト件数やコミット一覧を転載して作業量を説明せず、成果と確認できたことを伝える。代表素材は証拠と対象版を共有し、既存の素材が古い場合は現在の対象で取り直す。
+- 直近の報告と利用者の修正を参考にし、設定の `audience`・`format` と補足ファイルに合わせる。
+
+## 共通Cycle報告テンプレート
+
+```markdown
+## <Cycle名> 成果報告
+対象期間・Cycleリンク・報告日
+
+## 今回できるようになったこと
+利用者・運営への効果を短く説明。
+
+## 主な成果
+成果ごとの説明と代表スクショ、必要な短い動画。
+仕様決定・実装済み・公開済みを区別。
+
+## 動作確認と残る制限
+どの環境・端末で何を確認したか。未確認事項と詳細QAコメントへのリンク。
+
+## 次のCycle
+実際の登録Issueに基づく予定・依存・次に実現すること。
+
+## お願いしたいこと
+必要な人の対応とIssueリンク。なければ省略。
+```
+
+## 未完了と再実行
+
+- 未確認事項やHuman QA待ちがあっても途中報告は保存できるが、全体QAの合格や報告用IssueのDoneにはしない。不具合は修正Issueへ引き継ぎ、修正後に再検証する。
+- 再実行では同じCycleの記録を更新し、報告を重複して作成しない。保存・添付・索引の更新の結果が不明なら現状を読み直し、不足する処理だけを行う。
+- 報告先がLinearのドキュメントの場合、独立したドキュメントを増やさない運用のチームでも、設定されたCycle報告は例外として作成する。

package/plugins/shinaps-claude/skills/linear/references/issue.md

@@ -0,0 +1,66 @@
+# Issueの整理と記録
+
+本文は最新の要件と結論を保ち、古い案や相反する追記を残さない。現在の工程・次の担当・お願いを書く欄（移行元のテンプレートにある「現在地」など）は本文に設けず、整理・更新するIssueにあれば内容をステータスとコメントへ移して欄を除く。工程はステータスで表す。残作業・待ち理由・次の担当は、QAコメントか待機時のコメントで表す。チームに既存の本文規約があればその形式を尊重し、下のテンプレートの各欄の役割を対応づける。
+
+共通ルールはスキルとリポジトリ、製品仕様はその正本、個別Issueの判断と結果はIssueに置く。共通手順をIssueへ転載しない。
+
+## 要件を整理する手順
+
+1. 正しいアカウント・workspace・teamで、本文・親子・依存・Cycle・ラベル・状態・コメントを読む。一覧は最後のページまで取得する。関連仕様の正本・実装・会話の合意と照合する。
+2. 一つのIssueを、独立してレビュー・受入できる到達点に絞る。分割が必要なら既存Issueを優先して責務を移し、引継ぎ元と引継ぎ先、依存を更新する。元の要件ID・重要な判断・検証証拠を失わない。
+3. 確定・暫定・未決を区別する。既存の根拠で解消できる曖昧さや重複は自分で整理する。利用者の判断が必要な仕様変更や矛盾だけを一問ずつ相談する。未決の要件を推測で確定しない。
+4. 受入条件は場合の列挙ではなく、満たす性質で書く。Agent QAとHuman QAに分ける。
+5. 着手の前提と最終受入の前提を区別し、実際のブロッカーだけを依存に登録する。
+6. 更新後に本文・状態・ラベル・依存を読み戻す。失敗や結果不明なら現状を確認し、未反映分だけ再試行する。
+
+## Readyの条件
+
+目的・範囲・受入条件が明確で、自分たちの作業を依存順に進めれば着手できる。前工程の実装待ちだけを理由に未整理へ戻さない。Readyの後に前提が崩れたら、理由を記録して、整理中または該当する待ち状態へ戻す。
+
+## Cycle・期限・見積もり
+
+| 作業 | 作成時のCycle |
+| --- | --- |
+| すぐ着手する作業 | 現在のCycle |
+| 今後実施する作業 | 見積もり・依存・期限・作業量から決めた予定のCycle |
+| 時期未定の案 | Backlogに置き、Cycleを設定しない |
+| 取りまとめだけの親Issue | CycleとEstimateを付けない |
+
+- 期限は「いつまでに必要か」、Cycleは「いつ取り組むか」を表す。前提作業を後続のCycleに置かない。時期未定の案に予定を作らない。見積もり・期限・Cycle範囲の変更は、既存の合意または明示的な依頼の範囲でだけ行う。
+- 依存Issueを作るのは、独立した担当・完了条件が必要な作業だけ。既存のIssueを優先する。機能専用ならサブIssue、共有の準備なら独立したIssueにする。その場の質問ごとにIssueを作らない。
+
+## 共通Issueテンプレート
+
+```markdown
+## 目的
+このIssueで実現する到達点と利用者・運営にとっての効果。
+
+## 変更内容・レビュー観点
+変更前と変更後、変更理由。仕様・デザインの根拠と対応する実装箇所へのリンク。
+UIがある場合は代表スクショ、動きの説明には短い動画を添える。
+
+## 受入条件
+### Agent QA
+- [ ] 満たす性質 — 確認方法・工程・環境
+### Human QA
+- [ ] 人が確認する性質 — AIだけでは確認できない理由・環境
+（不要なら「不要。」だけを記載）
+
+## 検証状況
+最新の合否・未確認事項と、詳細なQAコメントへのリンク。
+
+## 対象・範囲外
+作業先のリポジトリ名、担当範囲、前提、依存するIssue、引継ぎ先。
+
+## 決定事項・参照
+判断と理由、仕様の正本と要件ID、未決事項。
+```
+
+- 「対象・範囲外」の作業先のリポジトリ名は、同じprojectを複数のリポジトリが使うときに、適用する設定を決めるために使う。ローカルの絶対パスは書かない。
+- Linear側のテンプレート設定を変えることは別の設定操作である。本文への適用では変更しない。
+
+## 書き方
+
+- 任意の欄は必要なときだけ使い、空欄や定型文で埋めない。Human QAが不要なら「不要。」だけを書く。
+- 一つの欄で一つの疑問に答え、同じ情報を複数の欄に書かない。長いログを本文へ貼らない。途中の議論はコメントへ残し、採用した結論を本文へ統合する。
+- 「変更内容・レビュー観点」では、変更前と変更後、根拠、対応する実装箇所、確認してほしい点を結ぶ。UIにはデザインと実装後のスクショ、操作や遷移には短い動画、APIや内部処理には入出力の例を添える。

package/plugins/shinaps-claude/skills/linear/references/qa.md

@@ -0,0 +1,46 @@
+# QAと証拠
+
+Agent QAは、自動テスト・API・ブラウザ・管理画面・Simulatorなど、AIが操作と結果を確認できるもの。Human QAは、人の判断や実機でしか確認できない条件。普通の画面に一律のHuman QAを設けない。不要なら「不要」と記録する。
+
+QAはPRごとに完結させ、複数のPRをまとめるために人の確認を遅らせない。環境ごとに、Agent QAと必要なHuman QAを分ける。Staging QAが必要な公開変更は、本番でも環境差と主要導線を確認する。存在しない環境を合格扱いにしない。
+
+自動検証のコマンドと必須対象は、各プロジェクトの規約・CI・スクリプト（設定の `references.validation`）を正本にする。原因調査の絞り込み実行を、必須検証全体の合格に読み替えない。
+
+## 証拠の要件
+
+- 確認日、差分またはコミット、環境、実行内容、期待と実際、未確認事項を含める。
+- QAの対象版と実際に動いている版が一致することを、QAの開始前と記録の直前に確認する。マージや配備で版が変わったら、以前の合格を使わず、影響する項目を再確認する。具体的な照合コマンドはプロジェクトの補足に置く。
+- Simulator、実機、配備、一般公開を区別する。失敗・取消と、意図せず実行されなかったテストや確認項目を合格にしない。チェックは、対応する性質を確認した証拠がある場合だけ付ける。
+- 秘密値・Cookie・個人情報を、設定・Issue・証拠に残さない。
+
+## QAコメントの書式と更新
+
+Codexは各工程のQA結果を、対応するIssueのコメントへ残す。初回と再検証、Local・Staging・Productionを区別する。
+
+```markdown
+### <工程・環境> Agent QA — <確認日>
+対象: <Issue・差分またはコミットSHA>
+環境: <URL・配備版・端末／ブラウザ・ビルド番号>
+
+| 受入条件 | 確認方法・期待結果 | 実際の結果 | 判定・証拠 |
+| --- | --- | --- | --- |
+| <条件または要件ID> | <コマンド・操作と期待> | <観測した結果> | <合格／不合格／未確認／対象外と理由、画像・動画・ログへのリンク> |
+
+残項目・次の対応: <誰が何を行うか、再開条件>
+再検証の場合: <前回結果へのリンク、修正内容と今回の対象>
+```
+
+- 失敗や中断も記録し、成功の結果で過去の失敗を消さない。送信の再試行では重複したコメントを作らない。実際に再検証した場合は、新しい対象と結果を区別して記録する。長いログは必要な箇所を要約して証拠へリンクする。
+- 本文の「検証状況」から最新のQAコメントへ辿れるようにし、コメント・添付・リンクを読み戻して確認する。
+- 人のQAの結果は本人の報告に基づいて対象と結果を記録し、AIが代わりに合格を決めない。
+
+## スクショ・動画
+
+- 画面を変更・検証した場合は、結果を説明できる代表スクショを記録する。遷移・入力・アニメーションなど静止画だけでは判断できない挙動は、操作と結果が分かる短い動画で示す。既存の対象版の素材を再利用できる場合は重複して撮影しない。画面を持たない変更はAPI・ログ等で示し、無関係な画像や動画を求めない。
+- 素材には画面名、対象版、環境、端末または画面幅・ブラウザ、確認した内容を添える。レビューで比較が必要な場合は、仕様・デザインや変更前の状態と対応づける。スクショだけで操作の成功を証明せず、期待結果と実際の結果も記録する。
+- 保存先は、Linearの添付、設定の `evidence:<保存先>` で許可された先、または利用者がその場で許可した先とする。Issue・QAコメント・Cycle報告から閲覧できるようにし、ローカルの一時パスだけで引き渡しを完了しない。
+- 画像の表示、動画の再生、リンク先へのアクセスを確認してから、共有済みとして扱う。埋め込みが使えない場合は説明付きのリンクを使う。保存・撮影ができなければ不足と理由を記録し、取得済みとは扱わない。公開設定を緩めて共有せず、秘密値・Cookie・実利用者の情報を含まない素材を使う。
+
+## Human QAの引き渡し
+
+依頼の前に、対象環境・URLまたはビルド、テストデータ、操作・期待結果・既知の制限をIssueに揃える。対象環境への配備の成功と基本動作を確認してから依頼する。確認の後に対象が変わったら、影響する項目を再確認する。