swain-init

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<!-- swain-model-hint: sonnet, effort: medium -->
<!-- swain-model-hint: sonnet, effort: medium -->

Project Onboarding

项目初始化引导

One-time setup for adopting swain in a project. This skill is not idempotent — it migrates files and installs tools. For per-session health checks, use swain-doctor.
Run all phases in order. If a phase detects its work is already done, skip it and move to the next.
在项目中采用swain的一次性设置流程。该技能不具备幂等性——它会迁移文件并安装工具。会话级健康检查请使用swain-doctor。
按顺序运行所有阶段。如果某阶段检测到工作已完成,则跳过该阶段进入下一阶段。

Phase 1: CLAUDE.md → AGENTS.md migration

阶段1:CLAUDE.md → AGENTS.md 迁移

Goal: establish the
@AGENTS.md
include pattern so project instructions live in AGENTS.md (which works across Claude Code, GitHub, and other tools that read AGENTS.md natively).
目标:建立
@AGENTS.md
引入模式,使项目说明文档存储在AGENTS.md中(该文件可在Claude Code、GitHub及其他原生支持AGENTS.md的工具中正常读取)。

Step 1.1 — Survey existing files

步骤1.1 — 检查现有文件

bash
cat CLAUDE.md 2>/dev/null; echo "---SEPARATOR---"; cat AGENTS.md 2>/dev/null
Classify the current state:
CLAUDE.mdAGENTS.mdState
Missing or emptyMissing or emptyFresh — no migration needed
Contains only
@AGENTS.md
AnyAlready migrated — skip to Phase 2
Has real contentMissing or emptyStandard — migrate CLAUDE.md → AGENTS.md
Has real contentHas real contentSplit — needs merge (ask user)
bash
cat CLAUDE.md 2>/dev/null; echo "---SEPARATOR---"; cat AGENTS.md 2>/dev/null
对当前状态进行分类:
CLAUDE.mdAGENTS.md状态
缺失或为空缺失或为空全新状态 — 无需迁移
仅包含
@AGENTS.md
任意已完成迁移 — 跳至阶段2
包含实际内容缺失或为空标准状态 — 将CLAUDE.md内容迁移至AGENTS.md
包含实际内容包含实际内容内容拆分 — 需要合并(询问用户)

Step 1.2 — Migrate

步骤1.2 — 执行迁移

Fresh state: Create both files.
undefined
全新状态: 创建两个文件。
undefined

CLAUDE.md

CLAUDE.md

@AGENTS.md
undefined
@AGENTS.md
undefined

AGENTS.md

AGENTS.md

(empty — governance will be added in Phase 3)

**Already migrated:** Skip to Phase 2.

**Standard state:**

1. Copy CLAUDE.md content to AGENTS.md (preserve everything).
2. If CLAUDE.md contains a `<!-- swain governance -->` block, strip it from the AGENTS.md copy — it will be re-added cleanly in Phase 3.
3. Replace CLAUDE.md with:
@AGENTS.md

Tell the user:
> Migrated your CLAUDE.md content to AGENTS.md and replaced CLAUDE.md with `@AGENTS.md`. Your existing instructions are preserved — Claude Code reads AGENTS.md via the include directive.

**Split state:** Both files have content. Ask the user:

> Both CLAUDE.md and AGENTS.md have content. How should I proceed?
> 1. **Merge** — append CLAUDE.md content to the end of AGENTS.md, then replace CLAUDE.md with `@AGENTS.md`
> 2. **Keep AGENTS.md** — discard CLAUDE.md content, replace CLAUDE.md with `@AGENTS.md`
> 3. **Abort** — leave both files as-is, skip migration

If merge: append CLAUDE.md content (minus any `<!-- swain governance -->` block) to AGENTS.md, replace CLAUDE.md with `@AGENTS.md`.
(空文件 — 治理规则将在阶段3添加)

**已完成迁移:** 跳至阶段2。

**标准状态:**

