setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Initialize Beat configuration in the current project.

<decision_boundary>

Use for:

Setting up Beat for the first time in a project
Updating existing Beat configuration (language, testing frameworks, rules)
Detecting project tech stack and recommending test frameworks

NOT for:

Editing
```
beat/config.yaml
```
directly (just edit the file)
Configuring non-Beat tools or project settings
Creating changes or writing feature files (use
```
/beat:design
```
)

Trigger examples:

"Set up Beat" / "Initialize Beat" / "Configure Beat for this project" / "Update Beat config"
Should NOT trigger: "edit config.yaml" / "design a feature" / "create a change"

</decision_boundary>

Input: None required. The skill gathers information interactively.

Steps

Check if config already exists
Check if
```
beat/config.yaml
```
exists.
- If yes: read it, show current config, ask if user wants to update or keep it
- If no: proceed to creation
Check superpowers dependency
Check if the superpowers plugin is available by looking for any
```
superpowers:*
```
skill in the skill list.
If not available:
"Beat works standalone, but is better with superpowers — it provides structured brainstorming, TDD discipline, task decomposition, and git worktree isolation.
Install with:
```
/plugin marketplace add obra/superpowers
```
Without it, Beat falls back to simpler built-in flows."
Use AskUserQuestion tool:
1. "Install now" -- run the install command
2. "Continue without it"
If available: proceed silently.
Ask artifact language

Use AskUserQuestion tool:

"What language should Beat use for artifacts (proposals, features, designs, tasks)?"

Provide options:
1. "English (en)" -- default
2. "繁體中文 (zh-TW)"
3. "简体中文 (zh-CN)"
4. Other -- let user specify a BCP 47 tag
This sets the
```
language
```
field in config.
Gather project context and detect tech stack

Use AskUserQuestion tool to ask:

"Describe your project so Beat can tailor its artifacts. Include: tech stack, test framework, and any key conventions."

Provide example options:
1. "Let me describe it" -- open-ended input
2. "Detect from codebase" -- agent scans package.json, Cargo.toml, go.mod, etc.
If user chooses detection:
- Scan common manifest files for tech stack and primary language
- Look for test configuration (vitest.config, jest.config, pytest.ini, etc.)
- Look for BDD runner configuration (cucumber.js, behave.ini, etc.)
- Look for e2e configuration (playwright.config, cypress.config, etc.)
- Check for linter/formatter configs
- Summarize findings and confirm with user
Record the detected/described tech stack — this informs Step 5 framework recommendations.

Configure test frameworks

Based on the tech stack from Step 4, recommend appropriate frameworks.

Step 5a: Ask project type

Use AskUserQuestion tool:

"What type of project is this?"

"Web app (has UI)" -- needs browser automation for e2e
"API server" -- needs HTTP client for e2e
"CLI tool" -- needs process execution for e2e
"Library / SDK" -- e2e usually not needed, behavior tests suffice

Step 5b: Recommend frameworks using the table below

Cross-reference (language × project type) to recommend a framework pair. Present as defaults the user can accept or customize:

"Based on your stack ({language} + {project type}), recommended test frameworks:

Behavior tests: {recommendation}

E2E tests: {recommendation}

Accept defaults or customize?"

Framework recommendation table:

Behavior test frameworks (UT / integration):

Language	Primary	Alternative
TypeScript / JavaScript	vitest	jest
Python	pytest	pytest-bdd
Go	go test	—
Java	JUnit	TestNG
C#	xUnit	NUnit
Ruby	RSpec	—
Rust	cargo test	—

E2E frameworks (BDD runner + driver, by project type):

Language	Web app (UI)	API server	CLI tool
TS / JS	cucumber-js + playwright	cucumber-js + supertest	cucumber-js + execa
Python	behave + playwright	behave + requests	behave + subprocess
Go	godog + playwright	godog + net/http	godog + os/exec
Java	Cucumber-JVM + Selenium	Cucumber-JVM + RestAssured	Cucumber-JVM + ProcessBuilder
C#	Reqnroll + Playwright	Reqnroll + HttpClient	Reqnroll + Process
Ruby	Cucumber + Capybara	Cucumber + Faraday	Cucumber + Open3

