kata-customize

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

<objective> Manage template overrides for customizing Kata output formats.

Templates control the structure of planning artifacts (plans, summaries, UAT sessions, verification reports, changelogs). Override a template to change how Kata generates these files for your project.

Operations: list, copy, edit, validate. </objective>

<context> $ARGUMENTS </context> <process>

<objective> 管理模板覆盖以自定义Kata输出格式。

模板控制规划工件（计划、摘要、UAT会话、验证报告、变更日志）的结构。通过覆盖模板，可以更改Kata为你的项目生成这些文件的方式。

操作：列出、复制、编辑、验证。 </objective>

<context> $ARGUMENTS </context> <process>

1. Validate Environment

1. 验证环境

bash

ls .planning/ 2>/dev/null

If not found: Error — run

/kata-new-project

first.

bash

ls .planning/ 2>/dev/null

如果未找到： 错误 — 先运行

/kata-new-project

。

2. Determine Operation

2. 确定操作

Parse

$ARGUMENTS

for the operation:

If contains "list" or "show" or no arguments → list operation
If contains "copy" → copy operation (extract template name from remaining args)
If contains "edit" or "modify" or "change" → edit operation (extract template name)
If contains "validate" or "check" or "drift" → validate operation

If unclear, present AskUserQuestion:

What would you like to do?

1. **List templates** — See all customizable templates and their override status
2. **Copy a template** — Copy a default template for local customization
3. **Edit a template** — Modify an existing template override
4. **Validate overrides** — Check all overrides for missing required fields

解析

$ARGUMENTS

以确定操作：

如果包含“list”或“show”或无参数 → 列出操作
如果包含“copy” → 复制操作（从剩余参数中提取模板名称）
如果包含“edit”或“modify”或“change” → 编辑操作（提取模板名称）
如果包含“validate”或“check”或“drift” → 验证操作

如果不明确，显示AskUserQuestion：

你想要执行什么操作？

1. **列出模板** — 查看所有可自定义的模板及其覆盖状态
2. **复制模板** — 复制默认模板供本地定制
3. **编辑模板** — 修改现有的模板覆盖
4. **验证覆盖** — 检查所有覆盖是否缺少必填字段

3. List Operation

3. 列出操作

Run the discovery script:

bash

bash scripts/list-templates.sh

Parse the JSON output. Display:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Kata > CUSTOMIZABLE TEMPLATES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

| Template | Used By | Controls | Status |
| --- | --- | --- | --- |
| summary-template.md | kata-execute-phase | Phase completion docs | {override / default} |
| plan-template.md | kata-plan-phase | Phase plan structure | {override / default} |
| UAT-template.md | kata-verify-work | UAT session format | {override / default} |
| verification-report.md | kata-verify-work | Verification report format | {override / default} |
| changelog-entry.md | kata-complete-milestone | Changelog entry format | {override / default} |

Override location: `.planning/templates/`

To customize a template:
  `/kata-customize copy summary-template.md`

After displaying the list, stop. Do not proceed to another operation.

运行发现脚本：

bash

bash scripts/list-templates.sh

解析JSON输出。显示：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Kata > 可自定义模板
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

| 模板 | 适用命令 | 控制内容 | 状态 |
| --- | --- | --- | --- |
| summary-template.md | kata-execute-phase | 阶段完成文档 | {已覆盖 / 默认} |
| plan-template.md | kata-plan-phase | 阶段计划结构 | {已覆盖 / 默认} |
| UAT-template.md | kata-verify-work | UAT会话格式 | {已覆盖 / 默认} |
| verification-report.md | kata-verify-work | 验证报告格式 | {已覆盖 / 默认} |
| changelog-entry.md | kata-complete-milestone | 变更日志条目格式 | {已覆盖 / 默认} |

覆盖文件位置：`.planning/templates/`

要自定义模板：
  `/kata-customize copy summary-template.md`

显示列表后停止，不进行其他操作。

4. Copy Operation

4. 复制操作

Requires a template name argument. If not provided, run list operation first, then ask user to select.

Step 4a: Resolve the default template path

bash

DEFAULT_PATH=$(node scripts/kata-lib.cjs resolve-template "$TEMPLATE_NAME" 2>&1)

If the resolve script exits non-zero, the template name is invalid. Display the error and stop.

Step 4b: Check for existing override

bash

[ -f ".planning/templates/$TEMPLATE_NAME" ] && echo "EXISTS" || echo "NEW"

If EXISTS, ask user via AskUserQuestion:

An override for `{TEMPLATE_NAME}` already exists at `.planning/templates/{TEMPLATE_NAME}`.

1. **Overwrite** — Replace with default (your customizations will be lost)
2. **Cancel** — Keep current override

If user selects Cancel, stop.

Step 4c: Copy the default

bash

mkdir -p .planning/templates
cp "$DEFAULT_PATH" ".planning/templates/$TEMPLATE_NAME"

Step 4d: Confirm

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Kata > TEMPLATE COPIED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Copied default to: `.planning/templates/{TEMPLATE_NAME}`

Edit the file to customize, then validate:
  `/kata-customize validate`

需要模板名称参数。如果未提供，先运行列出操作，然后让用户选择。

步骤4a：解析默认模板路径

bash

DEFAULT_PATH=$(node scripts/kata-lib.cjs resolve-template "$TEMPLATE_NAME" 2>&1)

如果解析脚本返回非零值，说明模板名称无效。显示错误并停止。

步骤4b：检查是否存在现有覆盖

bash

[ -f ".planning/templates/$TEMPLATE_NAME" ] && echo "EXISTS" || echo "NEW"

如果存在，通过AskUserQuestion询问用户：

`{TEMPLATE_NAME}`的覆盖文件已存在于`.planning/templates/{TEMPLATE_NAME}`。