1. 将CLAUDE.md内容复制到AGENTS.md(保留所有内容)。
2. 如果CLAUDE.md包含`<!-- swain governance -->`代码块,请在AGENTS.md的副本中移除该块——它将在阶段3中被干净地重新添加。
3. 将CLAUDE.md替换为:
@AGENTS.md

告知用户:
> 已将您的CLAUDE.md内容迁移至AGENTS.md,并将CLAUDE.md替换为`@AGENTS.md`。您的现有说明已被保留——Claude Code会通过引入指令读取AGENTS.md。

**内容拆分状态:** 两个文件均包含内容。询问用户:

> CLAUDE.md和AGENTS.md均包含内容。我应如何处理?
> 1. **合并** — 将CLAUDE.md内容追加至AGENTS.md末尾,然后将CLAUDE.md替换为`@AGENTS.md`
> 2. **保留AGENTS.md** — 丢弃CLAUDE.md内容,将CLAUDE.md替换为`@AGENTS.md`
> 3. **终止** — 保留两个文件原样,跳过迁移

如果选择合并:将CLAUDE.md内容(移除任何`<!-- swain governance -->`块后)追加至AGENTS.md,然后将CLAUDE.md替换为`@AGENTS.md`。

Phase 2: Verify dependencies

阶段2:验证依赖

Goal: ensure uv is available and the vendored tk script is accessible.
目标:确保uv可用且内置tk脚本可正常访问。

Step 2.1 — Check uv availability

步骤2.1 — 检查uv可用性

