spec-kitty-sync-plugin

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Spec Kitty Sync Plugin

Spec Kitty 同步插件

You are an active administrator for the Spec-Driven Development framework. This skill handles both initial setup and ongoing updates, ensuring the CLI, templates, plugin, and agent environments are all in sync.

Key principle: This project maintains two layers of knowledge:

Upstream content (auto-synced from spec-kitty CLI) — command templates, rules, mission configs
Custom augmented knowledge (hand-maintained) — best practices, safety guidance, workflow notes, project-specific conventions

The sync must NEVER overwrite custom augmented knowledge. Instead, the agent reviews upstream changes and intelligently reconciles them with existing custom content.

你是**规约驱动开发（Spec-Driven Development）**框架的活跃管理员。本技能同时负责初始搭建和持续更新，确保CLI、模板、插件和Agent环境全部保持同步。

核心原则：本项目维护两层知识：

上游内容（从spec-kitty CLI自动同步）—— 命令模板、规则、任务配置
自定义增强知识（人工维护）—— 最佳实践、安全指南、工作流笔记、项目特定规范

同步操作绝对不能覆盖自定义增强知识。相反，Agent会审查上游变更，并智能地将其与现有自定义内容进行协调。

Visual References

可视化参考

Update flow: See
```
sync-plugin-flow.mmd
```
Initial install flow: See
```
init-install-flow.mmd
```

更新流程：参见
```
sync-plugin-flow.mmd
```
初始安装流程：参见
```
init-install-flow.mmd
```

Execution Protocol

执行协议

CRITICAL RULE: Do not simulate these steps. You must invoke the bash commands and read their outputs.

关键规则：请勿模拟这些步骤。你必须调用bash命令并读取其输出。

Step 0: Detect Mode (Init vs Update)

步骤0：检测模式（初始化vs更新）

Check if

.kittify/

exists in the project root:

bash

test -d .kittify && echo "UPDATE" || echo "INIT"

INIT mode: First-time setup. Use
```
spec-kitty init .
```
(no
```
--force
```
).
UPDATE mode: Refresh existing setup. Use
```
spec-kitty init . --force
```
.

检查项目根目录下是否存在

.kittify/

：

bash

test -d .kittify && echo "UPDATE" || echo "INIT"

INIT模式：首次搭建。使用
```
spec-kitty init .
```
（不加
```
--force
```
参数）。
UPDATE模式：刷新现有配置。使用
```
spec-kitty init . --force
```
。

Step 1: Install or Upgrade the CLI

步骤1：安装或升级CLI

Install or update the

spec-kitty-cli

package:

bash

pip install --upgrade spec-kitty-cli

Confirm the installed version:

bash

spec-kitty --version

安装或更新

spec-kitty-cli

包：

bash

pip install --upgrade spec-kitty-cli

确认已安装的版本：

bash

spec-kitty --version

Step 2: Initialize or Refresh Templates

步骤2：初始化或刷新模板

Pull the latest command templates, mission configs, and scripts into

.kittify/

INIT mode (first time):

bash

spec-kitty init . --ai windsurf

This creates
.kittify/
,
.windsurf/workflows/
, mission configs, and git hooks.

UPDATE mode (existing project):

bash

spec-kitty init . --ai windsurf --force

This refreshes existing templates without affecting project-specific configs.

拉取最新的命令模板、任务配置和脚本到

.kittify/

INIT模式（首次搭建）：

bash

spec-kitty init . --ai windsurf

这将创建
.kittify/
、
.windsurf/workflows/
、任务配置和git钩子。

UPDATE模式（已有项目）：

bash

spec-kitty init . --ai windsurf --force

这将刷新现有模板，不会影响项目专属配置。

Step 3: Sync to Spec-Kitty Plugin (Automated)

步骤3：同步到Spec-Kitty插件（自动执行）

Convert the refreshed

.kittify/

templates into distributable plugin components inside

plugins/spec-kitty-plugin/

bash

python3 plugins/spec-kitty-plugin/skills/spec-kitty-agent/scripts/sync_configuration.py

This generates skills, rules, and templates that agents can consume.

IMPORTANT: This step ONLY touches auto-generated files (14 command skill SKILL.md files, rules, templates). It does NOT touch custom skills listed below.

将刷新后的

.kittify/

模板转换为

plugins/spec-kitty-plugin/

目录下可分发的插件组件：

bash

python3 plugins/spec-kitty-plugin/skills/spec-kitty-agent/scripts/sync_configuration.py

这将生成Agent可使用的技能、规则和模板。

重要提示：本步骤仅修改自动生成的文件（14个命令技能SKILL.md文件、规则、模板），不会修改下方列出的自定义技能。

