codely-plan-create-github

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

🧠 How to create a plan

🧠 如何创建计划

[!CRITICAL] Do NOT create or edit any GitHub issue until the user has agreed on the specific public contracts to be considered and the implementation phases. Propose first, get approval, then create the issues.

The structure of a plan, its sections and the rules to shape them are defined in

resources/plan-guidelines.md

. Read it before proposing anything.

[!CRITICAL] 在用户确认需要纳入考虑的具体 public contracts 和实施阶段之前，请勿创建或编辑任何 GitHub issue。应先提出方案，获得批准后再创建 issue。

计划的结构、各部分及其塑形规则由

resources/plan-guidelines.md

定义。提出任何方案之前，请先阅读该文件。

🎯 Input

🎯 输入

This skill is invoked as

/codely-plan-create-github <github-issue-url>

```
<github-issue-url>
```
is the URL of the GitHub issue describing the task to plan. This issue becomes the parent "plan" issue.
If no URL is provided, ask the user for it before doing anything else.

此 skill 通过

/codely-plan-create-github <github-issue-url>

调用。

```
<github-issue-url>
```
是描述待规划任务的 GitHub issue URL。该 issue 将成为父级“计划”issue。
如果未提供 URL，请先向用户索取，然后再执行其他操作。

🗂️ Repository

🗂️ 仓库

All the plan lives as GitHub issues in the repository of the current working directory. Never hardcode a repository: let

gh

resolve it from the local Git remote.

bash

gh issue view <number>
gh issue create --title "..." --body "..."
gh issue edit <number> --body "..."

Derive

<number>

from the provided URL. Confirm the repository

gh

resolves with

gh repo view --json nameWithOwner --jq .nameWithOwner

, and check that the provided URL belongs to it. If it does not, stop and ask the user to run the skill from the clone of that repository.

To link a phase as a native GitHub sub-issue of the parent, use the sub-issues REST API. It expects the child's numeric database

id

(not its issue number), so resolve it first. The

{owner}

and

{repo}

placeholders are substituted by

gh

with the current repository:

bash

undefined

整个计划都以 GitHub issue 的形式存放在当前工作目录所在的仓库中。绝不硬编码仓库：让

gh

通过本地 Git remote 进行解析。

bash

gh issue view <number>
gh issue create --title "..." --body "..."
gh issue edit <number> --body "..."

从提供的 URL 推导

<number>

。使用

gh repo view --json nameWithOwner --jq .nameWithOwner

确认

gh

解析出的仓库，并检查提供的 URL 是否属于该仓库。如果不属于，则停止操作，并请用户在该仓库的 clone 中运行此 skill。

要将某个阶段关联为父 issue 的 原生 GitHub sub-issue，请使用 sub-issues REST API。该 API 需要子 issue 的数字数据库

id

（而不是 issue 编号），因此必须先解析它。

{owner}

和

{repo}

占位符将由

gh

替换为当前仓库：

bash

undefined

Resolve the child issue database id from its number

child_id=$(gh api repos/{owner}/{repo}/issues/<child> --jq .id)

Attach the child as a native sub-issue of the parent

gh api --method POST repos/{owner}/{repo}/issues/<parent>/sub_issues -F sub_issue_id="$child_id"

undefined

gh api --method POST repos/{owner}/{repo}/issues/<parent>/sub_issues -F sub_issue_id="$child_id"

undefined

🧱 Issue structure

🧱 Issue 结构

A plan is stored as a tree of issues, using GitHub's native sub-issues feature:

Parent "plan" issue: the issue whose URL was passed in. It holds the
```
Goal
```
, the
```
Context
```
, the agreed design decisions, and a checklist of the phases, each item linking its child issue. The parent depends on its children: when every child issue is closed, the parent closes too.
One child issue per phase: each holds the phase description and its to-do actions as a checkbox list, plus a reference back to the parent (
```
Part of #<parent>
```
). Every child is attached to the parent as a native GitHub sub-issue (via the sub-issues API), not only as a checklist link.

#12 Product Bundles (parent plan)
     Goal / Context / design decisions
     - [ ] #13 Phase 1: ...
     - [ ] #14 Phase 2: ...
