Issue Driven

Issue-Driven Development Workflow

Manage the full lifecycle of development tasks through GitHub Issues.

Prerequisites

Before any subcommand, verify: 1. Current directory is a Git repository (git rev-parse --is-inside-work-tree) 2. gh CLI is authenticated (gh auth status) 3. A remote origin exists (git remote get-url origin)

If check 1 or 2 fails, inform the user and stop. If check 3 fails (no remote), suggest the user create a remote repository first (e.g. gh repo create), but do NOT stop — let the user decide whether to proceed or set up remote first.

Proactive Trigger Rules

• 有 remote 的 Git 项目：当用户开始 feature/bug/refactor 任务时，默认走 issue-driven 流程。无需用户显式调用 /issue，主动提示并引导。
• 无 remote 的 Git 项目：建议用户创建 remote（gh repo create），但不强制阻断。用户可选择先创建 remote 再走 issue 流程，或跳过 issue 流程直接开发。
• 非 Git 项目：不触发 issue-driven 流程。

Usage

/issue <subcommand>

Integration with CC Plan Mode

Issue 生命周期步骤必须编排进 CC plan 的执行步骤中，利用时间相位差消除衔接空隙。

标准 plan 模板（plan 中必须包含 issue 步骤）：

## Plan: {task title}

### Step 1 — Create Issue
- `/issue create` — 创建 GitHub Issue，记录任务背景和目标

### Step 2 — Design & Plan
- 在 plan 文件中完成方案设计
- `/issue update` — 将方案同步到 Issue body

### Step 3 — Setup Worktree
- `/issue worktree` — 创建 worktree + branch，label 自动切换到 in-progress

### Step 4 — Implementation
- 在 worktree 中完成开发

### Step 5 — Code Review
- `/issue review code` — 发送 diff 给 reviewer

### Step 6 — Create PR
- `/issue pr` — 创建 PR 并关联 Issue

关键原则：

• Plan 审批（CC plan mode 的 ExitPlanMode）和 Issue 创建是两个独立动作，plan 获批后按步骤顺序执行
• planning → in-progress 直接过渡，无需额外的 plan review 环节（plan review 由 CCB Peer Review Framework 在 CLAUDE.md 中统一管理）
• Issue 是 SSOT（Single Source of Truth），plan 内容通过 /issue update 同步到 Issue body

Label Convention

Ensure these labels exist in the repo (create if missing via gh label create):

Branch Naming

• Pattern: issue-{N}-{slug} (e.g. issue-42-add-auth)
• Slug: title converted to kebab-case, truncated to 30 chars
• One Issue can have multiple branches (1:N)

Subcommand Details

/issue create

1. Run prerequisite checks (Git repo, gh auth, remote). 2. Ask the user for:

• Task type: feature / bug / refactor / docs
• Title (concise, imperative)
• Background description (what and why)

3. Generate Issue body using this template:

## 背景
{user-provided background}

## 目标
{inferred from background, confirm with user}

## 方案
_待规划_

## 验收标准
_待定义_

4. Display the full Issue preview to the user and wait for confirmation. 5. Ensure required labels exist: gh label create "status/planning" --force and gh label create "type/{type}" --force. 6. Create the Issue: gh issue create -t "{title}" -b "{body}" -l "status/planning,type/{type}". 7. Record the Issue number for subsequent commands in this session.

/issue update

1. If no Issue number in session context, ask the user for it. 2. Find the current plan file — search in order:

• ls -t .claude/plans/*.md 2>/dev/null | head -1
• ls -t docs/plans/*.md 2>/dev/null | head -1
• If no plan file exists in either location, ask the user to provide plan content directly.

3. Read the plan content. 4. Fetch current Issue body: gh issue view {N} --json body -q .body. 5. Replace the ## 方案 and ## 验收标准 sections with plan content. 6. Update the Issue: gh issue edit {N} -b "{updated_body}". 7. Confirm success to the user.

/issue worktree

1. If no Issue number in session context, ask the user for it. 2. Fetch Issue title: gh issue view {N} --json title -q .title. 3. Generate slug: convert title to kebab-case, truncate to 30 chars. 4. Branch name: issue-{N}-{slug}. 5. Determine base branch: git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' (fallback to main). 6. Create worktree: git worktree add -b {branch} ../{branch} {base}. 7. Update label: gh issue edit {N} --remove-label "status/planning" --add-label "status/in-progress". 8. Inform user of the worktree path and suggest cd ../{branch}.

/issue review code

1. If no Issue number in session context, ask the user for it. 2. Determine base branch (same logic as worktree). 3. Generate diff: git diff {base}...HEAD. 4. If diff is empty, inform user there are no changes to review. 5. Construct the review request message:

[CODE REVIEW REQUEST]

Issue #{N}: {title}
Branch: {current branch}

--- CHANGES START ---
{diff output}
--- CHANGES END ---

6. Send to reviewer via /ask codex with the above message. 7. Follow the Async Guardrail — if output contains [CCB_ASYNC_SUBMITTED, end turn immediately. 8. When Codex response arrives, parse the JSON scores. 9. Display scores as a summary table with pass/fail status.

/issue pr

1. If no Issue number in session context, ask the user for it. 2. Get current branch name: git branch --show-current. 3. Verify branch follows issue-{N}-* pattern. 4. Determine base branch (same logic as worktree). 5. Ask user: "Is this the final PR for Issue #{N}?" (yes/no).

• Yes → PR body includes Closes #{N}
• No → PR body includes Refs #{N}

6. Generate PR title from branch name or ask user. 7. Create PR: gh pr create -B {base} -t "{title}" -b "{body}". 8. Display the PR URL to the user.

/issue status

1. Run prerequisite checks. 2. List open issues with status labels:

• gh issue list --label "status/planning" --json number,title,labels --limit 20
• gh issue list --label "status/in-progress" --json number,title,labels --limit 20
• Merge results.

3. For each issue, find associated branches: git branch -a --list "*/issue-{N}-*". 4. For each issue, find associated PRs: gh pr list --search "issue-{N}" --json number,title,state,url. 5. Display a formatted table:

# | Title | Status | Branch(es) | PR(s)

Issue Granularity Rules

• Small tasks (single change): Plan = Issue, 1:1 mapping. One Issue, one branch, one PR.
• Large tasks (multiple independent steps): Create an epic Issue as the parent.
• Epic Issue body contains a task list with checkboxes tracking sub-issues.
• Each step becomes a sub-issue with its own worktree/branch/PR.
• Sub-issue PRs use Refs #{epic}, the final one uses Closes #{epic}.
• All sub-issues completed → close the epic.

Non-Git Projects

If the current directory is not a Git repository, inform the user:

"Issue-driven workflow requires a Git repository. Current directory is not a Git repo."

Do not proceed with any subcommand.