rs-init

你正在为项目配置 RootSpec。首先告诉开发者你即将进行的操作：

“我将为这个项目配置 RootSpec——创建规范目录、复制框架文件，并配置前置条件（开发服务器、测试运行器等）。这需要一两分钟。”

步骤 1：扫描项目

了解项目中已有的内容。在项目根目录运行以下命令：

bash "$(dirname "$0")/../rs-shared/scripts/scan-spec.sh" .
bash "$(dirname "$0")/../rs-shared/scripts/scan-project.sh" .

如果这些路径无法解析，请在 skills 目录中搜索 scan-spec.sh，找到脚本。

根据输出判断项目的情况：

• 全新初始化 — 不存在 .rootspec.json，也没有 rootspec/ 目录。这是最常见的情况。
• 部分初始化 — 部分文件存在，但其他文件缺失（之前的初始化被中断）。
• 重新初始化 — .rootspec.json 已存在。如果其版本低于随附的框架版本，请改为建议运行 /rs-update。否则，询问开发者想更新哪些内容。不要覆盖现有的规范文件（01-05）。如果开发者确认，你可以将 00.AXIOMS.md 和 00.FRAMEWORK.md 更新为随附的最新版本。
• 已完成初始化 — 所有内容均已存在。告知开发者，并建议改为运行 /rs-spec。

继续之前，先汇报你发现的情况。

步骤 2：引导配置项目

运行引导脚本，创建规范目录、基础文件、前置条件和 .rootspec.json：

bash "$(dirname "$0")/../rs-shared/scripts/bootstrap-init.sh" . "$(dirname "$0")/../rs-shared"

如果此路径无法解析，请在 skills 目录中搜索 bootstrap-init.sh，找到脚本。

此脚本会为全新项目创建所需的一切：包含框架文件的 rootspec/、scripts/dev.sh、scripts/test.sh、.githooks/pre-commit、scripts/release.sh、Cypress 报告器、.rootspec.json 和 package.json。已存在的文件会跳过。

步骤 3：检测并调整前置条件

运行检测脚本，检查引导配置创建的内容与项目原有内容：

bash "$(dirname "$0")/../rs-shared/scripts/detect-prerequisites.sh" .

脚本会输出 DEV_SERVER=、PRE_COMMIT_HOOK=、RELEASE_SCRIPT=、VALIDATION_SCRIPT= 行，其中包含检测到的路径或 none。

阅读 ../rs-shared/fragments/prerequisites.md，了解各项前置条件的完整说明。

**package.json 规则：**绝不可直接写入 package.json 的 dependencies 或 devDependencies 部分。添加软件包时，始终使用 npm install <pkg> 或 npm install --save-dev <pkg>——由 npm 管理依赖树。你可以直接编辑 scripts 部分（例如添加 dev:start）。

汇报检测结果。对于棕地项目，请调整引导配置的默认值：

• 开发服务器 — scripts/dev.sh 和 scripts/preview.sh 内置了空的 DEV_CMD/PREVIEW_CMD 和递归防护。填入命令前，它们会直接失败。不要在此处设置它们——/rs-impl 会运行 detect-stack.sh，并根据检测到的技术栈（或从项目引导配置前的 package.json 中捕获、保存在 .rootspec.json 的 prerequisites.detected 中的原始值）写入框架二进制文件。在交接时说明：“运行 /rs-impl 以填充开发/预览封装脚本并创建约定。”
• 已有前置条件 — 如果项目已有开发服务器、测试运行器等，请更新 .rootspec.json，使其指向这些已有项，而不是引导配置的默认项。
• package.json 脚本 — 如果尚未包含 dev:start、dev:stop、dev:restart，请添加这些条目。dev、preview 和 start 脚本必须通过 ./scripts/dev.sh / ./scripts/preview.sh 运行。全新项目中，bootstrap-init.sh 会按此方式写入脚本；棕地项目中，请将任何现有的 dev/preview/start 脚本改为通过封装脚本运行。（改写前的值会捕获到 .rootspec.json 的 prerequisites.detected 中，以供 /rs-impl 重用。）

Cypress 插件设置

设置 RootSpec Cypress reporter（bootstrap 已复制该文件）：

1. 将其接入 cypress.config.ts — 如果配置文件已存在，请添加包含 reporter 的 setupNodeEvents 钩子。如果要新建配置文件，请从一开始就包含它。确切的接入方式请参阅 ../rs-shared/fragments/prerequisites.md。

此插件会在每次 Cypress 运行后自动更新 rootspec/tests-status.json — Agent 无需解析结果或调用脚本。

步骤 4：更新 .rootspec.json

如果步骤 3 检测到现有的先决条件与 bootstrap 默认值不同，请使用正确路径更新 .rootspec.json。

步骤 5：验证并交接

运行验证脚本：

bash "$(dirname "$0")/../rs-shared/scripts/verify-init.sh" .

如果报告有任何缺失项，请创建它们。然后报告：

"项目已初始化。以下是已设置的内容：

• [创建的文件列表]
• [已配置或跳过的先决条件列表]

运行 /rs-spec 创建规范。"

重点

如果开发者传入参数：

• "resume" → 跳转到尚未完成的步骤
• "prerequisites" → 仅运行步骤 3-4（检测/创建先决条件，更新 .rootspec.json）

范围

• 可以读取： 所有项目文件
• 可以写入： rootspec/ 目录（包括 spec-status.json、tests-status.json）、.rootspec.json、先决条件模板（例如 scripts/dev.sh）
• 不应写入： 应用源代码、现有测试文件