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 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的工具中正常读取)。
@AGENTS.mdStep 1.1 — Survey existing files
步骤1.1 — 检查现有文件
bash
cat CLAUDE.md 2>/dev/null; echo "---SEPARATOR---"; cat AGENTS.md 2>/dev/nullClassify the current state:
| CLAUDE.md | AGENTS.md | State |
|---|---|---|
| Missing or empty | Missing or empty | Fresh — no migration needed |
Contains only | Any | Already migrated — skip to Phase 2 |
| Has real content | Missing or empty | Standard — migrate CLAUDE.md → AGENTS.md |
| Has real content | Has real content | Split — needs merge (ask user) |
bash
cat CLAUDE.md 2>/dev/null; echo "---SEPARATOR---"; cat AGENTS.md 2>/dev/null对当前状态进行分类:
| CLAUDE.md | AGENTS.md | 状态 |
|---|---|---|
| 缺失或为空 | 缺失或为空 | 全新状态 — 无需迁移 |
仅包含 | 任意 | 已完成迁移 — 跳至阶段2 |
| 包含实际内容 | 缺失或为空 | 标准状态 — 将CLAUDE.md内容迁移至AGENTS.md |
| 包含实际内容 | 包含实际内容 | 内容拆分 — 需要合并(询问用户) |
Step 1.2 — Migrate
步骤1.2 — 执行迁移
Fresh state: Create both files.
undefined全新状态: 创建两个文件。
undefinedCLAUDE.md
CLAUDE.md
@AGENTS.md
undefined@AGENTS.md
undefinedAGENTS.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 uvIf uv is found, skip to Step 2.2.
If missing, install:
bash
curl -LsSf https://astral.sh/uv/install.sh | shIf 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. This usually means the swain-do skill was not fully installed. Try runningskills/swain-do/bin/tkto reinstall skills./swain update
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或其无法运行,告知用户:
未在路径下找到内置tk脚本。这通常意味着swain-do技能未完全安装。尝试运行skills/swain-do/bin/tk重新安装技能。/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 exists:
.beads/- Check for backup data:
ls .beads/backup/issues.jsonl 2>/dev/null - If backup exists, offer migration:
Found existingdata. Migrate tasks to tk? This will convert
.beads/to.beads/backup/issues.jsonlmarkdown files..tickets/ - 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 - Verify:
ls .tickets/*.md 2>/dev/null | wc -l - Tell the user the results and that can be removed after verification.
.beads/
If does not exist, skip this step. tk creates on first .
.beads/.tickets/tk create检查项目是否存在现有beads数据:
bash
test -d .beads && echo "beads found" || echo "no beads"如果存在:
.beads/- 检查备份数据:
ls .beads/backup/issues.jsonl 2>/dev/null - 如果存在备份,询问是否迁移:
发现现有数据。是否将任务迁移至tk? 这会将
.beads/转换为.beads/backup/issues.jsonl下的Markdown文件。.tickets/ - 如果用户同意,执行迁移:
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 - 验证:
ls .tickets/*.md 2>/dev/null | wc -l - 告知用户迁移结果,并说明验证完成后可删除。
.beads/
如果不存在,跳过此步骤。tk会在首次执行时创建目录。
.beads/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
.pre-commit-config.yaml步骤3.1 — 检查现有.pre-commit-config.yaml
.pre-commit-config.yamlbash
test -f .pre-commit-config.yaml && echo "exists" || echo "missing"If exists: Present the current config and ask:
Found existing. How should I proceed?.pre-commit-config.yaml
- Merge — add swain's gitleaks hook alongside your existing hooks
- Skip — leave pre-commit config unchanged
- 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
- 合并 — 在现有钩子旁添加swain的gitleaks钩子
- 跳过 — 保持预提交配置不变
- 替换 — 用swain的默认配置覆盖(现有钩子将丢失)
如果用户选择跳过,跳至阶段4。
如果不存在: 继续步骤3.2。
Step 3.2 — Check pre-commit framework
步骤3.2 — 检查pre-commit框架
bash
command -v pre-commit && pre-commit --versionIf is not found, install it:
pre-commitbash
uv tool install pre-commitIf uv is unavailable or installation fails, warn:
pre-commit framework not available. You can install it manually (oruv tool install pre-commit). Skipping hook setup.pip install pre-commit
Skip to Phase 4 if pre-commit cannot be installed.
bash
command -v pre-commit && pre-commit --version如果未找到,执行安装:
pre-commitbash
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
.pre-commit-config.yaml步骤3.3 — 创建或更新.pre-commit-config.yaml
.pre-commit-config.yamlThe default config enables gitleaks:
yaml
repos:
- repo: https://github.com/gitleaks/gitleaks
rev: v8.21.2
hooks:
- id: gitleaksIf the user requested additional scanners (via flags or when asked), add their hooks:
--scannerTruffleHog (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-scannerWrite the config file. If merging with an existing config, append the new repo entries to the existing list.
repos:默认配置启用gitleaks:
yaml
repos:
- repo: https://github.com/gitleaks/gitleaks
rev: v8.21.2
hooks:
- id: gitleaks如果用户要求添加额外扫描器(通过参数或询问时选择),添加对应的钩子:
--scannerTruffleHog(可选):
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 installbash
pre-commit installStep 3.5 — Update swain.settings.json
步骤3.5 — 更新swain.settings.json
Read the existing (if any) and add the key:
swain.settings.jsonsync.scannersjson
{
"sync": {
"scanners": {
"gitleaks": { "enabled": true },
"trufflehog": { "enabled": false },
"trivy": { "enabled": false, "scanners": ["vuln", "license"], "severity": "HIGH,CRITICAL" },
"osv-scanner": { "enabled": false }
}
}
}Set for any scanners the user opted into. Merge with existing settings — do not overwrite other keys.
enabled: trueTell the user:
Pre-commit hooks configured with gitleaks (default). Scanner settings saved to. To enable additional scanners later, editswain.settings.jsonand re-runswain.settings.json./swain-init
读取现有(如果存在)并添加键:
swain.settings.jsonsync.scannersjson
{
"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 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工作流依赖于这些技能的安装。
obra/superpowersStep 4.1 — Detect superpowers
步骤4.1 — 检测Superpowers
bash
ls .agents/skills/brainstorming/SKILL.md .claude/skills/brainstorming/SKILL.md 2>/dev/null | head -1If 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 () is not installed. It provides TDD, brainstorming, plan writing, and verification skills that swain chains into during implementation and design work.obra/superpowersInstall 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()。它提供TDD、头脑风暴、计划编写和验证技能,swain在实现与设计工作中会调用这些技能。obra/superpowers现在安装Superpowers吗?(是/否)
如果用户选择否,记录"Superpowers: 已跳过"并继续阶段5。用户后续可手动安装:。
npx skills add obra/superpowersStep 4.3 — Install
步骤4.3 — 执行安装
bash
npx skills add obra/superpowersIf 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/nullIf 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 . Locate it by searching for the file relative to the installed skills directory:
skills/swain-doctor/references/AGENTS.content.mdbash
find .claude/skills .agents/skills skills -path '*/swain-doctor/references/AGENTS.content.md' -print -quit 2>/dev/nullAppend 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 themarkers.<!-- swain governance -->
从读取标准治理内容。通过在已安装技能目录中搜索该文件来定位:
skills/swain-doctor/references/AGENTS.content.mdbash
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 .agentsThis 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 health, checks stale locks, removes legacy skill directories, and ensures governance is correctly installed.
.tickets/调用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 →
include pattern: [done/skipped/already set up]@AGENTS.md- 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 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 marker before asking.
/swain init<!-- swain governance -->To force a fresh governance block, delete the ... section from AGENTS.md and re-run.
<!-- swain governance --><!-- end swain governance -->如果用户在已配置完成的项目中运行,每个阶段会检测到工作已完成并跳过。唯一的交互阶段是治理规则注入(阶段5),它会在询问前检查标记。
/swain init<!-- swain governance -->如需强制添加新的治理规则块,删除AGENTS.md中的 ... 部分并重新运行初始化。
<!-- swain governance --><!-- end swain governance -->