diff --git a/AGENTS.md b/AGENTS.md index e8b5f38..34d8e7e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -65,23 +65,23 @@ These strings are not localizable in the current implementation. Forking is requ - Branch naming is the skill's responsibility (LLM-named in kebab-case, or user-supplied verbatim). The `worktree-` prefix forced by `EnterWorktree` is intentionally accepted; the `path` parameter escape hatch is out of scope (see issue #13). - The skill is a no-op when the current session is already inside a worktree — `EnterWorktree` itself rejects re-entry, and the skill double-checks via `git rev-parse --git-common-dir` / `--git-dir` before calling the tool. -## Cross-review backend selection +## Cross-review reviewer session selection -`cross-review` supports two backends, selected via the `CROSS_REVIEW_BACKEND` environment variable: +`cross-review` is defined as a second-opinion review from an independent reviewer session, not as a guarantee that a different backend or different model is used. -- `codex` — OpenAI Codex CLI (`codex exec` with stdin diff pipe; the `review` sub-command is avoided because of the 0.125.0 `--base` / `--uncommitted` / `[PROMPT]` mutual exclusion). Intended for "implemented with Claude Code → reviewed by GPT". -- `claude-self` — Claude CLI headless (`claude -p` with stdin diff). Intended for "implemented with Codex CLI / Cursor → reviewed by Claude". +- Codex runtime uses Codex CLI (`codex exec --sandbox read-only` with stdin diff pipe) to start a fresh reviewer session. +- Claude Code runtime uses Claude CLI headless (`claude -p` with stdin diff) to start a fresh reviewer session. -When the env var is unset, the skill falls back to `command -v` auto-detection (`codex` first, then `claude`). When the env var is **set** but the corresponding CLI is missing, the skill fails explicitly — there is no silent fallback to the other backend, since that would silently change the reviewer model the user asked for. +The runtime must be determined from the running agent's explicit environment, not inferred from whichever CLI exists on `PATH`. Environment-variable backend overrides and auto-detection fallback are intentionally not part of the workflow. If a different backend / different model review is needed, track that as a separate issue instead of keeping it inside `cross-review`. ## Cross-review base branch resolution -`cross-review` resolves the base branch dynamically via `gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'` and feeds the result into `git diff "$BASE_REF"...HEAD` for both backends (the diff is piped to `codex exec` / `claude -p` via stdin). `master` / `develop` / `trunk` repos work without modification. The skill stops with an explicit error (no silent fallback to `main`) when default-branch resolution fails — see its "失敗時の対応" section. Override (env var / arg) is intentionally out of scope. +`cross-review` resolves the base branch dynamically via `gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'` and feeds the result into `git diff "$BASE_REF"...HEAD` (the diff is piped to `codex exec` / `claude -p` via stdin). `master` / `develop` / `trunk` repos work without modification. The skill stops with an explicit error (no silent fallback to `main`) when default-branch resolution fails — see its "失敗時の対応" section. Override (env var / arg) is intentionally out of scope. ## External dependencies - `gh` CLI — all GitHub operations. Must be authenticated against the target repo. -- At least one of: Codex CLI (`brew install --cask codex`) or Claude CLI (`npm install -g @anthropic-ai/claude-code`), required by `cross-review`. The skill must fail loudly (not silently skip) when neither is available, or when an explicitly-selected backend's CLI is missing. +- The CLI for the current agent runtime: Codex CLI (`brew install --cask codex`) when implementing from Codex, or Claude CLI (`npm install -g @anthropic-ai/claude-code`) when implementing from Claude Code. `cross-review` must fail loudly (not silently skip) when the corresponding CLI is unavailable or the current runtime has no documented reviewer-session launch step. - Claude Code v2.1.49 or newer — required by `worktree-start` for the `EnterWorktree` tool. Older versions surface this as "tool not found"; the skill instructs users to upgrade rather than attempting any workaround. ## Editing skills diff --git a/README.md b/README.md index 703a9a8..474f3a1 100644 --- a/README.md +++ b/README.md @@ -73,14 +73,14 @@ This installs the skills under your agent's skill directory (e.g. `~/.claude/ski issuekit assumes the following tools are available on the host: -- **An [Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)-compatible agent runtime** (e.g. [Claude Code](https://docs.claude.com/en/docs/claude-code), Codex CLI, Cursor) that loads the skills. +- **An [Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)-compatible agent runtime** (e.g. [Claude Code](https://docs.claude.com/en/docs/claude-code), Codex CLI, Cursor) that loads the skills. The full `issue-implement` cycle currently requires Codex CLI or Claude Code because `cross-review` has reviewer-session launch steps only for those runtimes. - **[`gh` CLI](https://cli.github.com/)** — used for all GitHub interactions (issue read/write, PR creation, CI status). -- **At least one cross-review backend CLI** — required by `cross-review`. Pick whichever pairs with the agent driving the implementation: - - **[Codex CLI](https://github.com/openai/codex)** (`brew install --cask codex`) for the `codex` backend. - - **[Claude CLI](https://docs.claude.com/en/docs/claude-code)** (`npm install -g @anthropic-ai/claude-code`) for the `claude-self` backend (uses `claude -p` headless mode). -- **Claude Code v2.1.49 or newer** — required by `worktree-start` only (it uses the `EnterWorktree` tool added in 2.1.49). The other six skills run on any Agent Skills-compatible runtime. +- **The CLI for your current agent runtime** — required by `cross-review` to start an independent reviewer session: + - **[Codex CLI](https://github.com/openai/codex)** (`brew install --cask codex`) when the implementation is driven from Codex CLI. + - **[Claude CLI](https://docs.claude.com/en/docs/claude-code)** (`npm install -g @anthropic-ai/claude-code`) when the implementation is driven from Claude Code (uses `claude -p` headless mode). +- **Claude Code v2.1.49 or newer** — required by `worktree-start` only (it uses the `EnterWorktree` tool added in 2.1.49). Other skills load on any Agent Skills-compatible runtime, but `cross-review` currently documents reviewer-session launch steps only for Codex CLI and Claude Code. -`gh` must be authenticated against the repository you want to operate on. The `cross-review` backend is selected via the `CROSS_REVIEW_BACKEND` environment variable (`codex` / `claude-self`); if it is unset, the skill auto-detects whichever CLI is on `PATH`. If neither backend CLI is available, `cross-review` fails explicitly rather than silently skipping the review. +`gh` must be authenticated against the repository you want to operate on. `cross-review` does not switch to another backend automatically; it uses the CLI that corresponds to the runtime currently driving the implementation. If that CLI is unavailable, or if the current runtime has no documented reviewer-session launch step, `cross-review` fails explicitly rather than silently skipping the review. --- @@ -94,9 +94,9 @@ issuekit ships seven skills under `skills/`: | `issue-refine` | Entry point | Re-shape an existing issue (title-only or partially formatted) into the standard format. | | `issue-pick` | Entry point | Read-only triage: from a set of open issues, suggest the next one to take on, with rationale. | | `worktree-start` | Entry point | **Claude Code only.** Switch the running session into a freshly named git worktree via the `EnterWorktree` tool. Accepts a task description **or** an issue URL/number — when the input is a `Status: Ready` issue, it chains into `issue-implement` after the worktree switch (otherwise it stops at the switch). | -| `issue-implement` | Orchestrator| Drive the full cycle from an issue number: status check → worktree start → implementation / commits → acceptance check → cross-review → PR → CI. | +| `issue-implement` | Orchestrator| Drive the full cycle from an issue number: status check → worktree start → implementation / commits → acceptance check → cross-review → PR → CI. The full cycle currently requires Codex CLI or Claude Code because of `cross-review`. | | `acceptance-check` | Verifier | Read-only verifier that extracts `## 受け入れ条件` from an issue body and reports each item as `✓ / ✗ / ?`. Called by `issue-implement` after implementation/commits, before `cross-review`. | -| `cross-review` | Verifier | Delegate a second-opinion code review to a different AI backend (Codex CLI or Claude CLI headless, selectable via `CROSS_REVIEW_BACKEND`) before PR creation. Called by `issue-implement` after `acceptance-check` passes; review fixes land as additional commits. | +| `cross-review` | Verifier | Start an independent reviewer session with the current runtime's CLI and get a second-opinion code review before PR creation. Called by `issue-implement` after `acceptance-check` passes; review fixes land as additional commits. | `issue-implement` is the orchestrator; the other skills are either entry points or verifiers it calls. `worktree-start` is the only entry point that is Claude Code-specific (`EnterWorktree` is a Claude Code primitive — Codex CLI has no equivalent), so it has no fallback under other agent runtimes. It is also the only entry point that conditionally chains into the orchestrator: when invoked with an issue URL/number whose body has `Status: Ready`, it hands off to `issue-implement` after the worktree switch. diff --git a/skills/cross-review/SKILL.md b/skills/cross-review/SKILL.md index 91cebb1..8dcb128 100644 --- a/skills/cross-review/SKILL.md +++ b/skills/cross-review/SKILL.md @@ -1,72 +1,58 @@ --- name: cross-review -description: 実装・commit 後、`acceptance-check` 通過後・PR 作成前に別の AI (Codex CLI または Claude CLI headless) に diff を渡してセカンドオピニオンのコードレビューを得る。backend は環境変数 `CROSS_REVIEW_BACKEND` で `codex` / `claude-self` から選択でき、未指定時は利用可能な CLI を自動検出する。 -version: 1.0.3 +description: 実装・commit 後、`acceptance-check` 通過後・PR 作成前に、実装セッションから独立した reviewer session を実行中 agent runtime に対応する CLI で起動し、diff への second opinion を得る。 +version: 1.0.5 --- # Cross Review Skill -実装済みの変更を「実装した agent とは別の backend」にレビューさせ、異なる視点からのフィードバックを得る。Agent Skills は agent-portable な open standard であり、本 skill も特定の Claude Code 固有 primitive (Sub-Agent / Task tool) には依存せず、外部 CLI のみで動作する。 +実装済みの変更を、実装セッションから独立した **reviewer session** に渡して second opinion を得る。目的は「別 backend / 別モデルであること」の機械的保証ではなく、実装時の会話文脈・自己正当化・途中判断から切り離したレビュー専用セッションを作ること。 + +Agent Skills は agent-portable な open standard であり、本 skill は特定の Claude Code 固有 primitive (Sub-Agent / Task tool) には依存しない。実行中 agent runtime に対応する外部 CLI を使い、Codex 利用時は Codex CLI、Claude Code 利用時は Claude CLI だけで完結させる。 ## 利用タイミング - 実装・commit 後、`acceptance-check` を通過した時点で PR 作成前に呼び出す（cycle 内では実装/commit → acceptance-check → cross-review → PR の順）。レビュー指摘の修正は **追加 commit** として残し、`git commit --amend` / `rebase` 等で履歴整形しない。 -- ユーザーが明示的にレビューを依頼した場合 +- ユーザーが明示的にレビューを依頼した場合。 ## 依存 / 互換性 -- **Codex CLI**: 0.125.0 以降で動作確認済み (`brew install --cask codex`)。codex backend では `codex exec` + stdin diff pipe 方式を採用しており、`codex exec review` の `--base / --uncommitted / [PROMPT]` 三者排他 (0.125.0 以降の制約) を回避している。0.125.0 未満でも `codex exec [PROMPT]` への stdin pipe は基本機能として古くから存在するため動作する想定だが、明示的なサポート下限は 0.125.0 とする。`codex exec review` のサブコマンド固有の挙動には依存しない。 -- **Claude CLI**: claude-self backend が利用する `claude -p` のために必要 (`npm install -g @anthropic-ai/claude-code`)。stdin の 10MB 上限は Claude CLI v2.1.128 以降で明示的にエラー停止する (4. 分割レビューに切り替える)。 -- **`gh` CLI**: default branch 解決に必要。未認証 / repo 外実行では本 skill が明示的に停止する (失敗時の対応参照)。 +- **Codex CLI**: Codex runtime で本 skill を使う場合に必要 (`brew install --cask codex`)。`codex exec` + stdin diff pipe 方式で独立 reviewer session を起動する。`codex exec review` のサブコマンド固有の挙動には依存しない。 +- **Claude CLI**: Claude Code runtime で本 skill を使う場合に必要 (`npm install -g @anthropic-ai/claude-code`)。`claude -p` で独立 reviewer session を起動する。stdin の 10MB 上限に当たる場合は 4. 分割レビューに切り替える。 +- **`gh` CLI**: default branch 解決に必要。未認証 / repo 外実行では本 skill が明示的に停止する（失敗時の対応参照）。 + +## Reviewer Session の起動方針 -## Backend 選択 +実行中の agent runtime に対応する CLI で reviewer session を起動する。backend の自動検出や環境変数 override による切り替えは扱わない。runtime は実行中 agent が自分の環境情報として明示的に把握している値だけで判定し、`command -v codex` / `command -v claude` の存在順から推測しない。 -### 環境変数で明示指定する場合 +| 実装中の runtime | 使用 CLI | 起動方法 | +| ---------------- | -------- | -------- | +| Codex CLI | Codex CLI | `codex exec --sandbox read-only` | +| Claude Code | Claude CLI | `claude -p --allowedTools "Read"` | -`CROSS_REVIEW_BACKEND` で backend を選ぶ。 +この対応は「同じ製品ファミリーの CLI で別セッションを起動する」ためのものであり、別モデルレビューを保証するものではない。別 backend / 別モデルレビューが必要な場合は、本 skill の責務として残さず別 issue で設計する。 -| 値 | 使用 CLI | 想定ユースケース | -| -------------- | ------------------- | --------------------------------------------------------- | -| `codex` | OpenAI Codex CLI | Claude Code 等から実装し、別モデル (GPT 系) に交差レビュー | -| `claude-self` | Claude CLI headless | Codex CLI / Cursor 等から実装し、Claude にレビュー依頼 | +## 実行手順 -### 未指定時の自動検出 +### 0. runtime と CLI の事前確認 -`CROSS_REVIEW_BACKEND` が空 / 未設定の場合は、agent が以下の順で `command -v` を実行して backend を確定する。これは「実装した agent 自身に自分以外を選ばせる」優先順位ではなく、**利用可能なものから順に試す availability check** として機能する。 +実行中 agent runtime を明示的に判定する。Codex CLI で実装している場合は Codex CLI、Claude Code で実装している場合は Claude CLI を使う。判定できない場合、または Cursor / Gemini など本 skill に手順が定義されていない runtime の場合は、別 CLI へ自動的に切り替えず停止する。 -> **注意**: 自動検出は実行中の agent を判別しない。Codex CLI で実装中に両 CLI がインストールされていると、codex backend (= 同系統 backend) が選ばれて事実上「自己レビュー」になる可能性がある。「別 backend に必ず投げる」ことを保証したい場合は、ユーザー側で `CROSS_REVIEW_BACKEND=claude-self` (Codex から実装する場合) / `CROSS_REVIEW_BACKEND=codex` (Claude から実装する場合) のように明示指定する運用を推奨する。 +runtime 判定後、対応 CLI の存在だけを確認する。以下はいずれか一方だけを実行し、両方を連続実行しない。 ```bash -if [ -n "${CROSS_REVIEW_BACKEND:-}" ]; then - BACKEND="$CROSS_REVIEW_BACKEND" -elif command -v codex >/dev/null 2>&1; then - BACKEND="codex" -elif command -v claude >/dev/null 2>&1; then - BACKEND="claude-self" -else - echo "cross-review: 利用可能な backend が見つかりません。codex CLI (\`brew install --cask codex\`) または Claude CLI (\`npm install -g @anthropic-ai/claude-code\`) を導入してください。" >&2 - exit 1 -fi +# Codex CLI で実装している場合 +command -v codex >/dev/null 2>&1 || { printf '%s\n' 'Codex CLI runtime ですが `codex` コマンドが見つかりません。`brew install --cask codex` で導入してください。' >&2; exit 1; } ``` -明示指定された backend に対応する CLI が見つからない場合は、暗黙の fallback はせず明示的なエラーで停止する（ユーザーが意図した backend と異なる結果を返さないため）。 - ```bash -case "$BACKEND" in - codex) - command -v codex >/dev/null 2>&1 || { echo "CROSS_REVIEW_BACKEND=codex ですが \`codex\` コマンドが見つかりません。\`brew install --cask codex\` で導入してください。" >&2; exit 1; } ;; - claude-self) - command -v claude >/dev/null 2>&1 || { echo "CROSS_REVIEW_BACKEND=claude-self ですが \`claude\` コマンドが見つかりません。\`npm install -g @anthropic-ai/claude-code\` で導入してください。" >&2; exit 1; } ;; - *) - echo "cross-review: 未対応の CROSS_REVIEW_BACKEND=$BACKEND (対応値: codex / claude-self)" >&2; exit 1 ;; -esac +# Claude Code で実装している場合 +command -v claude >/dev/null 2>&1 || { printf '%s\n' 'Claude Code runtime ですが `claude` コマンドが見つかりません。`npm install -g @anthropic-ai/claude-code` で導入してください。' >&2; exit 1; } ``` -## 実行手順 - -### 1. base ref の確定 (backend 共通) +### 1. base ref の確定 -リポジトリの default branch 名を動的に取得し、ローカルで実際に解決可能な ref を `BASE_REF` に確定する。`BASE_REF` は両 backend が `git diff "$BASE_REF"...HEAD` の base として共通で使う。 +リポジトリの default branch 名を動的に取得し、ローカルで実際に解決可能な ref を `BASE_REF` に確定する。`BASE_REF` は `git diff "$BASE_REF"...HEAD` の base として使う。 ```bash BASE_BRANCH=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name') @@ -84,7 +70,7 @@ fi `master` / `develop` / `trunk` を default branch とするリポジトリでも、この `BASE_REF` 経由で同じ手順がそのまま動く。`main` への暗黙フォールバックは行わない（後述「失敗時の対応」参照）。 -### 2. 差分の確認 (backend 共通) +### 2. 差分の確認 ```bash # コミット済みの変更（ブランチの差分） @@ -99,17 +85,18 @@ git diff --cached ``` 差分のファイル数と行数を確認し、レビュー方法を決定する。 + - **差分が 500 行以下**: 一括レビュー（ステップ 3 へ） - **差分が 500 行超**: ファイル単位で分割レビュー（ステップ 4 へ） - **差分が 0 行**: レビュー不要としてスキップする ### 3. 一括レビュー -#### 3-a. backend = `codex` の場合 +#### 3-a. Codex CLI で実行中の場合 -`codex exec` に diff を stdin から流し込み、レビュー指示を `[PROMPT]` 引数として渡す。stdin が piped されかつ `[PROMPT]` も指定された場合、codex は stdin を `` ブロックとして prompt に append する仕様 (`codex exec --help` 参照)。`codex exec review --base / --uncommitted / [PROMPT]` の三者排他 (codex-cli 0.125.0 以降) を回避するため、`review` サブコマンドではなく汎用の `codex exec` を使う。claude-self backend と同じ「diff pipe + custom prompt」の構造に揃え、保守コストも下げている。 +`codex exec` に diff を stdin から流し込み、レビュー指示を `[PROMPT]` 引数として渡す。stdin が piped されかつ `[PROMPT]` も指定された場合、codex は stdin を `` ブロックとして prompt に append する仕様 (`codex exec --help` 参照)。`codex exec review` のサブコマンド固有の挙動には依存しない。 -`--sandbox read-only` を明示することで、汎用 `codex exec` を使いながらも cross-review の「報告のみ・自動修正しない」原則を CLI レイヤーで担保する (`--full-auto` は workspace-write が付くため使わない)。 +`--sandbox read-only` を明示することで、汎用 `codex exec` を使いながらも cross-review の「報告のみ・自動修正しない」原則を CLI レイヤーで担保する（`--full-auto` は workspace-write が付くため使わない）。 ```bash { @@ -121,7 +108,7 @@ git diff --cached echo echo "=== Staged diff ===" git diff --cached -} | codex exec --sandbox read-only --model gpt-5.4 "You are a senior code reviewer providing a second opinion. Do not modify any files; output the review only. The diff is supplied via stdin (codex wraps it as a block). First, read the repository's AGENTS.md (if it exists) to understand project conventions and coding standards. +} | codex exec --sandbox read-only "You are a senior code reviewer providing a second opinion. Do not modify any files; output the review only. The diff is supplied via stdin (codex wraps it as a block). First, read the repository's AGENTS.md (if it exists) to understand project conventions and coding standards. Then evaluate the diff from these perspectives: @@ -141,7 +128,7 @@ Output format (respond in Japanese): - End with a summary table: total findings by severity" ``` -#### 3-b. backend = `claude-self` の場合 +#### 3-b. Claude Code で実行中の場合 `claude -p` で Claude CLI に diff を stdin 経由で渡す。`--bare` は OAuth / keychain のログイン状態を読まず `ANTHROPIC_API_KEY` または `--settings` の `apiKeyHelper` 前提になるため、ローカルの Claude.ai ログイン運用でも動くように使わない。`AGENTS.md` を読ませるために `--allowedTools "Read"` を付与する。 @@ -176,11 +163,9 @@ Output format (respond in Japanese): - End with a summary table: total findings by severity" ``` -> piped stdin は Claude CLI v2.1.128 以降 10MB cap がある。500 行超の差分は次の分割レビューに切り替えれば 1 ファイルあたりは十分小さくなる。 - -### 4. 分割レビュー (差分が大きい場合) +### 4. 分割レビュー（差分が大きい場合） -差分をファイル単位に分割し、ファイルごとに backend を呼ぶ。最後に全ファイルのレビュー結果を集約してサマリーを作成する。 +差分をファイル単位に分割し、ファイルごとに reviewer session を呼ぶ。最後に全ファイルのレビュー結果を集約してサマリーを作成する。 ```bash # 変更ファイル一覧を取得（コミット済み + unstaged + staged の和集合） @@ -189,9 +174,9 @@ git diff --name-only git diff --cached --name-only ``` -#### 4-a. backend = `codex` +#### 4-a. Codex CLI で実行中の場合 -`FILE_PATH` でファイルパスを変数化し、空白や shell メタ文字を含むファイル名でも壊れないようにする (3-a と同じく `--sandbox read-only` で書き込みを禁止)。`` は placeholder で、実利用時は単一引用符付きで実パスに置き換える (例: `FILE_PATH='skills/cross-review/SKILL.md'`)。 +`FILE_PATH` でファイルパスを変数化し、空白や shell メタ文字を含むファイル名でも壊れないようにする（3-a と同じく `--sandbox read-only` で書き込みを禁止）。`` は placeholder で、実利用時は単一引用符付きで実パスに置き換える（例: `FILE_PATH='skills/cross-review/SKILL.md'`）。 ```bash FILE_PATH='' @@ -200,7 +185,7 @@ FILE_PATH='' git diff "$BASE_REF"...HEAD -- "$FILE_PATH" git diff -- "$FILE_PATH" git diff --cached -- "$FILE_PATH" -} | codex exec --sandbox read-only --model gpt-5.4 "You are a senior code reviewer providing a second opinion. Do not modify any files; output the review only. The diff for a single file is supplied via stdin (codex wraps it as a block). Review the changes to $FILE_PATH. +} | codex exec --sandbox read-only "You are a senior code reviewer providing a second opinion. Do not modify any files; output the review only. The diff for a single file is supplied via stdin (codex wraps it as a block). Review the changes to $FILE_PATH. Evaluate from: Correctness, Readability, Consistency, Security, Performance, Tests, Documentation, Related-file consistency. @@ -209,18 +194,19 @@ Output (respond in Japanese): - If no issues, state the file looks good" ``` -#### 4-b. backend = `claude-self` +#### 4-b. Claude Code で実行中の場合 ```bash +FILE_PATH='' { - echo "=== Diff for ===" - git diff "$BASE_REF"...HEAD -- - git diff -- - git diff --cached -- + echo "=== Diff for $FILE_PATH ===" + git diff "$BASE_REF"...HEAD -- "$FILE_PATH" + git diff -- "$FILE_PATH" + git diff --cached -- "$FILE_PATH" } | claude -p \ --allowedTools "Read" \ --append-system-prompt "You are a senior code reviewer providing a second opinion. The diff for a single file is supplied via stdin." \ - "Review the changes to . + "Review the changes to $FILE_PATH. Evaluate from: Correctness, Readability, Consistency, Security, Performance, Tests, Documentation, Related-file consistency. @@ -231,25 +217,28 @@ Output (respond in Japanese): ### 5. 結果の集約と報告 -backend のレビュー結果を確認し、ユーザーへ報告する。 +reviewer session の結果を確認し、ユーザーへ報告する。 + - **critical** の指摘がある場合: 修正案を提示し、ユーザーに対応方針を確認する - **warning** の指摘がある場合: agent 自身で対応要否を判断する。妥当な指摘は自律的に修正し、見送る場合は理由を添えて報告する（ユーザー確認は不要） - **info** のみの場合: 指摘を共有し、PR 作成に進む ## 失敗時の対応 -- **backend CLI が見つからない場合**: `command -v` 結果と `CROSS_REVIEW_BACKEND` の値を踏まえて明示的に停止する。`codex` 未導入なら `brew install --cask codex` を、`claude` 未導入なら `npm install -g @anthropic-ai/claude-code` を案内する。Codex CLI 初回利用時は `codex login` で OpenAI アカウント認証が必要。Claude CLI 初回利用時は `claude` を一度起動して認証する。 +- **実行中 runtime に対応する CLI が見つからない場合**: Codex CLI で実装しているなら `codex`、Claude Code で実装しているなら `claude` が必要。該当 CLI が無ければ明示的に停止し、Codex CLI は `brew install --cask codex`、Claude CLI は `npm install -g @anthropic-ai/claude-code` を案内する。Codex CLI 初回利用時は `codex login` で OpenAI アカウント認証が必要。Claude CLI 初回利用時は `claude` を一度起動して認証する。 +- **実行中 runtime を判定できない場合**: 自動検出で別 CLI へ切り替えず停止する。Codex CLI / Claude Code 以外の runtime 向け手順は別 issue で扱う。 - **default branch の取得失敗時**: `gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'` が空文字を返す、もしくは `gh` がエラーを返した場合は、その時点で停止しエラーメッセージを出す。`main` への暗黙フォールバックは行わない（誤った base に対する diff でレビュー結果が破綻するため）。よくある原因は、`gh` 未認証 (`gh auth status` で確認) / git repo 外での実行 / リモートが GitHub 以外。原因を解消してから再実行する。 - **base ref の resolve 失敗時**: `BASE_BRANCH` 名は取れたが、ローカルに該当 ref も `origin/$BASE_BRANCH` も存在しない場合（例: 浅い clone / default branch を local 側で削除した worktree 等）も停止する。`git fetch origin` で remote-tracking ref を取得すれば多くの場合解消する。 -- **codex backend で `codex exec review --base ... [PROMPT]` 系のエラーに遭遇した場合**: 古い呼び出し方式が残ったローカル環境の可能性が高い。本 skill は 0.125.0 の三者排他制約を踏まえて `codex exec` + stdin diff pipe に移行済み。SKILL.md を最新版に更新するか、shell history に残った古いコマンドを破棄する。 +- **Codex CLI で `codex exec review --base ... [PROMPT]` 系のエラーに遭遇した場合**: 古い呼び出し方式が残ったローカル環境の可能性が高い。本 skill は `codex exec` + stdin diff pipe を使う。SKILL.md を最新版に更新するか、shell history に残った古いコマンドを破棄する。 - **差分がない場合**: レビュー不要としてスキップする。 -- **backend がタイムアウトした場合**: 差分を分割して再試行する（ステップ 4）。 -- **claude-self backend で stdin が 10MB を超える場合**: Claude CLI が明示的にエラーで停止するので、ステップ 4 の分割レビューに切り替える。 +- **reviewer session がタイムアウトした場合**: 差分を分割して再試行する（ステップ 4）。 +- **Claude CLI で stdin が 10MB を超える場合**: Claude CLI が明示的にエラーで停止するので、ステップ 4 の分割レビューに切り替える。 ## やらないこと -- 暗黙の backend fallback（明示指定された backend が利用不可な場合に勝手に他の backend に切り替えること）。ユーザー意図と異なるレビュー結果を返すことを避けるため。 +- backend / CLI の自動検出や環境変数 override による切り替え。実行中 runtime に対応する CLI で独立 reviewer session を起動する。 +- 別 backend / 別モデルレビューの保証。必要なら別 issue として扱う。 - レビュー結果の自動修正適用（報告のみ）。 -- backend 出力フォーマットの統一（各 backend の出力をそのまま使う）。 +- reviewer session の出力フォーマットの統一（各 CLI の出力をそのまま使う）。 - 追加 backend (Gemini / OpenAI 直 API 等) の実装。構造を残しつつ別 issue 化。 -- codex-cli 0.124 系以前への downgrade 案内。upstream の意思決定に追従しない一時しのぎになり、依存 CLI のバージョン分岐が発散するため採らない (`codex exec` + stdin diff pipe で 0.125.0 以降を正面突破する)。 +- codex-cli 0.124 系以前への downgrade 案内。upstream の意思決定に追従しない一時しのぎになり、依存 CLI のバージョン分岐が発散するため採らない（`codex exec` + stdin diff pipe で正面突破する）。 diff --git a/skills/issue-implement/SKILL.md b/skills/issue-implement/SKILL.md index 13db1ef..4e002c9 100644 --- a/skills/issue-implement/SKILL.md +++ b/skills/issue-implement/SKILL.md @@ -1,7 +1,7 @@ --- name: issue-implement description: 特定の GitHub issue への実装着手と PR 作成を依頼されたときに使う。issue 番号・URL・会話内で選んだ issue のいずれかを起点に、実装・commit・lint・受け入れ条件チェック・cross-review・PR 作成・CI 確認まで一気通貫で自動進行する。コードを書いてプルリクを出す作業全般が対象で、issue 選定相談・タイトル編集・クローズ操作・PR レビュー単体には使わない。 -version: 1.0.4 +version: 1.0.5 --- # Issue Implement Skill @@ -12,7 +12,7 @@ GitHub issue を起点とした issue-driven 開発サイクルの中核 skill ## 依存 -- **`issuekit:cross-review` skill**: 実装・commit 後、PR 作成前に cross-review を実施する。APM plain-skill mode では `cross-review` として呼び出す。backend は環境変数 `CROSS_REVIEW_BACKEND` で `codex` / `claude-self` から選択でき、未指定時は利用可能な CLI を自動検出する。対応する CLI がいずれも未導入な場合は明確に失敗させる（該当 skill 側の失敗時対応に従う）。 +- **`issuekit:cross-review` skill**: 実装・commit 後、PR 作成前に、実装セッションから独立した reviewer session による second opinion を得る。APM plain-skill mode では `cross-review` として呼び出す。実装前に runtime と対応 CLI を事前確認し、未対応 runtime や CLI 未導入の場合は明確に失敗させる（該当 skill 側の失敗時対応に従う）。 - **`issuekit:acceptance-check` skill**: 実装・commit 後、cross-review より前に受け入れ条件の自動検査を実施する。APM plain-skill mode では `acceptance-check` として呼び出す。 - **`issuekit:worktree-start` skill**: Claude Code 環境かつ default branch 上で起動された場合に、実装直前で worktree への自動切り替えに使用する (条件付き、後述 step 4)。APM plain-skill mode では `worktree-start` として呼び出す。Claude Code 以外の runtime ではこの step は skip される。 - **`gh` CLI**: GitHub 操作全般に使用する。 @@ -22,7 +22,7 @@ GitHub issue を起点とした issue-driven 開発サイクルの中核 skill - **含む**: Status 確認、Depends on の close 確認、親 issue の文脈取り込み、worktree への自動切り替え (Claude Code 環境かつ default branch 上のときのみ、条件付き)、実装と適宜 commit、lint/format/型チェック、受け入れ条件チェック、cross-review、PR 作成、CI 確認・修正。 - **含まない**: - default branch 名を hardcode した branch ガード。default branch 名はリポジトリにより異なる (main / master / develop / trunk 等) ため、`gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'` で動的に解決した値と現在ブランチを比較する。 - - 非 Claude Code 環境 (Codex CLI / Cursor / Gemini) 向けの worktree 化フォールバック。`EnterWorktree` ツールが無い環境ではこの step を skip し、ユーザーが事前に切った worktree / branch でそのまま続行する。 + - 非 Claude Code 環境向けの worktree 化フォールバック。Codex CLI では `EnterWorktree` が無いためこの step を skip し、ユーザーが事前に切った worktree / branch で続行する。Cursor / Gemini など `cross-review` 未対応 runtime は、実装前の preflight で停止する。 - ユーザーが既に手動で feature ブランチに切り替えているケースの上書き。default branch 以外にいる場合は worktree 化を行わず既存ブランチを尊重する。 - レビュー指摘の修正を `git commit --amend` / `rebase` / `fixup` で履歴整形すること。指摘対応は **追加 commit** で行い、試行錯誤やレビュー対応の経緯を履歴に残す。 @@ -77,6 +77,8 @@ gh api "repos/${REPO}/issues/${ISSUE_NUMBER}/parent" --jq '{number, title, state 実装サイクルの冒頭で、default branch 上のまま実装を始めて main / master を直接汚す事故を機械的に防ぐためのステップ。以下の AND 条件 4 つを **すべて** 満たす場合のみ、`issuekit:worktree-start` skill (APM plain-skill mode では `worktree-start`) を呼び出して新規 worktree に切り替える。 +この step に入る前に、後続の step 8 で `cross-review` を実行できる runtime / CLI かを事前確認する。Codex CLI で実装している場合は `codex`、Claude Code で実装している場合は `claude` が必要。Cursor / Gemini など `cross-review` 側に手順が定義されていない runtime、または実行中 runtime を明示的に判定できない場合は、実装・commit に進む前に停止する。CLI の有無は対応するコマンドだけを `command -v` で確認し、インストール済み CLI の存在順から runtime を推測しない。 + 1. **`EnterWorktree` ツールが利用可能** (= Claude Code 環境)。Codex CLI / Cursor / Gemini 等の非 Claude Code 環境では `EnterWorktree` が存在しないため自動的に false となり、本 step は skip される。 2. **現在のセッションが worktree の外**: `git rev-parse --git-common-dir` と `git rev-parse --git-dir` の出力が一致する。一致しなければ既に worktree 内なので skip。 3. **現在のブランチが default branch**: `gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'` の結果と `git rev-parse --abbrev-ref HEAD` が一致する。default branch 以外 (= ユーザーが手動で feature ブランチに切り替え済み) なら skip し、既存ブランチを尊重する。 @@ -86,7 +88,7 @@ gh api "repos/${REPO}/issues/${ISSUE_NUMBER}/parent" --jq '{number, title, state いずれかの条件が欠ける場合は worktree を切らずにそのまま step 5 (実装) に進む: -- 非 Claude Code 環境 → ユーザーが事前に切った worktree / branch で続行。 +- preflight を通過した非 Claude Code 環境 (= Codex CLI) → ユーザーが事前に切った worktree / branch で続行。Cursor / Gemini など `cross-review` 未対応 runtime は上記の事前確認で停止済み。 - 既に worktree 内 → 二重発火を避けるため何もしない (`worktree-start` 側の再進入チェックでも no-op になる)。 - default branch 以外のブランチ → ユーザーが意図して feature ブランチを切っているとみなし上書きしない。 @@ -130,13 +132,13 @@ commit メッセージは Conventional Commit-like prefix (`feat:` / `fix:` / `c ### 8. cross-review (issuekit:cross-review skill) -受け入れ条件をすべて満たした最終形に対して、別 backend (Codex CLI または Claude CLI headless) による cross-review を実施する。`issuekit:cross-review` skill を呼び出す。APM plain-skill mode では `cross-review` を呼び出す。 +受け入れ条件をすべて満たした最終形に対して、実装セッションから独立した reviewer session による cross-review を実施する。`issuekit:cross-review` skill を呼び出す。APM plain-skill mode では `cross-review` を呼び出す。 - **critical** の指摘がある場合: **追加 commit** で修正してから次に進む（`git commit --amend` / `rebase` / `fixup` は使わない）。修正後に受け入れ条件への影響が無いか軽く確認する（影響が疑わしい場合は step 7 をやり直す）。 -- **warning** の指摘がある場合: Claude 自身で対応要否を判断する。妥当な指摘は自律的に **追加 commit** で修正し、見送る場合は理由を添えて報告する（ユーザー確認は不要）。 +- **warning** の指摘がある場合: 実装 agent 自身で対応要否を判断する。妥当な指摘は自律的に **追加 commit** で修正し、見送る場合は理由を添えて報告する（ユーザー確認は不要）。 - **info** のみの場合: 指摘を共有し、PR 作成に進む。 -backend は環境変数 `CROSS_REVIEW_BACKEND` (`codex` / `claude-self`) で選べる。未指定時は同 skill 側で `command -v` による自動検出が走る。base branch は `gh repo view --json defaultBranchRef` から動的に解決される（`master` / `develop` / `trunk` でもそのまま動く）。default branch 解決が失敗した場合は同 skill が明示的に停止するので、エラー出力に従って原因を解消してから再実行する。 +reviewer session は実行中 agent runtime に対応する CLI で起動する。Codex CLI で実装している場合は `codex exec --sandbox read-only`、Claude Code で実装している場合は `claude -p` を使う。base branch は `gh repo view --json defaultBranchRef` から動的に解決される（`master` / `develop` / `trunk` でもそのまま動く）。default branch 解決が失敗した場合は同 skill が明示的に停止するので、エラー出力に従って原因を解消してから再実行する。 ### 9. PR 作成 @@ -172,5 +174,5 @@ PR URL と CI 結果（成功 / 修正後成功）をユーザーに返す。 - step 4 で `worktree-start` を呼ぶ際に issue 番号を渡すこと。issue 番号を渡すと `worktree-start` 側の Status 判定経路に入り `issue-implement` への再帰連鎖が起きるため、タスク説明モードで slug (`-<issue 番号>`) のみを渡す。 - issue 本文や PR への `close` キーワードの自動付与（ユーザー明示指定時のみ）。 - 受け入れ条件を満たさない状態での PR 作成。 -- 対応 backend CLI（codex / claude）がいずれも未導入な状態での cross-review 省略（該当する `issuekit:cross-review` / `cross-review` skill の失敗時対応に従い、明確に失敗させる）。 +- 実行中 agent runtime に対応する CLI が未導入な状態での cross-review 省略（該当する `issuekit:cross-review` / `cross-review` skill の失敗時対応に従い、明確に失敗させる）。 - **`acceptance-check` / `cross-review` / CI の指摘修正のために `git commit --amend` / `git rebase` / `git rebase -i` / `--fixup` / `git reset` 等で履歴を整形すること**。レビュー対応・修正対応はすべて **追加 commit** として残し、試行錯誤と修正経緯を後から追えるようにする。issuekit リポジトリは merge commit 運用（squash ではない）なので、commit 履歴は merge 後も価値を持つ。