spec-to-issue

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

spec-to-issue — Spec to GitHub Issue

spec-to-issue — 从规格文档到GitHub Issue

Auto-generate GitHub Issues from spec directories (

.specs/{feature}/

从规格文档目录（

.specs/{feature}/

）自动生成GitHub Issue。

Language Rules

语言规则

Auto-detect input language → output in the same language
Japanese input → Japanese issue, use
```
references/issue-template.ja.md
```
as template reference
English input → English issue, use
```
references/issue-template.md
```
as template reference
Explicit override takes priority

Reference file selection: Based on the detected output language, use the corresponding template:

English →
```
references/issue-template.md
```
Japanese →
```
references/issue-template.ja.md
```

自动检测输入语言 → 输出与输入语言一致的内容
输入为日语时，生成日语Issue，使用
```
references/issue-template.ja.md
```
作为模板参考
输入为英语时，生成英语Issue，使用
```
references/issue-template.md
```
作为模板参考
显式设置优先级更高

参考文件选择：根据检测到的输出语言，使用对应的模板：

英语 →
```
references/issue-template.md
```
日语 →
```
references/issue-template.ja.md
```

Execution Flow

执行流程

1. Locate Spec Directory

1. 定位规格文档目录

With argument:

spec-to-issue auth-feature

→ use

.specs/auth-feature/

Without argument: Scan

.specs/

and present a list → ask user to select

Spec directories found in .specs/:
1. auth-feature (requirement.md, design.md, tasks.md)
2. member-management (requirement.md, tasks.md)
Which spec do you want to create an issue from?

带参数：

spec-to-issue auth-feature

→ 使用

.specs/auth-feature/

不带参数：扫描

.specs/

目录并列出可选项 → 询问用户选择

Spec directories found in .specs/:
1. auth-feature (requirement.md, design.md, tasks.md)
2. member-management (requirement.md, tasks.md)
Which spec do you want to create an issue from?

2. File Validation

2. 文件验证

Required:

requirement.md

must exist. Otherwise, exit with error. Recommended:

tasks.md

(if missing, generate a basic checklist) Optional:

design.md

(used as supplementary info if present)

必填项：必须存在

requirement.md

，否则报错退出。推荐项：

tasks.md

（如果缺失，生成基础检查清单）可选项：

design.md

（如果存在，用作补充信息）

3. Spec Analysis

3. 规格文档分析

Extract from each file:

requirement.md:

Title: First
```
# 
```
line, strip suffixes like "Requirements", "要件定義書"
Overview:
```
## Overview
```
or
```
## 概要
```
section
Key features: Sections starting with
```
### 1.
```
,
```
### 2.
```
, etc.
Tech stack:
```
## Technology Stack
```
or
```
## 技術要件
```
section

tasks.md:

Phases: Lines starting with
```
## Phase
```
or
```
## フェーズ
```
Tasks:
```
### 
```
headings within each phase, simplified for checklist
Done criteria:
```
## Definition of Done
```
or
```
## 完了の定義
```
section
Notes:
```
## Notes
```
or
```
## 注意事項
```
section

design.md (optional):

Architecture overview (as supplementary info)

从每个文件中提取以下信息：

requirement.md:

标题：第一个
```
# 
```
行，去除“Requirements”、“要件定義書”等后缀
概述：
```
## Overview
```
或
```
## 概要
```
部分
核心功能：以
```
### 1.
```
、
```
### 2.
```
等开头的部分
技术栈：
```
## Technology Stack
```
或
```
## 技術要件
```
部分

tasks.md:

阶段：以
```
## Phase
```
或
```
## フェーズ
```
开头的行
任务：每个阶段内的
```
### 
```
标题，简化后用作检查清单
完成标准：
```
## Definition of Done
```
或
```
## 完了の定義
```
部分
备注：
```
## Notes
```
或
```
## 注意事項
```
部分

design.md（可选）:

架构概述（用作补充信息）

4. Resolve Project Settings

4. 解析项目设置

Determine defaults in this priority order:

Command arguments > .specs/.config.yml > CLAUDE.md > Built-in defaults

From CLAUDE.md:

Branch name: PR target branch from Git Workflow section →
```
--branch
```
default
GitHub Organization: Inferred from repository URL

.specs/.config.yml (optional):

yaml

default-branch: develop
default-labels: [feature, spec-generated]
project-number: 7
assignee: username

按以下优先级确定默认值：

Command arguments > .specs/.config.yml > CLAUDE.md > Built-in defaults

从CLAUDE.md获取：

分支名称：Git Workflow部分中的PR目标分支 → 作为
```
--branch
```
的默认值
GitHub组织：从仓库URL推断

.specs/.config.yml (optional):

yaml

default-branch: develop
default-labels: [feature, spec-generated]
project-number: 7
assignee: username

5. Compose Issue Body

5. 编写Issue内容

See template details in the appropriate reference file (based on Language Rules):

English: references/issue-template.md
Japanese: references/issue-template.ja.md

根据语言规则，查看对应参考文件中的模板详情：

英语：references/issue-template.md
日语：references/issue-template.ja.md

6. Create Issue

6. 创建Issue

Without --preview (default): Show a brief summary and execute

gh issue create

Creating Issue:
  Title: [Feature] Member Management
  Labels: feature, spec-generated
  Phases: 3
  Tasks: 12
→ Running gh issue create...
Issue #42 created: https://github.com/org/repo/issues/42

With --preview: Display the full issue body, confirm, then execute

不带--preview（默认）：显示简要摘要并执行

gh issue create

Creating Issue:
  Title: [Feature] Member Management
  Labels: feature, spec-generated
  Phases: 3
  Tasks: 12
→ Running gh issue create...
Issue #42 created: https://github.com/org/repo/issues/42

带--preview：显示完整的Issue内容，确认后再执行

7. Additional Actions (optional)

7. 附加操作（可选）

```
--label
```
: Apply specified labels
```
--project
```
: Add to GitHub Project board via
```
gh project item-add
```
```
--assignee
```
: Set assignee

```
--label
```
: 应用指定标签
```
--project
```
: 通过
```
gh project item-add
```
添加到GitHub项目看板
```
--assignee
```
: 设置经办人

Options

选项

Option	Description	Default
`--preview`	Display issue body for confirmation	OFF
`--label <labels>`	Comma-separated labels	`.config.yml` value or none
`--project <number>`	Add to GitHub Project	`.config.yml` value or none
`--branch <name>`	Base branch for spec links	CLAUDE.md or `main`
`--assignee <user>`	Set assignee	`.config.yml` value or none

选项	描述	默认值
`--preview`	显示Issue内容供确认	关闭
`--label <labels>`	逗号分隔的标签列表	`.config.yml` 中的值或无
`--project <number>`	添加到GitHub项目	`.config.yml` 中的值或无
`--branch <name>`	规格文档链接的基础分支	CLAUDE.md中指定的分支或 `main`
`--assignee <user>`	设置经办人	`.config.yml` 中的值或无

Integration with spec-generator

与spec-generator集成

After spec-generator's

full

phase completes, suggest:

All three spec documents have been generated.
→ Create a GitHub Issue from them? (Y/n)

If yes, run spec-to-issue on the same directory.

当spec-generator的

full

阶段完成后，会提示：

All three spec documents have been generated.
→ Create a GitHub Issue from them? (Y/n)

如果用户确认（Y），则在同一目录下运行spec-to-issue。

Error Handling

错误处理

Situation	Response
`.specs/` does not exist	Error: Spec directory not found
`requirement.md` missing	Error: requirement.md is required
`tasks.md` missing	Warning: Use basic checklist as fallback
`gh` CLI not authenticated	Error: Guide user to `gh auth login`
Section not found	Use default value, show warning

场景	响应
`.specs/` 目录不存在	错误：未找到规格文档目录
缺失 `requirement.md`	错误：requirement.md为必填项
缺失 `tasks.md`	警告：使用基础检查清单作为备选
`gh` CLI未认证	错误：引导用户执行 `gh auth login`
未找到指定部分	使用默认值，并显示警告

Usage Examples

使用示例

undefined

undefined

With argument

/spec-to-issue auth-feature

Auto-detect and select

/spec-to-issue

With preview

/spec-to-issue auth-feature --preview

With labels and Project

/spec-to-issue auth-feature --label "feature,priority:high" --project 7

After spec-generator

"Create full spec for todo-app" → done → "Turn this into an issue"

Japanese

「仕様書を全部作って」→ 完了 →「これをIssueにして」

undefined

「仕様書を全部作って」→ 完了 →「これをIssueにして」

undefined