From bdb6aa31a1122914b364ca9e8ac4356dd42b2ec5 Mon Sep 17 00:00:00 2001 From: Hiroki SAKABE Date: Sun, 2 Aug 2026 00:36:27 +0900 Subject: [PATCH 1/3] feat: add comment-based investigation workflow --- AGENTS.md | 15 +-- README.md | 33 +++--- skills/acceptance-check/SKILL.md | 19 ++-- skills/issue-create/SKILL.md | 16 ++- skills/issue-investigate/SKILL.md | 167 ++++++++++++++++++++++++++++++ skills/issue-pick/SKILL.md | 29 ++++-- skills/issue-refine/SKILL.md | 10 +- skills/worktree-start/SKILL.md | 45 ++++---- 8 files changed, 273 insertions(+), 61 deletions(-) create mode 100644 skills/issue-investigate/SKILL.md diff --git a/AGENTS.md b/AGENTS.md index eb03ebe..3f74642 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,9 +6,9 @@ This file provides guidance to coding agents (Claude Code, Codex, etc.) when wor ## What this repository is -issuekit is an **Agent Skills bundle**, not an application. It contains 7 skills as `skills//SKILL.md` markdown files, distributed via `gh skill install hirokisakabe/issuekit` (version-pinnable via GitHub Releases) and `npx skills add hirokisakabe/issuekit` (always HEAD). There is no build, test, or lint toolchain — the artifacts are the SKILL.md files themselves. +issuekit is an **Agent Skills bundle**, not an application. It contains 8 skills as `skills//SKILL.md` markdown files, distributed via `gh skill install hirokisakabe/issuekit` (version-pinnable via GitHub Releases) and `npx skills add hirokisakabe/issuekit` (always HEAD). There is no build, test, or lint toolchain — the artifacts are the SKILL.md files themselves. -The bundle codifies an **issue-driven development** workflow where the GitHub issue body is the rich plan (with `Status: Ready/Draft`, `## 受け入れ条件`, `## スコープ外`, `Depends on:`, `親: #N`), and the repository contains only durable code. See `README.md` for the philosophy and the comparison vs. Spec Kit / cc-spex / superpowers. +The bundle codifies an **issue-driven development** workflow where the GitHub issue body is the rich plan (with `Status: Ready/Draft`, `## 受け入れ条件`, `## スコープ外`, `Depends on:`, `親: #N`), investigation results default to issue comments, and the repository contains only durable artifacts. See `README.md` for the philosophy and the comparison vs. Spec Kit / cc-spex / superpowers. ## Skill graph @@ -17,8 +17,10 @@ The bundle codifies an **issue-driven development** workflow where the GitHub is - `issue-implement` → `acceptance-check` (verifies `## 受け入れ条件` against the final repo state after implementation+commits, **before** `cross-review` so an acceptance ✗ does not waste a cross-review pass) - `issue-implement` → `cross-review` (second-opinion code review of the `base...HEAD` diff after `acceptance-check` passes, before PR creation; review fixes land as additional commits, not amends) - `issue-implement` → `worktree-start` (**conditional**, before implementation in `issue-implement` step 4): fires only when **all four** conditions hold — `EnterWorktree` is available (= Claude Code runtime), the session is outside any worktree (`git rev-parse --git-common-dir` == `--git-dir`), the current branch is the repo's default branch (`gh repo view --json defaultBranchRef`), and `Status: Ready`. `Status: Draft` triggers an early abort in step 1, so the worktree is never created for Draft issues. -- `worktree-start` → `issue-implement` (**only** when input is an issue URL/number with `Status: Ready`; with a generic task description, `Status: Draft`, or unformatted issues it stops at the worktree switch) -- `issue-create` / `issue-refine` / `issue-pick` are entry points; they do not chain into other skills. `issue-pick` is a triage entry point and does not chain (see its "やらないこと" — handing off to `issue-implement` is via user only). +- `worktree-start` → `issue-implement` or `issue-investigate` (**only** when input is an issue URL/number with `Status: Ready` and a clear completion shape; PR-shaped issues route to `issue-implement`, comment-shaped issues route to `issue-investigate`, and ambiguous issues stop after the worktree switch with an `issue-refine` recommendation) +- `issue-create` / `issue-refine` / `issue-pick` are entry points; they do not chain into other skills. `issue-pick` is a triage entry point and does not chain (see its "やらないこと" — handing off to `issue-implement` or `issue-investigate` is via user only). + +`issue-investigate` is the separate orchestrator for comment-complete investigation, design, and technical-validation issues. It posts a structured result comment, calls `acceptance-check`, and closes the issue only after the acceptance check succeeds. It does not commit, open a PR, or call `cross-review`. `issue-pick` suggests it via the user, while `worktree-start` may chain to it when a Ready issue's acceptance criteria require only an issue comment and no durable repo change. The `issue-implement ↔ worktree-start` edge is **bidirectional but not looping**: @@ -30,7 +32,7 @@ When editing one skill, check whether others reference it. Cross-references appe - Plugin mode: `issuekit:` (e.g. `issuekit:cross-review`) - APM plain-skill mode: bare `` (e.g. `cross-review`) -Both forms must stay in sync — `issue-implement` and `issue-pick` document each form explicitly. +Both forms must stay in sync — `issue-implement`, `issue-investigate`, `issue-pick`, and `worktree-start` document each form explicitly. ## Hardcoded Japanese keywords @@ -40,12 +42,13 @@ Skills mechanically parse Japanese section headers from issue bodies: - `Depends on: #N, #M` - `親: #N` - `## 概要` / `## 背景 / モチベーション` / `## 受け入れ条件` / `## Ready にするための未決事項` / `## スコープ外` / `## 参考` / `## 実装方針` / `## 再現手順` / `## 期待する挙動` / `## 実際の挙動` / `## 調査メモ` +- Result comments: `## 調査結果` / `### 結論` / `### 根拠` / `### 検証内容` / `### Blocker` / `### 却下案` / `### 後続候補` These strings are not localizable in the current implementation. Forking is required to use English issues (per README). ## Status semantics (single source of truth: `issue-create`) -`Status` is judged on **acceptance-criteria certainty only**, not implementation-plan certainty. A bug issue with a prioritized list of fix candidates and verifiable acceptance criteria is `Ready`. Acceptance criteria containing 「仮」/「要検討」 or that are too vague to self-verify → `Draft`. Draft issues must include `## Ready にするための未決事項`, listing only the concrete decisions needed to finalize acceptance criteria. `issue-refine` and `issue-implement` defer to `issue-create` for this rule — do not duplicate the definition; update `issue-create` and reference it. +`Status` is judged on **acceptance-criteria certainty only**, not implementation-plan certainty. A bug issue with a prioritized list of fix candidates and verifiable acceptance criteria is `Ready`. Acceptance criteria containing 「仮」/「要検討」 or that are too vague to self-verify → `Draft`. Draft issues must include `## Ready にするための未決事項`, listing only the concrete decisions needed to finalize acceptance criteria. `issue-refine`, `issue-implement`, and `issue-investigate` defer to `issue-create` for this rule — do not duplicate the definition; update `issue-create` and reference it. ## Depends on / parent semantics diff --git a/README.md b/README.md index 99cfde6..7fde501 100644 --- a/README.md +++ b/README.md @@ -58,7 +58,7 @@ The install location depends on `--agent` and `--scope`; for Claude Code at user ### via `npx skills` (Claude Code, Codex CLI, Cursor, Gemini, …) ```bash -# Install all seven skills (always installs HEAD — version pinning not yet supported) +# Install all eight skills (always installs HEAD — version pinning not yet supported) npx skills add hirokisakabe/issuekit # Or install a specific skill only @@ -86,19 +86,20 @@ issuekit assumes the following tools are available on the host: ## 🧩 Skills -issuekit ships seven skills under `skills/`: +issuekit ships eight skills under `skills/`: | Skill | Role | Description | | -------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `issue-create` | Entry point | Open a new GitHub issue using issuekit's standard format (`Status: Ready` / `Status: Draft` header, intent, plan, acceptance criteria, out-of-scope). | | `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). | +| `worktree-start` | Entry point | **Claude Code only.** Switch into a new worktree, then route a Ready issue to `issue-implement` (PR), `issue-investigate` (issue comment), or `issue-refine` (ambiguous). | | `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`. | +| `issue-investigate` | Orchestrator| Investigate, design, or run a technical spike without durable repo changes; post a structured result comment, run acceptance checks, then close the issue on success. | +| `acceptance-check` | Verifier | Read-only verifier that extracts `## 受け入れ条件` and checks repo state or issue comments, reporting each item as `✓ / ✗ / ?`. Called by both orchestrators before completion. | | `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. +`issue-implement` and `issue-investigate` are the two orchestrators. PR-shaped work goes through implementation, review, and CI; comment-shaped investigation work records its result on the issue and closes it without a commit or PR. `worktree-start` is the only Claude Code-specific entry point and routes a Ready issue by its acceptance criteria and out-of-scope section: PR → `issue-implement`, issue comment → `issue-investigate`, ambiguous → `issue-refine`. `Status: Draft` is reserved for issues whose acceptance criteria are not yet certain. Draft issues include a `## Ready にするための未決事項` checklist containing the concrete decisions needed to finalize those criteria; implementation-plan choices alone do not make an issue Draft. @@ -106,18 +107,22 @@ issuekit ships seven skills under `skills/`: ## 🔁 Workflow -The skills compose into a single issue-driven cycle. Entry points feed an issue into the orchestrator, which calls the verifiers before producing a commit and a PR. +The skills compose into two issue-driven completion paths. Entry points feed a Ready issue into the matching orchestrator; ambiguous completion shapes return to refinement. ```mermaid flowchart LR A[issue-create] --> I[(GitHub issue
Status: Ready)] R[issue-refine] --> I P[issue-pick] -. suggests .-> I - I --> W[worktree-start] - W --> IMPL[issue-implement
implementation + commits] + I --> W[worktree-start
completion-shape routing] + W -->|PR| IMPL[issue-implement
implementation + commits] + W -->|issue comment| INV[issue-investigate
investigation + result comment] + W -->|ambiguous| R IMPL --> AC[acceptance-check] AC --> CR[cross-review] CR --> C[PR + CI] + INV --> AC2[acceptance-check] + AC2 --> IC[close issue] classDef entry fill:#e8f4ff,stroke:#3b82f6,color:#1e3a8a classDef orch fill:#fef3c7,stroke:#d97706,color:#78350f @@ -125,9 +130,9 @@ flowchart LR classDef out fill:#f3f4f6,stroke:#6b7280,color:#1f2937 class A,R,P,W entry - class IMPL orch - class CR,AC ver - class I,C out + class IMPL,INV orch + class CR,AC,AC2 ver + class I,C,IC out ``` --- @@ -140,7 +145,7 @@ Most "spec-driven" or "plan-driven" frameworks for AI coding agents store the sp - **Versioning volatile artifacts in git is friction.** A merged plan rots in the repo, gets stale, and pollutes diffs and search. - **GitHub issues are already a versioned, queryable, time-bounded plan store.** They have state (`open` / `closed`), threading, references, and a natural lifecycle that matches the work itself. -So issuekit treats the **GitHub issue as the rich plan** for the work, and the repository contains only the durable artifacts (code, tests, configs). When the issue is closed, the plan disappears from the active surface area — exactly as intended. +So issuekit treats the **GitHub issue as the rich plan** for the work, and the repository contains only durable artifacts (code, tests, configs, and explicitly required long-lived documentation). Investigation, design, and spike results default to a structured issue comment; they become repository documents only when the acceptance criteria explicitly require a durable artifact. When the issue is closed, volatile plans and results leave the active surface area — exactly as intended. This is opinionated. issuekit will not be a good fit if you want plans to live next to the code, or if your team's workflow expects spec markdown checked in. @@ -159,9 +164,9 @@ issuekit shares one core idea with Spec Kit, cc-spex, and superpowers: **make th | [Spec Kit](https://github.com/github/spec-kit) | Spec markdown checked into the repo | Agent re-reads the spec | Teams that want specs versioned alongside code | | [cc-spex](https://github.com/rhuss/cc-spex) | Spec markdown checked into the repo | Agent re-reads the spec | Solo / small team, lighter than Spec Kit | | [superpowers](https://github.com/obra/superpowers) | Skill bundle of general-purpose engineering workflows | Skill conventions + agent judgment | Broad augmentation of Claude Code; not spec-centric | -| **issuekit** | GitHub issue body (`## 受け入れ条件`, `## スコープ外`, ...) | `acceptance-check` skill mechanically verifies each acceptance criterion as `✓ / ✗ / ?` before PR creation | Solo dev who already runs an issue-first workflow | +| **issuekit** | GitHub issue body and result comments (`## 受け入れ条件`, `## スコープ外`, ...) | `acceptance-check` mechanically verifies each criterion as `✓ / ✗ / ?` before PR creation or issue close | Solo dev who already runs an issue-first workflow | -The differentiator that matters most to issuekit's design is the **verification model**. Detailed specs help agents stay on-rails, but spec compliance is itself a problem: the longer the spec, the more places the agent can drift. issuekit's response is structural rather than prescriptive — instead of writing more spec, write fewer but **mechanically verifiable** acceptance criteria, and have a dedicated skill (`acceptance-check`) check them before PR creation. The spec stays small; the verification stays honest. +The differentiator that matters most to issuekit's design is the **verification model**. Detailed specs help agents stay on-rails, but spec compliance is itself a problem: the longer the spec, the more places the agent can drift. issuekit's response is structural rather than prescriptive — instead of writing more spec, write fewer but **mechanically verifiable** acceptance criteria, and have a dedicated skill (`acceptance-check`) check them before PR creation or issue close. The spec stays small; the verification stays honest. --- diff --git a/skills/acceptance-check/SKILL.md b/skills/acceptance-check/SKILL.md index 1f10861..f7d55cb 100644 --- a/skills/acceptance-check/SKILL.md +++ b/skills/acceptance-check/SKILL.md @@ -1,7 +1,7 @@ --- name: acceptance-check -description: GitHub issue 本文の `## 受け入れ条件` セクションを抽出し、各項目を自動検査して結果を ✓ / ✗ / ? で報告する read-only skill。`issue-implement` cycle 内で実装・commit 後・cross-review 前に呼び出して受け入れ条件確認を標準化する。 -version: 1.0.1 +description: GitHub issue 本文の `## 受け入れ条件` セクションを抽出し、repo 状態や issue コメントを根拠に各項目を ✓ / ✗ / ? で報告する read-only skill。`issue-implement` と `issue-investigate` の受け入れ条件確認を標準化する。 +version: 1.1.0 --- # Acceptance Check Skill @@ -19,7 +19,7 @@ GitHub issue の `## 受け入れ条件` セクションを機械的に抽出し ## 依存 -- **`gh` CLI**: issue 本文取得に使用する。Codex CLI 等の外部 AI ツールには依存しない。 +- **`gh` CLI**: issue 本文・コメント取得に使用する。Codex CLI 等の外部 AI ツールには依存しない。 ## 入力 @@ -27,17 +27,19 @@ GitHub issue の `## 受け入れ条件` セクションを機械的に抽出し ## 実行手順 -### 1. issue 本文の取得 +### 1. issue 本文とコメントの取得 ```bash ISSUE_NUMBER= -gh issue view "$ISSUE_NUMBER" --json body --jq '.body' +gh issue view "$ISSUE_NUMBER" --json body,comments ``` ### 2. `## 受け入れ条件` セクションの抽出 issue 本文から `## 受け入れ条件` の見出し以降〜次の `## ` 見出し直前までを取り出し、`- [ ]` または `- [x]` で始まるチェックリスト項目をすべて抽出する。 +コメント完結型 issue では `comments` も検査根拠として保持する。本文のチェック状態は完了判定に使わず、各条件と repo 状態・コメントの実体を照合する。 + 該当セクションが存在しない、または空の場合は「受け入れ条件が定義されていない」旨を報告して終了する（フォーマット不備の可能性があるので、`issue-refine` skill での整理を案内してよい）。 ### 3. 各項目の自動検査 @@ -50,6 +52,7 @@ issue 本文から `## 受け入れ条件` の見出し以降〜次の `## ` 見 | **symlink existence** | 「Stow で `~/.claude/skills/.../` にリンクされている」 | `test -L ` / `readlink` | | **文言チェック** | 「`SKILL.md` に〜と明記されている」「〜の手順が追記されている」 | `grep` / `rg` | | **command exit code** | 「`make help` が成功する」 | コマンド実行 + `$?` | +| **issue comment** | 「調査結果コメントに結論・根拠・検証内容がある」 | `comments[].body` の見出し・内容を照合 | | **要人間判定** | 「呼び出し元 agent から認識される」「UI が崩れていない」など | 自動化困難な項目はマーク | **自動化困難の判断基準**: @@ -61,6 +64,8 @@ issue 本文から `## 受け入れ条件` の見出し以降〜次の `## ` 見 これらは **`?` (要人間判定)** としてマークし、検査者（呼び出し側）に判断を委ねる。可能であれば「動作確認方法の提示」（例: 「呼び出し元 agent を再起動して `/help` で skill 一覧に現れるか確認」）も併記する。 +コメントを検査する場合は、対象 issue のコメント内に指定された結果コメントが存在するかを確認し、要求された見出し（例: `## 調査結果`、`### 結論`、`### 根拠`、`### 検証内容`、`### Blocker`、`### 却下案`、`### 後続候補`）と各見出し配下の内容を照合する。見出しや必須内容が明確に欠ければ `✗`、存在はするが内容の妥当性が自動判定できなければ `?` とする。コメントの編集やチェックリスト更新は行わない。 + ### 4. 結果報告 以下の形式で結果を出力する。 @@ -85,16 +90,18 @@ issue 本文から `## 受け入れ条件` の見出し以降〜次の `## ` 見 ## 利用タイミング - **`issue-implement` cycle 内**: 実装・commit 後、`cross-review` より前に呼び出す。`✗` がある場合は実装に戻り **追加 commit** で修正する（履歴整形はしない）。`?` のみであれば呼び出し側で人間判定を経て進む。 +- **`issue-investigate` cycle 内**: 構造化した結果コメントの投稿後、issue close より前に呼び出す。`✗` があれば調査またはコメントを補い、未解決の `?` があれば close しない。 - **手動呼び出し**: 実装完了後にユーザーが受け入れ条件のチェックを依頼した場合。 ## 失敗時の対応 -- `gh issue view` が失敗する（issue が存在しない / 認証エラー等）場合は、その旨を報告して終了する。 +- `gh issue view` が失敗する（issue が存在しない / 認証エラー等）、またはコメントを取得できない場合は、その旨を報告して終了する。 - `## 受け入れ条件` セクションが空 / 存在しない場合は、`issue-refine` skill での整理を案内する。 ## やらないこと - **issue body や code への書き込み**: 本 skill は read-only。チェックリストの `- [ ]` を `- [x]` に書き換える等もしない。 +- **コメントの投稿・編集・削除**: コメントは検査根拠として読むだけで変更しない。 - **failed 項目の自動修正**: 報告のみ行い、修正は呼び出し側の責任。 - **`## 受け入れ条件` 以外のセクションの検証**: 背景・スコープ外などは対象外。 - **動作確認の代行**: 確認方法の提示は行うが、実際の確認は呼び出し側に委ねる。 diff --git a/skills/issue-create/SKILL.md b/skills/issue-create/SKILL.md index 6ca3030..12a6dc1 100644 --- a/skills/issue-create/SKILL.md +++ b/skills/issue-create/SKILL.md @@ -1,7 +1,7 @@ --- name: issue-create -description: "Invoke for any request to create, file, open, or record a new GitHub issue. Trigger on:\n- Direct creation: 「issue 作って」「起票して」「issue 立て(といて)」「issue 化して」「issue 作れる?」\n- Record intent: 「issue に残したい/残しておいてほしい」「issue として残しておきたい」\n- Issue types: bug reports (with repro steps), feature requests, refactoring tasks, doc fixes, code-review findings to track later\n\nDo NOT trigger for viewing, listing, searching, or implementing existing issues." -version: 1.1.0 +description: "Invoke for any request to create, file, open, or record a new GitHub issue. Trigger on:\n- Direct creation: 「issue 作って」「起票して」「issue 立て(といて)」「issue 化して」「issue 作れる?」\n- Record intent: 「issue に残したい/残しておいてほしい」「issue として残しておきたい」\n- Issue types: bug reports (with repro steps), feature requests, refactoring tasks, doc fixes, investigation / design tasks, code-review findings to track later\n\nDo NOT trigger for viewing, listing, searching, or implementing existing issues." +version: 1.2.0 --- # Issue Create Skill @@ -62,6 +62,18 @@ Status の判定軸は **受け入れ条件の確定度** 一本である。言 - **依存 issue の状態（open / closed）は本文に書かない。** GitHub UI 側で close 済み issue は取り消し線で表示されるため、本文に状態を書くと二重管理になり古い情報が残るリスクがある。状態を判定したいときは `gh issue view <番号> --json state` で実体を確認する。 - `Status` との関係: `Status` は spec 自体の確定度（Ready / Draft）、`Depends on` は他 issue の完了待ちを表し、両者は独立した軸。「Ready だが Depends on あり」「Draft かつ Depends on あり」のような組み合わせもありうる。 +## 成果物と完了形 + +受け入れ条件と `## スコープ外` には、issue の完了形を判定できる情報を明記する。 + +- repo の code / test / config / durable docs の変更が完了条件に含まれる → **PR**。`issue-implement` で着手する。 +- 調査・設計・技術検証の結果を issue コメントへ記録することが完了条件で、durable な repo 変更を要求しない → **issue コメント**。`issue-investigate` で着手する。 +- 両方に該当する、または受け入れ条件とスコープ外から判別できない → **要確認**。`Status` の判定とは分けて扱い、着手前に `issue-refine` で完了形を明確にする。 + +調査・設計 issue の成果物は、デフォルトで対象 issue の結果コメントとする。公開 API 仕様、architecture decision、継続的な運用手順など、issue close 後も継続参照される durable artifact が **受け入れ条件に明示的に必要**な場合だけ repo 文書を成果物に含める。issuekit は durable artifact の保存場所を一律に決めない。 + +コメント完結型の受け入れ条件には、最低限「構造化した調査結果を対象 issue のコメントへ投稿する」を含め、必要な見出し・検証内容や close 条件を具体化する。`## 調査メモ` は着手前の情報であり、完了成果物の結果コメントとは区別する。 + ## 本文フォーマット ### 共通セクション（必須） diff --git a/skills/issue-investigate/SKILL.md b/skills/issue-investigate/SKILL.md new file mode 100644 index 0000000..b560185 --- /dev/null +++ b/skills/issue-investigate/SKILL.md @@ -0,0 +1,167 @@ +--- +name: issue-investigate +description: GitHub issue を起点に、PR や永続的な repo 変更を成果物としない調査・設計・技術検証を実行し、構造化した結果を issue コメントへ記録して受け入れ条件確認後に close する。Ready なコメント完結型 issue の着手時に使用する。 +version: 1.0.0 +--- + +# Issue Investigate Skill + +調査・設計・技術検証の結果を GitHub issue コメントへ記録して完了する orchestrator。repo の code / test / config / durable docs を成果物とする場合は `issue-implement` を使う。 + +## スコープ + +- **含む**: Status・コメント・依存・親 issue の事前確認、調査・設計・技術検証、構造化した結果コメントの投稿、`acceptance-check`、明示された後続 issue の起票、成功後の対象 issue close。 +- **含まない**: + - repo の code / test / config / durable docs を成果物とする変更、commit、cross-review、PR、CI。 + - 調査結果を保存するための新規 Markdown ファイル追加。 + - ユーザー指示や元 issue の受け入れ条件にない後続 issue の自動起票。 + +## 依存 + +- **`issuekit:acceptance-check` skill**: 結果コメント投稿後、対象 issue の受け入れ条件を read-only で検査する。APM plain-skill mode では `acceptance-check` として呼び出す。 +- **`issuekit:issue-create` skill**: 明示的に要求された後続 issue を起票する場合だけ使用する。APM plain-skill mode では `issue-create` として呼び出す。 +- **`gh` CLI**: issue・コメント・親子関係の取得、コメント投稿、close に使用する。 +- 調査対象に応じた read-only コマンドや検証ツール。repo を一時変更する検証は後述の安全条件を満たす場合だけ行う。 + +## 入力 + +- issue URL または issue 番号。 + +対象 issue の完了形が「issue コメント」であることを前提とする。受け入れ条件と `## スコープ外` を読み、repo の code / test / config / durable docs の変更も完了条件に含む、または完了形を判別できない場合は着手せず `issue-refine` を案内する。 + +## 実行手順 + +### 1. issue 本文・コメント・Status の確認 + +```bash +ISSUE_NUMBER= +gh issue view "$ISSUE_NUMBER" --comments +gh issue view "$ISSUE_NUMBER" --json title,body,updatedAt,comments +``` + +- 本文先頭が `Status: Ready` であることを確認する。`Status: Draft` または表記不完全なら着手せず `issue-refine` を案内する。 +- コメントを時系列で読み、本文との矛盾、未解決 blocker、方針保留、受け入れ条件の未反映変更がないことを確認する。`updatedAt` と時系列でも意図を確定できなければ着手しない。 +- 受け入れ条件とスコープ外から完了形を判定する。調査結果のコメント記録が完了条件で、durable な repo 変更を要求しない場合だけ続行する。PR とコメントの両方に該当する、または判別不能なら自動着手せず `issue-refine` を案内する。 + +### 2. Depends on の確認 + +本文に `Depends on: #N, #M` があれば、各 issue の実際の state を取得する。 + +```bash +gh issue view <依存 issue 番号> --json state --jq '.state' +``` + +1 件でも open なら着手しない。依存状態を本文へ書き戻さない。 + +### 3. 親 issue の確認 + +本文の `親: #N` と GitHub sub-issue parent endpoint の両方を確認し、親があれば本文とコメントを読む。 + +```bash +REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner') +gh api "repos/${REPO}/issues/${ISSUE_NUMBER}/parent" --jq '{number, title, state}' +gh issue view <親 issue 番号> --comments +``` + +parent endpoint の 404 は「親なし」として扱い、それ以外の取得失敗では着手しない。両経路で親が見つかった場合は和集合を取り、重複を除く。親の方針と対象 issue が矛盾し、時系列から解決できなければ着手しない。 + +### 4. 作業状態の記録と検証方法の決定 + +調査開始時に `git status --short` と必要に応じて `git diff` / `git diff --cached` を確認し、既存のユーザー変更を記録する。 + +- 原則として read-only な調査を優先する。 +- 一時的な repo 変更が必要なら、開始時点が clean な専用 worktree / branch 等、調査由来の差分をユーザー変更と確実に区別できる環境でのみ行う。既存変更がある環境では一時変更を行わず、別の clean な作業環境をユーザーに用意してもらう。 +- ユーザーの既存変更を `git reset`、`git checkout --`、`git clean`、手動上書き等で破棄しない。 +- 一時変更は commit せず、PR も作らない。検証コマンドと観測結果を記録してから、調査で追加・変更した対象だけを元に戻す。開始時点の snapshot と照合できない変更には触れない。 + +### 5. 調査・設計・技術検証 + +issue の受け入れ条件と調査方針に沿って、必要なソース・公式文書・履歴・実行結果を確認する。バージョンや仕様など変わりうる情報は最新の一次情報を確認し、結果コメントに URL を残す。 + +途中で blocker が見つかっても、判明した事実と未検証範囲を整理する。blocker により受け入れ条件を満たせない場合は結果コメントを投稿しても完了扱いにせず、issue を close しない。 + +### 6. 結果コメントの投稿 + +以下の構造を保ち、該当事項がない見出しも `なし` と明記してコメントを投稿する。これにより `acceptance-check` がコメントの存在と必須項目を検査できる。 + +```md +## 調査結果 + +### 結論 + +<採用する結論、または現時点で結論不能である旨> + +### 根拠 + +- <ソース、公式 URL、観測事実> + +### 検証内容 + +- <実行した手順 / コマンドと結果> + +### Blocker + +- なし + +### 却下案 + +- <案と却下理由、なければ「なし」> + +### 後続候補 + +- <候補と理由、なければ「なし」。未起票なら候補であることを明記> +``` + +```bash +gh issue comment "$ISSUE_NUMBER" --body-file - <<'EOF' +## 調査結果 +... +EOF +``` + +### 7. 一時差分が残っていないことの確認 + +結果投稿前後に `git status --short` を再取得し、step 4 の開始時点と比較する。調査由来の差分が 1 件でも残っていれば完了扱いにせず、安全に所有権を特定できる差分だけを戻して再確認する。開始時点に存在したユーザー変更は同じ状態で保持する。 + +### 8. 受け入れ条件チェック + +結果コメント投稿と一時差分の確認後に `issuekit:acceptance-check `（APM plain-skill mode では `acceptance-check `）を呼び出す。コメント完結型の条件は `gh issue view "$ISSUE_NUMBER" --json body,comments` を根拠に検査する。 + +- `✗` があれば調査または結果コメントを補い、再検査する。 +- `?` は呼び出し側で可能な確認を行う。判定できない項目が残れば close しない。 +- すべての項目が `✓`、または根拠を伴って呼び出し側が充足と判定できた場合だけ次へ進む。 + +### 9. 明示された後続 issue の起票 + +元 issue の受け入れ条件またはユーザー指示に「後続 issue を起票する」と明記されている場合だけ、`issue-create` の手順で起票する。明記がなければ、step 6 の `### 後続候補` に提案を残すだけで起票しない。 + +### 10. issue の close と完了報告 + +次の全条件を満たした後でのみ対象 issue を close する。 + +1. 構造化した結果コメントの投稿に成功した。 +2. 調査由来の repo 差分が残っていない。 +3. `acceptance-check` で未達・未判定項目がない。 +4. 明示的に要求された後続 issue の起票に成功した。 + +```bash +gh issue close "$ISSUE_NUMBER" +``` + +結果コメント URL、受け入れ条件チェックのサマリー、close 結果、起票した後続 issue（ある場合）をユーザーへ返す。 + +## 失敗時の対応 + +- issue / コメント / 親 / 依存の取得に失敗した場合は着手せず、取得できなかった対象を報告する。 +- コメント投稿に失敗した場合は close しない。結果をローカルの新規 Markdown として保存せず、再投稿可能な内容を会話内で保持してエラーを報告する。 +- 一時変更を安全に元へ戻せない、またはユーザー変更との区別がつかない場合は操作を止め、差分を残したまま対象と理由を報告する。ユーザー変更を推測で破棄しない。 +- `acceptance-check` に `✗` / 未解決の `?` がある、明示された後続 issue の起票に失敗した、または `gh issue close` が失敗した場合は途中成功を明示し、close 済みと報告しない。 + +## やらないこと + +- 調査結果を新規 Markdown として repo に追加しない。 +- 調査中の一時変更を commit、push、PR 化しない。`cross-review` や CI も実行しない。 +- 開始時点に存在したユーザー変更を破棄・上書き・整形しない。 +- 結果コメント投稿前、受け入れ条件確認前、一時差分解消前、明示された後続 issue 起票前に対象 issue を close しない。 +- 元 issue の受け入れ条件またはユーザー指示にない後続 issue を起票しない。 +- repo 変更を含む issue や完了形が曖昧な issue を `issue-investigate` へ強行しない。`issue-refine` で完了形を明確にする。 diff --git a/skills/issue-pick/SKILL.md b/skills/issue-pick/SKILL.md index 1f01d6f..6f44df3 100644 --- a/skills/issue-pick/SKILL.md +++ b/skills/issue-pick/SKILL.md @@ -1,7 +1,7 @@ --- name: issue-pick description: "Use when the user has NOT yet decided which issue to work on and needs help choosing. This is the pre-decision advisory phase: the user is weighing multiple open issues and wants structured guidance — not implementation. Key triggers: asking which issue to prioritize or tackle next, identifying which issues are blocked vs. ready to start independently, selecting issues that fit limited capacity (small/high-impact), or finding independent issues for parallel worktree sessions. The user's state is \"I have several candidates and don't know where to start.\" Provides ranked recommendation (1 pick + 1-2 alternates) across impact/dependencies/size/urgency — read-only, no state changes." -version: 1.0.4 +version: 1.1.0 --- # Issue Pick Skill @@ -16,7 +16,7 @@ version: 1.0.4 - **ranking の永続化**: 出力は揮発的な advisory に留め、優先度を保存する仕組みを持たない。 - **重み付け**: 観点ごとの重み付けやスコアリングはしない。文脈依存の判断 (好み・気分・直近の関心) は人間に委ねる。 - **assigned filter**: 個人リポジトリでは無意味のため非対応。 - - **自動着手**: `issuekit:issue-implement` skill との連携は user 経由のみ。APM plain-skill mode では `issue-implement` として案内する。skill 内で chain しない。 + - **自動着手**: `issuekit:issue-implement` / `issuekit:issue-investigate` skill との連携は user 経由のみ。APM plain-skill mode では bare skill 名で案内する。skill 内で chain しない。 ## 依存 @@ -45,7 +45,7 @@ gh issue list --state open --limit 1000 --json number,title,labels,body,createdA 各 issue の本文先頭の `Status:` 行を確認し、対象を絞り込む。 -- **デフォルト**: `Status: Ready` の issue のみを残す。`Status:` 表記が無い issue や `Status: Draft` の issue は **除外** する (それらは `issuekit:issue-implement`、または APM plain-skill mode の `issue-implement` で Ready 確認時にも弾かれるため、推奨に含めると整合しない)。 +- **デフォルト**: `Status: Ready` の issue のみを残す。`Status:` 表記が無い issue や `Status: Draft` の issue は **除外** する (着手 orchestrator は Ready 確認時に弾くため、推奨に含めると整合しない)。 - **`--include-draft` 指定時**: `Status: Ready` と `Status: Draft` の issue を残す。`Status:` 表記が無い issue は依然として除外する。 - フォーマット不完全な issue があった場合は、出力末尾の hint に「`/issuekit:issue-refine <番号>` で整理を促す」旨を案内してよい (推奨候補としては扱わない)。 @@ -102,7 +102,7 @@ done 親 issue 本文の取得には別途 `gh issue view <親番号>` が必要。blocker 判定が出力に効く場合のみ取得し、不要な fetch は避ける。 -### 5. 4 観点での構造化 +### 5. 4 観点と完了形での構造化 各候補 issue について、以下 4 観点で判断材料を整理する。 @@ -115,6 +115,12 @@ done 各観点は issue 本文・コメント・labels・親子関係から読み取れる範囲で整理し、推測が必要な場合は「(推測)」と明示する。コメント上の要確認点がある issue は、推奨 / 補欠ではなく要確認候補として分離する。 +4 観点は維持したまま、各候補の受け入れ条件と `## スコープ外` を `issue-create` の「成果物と完了形」に照らして、次のいずれかを必ず併記する。 + +- **PR**: repo の code / test / config / durable docs の変更が完了条件に含まれる。 +- **issue コメント**: 調査・設計・技術検証の結果コメントが完了条件で、durable な repo 変更を要求しない。 +- **要確認**: 両方に該当する、または判別不能。Status が Ready でも自動着手先を決めず `issue-refine` を案内する。 + ### 6. 推奨と補欠の提示 整理結果から **推奨 1 件 + 補欠 1〜2 件** を選び、理由とともに提示する。 @@ -128,8 +134,9 @@ done markdown 散文 + 観点別の箇条書きで出力する。出力末尾には次のアクションを促す **hint 行** を必ず含める。推奨 issue の Status により hint を分岐させる: -- 推奨が `Status: Ready`: plugin mode では `/issuekit:issue-implement <番号>`、APM plain-skill mode では `issue-implement <番号>` を案内する。 -- 推奨が `Status: Draft` (`--include-draft` 指定時のみ): plugin mode では `/issuekit:issue-refine <番号>`、APM plain-skill mode では `issue-refine <番号>` で先に Ready 化を促す (`issuekit:issue-implement` / `issue-implement` は Draft を弾くため)。 +- 推奨が `Status: Ready` + 完了形 `PR`: plugin mode では `/issuekit:issue-implement <番号>`、APM plain-skill mode では `issue-implement <番号>` を案内する。 +- 推奨が `Status: Ready` + 完了形 `issue コメント`: plugin mode では `/issuekit:issue-investigate <番号>`、APM plain-skill mode では `issue-investigate <番号>` を案内する。 +- 推奨が完了形 `要確認`、または `Status: Draft` (`--include-draft` 指定時のみ): plugin mode では `/issuekit:issue-refine <番号>`、APM plain-skill mode では `issue-refine <番号>` を案内する。 ```md ## 着手候補 @@ -140,6 +147,7 @@ markdown 散文 + 観点別の箇条書きで出力する。出力末尾には - 依存・blocker: ... - 規模: ... - 緊急度: ... +- 完了形: PR / issue コメント / 要確認 理由: <4 観点のどれを重視したかを含めた散文の説明> @@ -149,6 +157,7 @@ markdown 散文 + 観点別の箇条書きで出力する。出力末尾には - 依存・blocker: ... - 規模: ... - 緊急度: ... +- 完了形: PR / issue コメント / 要確認 理由: <なぜ推奨ではなく補欠なのか> @@ -161,9 +170,9 @@ markdown 散文 + 観点別の箇条書きで出力する。出力末尾には --- -着手する場合は `/issuekit:issue-implement <番号>` を呼んでください。 -APM plain-skill mode では `issue-implement <番号>` を呼んでください。 -(推奨が Draft の場合は代わりに `/issuekit:issue-refine <番号>`、APM plain-skill mode では `issue-refine <番号>` を案内) +PR に着手する場合は `/issuekit:issue-implement <番号>`、issue コメント完結の調査に着手する場合は `/issuekit:issue-investigate <番号>` を呼んでください。 +APM plain-skill mode ではそれぞれ `issue-implement <番号>` / `issue-investigate <番号>` を呼んでください。 +(推奨が Draft または完了形が要確認の場合は `/issuekit:issue-refine <番号>`、APM plain-skill mode では `issue-refine <番号>` を案内) ``` ## 重み付けについて @@ -190,5 +199,5 @@ skill は **観点を統一フォーマットで提示するところまで** - **issue body / labels / Projects v2 等の state 変更**: 本 skill は完全に read-only。 - **ranking 全件の出力**: 推奨 1 + 補欠 1〜2 件のみ。優先度の永続化と紛らわしくしないため。 - **重み付け / スコアリング**: 観点を提示するに留め、数値化はしない。 -- **`issuekit:issue-implement` への自動 chain**: 出力末尾の hint 行のみ。APM plain-skill mode では `issue-implement` として案内する。skill 内で自動呼び出しはしない。 +- **着手 orchestrator への自動 chain**: `issuekit:issue-implement` / `issuekit:issue-investigate` は出力末尾の hint 行で案内するだけ。APM plain-skill mode では bare skill 名として案内し、skill 内で自動呼び出しはしない。 - **assigned filter**: 個人リポジトリでは無意味のためサポートしない。 diff --git a/skills/issue-refine/SKILL.md b/skills/issue-refine/SKILL.md index d4fa4b2..0e1079d 100644 --- a/skills/issue-refine/SKILL.md +++ b/skills/issue-refine/SKILL.md @@ -1,7 +1,7 @@ --- name: issue-refine description: 既存の GitHub issue を `issue-create` skill のフォーマットに沿って整理する。タイトルのみで起票された issue や、フォーマット不完全な issue を後から rich plan に仕上げ直したい場合に使用する。 -version: 1.1.0 +version: 1.2.0 --- # Issue Refine Skill @@ -16,7 +16,7 @@ version: 1.1.0 | 操作 | `gh issue create` | `gh issue edit` | | 起点 | 白紙 | 既存本文を尊重して差分整理 | -フォーマット観点（共通セクション、Status 判定、親子 issue の扱い）は **`issue-create` skill を参照する**。本 skill では重複定義しない。 +フォーマット観点（共通セクション、Status 判定、成果物と完了形、親子 issue の扱い）は **`issue-create` skill を参照する**。本 skill では重複定義しない。 ## 実行手順 @@ -38,6 +38,8 @@ gh issue view "$ISSUE_NUMBER" - `Status: Draft` の場合、`## Ready にするための未決事項` があり、受け入れ条件を確定するための具体的な問いが列挙されているか - 親 issue がある場合の親リンクと「実装前に親 issue を必ず読むこと」明記 - 追加セクション（実装方針 / 再現手順 / 調査メモ等）の必要性 +- `issue-create` の「成果物と完了形」に照らし、受け入れ条件とスコープ外から完了形を「PR」「issue コメント」「要確認」のいずれかに判定できるか +- 調査・設計 issue では、成果物が結果コメントか明示的な durable artifact か、コメントに必要な項目と close 条件が受け入れ条件に書かれているか ### 3. 対話で不足を埋める @@ -47,6 +49,8 @@ gh issue view "$ISSUE_NUMBER" 既存の本文は **可能な限り尊重する**。表現を勝手に書き換えず、追記・補完を中心に進める。意図が不明な記述があればユーザーに確認してから整える。 +調査・設計 issue は `issue-create` の「成果物と完了形」を参照し、デフォルトを issue コメントとする。durable artifact が必要なら、その必要性と対象を受け入れ条件へ明記する。PR とコメントの両方に該当する、または判別不能なままなら、完了形をユーザーに確認して受け入れ条件とスコープ外へ反映する。 + ### 4. Status の再評価 `issue-create` skill の「Status > Draft とする条件」に従い、整理後の本文で Status を再判定する。判定軸は **受け入れ条件の確定度** 一本。 @@ -99,7 +103,7 @@ gh api "repos/${REPO}/issues/${PARENT_ISSUE_NUMBER}/sub_issues" \ ### 7. 完了報告 -更新後の issue URL と Status をユーザーに返す。`Status: Ready` になった場合は、続けて `issue-implement` skill で実装に進めることを案内してよい。 +更新後の issue URL、Status、完了形をユーザーに返す。`Status: Ready` になった場合は、完了形が PR なら `issue-implement`、issue コメントなら `issue-investigate` で進めることを案内する。要確認のままなら着手 skill を案内しない。 ## やらないこと diff --git a/skills/worktree-start/SKILL.md b/skills/worktree-start/SKILL.md index 38ece53..83572a6 100644 --- a/skills/worktree-start/SKILL.md +++ b/skills/worktree-start/SKILL.md @@ -1,22 +1,22 @@ --- name: worktree-start -description: "Claude Code 専用。素の `claude` で起動した直後に、タスク説明または issue URL / 番号から命名した git worktree へ `EnterWorktree` で切り替えて作業を開始する。issue 起点・タスク起点どちらでも並列セッション立ち上げに使う。issue URL / 番号入力で Status: Ready かつコメント上の未解決事項がない場合は worktree 切り替え後に `issue-implement` へ自動連鎖する。" -version: 1.0.4 +description: "Claude Code 専用。タスク説明または issue URL / 番号から命名した git worktree へ `EnterWorktree` で切り替える。Ready issue は完了形を判定し、PR なら `issue-implement`、コメント完結型なら `issue-investigate` へ連鎖し、要確認なら `issue-refine` を案内する。" +version: 1.1.0 --- # Worktree Start Skill -Claude Code が v2.1.49 で導入した `EnterWorktree` ツールを使い、起動済みセッションの cwd を新規 git worktree に切り替えて並列タスクを開始する skill。`issue-implement` が「issue 起点の実装サイクル」の orchestrator であるのに対し、本 skill は **issue 起点・タスク起点どちらでも入れる entry point** として並ぶ。 +Claude Code が v2.1.49 で導入した `EnterWorktree` ツールを使い、起動済みセッションの cwd を新規 git worktree に切り替えて並列タスクを開始する skill。`issue-implement` は PR 完結、`issue-investigate` はコメント完結の orchestrator であり、本 skill は **issue 起点・タスク起点どちらでも入れる entry point** として完了形に応じた経路へつなぐ。 ## スコープ -- **含む**: タスク説明 / issue URL / issue 番号からのブランチ名生成 (LLM 命名 or ユーザー明示指定の受領)、`EnterWorktree` ツール呼び出しによるセッション cwd 切り替え、既存 worktree 内での no-op 判定、issue 入力時の Status とコメント確認、着手可能な Ready 時の `issue-implement` への引き継ぎ。 +- **含む**: タスク説明 / issue URL / issue 番号からのブランチ名生成、`EnterWorktree` による cwd 切り替え、既存 worktree 内での no-op 判定、issue 入力時の Status・コメント・完了形の確認、着手可能な Ready issue の適切な orchestrator への引き継ぎ。 - **含まない**: - **外部タブ管理ツール (ターミナルマルチプレクサ等) との連携**: 並列タブの起動はユーザー操作のまま。 - **Codex CLI / 他 agent 用の fallback 実装**: `EnterWorktree` は Claude Code 固有で、他 runtime には対応 primitive が存在しない。 - **`EnterWorktree` の `path` パラメータでクリーン命名する回避策**: `worktree-` prefix 強制を許容する方針 (issue #13 スコープ外)。 - **作成済み worktree のクリーンアップ**: `ExitWorktree` / `git worktree remove` 等は呼ばない。 - - **Status: Draft / フォーマット不完全な issue 入力時の `issue-implement` 連鎖**: 受け入れ条件が確定していない issue は着手対象外。worktree 作成のみ行い `issue-refine` を案内する。 + - **Draft / フォーマット不完全 / 完了形が要確認な issue の着手連鎖**: worktree 作成のみ行い `issue-refine` を案内する。 ## 利用タイミング @@ -41,9 +41,9 @@ Claude Code が v2.1.49 で導入した `EnterWorktree` ツールを使い、起 - `Depends on:` がすべて close 済み - 親 issue の文脈取り込み -そのため `issue-implement` から呼ばれた際は、本 skill 側で再度 `gh issue view` による Status / Depends on / 親 issue の検証は行わない（**Status チェックは上流に委譲**）。具体的には、上流から渡されるのは **issue 番号ではなく事前生成済みのブランチ名 slug** (`-` 形式) のみであり、本 skill はそれを step 2 の「タスク説明モード」と同じ経路で扱う。issue 番号を伴う入力経路 (Status 判定 → Ready 時に `issue-implement` 連鎖) には入らないため、`issue-implement → worktree-start → issue-implement` の再帰連鎖は発生しない。 +そのため `issue-implement` から呼ばれた際は、本 skill 側で再度 `gh issue view` による Status / Depends on / 親 issue の検証は行わない（**Status チェックは上流に委譲**）。具体的には、上流から渡されるのは **issue 番号ではなく事前生成済みのブランチ名 slug** (`-` 形式) のみであり、本 skill はそれを step 2 の「タスク説明モード」と同じ経路で扱う。issue 番号を伴う入力経路 (Status・完了形判定 → 対応 orchestrator への連鎖) には入らないため、`issue-implement → worktree-start → issue-implement` の再帰連鎖は発生しない。 -万一上流が誤って issue 番号を渡してしまった場合でも、step 2 の Ready 経路から `issue-implement` を呼び出すと、その呼び出し先 `issue-implement` が再度本 skill を呼び出した時点で step 1 の no-op 判定 (現セッションが既に worktree 内) に引っかかり何もしないため、循環は二重チェックで自動的に止まる。とはいえ無駄な再呼び出しを避けるため、上流からは必ずブランチ名 slug のみを渡す運用にすること (詳細は `issue-implement` の "やらないこと" 節を参照)。 +万一上流が誤って issue 番号を渡してしまった場合、step 2 で完了形を再判定して対応 orchestrator を余分に呼ぶことになる。PR 経路で `issue-implement` が再度本 skill を呼び出しても、step 1 の no-op 判定で循環は止まる。とはいえ無駄な再呼び出しと誤ルーティングを避けるため、上流からは必ずブランチ名 slug のみを渡す運用にすること (詳細は `issue-implement` の "やらないこと" 節を参照)。 ## 依存 @@ -59,7 +59,7 @@ Claude Code が v2.1.49 で導入した `EnterWorktree` ツールを使い、起 - **issue URL**: `https://github.com///issues/` 形式。 - **issue 番号**: `#42` / `42` 単体。 -issue URL / 番号が渡された場合は、本 skill 側で `gh issue view --comments` を呼び出して title (ブランチ名生成用)、Status (連鎖判定用)、コメントの補足文脈を取得する。**Status の判定軸は `issue-create` の定義 (受け入れ条件の確定度) に従う**。 +issue URL / 番号が渡された場合は、本 skill 側で `gh issue view --comments` を呼び出して title (ブランチ名生成用)、Status と完了形 (連鎖判定用)、コメントの補足文脈を取得する。**Status と完了形は `issue-create` の定義に従う**。 ## 実行手順 @@ -74,15 +74,15 @@ issue URL / 番号が渡された場合は、本 skill 側で `gh issue view --c `EnterWorktree` を投機的に呼んでツール側のエラーで気付く運用は避ける。skill 側で先に判定し、ユーザーには「すでに worktree 内のため何もしません」と返す。 -### 2. 入力タイプの判定と issue 取得 +### 2. 入力タイプ、Status、完了形の判定 ユーザー入力を以下に分類する: - **タスク説明 (issue なし)**: そのまま step 3 のブランチ名生成へ進む。issue 連鎖は行わない (step 5 はスキップ)。`issue-implement` 上流から呼ばれた場合 (= 事前生成済みブランチ名 slug が渡される) もこの経路で扱い、Status 判定や `gh issue view` は走らせない。 - **issue URL / 番号**: URL から番号を抽出し、`gh issue view --comments` で本文、title、コメントを取得する。本文先頭の `Status:` を確認し、コメントに本文未反映の補足や矛盾がないかも確認して以下に分岐する。本文とコメントが矛盾する場合は、`updatedAt` やコメント時系列を踏まえて最新の意図を推定し、判断できないものだけを要確認として扱う: - - **`Status: Ready` かつコメントに未解決 blocker / 本文との矛盾 / 方針保留 / 受け入れ条件の未反映変更が無い**: 連鎖対象。step 3 でブランチ名を生成し、step 4 完了後 step 5 で `issue-implement` へ引き継ぐ。 - - **`Status: Ready` だがコメントに未解決 blocker / 本文との矛盾 / 方針保留 / 受け入れ条件の未反映変更がある**: 受け入れ条件や前提が揺らいでいるため `issue-implement` への連鎖は **行わない**。worktree は作成して切り替えるが、step 6 の完了報告でコメント上の要確認点を示し、ユーザー確認または `issue-refine` での整理を案内する。 - - **`Status: Draft`**: 受け入れ条件が未確定なため `issue-implement` への連鎖は **行わない**。worktree は作成して切り替えるが、step 6 の完了報告で `issuekit:issue-refine` skill (APM plain-skill mode では `issue-refine`) での整理を案内する。 + - **`Status: Ready` かつコメントに未解決事項がない**: 受け入れ条件と `## スコープ外` を `issue-create` の「成果物と完了形」に照らす。repo 変更が完了条件なら **PR**、結果コメントだけなら **issue コメント**、両方または判別不能なら **要確認** とする。 + - **`Status: Ready` だがコメントに未解決 blocker / 本文との矛盾 / 方針保留 / 受け入れ条件の未反映変更がある**: 完了形にかかわらず着手連鎖を行わず、ユーザー確認または `issue-refine` を案内する。 + - **`Status: Draft`**: 着手連鎖を行わず `issuekit:issue-refine`（APM plain-skill mode では `issue-refine`）を案内する。 - **`Status:` 表記なし / フォーマット不完全**: 同様に連鎖せず、`issue-refine` を案内する。 ### 3. ブランチ名の決定 @@ -105,21 +105,26 @@ EnterWorktree({ name: "slack-oauth-flow-42" }) 成功すれば現在のセッションの cwd が新規 worktree (`worktree-slack-oauth-flow-42` 系のブランチ + 対応ディレクトリ) に切り替わる。以降のツール呼び出しは新 worktree 上で動作する。 -### 5. (issue Ready 時のみ) `issue-implement` への引き継ぎ +### 5. (issue Ready 時のみ) 完了形に応じた引き継ぎ -step 2 で **issue URL / 番号 + `Status: Ready` + コメント上の未解決 blocker / 本文矛盾 / 方針保留 / 受け入れ条件の未反映変更なし** だった場合のみ、`issuekit:issue-implement` skill (APM plain-skill mode では `issue-implement`) を該当 issue 番号で呼び出し、issue 駆動の実装サイクルへ引き継ぐ。 +step 2 で **issue URL / 番号 + `Status: Ready` + コメント上の未解決事項なし** だった場合、完了形に応じて分岐する。 -- 引き継ぎ前にユーザーへの確認は挟まない。Ready は「着手 OK」のシグナルとして扱う方針 (`issue-create` の Status 定義に従う)。 -- 連鎖後の Status / Depends on / 親 issue 確認・実装と適宜 commit・受け入れ条件チェック・cross-review・PR・CI は `issue-implement` 側の責務。本 skill はあくまで worktree 切り替えと引き継ぎのみを行う。 +- **PR**: `issuekit:issue-implement `（APM plain-skill mode では `issue-implement `）へ引き継ぐ。 +- **issue コメント**: `issuekit:issue-investigate `（APM plain-skill mode では `issue-investigate `）へ引き継ぐ。 +- **要確認**: 自動連鎖せず `issuekit:issue-refine `（APM plain-skill mode では `issue-refine `）を案内する。 -それ以外 (タスク説明 / Draft / 表記なし) は引き継ぎを行わず、step 6 の完了報告のみで終わる。 +- PR または issue コメントと判定できた Ready issue は、引き継ぎ前にユーザー確認を挟まない。Ready は受け入れ条件が確定したシグナルであり、完了形が要確認なら `issue-refine` へ戻す。 +- 連鎖後の Status / Depends on / 親 issue 再確認と各 cycle の完了処理は呼び出し先 orchestrator の責務。本 skill は worktree 切り替えと引き継ぎだけを行う。 + +それ以外 (タスク説明 / Draft / 表記なし / 完了形が要確認) は着手 orchestrator へ引き継がず、step 6 の完了報告のみで終わる。 ### 6. 完了報告 ユーザーには以下を返す: - 入った worktree のパス (新 cwd) と作成されたブランチ名 (`worktree-` prefix 込み)。 -- **issue Ready で連鎖した場合**: `issue-implement ` を起動済みで、続けて issue サイクルが進むこと。 +- **issue Ready で連鎖した場合**: 判定した完了形と、`issue-implement ` または `issue-investigate ` を起動済みであること。 +- **issue Ready だが完了形が要確認の場合**: 自動連鎖せず、`issue-refine` で完了形を整理する案内。worktree は既に作成済み。 - **issue Ready だがコメント上の要確認点があり連鎖しなかった場合**: 要確認点を列挙し、ユーザー確認または `issue-refine` で整理してから再度呼ぶ案内。worktree は既に作成済み。 - **issue Draft / 表記なしの場合**: `issue-refine` で整理してから再度呼ぶ案内。worktree は既に作成済み。 - **タスク説明の場合**: 「次は何をしますか?」の確認 (そのまま実装に入る、別 skill を呼ぶ、など)。 @@ -135,8 +140,8 @@ step 2 で **issue URL / 番号 + `Status: Ready` + コメント上の未解決 - **既に worktree 内にいるセッションでの再進入**: 上記 step 1 で no-op として返す。`EnterWorktree` 自体も再進入を拒否するため、二重チェック構造で安全側に倒す。 - **外部タブ / ペインの自動起動**: 並列タブの起動はユーザー操作のまま。skill から外部のターミナルマルチプレクサ等を直接操作しない。 -- **Status: Draft / フォーマット不完全な issue 入力時の `issue-implement` 連鎖**: 受け入れ条件が確定していない issue は着手対象外。worktree 作成までで止め、`issue-refine` を案内する。Status の判定軸は `issue-create` の定義 (受け入れ条件の確定度) に従う。 -- **タスク説明 (issue なし) 入力時の `issue-implement` 連鎖**: issue 番号が文字列として登場しても、URL / 番号として明示入力されていなければ `gh issue view` を呼ばずタスク説明として扱う。連鎖は行わない。 +- **Draft / フォーマット不完全 / 完了形が要確認な issue の着手連鎖**: worktree 作成までで止め、`issue-refine` を案内する。Status と完了形は `issue-create` の定義に従う。 +- **タスク説明 (issue なし) 入力時の着手 orchestrator 連鎖**: issue 番号が文字列として登場しても、URL / 番号として明示入力されていなければ `gh issue view` を呼ばずタスク説明として扱う。連鎖は行わない。 - **Codex CLI / 他 agent 用の fallback 実装**: 本 skill は Claude Code 専用。「Claude Code 限定であること」セクション参照。 - **`EnterWorktree` の `path` パラメータでクリーン命名を試みる**: `worktree-` prefix 強制を許容する方針 (issue #13 スコープ外)。 - **作成済み worktree のクリーンアップ**: `ExitWorktree` / `git worktree remove` 等は呼ばない。worktree のライフサイクル管理はユーザー責務。 From 7bcb73d468f59f6c05f9a65d6e73ec720e6c95e2 Mon Sep 17 00:00:00 2001 From: Hiroki SAKABE Date: Sun, 2 Aug 2026 00:40:43 +0900 Subject: [PATCH 2/3] fix: tighten investigation workflow guards --- AGENTS.md | 1 + README.md | 2 +- skills/acceptance-check/SKILL.md | 8 ++++++-- skills/issue-implement/SKILL.md | 17 +++++++++++++---- skills/issue-investigate/SKILL.md | 28 +++++++++++++++++----------- 5 files changed, 38 insertions(+), 18 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3f74642..f450fce 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,6 +17,7 @@ The bundle codifies an **issue-driven development** workflow where the GitHub is - `issue-implement` → `acceptance-check` (verifies `## 受け入れ条件` against the final repo state after implementation+commits, **before** `cross-review` so an acceptance ✗ does not waste a cross-review pass) - `issue-implement` → `cross-review` (second-opinion code review of the `base...HEAD` diff after `acceptance-check` passes, before PR creation; review fixes land as additional commits, not amends) - `issue-implement` → `worktree-start` (**conditional**, before implementation in `issue-implement` step 4): fires only when **all four** conditions hold — `EnterWorktree` is available (= Claude Code runtime), the session is outside any worktree (`git rev-parse --git-common-dir` == `--git-dir`), the current branch is the repo's default branch (`gh repo view --json defaultBranchRef`), and `Status: Ready`. `Status: Draft` triggers an early abort in step 1, so the worktree is never created for Draft issues. +- `issue-implement` guards its direct-entry path with the same completion-shape rule: only PR-shaped Ready issues continue; comment-shaped issues stop with an `issue-investigate` recommendation, and ambiguous issues stop with an `issue-refine` recommendation. - `worktree-start` → `issue-implement` or `issue-investigate` (**only** when input is an issue URL/number with `Status: Ready` and a clear completion shape; PR-shaped issues route to `issue-implement`, comment-shaped issues route to `issue-investigate`, and ambiguous issues stop after the worktree switch with an `issue-refine` recommendation) - `issue-create` / `issue-refine` / `issue-pick` are entry points; they do not chain into other skills. `issue-pick` is a triage entry point and does not chain (see its "やらないこと" — handing off to `issue-implement` or `issue-investigate` is via user only). diff --git a/README.md b/README.md index 7fde501..085a646 100644 --- a/README.md +++ b/README.md @@ -94,7 +94,7 @@ issuekit ships eight 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 into a new worktree, then route a Ready issue to `issue-implement` (PR), `issue-investigate` (issue comment), or `issue-refine` (ambiguous). | -| `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`. | +| `issue-implement` | Orchestrator| Guard for PR-shaped work, then drive 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`. | | `issue-investigate` | Orchestrator| Investigate, design, or run a technical spike without durable repo changes; post a structured result comment, run acceptance checks, then close the issue on success. | | `acceptance-check` | Verifier | Read-only verifier that extracts `## 受け入れ条件` and checks repo state or issue comments, reporting each item as `✓ / ✗ / ?`. Called by both orchestrators before completion. | | `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. | diff --git a/skills/acceptance-check/SKILL.md b/skills/acceptance-check/SKILL.md index f7d55cb..068d138 100644 --- a/skills/acceptance-check/SKILL.md +++ b/skills/acceptance-check/SKILL.md @@ -24,6 +24,7 @@ GitHub issue の `## 受け入れ条件` セクションを機械的に抽出し ## 入力 - issue 番号 +- 結果コメントを条件として検査する場合: `--result-comment <コメント URL または ID>`。`issue-investigate` が今回投稿した単一コメントを渡す。 ## 実行手順 @@ -38,7 +39,9 @@ gh issue view "$ISSUE_NUMBER" --json body,comments issue 本文から `## 受け入れ条件` の見出し以降〜次の `## ` 見出し直前までを取り出し、`- [ ]` または `- [x]` で始まるチェックリスト項目をすべて抽出する。 -コメント完結型 issue では `comments` も検査根拠として保持する。本文のチェック状態は完了判定に使わず、各条件と repo 状態・コメントの実体を照合する。 +コメント完結型 issue では `comments` も検査根拠として保持する。`--result-comment` が渡された場合は URL または ID が一致する単一コメントを抽出し、その本文だけを今回の結果コメントとして扱う。本文のチェック状態は完了判定に使わず、各条件と repo 状態・指定コメントの実体を照合する。 + +結果コメントを要求する受け入れ条件があるのに `--result-comment` がない場合は、過去コメントを横断検索して推測せず `?` とする。指定された URL / ID に一致するコメントがなければ `✗` とする。再投稿時は呼び出し側が新しい識別子を渡し、古い結果コメントと内容を合成しない。 該当セクションが存在しない、または空の場合は「受け入れ条件が定義されていない」旨を報告して終了する（フォーマット不備の可能性があるので、`issue-refine` skill での整理を案内してよい）。 @@ -64,7 +67,7 @@ issue 本文から `## 受け入れ条件` の見出し以降〜次の `## ` 見 これらは **`?` (要人間判定)** としてマークし、検査者（呼び出し側）に判断を委ねる。可能であれば「動作確認方法の提示」（例: 「呼び出し元 agent を再起動して `/help` で skill 一覧に現れるか確認」）も併記する。 -コメントを検査する場合は、対象 issue のコメント内に指定された結果コメントが存在するかを確認し、要求された見出し（例: `## 調査結果`、`### 結論`、`### 根拠`、`### 検証内容`、`### Blocker`、`### 却下案`、`### 後続候補`）と各見出し配下の内容を照合する。見出しや必須内容が明確に欠ければ `✗`、存在はするが内容の妥当性が自動判定できなければ `?` とする。コメントの編集やチェックリスト更新は行わない。 +コメントを検査する場合は、`--result-comment` で指定された単一コメントについて、要求された見出し（例: `## 調査結果`、`### 結論`、`### 根拠`、`### 検証内容`、`### Blocker`、`### 却下案`、`### 後続候補`）と各見出し配下の内容を照合する。見出しや必須内容が明確に欠ければ `✗`、存在はするが内容の妥当性が自動判定できなければ `?` とする。コメントの編集やチェックリスト更新は行わない。 ### 4. 結果報告 @@ -96,6 +99,7 @@ issue 本文から `## 受け入れ条件` の見出し以降〜次の `## ` 見 ## 失敗時の対応 - `gh issue view` が失敗する（issue が存在しない / 認証エラー等）、またはコメントを取得できない場合は、その旨を報告して終了する。 +- `--result-comment` の形式を解釈できない場合は入力エラーとして終了する。一致するコメントが取得結果にない場合は、結果コメント存在条件を `✗` として報告する。 - `## 受け入れ条件` セクションが空 / 存在しない場合は、`issue-refine` skill での整理を案内する。 ## やらないこと diff --git a/skills/issue-implement/SKILL.md b/skills/issue-implement/SKILL.md index 4e002c9..32da013 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.5 +version: 1.1.0 --- # Issue Implement Skill @@ -15,20 +15,22 @@ GitHub issue を起点とした issue-driven 開発サイクルの中核 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 される。 +- **`issuekit:issue-create` skill**: Status と完了形の single source of truth。APM plain-skill mode では `issue-create`。本 skill では定義を複製せず参照する。 - **`gh` CLI**: GitHub 操作全般に使用する。 ## スコープ -- **含む**: Status 確認、Depends on の close 確認、親 issue の文脈取り込み、worktree への自動切り替え (Claude Code 環境かつ default branch 上のときのみ、条件付き)、実装と適宜 commit、lint/format/型チェック、受け入れ条件チェック、cross-review、PR 作成、CI 確認・修正。 +- **含む**: Status・PR 完了形の確認、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 環境向けの worktree 化フォールバック。Codex CLI では `EnterWorktree` が無いためこの step を skip し、ユーザーが事前に切った worktree / branch で続行する。Cursor / Gemini など `cross-review` 未対応 runtime は、実装前の preflight で停止する。 - ユーザーが既に手動で feature ブランチに切り替えているケースの上書き。default branch 以外にいる場合は worktree 化を行わず既存ブランチを尊重する。 - レビュー指摘の修正を `git commit --amend` / `rebase` / `fixup` で履歴整形すること。指摘対応は **追加 commit** で行い、試行錯誤やレビュー対応の経緯を履歴に残す。 + - issue コメントだけを成果物とする調査・設計・技術検証。`issue-investigate` の対象とする。 ## 実行手順 -### 1. issue の取得と Status 確認 +### 1. issue の取得と Status・完了形の確認 ```bash ISSUE_NUMBER= @@ -44,6 +46,12 @@ gh issue view "$ISSUE_NUMBER" --json title,body,updatedAt,comments - **`Status: Draft`**: 受け入れ条件が未確定（「仮」「要検討」を含む / 検証不能なほど曖昧）。着手しない。**worktree 化 (step 4) より前にここで early abort する**ため、worktree は作成されない。ユーザーに受け入れ条件の確認を促し、必要なら `issuekit:issue-refine` skill（APM plain-skill mode では `issue-refine`）で整理する。 - **`Status:` 表記なし / フォーマット不完全**: 同様に worktree 化前に abort し、`issuekit:issue-refine` skill（APM plain-skill mode では `issue-refine`）での整理を案内する。 +Status 確認後、受け入れ条件と `## スコープ外` を `issue-create` の「成果物と完了形」に照らし、worktree 化より前に分岐する。 + +- **PR**: repo の code / test / config / durable docs の変更が完了条件に含まれる。本 skill で続行する。 +- **issue コメント**: durable な repo 変更を要求しないコメント完結型。実装・commit を開始せず、plugin mode では `issuekit:issue-investigate `、APM plain-skill mode では `issue-investigate ` を案内して停止する。 +- **要確認**: 両方に該当する、または判別不能。実装・commit を開始せず、`issuekit:issue-refine `（APM plain-skill mode では `issue-refine `）を案内して停止する。 + ### 2. Depends on (依存 issue) の確認 issue 本文に `Depends on:` 行がある場合、列挙された依存 issue がすべて close 済みかを確認する。 @@ -82,7 +90,7 @@ gh api "repos/${REPO}/issues/${ISSUE_NUMBER}/parent" --jq '{number, title, state 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 し、既存ブランチを尊重する。 -4. **対象 issue が step 1 のコメント確認を通過した `Status: Ready`**: step 1 で確認済みの値を使う。`Status: Draft` / フォーマット不完全 / コメント上の未解決 blocker・本文矛盾・方針保留・受け入れ条件の未反映変更は step 1 で early abort 済み (worktree も作成しない) なので、ここに到達した時点で常に「着手可能な Ready」。 +4. **対象 issue が step 1 を通過した `Status: Ready` + 完了形 `PR`**: Draft / フォーマット不完全 / コメント上の未解決事項 / コメント完結型 / 要確認は step 1 で early abort 済みなので、ここに到達した時点で常に実装着手可能。 呼び方は **タスク説明モード** (issue 番号は渡さない)。issue title から kebab-case の slug を生成し、末尾に `-` を付けたブランチ名 (例: issue #42「Slack 連携の OAuth フロー」→ `slack-oauth-flow-42`) を指定する。issue 番号を渡すと `worktree-start` 側で Status 判定経路に入り `issue-implement` への再帰連鎖が発生してしまうため、Status は本 skill 側で既に確認済みである旨を踏まえて純粋な worktree 切り替え機能だけを使う形にする。 @@ -174,5 +182,6 @@ PR URL と CI 結果（成功 / 修正後成功）をユーザーに返す。 - step 4 で `worktree-start` を呼ぶ際に issue 番号を渡すこと。issue 番号を渡すと `worktree-start` 側の Status 判定経路に入り `issue-implement` への再帰連鎖が起きるため、タスク説明モードで slug (`-<issue 番号>`) のみを渡す。 - issue 本文や PR への `close` キーワードの自動付与（ユーザー明示指定時のみ）。 - 受け入れ条件を満たさない状態での PR 作成。 +- コメント完結型または完了形が要確認な issue の実装・commit・PR 化。step 1 で停止し、`issue-investigate` または `issue-refine` を案内する。 - 実行中 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 後も価値を持つ。 diff --git a/skills/issue-investigate/SKILL.md b/skills/issue-investigate/SKILL.md index b560185..5d21fe0 100644 --- a/skills/issue-investigate/SKILL.md +++ b/skills/issue-investigate/SKILL.md @@ -80,7 +80,13 @@ issue の受け入れ条件と調査方針に沿って、必要なソース・ 途中で blocker が見つかっても、判明した事実と未検証範囲を整理する。blocker により受け入れ条件を満たせない場合は結果コメントを投稿しても完了扱いにせず、issue を close しない。 -### 6. 結果コメントの投稿 +### 6. 明示された後続 issue の起票 + +元 issue の受け入れ条件またはユーザー指示に「後続 issue を起票する」と明記されている場合だけ、調査結果を踏まえて `issue-create` の手順で起票する。明記がなければ起票せず、step 7 の `### 後続候補` に提案を残すだけにする。 + +起票した後続 issue の URL は保持し、結果コメントの `### 後続候補` に記載する。起票に失敗した場合も判明済みの調査結果は step 7 でコメントするが、Blocker に失敗内容を記載し、受け入れ条件未達として close しない。 + +### 7. 結果コメントの投稿 以下の構造を保ち、該当事項がない見出しも `なし` と明記してコメントを投稿する。これにより `acceptance-check` がコメントの存在と必須項目を検査できる。 @@ -109,32 +115,32 @@ issue の受け入れ条件と調査方針に沿って、必要なソース・ ### 後続候補 -- <候補と理由、なければ「なし」。未起票なら候補であることを明記> +- <候補と理由。起票済みなら issue URL、未起票なら候補であることを明記。なければ「なし」> ``` ```bash -gh issue comment "$ISSUE_NUMBER" --body-file - <<'EOF' +RESULT_COMMENT_URL=$(gh issue comment "$ISSUE_NUMBER" --body-file - <<'EOF' ## 調査結果 ... EOF +) +[ -n "$RESULT_COMMENT_URL" ] || exit 1 ``` -### 7. 一時差分が残っていないことの確認 +投稿時に返された `RESULT_COMMENT_URL` を、この cycle で検査する結果コメントの一意な識別子として保持する。再投稿した場合は新しい URL へ置き換え、過去の結果コメントを今回の正本として扱わない。 + +### 8. 一時差分が残っていないことの確認 結果投稿前後に `git status --short` を再取得し、step 4 の開始時点と比較する。調査由来の差分が 1 件でも残っていれば完了扱いにせず、安全に所有権を特定できる差分だけを戻して再確認する。開始時点に存在したユーザー変更は同じ状態で保持する。 -### 8. 受け入れ条件チェック +### 9. 受け入れ条件チェック -結果コメント投稿と一時差分の確認後に `issuekit:acceptance-check <N>`（APM plain-skill mode では `acceptance-check <N>`）を呼び出す。コメント完結型の条件は `gh issue view "$ISSUE_NUMBER" --json body,comments` を根拠に検査する。 +明示された後続 issue の起票、結果コメント投稿、一時差分の確認後に `issuekit:acceptance-check <N> --result-comment <RESULT_COMMENT_URL>`（APM plain-skill mode では `acceptance-check <N> --result-comment <RESULT_COMMENT_URL>`）を呼び出す。コメント完結型の条件は `gh issue view "$ISSUE_NUMBER" --json body,comments` から URL が一致する単一コメントだけを正本として検査し、過去コメントを合成して充足扱いにしない。 - `✗` があれば調査または結果コメントを補い、再検査する。 - `?` は呼び出し側で可能な確認を行う。判定できない項目が残れば close しない。 - すべての項目が `✓`、または根拠を伴って呼び出し側が充足と判定できた場合だけ次へ進む。 -### 9. 明示された後続 issue の起票 - -元 issue の受け入れ条件またはユーザー指示に「後続 issue を起票する」と明記されている場合だけ、`issue-create` の手順で起票する。明記がなければ、step 6 の `### 後続候補` に提案を残すだけで起票しない。 - ### 10. issue の close と完了報告 次の全条件を満たした後でのみ対象 issue を close する。 @@ -155,7 +161,7 @@ gh issue close "$ISSUE_NUMBER" - issue / コメント / 親 / 依存の取得に失敗した場合は着手せず、取得できなかった対象を報告する。 - コメント投稿に失敗した場合は close しない。結果をローカルの新規 Markdown として保存せず、再投稿可能な内容を会話内で保持してエラーを報告する。 - 一時変更を安全に元へ戻せない、またはユーザー変更との区別がつかない場合は操作を止め、差分を残したまま対象と理由を報告する。ユーザー変更を推測で破棄しない。 -- `acceptance-check` に `✗` / 未解決の `?` がある、明示された後続 issue の起票に失敗した、または `gh issue close` が失敗した場合は途中成功を明示し、close 済みと報告しない。 +- `acceptance-check` に `✗` / 未解決の `?` がある、明示された後続 issue の起票に失敗した、結果コメント URL を保持できない、または `gh issue close` が失敗した場合は途中成功を明示し、close 済みと報告しない。 ## やらないこと From 39f16e9460a984e45bc26799f2ef2e181b12af21 Mon Sep 17 00:00:00 2001 From: Hiroki SAKABE <hiroki.sakabe@icloud.com> Date: Sun, 2 Aug 2026 00:43:53 +0900 Subject: [PATCH 3/3] chore: align skill release versions --- skills/acceptance-check/SKILL.md | 2 +- skills/issue-implement/SKILL.md | 2 +- skills/issue-investigate/SKILL.md | 2 +- skills/issue-pick/SKILL.md | 2 +- skills/worktree-start/SKILL.md | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/skills/acceptance-check/SKILL.md b/skills/acceptance-check/SKILL.md index 068d138..f584b14 100644 --- a/skills/acceptance-check/SKILL.md +++ b/skills/acceptance-check/SKILL.md @@ -1,7 +1,7 @@ --- name: acceptance-check description: GitHub issue 本文の `## 受け入れ条件` セクションを抽出し、repo 状態や issue コメントを根拠に各項目を ✓ / ✗ / ? で報告する read-only skill。`issue-implement` と `issue-investigate` の受け入れ条件確認を標準化する。 -version: 1.1.0 +version: 1.2.0 --- # Acceptance Check Skill diff --git a/skills/issue-implement/SKILL.md b/skills/issue-implement/SKILL.md index 32da013..a95dac0 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.1.0 +version: 1.2.0 --- # Issue Implement Skill diff --git a/skills/issue-investigate/SKILL.md b/skills/issue-investigate/SKILL.md index 5d21fe0..7fb5d94 100644 --- a/skills/issue-investigate/SKILL.md +++ b/skills/issue-investigate/SKILL.md @@ -1,7 +1,7 @@ --- name: issue-investigate description: GitHub issue を起点に、PR や永続的な repo 変更を成果物としない調査・設計・技術検証を実行し、構造化した結果を issue コメントへ記録して受け入れ条件確認後に close する。Ready なコメント完結型 issue の着手時に使用する。 -version: 1.0.0 +version: 1.2.0 --- # Issue Investigate Skill diff --git a/skills/issue-pick/SKILL.md b/skills/issue-pick/SKILL.md index 6f44df3..a4609ad 100644 --- a/skills/issue-pick/SKILL.md +++ b/skills/issue-pick/SKILL.md @@ -1,7 +1,7 @@ --- name: issue-pick description: "Use when the user has NOT yet decided which issue to work on and needs help choosing. This is the pre-decision advisory phase: the user is weighing multiple open issues and wants structured guidance — not implementation. Key triggers: asking which issue to prioritize or tackle next, identifying which issues are blocked vs. ready to start independently, selecting issues that fit limited capacity (small/high-impact), or finding independent issues for parallel worktree sessions. The user's state is \"I have several candidates and don't know where to start.\" Provides ranked recommendation (1 pick + 1-2 alternates) across impact/dependencies/size/urgency — read-only, no state changes." -version: 1.1.0 +version: 1.2.0 --- # Issue Pick Skill diff --git a/skills/worktree-start/SKILL.md b/skills/worktree-start/SKILL.md index 83572a6..ec71c08 100644 --- a/skills/worktree-start/SKILL.md +++ b/skills/worktree-start/SKILL.md @@ -1,7 +1,7 @@ --- name: worktree-start description: "Claude Code 専用。タスク説明または issue URL / 番号から命名した git worktree へ `EnterWorktree` で切り替える。Ready issue は完了形を判定し、PR なら `issue-implement`、コメント完結型なら `issue-investigate` へ連鎖し、要確認なら `issue-refine` を案内する。" -version: 1.1.0 +version: 1.2.0 --- # Worktree Start Skill