🧷 issuekit

Issue-driven development for AI coding agents.

An Agent Skills bundle that treats each GitHub issue as the canonical "rich plan" for a unit of work — so volatile specs stay out of your repository and only durable code gets versioned.

---

Note

Japanese-oriented plugin. Skill bodies, descriptions, and this README are written in English, but the skills read Japanese section headers (e.g. ## 受け入れ条件) hardcoded into issue bodies. Issue contents themselves are expected to remain in Japanese. To use issuekit with English-only issues, you will currently need to fork and adjust the hardcoded keywords.

Important

Casual OSS. No SLA, no response guarantees. Distributed as-is for users who share the underlying philosophy. PRs and issues are welcome but may be closed without action if they conflict with the maintainer's solo-dev workflow.

Table of Contents

• 📦 Install
• 🛠️ Dependencies
• 🧩 Skills
• 🔁 Workflow
• 💡 Philosophy
• 🆚 Comparison with related frameworks
• 📄 License

---

📦 Install

via gh skill (recommended — supports version pinning)

# Install a skill interactively (choose from the list)
gh skill install hirokisakabe/issuekit

# Install a specific skill (e.g. issue-implement)
gh skill install hirokisakabe/issuekit issue-implement

# Pin to a specific version
gh skill install hirokisakabe/issuekit issue-implement@v1.0.0

# Or use the --pin flag
gh skill install hirokisakabe/issuekit issue-implement --pin v1.0.0

# Install for Claude Code at user scope explicitly
gh skill install hirokisakabe/issuekit issue-implement --agent claude-code --scope user

The install location depends on --agent and --scope; for Claude Code at user scope, skills land in ~/.claude/skills/. Version tags follow GitHub Releases.

via npx skills (Claude Code, Codex CLI, Cursor, Gemini, …)

# Install all seven skills (always installs HEAD — version pinning not yet supported)
npx skills add hirokisakabe/issuekit

# Or install a specific skill only
npx skills add hirokisakabe/issuekit --skill issue-implement

This installs the skills under your agent's skill directory (e.g. ~/.claude/skills/ for Claude Code). See skills.sh for the list of supported agents (Claude Code, Codex CLI, Cursor, Gemini, ...).

---

🛠️ Dependencies

issuekit assumes the following tools are available on the host:

• An Agent Skills-compatible agent runtime (e.g. Claude Code, Codex CLI, Cursor) that loads the skills.
• gh CLI — 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 (brew install --cask codex) for the codex backend.
  • Claude CLI (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.

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.

---

🧩 Skills

issuekit ships seven 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).
issue-implement	Orchestrator	Drive the full cycle from an issue number: status check → worktree start → implementation / commits → acceptance check → cross-review → PR → CI.
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.

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.

---

🔁 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.

flowchart LR
    A[issue-create] --> I[(GitHub issue<br/>Status: Ready)]
    R[issue-refine] --> I
    P[issue-pick] -. suggests .-> I
    I --> W[worktree-start]
    W --> IMPL[issue-implement<br/>implementation + commits]
    IMPL --> AC[acceptance-check]
    AC --> CR[cross-review]
    CR --> C[PR + CI]

    classDef entry fill:#e8f4ff,stroke:#3b82f6,color:#1e3a8a
    classDef orch  fill:#fef3c7,stroke:#d97706,color:#78350f
    classDef ver   fill:#ecfdf5,stroke:#10b981,color:#065f46
    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

Loading

---

💡 Philosophy

Most "spec-driven" or "plan-driven" frameworks for AI coding agents store the spec in the repository as markdown files (spec.md, plan.md, etc.) checked in alongside the code. issuekit takes a different position:

• Specs and plans are volatile. They describe a single unit of intent. Once the work is merged, the plan is dead — what survives is the code, the test, and (if anything) a one-line commit message.
• 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.

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.

More precisely, issuekit operates on the volatile layer only — each GitHub issue captures a single unit of intent (what to build, acceptance criteria, scope boundary). That plan expires when the issue closes.

The durable layer — architecture decisions, domain models, ADRs, and design context that outlives individual issues — is explicitly outside issuekit's scope. Where that knowledge lives (docs/, AGENTS.md, an external wiki, or nowhere at all) is entirely your call; issuekit neither prescribes nor precludes any arrangement.

---

🆚 Comparison with related frameworks

issuekit shares one core idea with Spec Kit, cc-spex, and superpowers: make the "what" an explicit contract that an AI agent can read, follow, and be checked against. Where they differ is where that contract lives, and how compliance is verified.

Framework	Contract location	Verification model	Fit
Spec Kit	Spec markdown checked into the repo	Agent re-reads the spec	Teams that want specs versioned alongside code
cc-spex	Spec markdown checked into the repo	Agent re-reads the spec	Solo / small team, lighter than Spec Kit
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

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.

---

📄 License

MIT