#13 Phase 1: ...   (child, to-do checkboxes)
#14 Phase 2: ...   (child, to-do checkboxes)

计划使用 GitHub 的 原生 sub-issues 功能，以 issue 树的形式存储：

父级“计划”issue：传入 URL 所对应的 issue。其中包含
```
Goal
```
、
```
Context
```
、已达成一致的设计决策，以及一份阶段清单，每个条目都链接到对应的子 issue。父 issue 依赖其子 issue：所有子 issue 关闭后，父 issue 也会随之关闭。
每个阶段对应一个子 issue：其中包含阶段说明、以 checkbox 列表呈现的待办操作，以及指向父 issue 的引用（
```
Part of #<parent>
```
）。每个子 issue 都通过 sub-issues API 关联为父 issue 的原生 GitHub sub-issue，而不仅仅是通过清单链接关联。

#12 Product Bundles (parent plan)
     Goal / Context / design decisions
     - [ ] #13 Phase 1: ...
     - [ ] #14 Phase 2: ...
#13 Phase 1: ...   (child, to-do checkboxes)
#14 Phase 2: ...   (child, to-do checkboxes)

🪜 Steps to create a plan

🪜 创建计划的步骤

Read the task from the parent issue with
```
gh issue view <parent>
```
.
Define task phases, letting the user choose the amount of phases as described in the guidelines.
Specify the public contracts to be created/modified/deleted on each phase task, as described in the guidelines.
Propose the plan to the user for approval. IMPORTANT: Do not create any issue until the user has agreed on the specific contracts to be considered and the implementation phases.
Create one child issue per phase with
```
gh issue create
```
. Each child issue body must contain:
- The phase description.
- The phase to-do actions as a checkbox list (
```
- [ ] ...
```
  ).
- The public contracts for that phase.
- A
```
Part of #<parent>
```
  reference line.
Capture the number of every child issue returned by
```
gh
```
.
Attach every child as a native sub-issue of the parent. For each child, resolve its database id and link it to the parent with the sub-issues API (see the snippet in the Repository section above):
bash
```
child_id=$(gh api repos/{owner}/{repo}/issues/<child> --jq .id)
gh api --method POST repos/{owner}/{repo}/issues/<parent>/sub_issues -F sub_issue_id="$child_id"
```
Do this for every phase, in order, so the parent lists all phases as native sub-issues.
Update the parent issue with
```
gh issue edit <parent> --body ...
```
so its body contains the
```
Goal
```
,
```
Context
```
, agreed design decisions and a
```
Phases
```
checklist that links every child issue (
```
- [ ] #<child> Phase N: <title>
```
). Preserve the original task description from the parent issue: keep it as-is and append the new plan content below it, separated by a
```
---
```
line (do not lose or rewrite the original text).
Suggest next steps. Ask the user what do they want to do:
- Do not do anything else.
- Implement the plan by executing the
```
/codely-plan-phase-implement-github <parent-issue-url>
```
  skill (implements Phase 1 only).
- Implement a specific phase by executing the
```
/codely-plan-phase-implement-github <child-issue-url>
```
  skill.
[!IMPORTANT]
```
/codely-plan-phase-implement-github
```
handles one phase per invocation. Never implement all phases at once.

使用
```
gh issue view <parent>
```
从父 issue 中读取任务。
定义任务阶段，并按照指南让用户选择阶段数量。
按照指南，明确每个阶段任务中需要创建、修改或删除的 public contracts。
向用户提交计划以供批准。重要：在用户确认需要考虑的具体 contracts 和实施阶段之前，不要创建任何 issue。
使用
```
gh issue create
```
为每个阶段创建一个子 issue。每个子 issue 的正文必须包含：
- 阶段说明。
- 以 checkbox 列表（
```
- [ ] ...
```
  ）呈现的阶段待办操作。
- 该阶段的 public contracts。
- 一行
```
Part of #<parent>
```
  引用。