Step 3b: Review & Reconcile Custom Knowledge (Agent-Reviewed)

步骤3b：审查与协调自定义知识（Agent审核）

This is the intelligence step. After the automated sync, you MUST review what changed and reconcile with custom augmented skills.

这是核心智能步骤。自动同步完成后，你必须审查变更内容，并与自定义增强技能进行协调。

3b.1: Identify What Changed

3b.1：识别变更内容

Compare the new

.kittify/

content against what was there before:

bash

git diff --stat -- .kittify/ .windsurf/ plugins/spec-kitty-plugin/

Summarize the key changes for the user (new commands, removed commands, changed templates, updated mission configs).

将新的

.kittify/

内容与之前的版本进行对比：

bash

git diff --stat -- .kittify/ .windsurf/ plugins/spec-kitty-plugin/

为用户总结核心变更（新增命令、移除命令、模板修改、任务配置更新）。

3b.2: Review Custom Skills

3b.2：审查自定义技能

The following contain custom augmented knowledge that is NOT generated by

sync_configuration.py

. They MUST be reviewed for staleness after every upstream update:

Custom Skills (in

skills/

, never touched by sync):

Custom Skill	Contains	Review For
`skills/spec-kitty-workflow/SKILL.md`	End-to-end workflow guide, safety steps, best practices	New commands/phases added upstream, safety guidance still accurate
`skills/spec-kitty-sync-plugin/SKILL.md`	This skill (meta)	Script paths still valid, new sync features
`skills/spec-kitty-agent/SKILL.md`	Agent config sync, combined lifecycle	New agent configs, changes to sync scripts