For Library projects: omit

testing.e2e

— behavior tests are sufficient. Note this in the summary.

Step 5c: Escape hatch

If the user explicitly says tests are not needed (e.g., pure docs, config-only, infra project):

Set
```
testing.required: false
```
Do NOT push back — respect the user's judgment

This sets the

testing

field in config:

yaml

testing:
  behavior: <selected framework>     # always set (unless testing.required: false)
  e2e: <selected BDD runner + driver> # set unless Library type or testing.required: false

Ask about artifact rules (optional)

Use AskUserQuestion tool:

"Want to set rules for how artifacts are generated?"
1. "Yes, let me specify" -- ask per-artifact rules
2. "Skip for now" -- create config with context only
Write config
Create
```
beat/config.yaml
```
following the schema in
```
references/config-schema.md
```
.
bash
```
mkdir -p beat
```
Write the file with the gathered context and rules.

Create directory structure (if not exists)

bash

mkdir -p beat/changes
mkdir -p beat/features

Show summary

## Beat Initialized

**Config:** beat/config.yaml
**Directories:** beat/changes/, beat/features/
**Superpowers:** installed / not installed (fallback mode)
**Testing:** {behavior framework} + {e2e framework} (or "not required")

Your config will be used when creating artifacts.
Edit beat/config.yaml anytime to update preferences.

Ready to start? Run `/beat:design` or `/beat:explore`

Guardrails

Never overwrite existing config without asking
Config is always optional -- if user wants minimal setup, just create directories
Validate config against
```
references/config-schema.md
```
before writing
Context should be concise -- warn if it exceeds 2KB (soft limit, 50KB hard limit)
Framework recommendations are suggestions -- always let the user override
Do not insist on e2e for Library projects

在当前项目中初始化Beat配置。

<decision_boundary>

适用场景：

在项目中首次设置Beat
更新现有Beat配置（语言、测试框架、规则）
检测项目技术栈并推荐测试框架

不适用场景：

直接编辑
```
beat/config.yaml
```
（直接编辑文件即可）
配置非Beat工具或项目设置
创建变更或编写特性文件（使用
```
/beat:design
```
）

触发示例：

"Set up Beat" / "Initialize Beat" / "Configure Beat for this project" / "Update Beat config"
不应触发："edit config.yaml" / "design a feature" / "create a change"

</decision_boundary>

输入：无需输入。该技能会交互式收集信息。

步骤

检查配置是否已存在
检查
```
beat/config.yaml
```
是否存在。
- 若存在：读取该文件，展示当前配置，询问用户是否要更新或保留现有配置
- 若不存在：继续创建流程
检查superpowers依赖
通过查看技能列表中是否存在任何
```
superpowers:*
```
技能，检查superpowers插件是否可用。
若不可用：
"Beat可独立运行，但搭配superpowers使用效果更佳——它提供结构化头脑风暴、TDD规范、任务分解以及git工作树隔离功能。
安装方式：
```
/plugin marketplace add obra/superpowers
```
若无该插件，Beat将退化为更简单的内置流程。"
使用AskUserQuestion工具：
1. "立即安装" —— 执行安装命令
2. "不安装，继续"
若可用： 静默继续流程。
询问工件语言

使用AskUserQuestion工具：

"Beat生成工件（提案、特性、设计、任务）时应使用哪种语言？"

提供选项：
1. "English (en)" —— 默认选项
2. "繁體中文 (zh-TW)"
3. "简体中文 (zh-CN)"
4. 其他 —— 允许用户指定BCP 47标签
此步骤将设置配置中的
```
language
```
字段。
收集项目上下文并检测技术栈

使用AskUserQuestion工具询问：

"请描述你的项目，以便Beat定制生成的工件。内容包括：技术栈、测试框架以及任何关键约定。"