bash
command -v uv
If uv is found, skip to Step 2.2.
If missing, install:
bash
curl -LsSf https://astral.sh/uv/install.sh | sh
If installation fails, tell the user:
uv installation failed. You can install it manually (https://docs.astral.sh/uv/getting-started/installation/) — swain scripts require uv for Python execution.
Then skip the rest of Phase 2 (don't block init on uv, but warn that scripts will not function without it).
bash
command -v uv
如果找到uv,跳至步骤2.2。
如果未找到,执行安装:
bash
curl -LsSf https://astral.sh/uv/install.sh | sh
如果安装失败,告知用户:
然后跳过阶段2的剩余部分(不阻塞初始化,但警告用户无uv时脚本无法运行)。

Step 2.2 — Verify vendored tk

步骤2.2 — 验证内置tk

tk (ticket) is vendored in the swain skill tree — no external installation is needed.
bash
TK_PATH="$(find . .claude .agents -path '*/swain-do/bin/tk' -print -quit 2>/dev/null)"
test -x "$TK_PATH" && echo "tk found at $TK_PATH" || echo "tk not found"
If found, verify it runs:
bash
"$TK_PATH" help >/dev/null 2>&1 && echo "tk works" || echo "tk broken"
If tk is not found or broken, tell the user:
The vendored tk script was not found at
skills/swain-do/bin/tk
. This usually means the swain-do skill was not fully installed. Try running
/swain update
to reinstall skills.
tk(ticket)是swain技能树中的内置工具——无需外部安装。
bash
TK_PATH="$(find . .claude .agents -path '*/swain-do/bin/tk' -print -quit 2>/dev/null)"
test -x "$TK_PATH" && echo "tk found at $TK_PATH" || echo "tk not found"
如果找到,验证其可运行:
bash
"$TK_PATH" help >/dev/null 2>&1 && echo "tk works" || echo "tk broken"
如果未找到tk或其无法运行,告知用户:
未在
skills/swain-do/bin/tk
路径下找到内置tk脚本。这通常意味着swain-do技能未完全安装。尝试运行
/swain update
重新安装技能。

Step 2.3 — Migrate from beads (if applicable)

步骤2.3 — 从beads迁移(如适用)

Check if this project has existing beads data:
bash
test -d .beads && echo "beads found" || echo "no beads"
If
.beads/
exists:
  1. Check for backup data:
    ls .beads/backup/issues.jsonl 2>/dev/null
  2. If backup exists, offer migration:
    Found existing
    .beads/
    data. Migrate tasks to tk? This will convert
    .beads/backup/issues.jsonl
    to
    .tickets/
    markdown files.
  3. If user agrees, run migration:
    bash
    TK_BIN="$(cd "$(dirname "$TK_PATH")" && pwd)"
    export PATH="$TK_BIN:$PATH"
    cp .beads/backup/issues.jsonl .beads/issues.jsonl 2>/dev/null  # migrate-beads expects this location
    ticket-migrate-beads
  4. Verify:
    ls .tickets/*.md 2>/dev/null | wc -l
  5. Tell the user the results and that
    .beads/
    can be removed after verification.
If
.beads/
does not exist, skip this step. tk creates
.tickets/
on first
tk create
.
检查项目是否存在现有beads数据:
bash
test -d .beads && echo "beads found" || echo "no beads"
如果
.beads/
存在:
  1. 检查备份数据:
    ls .beads/backup/issues.jsonl 2>/dev/null
  2. 如果存在备份,询问是否迁移:
    发现现有
    .beads/
    数据。是否将任务迁移至tk? 这会将
    .beads/backup/issues.jsonl
    转换为
    .tickets/
    下的Markdown文件。
  3. 如果用户同意,执行迁移:
    bash
    TK_BIN="$(cd "$(dirname "$TK_PATH")" && pwd)"
    export PATH="$TK_BIN:$PATH"
    cp .beads/backup/issues.jsonl .beads/issues.jsonl 2>/dev/null  # migrate-beads期望该路径
    ticket-migrate-beads
  4. 验证:
    ls .tickets/*.md 2>/dev/null | wc -l
  5. 告知用户迁移结果,并说明验证完成后可删除
    .beads/
如果
.beads/
不存在,跳过此步骤。tk会在首次执行
tk create
时创建
.tickets/
目录。

Phase 3: Pre-commit security hooks

阶段3:预提交安全钩子

Goal: configure pre-commit hooks for secret scanning so credentials are caught before they enter git history. Default scanner is gitleaks; additional scanners (TruffleHog, Trivy, OSV-Scanner) are opt-in.
目标:配置用于密钥扫描的预提交钩子,确保凭据在进入git历史前被捕获。默认扫描器为gitleaks;额外扫描器(TruffleHog、Trivy、OSV-Scanner)为可选启用。

Step 3.1 — Check for existing
.pre-commit-config.yaml

步骤3.1 — 检查现有
.pre-commit-config.yaml

bash
test -f .pre-commit-config.yaml && echo "exists" || echo "missing"
If exists: Present the current config and ask:
Found existing
.pre-commit-config.yaml
. How should I proceed?
  1. Merge — add swain's gitleaks hook alongside your existing hooks
  2. Skip — leave pre-commit config unchanged
  3. Replace — overwrite with swain's default config (your existing hooks will be lost)
If user chooses Skip, skip to Phase 4.
If missing: Proceed to Step 3.2.
bash
test -f .pre-commit-config.yaml && echo "exists" || echo "missing"
如果已存在: 展示当前配置并询问用户:
发现现有
.pre-commit-config.yaml
。我应如何处理?
  1. 合并 — 在现有钩子旁添加swain的gitleaks钩子
  2. 跳过 — 保持预提交配置不变
  3. 替换 — 用swain的默认配置覆盖(现有钩子将丢失)
如果用户选择跳过,跳至阶段4。
如果不存在: 继续步骤3.2。

Step 3.2 — Check pre-commit framework

步骤3.2 — 检查pre-commit框架

bash
command -v pre-commit && pre-commit --version
If
pre-commit
is not found, install it:
bash
uv tool install pre-commit
If uv is unavailable or installation fails, warn:
pre-commit framework not available. You can install it manually (
uv tool install pre-commit
or
pip install pre-commit
). Skipping hook setup.
Skip to Phase 4 if pre-commit cannot be installed.
bash
command -v pre-commit && pre-commit --version
如果未找到
pre-commit
,执行安装:
bash
uv tool install pre-commit
如果uv不可用或安装失败,警告:
未找到pre-commit框架。您可以手动安装(
uv tool install pre-commit
pip install pre-commit
)。跳过钩子设置。
如果无法安装pre-commit,跳至阶段4。

Step 3.3 — Create or update
.pre-commit-config.yaml

步骤3.3 — 创建或更新
.pre-commit-config.yaml

The default config enables gitleaks:
yaml
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.21.2
    hooks:
      - id: gitleaks
If the user requested additional scanners (via
--scanner
flags or when asked), add their hooks:
TruffleHog (opt-in):
yaml
  - repo: https://github.com/trufflesecurity/trufflehog
    rev: v3.88.1
    hooks:
      - id: trufflehog
        args: ['--results=verified,unknown']
Trivy (opt-in):
yaml
  - repo: https://github.com/cebidhem/pre-commit-trivy
    rev: v1.0.0
    hooks:
      - id: trivy-fs
        args: ['--severity', 'HIGH,CRITICAL', '--scanners', 'vuln,license']
OSV-Scanner (opt-in):
yaml
  - repo: https://github.com/nicjohnson145/pre-commit-osv-scanner
    rev: v0.0.1
    hooks:
      - id: osv-scanner
Write the config file. If merging with an existing config, append the new repo entries to the existing
repos:
list.
默认配置启用gitleaks:
yaml
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.21.2
    hooks:
      - id: gitleaks
如果用户要求添加额外扫描器(通过
--scanner
参数或询问时选择),添加对应的钩子:
TruffleHog(可选):
yaml
  - repo: https://github.com/trufflesecurity/trufflehog
    rev: v3.88.1
    hooks:
      - id: trufflehog
        args: ['--results=verified,unknown']
Trivy(可选):
yaml
  - repo: https://github.com/cebidhem/pre-commit-trivy
    rev: v1.0.0
    hooks:
      - id: trivy-fs
        args: ['--severity', 'HIGH,CRITICAL', '--scanners', 'vuln,license']
OSV-Scanner(可选):
yaml
  - repo: https://github.com/nicjohnson145/pre-commit-osv-scanner
    rev: v0.0.1
    hooks:
      - id: osv-scanner
写入配置文件。如果是与现有配置合并,将新的仓库条目追加至现有
repos:
列表中。

Step 3.4 — Install hooks

步骤3.4 — 安装钩子

bash
pre-commit install
bash
pre-commit install

Step 3.5 — Update swain.settings.json

步骤3.5 — 更新swain.settings.json

Read the existing
swain.settings.json
(if any) and add the
sync.scanners
key:
json
{
  "sync": {
    "scanners": {
      "gitleaks": { "enabled": true },
      "trufflehog": { "enabled": false },
      "trivy": { "enabled": false, "scanners": ["vuln", "license"], "severity": "HIGH,CRITICAL" },
      "osv-scanner": { "enabled": false }
    }
  }
}
Set
enabled: true
for any scanners the user opted into. Merge with existing settings — do not overwrite other keys.
Tell the user:
Pre-commit hooks configured with gitleaks (default). Scanner settings saved to
swain.settings.json
. To enable additional scanners later, edit
swain.settings.json
and re-run
/swain-init
.
读取现有
swain.settings.json
(如果存在)并添加
sync.scanners
键:
json
{
  "sync": {
    "scanners": {
      "gitleaks": { "enabled": true },
      "trufflehog": { "enabled": false },
      "trivy": { "enabled": false, "scanners": ["vuln", "license"], "severity": "HIGH,CRITICAL" },
      "osv-scanner": { "enabled": false }
    }
  }
}
对用户选择启用的扫描器设置
enabled: true
。与现有设置合并——不要覆盖其他键。
告知用户:
已配置预提交钩子,默认使用gitleaks。扫描器设置已保存至
swain.settings.json
。后续如需启用额外扫描器,编辑
swain.settings.json
并重新运行
/swain-init

Phase 4: Superpowers companion

阶段4:Superpowers配套技能

Goal: offer to install
obra/superpowers
if it is not already present. Superpowers provides TDD enforcement, brainstorming, plan writing, and verification skills that swain chains into — the full AGENTS.md workflow depends on them being installed.
目标:如果
obra/superpowers
未安装,提供安装选项。Superpowers提供TDD强制执行、头脑风暴、计划编写和验证技能,swain会调用这些技能——完整的AGENTS.md工作流依赖于这些技能的安装。

Step 4.1 — Detect superpowers

步骤4.1 — 检测Superpowers

bash
ls .agents/skills/brainstorming/SKILL.md .claude/skills/brainstorming/SKILL.md 2>/dev/null | head -1
If any result is returned, superpowers is already installed. Report "Superpowers: already installed" and skip to Phase 5.
bash
ls .agents/skills/brainstorming/SKILL.md .claude/skills/brainstorming/SKILL.md 2>/dev/null | head -1
如果返回结果,说明Superpowers已安装。提示"Superpowers: 已安装"并跳至阶段5。

Step 4.2 — Offer installation

步骤4.2 — 提供安装选项

Ask the user:
Superpowers (
obra/superpowers
) is not installed. It provides TDD, brainstorming, plan writing, and verification skills that swain chains into during implementation and design work.
Install superpowers now? (yes/no)
If the user says no, note "Superpowers: skipped" and continue to Phase 5. They can always install later:
npx skills add obra/superpowers
.
询问用户:
未安装Superpowers(
obra/superpowers
)。它提供TDD、头脑风暴、计划编写和验证技能,swain在实现与设计工作中会调用这些技能。
现在安装Superpowers吗?(是/否)
如果用户选择,记录"Superpowers: 已跳过"并继续阶段5。用户后续可手动安装:
npx skills add obra/superpowers

Step 4.3 — Install

步骤4.3 — 执行安装

bash
npx skills add obra/superpowers
If the install succeeds, tell the user:
Superpowers installed. Brainstorming, TDD, plan writing, and verification skills are now available.
If it fails, warn:
Superpowers installation failed. You can retry manually:
npx skills add obra/superpowers
Continue to Phase 5 regardless.
bash
npx skills add obra/superpowers
如果安装成功,告知用户:
Superpowers已安装。现在可使用头脑风暴、TDD、计划编写和验证技能。
如果安装失败,警告:
Superpowers安装失败。您可手动重试:
npx skills add obra/superpowers
无论结果如何,继续阶段5。

Phase 5: Swain governance

阶段5:Swain治理规则

Goal: add swain's routing and governance rules to AGENTS.md.
目标:将swain的路由与治理规则添加至AGENTS.md。

Step 5.1 — Check for existing governance

步骤5.1 — 检查现有治理规则

bash
grep -l "swain governance" AGENTS.md CLAUDE.md 2>/dev/null
If found in either file, governance is already installed. Tell the user and skip to Phase 6.
bash
grep -l "swain governance" AGENTS.md CLAUDE.md 2>/dev/null
如果在任一文件中找到,说明治理规则已安装。告知用户并跳至阶段6。

Step 5.2 — Ask permission

步骤5.2 — 请求许可

Ask the user:
Ready to add swain governance rules to AGENTS.md. These rules:
  • Route artifact requests (specs, stories, ADRs, etc.) to swain-design
  • Route task tracking to swain-do (using tk)
  • Enforce the pre-implementation protocol (plan before code)
  • Prefer swain skills over built-in alternatives
Add governance rules to AGENTS.md? (yes/no)
If no, skip to Phase 6.
询问用户:
准备将swain治理规则添加至AGENTS.md。这些规则:
  • 将工件请求(规格、用户故事、ADR等)路由至swain-design
  • 将任务追踪路由至swain-do(使用tk)
  • 强制执行预实现协议(编码前先制定计划)
  • 优先使用swain技能而非内置替代方案
是否将治理规则添加至AGENTS.md?(是/否)
如果用户选择否,跳至阶段6。

Step 5.3 — Inject governance

步骤5.3 — 注入治理规则

Read the canonical governance content from
skills/swain-doctor/references/AGENTS.content.md
. Locate it by searching for the file relative to the installed skills directory:
bash
find .claude/skills .agents/skills skills -path '*/swain-doctor/references/AGENTS.content.md' -print -quit 2>/dev/null
Append the full contents of that file to AGENTS.md.
Tell the user:
Governance rules added to AGENTS.md. These ensure swain skills are routable and conventions are enforced. You can customize anything outside the
<!-- swain governance -->
markers.
skills/swain-doctor/references/AGENTS.content.md
读取标准治理内容。通过在已安装技能目录中搜索该文件来定位:
bash
find .claude/skills .agents/skills skills -path '*/swain-doctor/references/AGENTS.content.md' -print -quit 2>/dev/null
将该文件的全部内容追加至AGENTS.md。
告知用户:
治理规则已添加至AGENTS.md。这些规则确保swain技能可被正确路由,并强制执行约定。您可在
<!-- swain governance -->
标记外自定义任何内容。

Phase 6: Finalize

阶段6:最终完成

Step 6.1 — Create .agents directory

步骤6.1 — 创建.agents目录

bash
mkdir -p .agents
This directory is used by swain-do for configuration and by swain-design scripts for logs.
bash
mkdir -p .agents
该目录供swain-do存储配置,以及swain-design脚本存储日志。

Step 6.2 — Run swain-doctor

步骤6.2 — 运行swain-doctor

Invoke the swain-doctor skill. This validates
.tickets/
health, checks stale locks, removes legacy skill directories, and ensures governance is correctly installed.
调用swain-doctor技能。它会验证
.tickets/
的健康状态、检查过期锁、移除旧版技能目录,并确保治理规则已正确安装。

Step 6.3 — Onboarding

步骤6.3 — 引导说明

Invoke the swain-help skill in onboarding mode to give the user a guided orientation of what they just installed.
以引导模式调用swain-help技能,为用户提供刚安装内容的定向介绍。

Step 6.4 — Summary

步骤6.4 — 总结

Report what was done:
swain init complete.
  • CLAUDE.md →
    @AGENTS.md
    include pattern: [done/skipped/already set up]
  • tk (ticket) verified: [done/not found]
  • Beads migration: [done/skipped/no beads found]
  • Pre-commit security hooks: [done/skipped/already configured]
  • Superpowers: [installed/skipped/already present]
  • Swain governance in AGENTS.md: [done/skipped/already present]
报告已完成的操作:
swain初始化完成。
  • CLAUDE.md →
    @AGENTS.md
    引入模式:[已完成/已跳过/已配置]
  • tk(ticket)验证:[已完成/未找到]
  • Beads迁移:[已完成/已跳过/未找到beads]
  • 预提交安全钩子:[已完成/已跳过/已配置]
  • Superpowers:[已安装/已跳过/已存在]
  • AGENTS.md中的swain治理规则:[已完成/已跳过/已存在]

Re-running init

重新运行初始化

If the user runs
/swain init
on a project that's already set up, each phase will detect its work is done and skip. The only interactive phase is governance injection (Phase 5), which checks for the
<!-- swain governance -->
marker before asking.
To force a fresh governance block, delete the
<!-- swain governance -->
...
<!-- end swain governance -->
section from AGENTS.md and re-run.
如果用户在已配置完成的项目中运行
/swain init
,每个阶段会检测到工作已完成并跳过。唯一的交互阶段是治理规则注入(阶段5),它会在询问前检查
<!-- swain governance -->
标记。
如需强制添加新的治理规则块,删除AGENTS.md中的
<!-- swain governance -->
...
<!-- end swain governance -->
部分并重新运行初始化。