1. **覆盖** — 替换为默认模板（你的自定义内容将丢失）
2. **取消** — 保留当前覆盖文件

如果用户选择取消，停止操作。

步骤4c：复制默认模板

bash

mkdir -p .planning/templates
cp "$DEFAULT_PATH" ".planning/templates/$TEMPLATE_NAME"

步骤4d：确认

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Kata > 模板已复制
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

已将默认模板复制到：`.planning/templates/{TEMPLATE_NAME}`

编辑文件进行自定义，然后验证：
  `/kata-customize validate`

5. Edit Operation

5. 编辑操作

Requires a template name argument. If not provided, run list operation to show overrides, then ask which to edit.

Step 5a: Check override exists

bash

[ -f ".planning/templates/$TEMPLATE_NAME" ] && echo "EXISTS" || echo "MISSING"

If MISSING, ask user via AskUserQuestion:

No override exists for `{TEMPLATE_NAME}`.

1. **Copy and edit** — Copy the default first, then edit
2. **Cancel** — Do nothing

If user selects "Copy and edit", run step 4c first.

Step 5b: Read current content

Read

.planning/templates/{TEMPLATE_NAME}

and display the current content to the user.

Step 5c: Accept modifications

Ask the user what they want to change. Two paths:

If user describes specific changes ("change heading X to Y", "add field Z"), apply the edits to the file using Edit tool and write the updated content.
If user says they will edit externally ("let me edit it", "I'll do it in my editor"), acknowledge and offer to validate when they return.

Step 5d: Validate after edit

After writing changes (or when user returns from external editing), run single-template validation:

bash

node scripts/kata-lib.cjs check-template-drift

If drift warnings mention the edited template, display them. If clean, display:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Kata > TEMPLATE VALID
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

`{TEMPLATE_NAME}` has all required fields. Override is active.

需要模板名称参数。如果未提供，运行列出操作显示覆盖文件，然后询问要编辑哪个。

步骤5a：检查覆盖文件是否存在

bash

[ -f ".planning/templates/$TEMPLATE_NAME" ] && echo "EXISTS" || echo "MISSING"

如果不存在，通过AskUserQuestion询问用户：

`{TEMPLATE_NAME}`的覆盖文件不存在。

1. **复制并编辑** — 先复制默认模板，再编辑
2. **取消** — 不执行任何操作

如果用户选择“复制并编辑”，先执行步骤4c。

步骤5b：读取当前内容

读取

.planning/templates/{TEMPLATE_NAME}

并向用户显示当前内容。

步骤5c：接受修改

询问用户想要更改的内容。两种情况：

如果用户描述了具体更改（“将标题X改为Y”、“添加字段Z”），使用Edit工具将编辑应用到文件并写入更新后的内容。
如果用户表示将在外部编辑（“让我自己编辑”、“我会在我的编辑器中修改”），确认并在用户返回时提供验证服务。

步骤5d：编辑后验证

写入更改后（或用户从外部编辑返回后），运行单模板验证：

bash

node scripts/kata-lib.cjs check-template-drift

如果漂移警告提到已编辑的模板，显示这些警告。如果验证通过，显示：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Kata > 模板验证通过
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

`{TEMPLATE_NAME}`包含所有必填字段。覆盖已生效。

6. Validate Operation

6. 验证操作

Run validation on all overrides:

bash

DRIFT_OUTPUT=$(node scripts/kata-lib.cjs check-template-drift 2>/dev/null)

DRIFT_OUTPUT

is empty and

.planning/templates/

exists with .md files:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Kata > ALL TEMPLATES VALID
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

All template overrides pass schema validation.

DRIFT_OUTPUT

is empty and no overrides exist:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Kata > NO OVERRIDES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

No template overrides found at `.planning/templates/`.

To create an override:
  `/kata-customize copy summary-template.md`

DRIFT_OUTPUT

has content (warnings):

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Kata > TEMPLATE DRIFT DETECTED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

{DRIFT_OUTPUT}

To fix, edit the override or reset to default:
  `/kata-customize edit {template-name}`
  `/kata-customize copy {template-name}` (resets to default)

</process>

<success_criteria>

Templates listed with descriptions and override status
Default copied to .planning/templates/ with overwrite protection
Edit operation reads current content and applies user changes
Validation runs after edit and reports missing fields
All operations use existing infrastructure (kata-lib.cjs resolve-template, kata-lib.cjs check-template-drift)
Skill responds to natural language triggers </success_criteria>

对所有覆盖文件运行验证：

bash

DRIFT_OUTPUT=$(node scripts/kata-lib.cjs check-template-drift 2>/dev/null)

如果

DRIFT_OUTPUT

为空且

.planning/templates/

存在.md文件：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Kata > 所有模板验证通过
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

所有模板覆盖均通过架构验证。

如果

DRIFT_OUTPUT

为空且无覆盖文件：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Kata > 无覆盖文件
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

在`.planning/templates/`未找到模板覆盖文件。

要创建覆盖文件：
  `/kata-customize copy summary-template.md`

如果

DRIFT_OUTPUT

有内容（警告）：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Kata > 检测到模板漂移
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

{DRIFT_OUTPUT}

要修复，请编辑覆盖文件或重置为默认模板：
  `/kata-customize edit {template-name}`
  `/kata-customize copy {template-name}`（重置为默认）

</process>

<success_criteria>

模板已列出并附带描述和覆盖状态
默认模板已复制到.planning/templates/并带有覆盖保护
编辑操作读取当前内容并应用用户更改
编辑后运行验证并报告缺失字段
所有操作使用现有基础设施（kata-lib.cjs resolve-template, kata-lib.cjs check-template-drift）
Skill响应自然语言触发词 </success_criteria>