记录
```
gh
```
返回的每个子 issue 编号。
将每个子 issue 关联为父 issue 的原生 sub-issue。 对每个子 issue，解析其数据库 ID，并使用 sub-issues API 将其关联到父 issue（参见上文“仓库”部分中的代码片段）：
bash
```
child_id=$(gh api repos/{owner}/{repo}/issues/<child> --jq .id)
gh api --method POST repos/{owner}/{repo}/issues/<parent>/sub_issues -F sub_issue_id="$child_id"
```
按阶段顺序逐一执行此操作，使父 issue 列出所有原生 sub-issue 阶段。
使用
```
gh issue edit <parent> --body ...
```
更新父 issue，使其正文包含
```
Goal
```
、
```
Context
```
、已达成一致的设计决策，以及链接到每个子 issue 的
```
Phases
```
清单（
```
- [ ] #<child> Phase N: <title>
```
）。保留父 issue 中原有的任务说明：保持原样，并在其下方追加新的计划内容，中间使用一行
```
---
```
分隔（不得丢失或改写原文）。
建议后续操作并询问用户希望接下来做什么：
- 不执行其他操作。
- 执行
```
/codely-plan-phase-implement-github <parent-issue-url>
```
  skill 来实施计划（仅实施 Phase 1）。
- 执行
```
/codely-plan-phase-implement-github <child-issue-url>
```
  skill 来实施特定阶段。
[!IMPORTANT]
```
/codely-plan-phase-implement-github
```
每次调用仅处理一个阶段。绝不要一次实施所有阶段。

🗃️ Plan metadata

🗃️ 计划元数据

GitHub issues have no YAML frontmatter, so add the plan metadata as a footer at the end of the parent issue body:

markdown

---

<sub>Created by { tool } · { model.name } { model.version } (reasoning effort: { model.reasoning_effort }) · { current_date }</sub>

```
current_date
```
: The current date in the format ISO 8601 RFC 3339 (
```
YYYY-MM-DDTHH:MM:SSZ
```
).
```
tool
```
: The AI coding tool used (e.g.
```
Claude Code
```
,
```
Cursor
```
,
```
Copilot
```
,
```
Codex
```
)
```
model.name
```
: The name of the model used to make the change (e.g.
```
Claude Opus
```
,
```
Cursor Composer
```
,
```
OpenAI GPT
```
)
```
model.version
```
: The version of the model used to make the change (e.g.
```
4.6
```
,
```
1.5
```
,
```
5.4
```
)
```
model.reasoning_effort
```
: The reasoning effort of the model used to make the change (e.g.
```
low
```
,
```
medium
```
,
```
high
```
)

GitHub issue 不支持 YAML frontmatter，因此请将计划元数据作为 footer 添加到父 issue正文的末尾：

markdown

---

<sub>Created by { tool } · { model.name } { model.version } (reasoning effort: { model.reasoning_effort }) · { current_date }</sub>

```
current_date
```
：采用 ISO 8601 RFC 3339 格式（
```
YYYY-MM-DDTHH:MM:SSZ
```
）的当前日期。
```
tool
```
：使用的 AI 编码工具（例如
```
Claude Code
```
、
```
Cursor
```
、
```
Copilot
```
、
```
Codex
```
）。
```
model.name
```
：执行变更所使用的模型名称（例如
```
Claude Opus
```
、
```
Cursor Composer
```
、
```
OpenAI GPT
```
）。
```
model.version
```
：执行变更所使用的模型版本（例如
```
4.6
```
、
```
1.5
```
、
```
5.4
```
）。
```
model.reasoning_effort
```
：模型的推理强度（例如
```
low
```
、
```
medium
```
、
```
high
```
）。

🗂️ Where each plan section lives

🗂️ 各个计划部分的位置

The parent issue holds the

Goal

, the

Context

, the

Phases

checklist and the

Next step

sections described in

resources/plan-guidelines.md

. Each child issue holds the description and the to-do actions list of its own phase.

As the phases are implemented through pull requests, the last to-do action of every phase asks for pull request titles instead of commit messages.

父 issue 包含

resources/plan-guidelines.md

中描述的

Goal

、

Context

、

Phases

清单和

Next step

部分。每个子 issue 包含其所属阶段的说明和待办操作列表。

由于各阶段通过 pull request 实施，因此每个阶段的最后一项待办操作都应要求提供 pull request 标题，而不是 commit message。