提供示例选项：
1. "我来描述" —— 开放式输入
2. "从代码库检测" —— Agent扫描package.json、Cargo.toml、go.mod等文件
若用户选择检测：
- 扫描常见清单文件以获取技术栈和主要语言
- 查找测试配置文件（vitest.config、jest.config、pytest.ini等）
- 查找BDD运行器配置文件（cucumber.js、behave.ini等）
- 查找端到端（e2e）配置文件（playwright.config、cypress.config等）
- 检查代码检查器/格式化工具配置文件
- 总结检测结果并与用户确认
记录检测/描述的技术栈——这将为步骤5的框架推荐提供依据。

配置测试框架

基于步骤4获取的技术栈，推荐合适的框架。

步骤5a：询问项目类型

使用AskUserQuestion工具：

"这是什么类型的项目？"

"Web应用（含UI）" —— 需要浏览器自动化进行端到端测试
"API服务器" —— 需要HTTP客户端进行端到端测试
"CLI工具" —— 需要进程执行进行端到端测试
"库/SDK" —— 通常不需要端到端测试，行为测试即可满足需求

步骤5b：使用下表推荐框架

交叉参考（语言 × 项目类型）以推荐框架组合。向用户展示默认选项，用户可接受或自定义：

"基于你的技术栈（{language} + {project type}），推荐的测试框架：

行为测试： {recommendation}

端到端测试： {recommendation}

是否接受默认选项或自定义？"

框架推荐表：

行为测试框架（单元测试/集成测试）：

语言	首选	备选
TypeScript / JavaScript	vitest	jest
Python	pytest	pytest-bdd
Go	go test	—
Java	JUnit	TestNG
C#	xUnit	NUnit
Ruby	RSpec	—
Rust	cargo test	—

端到端测试框架（BDD运行器 + 驱动，按项目类型分类）：

语言	Web应用（UI）	API服务器	CLI工具
TS / JS	cucumber-js + playwright	cucumber-js + supertest	cucumber-js + execa
Python	behave + playwright	behave + requests	behave + subprocess
Go	godog + playwright	godog + net/http	godog + os/exec
Java	Cucumber-JVM + Selenium	Cucumber-JVM + RestAssured	Cucumber-JVM + ProcessBuilder
C#	Reqnroll + Playwright	Reqnroll + HttpClient	Reqnroll + Process
Ruby	Cucumber + Capybara	Cucumber + Faraday	Cucumber + Open3

对于库类型项目：省略

testing.e2e

——行为测试已足够。在总结中注明这一点。

步骤5c：特殊处理

若用户明确表示不需要测试（例如纯文档、仅配置、基础设施项目）：

设置
```
testing.required: false
```
不要反驳——尊重用户的判断

此步骤将设置配置中的

testing

字段：

yaml

testing:
  behavior: <selected framework>     # 始终设置（除非testing.required: false）
  e2e: <selected BDD runner + driver> # 设置，除非是库类型项目或testing.required: false

询问工件规则（可选）

使用AskUserQuestion工具：

"是否要设置工件生成规则？"
1. "是，我来指定" —— 询问每个工件的规则
2. "暂时跳过" —— 仅使用上下文创建配置
写入配置
按照
```
references/config-schema.md
```
中的架构创建
```
beat/config.yaml
```
。
bash
```
mkdir -p beat
```
写入包含收集到的上下文和规则的文件。

创建目录结构（若不存在）

bash

mkdir -p beat/changes
mkdir -p beat/features

展示总结

## Beat已初始化

**配置文件：** beat/config.yaml
**目录：** beat/changes/, beat/features/
**Superpowers：** 已安装 / 未安装（回退模式）
**测试配置：** {behavior framework} + {e2e framework}（或"不需要"）

你的配置将用于生成工件。
随时编辑beat/config.yaml以更新偏好设置。

准备开始了吗？运行`/beat:design`或`/beat:explore`

约束规则

未经询问，绝不能覆盖现有配置
配置始终是可选的——若用户希望最小化设置，仅创建目录即可
写入前需根据
```
references/config-schema.md
```
验证配置
上下文应简洁——若超过2KB（软限制，硬限制为50KB）则发出警告
框架推荐仅为建议——始终允许用户覆盖
不要坚持为库类型项目配置端到端测试