hirokisakabe · hirokisakabe · Aug 12, 2026 · Aug 12, 2026 · Aug 12, 2026 · Aug 12, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -6,7 +6,7 @@ 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 9 skills as `skills/<name>/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 10 skills as `skills/<name>/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`), 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.
 
@@ -18,6 +18,12 @@ The bundle codifies an **issue-driven development** workflow where the GitHub is
 - `issue-implement` → `issue-dispatch` only for a single PR-shaped Ready issue invoked from Codex CLI on the default branch. The dispatcher creates one ordinary worktree and launches `codex exec -C <path>`; the linked-worktree worker re-enters `issue-implement` and continues without dispatching again.
 - Direct multi-issue implementation requests enter `issue-dispatch`. `issue-pick` remains read-only and does not chain into it without a new explicit implementation request from the user.
 
+`issue-discover` is the read-only entry point for finding new, untracked improvement themes from repository evidence:
+
+- `issue-discover` inspects README, `SKILL.md`, recent changes, TODO / FIXME, and documentation inconsistencies, then checks open issue titles, bodies, and relevant comments before proposing at most three candidates.
+- `issue-discover` does not rank candidates alongside existing issues, mutate GitHub or repo state, or chain automatically. After the user selects a candidate, plugin mode directs them to `issuekit:issue-create`; APM plain-skill mode directs them to bare `issue-create`.
+- `issue-pick` remains responsible only for selecting among registered open issues. When no registered candidate fits and the user wants a new theme, it may suggest `issuekit:issue-discover` / `issue-discover` without invoking it.
+
 `issue-implement` is the orchestrator of the implementation cycle and **calls** the other skills:
 
 - `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)
@@ -26,7 +32,7 @@ The bundle codifies an **issue-driven development** workflow where the GitHub is
 - `issue-implement` → `issue-dispatch` (**conditional**, inside the mandatory isolation preflight): fires only for Codex CLI on the default branch and passes exactly the current issue. The parent session stays in place while the dispatcher owns the worker worktree and waits through PR / CI.
 - `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).
+- `issue-create` / `issue-refine` / `issue-pick` / `issue-discover` are entry points; they do not chain into other skills. `issue-pick` is a triage entry point for registered issues, while `issue-discover` finds untracked themes from repo evidence. Their handoffs to `issue-implement`, `issue-investigate`, or `issue-create` are via the 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.
 
@@ -41,7 +47,7 @@ When editing one skill, check whether others reference it. Cross-references appe
 - Plugin mode: `issuekit:<skill-name>` (e.g. `issuekit:cross-review`)
 - APM plain-skill mode: bare `<skill-name>` (e.g. `cross-review`)
 
-Both forms must stay in sync — `issue-dispatch`, `issue-implement`, `issue-investigate`, `issue-pick`, and `worktree-start` document each form explicitly.
+Both forms must stay in sync — `issue-dispatch`, `issue-implement`, `issue-investigate`, `issue-pick`, `issue-discover`, and `worktree-start` document each form explicitly.
 
 ## Hardcoded Japanese keywords
 
@@ -57,7 +63,7 @@ These strings are not localizable in the current implementation. Forking is requ
 
 ## 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`, `issue-dispatch`, `issue-implement`, and `issue-investigate` 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-discover`, `issue-dispatch`, `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
@@ -60,7 +60,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 nine skills (always installs HEAD — version pinning not yet supported)
+# Install all ten skills (always installs HEAD — version pinning not yet supported)
 npx skills add hirokisakabe/issuekit
 
 # Or install a specific skill only
@@ -88,20 +88,23 @@ issuekit assumes the following tools are available on the host:
 
 ## 🧩 Skills
 
-issuekit ships nine skills under `skills/`:
+issuekit ships ten 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.                                                          |
+| `issue-discover`     | Entry point | Read-only discovery: inspect repository evidence, exclude themes already covered by open issues, and suggest up to three new issue candidates.         |
 | `worktree-start`     | Entry point | **Claude Code interactive sessions only.** Switch via `EnterWorktree`; reuse an existing linked worktree; route a Ready issue to `issue-implement` (PR), `issue-investigate` (issue comment), or `issue-refine` (ambiguous). |
 | `issue-dispatch`     | Orchestrator| Resolve one or more implementation requests, preflight dependencies / conflicts / runtime permissions, then run one worktree-isolated `issue-implement` worker per issue and aggregate PR / CI results. |
 | `issue-implement`    | Orchestrator| Guard for PR-shaped work, then drive status check → mandatory isolation preflight → 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. |
 
+`issue-discover` and `issue-pick` are separate read-only advisory entry points: discovery finds evidence-backed themes that are not yet tracked, while picking compares only registered open issues. A discovered theme reaches `issue-create` only after the user explicitly selects it; neither skill creates or starts work automatically.
+
 `issue-dispatch`, `issue-implement`, and `issue-investigate` are the three orchestrators. `issue-dispatch` owns cross-issue scheduling and isolation but delegates every issue's implementation cycle to `issue-implement`; PR-shaped work then 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, owns only the in-session `EnterWorktree` transition, and routes a Ready issue by its acceptance criteria and out-of-scope section: PR → `issue-implement`, issue comment → `issue-investigate`, ambiguous → `issue-refine`. Codex App managed worktrees and Handoff remain App-owned.
 
 `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.
@@ -149,6 +152,7 @@ The skills compose into PR and issue-comment completion paths. A single Codex CL
 
 ```mermaid
 flowchart LR
+    DS[issue-discover] -. user selects candidate .-> A
     A[issue-create] --> I[(GitHub issue<br/>Status: Ready)]
     R[issue-refine] --> I
     P[issue-pick] -. suggests .-> I
@@ -176,7 +180,7 @@ flowchart LR
     classDef ver   fill:#ecfdf5,stroke:#10b981,color:#065f46
     classDef out   fill:#f3f4f6,stroke:#6b7280,color:#1f2937
 
-    class A,R,P,W entry
+    class DS,A,R,P,W entry
     class D,PF,PFW,WK,IMPL,INV orch
     class CR,AC,AC2 ver
     class I,C,IC,STOP out