@shinaps/skills 0.18.3 → 0.20.0

package/plugins/shinaps-codex/skills/linear/references/workflow.md

@@ -0,0 +1,155 @@
+# 担当と工程
+
+## 担当と窓口
+
+| 担当 | 責務 |
+| --- | --- |
+| Codex | Issueの作成・整理、仕様相談、Ready判定、依存・Cycle管理、進行判断、Bridgeでの依頼、Local・Staging・ProductionのAgent QA、許可されたPR・配備等の運用、結果の記録、人への依頼 |
+| Claude | Codexの指示に基づく技術調査、`shinaps:dev` による実装・自動テスト・簡素化・セルフレビュー、QA指摘の修正、成果と人の対応結果の報告。実装を伴わない文書整理は、作業先リポジトリの規約に従い `shinaps:dev` の対象外にできる。スキル・コードの変更は文書の形でも実装として `shinaps:dev` を使う |
+| 人 | 未合意の仕様・権限の判断、設定で必要なコードレビュー・必要な修正、AIに許可していないコミット、本人の操作が必要な認証等、必要なHuman QA |
+
+人への質問と依頼はCodexが窓口になる。Claudeは人へ着手確認やコミット依頼をしない。人がClaudeへ直接伝えた指示や結果は、Claudeが保持してCodexへ報告する。
+
+CodexはQAで見つけた不具合を自分で実装修正せず、再現条件と証拠をClaudeへ返す。同じ作業ツリーを同時に編集せず、人や他のAIの変更を保持する。
+
+Linear MCPで扱えない画面操作（添付、並べ替え、Cycleへの紐付けなど）は、Codexが利用可能なブラウザで行う。MCPが対応していないという理由だけで人へ回さない。人の認証や権限が必要な場合だけ人へ依頼する。
+
+## 再確認せず進める条件
+
+| 状況 | 必要な行動 |
+| --- | --- |
+| Codexから許可範囲と受入条件を伴う実装・修正の依頼を受けた | Claudeは人へ着手を再確認せず、指定されたスキルで実行する |
+| `shinaps:dev` の中で計画上の判断が必要になった | ClaudeはCodexへ相談する。Codexは既存の合意で判断できれば回答し、人へ再承認を求めない |
+| QAで受入条件の範囲内の不具合が見つかった | CodexがClaudeへ修正を依頼し、Claudeは人の着手許可を改めて取らずに修正する。Codexが再検証する |
+| Claudeが人のレビュー・コミット完了をBridgeで報告した | Codexは人に同じ事実を聞き直さず、報告の対象とGitの状態を照合して次の工程へ進む |
+| 次の操作の継続的な許可があり、必要な工程の結果が揃った | Codexは「進めてもよいか」を再質問せずに実行する |
+| Cycle全体を任され、対象Issueが設定された終了地点に達した | CodexはCycleを読み直し、依存・優先順位から次の実行可能なIssueを選んで続ける |
+
+「自律的に進める」とだけ書かず、この表と具体的な許可範囲を各Bridge依頼に書く。
+
+## 人に確認する条件
+
+目的・仕様・受入条件・許可範囲の変更、設定で必要な未実施の人のレビュー、Human QA、本人にしかできない操作、根拠を確認しても解消できない報告の矛盾は、人に確認する。経過時間、無回答、Bridgeの送信成功や受領通知を、人の完了や合格として扱わない。
+
+## 工程とステータス
+
+| 工程キー | 工程 | 内容・次へ進む条件 |
+| --- | --- | --- |
+| `todo` | Todo | 未着手のIssue |
+| `refinement` | 仕様整理中 | 目的・仕様・範囲・依存・受入条件を整理する |
+| `ready` | Ready | 自分たちの作業を依存順に進めれば着手できる。開始時に、必要な前工程の成果を再確認する |
+| `coding` | Coding | Claudeが実装・自動検証・簡素化・セルフレビューを完了し、差分と結果を渡す |
+| `local_agent_qa` | Local Agent QA | Codexが受入条件を検証する。不合格なら `coding` へ戻す |
+| `code_review` | Code Review（人のレビューまたは省略の記録・コミット） | `human_code_review: required` では人がレビュー・修正する。`skip` では人へのレビュー依頼も待ちも作らず、省略を記録する。コミットは、Local Agent QAの合格後（`required` では人のレビュー完了の確認後）に、`commit` と `stage` の許可があればCodexの依頼でClaudeが行い、なければ人が行う。対象コミットと、人の完了通知または省略の記録を照合する。`document_only_changes: ai_commit` があり、対象差分が文書だけの変更に当たる場合は、下の箇条に従う |
+| `post_commit` | コミット後の検証・PR準備 | 設定に従って、push前の最終Agent QA、必須検証、許可されたpush・PR作成を行う |
+| `staging_agent_qa` | Staging Agent QA | 配備されたPR候補版をCodexが検証する |
+| `staging_human_qa` | Staging Human QA | そのPRで必要な人の確認。不要なら理由を記録して省略する |
+| `release` | マージ・本番配備・公開 | 必要なQA・承認と操作の許可が揃ってから実行する |
+| `production_agent_qa` | Production Agent QA | 公開対象の版・環境差・主要導線をCodexが検証する |
+| `production_human_qa` | Production Human QA | 本番で必要な人の確認。不要なら省略する |
+| `done` | Done | そのIssueの必須受入条件を満たした状態 |
+
+- 工程名を使うことは、チーム設定を変更する許可ではない。専用のステータスがないQA工程は進行中の状態に対応づけ、工程・待ち理由・再開条件をコメントへ記録する。`done` と途中の工程を同じ完了状態に対応づけない。
+- QAステータスへの移動とQAの合格を区別する。終了地点への到達とIssueのDoneを区別する。
+- 工程を行うかどうかは、Issueの受入条件と終了地点で決める。Issueに適用されない工程は通らない（配備しない変更の環境配備・環境QA、Git変更がない作業のレビュー・コミット・PRなど）。省略した工程は理由を記録する。工程の省略を理由に、必要なQAや未達の受入条件を省かない。
+- 終了地点の工程がそのIssueにない場合は、適用される最後の必要工程まで進めて止まる。そのとき必須受入条件をすべて満たしていればDoneにする。満たしていなければ、残る条件を記録してDoneにしない（push前QAで止める運用で、本番公開の受入条件が残るIssueなど）。
+- 人がレビュー中に修正した場合は `code_review` を続ける。AIへ追加実装を依頼する場合は、範囲と受入条件をIssueで更新してから `coding` へ戻す。
+- Human QAが新たに必要になった場合は、理由と具体的な残項目をIssueに記録して利用者に相談する。
+- プロジェクトの規約や補足の記述だけでは、AIのコミットの許可として扱わない。文書だけの変更であることを理由に人のレビューを省きAIがコミットする例外は、設定に `document_only_changes: ai_commit` があるときだけ適用する。適用しない場合は、通常のレビュー・コミットの条件（`human_code_review` と [configuration.md](configuration.md) の「許可」の `commit`）に従う。
+- `human_code_review: skip`、または下の文書だけの変更の例外で人のレビューを行わなかった場合、Codexは `code_review` の工程で、省略と、実施した確認（`shinaps:dev` 内のレビュー、Local Agent QA）への参照をIssueへ記録する。1行目には省略の根拠になった設定を書き、文書だけの変更の例外では判定の記録へのリンクを添える。
+
+  ```text
+  人のコードレビュー: 省略（作業先リポジトリの設定 <human_code_review: skip または document_only_changes: ai_commit>。文書だけの変更の例外では「判定: <Local Agent QAのコメントへのリンク>」を続ける）
+  実施した確認: shinaps:dev 内のレビュー（使った場合。Claudeの完了報告 <コメントへのリンク>）、Local Agent QA（<記録へのリンク>）
+  コミット: <SHA>（<実際の実施者と方法>）
+  ```
+
+- `document_only_changes: ai_commit` がある場合は、次のとおり進める（文書だけの変更の定義は [configuration.md](configuration.md) の「項目」）。
+  - Local Agent QAで、Codexは受入条件の検証に加え、対象差分の全体が文書だけの変更に当たるかを判定し、範囲と理由をQAコメントに一度だけ記録する。
+  - 当たる場合、`required` でも人へのレビュー依頼も待ちも作らない。CodexはClaudeへコミットを依頼し、依頼に判定の記録へのリンクを添える。
+  - Claudeは、設定にこのキーと `stage` の許可があること、依頼された対象差分が、作業ツリー上の同じ対象（ファイルと内容）の差分と一致することを確認してから `shinaps:commit` でコミットする。違えばコミットせずCodexへ返す。差分の性質は判定し直さない。
+  - コミット後、Codexはコミットの内容が判定した差分と一致し、対象作業の未コミット変更が残らないことを照合する。一致しなければ次の工程へ進まず、SHA・判定した差分・実際の差分の違いをIssueに記録して人に確認する。履歴の書き換えはその場で確認する。
+  - 判定の後に対象差分が変わったら、新しい対象で判定とQAをやり直す。
+  - 照合の後に、上の省略の記録をIssueへ書く。
+  - 当たらない場合は、通常の `code_review`（`human_code_review` と `commit` に従う）のまま進める。
+
+## 待ち状態
+
+その場の質問と、本人が対応できるレビュー・作業の待ちは、元の工程を維持する。外部の資料提供・権限付与・審査など、自分たちでは解消できない対応の待ちだけを `human_input` で表す。別Issueの待ちは依存関係、Claudeの作業待ちはAI間の待機として扱う。
+
+待つときは、必要な対応・担当・再開条件・戻る工程をIssueのコメントへ記録する。人の回答や対応完了を確認したら続け、同じ依頼を繰り返さない。
+
+Linearの工程のステータスと、Codexのゴールの状態は別に扱う。人のレビュー・コミット、Human QA、その場の回答を待つ間、Linearは進行中の工程を維持し、Codexはゴールを作業中のまま利用可能な待機手段で待つ。人の応答待ちという理由だけで、自発的にゴールをblocked・一時停止・完了へ切り替えない。人からの通知を受けたら、対象を照合してから再開する。実行環境の上位の指示やゴール機能の制約はこのスキルで上書きできないため、環境が許す範囲で作業中を維持し、環境が状態の変更を要求する場合はその理由を利用者に説明する。制約を迂回する操作や、代わりの新しいゴールの作成はしない。
+
+## Bridgeでの依頼と報告
+
+AI Terminal Bridge（以下Bridge）の本体は同梱しない。導入済みのMCPとWebStormプラグインを使う。開発進行には必須で、Issue整理だけなら不要。
+
+送信前に `list_sessions` で、相手の `project_path`、完全な `session_id`、受信の可否を確認する。`session_id` は保存せず、依頼のたびに一覧から取得する。`project_path` はIDEのプロジェクトのルートで、作業ディレクトリと一致するとは限らない。依頼と報告には、Gitの作業ディレクトリを別に書く。
+
+| 依頼・報告 | 含めるもの |
+| --- | --- |
+| 実装・修正の依頼（CodexからClaude） | Issueリンク、範囲・受入条件、Gitの作業ディレクトリ・ブランチ・既存差分、許可範囲（`dev_delegation` の有無を含む）、返信先のCodexの `session_id`、関係する補足と参照先、下の定型文。修正依頼では、再現手順・期待と実際・対象差分・証拠の場所を加える |
+| コミットの依頼（CodexからClaude） | Issueリンク、対象差分・Gitの作業ディレクトリ・ブランチ、Local Agent QAの結果、人のレビューの状態（完了通知の内容、または設定による省略）、返信先のCodexの `session_id` |
+| 完了の報告（ClaudeからCodex） | 対象差分、自動検証の結果、起動方法、確認観点、既知の制限、未解決の事項、`shinaps:dev` 内のレビュー結果の要約と未解決の指摘。コミットした場合は、コミットSHAと `shinaps:commit` の検証・レビューの結果 |
+| 人のレビュー・コミット完了の報告（ClaudeからCodex） | 下の「人のレビュー・コミット完了の報告」の項目 |
+| 開発進行の引き渡し（ClaudeからCodex） | 利用者からの依頼の内容、対象Issue・Cycle、作業先リポジトリ、利用者が示した範囲と条件。Codexは作業先リポジトリの設定と照合して進行を始め、不足する判断はCodexから利用者へ確認する |
+
+コミットの依頼では、`commit_mode` がない場合の開始時の確認と、通常モードの単位ごとの承認を、Codexが人へ取り次ぐ。Codexは自分で選択・承認しない。
+
+実装・修正の依頼には次の文を含める。
+
+```text
+ユーザー承認済みの範囲でCodexが進行する。shinaps:linearを読み込み、この依頼の範囲と受入条件の中では人へ着手を再確認せず、shinaps:devで実行する。計画の相談・質問・障害・完了はBridgeで依頼元のCodexへ返す。人のレビュー・コミット完了を受けた場合も同じ返信先へ報告する。
+許可範囲: <設定と会話で許可された操作。dev_delegationの有無を含む>
+```
+
+受信は `read_messages` で全文を読み、受け取ったIDを `ack_messages` で確認する。ackは受領の確認であり、作業の完了ではない。完了は、相手の報告と実際の差分・検証結果で確認する。
+
+再接続後は、宛先を一覧から取得し直す。結果が不明な依頼を重複して送らない。重要な判断と結果はIssueへ記録し、Bridgeを唯一の記録先にしない。Bridgeの依頼は、利用者の明示的な停止や操作の許可範囲を上書きしない。
+
+Bridgeが必要な工程で使えない場合は、未実施の引き渡しを完了扱いにしない。担当を入れ替えず、状態と必要な準備を利用者へ伝える。
+
+### 人のレビュー・コミット完了の報告
+
+Claudeは、対象Issue、Gitの作業ディレクトリとブランチ、コミットSHA、人から受けた完了通知の内容、残作業を報告する。Gitにコミットがあるだけで、人のレビュー済みと推測しない。人がレビューだけを行い、コミットを `code_review` の工程の条件によりAIが行う場合は、レビューの完了通知の内容を報告し、コミットは後の工程で扱う。
+
+Codexは、対象Issue・差分・コミットと、対象作業の未コミット変更の有無を照合する。報告と実体が一致し、許可済みの工程へ進む場合は、人へ再確認しない。これは人のレビューをAIのレビューで代わりにする扱いではなく、人の完了通知を別のセッション経由で受け取る扱いである。
+
+Bridgeの報告は、新しい公開や破壊的な操作の許可を作らない。対象や通知の内容が足りない場合は、まずClaudeへ補足を求める。利用者の判断が必要な矛盾だけ、Codexから人へ確認する。
+
+## 人への依頼
+
+Code Reviewを依頼する前に対象差分を確認する。`stage` の許可がある場合だけ、対象だけをステージする。`git diff --cached` と `git status --short` で、新規ファイルの漏れと無関係な差分の混入を確認する。ステージにコミットは含めない。許可がなければ、ステージを人への依頼に含める。
+
+会話でIssueリンクと必要な作業を明示し、ステータスの変更だけで依頼を済ませない。
+
+| 依頼 | 文例 |
+| --- | --- |
+| Code Review | できるようになったことと重点確認点を添えて「[Issueリンク]の<依頼する作業>をお願いします。」依頼する作業は、設定で必要なコードレビューと、AIに許可していないコミットだけにする |
+| Human QA | 「[Issueリンク]のHuman QAをお願いします。」 |
+| 外部対応 | 「[Issueリンク]の〇〇をお願いします。」 |
+
+確認に必要な情報はIssueにまとめ、会話に毎回転載しない。未回答の同じ依頼は繰り返さず、対象が変わったら変更点を添える。Human QAの準備項目は [qa.md](qa.md) にある。
+
+## Issue単位とCycle単位の継続
+
+Issue単位の依頼は、そのIssueの終了地点で止まる。Cycle全体を任された場合だけ、Cycleを読み直して、依存と優先順位から次のIssueを選ぶ。
+
+### 開発進行のゴール
+
+Codexは開発進行を始めるとき、利用者が指定した対象（IssueまたはCycle）が完了するまでを一つのゴールとして設定する。Issueなら、そのIssueの完了。Cycleなら、対象Issueの完了と、合意されたCycle全体のQA・成果報告まで。同じ対象の既存のゴールがあれば再利用し、別の未完了のゴールを上書きしない。予算は利用者が明示した場合だけ設定する。Issueの読み取りや整理だけの呼び出しでは、ゴールを設定しない。
+
+設定の `stop_after` が対象の完了より手前なら、ゴールに到達したと扱わず、開始前に完了までの依頼と設定の相違を利用者と解消する。この解消で許可範囲を暗黙に広げない。通常の人の対応待ちで自発的にゴールを一時停止・完了にしない（[待ち状態](#待ち状態)）。利用者の明示的な停止・一時停止の指示と、実行環境の上位の制約は尊重する。ゴール機能が利用者からの明示的な依頼を要求する環境では、スキルだけでその制約を迂回しない。利用者の明示的な依頼が既にあればそれを用い、ない場合だけ開始時に一度得る。
+
+| 状況 | 行動 |
+| --- | --- |
+| 継続中のIssue、人の対応が済んだIssueがある | それを優先する。レビュー対象を残して別のIssueへ切り替えない |
+| 次のIssueを選ぶ | Cycle内で依存が解消し、着手できるIssueを優先順位の順に選ぶ |
+| 人の対応が必要になった | Issueリンクと必要な作業を添えて依頼し、回答・対応を確認してから再開する。人の対応を代わりに行わず、対象を残して別のIssueへ切り替えない |
+| 別のAIが作業中 | 完了の報告を待ち、結果を検証して次の工程へ進む。利用者への再開依頼に置き換えない |
+| 進められる作業がない | 理由と再開条件を報告して止まる |
+
+複数のリポジトリを含むCycleでは、各Issueの作業先リポジトリの設定を使う。設定・担当・QAの証拠が足りない部分を、別のリポジトリの結果で代わりにしない。
+
+Cycle外の取り込みと次のCycleへの継続には、別の合意が必要。Cycleの移動や取消で見かけ上の完了を作らない。Cycle実行の終わりには、対象Issueの到達点・未完了の条件・次に必要な対応を要約する。途中の終了地点に達しただけでは、Cycle完了報告を行わない。

package/plugins/shinaps-codex/skills/review/SKILL.md

@@ -13,6 +13,8 @@ Shinaps AIのルール検索が利用できる場合は関連するルールを
 
 指摘の独立検証が依頼・許可の範囲に含まれる場合は、登録済みのshinaps-review-validatorへ元の対象と一次指摘を渡す。外部APIの仕様が判断を左右する場合はshinaps-tech-surveyorで調査し、具体的な推奨の出典をshinaps-survey-validatorで確認できる。委託の数や範囲をユーザーが制限した場合はそれに従う。
 
-返された指摘を実コードと照合してから、挙動への影響があるものを優先度順に報告する。対象箇所、発生条件、影響、最小の修正案を含める。推測と確認済みの事実、実施した検証と未実施を区別する。指摘を埋めるための好みの変更は加えない。
+返された指摘を実コードと照合してから、挙動への影響や根拠のある保守上の負担を優先度順に報告する。対象箇所、発生条件、影響、最小の修正案を含める。推測と確認済みの事実、実施した検証と未実施を区別する。指摘を埋めるための好みの変更は加えない。
+
+可読性は、対象言語の基礎を知るジュニアが初めて読んでも目的・流れ・判断理由を追えるかで判断する。推測する意味、同時に覚える状態、理解のための往復を減らし、短さや分割数、特定構文を目標にしない。正しさ・型の保証・既存の性能とプロジェクト規約を維持する。指摘には読み手の具体的な負担と軽減する修正案を示し、ほぼ同等の表現や好みだけの差は修正要求にしない。性能への影響が不明なら必要な検証を示す。委託する場合もこの判断軸を渡す。
 
 修正・コミット・PR投稿はユーザーに依頼された範囲だけ行う。記録が必要ならプロジェクトの.shinaps/work/に保存し、.shinaps/.gitignoreに必要な除外を追加する。既存内容と追跡済みファイルは保持する。