rs-init

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

You are setting up a project to use RootSpec. Start by telling the developer what you're about to do:

"I'll set up RootSpec for this project — create the spec directory, copy the framework files, and configure prerequisites (dev server, test runner, etc.). This takes a minute or two."

你正在为项目配置RootSpec以使用该框架。首先告知开发者你即将执行的操作：

"我将为该项目设置RootSpec——创建spec目录、复制框架文件，并配置前置依赖（开发服务器、测试运行器等）。这需要一两分钟时间。"

Step 1: Scan the project

步骤1：扫描项目

Understand what exists. Run these from the project root:

bash

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

If these paths don't resolve, find the scripts by searching for

scan-spec.sh

in the skills directory.

Based on the output, determine the situation:

Fresh init — no
```
.rootspec.json
```
, no
```
rootspec/
```
directory. Most common case.
Partial init — some files exist but others are missing (interrupted previous init).
Re-init —
```
.rootspec.json
```
exists. If the version is behind the bundled framework, suggest
```
/rs-update
```
instead. Otherwise, ask the developer what they want to update. Do NOT overwrite existing spec files (01-05). You may update
```
00.AXIOMS.md
```
and
```
00.FRAMEWORK.md
```
to the latest bundled versions if the developer confirms.
Already initialized — everything exists. Tell the developer and suggest
```
/rs-spec
```
instead.

Report what you found before proceeding.

了解现有项目情况。在项目根目录下执行以下命令：

