kata-add-phase

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

<objective> Add a new integer phase to the end of the current milestone in the roadmap.

This command appends sequential phases to the current milestone's phase list, automatically calculating the next phase number based on existing phases.

Purpose: Add planned work discovered during execution that belongs at the end of current milestone.

IMPORTANT: When showing examples to users, always use

/kata-add-phase

(the command), not the skill name. </objective>

<execution_context> @.planning/ROADMAP.md @.planning/STATE.md </execution_context>

<process> <step name="parse_arguments"> Parse the command arguments:

With
--issue
flag:

/kata-add-phase --issue .planning/issues/open/2026-02-06-phase-lookup.md

Read the issue file to extract title, provenance, and context
```
description
```
= issue title from frontmatter
```
ISSUE_FILE
```
= the path argument
```
ISSUE_PROVENANCE
```
= provenance field from frontmatter (e.g.,
```
github:owner/repo#102
```
)
```
ISSUE_NUMBER
```
= extracted from provenance if GitHub-linked (e.g.,
```
102
```
)

bash

if echo "$ARGUMENTS" | grep -q "^--issue "; then
  ISSUE_FILE=$(echo "$ARGUMENTS" | sed 's/^--issue //')
  if [ ! -f "$ISSUE_FILE" ]; then
    echo "ERROR: Issue file not found: $ISSUE_FILE"
    exit 1
  fi
  description=$(grep "^title:" "$ISSUE_FILE" | cut -d':' -f2- | xargs)
  ISSUE_PROVENANCE=$(grep "^provenance:" "$ISSUE_FILE" | cut -d' ' -f2)
  ISSUE_NUMBER=""
  if echo "$ISSUE_PROVENANCE" | grep -q "^github:"; then
    ISSUE_NUMBER=$(echo "$ISSUE_PROVENANCE" | grep -oE '#[0-9]+' | tr -d '#')
  fi
fi

Without
--issue
flag:

All arguments become the phase description
Example:
```
/kata-add-phase Add authentication
```
→ description = "Add authentication"
```
ISSUE_FILE
```
,
```
ISSUE_PROVENANCE
```
,
```
ISSUE_NUMBER
```
are empty

If no arguments provided:

ERROR: Phase description required
Usage: /kata-add-phase <description>
       /kata-add-phase --issue <issue-file-path>
Example: /kata-add-phase Add authentication system

Exit. </step>

<step name="load_roadmap"> Load the roadmap file:

bash

if [ -f .planning/ROADMAP.md ]; then
  ROADMAP=".planning/ROADMAP.md"
else
  echo "ERROR: No roadmap found (.planning/ROADMAP.md)"
  exit 1
fi

Read roadmap content for parsing. </step>

<step name="find_current_milestone"> Parse the roadmap to find the current milestone section:

Locate the "## Current Milestone:" heading
Extract milestone name and version
Identify all phases under this milestone (before next "---" separator or next milestone heading)
Parse existing phase numbers (including decimals if present)

Example structure:

undefined

<objective> 在路线图的当前里程碑末尾添加一个新的整数阶段。

该命令会在当前里程碑的阶段列表后追加连续的阶段，并根据现有阶段自动计算下一个阶段编号。

用途：添加执行过程中发现的、属于当前里程碑末尾的计划工作。

重要提示：向用户展示示例时，请始终使用

/kata-add-phase

（该命令），而非Skill名称。 </objective>

<execution_context> @.planning/ROADMAP.md @.planning/STATE.md </execution_context>

<process> <step name="parse_arguments"> 解析命令参数：

使用
--issue
标志时：

/kata-add-phase --issue .planning/issues/open/2026-02-06-phase-lookup.md

读取issue文件以提取标题、来源和上下文
```
description
```
= 来自前置元数据的issue标题
```
ISSUE_FILE
```
= 路径参数
```
ISSUE_PROVENANCE
```
= 来自前置元数据的来源字段（例如：
```
github:owner/repo#102
```
）
```
ISSUE_NUMBER
```
= 如果关联GitHub，则从来源中提取（例如：
```
102
```
）

bash