AUGMENTED.md Files (in

skills/*/references/

, adjacent to auto-synced SKILL.md — never overwritten):

Augmented File	Contains	Review For
`skills/spec-kitty-merge/references/AUGMENTED.md`	Pre-merge safety protocol, branch protection awareness, kitty-specs conflict resolution	New merge flags, changed CLI behavior
`skills/spec-kitty-implement/references/AUGMENTED.md`	Worktree discipline, commit hygiene, dependency management	New implement flags, changed validation rules
`skills/spec-kitty-review/references/AUGMENTED.md`	Batch review protocol, review standards, dependency verification	New review commands, changed lane logic

For each custom skill:

Read the current content
Compare against the new upstream
```
.kittify/
```
command templates
Check if any new features, commands, or workflow changes require updates
Check if any existing custom guidance references deprecated features

以下内容包含

sync_configuration.py

不会生成的自定义增强知识，每次上游更新后都必须审查其是否过时：

自定义技能（位于

skills/

目录，同步操作永远不会修改）：

自定义技能	包含内容	审查要点
`skills/spec-kitty-workflow/SKILL.md`	端到端工作流指南、安全步骤、最佳实践	上游是否新增命令/阶段、安全指南是否仍然准确
`skills/spec-kitty-sync-plugin/SKILL.md`	本技能（元技能）	脚本路径是否仍然有效、是否有新的同步功能
`skills/spec-kitty-agent/SKILL.md`	Agent配置同步、全生命周期管理	新增的Agent配置、同步脚本的变更

AUGMENTED.md文件（位于

skills/*/references/

目录，与自动同步的SKILL.md相邻，永远不会被覆盖）：

增强文件	包含内容	审查要点
`skills/spec-kitty-merge/references/AUGMENTED.md`	合并前安全协议、分支保护感知、kitty-specs冲突解决方案	新增的合并参数、CLI行为变更
`skills/spec-kitty-implement/references/AUGMENTED.md`	工作树规范、提交规范、依赖管理	新增的implement参数、验证规则变更
`skills/spec-kitty-review/references/AUGMENTED.md`	批量审查协议、审查标准、依赖验证	新增的审查命令、流程逻辑变更

针对每个自定义技能：

读取当前内容
与上游最新的
```
.kittify/
```
命令模板进行对比
检查是否有新功能、命令或工作流变更需要更新
检查现有自定义指南是否引用了已弃用的功能

3b.3: Propose Updates (Never Overwrite)

3b.3：提出更新建议（绝不覆盖）

If changes are needed in custom skills:

ADD new sections for new upstream features
UPDATE references to renamed or changed commands
PRESERVE all custom best practices, safety guidance, and project-specific notes
FLAG any conflicts between upstream changes and custom guidance for user review

Present proposed changes to the user in diff format before applying them.

如果自定义技能需要修改：

新增上游新功能对应的章节
更新重命名或变更后的命令引用
保留所有自定义最佳实践、安全指南和项目专属说明
标记上游变更与自定义指南之间的任何冲突，供用户审查

在应用变更前，以diff格式向用户展示提议的修改内容。

3b.4: Protected Files Checklist & Escalation Taxonomy

3b.4：受保护文件检查清单与上报分类

Before completing the sync, verify these files were NOT deleted or corrupted:

.agent/rules/constitution.md

(symlinked from

.kittify/memory/

)

```
.agent/rules/standard-workflow-rules.md
```
```
.agent/rules/01_PROCESS/*
```
(policy files)
```
.agent/rules/02_OPERATIONS/*
```
```
.agent/rules/03_TECHNICAL/*
```

bash

test -f .agent/rules/constitution.md && echo "constitution OK" || echo "MISSING!"
ls .agent/rules/01_PROCESS/ .agent/rules/02_OPERATIONS/ .agent/rules/03_TECHNICAL/ 2>/dev/null | head -20

Escalation Taxonomy (Missing Data Response) If ANY protected file is missing or

ls

returns an error, trigger the Escalation Taxonomy:

Stop: Do not proceed to Step 4 (Bridging).
Alert:
```
🚨 PROTECTED FILE MISSING 🚨
```
Explain: State which file is missing (e.g., "constitution.md was deleted during update").
Recommend: "We must restore this file from git history before bridging plugins."
Draft: Ask the user for permission to run
```
git checkout -- <file>
```
.

完成同步前，验证以下文件未被删除或损坏：

.agent/rules/constitution.md

（从

.kittify/memory/

软链接而来）

```
.agent/rules/standard-workflow-rules.md
```
```
.agent/rules/01_PROCESS/*
```
（策略文件）
```
.agent/rules/02_OPERATIONS/*
```
```
.agent/rules/03_TECHNICAL/*
```

bash

test -f .agent/rules/constitution.md && echo "constitution OK" || echo "MISSING!"
ls .agent/rules/01_PROCESS/ .agent/rules/02_OPERATIONS/ .agent/rules/03_TECHNICAL/ 2>/dev/null | head -20

上报分类（数据缺失响应） 如果任何受保护文件缺失或

ls

返回错误，触发上报流程：

停止：不要继续执行步骤4（对接）。
告警：
```
🚨 受保护文件缺失 🚨
```
说明：指出哪个文件缺失（例如："constitution.md在更新过程中被删除"）。
建议："我们必须先从git历史中恢复该文件，再对接插件。"
草案：请求用户允许执行
```
git checkout -- <file>
```
命令。

Step 4: Bridge to Agent Environments (Interactive)

步骤4：对接Agent环境（交互执行）

ASK THE USER before bridging:

Which plugins should I bridge?

Only spec-kitty-plugin (just the updated spec-kitty commands)

All plugins (full ecosystem sync across all plugins)

Which agent environments?

antigravity, claude, github, gemini, windsurf, or all

If spec-kitty-plugin only: Invoke your ecosystem's specific plugin bridge mapping script targeted specifically at

plugins/spec-kitty-plugin

for the selected agent environments.

If all plugins: Invoke your ecosystem's specific

install-all

mapping script across the entire

plugins/

directory for the selected agent environments. Repeat for each selected agent environment, or run once per target.

对接前询问用户：

我应该对接哪些插件？

仅spec-kitty-plugin（仅更新后的spec-kitty命令）

所有插件（全生态所有插件同步）

对接哪些Agent环境？

antigravity、claude、github、gemini、windsurf，或全部

如果仅选择spec-kitty-plugin：调用你生态系统专属的插件桥接映射脚本，针对选中的Agent环境仅对接

plugins/spec-kitty-plugin

。

如果选择所有插件：调用你生态系统专属的

install-all

映射脚本，针对选中的Agent环境遍历整个

plugins/

目录。为每个选中的Agent环境重复执行，或针对每个目标运行一次。

Step 5: Confirmation

步骤5：确认

Inform the user:

Whether this was an INIT or UPDATE
Which CLI version is now installed
How many skills/rules/templates were synced (auto-generated)
What changed in the upstream update (key diff summary)
Whether any custom skills needed reconciliation (and what was proposed)
Whether all protected files are intact
Which plugins were bridged to which agents
That they must Reload their Window (or restart the agent session) to see the new commands

告知用户以下信息：

本次操作是INIT还是UPDATE
当前安装的CLI版本
同步了多少个技能/规则/模板（自动生成的）
上游更新的变更内容（核心diff摘要）
是否有自定义技能需要协调（以及提议了哪些修改）
所有受保护文件是否完好
哪些插件被对接到了哪些Agent
他们必须重载窗口（或重启Agent会话）才能看到新命令