bash

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
```
命令。否则询问开发者想要更新的内容。请勿覆盖已有的spec文件（01-05）。如果开发者确认，你可以将
```
00.AXIOMS.md
```
和
```
00.FRAMEWORK.md
```
更新为最新的捆绑版本。
已完成初始化——所有文件都已存在。告知开发者并建议使用
```
/rs-spec
```
命令。

继续操作前先报告你扫描到的情况。

Step 2: Create the spec directory and base files

步骤2：创建spec目录和基础文件

Create whatever is missing:

rootspec/
directory —
```
mkdir -p rootspec
```
rootspec/00.AXIOMS.md
— copy from the bundled version at
```
../rs-shared/00.AXIOMS.md
```
(relative to this skill's directory). Read the source file and write it to the project.

rootspec/00.FRAMEWORK.md
— copy from

../rs-shared/00.FRAMEWORK.md

. Same approach.

rootspec/spec-status.json
:

json

{ "hash": null, "validatedAt": null, "valid": false, "version": "7.0.1" }

rootspec/tests-status.json
:

json

{ "lastRun": null, "stories": {} }

创建所有缺失的内容：

rootspec/
目录——执行
```
mkdir -p rootspec
```
rootspec/00.AXIOMS.md
——从该skill目录下的
```
../rs-shared/00.AXIOMS.md
```
捆绑版本复制。读取源文件并写入到项目中。

rootspec/00.FRAMEWORK.md
——从

../rs-shared/00.FRAMEWORK.md

复制，操作方式同上。

rootspec/spec-status.json
:

json

{ "hash": null, "validatedAt": null, "valid": false, "version": "7.0.1" }

rootspec/tests-status.json
:

json

{ "lastRun": null, "stories": {} }

Step 3: Detect or create prerequisites

步骤3：检测或创建前置依赖

Run the detection script:

bash

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

The script outputs

DEV_SERVER=

PRE_COMMIT_HOOK=

RELEASE_SCRIPT=

VALIDATION_SCRIPT=

lines with detected paths or

none

Read

../rs-shared/fragments/prerequisites.md

for the full reference on what each prerequisite is.

Report what was found. For missing prerequisites, tell the developer you'll create all templates and proceed unless they object:

"I'll create templates for [list missing]. These are lightweight and needed by

/rs-impl

and

/rs-validate

. Let me know if you'd rather skip any."

Then create them all. Do not present a menu of options or ask which ones to create — just create them. The developer can always delete what they don't want.

/rs-impl

needs the dev server and validation script.

/rs-validate

needs both. The pre-commit hook catches problems early. The release script is the only truly optional one, but it's cheap to create.

For each prerequisite:

Found → confirm with developer, record the path
Not found → create the template
Skipped (only if developer explicitly asks) → record
```
null
```

运行检测脚本：

bash

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

脚本会输出

DEV_SERVER=

、

PRE_COMMIT_HOOK=

、

RELEASE_SCRIPT=

、

VALIDATION_SCRIPT=

行，内容为检测到的路径或

none

。

阅读

../rs-shared/fragments/prerequisites.md

获取每个前置依赖的完整参考说明。

报告检测到的结果。对于缺失的前置依赖，告知开发者你将创建所有模板并继续操作，除非他们反对：

"我将为[缺失的依赖列表]创建模板。这些模板非常轻量，是

/rs-impl

和

/rs-validate

运行所需的依赖。如果你想跳过任何项请告知我。"

然后创建所有缺失的模板。不要展示选项菜单或者询问要创建哪些，直接创建即可。开发者随时可以删除不需要的内容。

/rs-impl

需要开发服务器和验证脚本，

/rs-validate

两者都需要。pre-commit钩子可以提前发现问题，发布脚本是唯一真正可选的依赖，但创建成本很低。

针对每个前置依赖：

已找到→向开发者确认，记录路径
未找到→创建模板
已跳过（仅开发者明确要求时）→记录为
```
null
```

Dev server template

开发服务器模板

When creating the dev server template:

Copy the bundled template from
```
../rs-shared/scripts/dev.sh
```
to
```
scripts/dev.sh
```
in the project. Make it executable. Read the source and write it — don't generate from scratch.
Edit the
DEV_CMD
variable at the top of the copied script to match the project's actual dev command (e.g.,
```
npm run dev
```
,
```
npx vite
```
, etc.).

Add package.json scripts if

package.json

exists — add

dev:start

dev:stop

, and

dev:restart

entries that delegate to

scripts/dev.sh

json

"dev:start": "./scripts/dev.sh start",
"dev:stop": "./scripts/dev.sh stop",
"dev:restart": "./scripts/dev.sh restart"

package.json

doesn't exist, tell the developer: "No package.json found — run

npm init

first if you want convenience scripts."

Update .gitignore — if
```
.gitignore
```
exists, add
```
.dev-server.pid
```
and
```
.dev-server.log
```
if not already present.

创建开发服务器模板时：

复制捆绑模板：将
```
../rs-shared/scripts/dev.sh
```
复制到项目的
```
scripts/dev.sh
```
路径，设置为可执行权限。读取源文件内容写入，不要从头生成。
编辑复制的脚本顶部的
DEV_CMD
变量，匹配项目实际的开发命令（例如
```
npm run dev
```
、
```
npx vite
```
等）。

添加package.json脚本：如果存在

package.json

，添加

dev:start

、

dev:stop

和

dev:restart

条目，指向

scripts/dev.sh

：

json

"dev:start": "./scripts/dev.sh start",
"dev:stop": "./scripts/dev.sh stop",
"dev:restart": "./scripts/dev.sh restart"

如果不存在

package.json

，告知开发者："未找到package.json——如果你需要便捷脚本请先执行

npm init

。"

更新.gitignore：如果存在
```
.gitignore
```
，如果
```
.dev-server.pid
```
和
```
.dev-server.log
```
不在其中则添加这两项。

Cypress plugin setup

Cypress插件设置

When creating the validation script template, also set up the RootSpec Cypress reporter:

Copy the reporter from

../rs-shared/cypress/rootspec-reporter.ts

cypress/support/rootspec-reporter.ts

in the project.

Wire it into
cypress.config.ts
— if the config exists, add the
```
setupNodeEvents
```
hook with the reporter. If creating a new config, include it from the start. See
```
../rs-shared/fragments/prerequisites.md
```
for the exact wiring.

This plugin automatically updates

rootspec/tests-status.json

after every Cypress run — the agent doesn't need to parse results or call scripts.

创建验证脚本模板时，同时设置RootSpec Cypress报告器：

复制报告器：将

../rs-shared/cypress/rootspec-reporter.ts

复制到项目的

cypress/support/rootspec-reporter.ts

路径。

接入
cypress.config.ts
：如果配置文件已存在，添加带有报告器的
```
setupNodeEvents
```
钩子。如果是创建新配置，初始就包含该配置。查看
```
../rs-shared/fragments/prerequisites.md
```
获取准确的接入代码。

该插件会在每次Cypress运行后自动更新

rootspec/tests-status.json

——agent无需解析结果或调用脚本。

Step 4: Write

.rootspec.json

步骤4：写入

.rootspec.json

Create (or update)

.rootspec.json

at the project root:

json

{
  "version": "7.0.1",
  "specDirectory": "rootspec",
  "prerequisites": {
    "devServer": null,
    "preCommitHook": null,
    "releaseScript": null,
    "validationScript": null
  }
}

Fill in prerequisite values with paths or commands discovered in Step 3.

在项目根目录创建（或更新）

.rootspec.json

：

json

{
  "version": "7.0.1",
  "specDirectory": "rootspec",
  "prerequisites": {
    "devServer": null,
    "preCommitHook": null,
    "releaseScript": null,
    "validationScript": null
  }
}

用步骤3中发现的路径或命令填充前置依赖的值。

Step 5: Verify and hand off

步骤5：验证并移交

Run the verification script:

bash

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

If anything is reported missing, create it. Then report:

"Project initialized. Here's what was set up:

[list files created]
[list prerequisites configured or skipped]

Run

/rs-spec

to create your specification."

运行验证脚本：

bash

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

如果报告有缺失内容，创建对应的文件。然后报告：

"项目初始化完成。已设置的内容如下：

[已创建的文件列表]
[已配置或跳过的前置依赖列表]

运行

/rs-spec

创建你的规范。"

Focus

特殊跳转逻辑

If the developer passes an argument:

```
"resume"
```
→ skip to whatever step is incomplete
```
"prerequisites"
```
→ only run Steps 3-4 (detect/create prerequisites, update .rootspec.json)

如果开发者传入了参数：

```
"resume"
```
→直接跳转到未完成的步骤
```
"prerequisites"
```
→仅执行步骤3-4（检测/创建前置依赖，更新.rootspec.json）

Scope

权限范围

CAN read: all project files

CAN write:

rootspec/

directory (including

spec-status.json

tests-status.json

.rootspec.json

, prerequisite templates (e.g.,

scripts/dev.sh

)

SHOULD NOT write: application source code, existing test files

允许读取：所有项目文件
允许写入：
```
rootspec/
```
目录（包括
```
spec-status.json
```
、
```
tests-status.json
```
）、
```
.rootspec.json
```
、前置依赖模板（例如
```
scripts/dev.sh
```
）
禁止写入：应用源代码、已存在的测试文件

rs-init

Original

Translation

Step 1: Scan the project

步骤1：扫描项目

Step 2: Create the spec directory and base files

步骤2：创建spec目录和基础文件

Step 3: Detect or create prerequisites

步骤3：检测或创建前置依赖

Dev server template

开发服务器模板

Cypress plugin setup

Cypress插件设置

Step 4: Write
`.rootspec.json`

步骤4：写入
`.rootspec.json`

Step 5: Verify and hand off

步骤5：验证并移交

Focus

特殊跳转逻辑

Scope

权限范围

rs-init

Original

Translation

Step 1: Scan the project

步骤1：扫描项目

Step 2: Create the spec directory and base files

步骤2：创建spec目录和基础文件

Step 3: Detect or create prerequisites

步骤3：检测或创建前置依赖

Dev server template

开发服务器模板

Cypress plugin setup

Cypress插件设置

Step 4: Write .rootspec.json

步骤4：写入.rootspec.json

Step 5: Verify and hand off

步骤5：验证并移交

Focus

特殊跳转逻辑

Scope

权限范围

Step 4: Write
`.rootspec.json`

步骤4：写入
`.rootspec.json`