if echo "$ARGUMENTS" | grep -q "^--issue "; then
  ISSUE_FILE=$(echo "$ARGUMENTS" | sed 's/^--issue //')
  if [ ! -f "$ISSUE_FILE" ]; then
    echo "ERROR: Issue file not found: $ISSUE_FILE"
    exit 1
  fi
  description=$(grep "^title:" "$ISSUE_FILE" | cut -d':' -f2- | xargs)
  ISSUE_PROVENANCE=$(grep "^provenance:" "$ISSUE_FILE" | cut -d' ' -f2)
  ISSUE_NUMBER=""
  if echo "$ISSUE_PROVENANCE" | grep -q "^github:"; then
    ISSUE_NUMBER=$(echo "$ISSUE_PROVENANCE" | grep -oE '#[0-9]+' | tr -d '#')
  fi
fi

不使用
--issue
标志时：

所有参数均为阶段描述
示例：
```
/kata-add-phase 添加身份验证
```
→ description = "添加身份验证"
```
ISSUE_FILE
```
、
```
ISSUE_PROVENANCE
```
、
```
ISSUE_NUMBER
```
为空

如果未提供参数：

ERROR: 需提供阶段描述
用法: /kata-add-phase <描述>
       /kata-add-phase --issue <issue文件路径>
示例: /kata-add-phase 添加身份验证系统

退出。 </step>

<step name="load_roadmap"> 加载路线图文件：

bash

if [ -f .planning/ROADMAP.md ]; then
  ROADMAP=".planning/ROADMAP.md"
else
  echo "ERROR: No roadmap found (.planning/ROADMAP.md)"
  exit 1
fi

读取路线图内容以进行解析。 </step>

<step name="find_current_milestone"> 解析路线图以找到当前里程碑部分：

定位"## Current Milestone:"标题
提取里程碑名称和版本
识别该里程碑下的所有阶段（在下一个"---"分隔符或下一个里程碑标题之前）
解析现有阶段编号（包括可能存在的小数）

示例结构：

undefined

Current Milestone: v1.0 Foundation

Phase 4: Focused Command System

Phase 5: Path Routing & Validation

Phase 6: Documentation & Distribution


</step>

<step name="calculate_next_phase">
Find the highest integer phase number in the current milestone:

1. Extract all phase numbers from phase headings (### Phase N:)
2. Filter to integer phases only (ignore decimals like 4.1, 4.2)
3. Find the maximum integer value
4. Add 1 to get the next phase number

Example: If phases are 4, 5, 5.1, 6 → next is 7

Format as two-digit: `printf "%02d" $next_phase`
</step>

<step name="generate_slug">
Convert the phase description to a kebab-case slug:

```bash


</step>

<step name="calculate_next_phase">
找到当前里程碑中最高的整数阶段编号：

1. 从阶段标题中提取所有阶段编号（### Phase N:）
2. 仅筛选整数阶段（忽略如4.1、4.2这样的小数）
3. 找到最大的整数值
4. 加1得到下一个阶段编号

示例：如果阶段为4、5、5.1、6 → 下一个阶段为7

格式化为两位数：`printf "%02d" $next_phase`
</step>

<step name="generate_slug">
将阶段描述转换为短横线分隔的小写格式（kebab-case slug）：

```bash

Example transformation:

示例转换:

"Add authentication" → "add-authentication"

"Fix critical performance issues" → "fix-critical-performance-issues"

slug=$(echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')


Phase directory name: `{two-digit-phase}-{slug}`
Example: `07-add-authentication`
</step>

<step name="create_phase_directory">
Create the phase directory structure:

```bash
phase_dir=".planning/phases/pending/${phase_num}-${slug}"
mkdir -p "$phase_dir"

Confirm: "Created directory: $phase_dir" </step>

<step name="update_roadmap"> Add the new phase entry to the roadmap:

Find the insertion point (after last phase in current milestone, before "---" separator)

Insert new phase heading:

### Phase {N}: {Description}

**Goal:** [To be planned]
**Depends on:** Phase {N-1}
{if ISSUE_NUMBER: **Issue:** Closes #{ISSUE_NUMBER}}
**Plans:** 0 plans

Plans:
- [ ] TBD (run /kata-plan-phase {N} to break down)

**Details:**
[To be added during planning]

ISSUE_NUMBER

is set (from

--issue

flag), include the

**Issue:** Closes #{N}

line. This ensures PRs referencing this phase will auto-close the GitHub issue.

Write updated roadmap back to file

Preserve all other content exactly (formatting, spacing, other phases). </step>

<step name="update_project_state"> Update STATE.md to reflect the new phase:

Read
```
.planning/STATE.md
```
Under "## Current Position" → "Next Phase:" add reference to new phase
Under "## Accumulated Context" → "### Roadmap Evolution" add entry:
```
- Phase {N} added: {description}
```

If "Roadmap Evolution" section doesn't exist, create it. </step>

<step name="completion"> Present completion summary:

Phase {N} added to current milestone:
- Description: {description}
- Directory: .planning/phases/{phase-num}-{slug}/
- Status: Not planned yet
{if ISSUE_NUMBER: - Issue: Closes #${ISSUE_NUMBER} (linked from ${ISSUE_FILE})}

Roadmap updated: {roadmap-path}
Project state updated: .planning/STATE.md

---

slug=$(echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')


阶段目录名称：`{two-digit-phase}-{slug}`
示例：`07-add-authentication`
</step>

<step name="create_phase_directory">
创建阶段目录结构：

```bash
phase_dir=".planning/phases/pending/${phase_num}-${slug}"
mkdir -p "$phase_dir"

确认："Created directory: $phase_dir" </step>

<step name="update_roadmap"> 将新阶段条目添加到路线图中：

找到插入位置（当前里程碑的最后一个阶段之后，"---"分隔符之前）

插入新的阶段标题：

### Phase {N}: {Description}

**Goal:** [To be planned]
**Depends on:** Phase {N-1}
{if ISSUE_NUMBER: **Issue:** Closes #{ISSUE_NUMBER}}
**Plans:** 0 plans

Plans:
- [ ] TBD (run /kata-plan-phase {N} to break down)

**Details:**
[To be added during planning]

如果设置了

ISSUE_NUMBER

（来自

--issue

标志），则包含

**Issue:** Closes #{N}

行。这确保引用该阶段的PR会自动关闭GitHub issue。

将更新后的路线图写回文件

完全保留所有其他内容（格式、空格、其他阶段）。 </step>

<step name="update_project_state"> 更新STATE.md以反映新阶段：

读取
```
.planning/STATE.md
```
在"## Current Position" → "Next Phase:"下添加对新阶段的引用
在"## Accumulated Context" → "### Roadmap Evolution"下添加条目：
```
- Phase {N} added: {description}
```

如果“Roadmap Evolution”部分不存在，则创建该部分。 </step>

<step name="completion"> 展示完成总结：

Phase {N} added to current milestone:
- Description: {description}
- Directory: .planning/phases/{phase-num}-{slug}/
- Status: Not planned yet
{if ISSUE_NUMBER: - Issue: Closes #${ISSUE_NUMBER} (linked from ${ISSUE_FILE})}

Roadmap updated: {roadmap-path}
Project state updated: .planning/STATE.md

---

▶ Next Up

Phase {N}: {description}

/kata-plan-phase {N}

<sub>

/clear

first → fresh context window</sub>

Also available:

```
/kata-add-phase <description>
```
— add another phase
Review roadmap

</step>

</process>

<anti_patterns>

- Don't modify phases outside current milestone
- Don't renumber existing phases
- Don't use decimal numbering (that's /kata-insert-phase)
- Don't create plans yet (that's /kata-plan-phase)
- Don't commit changes (user decides when to commit)
  </anti_patterns>

<success_criteria>
Phase addition is complete when:

- [ ] Phase directory created: `.planning/phases/pending/{NN}-{slug}/`
- [ ] Roadmap updated with new phase entry
- [ ] STATE.md updated with roadmap evolution note
- [ ] New phase appears at end of current milestone
- [ ] Next phase number calculated correctly (ignoring decimals)
- [ ] User informed of next steps
      </success_criteria>

Phase {N}: {description}

/kata-plan-phase {N}

<sub>

/clear

first → fresh context window</sub>

Also available:

```
/kata-add-phase <description>
```
— add another phase
Review roadmap

</step>

</process>

<anti_patterns>

- 不要修改当前里程碑之外的阶段
- 不要重新编号现有阶段
- 不要使用小数编号（那是/kata-insert-phase的功能）
- 不要创建计划（那是/kata-plan-phase的功能）
- 不要提交更改（由用户决定何时提交）
  </anti_patterns>

<success_criteria>
阶段添加完成的标准：

- [ ] 阶段目录已创建：`.planning/phases/pending/{NN}-{slug}/`
- [ ] 路线图已更新，添加了新阶段条目
- [ ] STATE.md已更新，添加了路线图演进记录
- [ ] 新阶段出现在当前里程碑的末尾
- [ ] 下一个阶段编号计算正确（忽略小数）
- [ ] 已告知用户下一步操作
      </success_criteria>